@xmachines/play-pattern 5.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikael Karon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @xmachines/play-pattern
+
+The route pattern language of the XMachines Play Architecture.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-5.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-pattern)
+
+One parse of the URLPattern pathname grammar, and the path that it builds back.
+
+## What this package is
+
+`URLPattern` is the pattern language of XMachines. This package reads a route pattern ONE time and answers every question that a router asks about it, and it writes a path back from the same parse.
+
+- **`parsePattern(pattern)`** — the parts, the params, which of them a path must fill, whether the pattern needs a match, the bucket key, the bare form, and the literal path.
+- **`buildPath(pattern, params)`** — the path that the pattern describes, with each param filled. It reports a fault through its return value, and it throws never: `reason: "missing"` for a param that needs a value and has none, and `reason: "unresolvable"` for a param that carries a value no path can hold, such as a dot segment.
+- **`getIndexKey(path)`** — the bucket key of a concrete path.
+- **`isDotSegment(segment)`** — whether a URL resolves the segment away. `buildPath` reads it, and [`@xmachines/play-url`](../play-url/README.md) reads it for a base path, so ONE definition answers for both.
+
+Both directions read the same parts, so a route that the match reads derives a URL that the match reads back.
+
+## What this package is NOT
+
+It holds no `URLPattern` API. A parse is string work and it needs no constructor, so this package carries no polyfill. [`@xmachines/play-url`](../play-url/README.md) holds the API, the base path and the params of a framework router, and it reads this package for the language.
+
+That line is why the package exists. [`@xmachines/play-xstate`](../play-xstate/README.md) BUILDS a URL and matches none, so it reads the grammar and installs no matching machinery for it.
+
+## Install
+
+```bash
+pnpm add @xmachines/play-pattern
+```
+
+Most applications install it through [`@xmachines/play-url`](../play-url/README.md), which re-exports the language whole. [`@xmachines/play-router`](../play-router/README.md) re-exports the part that a router needs: `parsePattern` and `createPatternCache`.
+
+## Usage
+
+```typescript
+import { buildPath, parsePattern } from "@xmachines/play-pattern";
+
+parsePattern("/settings/:section?").requiredNames; // []
+parsePattern("/docs/:cat-id").names; // ["cat-id"]
+
+buildPath("/profile/:userId", { userId: "alice" }); // { ok: true, path: "/profile/alice" }
+buildPath("/settings/:section?", {}); // { ok: true, path: "/settings" }
+buildPath("/profile/:userId", {}); // { ok: false, reason: "missing", missing: "userId" }
+buildPath("/files/:name", { name: ".." }); // { ok: false, reason: "unresolvable", param: "name", value: ".." }
+buildPath("/files/v:version", { version: ".." }); // { ok: true, path: "/files/v.." } — the value shares the segment
+```
+
+## The grammar
+
+| form         | meaning                                                   |
+| ------------ | --------------------------------------------------------- |
+| `/users`     | a literal                                                 |
+| `:name`      | a named param, one path segment                           |
+| `:name(\d+)` | a named param with a regular expression constraint        |
+| `(\d+)`      | an anonymous param, numbered from `0`                     |
+| `*`          | an anonymous param that matches every remaining character |
+| `{…}`        | a group, which carries its own literals and params        |
+| `?` `+` `*`  | the modifier of the part before it                        |
+| `\:`         | an escape, which makes the next character a literal       |
+
+A param name of this library holds a hyphen, which URLPattern does not: `/docs/:cat-id` is ONE param named `cat-id`, and `ParsedPattern.normalized` carries the form that URLPattern compiles. The [routing guide](../docs/guides/routing.md) states the divergence and which forms each direction reads.
+
+## License
+
+MIT

