regex-partial-match 0.1.7 → 0.1.10

package/README.md

@@ -77,7 +77,8 @@ Such combinations have not been tested.
 - 👥 [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) (`^`, `$`)
+- ⚓ [Input Boundaries](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Input_boundary_assertion) (`^`, `$`)
+- 🆒 [Word Boundaries](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Word_boundary_assertion) (`\b`, `\B`)
 - 🏴 [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
@@ -85,8 +86,8 @@ Such combinations have not been tested.
 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+
+- ❌ [Unicode sets (`v` flag)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicodeSets) - ES2024+. See [issue](https://github.com/TomStrepsil/regex-partial-match/issues/1).
+- ❌ [Modifiers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Modifier) (`(?ims:...)`, `(?-ims:...)`) - ES2025+. See [issue](https://github.com/TomStrepsil/regex-partial-match/issues/2).
 
 ## Browser Compatibility
 
@@ -101,15 +102,57 @@ 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.  Feasibly, this is the start of a new partial match.
+
+Hence:
+
+```js
+/x/.test("a") === false; /* untransformed regex */
+/(?:x|$)/.test("a") === true; /* what's produced by the library */
+```
+
+To mitigate, a start boundary anchor can prevent anything _but_ an empty string matching:
+
+```js
+/^(?:x|$)/.test("") === true;
+/^(?:x|$)/.test("x") === true;
+/^(?:x|$)/.test("a") === false;
+```
+
+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", if validating that which came before.
+
+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. See [issue](https://github.com/TomStrepsil/regex-partial-match/issues/14).
+
 ### Backreferences
 
 **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.
+
+e.g.
+
+```js
+/(?<=foo)bar/;
+```
+
+"f" through "foo" is not a match, but "foob" is.
+
 ### 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.
+In [unicode-aware mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicode) (`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`)
 
@@ -140,8 +183,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);
 
@@ -175,8 +216,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);
@@ -246,11 +285,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/lib/extend.d.ts

@@ -1,5 +1,34 @@
 declare global {
     interface RegExp {
+        /**
+         * Transforms this regular expression to support partial matching.
+         *
+         * This method 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.
+         *
+         * @returns A new RegExp that matches partial strings of the original pattern
+         *
+         * @example
+         * ```typescript
+         * import 'regex-partial-match/extend';
+         *
+         * const partial = /hello world/.toPartialMatchRegex();
+         *
+         * 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}
+         */
         toPartialMatchRegex(): RegExp;
     }
 }

package/lib/index.d.ts

@@ -1,2 +1,31 @@
 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;

package/lib/index.js

@@ -130,4 +130,33 @@ var createPartialMatchRegex = function (regex) {
     }
     return new RegExp(process(), regex.flags);
 };
+/**
+ * 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "regex-partial-match",
-  "version": "0.1.7",
+  "version": "0.1.10",
   "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",