@stll/regex-set

@stll/regex-set

NAPI-RS bindings to Rust's regex-automata crate for Node.js and Bun.

Multi-pattern regex matching in a single pass. Backtracking-free on the main DFA path, with a targeted fallback for some lookaround cases. Built on the same regex engine that powers ripgrep.

Install

npm install @stll/regex-set
# or
bun add @stll/regex-set

The companion @stll/regex-set-wasm package is available for browser builds.

You do not need Vite to use @stll/regex-set in Node.js or Bun. Vite is only relevant for the browser/WASM companion package.

Prebuilts are available for:

Platform	Architecture
macOS	x64, arm64
Linux (glibc)	x64, arm64
WASM	browser

Usage

import { RegexSet } from "@stll/regex-set";

const rs = new RegexSet([
  "\\d{2}\\.\\d{2}\\.\\d{4}", // dates
  "\\+?\\d{9,12}", // phones
  "[A-Z]{2}\\d{6}", // IDs
  "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+", // emails
]);

rs.findIter("Born 15.03.1990, ID CZ123456");
// [
//   { pattern: 0, start: 5, end: 15,
//     text: "15.03.1990" },
//   { pattern: 2, start: 20, end: 28,
//     text: "CZ123456" },
// ]

// Quick check
rs.isMatch("call [phone]"); // true

// Which patterns matched (not where)
rs.whichMatch("call [phone]"); // [1]

// Replace all matches
rs.replaceAll("Born 15.03.1990, phone [phone]", [
  "[DATE]",
  "[PHONE]",
  "[ID]",
  "[EMAIL]",
]);
// "Born [DATE], phone [PHONE]"

Named patterns

const rs = new RegexSet([
  { pattern: /\d{2}\.\d{2}\.\d{4}/, name: "date" },
  { pattern: /\+?\d{9,12}/, name: "phone" },
  "[A-Z]{2}\\d{6}", // unnamed
]);

rs.findIter("Born 15.03.1990, ID CZ123456");
// [
//   { pattern: 0, ..., name: "date" },
//   { pattern: 2, ..., text: "CZ123456" },
//   ← no `name` property on unnamed patterns
// ]

Options

const rs = new RegexSet(patterns, {
  // Only match whole words (default: false)
  wholeWords: true,

  // Unicode word boundaries (default: true)
  // Treats accented letters, CJK, etc. as word
  // characters. Auto UAX#29 for Thai/CJK.
  // Set to false for JS RegExp ASCII parity.
  unicodeBoundaries: true,
});

Unicode word boundaries

By default, \b uses Unicode semantics — correct for all scripts. Set unicodeBoundaries: false for JS RegExp ASCII parity:

// Default (Unicode \b): "čáp" is one word (CORRECT)
new RegexSet(["\\bp\\b"]).findIter("čáp");
// → [] (no match — p is inside a word)

// ASCII \b: "p" matches as standalone (WRONG)
new RegexSet(["\\bp\\b"], {
  unicodeBoundaries: false,
}).findIter("čáp");
// → [{ text: "p" }]

// Unicode \b: "čáp" is one word (CORRECT)
new RegexSet(["\\bp\\b"], {
  unicodeBoundaries: true,
}).findIter("čáp");
// → [] (no match — p is inside a word)

new RegexSet(["\\bčáp\\b"], {
  unicodeBoundaries: true,
}).findIter("malý čáp letí");
// → [{ text: "čáp" }]

Implementation: edge \b is stripped from patterns and verified inline per match (two char lookups). The DFA never sees \b, so boundary verification stays O(1) per match in either mode.

Lookaround

Lookahead and lookbehind are supported:

const rs = new RegexSet([
  "(?<!\\p{L})IČO:\\s*[0-9]{8}", // lookbehind
  "[0-9]{6}/[0-9]{3,4}(?![0-9])", // lookahead
]);

Internally, lookaround is stripped from patterns, the cores are compiled into a single fast DFA, and assertions are verified as inline char checks on each match. No backtracking engine is involved for simple assertions.

When a greedy quantifier (e.g., \s*) causes the DFA to overshoot past a valid match boundary and the lookahead rejects the longer match, the engine falls back to fancy-regex for that specific match to backtrack the quantifier and find the shorter valid match. This fallback is slower on affected matches but preserves correctness; patterns without lookaround are unaffected.

