pintjuk/go-regex-wasm

A demo project showcasing how to use Go-based regex functionality in JavaScript via WebAssembly, with a clean API and JSDoc-typed JavaScript library for seamless browser integration.

@pintjuk/golang-regex

@pintjuk/golang-regex is a JavaScript package that enables regex matching using Go's regex engine via WebAssembly. It supports the full Go regex syntax, providing powerful and efficient matching capabilities directly in JavaScript environments.

Features

• Full compatibility with Go's regex syntax.
• Efficient WebAssembly-based implementation.
• Simple integration with modern JavaScript/TypeScript projects.
• Supports lazy loading for optimized performance.

---

Demo

For a complete demonstration of how to use this package, check out the live demo repository:

👉 Demo Repo

👉 Demo Site

---

Installation

Install the package via npm:

npm install @pintjuk/golang-regex

---

Webpack Configuration for .wasm Files

To use @pintjuk/golang-regex in a Webpack-based project, configure Webpack to handle .wasm files and enable WebAssembly support.

Example Webpack Configuration

const path = require('path');

module.exports = {
  entry: './src/main.js', // Your JavaScript entry point
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  mode: 'production',
  module: {
    rules: [
      {
        test: /\.wasm$/, // Handles `.wasm` files
        type: 'asset/resource', // Emits `.wasm` files as separate assets
      },
    ],
  },
  experiments: {
    asyncWebAssembly: true, // Enable asynchronous WebAssembly loading
  },
};

Key Configuration Points:

1. type: 'asset/resource' for .wasm Files:
   • Ensures .wasm files are correctly emitted to the output directory.
2. Enable asyncWebAssembly:
   • Allows WebAssembly files to be loaded asynchronously.

---

Usage

Basic Usage

Here’s how to use the package in a typical JavaScript application:

import GolangRegex from '@pintjuk/golang-regex';
import wasmPath from '@pintjuk/golang-regex/goregex.wasm';

(async () => {
  await GolangRegex.initialize(wasmPath);

  const pattern = '^hello';
  const text = 'hello world';

  const isMatch = GolangRegex.match(pattern, text);
  console.log(isMatch ? 'Match found!' : 'No match found.');
})();

---

Lazy Loading for Optimization

Since @pintjuk/golang-regex uses WebAssembly, it is recommended to lazy load the package to avoid blocking page load. Lazy loading ensures the WebAssembly module is initialized only when required.

Example: Lazy Loading

document.getElementById('regexButton').addEventListener('click', async () => {
  const GolangRegex = await import('@pintjuk/golang-regex');
  const wasmPath = await import('@pintjuk/golang-regex/goregex.wasm');

  await GolangRegex.initialize(wasmPath);

  const pattern = '^hello';
  const text = 'hello world';

  const isMatch = GolangRegex.match(pattern, text);
  console.log(isMatch ? 'Match found!' : 'No match found.');
});

Why Lazy Loading?

1. Improved Performance: Loads the WebAssembly module only when needed, reducing initial load time.
2. Non-blocking: Keeps the main thread free during the initial page load.
3. Scalability: Ideal for applications where regex functionality is used conditionally or infrequently.

---

Why WebAssembly is Loaded Asynchronously

WebAssembly modules, such as goregex.wasm, must be downloaded and compiled by the browser. Loading these modules asynchronously provides several benefits:

1. Non-blocking Execution: Prevents UI freezing during WebAssembly loading and compilation.
2. Streaming Compilation: The WebAssembly.instantiateStreaming method allows browsers to compile the WebAssembly module while it's still downloading, improving performance.
3. Optimized Resource Loading: Ensures that the WebAssembly module is only downloaded when needed.

---

License

This project is licensed under the MIT License.