package/dist/cache.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The cache contract of this package, and the default implementation of it.
+ *
+ * A parse is deterministic, so a cache changes no answer. It changes how often the parser
+ * runs, and it changes nothing else — which is what makes the contract below safe to
+ * adopt one caller at a time. A caller that passes no cache reads the shared default, and
+ * a caller that passes one reads that one. The two never disagree.
+ *
+ * ## Why a caller brings one
+ *
+ * The default cache is one object for the whole process, and a process serves more than
+ * one caller:
+ *
+ * - A server renders for many tenants. One route table for each tenant, and a shared
+ *   cache that each tenant evicts for the others.
+ * - A test measures the parser and reaches a parse that an earlier test wrote.
+ * - A worker lives longer than a page, and the bound of a page is arbitrary for it.
+ * - A host owns an LRU already, and one eviction policy for every cache it holds.
+ *
+ * @see [Routing guide](../../docs/guides/routing.md)
+ */
+import type { ParsedPattern } from "./pattern-grammar.js";
+/**
+ * The options that every read of the pattern language takes.
+ *
+ * It is ONE field today, and it is an object rather than a positional argument so that a
+ * caller holds one object and hands it to every call — `parsePattern`, `buildPath`,
+ * `getCompiledPattern`, `findRouteByPath`, a route map and a bridge all take it, and
+ * `CompileOptions` and `RouteMapOptions` extend it with the caches of their own layer. A
+ * positional argument gave each layer a different position to remember.
+ */
+export interface ParseOptions {
+    /**
+     * The cache of the PARSE of a pattern.
+     *
+     * The default is the cache that this package shares with every caller of the process.
+     */
+    readonly patternCache?: PatternCache<ParsedPattern> | undefined;
+}
+/**
+ * What this package needs from a cache: a read and a write, both by a string key.
+ *
+ * The contract is this small on purpose. A `Map` satisfies it, and so does an LRU of any
+ * library — a caller that wants a time to live or an eviction callback brings the module
+ * that has one, and this package needs to know nothing about it.
+ *
+ * A cache may forget an entry at any time, and it may forget none. Both are correct: the
+ * parser runs again for an entry that is absent.
+ */
+export interface PatternCache<V> {
+    /** Reads one entry, or `undefined` when the cache holds none for the key. */
+    get(key: string): V | undefined;
+    /** Writes one entry. */
+    set(key: string, value: V): void;
+}
+/**
+ * Builds a cache that forgets its least recently used entries.
+ *
+ * ## The algorithm
+ *
+ * Two maps, and no list. `recent` takes every write. When a write fills `recent`, it
+ * becomes `old` and a new `recent` opens, which drops the previous `old` whole. A read of
+ * a key of `old` moves the entry into `recent`, and THAT is what makes the eviction an
+ * LRU one rather than a FIFO one: an entry that every lookup reads moves forward, and an
+ * entry that nothing reads falls out with the map that holds it.
+ *
+ * The cache therefore holds between `maxSize` and `2 * maxSize` entries, and it does no
+ * bookkeeping for a read that hits `recent`.
+ *
+ * @param maxSize - The number of entries that `recent` holds. It is `1` at the least, and
+ *   the default is `500`. A value that is not a finite number reads as the default, so a
+ *   cache with no eviction at all cannot happen by accident.
+ * @returns A cache. It is not shared: each call builds one.
+ *
+ * @example
+ * ```typescript
+ * const cache = createPatternCache<ParsedPattern>(50);
+ * parsePattern("/profile/:userId", { patternCache: cache });
+ * ```
+ */
+export declare function createPatternCache<V>(maxSize?: number): PatternCache<V>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC,aAAa,CAAC,GAAG,SAAS,CAAC;CAChE;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC9B,6EAA6E;IAC7E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAChC,wBAAwB;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,SAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAqCpE"}

package/dist/cache.js

