regex-partial-match 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright 2025 Tom Pereira (https://github.com/TomStrepsil)
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# regex-partial-match
+
+A zero-dependency regular expression transform for partial matching, enabling validation of incomplete input strings against regex patterns.
+
+## Problem statement
+
+Unlike C/C++ (via [PCRE/PCRE2](https://www.pcre.org/original/doc/html/pcrepartial.html), [RE2](https://github.com/google/re2?tab=readme-ov-file#matching-interface), [Boost.Regex](https://www.boost.org/doc/libs/1_34_1/libs/regex/doc/partial_matches.html)), Python ([via third party regex module](https://pypi.org/project/regex/#:~:text=Added%20partial%20matches)) or Java (via [`hitEnd`](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#hitEnd--)), Javascript has no canonical / innate partial-matching for regular expressions.
+
+## Overview
+
+This library transforms regular expressions to best-effort support **partial matching**, allowing you to test if an incomplete string could potentially match the full pattern. This is particularly useful for real-time input validation, autocomplete systems, progressive form validation, stream chunk matching, etc.
+
+**Based on an algorithm created by [Lucas Trzesniewski](https://github.com/ltrzesniewski)**, re-created for NPM via ISC license, with permission.
+
+## Installation
+
+```bash
+npm install regex-partial-match
+```
+
+If your runtime doesn't support these features, attempting to use patterns with them will throw a `SyntaxError`.
+
+## Usage
+
+### Basic Usage
+
+```javascript
+import createPartialMatchRegex from "regex-partial-match";
+
+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
+```
+
+### Extending RegExp.prototype
+
+```javascript
+import "regex-partial-match/extend";
+
+const partial = /hello world/.createPartialMatchRegexRegex();
+
+partial.test("hel"); // true
+```
+
+## How It Works
+
+The library transforms a regular expression by wrapping each atomic element in a non-capturing group with an alternation to end-of-input (`$`):
+
+```javascript
+/abc/ → /(?:a|$)(?:b|$)(?:c|$)/
+```
+
+This allows the pattern to match prefixes of the original pattern, enabling validation of incomplete input.
+
+Since the library accepts only valid regular expressions [^1], this enables the algorithm to make lots of unguarded assumptions about the source of the expression.
+
+The library has been stress-tested with various regular expression features in isolation, and some in likely combination, but obviously its an unbounded test space, and syntactically valid regular expressions nevertheless support contradictory patterns e.g.
+
+- `/\b\B/` - impossible to match both a word boundary and a non-word boundary
+- `/$^/` - end cannot come before start
+- `x{2}?` - lazy quantifiers are mutually exclusive to fixed-length assertions
+
+Such combinations have not been tested.
+
+[^1]: To remain lightweight, no runtime type validation is applied, so non-typescript consumers will be reliant on underlying errors thrown, if used incorrectly.
+
+## Supported Features
+
+- 🔤 [Literal characters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Literal_character)
+- 📋 [Character classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_class) (`[abc]`, `[^abc]`, `[a-z]`)
+- 🔣 [Character escapes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_escape) (`\n`, `\t`, `\x61`, `\u0061`, `\u{1F600}`)
+- 🌐 [Unicode character class escape](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape) (`\p{Letter}`, `\P{Letter}`)
+- 🔢 [Quantifiers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Quantifier) (`*`, `+`, `?`, `{n}`, `{n,}`, `{n,m}`)
+- 🔀 [Disjunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Disjunction) (`a|b`)
+- 👥 [Groups](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Capturing_group) (capturing and non-capturing) (`(?:abc)`, `(abc)`, `(?<named>abc)`)
+- 👀 [Lookahead assertions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Lookahead_assertion) (`(?=...)`, `(?!...)`)
+- 👈 [Lookbehind assertions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Lookbehind_assertion) (`(?<=...)`, `(?<!...)`)
+- ⚓ [Anchors](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Input_boundary_assertion) (`^`, `$`)
+- 🏴 [Flags](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/flags): `g`, `i`, `m`, `s`, `u`, `d`, `y` (See caveats for `y`)
+
+## Unsupported Features
+
+The following regex features are **not currently supported**:
+
+- ⚠️ [Backreferences](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Backreference) (`\1`, `\k<name>`) - Can be included, but can't partially match. See [caveats](#caveats).
+- ❌ [Unicode sets (`v` flag)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicodeSets) - ES2024+
+- ❌ [Modifiers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Modifier) (`(?ims:...)`, `(?-ims:...)`) - ES2025+
+
+## Browser Compatibility
+
+The library is compiled to **ES5** for broad compatibility with older browsers and JavaScript environments. However, certain regular expression features naturally require ES2015+ support:
+
+- [**Unicode escapes**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape) (`\u{...}`) - ES2015+
+- [**Unicode property escapes**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape) (`\p{...}`, `\P{...}`) - ES2018+
+- [**Lookbehind assertions**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Lookbehind_assertion) (`(?<=...)`, `(?<!...)`) - ES2018+
+- [**Named capturing groups**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Named_capturing_group) (`(?<name>...)`) - ES2018+
+- [**`s` (dotAll) flag**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/dotAll) - ES2018+
+- [**`d` (hasIndices) flag**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/hasIndices) - ES2022+
+
+## Caveats
+
+### Backreferences
+
+**Backreferences with variable-length captures cannot be partially matched** due to ambiguity in how the pattern should be matched. While simple fixed-length backreferences like `/(abc)\1/` could theoretically be transformed (if accepting that the group indexes would be polluted, compared to the original), to become `/(?:(a)|$)(?:(b)|$)(?:(c)|$)(?:\1|$)(?:\2|$)(?:\3|$)/` variable-length patterns break down.
+
+For example, with `/(\w+) \1/` (matches "hello hello"):
+
+- A naive transformation `/(?:(\w+)|$)(?:( )|$)(?:\1|$)/` creates ambiguity
+- For input "hello h", the regex can match in multiple ways:
+  - Capture group 1 as "hello", skip the space with `$`, skip `\1` with `$` ✓
+  - Capture group 1 as "h", skip the space with `$`, match `\1` as "h" ✓ (at position 6)
+- The engine chooses the second interpretation, matching just "h" instead of recognizing "hello h" as a partial match
+
+The core issue: **the regex engine cannot determine which part of the input should be captured vs. which part should match the backreference** when dealing with variable-length patterns and incomplete input. Fixed-length patterns like `/(abc)\1/` avoid this ambiguity since each character position has a clear role.
+
+### Surrogate Pair Matching
+
+In unicode-aware mode (`u` flag), **only whole astral characters are supported**. Partial matching of individual surrogate pairs is not supported. For example, `/😀/u` will match the complete emoji character, but not the first surrogate pair in isolation. Hence, if partially matching a byte stream, be sure to pipe via a [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder) first.
+
+### [Sticky](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) Flag (`y`)
+
+The **sticky flag may not behave as expected** in partial matching scenarios. The sticky flag requires matches to start at `lastIndex`, but a partial match failure resets `lastIndex` to 0. This means subsequent attempts cannot "continue" from where the previous match failed, making progressive character-by-character validation problematic.
+
+**Example:**
+
+```javascript
+const pattern = /hello/y;
+const partial = createPartialMatchRegex(pattern);
+
+pattern.lastIndex = 0;
+partial.test("h"); // succeeds, lastIndex advances
+partial.test("he"); // succeeds, but lastIndex was reset by previous test
+// Cannot reliably continue partial matching with sticky flag
+```
+
+**Recommendation:** Avoid using the `y` flag with partial matching unless you fully understand the implications.
+
+### Global Flag (`g`)
+
+The **global flag is preserved** but may not be necessary for partial matching use cases. The `g` flag affects behavior when using `.exec()` repeatedly to find all matches, but partial matching typically validates a single prefix at a time.
+
+The global flag does not cause issues like the sticky flag, as partial patterns naturally match from the beginning of the input. However, if you're using `lastIndex` to track position, be aware that failed matches will reset it to 0.
+
+## Examples
+
+### Form Validation
+
+```javascript
+import createPartialMatchRegex from "regex-partial-match";
+
+const emailPattern = /^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$/i;
+const partial = createPartialMatchRegex(emailPattern);
+
+function validateEmail(input) {
+  return partial.test(input) ? "valid" : "invalid";
+}
+
+validateEmail("user"); // 'valid' - could become valid
+validateEmail("user@"); // 'valid' - could become valid
+validateEmail("user@example"); // 'valid' - could become valid
+validateEmail("user@example.com"); // 'valid' - complete match
+validateEmail("@@invalid"); // 'invalid' - cannot match
+```
+
+### Autocomplete
+
+```javascript
+const commandPattern = /^(help|quit|save|load)/;
+const partial = createPartialMatchRegex(commandPattern);
+
+function getSuggestions(input) {
+  return partial.test(input) ? "valid prefix" : "no suggestions";
+}
+
+getSuggestions("h"); // 'valid prefix'
+getSuggestions("hel"); // 'valid prefix'
+getSuggestions("help"); // 'valid prefix'
+getSuggestions("xyz"); // 'no suggestions'
+```
+
+### Stream Processing
+
+```javascript
+import createPartialMatchRegex from "regex-partial-match";
+
+// Process streaming data with pattern matching at chunk boundaries
+const pattern = /\{"[^"]+":"[^"]+"\}/; // Match JSON objects
+const partial = createPartialMatchRegex(pattern);
+let buffer = "";
+
+function processChunk(chunk) {
+  buffer += chunk;
+  const matches = [];
+
+  // Extract complete matches
+  let match;
+  while ((match = pattern.exec(buffer))) {
+    matches.push(match[0]);
+    buffer = buffer.slice(match.index + match[0].length);
+  }
+
+  // Discard buffer if it cannot possibly complete
+  if (buffer && !partial.test(buffer)) {
+    buffer = "";
+  }
+
+  return matches;
+}
+
+processChunk('{"na'); // [] - partial, buffer: '{"na'
+processChunk('me":"Jo'); // [] - partial, buffer: '{"name":"Jo'
+processChunk('hn"}{"age":'); // ['{"name":"John"}'] - buffer: '{"age":'
+processChunk("25}"); // ['{"age":25}'] - buffer: ''
+processChunk("invalid{"); // [] - discarded, buffer: ''
+```
+
+Useful for parsing log files, network streams, or any chunked data where records may be split across boundaries.
+
+## API
+
+### `createPartialMatchRegex(regex: RegExp): RegExp`
+
+Transforms a regular expression to support partial matching.
+
+Available via the default entry point of the package.
+
+**Parameters:**
+
+- `regex` - The regular expression to transform
+
+**Returns:**
+
+- A new `RegExp` that matches partial strings
+
+### `RegExp.prototype.toPartialMatchRegex(): RegExp`
+
+When using `import 'regex-partial-match/extend'`, this method is added to `RegExp.prototype`.
+
+**Returns:**
+
+- A new `RegExp` that matches partial strings, created from the `RegExp` instance the method was called on.
+
+## License
+
+ISC License - see [LICENSE](./LICENSE) file for details.
+
+## Credits
+
+Algorithm created by [Lucas Trzesniewski](https://github.com/ltrzesniewski).
+
+## Contributing
+
+Contributions are welcome! Please open an issue or pull request on [GitHub](https://github.com/TomStrepsil/regex-partial-match).
+
+## Related packages
+
+- [`incr-regex-package`](https://www.npmjs.com/package/incr-regex-package)
+  - Incremental regex matcher
+- [`dfa`](https://github.com/foliojs/dfa)
+  - Compiles a regular expression like syntax to fast deterministic finite automata, which could be used to partial match?
+- [`refa`](https://github.com/RunDevelopment/refa)
+  - Can [convert regular expressions to an Abstract Syntax Tree](https://rundevelopment.github.io/refa/docs/latest/classes/JS.Parser.html), which might afford partial-match capability?

package/lib/extend.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    interface RegExp {
+        toPartialMatchRegex(): RegExp;
+    }
+}
+export {};

package/lib/extend.js

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

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+declare const createPartialMatchRegex: (regex: RegExp) => RegExp;
+export default createPartialMatchRegex;

package/lib/index.js

@@ -0,0 +1,133 @@
+var characterClassGlobalRegex = /\[(?:\\.|.)*?\]/g;
+var occurrencesRegex = /\{\d+,?\d*\}/g;
+var createPartialMatchRegex = function (regex) {
+    var source = regex.source;
+    var i = 0;
+    function extractSubstring(length) {
+        return source.substring(i, (i += length));
+    }
+    function process() {
+        var result = "";
+        function appendOptional(length) {
+            result += "(?:" + extractSubstring(length) + "|$)";
+        }
+        function appendRaw(length) {
+            result += extractSubstring(length);
+        }
+        while (i < source.length) {
+            switch (source[i]) {
+                case "\\":
+                    switch (source[i + 1]) {
+                        case "c":
+                            appendOptional(3);
+                            break;
+                        case "k":
+                            appendOptional(source.indexOf(">", i) - i + 1);
+                            break;
+                        case "u":
+                            if (regex.unicode && source[i + 2] === "{") {
+                                appendOptional(source.indexOf("}", i) - i + 1);
+                            }
+                            else {
+                                appendOptional(6);
+                            }
+                            break;
+                        case "p":
+                        case "P":
+                            if (regex.unicode) {
+                                appendOptional(source.indexOf("}", i) - i + 1);
+                            }
+                            else {
+                                appendOptional(2);
+                            }
+                            break;
+                        case "x":
+                            appendOptional(4);
+                            break;
+                        default:
+                            appendOptional(2);
+                            break;
+                    }
+                    break;
+                case "[": {
+                    characterClassGlobalRegex.lastIndex = i;
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- must match, since otherwise an invalid regex
+                    var match = characterClassGlobalRegex.exec(source)[0];
+                    appendOptional(match.length);
+                    break;
+                }
+                case "|":
+                case "^":
+                case "*":
+                case "+":
+                case "?":
+                case "$":
+                    appendRaw(1);
+                    break;
+                case "{": {
+                    occurrencesRegex.lastIndex = i;
+                    var regExpExecArray = occurrencesRegex.exec(source);
+                    if (regExpExecArray) {
+                        appendRaw(regExpExecArray[0].length);
+                    }
+                    else {
+                        appendOptional(1);
+                    }
+                    break;
+                }
+                case "(":
+                    if (source[i + 1] == "?") {
+                        switch (source[i + 2]) {
+                            case ":":
+                                result += "(?:";
+                                i += 3;
+                                result += process() + "|$)";
+                                break;
+                            case "=":
+                                result += "(?=";
+                                i += 3;
+                                result += process() + ")";
+                                break;
+                            case "!": {
+                                var temp = i;
+                                i += 3;
+                                process();
+                                result += source.substring(temp, i);
+                                break;
+                            }
+                            case "<":
+                                switch (source[i + 3]) {
+                                    case "=":
+                                    case "!": {
+                                        var temp = i;
+                                        i += 4;
+                                        process();
+                                        result += source.substring(temp, i);
+                                        break;
+                                    }
+                                    default:
+                                        appendRaw(source.indexOf(">", i) - i + 1);
+                                        result += process() + "|$)";
+                                        break;
+                                }
+                                break;
+                        }
+                    }
+                    else {
+                        appendRaw(1);
+                        result += process() + "|$)";
+                    }
+                    break;
+                case ")":
+                    ++i;
+                    return result;
+                default:
+                    appendOptional(1);
+                    break;
+            }
+        }
+        return result;
+    }
+    return new RegExp(process(), regex.flags);
+};
+export default createPartialMatchRegex;

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "regex-partial-match",
+  "version": "0.1.0",
+  "description": "A regular expression transform for partial matching",
+  "engines": {
+    "node": ">=23"
+  },
+  "keywords": [
+    "regexp",
+    "regular expressions",
+    "partial matcher"
+  ],
+  "license": "ISC",
+  "author": {
+    "name": "Tom Pereira",
+    "url": "https://github.com/TomStrepsil"
+  },
+  "bugs": {
+    "url": "https://github.com/TomStrepsil/regex-partial-match/issues"
+  },
+  "homepage": "https://github.com/TomStrepsil/regex-partial-match#readme",
+  "contributors": [
+    {
+      "name": "Lucas Trzesniewski",
+      "url": "https://github.com/ltrzesniewski"
+    }
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "import": "./lib/index.js",
+      "types": "./lib/index.d.ts"
+    },
+    "./extend": {
+      "import": "./lib/extend.js",
+      "types": "./lib/extend.d.ts"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TomStrepsil/regex-partial-match.git"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prepare": "simple-git-hooks",
+    "prepublishOnly": "tsc -p tsconfig.build.json",
+    "test": "vitest run --config ./test/vitest.config.ts",
+    "test:watch": "vitest --config ./test/vitest.config.ts"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "node_modules/.bin/lint-staged"
+  },
+  "lint-staged": {
+    "*.{ts,js}": [
+      "npm run lint:fix"
+    ]
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "eslint": "^9.17.0",
+    "jiti": "^2.6.1",
+    "lint-staged": "^15.2.11",
+    "simple-git-hooks": "^2.12.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.18.1",
+    "vitest": "^4.0.15"
+  }
+}