regex-partial-match 2.0.1 → 2.1.0

package/README.md

@@ -89,6 +89,16 @@ 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).
 
+To tell an instance from a plain `RegExp` without importing a class, use [`isPartialMatchRegExp()`](#ispartialmatchregexp). It returns `true` for an instance of any `PartialMatchRegExp` class and `false` for anything else, including a plain `RegExp`:
+
+```javascript
+import PartialMatchRegExp from "regex-partial-match/core";
+import { isPartialMatchRegExp } from "regex-partial-match/features";
+
+isPartialMatchRegExp(new PartialMatchRegExp(/a/)); // true
+isPartialMatchRegExp(/a/); // false
+```
+
 ### 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`:
@@ -321,7 +331,7 @@ Available as a named export of the default entry point, `import { hitEnd } from
 **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.
+- `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 three cases in [What it cannot see](#what-it-cannot-see) below, where a read of the end leaves no marker, or a split surrogate pair can still change the match, and `false` is reported despite it.
 
 ```javascript
 import PartialMatchRegExp, { hitEnd } from "regex-partial-match";
@@ -338,7 +348,7 @@ hitEnd(greedy, greedy.exec("hello world")); // true  — \w+ read the end lookin
 ```
 
 > [!NOTE]
-> Where the JDK is exact, [`hitEnd`](#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.
+> Where the JDK is exact, [`hitEnd`](#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 three limits in [What it cannot see](#what-it-cannot-see), it is never wrong in the other direction.
 
 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`](#hitend) records a read of the end.
 
@@ -346,6 +356,7 @@ See [How It Works](./docs/how-it-works.md#why-the-question-cant-be-answered-from
 
 - **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.
+- **A high surrogate ending the input under `u` or `v`.** Only whole astral characters are supported (see [Surrogate Pair Matching](./docs/caveats.md#surrogate-pair-matching)), so a match whose last code unit is a lone high surrogate reports `false`, although a following low surrogate would pair with it and change the match's text: `/./u` on `"\ud83d"` matches `"\ud83d"`, but `"😄"` matches `"😄"`. [^3]
 
 ### `features()`
 
@@ -353,7 +364,7 @@ See [How It Works](./docs/how-it-works.md#why-the-question-cant-be-answered-from
 features(partial: PartialMatchRegExp): ReadonlySet<RegexFeature>
 ```
 
-Building the partial-match regex requires walking the entire source pattern, usually once. [^3] 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.
+Building the partial-match regex requires walking the entire source pattern, usually once. [^4] 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).
 
@@ -413,7 +424,22 @@ Three things worth knowing about how these tags line up with the grammar:
 - **A named capturing group always carries both `namedGroup` and `capturingGroup`.** The grammar treats a capturing group with a name and one without as the same production (`( GroupSpecifier? Disjunction )`), not two, so both tags are added together.
 - **`lookaroundCapture` records nesting, not a construct.** Every other tag names something the source contains; this one names where something sits — a capturing group appearing lexically inside `(?=...)`, `(?!...)`, `(?<=...)` or `(?<!...)`, at any depth of nested groups. It is the one relationship between constructs the flattened set cannot otherwise express: `/(\w+)(?= END)/` and `/a(?=(?:b(?:x|(c))d|b))/` both report `lookahead` and `capturingGroup`, but only the second has a capture whose value the assertion decides.
 
-[^3]: 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.
+[^3]: A scanner fed from a source that can split a surrogate pair across chunks, rather than a [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder) in streaming mode (`stream: true`, or `TextDecoderStream`), should defer any match ending on a code unit in `0xD800`–`0xDBFF` at the end of the input.
+
+[^4]: 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.
+
+### `isPartialMatchRegExp()`
+
+```typescript
+isPartialMatchRegExp(value: unknown): value is PartialMatchRegExp
+```
+
+Returns `true` for an instance of any `PartialMatchRegExp` class, from `regex-partial-match/core`, from `withModules(...)`, or from the default entry point, and `false` for a plain `RegExp` or any other value. It doesn't import a class or module, so it can be used to accept either a `RegExp` or a ready-built instance without pulling the default class into a bundle.
+
+Available as a named export of `regex-partial-match/features`, or of the default entry point, `import { isPartialMatchRegExp } from 'regex-partial-match'`.
+
+> [!CAUTION]
+> It recognises instances from the same installed copy of the library only: an instance from a second copy, such as a duplicate install in a bundle, returns `false`.
 
 ## 📜 License
 

package/lib/features/index.d.ts

@@ -1,6 +1,7 @@
 import type PartialMatchRegExp from "../partialMatchRegExp/index.ts";
 import { type RegexFeature } from "../partialMatchRegExp/regexFeatures.ts";
 export type { RegexFeature };
+export { default as isPartialMatchRegExp } from "../partialMatchRegExp/isPartialMatchRegExp.ts";
 /**
  * The syntactic constructs `partial`'s original pattern uses.
  *

package/lib/features/index.js

@@ -1,5 +1,6 @@
 import { compiledOf } from "../partialMatchRegExp/partialMatchInternals.js";
 import { featureSet } from "../partialMatchRegExp/regexFeatures.js";
+export { default as isPartialMatchRegExp } from "../partialMatchRegExp/isPartialMatchRegExp.js";
 /**
  * The syntactic constructs `partial`'s original pattern uses.
  *

package/lib/index.d.ts

@@ -1,4 +1,4 @@
 export * from "./partialMatchRegExp/index.ts";
 export { default } from "./partialMatchRegExp/index.ts";
 export { default as hitEnd } from "./hitEnd/index.ts";
-export { default as features } from "./features/index.ts";
+export { default as features, isPartialMatchRegExp } from "./features/index.ts";

package/lib/index.js

@@ -1,4 +1,4 @@
 export * from "./partialMatchRegExp/index.js";
 export { default } from "./partialMatchRegExp/index.js";
 export { default as hitEnd } from "./hitEnd/index.js";
-export { default as features } from "./features/index.js";
+export { default as features, isPartialMatchRegExp } from "./features/index.js";

package/lib/partialMatchRegExp/createPartialMatchRegExp.js

@@ -1,11 +1,12 @@
 import compileWith from "./compilePartial/compileWith.js";
-import { compiledPartial } from "./partialMatchInternals.js";
+import { compiledPartial, constructedPartials } from "./partialMatchInternals.js";
 import execFrom from "./execFrom.js";
 export default function createPartialMatchRegExp(hooks) {
     return class PartialMatchRegExp extends RegExp {
         constructor(pattern, flags) {
             super(pattern, flags);
             this[compiledPartial] = compileWith(this, hooks);
+            constructedPartials.add(this);
         }
         exec(input) {
             const compiled = this[compiledPartial];

package/lib/partialMatchRegExp/isPartialMatchRegExp.d.ts

@@ -0,0 +1,19 @@
+import type { PartialMatchRegExp } from "./index.ts";
+/**
+ * Whether `value` is an instance of a `PartialMatchRegExp` class, from any
+ * entry point or `withModules`, without importing any of those classes.
+ *
+ * @param value - Any value
+ * @returns `true` for a `PartialMatchRegExp` instance; `false` for a plain
+ * `RegExp` or any other value
+ *
+ * @example
+ * ```typescript
+ * import PartialMatchRegExp from "regex-partial-match/core";
+ * import { isPartialMatchRegExp } from "regex-partial-match/features";
+ *
+ * isPartialMatchRegExp(new PartialMatchRegExp(/a/)); // true
+ * isPartialMatchRegExp(/a/); // false
+ * ```
+ */
+export default function isPartialMatchRegExp(value: unknown): value is PartialMatchRegExp;

package/lib/partialMatchRegExp/isPartialMatchRegExp.js

@@ -0,0 +1,23 @@
+import { constructedPartials } from "./partialMatchInternals.js";
+/**
+ * Whether `value` is an instance of a `PartialMatchRegExp` class, from any
+ * entry point or `withModules`, without importing any of those classes.
+ *
+ * @param value - Any value
+ * @returns `true` for a `PartialMatchRegExp` instance; `false` for a plain
+ * `RegExp` or any other value
+ *
+ * @example
+ * ```typescript
+ * import PartialMatchRegExp from "regex-partial-match/core";
+ * import { isPartialMatchRegExp } from "regex-partial-match/features";
+ *
+ * isPartialMatchRegExp(new PartialMatchRegExp(/a/)); // true
+ * isPartialMatchRegExp(/a/); // false
+ * ```
+ */
+export default function isPartialMatchRegExp(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        constructedPartials.has(value));
+}

package/lib/partialMatchRegExp/partialMatchInternals.d.ts

@@ -1,3 +1,4 @@
 import type { CompiledPartial } from "./compilePartial/compiled.ts";
 export declare const compiledPartial: unique symbol;
+export declare const constructedPartials: WeakSet<object>;
 export declare function compiledOf(partial: RegExp): CompiledPartial;

package/lib/partialMatchRegExp/partialMatchInternals.js

@@ -1,4 +1,5 @@
 export const compiledPartial = Symbol("compiledPartial");
+export const constructedPartials = new WeakSet();
 export function compiledOf(partial) {
     return partial[compiledPartial];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "regex-partial-match",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A regular expression transform for partial matching",
   "keywords": [
     "regexp",