@@ -0,0 +1,83 @@
+/**
+ * The cache contract of this package, and the default implementation of it.
+ *
+ * A parse is deterministic, so a cache changes no answer. It changes how often the parser
+ * runs, and it changes nothing else — which is what makes the contract below safe to
+ * adopt one caller at a time. A caller that passes no cache reads the shared default, and
+ * a caller that passes one reads that one. The two never disagree.
+ *
+ * ## Why a caller brings one
+ *
+ * The default cache is one object for the whole process, and a process serves more than
+ * one caller:
+ *
+ * - A server renders for many tenants. One route table for each tenant, and a shared
+ *   cache that each tenant evicts for the others.
+ * - A test measures the parser and reaches a parse that an earlier test wrote.
+ * - A worker lives longer than a page, and the bound of a page is arbitrary for it.
+ * - A host owns an LRU already, and one eviction policy for every cache it holds.
+ *
+ * @see [Routing guide](../../docs/guides/routing.md)
+ */
+/**
+ * Builds a cache that forgets its least recently used entries.
+ *
+ * ## The algorithm
+ *
+ * Two maps, and no list. `recent` takes every write. When a write fills `recent`, it
+ * becomes `old` and a new `recent` opens, which drops the previous `old` whole. A read of
+ * a key of `old` moves the entry into `recent`, and THAT is what makes the eviction an
+ * LRU one rather than a FIFO one: an entry that every lookup reads moves forward, and an
+ * entry that nothing reads falls out with the map that holds it.
+ *
+ * The cache therefore holds between `maxSize` and `2 * maxSize` entries, and it does no
+ * bookkeeping for a read that hits `recent`.
+ *
+ * @param maxSize - The number of entries that `recent` holds. It is `1` at the least, and
+ *   the default is `500`. A value that is not a finite number reads as the default, so a
+ *   cache with no eviction at all cannot happen by accident.
+ * @returns A cache. It is not shared: each call builds one.
+ *
+ * @example
+ * ```typescript
+ * const cache = createPatternCache<ParsedPattern>(50);
+ * parsePattern("/profile/:userId", { patternCache: cache });
+ * ```
+ */
+export function createPatternCache(maxSize = 500) {
+    // `Math.max(1, NaN)` answers `NaN`, and `recent.size > NaN` is false for ever, so a
+    // non-finite argument turned the bound off and the cache grew for the life of the
+    // process. A caller reads the size from a configuration value often enough — an absent
+    // environment variable gives `Number(undefined)` — so the guard reads the number
+    // itself, and it falls back to the default that the parameter names.
+    const bound = Number.isFinite(maxSize) ? Math.max(1, Math.floor(maxSize)) : 500;
+    let recent = new Map();
+    let old = new Map();
+    const write = (key, value) => {
+        recent.set(key, value);
+        if (recent.size > bound) {
+            old = recent;
+            recent = new Map();
+        }
+    };
+    return {
+        get(key) {
+            const hit = recent.get(key);
+            // A `has` costs a second lookup, and a stored `undefined` is the only value that
+            // this tells apart. No caller of this package stores one: a parse is an object,
+            // and a path match stores `null` for "no match".
+            if (hit !== undefined)
+                return hit;
+            const stale = old.get(key);
+            if (stale === undefined)
+                return undefined;
+            // The entry survives, so the read promotes it. Without the promotion the eviction
+            // drops an entry that every lookup reads.
+            old.delete(key);
+            write(key, stale);
+            return stale;
+        },
+        set: write,
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAuCH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB,CAAI,OAAO,GAAG,GAAG;IAClD,oFAAoF;IACpF,kFAAkF;IAClF,uFAAuF;IACvF,iFAAiF;IACjF,qEAAqE;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAChF,IAAI,MAAM,GAAG,IAAI,GAAG,EAAa,CAAC;IAClC,IAAI,GAAG,GAAG,IAAI,GAAG,EAAa,CAAC;IAE/B,MAAM,KAAK,GAAG,CAAC,GAAW,EAAE,KAAQ,EAAQ,EAAE;QAC7C,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACvB,IAAI,MAAM,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;YACzB,GAAG,GAAG,MAAM,CAAC;YACb,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACpB,CAAC;IACF,CAAC,CAAC;IAEF,OAAO;QACN,GAAG,CAAC,GAAW;YACd,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,iFAAiF;YACjF,gFAAgF;YAChF,iDAAiD;YACjD,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,GAAG,CAAC;YAElC,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC3B,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAE1C,kFAAkF;YAClF,0CAA0C;YAC1C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChB,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAClB,OAAO,KAAK,CAAC;QACd,CAAC;QACD,GAAG,EAAE,KAAK;KACV,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The route pattern language of XMachines.
+ *
+ * `URLPattern` is that language, and this package reads it ONE time for each pattern.
+ * `parsePattern` answers every question that a router asks about a route — which params
+ * the pattern declares, which of them a path must fill, whether the pattern needs a match
+ * at all, which bucket it belongs to, and which path it matches when every optional part
+ * is absent. `buildPath` walks the SAME parts back into a path, so a route that the match
+ * reads derives a URL that the match reads back.
+ *
+ * ## What this package does NOT hold
+ *
+ * The URLPattern API. A parse is string work, and it needs no constructor: this package
+ * therefore carries no polyfill. `@xmachines/play-url` holds the API, the base path and
+ * the params of a framework router, and it reads this package for the language.
+ *
+ * That line is the reason the package exists. `@xmachines/play-xstate` BUILDS a URL and
+ * it matches none, so it reads the grammar and it installs no matching machinery for it.
+ *
+ * @packageDocumentation
+ * @see [Routing guide](../../docs/guides/routing.md)
+ */
+export { buildPath, getIndexKey, isDotSegment, parsePattern } from "./pattern-grammar.js";
+export { createPatternCache } from "./cache.js";
+export type { ParseOptions, PatternCache } from "./cache.js";
+export type { GroupPart, LiteralPart, ParamPart, ParsedPattern, PathBuildResult, PathParams, PatternModifier, PatternParam, PatternPart, } from "./pattern-grammar.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC7D,YAAY,EACX,SAAS,EACT,WAAW,EACX,SAAS,EACT,aAAa,EACb,eAAe,EACf,UAAU,EACV,eAAe,EACf,YAAY,EACZ,WAAW,GACX,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * The route pattern language of XMachines.
+ *
+ * `URLPattern` is that language, and this package reads it ONE time for each pattern.
+ * `parsePattern` answers every question that a router asks about a route — which params
+ * the pattern declares, which of them a path must fill, whether the pattern needs a match
+ * at all, which bucket it belongs to, and which path it matches when every optional part
+ * is absent. `buildPath` walks the SAME parts back into a path, so a route that the match
+ * reads derives a URL that the match reads back.
+ *
+ * ## What this package does NOT hold
+ *
+ * The URLPattern API. A parse is string work, and it needs no constructor: this package
+ * therefore carries no polyfill. `@xmachines/play-url` holds the API, the base path and
+ * the params of a framework router, and it reads this package for the language.
+ *
+ * That line is the reason the package exists. `@xmachines/play-xstate` BUILDS a URL and
+ * it matches none, so it reads the grammar and it installs no matching machinery for it.
+ *
+ * @packageDocumentation
+ * @see [Routing guide](../../docs/guides/routing.md)
+ */
+export { buildPath, getIndexKey, isDotSegment, parsePattern } from "./pattern-grammar.js";
+export { createPatternCache } from "./cache.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/pattern-grammar.d.ts

@@ -0,0 +1,295 @@
+/**
+ * The pattern language of this library, read and written in ONE place.
+ *
+ * `parsePattern` reads a pattern into parts, and `buildPath` walks those same parts back
+ * into a path. Both directions therefore hold one grammar, and neither can drift from the
+ * other. `index.ts` exports both.
+ *
+ * `URLPattern` is the pattern language of XMachines, and this module is the only reader
+ * of it. Every question that the router asks about a route pattern comes from one parse:
+ * which params the pattern declares, which of them a path must fill, whether the pattern
+ * needs a match at all, which bucket it belongs to, and which path the pattern matches
+ * when every optional part is absent.
+ *
+ * Four regular expressions asked those questions before, each over a different subset of
+ * the grammar, and they disagreed. `getRequiredPatternParamNames` read a bare `?` alone,
+ * so it called `:path*` and `{/:id}?` required. `isParameterizedPattern` looked for a
+ * `:` or a `*`, so it called `/a{/b}?/c` a static path and sent it to the exact-match
+ * map, where it matched nothing. One parse answers all of them, and the answers cannot
+ * move apart.
+ *
+ * ## The grammar
+ *
+ * The parser reads the pathname grammar of URLPattern:
+ *
+ * | form | meaning |
+ * | --- | --- |
+ * | `/users` | a literal |
+ * | `:name` | a named param, one path segment |
+ * | `:name(\d+)` | a named param with a regular expression constraint |
+ * | `(\d+)` | an anonymous param, numbered from `0` |
+ * | `*` | an anonymous param that matches every remaining character |
+ * | `{…}` | a group, which carries its own literals and params |
+ * | `?` `+` `*` | the modifier of the part before it: optional, one or more, zero or more |
+ * | `\:` | an escape, which makes the next character a literal |
+ *
+ * ## The prefix rule
+ *
+ * A `/` directly before a param belongs TO that param, and a `/` directly before a group
+ * does not. `/settings/:section?` therefore matches `/settings`, and `/a/{b}?/c` matches
+ * `/a//c` and not `/a/c`. The rule decides every bare form below, and each case of it is
+ * measured against the native API and against the polyfill in
+ * `test/pattern-grammar.test.ts`.
+ *
+ * ## The one divergence from URLPattern
+ *
+ * A param name of URLPattern is a JavaScript identifier, and it holds no hyphen:
+ * `/docs/:cat-id` is the param `cat` and the literal `-id` for the standard. This library
+ * reads `cat-id` as ONE name and compiles it as `:cat_id`, because a route of a machine
+ * names a param the way the application does. The guide states the divergence, and
+ * {@link ParsedPattern.normalized} carries the form that URLPattern compiles.
+ */
+import type { ParseOptions } from "./cache.js";
+/** The modifier of a part. `""` means that the part carries none. */
+export type PatternModifier = "" | "?" | "+" | "*";
+/** A run of literal characters, with every escape already resolved. */
+export interface LiteralPart {
+    readonly kind: "literal";
+    /** The characters that a path must carry, for example `/settings`. */
+    readonly text: string;
+}
+/**
+ * A param: `:name`, `(\d+)`, or `*`.
+ *
+ * An anonymous param carries no `name`. URLPattern numbers such a group from `0`, and
+ * this library reports it to no machine — see {@link ParsedPattern.params}.
+ */
+export interface ParamPart {
+    readonly kind: "param";
+    /** The declared name, with each hyphen kept, or `null` for an anonymous param. */
+    readonly name: string | null;
+    /**
+     * The name that URLPattern compiles, with each hyphen rewritten to an underscore, or
+     * `null` for an anonymous param.
+     *
+     * The rewrite happens ONE time, here, and {@link ParsedPattern.normalized} carries the
+     * same characters. A caller that needs the group name of a param reads this field, and
+     * it rewrites nothing of its own.
+     */
+    readonly groupName: string | null;
+    /** The source of the constraint of `:id(\d+)`, or `null` when the param declares none. */
+    readonly regexp: string | null;
+    /** The `/` that the param absorbed from the literal before it, or `""`. */
+    readonly prefix: string;
+    readonly modifier: PatternModifier;
+}
+/** A `{…}` group, which carries its own parts and its own modifier. */
+export interface GroupPart {
+    readonly kind: "group";
+    readonly parts: readonly PatternPart[];
+    readonly modifier: PatternModifier;
+}
+export type PatternPart = LiteralPart | ParamPart | GroupPart;
+/** One named param of a pattern, with the question that every caller asks about it. */
+export interface PatternParam {
+    /** The name as the pattern declares it, for example `cat-id`. */
+    readonly name: string;
+    /** The name that URLPattern compiles, for example `cat_id`. */
+    readonly groupName: string;
+    /**
+     * True when a matching path can carry no value for this param.
+     *
+     * The modifier `?` and the modifier `*` make a param optional, and so does EVERY
+     * group above it that carries one of the two. The modifier `+` does not: it repeats a
+     * param that one value must still fill.
+     */
+    readonly optional: boolean;
+}
+/** Everything that this library reads from one route pattern. */
+export interface ParsedPattern {
+    /** The pattern as the caller wrote it. */
+    readonly source: string;
+    /** The parts, in the order that the pattern declares them. */
+    readonly parts: readonly PatternPart[];
+    /** The NAMED params, in the order that the pattern declares them. */
+    readonly params: readonly PatternParam[];
+    /**
+     * The name of every param of {@link params}, in the same order.
+     *
+     * `resolveFrameworkParams` runs on EVERY navigation and it needs this list each time.
+     * The parse holds it, so a navigation allocates none. A caller that hands the array to
+     * somebody else copies it: the cache holds this one.
+     */
+    readonly names: readonly string[];
+    /**
+     * The name of every param that a path must fill, in the order of {@link params}.
+     *
+     * The same rule as {@link names}: the parse holds the array, and a navigation reads it.
+     */
+    readonly requiredNames: readonly string[];
+    /**
+     * True when the pattern needs a URLPattern match, and false when it is a literal path.
+     *
+     * A malformed pattern reports `true`, so that it reaches the URLPattern constructor
+     * and fails there with the error of the API. A parser that called it static would
+     * send it to the exact-match map instead, where it matches nothing and reports no
+     * fault.
+     */
+    readonly parameterized: boolean;
+    /**
+     * The path that the pattern matches when every optional part is absent, or `null`
+     * when the pattern holds a part that a path must fill.
+     *
+     * `/settings/:section?` gives `/settings`, `/a/{b}?/c` gives `/a//c`, and
+     * `/profile/:userId` gives `null`.
+     */
+    readonly bareForm: string | null;
+    /**
+     * The ONE path that the pattern matches, with each escape resolved, or `null` when the
+     * pattern describes a SET of paths.
+     *
+     * `/users` gives `/users`, `/tags/c\+\+` gives `/tags/c++`, `/x{y}z` gives `/xyz`, and
+     * `/profile/:userId` gives `null`.
+     *
+     * A bridge writes a real browser URL from this field. The SOURCE of the pattern is no
+     * substitute for it: `/tags/c\+\+` carries two backslashes that the address bar must
+     * not hold, and a location that carries them matches the route never.
+     */
+    readonly literalPath: string | null;
+    /**
+     * The key of the bucket index: the first path segment, or `"*"` when a param can
+     * stand in the first segment.
+     */
+    readonly indexKey: string;
+    /**
+     * The pattern in the form that URLPattern compiles: each param name that holds a
+     * hyphen carries an underscore instead.
+     */
+    readonly normalized: string;
+    /**
+     * The map from each rewritten group name back to the name that the pattern declares,
+     * for example `cat_id` to `cat-id`.
+     *
+     * The map holds an entry only for a name that the rewrite changed. It is empty for
+     * most patterns, and a caller that reads a group name falls back to the name itself.
+     */
+    readonly declaredNames: ReadonlyMap<string, string>;
+}
+/**
+ * Computes the key of the bucket index of a concrete PATH.
+ *
+ * The key is the first path segment, for example `"settings"` of `"/settings/billing"`.
+ * The root path `"/"` gives the key `"/"`, and a path whose first segment is EMPTY —
+ * `"//docs"` — gives the key `""`. The two are different keys, so a pattern that matches
+ * both asks {@link ParsedPattern.indexKey} for the wildcard key instead.
+ *
+ * {@link ParsedPattern.indexKey} computes the key of a PATTERN, and it calls this
+ * function for every pattern whose first segment is a literal. One function therefore
+ * answers both sides, and a pattern in the wrong bucket cannot happen.
+ *
+ * @param path - The string of a URL path.
+ */
+export declare function getIndexKey(path: string): string;
+/**
+ * Reads a route pattern, one time for each distinct pattern.
+ *
+ * The parser reports a fault never. A pattern that it cannot read reports
+ * `parameterized: true` and `bareForm: null`, which sends it to the URLPattern
+ * constructor and keeps every derived answer on the safe side.
+ *
+ * @param pattern - The route pattern, for example `/profile/:userId`.
+ * @returns The parse. The caller treats it as read-only: the cache holds this object.
+ */
+export declare function parsePattern(pattern: string, options?: ParseOptions): ParsedPattern;
+/** The answer of {@link buildPath}. */
+export type PathBuildResult = 
+/** The pattern built a path, and every part that needs a value has one. */
+{
+    readonly ok: true;
+    readonly path: string;
+}
+/**
+ * A part needs a value that the caller did not give.
+ *
+ * `missing` names the param as the PATTERN declares it, with each hyphen kept, so a
+ * caller reports the name that its author wrote.
+ */
+ | {
+    readonly ok: false;
+    readonly reason: "missing";
+    readonly missing: string;
+}
+/**
+ * A param carries a value that no path can hold, so the pattern matches the result
+ * back never. `param` names the param, and `value` holds what the caller gave.
+ *
+ * A dot segment is the one such value today: see {@link isDotSegment}.
+ */
+ | {
+    readonly ok: false;
+    readonly reason: "unresolvable";
+    readonly param: string;
+    readonly value: string;
+};
+/**
+ * The values that a caller gives, keyed by the declared name of the param.
+ *
+ * The value is `unknown`, because a caller reads it from the context of an actor and that
+ * context carries whatever the machine put there. {@link buildPath} calls `String` on a
+ * value that is neither `undefined` nor `null`.
+ */
+export type PathParams = Readonly<Record<string, unknown>>;
+/**
+ * Builds the path that a pattern describes, with each param filled from `params`.
+ *
+ * This is the OUTBOUND half of the language, and it reads the same parse as the match.
+ * The walk drops an optional part that has no value TOGETHER with the `/` that the part
+ * absorbed, which is the prefix rule of the module comment: `/settings/:section?` builds
+ * `/settings`, and not `/settings/`.
+ *
+ * The function reports a fault through its return value, and it throws never. The
+ * `reason` field names the fault: `missing` for a param that needs a value and has none,
+ * and `unresolvable` for a param that carries a value no path can hold. A caller raises
+ * the error of its own layer — `@xmachines/play-xstate` raises `MissingRouteParamError`
+ * for the first one and `InvalidRouteParamError` for the second.
+ *
+ * @param pattern - The route pattern, for example `/profile/:userId`.
+ * @param params - The value of each param, keyed by the name that the pattern declares.
+ * @returns The path, or the reason that stopped the walk with the param that carries it.
+ *
+ * @example
+ * ```typescript
+ * buildPath("/profile/:userId", { userId: "alice" }); // { ok: true, path: "/profile/alice" }
+ * buildPath("/settings/:section?", {});               // { ok: true, path: "/settings" }
+ * buildPath("/tags/c\\+\\+", {});                     // { ok: true, path: "/tags/c++" }
+ * buildPath("/profile/:userId", {});                  // { ok: false, reason: "missing", missing: "userId" }
+ * buildPath("/files/:name", { name: ".." });          // { ok: false, reason: "unresolvable", … }
+ * ```
+ */
+export declare function buildPath(pattern: string, params?: PathParams, options?: ParseOptions): PathBuildResult;
+/**
+ * Answers whether one segment resolves away in a URL, rather than naming itself.
+ *
+ * A URL parser reads the dot segments BEFORE it decodes the percent escapes, and it counts
+ * `%2e` as the dot. The WHATWG URL standard names six forms, and a browser resolves every
+ * one of them out of a location: `.` and `%2e` for the single dot, and `..`, `.%2e`, `%2e.`
+ * and `%2e%2e` for the double dot. Each percent test is case-insensitive.
+ *
+ * NO encoding of `.` or `..` therefore survives. A param that carries one describes a path
+ * that its own pattern matches back never, so {@link buildPath} refuses it, and
+ * `normalizeBasePath` of `@xmachines/play-url` refuses the same value in a base path.
+ *
+ * Give the segment in the form that the URL carries, and encode nothing here. The two
+ * callers reach that form by two roads, and both are correct. {@link buildPath} encodes a
+ * param value first, so a value that HOLDS a percent sign arrives with that sign escaped:
+ * the string `"%2e"` encodes to `"%252e"`, which names itself and stays. `normalizeBasePath`
+ * of `@xmachines/play-url` reads a path that an author wrote, which is encoded already, so
+ * it passes the segment RAW and `"%2e"` there is the dot. A caller that encodes an
+ * already-encoded segment a second time hides every `%2e` from this test.
+ *
+ * @param segment - ONE path segment, with no separator around it, in the form that the URL
+ *   carries it.
+ * @returns `true` when a URL resolves the segment away.
+ */
+export declare function isDotSegment(segment: string): boolean;
+//# sourceMappingURL=pattern-grammar.d.ts.map

package/dist/pattern-grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-grammar.d.ts","sourceRoot":"","sources":["../src/pattern-grammar.ts"],"names":[],"mappings":"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"}