regex-partial-match 1.2.0 → 2.0.0

package/README.md

@@ -10,7 +10,7 @@ Unlike C/C++ (via [PCRE/PCRE2](https://www.pcre.org/original/doc/html/pcrepartia
 
 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.
 
-As a side effect of the parse this requires, each `PartialMatchRegExp` also exposes a [`features`](#partialmatchregexpprototypefeatures-readonlysetregexfeature) set naming the syntactic constructs its pattern uses — useful for consumers that need to reason about a pattern without writing their own regex parser.  For many features, a simple search in the [source](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/source) would be insufficient.
+As a side effect of the parse this requires, [`features()`](#features) names the syntactic constructs a `PartialMatchRegExp`'s pattern uses — useful for consumers that need to reason about a pattern without writing their own regex parser.  For many features, a simple search in the [source](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/source) would be insufficient.
 
 **Based on an algorithm created by [Lucas Trzesniewski](https://github.com/ltrzesniewski)**, re-created for NPM via ISC license, with permission.
 
@@ -46,35 +46,102 @@ const partial = /^hello world/.toPartialMatchRegex();
 partial.test("hel"); // true
 ```
 
-## ⚙️ How It Works
+### Telling a settled match from one still reading
 
-The library transforms a regular expression by wrapping each [atomic element](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions#atoms) in a [non-capturing group](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Non-capturing_group) with a [disjunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Disjunction) to a true-end-of-input sentinel (`$(?![\s\S])`[^1]):
+`test()` and `exec()` answer "could this match?", which is `true` for a prefix and for a complete match alike. [`hitEnd()`](#hitend) reports whether the engine reached the end of the input while producing the match, so more input could still change it [^1]. Testing the original pattern instead doesn't answer that [^2]. Together they give progressive validation its three states:
 
 ```javascript
-/abc/ → /(?:a|$(?![\s\S]))(?:b|$(?![\s\S]))(?:c|$(?![\s\S]))/
+import PartialMatchRegExp, { hitEnd } from "regex-partial-match";
+
+const partial = new PartialMatchRegExp(/^\d{4}-\d{2}-\d{2}/);
+
+function state(input) {
+  const match = partial.exec(input);
+
+  if (match === null) return "invalid";
+  return hitEnd(partial, match) ? "incomplete" : "complete";
+}
+
+state("20xx"); // 'invalid'    - reject
+state("2024"); // 'incomplete' - no error, keep typing
+state("2024-06"); // 'incomplete' - no error, keep typing
+state("2024-06-15"); // 'complete'   - accept, enable submit
 ```
 
-This allows the pattern to match prefixes of the original pattern, enabling validation of incomplete input.
+> [!NOTE]
+> `hitEnd()` answers "could more input change this match?", not "is this text a match?". `/hello \w+/` matches `"hello world"` in full, and `hitEnd()` is still `true`: `\w+` read the end of the input looking for more. For an exact-length pattern like the date above the two questions coincide, which is what makes the three states work; a validator for an open-ended pattern that wants "valid so far" should test the original pattern as well.
+
+Upgrading from 1.x, where this was `isComplete()`? See the [migration guide](./codemods/transforms/v1-v2/README.md).
 
-Since the library accepts only valid regular expressions [^2], this enables the algorithm to make lots of unguarded assumptions about the source of the expression.
+[^1]: 
+    Mimicking JDK's [`Matcher.hitEnd()`](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#hitEnd--)
 
-The library has been stress-tested with various regular expression features in isolation, and some in likely combination, but obviously it's an unbounded test space, and syntactically valid regular expressions nevertheless support contradictory patterns e.g.
+[^2]:
+    Testing the original, untransformed pattern looks like it should answer this — "did the input fully satisfy the original pattern?" — but it asks a different question: whether the original matches *at all* here, not whether *this* match reached the end of the input on its way. The two agree almost always, but a read of the end inside a zero-width assertion can make both return an identical result by different paths. See [Why the question can't be answered from the outside](https://github.com/TomStrepsil/regex-partial-match/blob/main/docs/how-it-works.md#why-the-question-cant-be-answered-from-the-outside) for the case where they diverge.
 
-- `/\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
+### A note on Tree-Shaking
 
-Such combinations have not been tested.
+If your environment doesn't tree-shake (e.g. Deno, or unbundled Node), the default entry loads `hitEnd` and `features` with the class. Import each from its own subpath instead, and only the ones you use:
 
-> [!NOTE]
-> See [Partial Match Parity](/docs/partial-match-parity.md) for full details on how the library compares to reference implementations
+```javascript
+import PartialMatchRegExp from "regex-partial-match/partialMatchRegExp";
+import hitEnd from "regex-partial-match/hitEnd";
+import features from "regex-partial-match/features";
+```
+
+[`hitEnd`](#hitend) and [`features`](#features) accept an instance of any `PartialMatchRegExp` class, including those from [`regex-partial-match/core`](#the-lean-entry-regex-partial-matchcore).
+
+### The lean entry: `regex-partial-match/core`
+
+`regex-partial-match/core` exports a `PartialMatchRegExp` without two sets of rules, so a bundle that doesn't need them can leave them out. Each set is a module you bind back with `withModules`:
 
-### Patterns with backreferences
+| Module | Import | Supplies |
+|---|---|---|
+| `carets` | `regex-partial-match/modules/carets` | the rules for a `^` under the `m` flag that has something before it, and for a `^` in a group or positive lookahead |
+| `backreferences` | `regex-partial-match/modules/backreferences` | matching a backreference against the text its group captured |
+
+Both are also named exports of `regex-partial-match/modules`.
+
+```javascript
+import PartialMatchRegExp, { withModules } from "regex-partial-match/core";
+import carets from "regex-partial-match/modules/carets";
+import backreferences from "regex-partial-match/modules/backreferences";
+
+new PartialMatchRegExp(/^\d{4}-\d{2}/).test("20"); // true
+
+const WithBoth = withModules(carets, backreferences);
+new WithBoth(/(a|b)\1/).test("a"); // true
+```
+
+`withModules` returns a `PartialMatchRegExp` class extending `RegExp`, and the same set of modules in any order returns the same class: `withModules()` is the `core` class, and `withModules(carets, backreferences)` is the default `PartialMatchRegExp`, so `instanceof` holds between them. [`hitEnd()`](#hitend) and [`features()`](#features) accept instances of any of these classes.
+
+A module's type is `Module`, exported from both `regex-partial-match/core` and `regex-partial-match/modules`, for annotating a list of modules: `const modules: Module[] = [carets, backreferences]`. It is opaque, so what a module holds is not part of the API, and `withModules` throws a `TypeError` for anything that isn't a module.
+
+#### Choosing an entry point
+
+If your patterns aren't known when you build, because they come from users or configuration, use `regex-partial-match`. If they are fixed, use `core`: construct each pattern once, and bind the modules construction asks for.
+
+| Error when constructed | Bind |
+|---|---|
+| `TypeError: Needs the carets module` | `carets` |
+| `TypeError: Needs the backreferences module` | `backreferences` |
+| `TypeError: Needs the carets and backreferences modules` | both |
+
+The error names every module the pattern needs, and none that is already bound.
+
+**Without `carets`**, a `^` is accepted outside every group and positive lookahead and, under the `m` flag, only at the start of the pattern or of a top-level alternative, with nothing before it but `^`, `$`, `\b`, `\B`, a negative lookahead or a lookbehind: `/^a|^b/m` and `/\b^a/m` compile. A `^` inside a lookbehind or negative lookahead is always accepted, since those are kept as written: `/(?<=^)a/` compiles. Any other `^` throws `TypeError: Needs the carets module` when constructed, as `/x^a/m` and `/(?=a)^a/m` do. So does a `^` inside a group or positive lookahead, even without `m`, as in `/(^a|^b)/` and `/(?m:^a)/`, since the rule that moves such a caret in front of its group is in the carets module. The rule stays there to keep `core` small. An unquantified group whose every alternative starts with `^` matches the same with the caret written once in front of it, and `core` accepts `/^(a|b)/` where it refuses `/(^a|^b)/`. Every pattern `core` accepts is transformed exactly as by the default class.
+
+**Without `backreferences`**, a pattern whose backreference must be matched at run time throws `TypeError: Needs the backreferences module` when constructed, as `/(a)\1/` does. An escape that resolves without it still compiles: in `/x\8y/` there is no group 8, so `\8` is the literal `8`.
+
+## ⚙️ How It Works
 
-Backreferences cannot be handled by the `|$(?![\s\S])` transform alone because they are atomic — `\1` must match the entire captured string or fail, and its length is only known at runtime. `PartialMatchRegExp` first tries a full match natively, but that native result only wins outright if nothing earlier in the input could still be a viable partial — a cheap bound check settles that without needing to resolve the backreference's actual value, so the common case (no earlier partial exists) stays fast. Otherwise it runs a "capture scan": a variant of the pattern with each backreference swapped for a lazy `(?:[\s\S]*?)` wildcard, so the group it depends on can still capture against a partial input — matching anything, or nothing at all, without needing to already know the backreference's value. 
+The library wraps each [atomic element](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions#atoms) in a non-capturing group with a disjunction to the true end of the input, so the pattern matches any prefix of what the original would match:
 
-Whatever that scan captures (or leaves `undefined`, if the group hasn't been reached yet) is then used to build a fresh partial-matching regex for this specific input, expanding the backreference character-by-character from the captured value with the same per-atom transform as the rest of the pattern. See [docs/backreferences.md](./docs/backreferences.md) for the full algorithm, including the prefer-longer post-processing that preserves correct captures for groups inside quantifiers.
+```javascript
+/abc/ → /(?:a|$(?![\s\S]))(?:b|$(?![\s\S]))(?:c|$(?![\s\S]))/
+```
 
+See [How It Works](./docs/how-it-works.md) for the full transform, where it over-accepts, how `^` is handled in groups and under the `m` flag, and how backreferences are matched.
 
 ## ✅ Supported Features
 
@@ -87,19 +154,19 @@ Whatever that scan captures (or leaves `undefined`, if the group hasn't been rea
 - 🔢 [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)`)
-- 🔙 [Backreferences](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Backreference) (`\1`, `\k<name>`) (See [caveats](#backreferences) for known limitations)
+- 🔙 [Backreferences](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Backreference) (`\1`, `\k<name>`) (See [caveats](./docs/caveats.md#backreferences) for known limitations)
 - 👉 [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) (`(?<=...)`, `(?<!...)`)
 - ⚓ [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](#sticky-flag-y) for `y`)
+- 🏴 [Flags](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/flags): `g`, `i`, `m`, `s`, `u`, `d`, `y` (See [caveats](./docs/caveats.md#sticky-flag-y) for `y`)
 - 🎚️ [Modifiers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Modifier) (`(?ims:...)`, `(?-ims:...)`, `(?im-s:...)`)
 
 ## 🚫 Unsupported Features
 
 The following regex features are **not currently supported**:
 
-- ⚠️ [Character class substrings](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_class#matching_strings) (`\q{abc}`) - When used independently, rather than to modify, can be included, but can't partially match. See [caveats](#caveats).
+- ⚠️ [Character class substrings](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_class#matching_strings) (`\q{abc}`) - When used independently, rather than to modify, can be included, but can't partially match. See [caveats](./docs/caveats.md#string-properties).
 
 ## 🌐 Browser Compatibility
 
@@ -113,154 +180,20 @@ The library is compiled to **ES2015** (ECMAScript 6). Certain regular expression
 - [**`v` (unicodeSets) 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:...)`, `(?i-ms:...)`) - ES2025+
 
-## ⚠️ 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)
-
-For unanchored patterns (no `^` and not using the `y` flag), the library produces an expression that always matches an empty string at the true end of the input — see [How It Works](#how-it-works). Feasibly, this is the start of a new partial match.
-
-Hence:
-
-```js
-/x/.test("a") === false; /* untransformed regex */
-/(?:x|$(?![\s\S]))/.test("a") === true; /* new PartialMatchRegExp(/x/), internally */
-```
-
-To mitigate, a start anchor (`^`) can prevent the engine from scanning forward to match the empty-string fallback at the end of the input:
-
-```js
-/* new PartialMatchRegExp(/^x/) matches as if it were /^(?:x|$(?![\s\S]))/ */
-/^(?:x|$(?![\s\S]))/.test("") === true;
-/^(?:x|$(?![\s\S]))/.test("x") === true;
-/^(?:x|$(?![\s\S]))/.test("a") === false;
-```
-
-> [!CAUTION]
-> In [multiline mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/multiline), `^` still matches at the start of the string and immediately after each `\n`, so the transformed regex can attempt the empty-string fallback at the start of any line — but, since the fallback requires strict end-of-input, it only succeeds if that line start is *also* genuinely where the input ends:
->
-> ```js
-> /^(?:x|$(?![\s\S]))/m.test("x") === true;
-> /^(?:x|$(?![\s\S]))/m.test("a\n") === true;  /* '^' matches after '\n', and input truly ends there */
-> /^(?:x|$(?![\s\S]))/m.test("a\nb") === false; /* '^' matches after '\n', but "b" remains — not genuine end-of-input */
-> ```
-
-The [`y` flag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) prevents matching ahead from the [`lastIndex`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) (defaulting to `0` for a new `RegExp`):
-
-```js
-/(?:x|$(?![\s\S]))/y.test("x") === true;
-/(?:x|$(?![\s\S]))/y.test("a") === false;
-```
-
-> [!CAUTION]
-> See [caveats](#sticky-flag-y) re: resetting `lastIndex` when incrementally matching
-
-On this basis, `.test()` should be used with caution, and a match of an empty string at the true end of the input should instead be considered "no match", if validating that which came before.
-
-e.g.
-
-```js
-/(?:x|$(?![\s\S]))/.exec("a"); // ['', index: 1, input: "a", groups: undefined];
-"a".match(/(?:x|$(?![\s\S]))/); // ['', index: 1, input: "a", groups: undefined];
-```
-
-> [!NOTE]
-> A more ergonomic `test()` / `exec()` output [was explored](https://github.com/TomStrepsil/regex-partial-match/pull/51), but proved a complex problem space.
-
-### Backreferences
-
-`PartialMatchRegExp` supports partial matching of backreferences (`\1`, `\k<name>`) — see [Patterns with backreferences](#patterns-with-backreferences) above and [docs/backreferences.md](./docs/backreferences.md) for the algorithm. A backreference is inherently atomic — `\1` must match the complete captured text or fail — but the library resolves what each group captured from a partial input and expands the backreference into per-character partial form so matching can still proceed character-by-character in the common case.
-
-The following cases remain atomic (full native value or exactly at true end of input, no mid-value partial matching):
-
-- **Backreferences inside lookbehinds and negative lookarounds.** These are verbatim contexts — the value a lookbehind or negative lookahead requires must be fully present or fully absent, so there's no partial-prefix position to expand into.
-- **`\k<name>` with no named capturing groups in the pattern.** [Annex B](https://tc39.es/ecma262/#sec-regular-expressions-patterns) tolerates this as the literal characters `k<a>`, but it's still treated as if it were a named backreference and matched atomically — `"k"` and `"k<"` will not partially match. A `\k` not immediately followed by a well-formed `<name>` reference is treated as the literal `k` and partially matches as usual.
-- **A backreference whose captured value can't be determined from a partial input.** This only affects the backreference site itself; it's strictly better than rejecting the input outright, and never accepts anything unsound.
-
-#### Prefix-ambiguous top-level alternation
-
-When a pattern uses top-level alternation where one branch is a strict prefix of another (e.g. `^(ab)\1|^(abc)\2`), the internal capture scan may select the shorter branch — because it uses `(?:[\s\S]*?)` which accepts zero characters — causing the final partial regex to fail for inputs that are valid prefixes of the longer branch. In such cases `exec` returns `null` even though the input is a valid partial match:
-
-```javascript
-const partial = new PartialMatchRegExp(/^(ab)\1|^(abc)\2/);
-
-partial.test("abca"); // false — but "abca" is a valid prefix of "abcabc" via the second branch
-```
-
-> [!TIP]
-> If alternate branches share a prefix, list the longer one first. The capture scan tries branches in order and stops at the first that accepts the partial input, so putting the longer branch first ensures it's the one selected:
->
-> ```javascript
-> const partial = new PartialMatchRegExp(/^(abc)\2|^(ab)\1/);
->
-> partial.test("abca"); // true
-> ```
-
-See [docs/backreferences.md](./docs/backreferences.md) for why this happens (the internal capture scan resolving the wrong alternative first).
-
-[^1]: 
-    A bare `$` alone isn't sufficient here: under the `m` (multiline) flag — including one turned on locally via a `(?m:...)` [modifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Modifier) — `$` also matches immediately before *any* line terminator, not just the true end of input. That would let a `"\n"` the source pattern never allowed for be silently accepted as if the input had simply run out, e.g. `new PartialMatchRegExp(/^foobar/m)` would wrongly accept `"foo\nbaz"`. Appending `(?![\s\S])` narrows the disjunction down to strict end-of-input, regardless of multiline state.
-
-    See [chromium issue 536420076](https://issues.chromium.org/u/2/issues/536420076) for the underlying V8 bug that requires `$` to precede `(?![\s\S])` rather than using the lookahead alone.
-
-    A shorter option, `(?-m:$)` — disabling multiline locally so `$` means strict end-of-input on its own — also sidesteps the bug and saves a few bytes per atom. However, modifier groups are new enough that support isn't universal, and feature-detecting them would add a fallback branch the test suite can't exercise honestly, since every engine that can realistically be tested against already supports them.
-
-[^2]: 
-    To remain lightweight, no runtime type validation is applied, so non-TypeScript consumers will be reliant on underlying errors thrown if used incorrectly.
-
-### 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](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`)
-
-The sticky flag is fully supported for its intended use case: **scanning within a single fixed string**. Partial matches are found only at `lastIndex`; the engine does not scan forward, and `lastIndex` advances on success or resets to `0` on failure — exactly as native sticky regexes behave.
-
-```javascript
-import PartialMatchRegExp from "regex-partial-match";
-
-const partial = new PartialMatchRegExp(/hello/y);
-
-partial.lastIndex = 2;
-partial.test("xyhello"); // true  — partial match at position 2
-partial.test("xyworld"); // false — no match at position 2, no forward scan
-partial.lastIndex = 2;
-partial.test("xyhel"); // true  — partial prefix "hel" at position 2
-```
-
-**Limitation — progressive input validation:** Because a successful match advances `lastIndex`, testing a sequence of growing strings against the same instance does not work as expected:
-
-```javascript
-const partial = new PartialMatchRegExp(/hello/y);
-
-partial.test("h");   // true,  lastIndex → 1
-partial.test("he");  // false — sticky requires a match at position 1 of "he",
-                     //         but "e" is not a valid start of the pattern
-partial.test("hel"); // true (lastIndex was reset to 0 by the previous failure)
-```
-
-There is no way to distinguish "scanning forward in the same string" from "testing a new, longer string", so this cannot be fixed in code. For progressive input validation, use a regex **without** the `y` flag and always test against the full input so far.
-
-The `gy` flag combination is also fully supported: `exec()`/`test()` behave as sticky, while `match()`, `matchAll()`, `replace()`, and `replaceAll()` iterate via `exec()` as global — matching [the language specification](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky).
-
-### "String properties"
+Each of these applies only when the *original* pattern uses the feature — everything else, including construction, `exec()`, `test()` and [`hitEnd()`](#hitend), holds to the ES2015 floor.
 
-As with surrogate pair matching, grapheme clusters / string properties can only match atomically.
+## ⚠️ Caveats
 
-Hence, `[\p{RGI_Emoji_Flag_Sequence}]` will match `🇺🇳` as a whole, but not as the individual code points of which it's comprised.
+See [Caveats](./docs/caveats.md) for details, examples and workarounds.
 
-In [`v` mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicodeSets) expressions, where `[\q{abc}]` syntax is used in isolation (rather than its canonical use-case as a subtraction/intersection of another character class), this will also only match entirely or not at all. i.e. `abc` can match, but not partially.
+- [**`.test()` and empty matches at the end of the input**](./docs/caveats.md#test-behaviour-and-non-matching-results-from-exec-and-match): an unanchored pattern always matches `""` at the end of the input; anchor with `^`, or ask [`hitEnd()`](#hitend)
+- [**Backreferences**](./docs/caveats.md#backreferences): some backreferences stay atomic
+  - [Captures on a partial match](./docs/caveats.md#captures-on-a-partial-match)
+  - [Prefix-ambiguous top-level alternation](./docs/caveats.md#prefix-ambiguous-top-level-alternation)
+- [**Positive lookbehinds**](./docs/caveats.md#positive-lookbehinds): must match in their entirety
+- [**Surrogate pair matching**](./docs/caveats.md#surrogate-pair-matching): only whole astral characters match
+- [**Sticky flag (`y`)**](./docs/caveats.md#sticky-flag-y): not suited to progressive input validation
+- [**"String properties"**](./docs/caveats.md#string-properties): match atomically
 
 ## 💡 Examples
 
@@ -341,11 +274,15 @@ Useful for parsing log files, network streams, or any chunked data where records
 
 ## 🔌 API
 
-### `new PartialMatchRegExp(pattern: RegExp | string, flags?: string)`
+### `new PartialMatchRegExp()`
+
+```typescript
+new PartialMatchRegExp(pattern: RegExp | string, flags?: string)
+```
 
-Extends `RegExp`. An instance behaves like a normal `RegExp` — `instanceof RegExp` is `true`, and `.test()`, `.exec()`, `.match()`, `.matchAll()`, `.replace()`, etc. all work as expected — but also matches any input string that is a valid prefix of the original pattern, in addition to full matches.
+Extends `RegExp`. An instance behaves like a normal `RegExp`; `instanceof RegExp` is `true`, and `.test()`, `.exec()`, `.match()`, `.matchAll()`, `.replace()` etc. all work as expected, but also matches any input string that is a valid prefix of the original pattern, in addition to full matches.
 
-Available via the default entry point of the package.
+Available via the default entry point of the package, or via `regex-partial-match/partialMatchRegExp`; see [A note on Tree-Shaking](#a-note-on-tree-shaking).
 
 **Parameters:**
 
@@ -356,7 +293,11 @@ Available via the default entry point of the package.
 
 - A `PartialMatchRegExp` instance that matches partial strings of the original pattern
 
-### `RegExp.prototype.toPartialMatchRegex(): PartialMatchRegExp`
+### `toPartialMatchRegex()`
+
+```typescript
+RegExp.prototype.toPartialMatchRegex(): PartialMatchRegExp
+```
 
 When using `import 'regex-partial-match/extend'`, this method is added to `RegExp.prototype`.
 
@@ -364,26 +305,76 @@ When using `import 'regex-partial-match/extend'`, this method is added to `RegEx
 
 - A new `PartialMatchRegExp` that matches partial strings, created from the `RegExp` instance the method was called on.
 
-### `PartialMatchRegExp.prototype.features: ReadonlySet<RegexFeature>`
+### `hitEnd()`
+
+```typescript
+hitEnd(partial: PartialMatchRegExp, match: RegExpExecArray): boolean
+```
+
+Reports whether the engine **reached the end of the input** while producing `match`, so that more input could change it — the contract of the JDK's [`Matcher.hitEnd()`](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#hitEnd--): when it returns `false`, no continuation of the input changes the match's index or text. `exec()` alone cannot say: it returns the same shape of array for `"h"`, `"hello"` and `"hello world"` against `/hello world/`.
+
+Available as a named export of the default entry point, `import { hitEnd } from 'regex-partial-match'`, or as the default export of `regex-partial-match/hitEnd`.
+
+**Parameters:**
+
+- `partial` - The `PartialMatchRegExp` instance that produced `match`
+- `match` - A match returned by `partial.exec()`
+
+**Returns:**
+
+- `true` when the match read the end of the input: an atom ran out of input and took one of the `|$(?![\s\S])` branches described in [How It Works](#how-it-works); a greedy quantifier stopped at the end because there was nothing left to read; or `$`, `\b` or `\B` held there. More input could extend the match, change which alternative wins, or invalidate it, and its captures are the closest available rather than final — see [Captures on a partial match](./docs/caveats.md#captures-on-a-partial-match).
+- `false` when every atom matched literally and nothing read past the last character consumed. No continuation of the input changes the match's index or text, and the captures are the ones the original pattern produces — except the two cases in [What it cannot see](#what-it-cannot-see) below, where a read of the end leaves no marker and `false` is reported despite it.
+
+```javascript
+import PartialMatchRegExp, { hitEnd } from "regex-partial-match";
+
+const partial = new PartialMatchRegExp(/hello world/);
+
+hitEnd(partial, partial.exec("hello")); // true  — ran out of input inside "world"
+hitEnd(partial, partial.exec("hello world!")); // false — settled short of the end
+hitEnd(partial, partial.exec("hello world")); // false — consumed the last character without reading past it
+
+const greedy = new PartialMatchRegExp(/hello \w+/);
+
+hitEnd(greedy, greedy.exec("hello world")); // true  — \w+ read the end looking for more
+```
+
+> [!NOTE]
+> Where the JDK is exact, `hitEnd()` is conservative in one place: a bounded greedy quantifier (`?`, `{n,m}`) fully taken at the end of the input reports `true`, although the engine attempted no further read there — on a *group* (`/(ab)?/` on `"ab"` is `true` here and `false` in Java), and the same way for an unequal-bound `{n,m}` directly on a single atom once it's saturated at its maximum (`/a{1,2}/` on `"aa"` is `true`, though no continuation can add a third `a`). Outside the two limits in [What it cannot see](#what-it-cannot-see), it is never wrong in the other direction.
 
-Building the partial-match regex requires walking the entire source pattern once. As a side effect of that same walk, each instance records which syntactic constructs its pattern actually uses, exposed as a `features` set — no separate scan of the source is performed to produce it.
+See [How It Works](./docs/how-it-works.md#why-the-question-cant-be-answered-from-the-outside) for why this can't be worked out from the match alone, and how `hitEnd()` records a read of the end.
+
+#### What it cannot see
+
+- **A read of the end inside a lookahead in an earlier iteration of a quantified group.** The probe's [markers](./docs/how-it-works.md#recording-a-read-of-the-end) are capturing groups, and [`RepeatMatcher`](https://tc39.es/ecma262/#sec-runtime-semantics-repeatmatcher-abstract-operation) resets a quantified group's captures at the start of every iteration. `/(?:a(?=bcd)|b)+/` on `"abc"` reads the end inside `(?=bcd)` in its first iteration, matches `b` in its second, and reports `false` — although `"abcx"` changes the match to `"b"` at index 1. Nothing placed inside the repeated atom survives the reset, so this is a limit of the marker approach rather than an oversight, and it is pinned by a test.
+- **A read of the end inside a raw lookaround.** Negative lookaheads and both lookbehinds are kept verbatim (see [Caveats](./docs/caveats.md)), so a read of the end inside them leaves no marker: `/^a(?!b)/` on `"a"` reports `false`, although `"ab"` invalidates the match. A scanner whose output must not depend on where its input was chunked should refuse or buffer patterns that use them.
+
+### `features()`
+
+```typescript
+features(partial: PartialMatchRegExp): ReadonlySet<RegexFeature>
+```
+
+Building the partial-match regex requires walking the entire source pattern, usually once. The [carets module](./docs/modules/carets.md) guesses from a cheap look at the source whether a pattern needs its rules, and when it guesses wrong the pattern is walked a second time with them. As a side effect of the walk that builds the regex, each instance records which syntactic constructs its pattern actually uses, and `features()` names them as a set — no separate scan of the source is performed to produce it. The set is built on the first call for an instance and the same set is returned after that.
+
+Available as a named export of the default entry point, `import { features } from 'regex-partial-match'`, or as the default export of `regex-partial-match/features`. It accepts an instance of any `PartialMatchRegExp` class, including those from [`regex-partial-match/core`](#the-lean-entry-regex-partial-matchcore).
 
 This is useful for consumers building on top of `PartialMatchRegExp` who need to reason about which constructs a *specific* pattern uses, without writing their own regex parser to find out. Two concrete cases:
 
-- **Flagging patterns likely to hit one of the [caveats](#caveats) documented above.** For example, a pattern combining `backreference` with `lookbehind`, `negativeLookahead`, or `negativeLookbehind` is a candidate for the [atomic-backreference caveat](#backreferences); one combining `backreference` with `disjunction` is a candidate for the [prefix-ambiguous top-level alternation caveat](#prefix-ambiguous-top-level-alternation). A consumer accepting user-supplied patterns can surface a warning instead of letting the edge case surprise someone later.
-- **Restricting which constructs a product surface allows.** e.g. a system that only wants to accept "simple" patterns (no lookaround, no backreferences) from untrusted input can check `features` against an allow-list and reject the rest, without needing to hand-roll that check against the raw pattern source.
-- **Deciding at construction time whether a pattern needs a careful path.** A capture nested inside a lookaround is decided by the assertion rather than by the consumed text, so its value can vary with how far the input has been seen. `features.has("lookaroundCapture")` isolates exactly those patterns, where `features.has("lookahead") && features.has("capturingGroup")` would also catch the ordinary `/(\w+)(?= END)/`.
+- **Flagging patterns likely to hit one of the [caveats](./docs/caveats.md).** For example, a pattern combining `backreference` with `lookbehind`, `negativeLookahead`, or `negativeLookbehind` is a candidate for the [atomic-backreference caveat](./docs/caveats.md#backreferences); one combining `backreference` with `disjunction` is a candidate for the [prefix-ambiguous top-level alternation caveat](./docs/caveats.md#prefix-ambiguous-top-level-alternation). A consumer accepting user-supplied patterns can surface a warning instead of letting the edge case surprise someone later.
+- **Restricting which constructs a product surface allows.** e.g. a system that only wants to accept "simple" patterns (no lookaround, no backreferences) from untrusted input can check `features()` against an allow-list and reject the rest, without needing to hand-roll that check against the raw pattern source.
+- **Deciding at construction time whether a pattern needs a careful path.** A capture nested inside a lookaround is decided by the assertion rather than by the consumed text, so its value can vary with how far the input has been seen. `features(partial).has("lookaroundCapture")` isolates exactly those patterns, where checking for both `lookahead` and `capturingGroup` would also catch the ordinary `/(\w+)(?= END)/`.
 
 ```javascript
-import PartialMatchRegExp from "regex-partial-match";
+import PartialMatchRegExp, { features } from "regex-partial-match";
 
 const partial = new PartialMatchRegExp(/^[a-z]+(?<domain>\.[a-z]+)\1/);
 
-partial.features; // Set { "startAnchor", "backreference", "namedGroup", "capturingGroup", "characterClass", "quantifier", "otherEscape" }
-partial.features.has("backreference"); // true
+features(partial); // Set { "startAnchor", "backreference", "namedGroup", "capturingGroup", "characterClass", "quantifier", "otherEscape" }
+features(partial).has("backreference"); // true
 ```
 
-`RegexFeature` is a string union, exported alongside `PartialMatchRegExp`:
+`RegexFeature` is a string union, exported from `regex-partial-match` and `regex-partial-match/features`:
 
 | Feature                    | Matches                                                | Notes                                                                          |
 | --------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- |
@@ -416,7 +407,7 @@ partial.features.has("backreference"); // true
 | `controlLetterEscape`        | `\cX`                                                   |                                                                                 |
 | `hexEscapeSequence`          | `\xXX`                                                  |                                                                                 |
 | `unicodeEscapeSequence`      | `\uXXXX`, `\u{...}`                                     |                                                                                 |
-| `otherEscape`                 | Any other `\X`, e.g. `\.`, `\0`                         |                                                                                 |
+| `otherEscape`                 | Any other `\X`, e.g. `\.`                               | `\0` alone is tagged `otherEscape` only under `u`/`v`; otherwise `backreference`, [like any other digit escape](docs/modules/backreferences.md) |
 
 Three things worth knowing about how these tags line up with the grammar:
 

package/lib/core/corePartialMatchRegExp.d.ts

@@ -0,0 +1,24 @@
+import type { PartialMatchRegExpConstructor } from "../partialMatchRegExp/index.ts";
+/**
+ * `PartialMatchRegExp` without the rules that place a `^` in a group or after
+ * other parts under the `m` flag, or match a backreference, so that a bundle
+ * importing only `regex-partial-match/core` leaves them out.
+ *
+ * A pattern that needs either throws one `TypeError` naming every module it
+ * needs; every other pattern is transformed exactly as the class exported
+ * from `regex-partial-match` transforms it.
+ *
+ * @example
+ * ```typescript
+ * import PartialMatchRegExp from "regex-partial-match/core";
+ *
+ * new PartialMatchRegExp(/^hello world/).test("hello"); // true
+ * new PartialMatchRegExp(/(a)\1/); // throws TypeError
+ * ```
+ *
+ * @see {@link https://github.com/TomStrepsil/regex-partial-match#readme | Documentation}
+ */
+declare const PartialMatchRegExp: PartialMatchRegExpConstructor;
+type PartialMatchRegExp = InstanceType<typeof PartialMatchRegExp>;
+export default PartialMatchRegExp;
+export type { PartialMatchRegExp, PartialMatchRegExpConstructor };

package/lib/core/corePartialMatchRegExp.js

@@ -0,0 +1,22 @@
+import withModules from "../partialMatchRegExp/withModules.js";
+/**
+ * `PartialMatchRegExp` without the rules that place a `^` in a group or after
+ * other parts under the `m` flag, or match a backreference, so that a bundle
+ * importing only `regex-partial-match/core` leaves them out.
+ *
+ * A pattern that needs either throws one `TypeError` naming every module it
+ * needs; every other pattern is transformed exactly as the class exported
+ * from `regex-partial-match` transforms it.
+ *
+ * @example
+ * ```typescript
+ * import PartialMatchRegExp from "regex-partial-match/core";
+ *
+ * new PartialMatchRegExp(/^hello world/).test("hello"); // true
+ * new PartialMatchRegExp(/(a)\1/); // throws TypeError
+ * ```
+ *
+ * @see {@link https://github.com/TomStrepsil/regex-partial-match#readme | Documentation}
+ */
+const PartialMatchRegExp = withModules();
+export default PartialMatchRegExp;

package/lib/core/index.d.ts

@@ -0,0 +1,4 @@
+export { default } from "./corePartialMatchRegExp.ts";
+export type { PartialMatchRegExp, PartialMatchRegExpConstructor } from "./corePartialMatchRegExp.ts";
+export { default as withModules } from "../partialMatchRegExp/withModules.ts";
+export type { Module } from "../partialMatchRegExp/opaqueModule.ts";

package/lib/core/index.js

@@ -0,0 +1,2 @@
+export { default } from "./corePartialMatchRegExp.js";
+export { default as withModules } from "../partialMatchRegExp/withModules.js";

package/lib/{extend.d.ts → extend/index.d.ts}

@@ -1,12 +1,11 @@
-import PartialMatchRegExp from "./partialMatchRegExp.ts";
+import PartialMatchRegExp from "../partialMatchRegExp/index.ts";
 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.
+         * The result matches any prefix of the original pattern, which enables
+         * validation of incomplete input strings.
          *
          * @returns A new PartialMatchRegExp that matches partial strings of the original pattern
          *
@@ -23,9 +22,9 @@ declare global {
          * ```
          *
          * @remarks
-         * - The transformed regex will always match an empty string at the end of input
-         * - 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
+         * 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.
+         * See the documentation for how the `y` (sticky) flag behaves.
          *
          * @see {@link https://github.com/TomStrepsil/regex-partial-match#readme | Documentation}
          */

package/lib/{extend.js → extend/index.js}

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

package/lib/features/index.d.ts

@@ -0,0 +1,20 @@
+import type PartialMatchRegExp from "../partialMatchRegExp/index.ts";
+import { type RegexFeature } from "../partialMatchRegExp/regexFeatures.ts";
+export type { RegexFeature };
+/**
+ * The syntactic constructs `partial`'s original pattern uses.
+ *
+ * The set iterates in `RegexFeature` declaration order, not the order the
+ * constructs appear in the pattern.
+ *
+ * @param partial - A `PartialMatchRegExp` instance, from any entry point
+ * @returns The features the original pattern contains
+ *
+ * @example
+ * ```typescript
+ * import PartialMatchRegExp, { features } from "regex-partial-match";
+ *
+ * features(new PartialMatchRegExp(/^[a-z]+/)).has("startAnchor"); // true
+ * ```
+ */
+export default function features(partial: PartialMatchRegExp): ReadonlySet<RegexFeature>;

package/lib/features/index.js

@@ -0,0 +1,23 @@
+import { compiledOf } from "../partialMatchRegExp/partialMatchInternals.js";
+import { featureSet } from "../partialMatchRegExp/regexFeatures.js";
+/**
+ * The syntactic constructs `partial`'s original pattern uses.
+ *
+ * The set iterates in `RegexFeature` declaration order, not the order the
+ * constructs appear in the pattern.
+ *
+ * @param partial - A `PartialMatchRegExp` instance, from any entry point
+ * @returns The features the original pattern contains
+ *
+ * @example
+ * ```typescript
+ * import PartialMatchRegExp, { features } from "regex-partial-match";
+ *
+ * features(new PartialMatchRegExp(/^[a-z]+/)).has("startAnchor"); // true
+ * ```
+ */
+export default function features(partial) {
+    var _a;
+    const compiled = compiledOf(partial);
+    return ((_a = compiled.features) !== null && _a !== void 0 ? _a : (compiled.features = featureSet(compiled.featureMask)));
+}