regex-partial-match 0.1.6 → 0.1.9

package/README.md

@@ -101,19 +101,53 @@ The library is compiled to **ES5** for broad compatibility with older browsers a
 
 ## Caveats
 
+### [`.test()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test) behaviour and non-matching results from [`.exec()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) and [`.match()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match)
+
+The library produces an expression that always matches an empty string, at the end of the input.
+
+Hence:
+
+```js
+/x/.test("a") === false; /* what you'd expect */
+/(?:x|$)/.test("a") === true; /* what's produced by the library */
+```
+
+To mitigate, a start boundary anchor can prevent anything _but_ the empty string matching:
+
+```js
+/^(?:x|$)/.test("") === true;
+/^(?:x|$)/.test("a") === false;
+/^(?:x|$)/.test("x") === true;
+```
+
+On this basis, `.test()` should be used with caution, and a match of an empty string at the end of the input should instead be considered "no match".
+
+i.e.
+
+```js
+/(?:x|$)/.exec("a"); // ['', index: 1, input: "a", groups: undefined];
+"a".match(/(?:x|$)/); // ['', index: 1, input: "a", groups: undefined];
+```
+
+Since the library produces a native `RegExp` object, no attempt to proxy / translate this output to `null` has been attempted, but a helper could be produced in future, for clarity.
+
 ### 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.
+**Backreferences cannot be partially matched because they are atomic.** A backreference like `\1` must match the complete captured text or fail entirely, and cannot be split into individual characters for partial matching like regular atoms can.
+
+Fixed-length patterns like `/(abc)\1/` could theoretically become `/(?:(a)|$)(?:(b)|$)(?:(c)|$)(?:\1|$)(?:\2|$)(?:\3|$)/` (accepting polluted capture indexes as a side-effect), but this doesn't work for variable-length captures.
+
+### Positive Lookbehinds
+
+Whilst forming a match, a positive lookbehind must match in entirety, for the pattern to match. This is inherent in the concept of non-matching groups, since they are not match-worthy themselves, but just qualify matching atoms.
 
-For example, with `/(\w+) \1/` (matches "hello hello"):
+e.g.
 
-- 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
+```js
+/(?<=foo)bar/;
+```
 
-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.
+"f" through "foo" is not a match, but "foob" is.
 
 ### Surrogate Pair Matching
 
@@ -148,8 +182,6 @@ The global flag does not cause issues like the sticky flag, as partial patterns
 ### 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);
 
@@ -183,8 +215,6 @@ 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);
@@ -254,11 +284,13 @@ Algorithm created by [Lucas Trzesniewski](https://github.com/ltrzesniewski).
 
 Contributions are welcome! Please open an issue or pull request on [GitHub](https://github.com/TomStrepsil/regex-partial-match).
 
-## Related packages
+## Related projects
 
-- [`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?
+| Project                                                                    | Description                                                                                                                                                                          |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`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? |
+| [`@eslint-community/regexpp`](https://github.com/eslint-community/regexpp) | A regular expression parser for ECMAScript with AST generation and visitor implementation                                                                                            |
+| [`Regex+`](https://www.npmjs.com/package/regex)                            | template literal, transforming native regular expressions                                                                                                                            |
+| [`Awesome Regex`](https://github.com/slevithan/awesome-regex)              | Curated list of tools, tutorials, libraries, and other resources, covering all major regex flavours                                                                                  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "regex-partial-match",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "description": "A regular expression transform for partial matching",
   "engines": {
     "node": ">=23"
@@ -66,6 +66,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
+    "@eslint/markdown": "^7.5.1",
     "eslint": "^9.17.0",
     "jiti": "^2.6.1",
     "lint-staged": "^15.2.11",