regex-partial-match 0.4.0 → 1.1.0

package/lib/compilePartial.js

@@ -0,0 +1,334 @@
+import escapeAtom from "./escapeAtom.js";
+const OCCURRENCES_REGEX = /\{\d+,?\d*\}/y;
+const NOT_NUMBERS_REGEX = /\D/g;
+const DISJUNCTION_TO_END_OF_INPUT = "|$(?![\\s\\S]))";
+const MAYBE_HAS_BACKREFERENCE = /\\[1-9]|\\k</;
+const isBackreference = (part) => typeof part !== "string";
+const isNumericBackreference = (part) => isBackreference(part) && typeof part.ref === "number";
+function walk(regex) {
+    const source = regex.source;
+    const isUnicode = regex.unicode || regex.unicodeSets;
+    let i = 0;
+    let groupCount = 0;
+    const features = new Set();
+    function extractSlice(length) {
+        return source.slice(i, (i += length));
+    }
+    function process() {
+        var _a;
+        const result = [];
+        function appendOptional(length) {
+            result.push("(?:" + extractSlice(length) + DISJUNCTION_TO_END_OF_INPUT);
+        }
+        function appendRaw(length) {
+            result.push(extractSlice(length));
+        }
+        function appendRawGroup(prefixLength) {
+            const start = i;
+            i += prefixLength;
+            process();
+            result.push(source.slice(start, i));
+        }
+        while (i < source.length) {
+            switch (source[i]) {
+                case "\\":
+                    switch (source[i + 1]) {
+                        case "c":
+                            features.add("controlLetterEscape");
+                            appendOptional(3);
+                            break;
+                        case "k": {
+                            const referenceEnd = source[i + 2] === "<" ? source.indexOf(">", i) : -1;
+                            if (referenceEnd === -1) {
+                                appendOptional(2);
+                            }
+                            else {
+                                features.add("namedBackreference");
+                                const start = i;
+                                const ref = source.slice(i + 3, referenceEnd);
+                                i = referenceEnd + 1;
+                                result.push({ ref, start, end: i });
+                            }
+                            break;
+                        }
+                        case "u":
+                            features.add("unicodeEscapeSequence");
+                            if (isUnicode && source[i + 2] === "{") {
+                                appendOptional(source.indexOf("}", i) - i + 1);
+                            }
+                            else {
+                                appendOptional(6);
+                            }
+                            break;
+                        case "p":
+                        case "P":
+                            if (isUnicode) {
+                                features.add("unicodePropertyEscape");
+                                appendOptional(source.indexOf("}", i) - i + 1);
+                            }
+                            else {
+                                appendOptional(2);
+                            }
+                            break;
+                        case "x":
+                            features.add("hexEscapeSequence");
+                            appendOptional(4);
+                            break;
+                        case "b":
+                            features.add("wordBoundary");
+                            appendOptional(2);
+                            break;
+                        case "B":
+                            features.add("nonWordBoundary");
+                            appendOptional(2);
+                            break;
+                        case "f":
+                        case "n":
+                        case "r":
+                        case "t":
+                        case "v":
+                            features.add("controlEscape");
+                            appendOptional(2);
+                            break;
+                        case "1":
+                        case "2":
+                        case "3":
+                        case "4":
+                        case "5":
+                        case "6":
+                        case "7":
+                        case "8":
+                        case "9": {
+                            features.add("backreference");
+                            NOT_NUMBERS_REGEX.lastIndex = i + 1;
+                            const nextNonDigit = NOT_NUMBERS_REGEX.exec(source);
+                            const start = i;
+                            const end = nextNonDigit ? nextNonDigit.index : source.length;
+                            const ref = Number(source.slice(start + 1, end));
+                            i = end;
+                            result.push({ ref, start, end });
+                            break;
+                        }
+                        case "d":
+                        case "D":
+                        case "w":
+                        case "W":
+                        case "s":
+                        case "S":
+                            features.add("characterClassEscape");
+                            appendOptional(2);
+                            break;
+                        default:
+                            features.add("otherEscape");
+                            appendOptional(2);
+                            break;
+                    }
+                    break;
+                case "[": {
+                    features.add("characterClass");
+                    let depth = 1, j = i + 1, previousSetOperatorCharacter;
+                    while (depth) {
+                        const character = source[j];
+                        switch (character) {
+                            case "\\":
+                                j += 2;
+                                previousSetOperatorCharacter = undefined;
+                                continue;
+                            case "[":
+                                if (regex.unicodeSets) {
+                                    features.add("nestedCharacterClass");
+                                    depth++;
+                                }
+                                break;
+                            case "]":
+                                depth--;
+                                break;
+                            case "&":
+                                if (regex.unicodeSets && previousSetOperatorCharacter === "&") {
+                                    features.add("classIntersection");
+                                }
+                                break;
+                            case "-":
+                                if (regex.unicodeSets && previousSetOperatorCharacter === "-") {
+                                    features.add("classSubtraction");
+                                }
+                                break;
+                        }
+                        previousSetOperatorCharacter = character;
+                        j++;
+                    }
+                    appendOptional(j - i);
+                    break;
+                }
+                case "^":
+                    features.add("startAnchor");
+                    appendRaw(1);
+                    break;
+                case "$":
+                    features.add("endAnchor");
+                    appendRaw(1);
+                    break;
+                case "|":
+                    features.add("disjunction");
+                    appendRaw(1);
+                    break;
+                case "*":
+                case "+":
+                case "?":
+                    features.add("quantifier");
+                    appendRaw(1);
+                    break;
+                case "{": {
+                    OCCURRENCES_REGEX.lastIndex = i;
+                    const regExpExecArray = OCCURRENCES_REGEX.exec(source);
+                    if (regExpExecArray) {
+                        features.add("quantifier");
+                        appendRaw(regExpExecArray[0].length);
+                    }
+                    else {
+                        appendOptional(1);
+                    }
+                    break;
+                }
+                case "(":
+                    if (source[i + 1] == "?") {
+                        switch (source[i + 2]) {
+                            case ":":
+                                features.add("nonCapturingGroup");
+                                result.push("(?:");
+                                i += 3;
+                                result.push(...process(), DISJUNCTION_TO_END_OF_INPUT);
+                                break;
+                            case "=":
+                                features.add("lookahead");
+                                result.push("(?=");
+                                i += 3;
+                                result.push(...process(), ")");
+                                break;
+                            case "-":
+                            case "i":
+                            case "s":
+                            case "m": {
+                                const flagsStart = i + 2, colonIndex = source.indexOf(":", flagsStart);
+                                const modifiers = source.slice(flagsStart, colonIndex);
+                                features.add(modifiers.includes("-")
+                                    ? "modifierGroupWithRemoval"
+                                    : "modifierGroup");
+                                result.push("(?" + modifiers + ":");
+                                i = colonIndex + 1;
+                                result.push(...process(), ")");
+                                break;
+                            }
+                            case "!":
+                                features.add("negativeLookahead");
+                                appendRawGroup(3);
+                                break;
+                            case "<":
+                                switch (source[i + 3]) {
+                                    case "=":
+                                        features.add("lookbehind");
+                                        appendRawGroup(4);
+                                        break;
+                                    case "!":
+                                        features.add("negativeLookbehind");
+                                        appendRawGroup(4);
+                                        break;
+                                    default:
+                                        features.add("namedGroup");
+                                        features.add("capturingGroup");
+                                        ++groupCount;
+                                        appendRaw(source.indexOf(">", i) - i + 1);
+                                        result.push(...process(), DISJUNCTION_TO_END_OF_INPUT);
+                                        break;
+                                }
+                                break;
+                        }
+                    }
+                    else {
+                        features.add("capturingGroup");
+                        ++groupCount;
+                        appendRaw(1);
+                        result.push(...process(), DISJUNCTION_TO_END_OF_INPUT);
+                    }
+                    break;
+                case ")":
+                    ++i;
+                    return result;
+                default:
+                    features.add("patternCharacter");
+                    appendOptional(isUnicode && ((_a = source.codePointAt(i)) !== null && _a !== void 0 ? _a : 0) > 0xffff ? 2 : 1);
+                    break;
+            }
+        }
+        return result;
+    }
+    return { parts: process(), groupCount, features };
+}
+function render(parts, renderBackref) {
+    return parts
+        .map((part) => (isBackreference(part) ? renderBackref(part) : part))
+        .join("");
+}
+function backrefToken(backref) {
+    return isNumericBackreference(backref)
+        ? "\\" + String(backref.ref)
+        : "\\k<" + backref.ref + ">";
+}
+function reclassifyOctalEscapes(parts, source, groupCount) {
+    return parts.map((part) => isNumericBackreference(part) && part.ref > groupCount
+        ? "(?:" + source.slice(part.start, part.end) + DISJUNCTION_TO_END_OF_INPUT
+        : part);
+}
+function spliceOriginalSource(source, backrefs) {
+    let result = "";
+    let cursor = 0;
+    for (const { start, end } of backrefs) {
+        result += source.slice(cursor, start) + "(?:[\\s\\S]*?)";
+        cursor = end;
+    }
+    return result + source.slice(cursor);
+}
+function expandCaptured(value, isUnicode) {
+    return (isUnicode ? Array.from(value) : value.split(""))
+        .map((atom) => "(?:" + escapeAtom(atom) + DISJUNCTION_TO_END_OF_INPUT)
+        .join("");
+}
+export const compilePartial = (regex) => {
+    const { parts, groupCount, features } = walk(regex);
+    if (!MAYBE_HAS_BACKREFERENCE.test(regex.source)) {
+        return {
+            kind: "static",
+            regex: new RegExp(render(parts, backrefToken), regex.flags),
+            features
+        };
+    }
+    const isUnicode = regex.unicode || regex.unicodeSets;
+    const sanitizedParts = isUnicode
+        ? parts
+        : reclassifyOctalEscapes(parts, regex.source, groupCount);
+    const backreferences = sanitizedParts.filter(isBackreference);
+    if (backreferences.length === 0) {
+        return {
+            kind: "static",
+            regex: new RegExp(render(sanitizedParts, backrefToken), regex.flags),
+            features
+        };
+    }
+    return {
+        kind: "dynamic",
+        features,
+        dynamic: {
+            originalCaptureScan: new RegExp(spliceOriginalSource(regex.source, backreferences), regex.flags),
+            preScan: new RegExp(render(parts, () => "(?:[\\s\\S]*?)"), regex.flags),
+            expand: (capture) => render(parts, (backref) => {
+                var _a;
+                const captured = isNumericBackreference(backref)
+                    ? capture[backref.ref]
+                    : (_a = capture.groups) === null || _a === void 0 ? void 0 : _a[backref.ref];
+                return captured === undefined
+                    ? "(?:" + backrefToken(backref) + DISJUNCTION_TO_END_OF_INPUT
+                    : expandCaptured(captured, isUnicode);
+            })
+        }
+    };
+};