Benchmarks

The repository includes only public, reproducible benchmark inputs and scripts in __bench__/.

Inputs:

• mariomka/regex-benchmark
• rust-leipzig/regex-performance
• Canterbury Large Corpus

Run them locally:

bun install
bun run build
bun run bench:download
bun run bench
bun run bench:fallback

Representative baseline from the checked-in public harness:

• runtime: Bun 1.3.10
• platform: macOS 26.4.1 (Darwin arm64)

Scenario	@stll/regex-set	JS RegExp	Relative
mariomka, 3 patterns, 6.2 MB	19.08 ms	102.67 ms	5.4x faster
Twain literal Twain, 16.0 MB	9.47 ms	1.21 ms	0.13x
Twain char class [a-z]shing, 16.0 MB	10.38 ms	8.01 ms	0.77x
Twain word boundary \\b\\w+nn\\b, 16.0 MB	13.00 ms	55.59 ms	4.3x faster
Twain alternation Tom|Sawyer|..., 16.0 MB	9.20 ms	20.77 ms	2.3x faster
Twain suffix [a-zA-Z]+ing, 16.0 MB	15.79 ms	91.93 ms	5.8x faster
Bible, 5 patterns, 4.0 MB	12.20 ms	57.52 ms	4.7x faster
Bible, 3 lookaround patterns, 4.0 MB	25.93 ms	77.33 ms	3.0x faster

Fallback-path microbenchmark in the same environment:

Scenario	Time
baseline DFA, no lookaround	0.168 ms
verifier present, no fallback	0.134 ms
verifier + fancy-regex fallback	0.829 ms

The benchmark harness covers:

• multi-pattern scanning on public corpora
• lookaround-heavy scans
• catastrophic backtracking resistance
• the verifier + fancy-regex fallback path

Alternatives tested

• node-re2 — Google RE2 via C++, single pattern per call
• JS RegExp — V8 built-in, per-pattern loop

API

Method	Returns	Description
new RegexSet(patterns, options?)	instance	Compile patterns
.findIter(haystack)	Match[]	All non-overlapping matches
.isMatch(haystack)	boolean	Any pattern matches?
.whichMatch(haystack)	number[]	Which pattern indices matched
.replaceAll(haystack, replacements)	string	Replace matches
.patternCount	number	Number of patterns

Types

type PatternEntry =
  | string
  | RegExp
  | { pattern: string | RegExp; name?: string };

type Options = {
  wholeWords?: boolean;
  unicodeBoundaries?: boolean;
};

type Match = {
  pattern: number; // which regex matched
  start: number; // UTF-16 code unit offset
  end: number; // exclusive
  text: string; // matched substring
  name?: string; // pattern name (if provided)
};

Same Match type as @stll/aho-corasick: composable results, same UTF-16 offsets compatible with String.prototype.slice().

Regex syntax

Uses Rust regex syntax. Similar to PCRE but:

• No backreferences (by design: enables O(n))
• Lookahead/lookbehind supported (via inline char checks, no backtracking)
• Unicode support by default (\d matches Unicode digits, \w matches Unicode word chars)

Full syntax: docs.rs/regex

Limitations

• No backreferences. By design: enables the O(n) guarantee. Use JS RegExp for patterns that need backreferences.
• Single literal patterns are slower than JS. V8 uses SIMD memchr for single literals. Use @stll/aho-corasick for literal string matching.

Using with Vite

Vite's dependency pre-bundler rewrites import.meta.url, which breaks the relative .wasm path emitted by the napi-rs loader. Import the bundled plugin so the package is excluded from pre-bundling:

// vite.config.ts
import stllWasm from "@stll/regex-set-wasm/vite";

export default {
  plugins: [stllWasm()],
};

Acknowledgements

• regex by Andrew Gallant (BurntSushi). MIT/Apache-2.0.
• fancy-regex for lookaround support. MIT.
• NAPI-RS. MIT.

Development

# Install dependencies
bun install

# Build native module (requires Rust toolchain)
bun run build
bun run build:js

# Run tests
bun test
bun run test:props

# Download benchmark corpora
bun run bench:download

# Run benchmark suites
bun run bench
bun run bench:fallback

# Lint & format
bun run lint
bun run format

# Rust quality gates
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --all -- --check

License

MIT