trilean-regex 0.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,88 @@
+# trilean-regex
+
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/trilean) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/trilean-regex) [![Release](https://img.shields.io/github/v/release/ExaDev/trilean?filter=trilean-regex@*&label=release)](https://github.com/ExaDev/trilean/releases?q=trilean-regex%40) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/trilean/ci.yml?branch=main)](https://github.com/ExaDev/trilean/actions)
+
+A portable regular-expression grammar -- a true regular language, with its own parser and a Thompson-construction reference matcher -- so a pattern means the same thing wherever it runs: in process here, and pushed down to a database's own engine by [`trilean-sql`](../trilean-sql).
+
+## Why a new grammar
+
+ECMAScript's `RegExp` is not a regular language. Backreferences and lookaround make it strictly more expressive than a finite automaton can recognise, and its backtracking implementation can take exponential time on certain inputs (the well-known "catastrophic backtracking" failure mode). Worse for portability: every SQL engine's own regex support is a *different* language again -- PostgreSQL's POSIX ARE is close to ECMAScript but not identical, and SQLite/D1 have no built-in regex engine at all.
+
+A pattern written in this package's grammar is different on both counts. It is restricted to constructs a finite automaton can express, so it always matches in linear time with no backtracking risk, and its reference matcher is guaranteed to agree with itself regardless of input. And because the grammar is deliberately small, a SQL dialect compiler can translate it structurally instead of trying to detect which subset of an open-ended ECMAScript pattern happens to be "safe" for that dialect -- see `trilean-sql`'s `portableMatches`/`portableNotMatches` compilers, which do exactly this for PostgreSQL and SQLite/D1.
+
+## Grammar
+
+Patterns are written with ordinary regex-like syntax so nothing new has to be learned, but only the constructs below are legal -- anything else is a parse error naming exactly where parsing failed, never a fuzzy runtime failure.
+
+| Construct | Meaning |
+|---|---|
+| `a` | A literal character |
+| `ab` | Concatenation: `a` then `b` |
+| `a\|b` | Alternation: `a` or `b` |
+| `a*` | Zero or more `a` |
+| `a+` | One or more `a` |
+| `a?` | Zero or one `a` |
+| `a{3}` | Exactly 3 `a` |
+| `a{2,}` | 2 or more `a` |
+| `a{2,5}` | Between 2 and 5 `a`, inclusive |
+| `.` | Any single character |
+| `^` | Start of the input |
+| `$` | End of the input |
+| `[abc]` | Any one of `a`, `b`, `c` |
+| `[a-z]` | Any character in the range `a` to `z` |
+| `[^abc]` | Any character except `a`, `b`, `c` |
+| `\d` `\D` | An ASCII digit (`0`-`9`), or its negation |
+| `\w` `\W` | An ASCII word character (`A`-`Z`, `a`-`z`, `0`-`9`, `_`), or its negation |
+| `\s` `\S` | An ASCII whitespace character (space, tab, `\n`, `\r`, `\f`, `\v`), or its negation |
+| `(?:ab)` | A non-capturing group, for precedence and repetition |
+| `\.` `\*` `\+` `\?` `\(` `\)` `\[` `\]` `\{` `\}` `\|` `\^` `\$` `\\` `\/` | An escaped metacharacter, matched literally |
+| `\n` `\t` `\r` `\f` `\v` | A control character, matched literally |
+
+Everything else the grammar deliberately excludes:
+
+- **No capturing groups.** `(a)` is a parse error directing the author to `(?:a)` instead. There is nothing to capture: this grammar only ever answers whether a pattern matches, never what matched, so a capturing group would be pure syntax with no corresponding capability.
+- **No backreferences** (`\1`), because they make the language context-sensitive rather than regular -- no finite automaton can recognise `(a+)\1`.
+- **No lookaround** (`(?=...)`, `(?!...)`, `(?<=...)`, `(?<!...)`), for the same reason: lookaround assertions are not part of a regular language's own recognition power.
+- **No lazy or possessive quantifiers** (`a*?`, `a*+`). These only change *which* substring a backtracking engine reports as the match; since this grammar only ever answers a yes/no membership question, greedy and lazy always agree on whether a match exists, so there is no behaviour left for either modifier to control. Stacking a second quantifier onto a first (`a**`, `a*+`, `a*{2}`) is therefore a parse error rather than being silently accepted as a no-op.
+- **No flags** (case-insensitivity, multiline, dotAll). `^`/`$` always mean the absolute start/end of the whole input, never a line boundary, and `.` always matches any character including a line terminator -- there is no flag to make either mean something else, so there is nothing to configure.
+
+## Character encoding
+
+A character is a UTF-16 code unit, exactly matching `RegExp`'s own behaviour without the `u` flag: `String.prototype.charCodeAt`'s notion of one character, not a full Unicode scalar value. A character outside the Basic Multilingual Plane is two separate code units under `.`, a character class, or a shorthand class, the same as it would be against a non-`u`-flag native `RegExp`.
+
+## Matching semantics
+
+`testPattern`/`compilePattern(...).test(...)` report whether **any substring** of the input matches -- the same "search" semantics as a bare `RegExp.prototype.test()` call with no anchors, not a "does the whole string match" test. Anchor the pattern yourself (`^...$`) for a full-string match.
+
+`^` and `$` can appear anywhere in the pattern -- inside a group, inside an alternation branch -- and always mean the absolute start/end of the whole input, evaluated at whatever position the automaton reaches them, not confined to the very start/end of the pattern text. `^a|z$` matches a string starting with `a`, or one ending with `z` (they are independent branches, each anchored on its own side only).
+
+## Reference implementation
+
+`parseRegex` is a hand-written recursive-descent parser producing a `RegexNode` AST -- the same AST `trilean-sql`'s dialect compilers pattern-match over to translate a pattern into `LIKE`/`GLOB`/`~` fragments, rather than each compiler re-parsing pattern text itself.
+
+`compilePattern`/`compileToNfa` compile that AST to a non-deterministic finite automaton via Thompson's construction, and `matchesNfa` simulates it against an input with the standard "new thread at every position" search algorithm (Cox, ["Regular Expression Matching Can Be Simple And Fast"](https://swtch.com/~rsc/regexp/regexp1.html)). This is what makes the "no catastrophic backtracking" guarantee true by construction rather than merely by convention: simulating an NFA takes time linear in `pattern states x input length` regardless of the pattern's shape, so there is no input this package's own reference matcher can be made to hang on.
+
+```ts
+import { compilePattern, testPattern, parseRegex, RegexParseError } from "trilean-regex";
+
+testPattern("^[\\w.]+@[\\w]+\\.[a-z]{2,}$", "person@example.com"); // true
+
+const compiled = compilePattern("^ENA-\\d{4,6}$");
+compiled.test("ENA-12345"); // true -- reuse the compiled pattern across many inputs
+compiled.test("ENA-123");   // false
+
+try {
+  parseRegex("(a)");
+} catch (error) {
+  if (error instanceof RegexParseError) {
+    // "invalid pattern at index 0: capturing groups are not supported..."
+  }
+}
+```
+
+## Design principles
+
+- **A true regular language, not a documented subset of one.** Every construct this grammar accepts corresponds to something a finite automaton can express; nothing is included on the promise that "most engines happen to agree about it."
+- **A real parser, not pattern validation.** `parseRegex` builds an AST via recursive descent, the same way a general-purpose parser would -- it does not check the input string against a meta-pattern and hope the input itself is then safe to hand to another regex engine.
+- **No indeterminate outcome for a bad pattern here.** A pattern is grammatical or it is not; `parseRegex` throws `RegexParseError` for the latter, naming the exact index. (What a caller does with that error -- `trilean` core's `evaluator.ts` turns an invalid `portableMatches` pattern into `wrong-type`, matching how it already treats an invalid ECMAScript pattern under plain `matches` -- is that caller's decision, not this package's.)
+- **Isomorphic.** No `node:*` import, no `Buffer`, in any runtime module -- enforced by this package's own `eslint.config.ts` isomorphism guard, the same convention `trilean` and `trilean-sql` both follow.

package/dist/ast-D8HLFxxv.d.cts

@@ -0,0 +1,75 @@
+//#region src/ast.d.ts
+/**
+ * The abstract syntax this package's parser produces and its matcher and NFA compiler both consume.
+ *
+ * Every node kind here corresponds to a construct of a true regular language: no node kind exists for anything a finite automaton cannot express (a backreference, a lookaround assertion). That is what "portable" means for this grammar -- the AST is small enough, and restricted enough, that a `trilean-sql` dialect compiler can pattern-match over it directly instead of walking an open-ended ECMAScript pattern and hoping the subset it recognises is really the whole story.
+ *
+ * A code point is represented as its UTF-16 code unit value (what `String.prototype.charCodeAt` returns), matching non-`u`-flag ECMAScript `RegExp` semantics: a character outside the Basic Multilingual Plane is two code units, each matched independently, rather than one Unicode scalar value. This keeps the grammar's notion of "one character" identical to what `[a-z]`-style ranges and `.` mean in the engine most authors already carry a mental model of.
+ */
+/** A single literal character, matched by its UTF-16 code unit value. */
+interface LiteralNode {
+  readonly kind: "literal";
+  readonly codeUnit: number;
+}
+/** `.` -- matches exactly one character, of any value. Unlike ECMAScript's default mode, this grammar defines it to match a line terminator too: there is no multiline/dotAll mode to make that a meaningful distinction, so one unconditional rule is simpler than a flag nobody can set. */
+interface AnyCharNode {
+  readonly kind: "anyChar";
+}
+/** An inclusive code-unit range within a character class, e.g. `a-z`. A single character `c` is represented as `{ from: c, to: c }`. */
+interface CharRange {
+  readonly from: number;
+  readonly to: number;
+}
+/** `[...]` / `[^...]`, and the standalone shorthand classes (`\d`, `\D`, `\w`, `\W`, `\s`, `\S`) once expanded -- see `shorthand-classes.ts` for the fixed range tables each shorthand expands to. `ranges` is the positive set; `negated` flips membership rather than the ranges themselves, so a negated class still reports the positive ranges it was written against (useful for tooling, and what the SQLite `GLOB` compiler in trilean-sql needs to render `[^...]` back out). */
+interface CharClassNode {
+  readonly kind: "charClass";
+  readonly negated: boolean;
+  readonly ranges: readonly CharRange[];
+}
+/** `^` -- zero-width assertion that the current position is the very start of the input (absolute index 0), regardless of where in the pattern it appears. */
+interface AnchorStartNode {
+  readonly kind: "anchorStart";
+}
+/** `$` -- zero-width assertion that the current position is the very end of the input (index equal to the input's length). */
+interface AnchorEndNode {
+  readonly kind: "anchorEnd";
+}
+/** Sequencing: `operands` matched one after another with no characters skipped in between. An empty `operands` array is the empty pattern, matching the empty string. */
+interface ConcatNode {
+  readonly kind: "concat";
+  readonly operands: readonly RegexNode[];
+}
+/** `a|b|c` -- exactly one of `branches` matches. Always at least two branches; a single-branch alternation has no reason to exist and the parser never produces one. */
+interface AlternationNode {
+  readonly kind: "alternation";
+  readonly branches: readonly RegexNode[];
+}
+/** `a*` -- zero or more repetitions of `operand`. */
+interface StarNode {
+  readonly kind: "star";
+  readonly operand: RegexNode;
+}
+/** `a+` -- one or more repetitions of `operand`. */
+interface PlusNode {
+  readonly kind: "plus";
+  readonly operand: RegexNode;
+}
+/** `a?` -- zero or one repetition of `operand`. */
+interface OptionalNode {
+  readonly kind: "optional";
+  readonly operand: RegexNode;
+}
+/** `a{min,max}` -- between `min` and `max` repetitions of `operand`, inclusive. `max: undefined` means unbounded (`a{min,}`). `a{n}` parses to `min: n, max: n`. The parser never produces `min > max` (a bounded form with `max < min` is a parse error) and never produces the forms already covered by `StarNode`/`PlusNode`/`OptionalNode` -- those three are their own node kinds precisely so a matcher or compiler can special-case the common shapes without reading repetition bounds at all. */
+interface RepeatNode {
+  readonly kind: "repeat";
+  readonly operand: RegexNode;
+  readonly min: number;
+  readonly max: number | undefined;
+}
+type RegexNode = LiteralNode | AnyCharNode | CharClassNode | AnchorStartNode | AnchorEndNode | ConcatNode | AlternationNode | StarNode | PlusNode | OptionalNode | RepeatNode;
+/** Whether `unit` falls inside an inclusive range. */
+declare function rangeContains(range: CharRange, unit: number): boolean;
+/** Whether `unit` is a member of a character class, honouring `negated`. */
+declare function charClassMatches(node: CharClassNode, unit: number): boolean;
+//#endregion
+export { CharClassNode as a, LiteralNode as c, RegexNode as d, RepeatNode as f, rangeContains as h, AnyCharNode as i, OptionalNode as l, charClassMatches as m, AnchorEndNode as n, CharRange as o, StarNode as p, AnchorStartNode as r, ConcatNode as s, AlternationNode as t, PlusNode as u };

package/dist/ast-D8HLFxxv.d.ts

@@ -0,0 +1,75 @@
+//#region src/ast.d.ts
+/**
+ * The abstract syntax this package's parser produces and its matcher and NFA compiler both consume.
+ *
+ * Every node kind here corresponds to a construct of a true regular language: no node kind exists for anything a finite automaton cannot express (a backreference, a lookaround assertion). That is what "portable" means for this grammar -- the AST is small enough, and restricted enough, that a `trilean-sql` dialect compiler can pattern-match over it directly instead of walking an open-ended ECMAScript pattern and hoping the subset it recognises is really the whole story.
+ *
+ * A code point is represented as its UTF-16 code unit value (what `String.prototype.charCodeAt` returns), matching non-`u`-flag ECMAScript `RegExp` semantics: a character outside the Basic Multilingual Plane is two code units, each matched independently, rather than one Unicode scalar value. This keeps the grammar's notion of "one character" identical to what `[a-z]`-style ranges and `.` mean in the engine most authors already carry a mental model of.
+ */
+/** A single literal character, matched by its UTF-16 code unit value. */
+interface LiteralNode {
+  readonly kind: "literal";
+  readonly codeUnit: number;
+}
+/** `.` -- matches exactly one character, of any value. Unlike ECMAScript's default mode, this grammar defines it to match a line terminator too: there is no multiline/dotAll mode to make that a meaningful distinction, so one unconditional rule is simpler than a flag nobody can set. */
+interface AnyCharNode {
+  readonly kind: "anyChar";
+}
+/** An inclusive code-unit range within a character class, e.g. `a-z`. A single character `c` is represented as `{ from: c, to: c }`. */
+interface CharRange {
+  readonly from: number;
+  readonly to: number;
+}
+/** `[...]` / `[^...]`, and the standalone shorthand classes (`\d`, `\D`, `\w`, `\W`, `\s`, `\S`) once expanded -- see `shorthand-classes.ts` for the fixed range tables each shorthand expands to. `ranges` is the positive set; `negated` flips membership rather than the ranges themselves, so a negated class still reports the positive ranges it was written against (useful for tooling, and what the SQLite `GLOB` compiler in trilean-sql needs to render `[^...]` back out). */
+interface CharClassNode {
+  readonly kind: "charClass";
+  readonly negated: boolean;
+  readonly ranges: readonly CharRange[];
+}
+/** `^` -- zero-width assertion that the current position is the very start of the input (absolute index 0), regardless of where in the pattern it appears. */
+interface AnchorStartNode {
+  readonly kind: "anchorStart";
+}
+/** `$` -- zero-width assertion that the current position is the very end of the input (index equal to the input's length). */
+interface AnchorEndNode {
+  readonly kind: "anchorEnd";
+}
+/** Sequencing: `operands` matched one after another with no characters skipped in between. An empty `operands` array is the empty pattern, matching the empty string. */
+interface ConcatNode {
+  readonly kind: "concat";
+  readonly operands: readonly RegexNode[];
+}
+/** `a|b|c` -- exactly one of `branches` matches. Always at least two branches; a single-branch alternation has no reason to exist and the parser never produces one. */
+interface AlternationNode {
+  readonly kind: "alternation";
+  readonly branches: readonly RegexNode[];
+}
+/** `a*` -- zero or more repetitions of `operand`. */
+interface StarNode {
+  readonly kind: "star";
+  readonly operand: RegexNode;
+}
+/** `a+` -- one or more repetitions of `operand`. */
+interface PlusNode {
+  readonly kind: "plus";
+  readonly operand: RegexNode;
+}
+/** `a?` -- zero or one repetition of `operand`. */
+interface OptionalNode {
+  readonly kind: "optional";
+  readonly operand: RegexNode;
+}
+/** `a{min,max}` -- between `min` and `max` repetitions of `operand`, inclusive. `max: undefined` means unbounded (`a{min,}`). `a{n}` parses to `min: n, max: n`. The parser never produces `min > max` (a bounded form with `max < min` is a parse error) and never produces the forms already covered by `StarNode`/`PlusNode`/`OptionalNode` -- those three are their own node kinds precisely so a matcher or compiler can special-case the common shapes without reading repetition bounds at all. */
+interface RepeatNode {
+  readonly kind: "repeat";
+  readonly operand: RegexNode;
+  readonly min: number;
+  readonly max: number | undefined;
+}
+type RegexNode = LiteralNode | AnyCharNode | CharClassNode | AnchorStartNode | AnchorEndNode | ConcatNode | AlternationNode | StarNode | PlusNode | OptionalNode | RepeatNode;
+/** Whether `unit` falls inside an inclusive range. */
+declare function rangeContains(range: CharRange, unit: number): boolean;
+/** Whether `unit` is a member of a character class, honouring `negated`. */
+declare function charClassMatches(node: CharClassNode, unit: number): boolean;
+//#endregion
+export { CharClassNode as a, LiteralNode as c, RegexNode as d, RepeatNode as f, rangeContains as h, AnyCharNode as i, OptionalNode as l, charClassMatches as m, AnchorEndNode as n, CharRange as o, StarNode as p, AnchorStartNode as r, ConcatNode as s, AlternationNode as t, PlusNode as u };

package/dist/ast.cjs

@@ -0,0 +1,14 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/ast.ts
+/** Whether `unit` falls inside an inclusive range. */
+function rangeContains(range, unit) {
+	return unit >= range.from && unit <= range.to;
+}
+/** Whether `unit` is a member of a character class, honouring `negated`. */
+function charClassMatches(node, unit) {
+	const inRanges = node.ranges.some((range) => rangeContains(range, unit));
+	return node.negated ? !inRanges : inRanges;
+}
+//#endregion
+exports.charClassMatches = charClassMatches;
+exports.rangeContains = rangeContains;

package/dist/ast.d.cts

@@ -0,0 +1,2 @@
+import { a as CharClassNode, c as LiteralNode, d as RegexNode, f as RepeatNode, h as rangeContains, i as AnyCharNode, l as OptionalNode, m as charClassMatches, n as AnchorEndNode, o as CharRange, p as StarNode, r as AnchorStartNode, s as ConcatNode, t as AlternationNode, u as PlusNode } from "./ast-D8HLFxxv.cjs";
+export { AlternationNode, AnchorEndNode, AnchorStartNode, AnyCharNode, CharClassNode, CharRange, ConcatNode, LiteralNode, OptionalNode, PlusNode, RegexNode, RepeatNode, StarNode, charClassMatches, rangeContains };

package/dist/ast.d.ts

@@ -0,0 +1,2 @@
+import { a as CharClassNode, c as LiteralNode, d as RegexNode, f as RepeatNode, h as rangeContains, i as AnyCharNode, l as OptionalNode, m as charClassMatches, n as AnchorEndNode, o as CharRange, p as StarNode, r as AnchorStartNode, s as ConcatNode, t as AlternationNode, u as PlusNode } from "./ast-D8HLFxxv.js";
+export { AlternationNode, AnchorEndNode, AnchorStartNode, AnyCharNode, CharClassNode, CharRange, ConcatNode, LiteralNode, OptionalNode, PlusNode, RegexNode, RepeatNode, StarNode, charClassMatches, rangeContains };

package/dist/ast.js

@@ -0,0 +1,12 @@
+//#region src/ast.ts
+/** Whether `unit` falls inside an inclusive range. */
+function rangeContains(range, unit) {
+	return unit >= range.from && unit <= range.to;
+}
+/** Whether `unit` is a member of a character class, honouring `negated`. */
+function charClassMatches(node, unit) {
+	const inRanges = node.ranges.some((range) => rangeContains(range, unit));
+	return node.negated ? !inRanges : inRanges;
+}
+//#endregion
+export { charClassMatches, rangeContains };

package/dist/errors.cjs

@@ -0,0 +1,19 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/errors.ts
+/**
+* A pattern the parser refuses, with a real position rather than a generic message: `index` is the UTF-16 code unit offset into the source pattern string where parsing could not proceed, so a caller (or a test) can point at exactly what was wrong instead of re-deriving it from `message` alone.
+*
+* This is the only error this package's parser ever throws. There is no partial-AST return, no best-effort fallback -- a pattern either parses completely into a `RegexNode` or this is thrown, matching the "clear parse error, not a fuzzy runtime failure" goal a portable grammar exists for in the first place.
+*/
+var RegexParseError = class extends Error {
+	pattern;
+	index;
+	constructor(pattern, index, reason) {
+		super(`invalid pattern at index ${String(index)}: ${reason}\n  ${pattern}\n  ${" ".repeat(index)}^`);
+		this.name = "RegexParseError";
+		this.pattern = pattern;
+		this.index = index;
+	}
+};
+//#endregion
+exports.RegexParseError = RegexParseError;

package/dist/errors.d.cts

@@ -0,0 +1,13 @@
+//#region src/errors.d.ts
+/**
+ * A pattern the parser refuses, with a real position rather than a generic message: `index` is the UTF-16 code unit offset into the source pattern string where parsing could not proceed, so a caller (or a test) can point at exactly what was wrong instead of re-deriving it from `message` alone.
+ *
+ * This is the only error this package's parser ever throws. There is no partial-AST return, no best-effort fallback -- a pattern either parses completely into a `RegexNode` or this is thrown, matching the "clear parse error, not a fuzzy runtime failure" goal a portable grammar exists for in the first place.
+ */
+declare class RegexParseError extends Error {
+  readonly pattern: string;
+  readonly index: number;
+  constructor(pattern: string, index: number, reason: string);
+}
+//#endregion
+export { RegexParseError };

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+//#region src/errors.d.ts
+/**
+ * A pattern the parser refuses, with a real position rather than a generic message: `index` is the UTF-16 code unit offset into the source pattern string where parsing could not proceed, so a caller (or a test) can point at exactly what was wrong instead of re-deriving it from `message` alone.
+ *
+ * This is the only error this package's parser ever throws. There is no partial-AST return, no best-effort fallback -- a pattern either parses completely into a `RegexNode` or this is thrown, matching the "clear parse error, not a fuzzy runtime failure" goal a portable grammar exists for in the first place.
+ */
+declare class RegexParseError extends Error {
+  readonly pattern: string;
+  readonly index: number;
+  constructor(pattern: string, index: number, reason: string);
+}
+//#endregion
+export { RegexParseError };

package/dist/errors.js

@@ -0,0 +1,18 @@
+//#region src/errors.ts
+/**
+* A pattern the parser refuses, with a real position rather than a generic message: `index` is the UTF-16 code unit offset into the source pattern string where parsing could not proceed, so a caller (or a test) can point at exactly what was wrong instead of re-deriving it from `message` alone.
+*
+* This is the only error this package's parser ever throws. There is no partial-AST return, no best-effort fallback -- a pattern either parses completely into a `RegexNode` or this is thrown, matching the "clear parse error, not a fuzzy runtime failure" goal a portable grammar exists for in the first place.
+*/
+var RegexParseError = class extends Error {
+	pattern;
+	index;
+	constructor(pattern, index, reason) {
+		super(`invalid pattern at index ${String(index)}: ${reason}\n  ${pattern}\n  ${" ".repeat(index)}^`);
+		this.name = "RegexParseError";
+		this.pattern = pattern;
+		this.index = index;
+	}
+};
+//#endregion
+export { RegexParseError };

package/dist/index.cjs

@@ -0,0 +1,16 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_ast = require("./ast.cjs");
+const require_errors = require("./errors.cjs");
+const require_shorthand_classes = require("./shorthand-classes.cjs");
+const require_parser = require("./parser.cjs");
+const require_nfa = require("./nfa.cjs");
+const require_matcher = require("./matcher.cjs");
+exports.RegexParseError = require_errors.RegexParseError;
+exports.charClassMatches = require_ast.charClassMatches;
+exports.compilePattern = require_matcher.compilePattern;
+exports.compileToNfa = require_nfa.compileToNfa;
+exports.expandShorthandClass = require_shorthand_classes.expandShorthandClass;
+exports.matchesNfa = require_matcher.matchesNfa;
+exports.parseRegex = require_parser.parseRegex;
+exports.rangeContains = require_ast.rangeContains;
+exports.testPattern = require_matcher.testPattern;

package/dist/index.d.cts

@@ -0,0 +1,7 @@
+import { a as CharClassNode, c as LiteralNode, d as RegexNode, f as RepeatNode, h as rangeContains, i as AnyCharNode, l as OptionalNode, m as charClassMatches, n as AnchorEndNode, o as CharRange, p as StarNode, r as AnchorStartNode, s as ConcatNode, t as AlternationNode, u as PlusNode } from "./ast-D8HLFxxv.cjs";
+import { RegexParseError } from "./errors.cjs";
+import { parseRegex } from "./parser.cjs";
+import { ShorthandClassLetter, expandShorthandClass } from "./shorthand-classes.cjs";
+import { CompiledNfa, NfaState, compileToNfa } from "./nfa.cjs";
+import { CompiledPattern, compilePattern, matchesNfa, testPattern } from "./matcher.cjs";
+export { type AlternationNode, type AnchorEndNode, type AnchorStartNode, type AnyCharNode, type CharClassNode, type CharRange, type CompiledNfa, type CompiledPattern, type ConcatNode, type LiteralNode, type NfaState, type OptionalNode, type PlusNode, type RegexNode, RegexParseError, type RepeatNode, type ShorthandClassLetter, type StarNode, charClassMatches, compilePattern, compileToNfa, expandShorthandClass, matchesNfa, parseRegex, rangeContains, testPattern };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { a as CharClassNode, c as LiteralNode, d as RegexNode, f as RepeatNode, h as rangeContains, i as AnyCharNode, l as OptionalNode, m as charClassMatches, n as AnchorEndNode, o as CharRange, p as StarNode, r as AnchorStartNode, s as ConcatNode, t as AlternationNode, u as PlusNode } from "./ast-D8HLFxxv.js";
+import { RegexParseError } from "./errors.js";
+import { parseRegex } from "./parser.js";
+import { ShorthandClassLetter, expandShorthandClass } from "./shorthand-classes.js";
+import { CompiledNfa, NfaState, compileToNfa } from "./nfa.js";
+import { CompiledPattern, compilePattern, matchesNfa, testPattern } from "./matcher.js";
+export { type AlternationNode, type AnchorEndNode, type AnchorStartNode, type AnyCharNode, type CharClassNode, type CharRange, type CompiledNfa, type CompiledPattern, type ConcatNode, type LiteralNode, type NfaState, type OptionalNode, type PlusNode, type RegexNode, RegexParseError, type RepeatNode, type ShorthandClassLetter, type StarNode, charClassMatches, compilePattern, compileToNfa, expandShorthandClass, matchesNfa, parseRegex, rangeContains, testPattern };

package/dist/index.js

@@ -0,0 +1,7 @@
+import { charClassMatches, rangeContains } from "./ast.js";
+import { RegexParseError } from "./errors.js";
+import { expandShorthandClass } from "./shorthand-classes.js";
+import { parseRegex } from "./parser.js";
+import { compileToNfa } from "./nfa.js";
+import { compilePattern, matchesNfa, testPattern } from "./matcher.js";
+export { RegexParseError, charClassMatches, compilePattern, compileToNfa, expandShorthandClass, matchesNfa, parseRegex, rangeContains, testPattern };

package/dist/matcher.cjs

@@ -0,0 +1,89 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_parser = require("./parser.cjs");
+const require_nfa = require("./nfa.cjs");
+//#region src/matcher.ts
+/**
+* Epsilon-closure of `seeds` at absolute input position `pos` (0-based, counting the boundary *before* the character at that index -- so `pos === length` means "after the last character"): follows every `split` unconditionally and every `anchorStart`/`anchorEnd` only when `pos` satisfies it, stopping at each `char` or `match` state reached, which are the only kinds `matchesNfa`'s step loop ever needs to see.
+*
+* `length` is threaded through only for the `anchorEnd` check (`pos === length`) rather than read off a captured string, so this function depends on nothing beyond the automaton and two numbers -- it has no notion of "the input," only of where the boundary it is being asked about sits relative to the input's own length.
+*/
+function closure(nfa, seeds, pos, length) {
+	const result = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const stack = [...seeds];
+	while (stack.length > 0) {
+		const idx = stack.pop();
+		if (idx === void 0) continue;
+		if (visited.has(idx)) continue;
+		visited.add(idx);
+		const state = nfa.states[idx];
+		if (state === void 0) continue;
+		switch (state.kind) {
+			case "char":
+			case "match":
+				result.add(idx);
+				break;
+			case "split":
+				stack.push(state.to1, state.to2);
+				break;
+			case "anchorStart":
+				if (pos === 0) stack.push(state.to);
+				break;
+			case "anchorEnd": if (pos === length) stack.push(state.to);
+		}
+	}
+	return result;
+}
+/** The `char` states in `current` whose test accepts `codeUnit`, mapped to their (not yet closed) successor. Never includes `match` states -- there is nothing past a match to step from. */
+function step(nfa, current, codeUnit) {
+	const next = /* @__PURE__ */ new Set();
+	for (const idx of current) {
+		const state = nfa.states[idx];
+		if (state?.kind !== "char") continue;
+		if (state.test(codeUnit)) next.add(state.to);
+	}
+	return next;
+}
+/**
+* Simulates `nfa` against `input` and reports whether any substring of `input` matches -- the same "search," not "full match," semantics a bare `RegExp.prototype.test()` call has without the `^.../$...` anchors pinning it down, since `^`/`$` are already ordinary states inside the automaton (see `nfa.ts`) rather than a separate mode this function chooses between.
+*
+* The technique is the standard "add a fresh thread at every position" Thompson NFA search (Cox, "Regular Expression Matching Can Be Simple And Fast"): a new candidate match start is injected into the active state set before each character is consumed, exactly as if `.*?` had been prepended to an anchored pattern, except no such prefix is ever built -- the injection is the runtime equivalent of it. Because injection happens unconditionally and `^`'s own position check is what actually restricts where a match may begin, a pattern beginning with `^` still only ever matches from position 0, and one that does not can begin anywhere.
+*
+* Runs in O(length x states) time and allocates no more than two small state sets at a time, regardless of the pattern's shape -- there is no exponential blow-up for any input this compiles, which is the whole reason this package builds an automaton instead of calling a backtracking engine.
+*/
+function matchesNfa(nfa, input) {
+	const length = input.length;
+	let current = closure(nfa, [nfa.start], 0, length);
+	if (current.has(nfa.matchState)) return true;
+	for (let pos = 0; pos < length; pos += 1) {
+		const codeUnit = input.charCodeAt(pos);
+		const stepped = step(nfa, current, codeUnit);
+		stepped.add(nfa.start);
+		current = closure(nfa, [...stepped], pos + 1, length);
+		if (current.has(nfa.matchState)) return true;
+	}
+	return false;
+}
+/**
+* Parses `pattern` (this package's grammar; see README.md) and compiles it to a reference matcher.
+*
+* Prefer this over `testPattern` when the same pattern will be tested against more than one input: it parses and compiles exactly once, and the returned `CompiledPattern.test` is then only the O(length x states) simulation.
+*
+* @throws {RegexParseError} if `pattern` is not a valid pattern in this grammar.
+*/
+function compilePattern(pattern) {
+	const nfa = require_nfa.compileToNfa(require_parser.parseRegex(pattern));
+	return { test: (input) => matchesNfa(nfa, input) };
+}
+/**
+* Parses `pattern` and tests it against `input` in one call. Equivalent to `compilePattern(pattern).test(input)`, and exactly as cheap for a single test -- prefer `compilePattern` instead when the same pattern will be reused, so the parse and compile steps happen once rather than once per input.
+*
+* @throws {RegexParseError} if `pattern` is not a valid pattern in this grammar.
+*/
+function testPattern(pattern, input) {
+	return compilePattern(pattern).test(input);
+}
+//#endregion
+exports.compilePattern = compilePattern;
+exports.matchesNfa = matchesNfa;
+exports.testPattern = testPattern;

package/dist/matcher.d.cts

@@ -0,0 +1,31 @@
+import { CompiledNfa } from "./nfa.cjs";
+//#region src/matcher.d.ts
+/**
+ * Simulates `nfa` against `input` and reports whether any substring of `input` matches -- the same "search," not "full match," semantics a bare `RegExp.prototype.test()` call has without the `^.../$...` anchors pinning it down, since `^`/`$` are already ordinary states inside the automaton (see `nfa.ts`) rather than a separate mode this function chooses between.
+ *
+ * The technique is the standard "add a fresh thread at every position" Thompson NFA search (Cox, "Regular Expression Matching Can Be Simple And Fast"): a new candidate match start is injected into the active state set before each character is consumed, exactly as if `.*?` had been prepended to an anchored pattern, except no such prefix is ever built -- the injection is the runtime equivalent of it. Because injection happens unconditionally and `^`'s own position check is what actually restricts where a match may begin, a pattern beginning with `^` still only ever matches from position 0, and one that does not can begin anywhere.
+ *
+ * Runs in O(length x states) time and allocates no more than two small state sets at a time, regardless of the pattern's shape -- there is no exponential blow-up for any input this compiles, which is the whole reason this package builds an automaton instead of calling a backtracking engine.
+ */
+declare function matchesNfa(nfa: CompiledNfa, input: string): boolean;
+/** A parsed and compiled pattern, ready to test any number of inputs without re-parsing or re-compiling. */
+interface CompiledPattern {
+  /** Whether any substring of `input` matches this pattern -- see `matchesNfa`. */
+  test: (input: string) => boolean;
+}
+/**
+ * Parses `pattern` (this package's grammar; see README.md) and compiles it to a reference matcher.
+ *
+ * Prefer this over `testPattern` when the same pattern will be tested against more than one input: it parses and compiles exactly once, and the returned `CompiledPattern.test` is then only the O(length x states) simulation.
+ *
+ * @throws {RegexParseError} if `pattern` is not a valid pattern in this grammar.
+ */
+declare function compilePattern(pattern: string): CompiledPattern;
+/**
+ * Parses `pattern` and tests it against `input` in one call. Equivalent to `compilePattern(pattern).test(input)`, and exactly as cheap for a single test -- prefer `compilePattern` instead when the same pattern will be reused, so the parse and compile steps happen once rather than once per input.
+ *
+ * @throws {RegexParseError} if `pattern` is not a valid pattern in this grammar.
+ */
+declare function testPattern(pattern: string, input: string): boolean;
+//#endregion
+export { CompiledPattern, compilePattern, matchesNfa, testPattern };

package/dist/matcher.d.ts

@@ -0,0 +1,31 @@
+import { CompiledNfa } from "./nfa.js";
+//#region src/matcher.d.ts
+/**
+ * Simulates `nfa` against `input` and reports whether any substring of `input` matches -- the same "search," not "full match," semantics a bare `RegExp.prototype.test()` call has without the `^.../$...` anchors pinning it down, since `^`/`$` are already ordinary states inside the automaton (see `nfa.ts`) rather than a separate mode this function chooses between.
+ *
+ * The technique is the standard "add a fresh thread at every position" Thompson NFA search (Cox, "Regular Expression Matching Can Be Simple And Fast"): a new candidate match start is injected into the active state set before each character is consumed, exactly as if `.*?` had been prepended to an anchored pattern, except no such prefix is ever built -- the injection is the runtime equivalent of it. Because injection happens unconditionally and `^`'s own position check is what actually restricts where a match may begin, a pattern beginning with `^` still only ever matches from position 0, and one that does not can begin anywhere.
+ *
+ * Runs in O(length x states) time and allocates no more than two small state sets at a time, regardless of the pattern's shape -- there is no exponential blow-up for any input this compiles, which is the whole reason this package builds an automaton instead of calling a backtracking engine.
+ */
+declare function matchesNfa(nfa: CompiledNfa, input: string): boolean;
+/** A parsed and compiled pattern, ready to test any number of inputs without re-parsing or re-compiling. */
+interface CompiledPattern {
+  /** Whether any substring of `input` matches this pattern -- see `matchesNfa`. */
+  test: (input: string) => boolean;
+}
+/**
+ * Parses `pattern` (this package's grammar; see README.md) and compiles it to a reference matcher.
+ *
+ * Prefer this over `testPattern` when the same pattern will be tested against more than one input: it parses and compiles exactly once, and the returned `CompiledPattern.test` is then only the O(length x states) simulation.
+ *
+ * @throws {RegexParseError} if `pattern` is not a valid pattern in this grammar.
+ */
+declare function compilePattern(pattern: string): CompiledPattern;
+/**
+ * Parses `pattern` and tests it against `input` in one call. Equivalent to `compilePattern(pattern).test(input)`, and exactly as cheap for a single test -- prefer `compilePattern` instead when the same pattern will be reused, so the parse and compile steps happen once rather than once per input.
+ *
+ * @throws {RegexParseError} if `pattern` is not a valid pattern in this grammar.
+ */
+declare function testPattern(pattern: string, input: string): boolean;
+//#endregion
+export { CompiledPattern, compilePattern, matchesNfa, testPattern };