package/lib/escapeAtom.d.ts

@@ -0,0 +1 @@
+export default function escapeAtom(atom: string): string;

package/lib/escapeAtom.js

@@ -0,0 +1,5 @@
+export default function escapeAtom(atom) {
+    var _a, _b;
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- support for RegExp.escape is not yet widespread, so fallback to manual escape
+    return (_b = (_a = RegExp.escape) === null || _a === void 0 ? void 0 : _a.call(RegExp, atom)) !== null && _b !== void 0 ? _b : atom.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/lib/extend.d.ts

@@ -1,3 +1,4 @@
+import PartialMatchRegExp from "./partialMatchRegExp.ts";
 declare global {
     interface RegExp {
         /**
@@ -7,7 +8,7 @@ declare global {
          * with an alternation to end-of-input (`$`), allowing the pattern to match prefixes
          * of the original pattern. This enables validation of incomplete input strings.
          *
-         * @returns A new RegExp that matches partial strings of the original pattern
+         * @returns A new PartialMatchRegExp that matches partial strings of the original pattern
          *
          * @example
          * ```typescript
@@ -23,13 +24,11 @@ declare global {
          *
          * @remarks
          * - The transformed regex will always match an empty string at the end of input
-         * - Backreferences cannot be partially matched as they are atomic
          * - Use with a start anchor (`^`) to prevent false positives from empty string matches
          * - The `y` (sticky) flag may not behave as expected in partial matching scenarios
          *
          * @see {@link https://github.com/TomStrepsil/regex-partial-match#readme | Documentation}
          */
-        toPartialMatchRegex(): RegExp;
+        toPartialMatchRegex(): PartialMatchRegExp;
     }
 }
-export {};

package/lib/extend.js

@@ -1,4 +1,4 @@
-import createPartialMatchRegex from "./index.js";
+import PartialMatchRegExp from "./partialMatchRegExp.js";
 RegExp.prototype.toPartialMatchRegex = function () {
-    return createPartialMatchRegex(this);
+    return new PartialMatchRegExp(this);
 };

package/lib/partialMatchRegExp.d.ts

@@ -0,0 +1,35 @@
+import { type RegexFeature } from "./compilePartial.ts";
+export type { RegexFeature };
+/**
+ * A `RegExp` subclass that supports partial (prefix) matching.
+ *
+ * An instance behaves like a normal `RegExp` but also matches any input string
+ * that is a valid prefix of the original pattern — i.e. strings that could still
+ * lead to a full match with more input. This enables validation of incomplete
+ * input strings.
+ *
+ * @example
+ * ```typescript
+ * const pattern = /^hello world/;
+ * const partial = new PartialMatchRegExp(pattern);
+ *
+ * partial.test('h');           // true - could match
+ * partial.test('hello');       // true - could match
+ * partial.test('hello world'); // true - full match
+ * partial.test('goodbye');     // false - cannot match
+ * ```
+ *
+ * @remarks
+ * - The transformed pattern always matches an empty string at the end of input;
+ *   use a start anchor (`^`) to prevent false positives from empty string matches
+ * - The `y` (sticky) flag may not behave as expected in partial matching scenarios
+ *
+ * @see {@link https://github.com/TomStrepsil/regex-partial-match#readme | Documentation}
+ */
+declare class PartialMatchRegExp extends RegExp {
+    #private;
+    readonly features: ReadonlySet<RegexFeature>;
+    constructor(pattern: RegExp | string, flags?: string);
+    exec(input: string): RegExpExecArray | null;
+}
+export default PartialMatchRegExp;

package/lib/partialMatchRegExp.js

@@ -0,0 +1,114 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _PartialMatchRegExp_static, _PartialMatchRegExp_dynamic;
+import { compilePartial } from "./compilePartial.js";
+/**
+ * A `RegExp` subclass that supports partial (prefix) matching.
+ *
+ * An instance behaves like a normal `RegExp` but also matches any input string
+ * that is a valid prefix of the original pattern — i.e. strings that could still
+ * lead to a full match with more input. This enables validation of incomplete
+ * input strings.
+ *
+ * @example
+ * ```typescript
+ * const pattern = /^hello world/;
+ * const partial = new PartialMatchRegExp(pattern);
+ *
+ * partial.test('h');           // true - could match
+ * partial.test('hello');       // true - could match
+ * partial.test('hello world'); // true - full match
+ * partial.test('goodbye');     // false - cannot match
+ * ```
+ *
+ * @remarks
+ * - The transformed pattern always matches an empty string at the end of input;
+ *   use a start anchor (`^`) to prevent false positives from empty string matches
+ * - The `y` (sticky) flag may not behave as expected in partial matching scenarios
+ *
+ * @see {@link https://github.com/TomStrepsil/regex-partial-match#readme | Documentation}
+ */
+class PartialMatchRegExp extends RegExp {
+    constructor(pattern, flags) {
+        var _a, _b;
+        super(pattern, flags);
+        _PartialMatchRegExp_static.set(this, void 0);
+        _PartialMatchRegExp_dynamic.set(this, void 0);
+        const compiled = compilePartial(this);
+        _a = this, _b = this, [({ set value(_c) { __classPrivateFieldSet(_a, _PartialMatchRegExp_dynamic, _c, "f"); } }).value, ({ set value(_c) { __classPrivateFieldSet(_b, _PartialMatchRegExp_static, _c, "f"); } }).value] = compiled.kind === "dynamic"
+            ? [compiled.dynamic, null]
+            : [null, compiled.regex];
+        this.features = compiled.features;
+    }
+    exec(input) {
+        if (!__classPrivateFieldGet(this, _PartialMatchRegExp_dynamic, "f")) {
+            const partial = __classPrivateFieldGet(this, _PartialMatchRegExp_static, "f"); // eslint-disable-line @typescript-eslint/no-non-null-assertion -- #static is set whenever #dynamic is null
+            partial.lastIndex = this.lastIndex;
+            const match = partial.exec(input);
+            this.lastIndex = partial.lastIndex;
+            return match;
+        }
+        const start = this.lastIndex;
+        const originalMatch = super.exec(input);
+        if (originalMatch)
+            return originalMatch;
+        const { originalCaptureScan, preScan, expand } = __classPrivateFieldGet(this, _PartialMatchRegExp_dynamic, "f");
+        originalCaptureScan.lastIndex = start;
+        let capture = originalCaptureScan.exec(input);
+        if (capture === null) {
+            preScan.lastIndex = start;
+            capture = preScan.exec(input);
+        }
+        if (capture === null)
+            return null;
+        const expanded = new RegExp(expand(capture), this.flags);
+        expanded.lastIndex = start;
+        const match = expanded.exec(input);
+        if (match === null)
+            return null;
+        preferLongerCaptures(match, capture);
+        this.lastIndex = expanded.lastIndex;
+        return match;
+    }
+}
+_PartialMatchRegExp_static = new WeakMap(), _PartialMatchRegExp_dynamic = new WeakMap();
+function pickLonger(scanned, matched) {
+    return scanned !== undefined &&
+        matched !== undefined &&
+        scanned.length > matched.length
+        ? scanned
+        : undefined;
+}
+function preferLongerCaptures(match, scanned) {
+    var _a, _b, _c, _d;
+    for (let index = 1; index < match.length; index++) {
+        const longer = pickLonger(scanned[index], match[index]);
+        if (longer === undefined)
+            continue;
+        match[index] = longer;
+        if (match.indices && ((_a = scanned.indices) === null || _a === void 0 ? void 0 : _a[index])) {
+            match.indices[index] = scanned.indices[index];
+        }
+    }
+    if (match.groups && scanned.groups) {
+        for (const name of Object.keys(match.groups)) {
+            const longer = pickLonger(scanned.groups[name], match.groups[name]);
+            if (longer === undefined)
+                continue;
+            match.groups[name] = longer;
+            if ((_b = match.indices) === null || _b === void 0 ? void 0 : _b.groups) {
+                match.indices.groups[name] = (_d = (_c = scanned.indices) === null || _c === void 0 ? void 0 : _c.groups) === null || _d === void 0 ? void 0 : _d[name];
+            }
+        }
+    }
+}
+export default PartialMatchRegExp;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "regex-partial-match",
-  "version": "0.4.0",
+  "version": "1.1.0",
   "description": "A regular expression transform for partial matching",
   "devEngines": {
     "runtime": {
@@ -9,7 +9,7 @@
     },
     "packageManager": {
       "name": "npm",
-      "version": "^11"
+      "version": "11.17.0+sha512.3eeaf18997b11070d313849268b23766b9db0068997dec9471073170fe43fa17f2b4d0337bf0f52330ee2274e7f5754b21b01052742e48f5c9c74d8b1e32ef43"
     }
   },
   "keywords": [
@@ -33,12 +33,12 @@
     }
   ],
   "type": "module",
-  "main": "lib/index.js",
+  "main": "lib/partialMatchRegExp.js",
   "exports": {
     ".": {
-      "types": "./lib/index.d.ts",
-      "import": "./lib/index.js",
-      "default": "./lib/index.js"
+      "types": "./lib/partialMatchRegExp.d.ts",
+      "import": "./lib/partialMatchRegExp.js",
+      "default": "./lib/partialMatchRegExp.js"
     },
     "./extend": {
       "types": "./lib/extend.d.ts",
@@ -53,6 +53,9 @@
     "type": "git",
     "url": "git+https://github.com/TomStrepsil/regex-partial-match.git"
   },
+  "workspaces": [
+    "benchmarking"
+  ],
   "sideEffects": false,
   "scripts": {
     "lint": "eslint .",
@@ -74,13 +77,16 @@
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
+    "@typescript/lib-es2018": "file:types/lib-es2018",
+    "@typescript/lib-es2022": "file:types/lib-es2022",
     "@eslint/js": "^9.17.0",
     "@eslint/markdown": "^7.5.1",
+    "@types/node": "^25.9.3",
     "eslint": "^9.17.0",
     "jiti": "^2.6.1",
     "lint-staged": "^15.2.11",
     "simple-git-hooks": "^2.12.1",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.18.1",
     "vitest": "^4.0.15"
   }

package/lib/index.d.ts

@@ -1,31 +0,0 @@
-declare const createPartialMatchRegex: (regex: RegExp) => RegExp;
-/**
- * Transforms a regular expression to support partial matching.
- *
- * This function wraps each atomic element of the regex pattern in a non-capturing group
- * with an alternation to end-of-input (`$`), allowing the pattern to match prefixes
- * of the original pattern. This enables validation of incomplete input strings.
- *
- * @param regex - The regular expression to transform for partial matching
- * @returns A new RegExp that matches partial strings of the original pattern
- *
- * @example
- * ```typescript
- * const pattern = /hello world/;
- * const partial = createPartialMatchRegex(pattern);
- *
- * partial.test('h');           // true - could match
- * partial.test('hello');       // true - could match
- * partial.test('hello world'); // true - full match
- * partial.test('goodbye');     // false - cannot match
- * ```
- *
- * @remarks
- * - The transformed regex will always match an empty string at the end of input
- * - Backreferences cannot be partially matched as they are atomic
- * - Use with a start anchor (`^`) to prevent false positives from empty string matches
- * - The `y` (sticky) flag may not behave as expected in partial matching scenarios
- *
- * @see {@link https://github.com/TomStrepsil/regex-partial-match#readme | Documentation}
- */
-export default createPartialMatchRegex;