@xmachines/play-pattern 5.0.0

package/dist/pattern-grammar.js

@@ -0,0 +1,716 @@
+import { createPatternCache } from "./cache.js";
+/**
+ * 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 function getIndexKey(path) {
+    const trimmed = path.startsWith("/") ? path.slice(1) : path;
+    if (trimmed.length === 0)
+        return "/";
+    // The FIRST separator ends the segment. A split of the whole path allocated one string
+    // for each segment, and this function runs on every lookup of `RouteMap`.
+    const end = trimmed.indexOf("/");
+    return end === -1 ? trimmed : trimmed.slice(0, end);
+}
+/** The characters that start a param name. */
+const NAME_START_RE = /[A-Za-z_$]/;
+/**
+ * The characters that continue a param name.
+ *
+ * The hyphen is the divergence from URLPattern that the module comment states. It is
+ * here, and in {@link ParsedPattern.normalized}, and nowhere else.
+ */
+const NAME_PART_RE = /[A-Za-z0-9_$-]/;
+/** The modifiers, as the parser meets them after a part. */
+const MODIFIERS = new Set(["?", "+", "*"]);
+/**
+ * The character that a param absorbs from the literal before it.
+ *
+ * URLPattern calls it the prefix code point, and for a pathname it is `/`. The parser
+ * moves it INTO the param, so that a `?` or a `*` modifier removes the separator
+ * together with the value. That is the whole reason `/settings/:section?` matches
+ * `/settings` and not `/settings/`.
+ */
+const PREFIX = "/";
+/**
+ * The parse of the patterns that this module read last, kept at the module level.
+ *
+ * A route pattern is a static string of the route map, so the answer for one pattern
+ * never changes and the cache pays for itself.
+ *
+ * The cache is BOUNDED even so, because two callers hand it a string that no route map
+ * holds. `RouterBridgeBase` resolves the escape of an actor route in
+ * `resolveNavigationPath` and in `isActorAtPath`, and an actor route is a concrete
+ * location — one for each value that an application puts in a param. Both callers reach
+ * the parse only for a route that carries a BACKSLASH, which no ordinary location does,
+ * and `holdsUnsubstitutedParam` answers the question that took the plain path of every
+ * navigation before.
+ *
+ * A bound removes the whole class anyway. An unbounded map grew for the life of the page,
+ * one entry for each location an application visited, and the eviction costs one re-parse
+ * of a pattern that fell out — the trade `RouteMap` already makes for its path-match
+ * cache.
+ */
+const parseCache = createPatternCache(500);
+/**
+ * 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 function parsePattern(pattern, options) {
+    const cache = options?.patternCache ?? parseCache;
+    const cached = cache.get(pattern);
+    if (cached)
+        return cached;
+    const parsed = readPattern(pattern);
+    cache.set(pattern, parsed);
+    return parsed;
+}
+/**
+ * Reads the pattern into parts, and builds the normalized form in the same pass.
+ *
+ * One pass gives both, and that is what keeps them together: the normalized form carries
+ * the source of every part without a change, and the rewritten name of each param. A
+ * second pass with an expression of its own rewrote a name that the parser reads as a
+ * literal, which is the defect this module exists to end.
+ */
+function readPattern(source) {
+    const root = { parts: [], pending: "", escapedTail: false };
+    const stack = [];
+    let frame = root;
+    let normalized = "";
+    const declaredNames = new Map();
+    let malformed = false;
+    /**
+     * True when the pattern carries an escape, for example `/x\:lit`.
+     *
+     * Such a pattern is a literal path, and the parts report it as one. It must still
+     * reach URLPattern: the exact-match map of `RouteMap` keys on the pattern string AS
+     * WRITTEN, so it would hold `/x\:lit` and answer the path `/x:lit` never.
+     */
+    let escaped = false;
+    let index = 0;
+    /** Moves the pending literal characters into the frame as one part. */
+    function flush() {
+        frame.escapedTail = false;
+        if (frame.pending === "")
+            return;
+        frame.parts.push({ kind: "literal", text: frame.pending });
+        frame.pending = "";
+    }
+    /**
+     * Takes the `/` that a param absorbs, and flushes what stays behind it.
+     *
+     * A GROUP takes no prefix. `/a{/b}?/c` writes the separator inside the group itself,
+     * and `/a/{b}?/c` keeps it outside, which is why the second one matches `/a//c`.
+     */
+    function takePrefix() {
+        // An ESCAPED separator belongs to the literal, and no param takes it. `/x\\/:id?`
+        // therefore matches `/x/` and not `/x`, and the bare form has to say so.
+        if (frame.escapedTail || !frame.pending.endsWith(PREFIX)) {
+            flush();
+            return "";
+        }
+        frame.pending = frame.pending.slice(0, -PREFIX.length);
+        flush();
+        return PREFIX;
+    }
+    /** Reads a modifier when one follows the part that the parser just added. */
+    function readModifier() {
+        const next = source.at(index);
+        if (next !== undefined && MODIFIERS.has(next)) {
+            index += 1;
+            return next;
+        }
+        return "";
+    }
+    while (index < source.length) {
+        const char = source.at(index);
+        if (char === "\\") {
+            // The escape keeps its backslash in the normalized form, and it drops it in the
+            // literal text: the text is what a bare form must carry, and a path carries the
+            // escaped character alone.
+            const literal = source.at(index + 1);
+            if (literal === undefined) {
+                malformed = true;
+                normalized += char;
+                index += 1;
+                break;
+            }
+            escaped = true;
+            frame.pending += literal;
+            frame.escapedTail = true;
+            normalized += char + literal;
+            index += 2;
+            continue;
+        }
+        if (char === "{") {
+            flush();
+            stack.push(frame);
+            frame = { parts: [], pending: "", escapedTail: false };
+            normalized += char;
+            index += 1;
+            continue;
+        }
+        if (char === "}") {
+            const parent = stack.pop();
+            if (parent === undefined) {
+                // A close with no open. Keep it as a literal and let URLPattern report the
+                // fault, because the API owns the error message of an invalid pattern.
+                malformed = true;
+                frame.pending += char;
+                frame.escapedTail = false;
+                normalized += char;
+                index += 1;
+                continue;
+            }
+            flush();
+            const parts = frame.parts;
+            frame = parent;
+            normalized += char;
+            index += 1;
+            const modifier = readModifier();
+            normalized += modifier;
+            frame.parts.push({ kind: "group", parts, modifier });
+            continue;
+        }
+        if (char === ":") {
+            const name = readName(source, index + 1);
+            if (name === "") {
+                // A `:` that no name follows. URLPattern refuses every such pattern — `/x/:`,
+                // `/a:` and `/time/10:30` all fail in the constructor — so the fault belongs to
+                // the API. A parser that kept the character as a literal called the pattern
+                // static, and `RouteMap` then registered `/time/10:30` in its exact-match map,
+                // where the route matched the path it declares and reported no fault. Write
+                // `\\:` when you mean the character itself.
+                malformed = true;
+                frame.pending += char;
+                frame.escapedTail = false;
+                normalized += char;
+                index += 1;
+                continue;
+            }
+            index += 1 + name.length;
+            const prefix = takePrefix();
+            const regexp = source.at(index) === "(" ? readRegexp(source, index) : null;
+            if (regexp !== null)
+                index += regexp.length + 2;
+            const modifier = readModifier();
+            const groupName = name.replace(/-/g, "_");
+            if (groupName !== name)
+                declaredNames.set(groupName, name);
+            normalized += `:${groupName}${regexp === null ? "" : `(${regexp})`}${modifier}`;
+            frame.parts.push({ kind: "param", name, groupName, regexp, prefix, modifier });
+            continue;
+        }
+        if (char === "(") {
+            const regexp = readRegexp(source, index);
+            if (regexp === null) {
+                // An open with no close. The same reason as the stray `}` above.
+                malformed = true;
+                frame.pending += char;
+                frame.escapedTail = false;
+                normalized += char;
+                index += 1;
+                continue;
+            }
+            index += regexp.length + 2;
+            const prefix = takePrefix();
+            const modifier = readModifier();
+            normalized += `(${regexp})${modifier}`;
+            frame.parts.push({
+                kind: "param",
+                name: null,
+                groupName: null,
+                regexp,
+                prefix,
+                modifier,
+            });
+            continue;
+        }
+        if (char === "*") {
+            index += 1;
+            const prefix = takePrefix();
+            const modifier = readModifier();
+            normalized += `*${modifier}`;
+            frame.parts.push({
+                kind: "param",
+                name: null,
+                groupName: null,
+                regexp: null,
+                prefix,
+                modifier,
+            });
+            continue;
+        }
+        // A `?` or a `+` that reaches this point follows no part, and URLPattern refuses
+        // every such pattern — the native API and the polyfill both. A parser that kept it
+        // as a literal sent `/settings?` to the exact-match map of `RouteMap`, where
+        // `getStateIdByPath` reaches it never: the lookup cuts the path at its `?` first.
+        // Report the fault instead, and let the API name it.
+        if (char === "?" || char === "+")
+            malformed = true;
+        frame.pending += char;
+        frame.escapedTail = false;
+        normalized += char;
+        index += 1;
+    }
+    flush();
+    // An open group that no `}` closed. Its parts belong to the pattern, and the fault
+    // belongs to URLPattern.
+    while (stack.length > 0) {
+        malformed = true;
+        const parts = frame.parts;
+        const parent = stack.pop();
+        /* c8 ignore next */
+        if (parent === undefined)
+            break;
+        frame = parent;
+        flush();
+        frame.parts.push({ kind: "group", parts, modifier: "" });
+    }
+    const parts = root.parts;
+    const params = [];
+    collectParams(parts, false, params);
+    // The cache holds this object for the life of the process, and `parsePattern` hands the
+    // SAME arrays to every caller. The freeze makes that safe to do: a caller cannot write
+    // into the answer of the next one. The accessors copied an array for this reason, and
+    // the freeze replaces the copy.
+    //
+    // `declaredNames` carries the same promise through its TYPE alone. `Object.freeze`
+    // stops no `Map.prototype.set`, so a freeze of it would say nothing, and a copy for
+    // each caller would allocate a map that the common pattern leaves empty. Treat it as
+    // read-only, as {@link ParsedPattern} states for every field.
+    return {
+        source,
+        parts: freezeParts(parts),
+        params: Object.freeze(params.map((param) => Object.freeze(param))),
+        names: Object.freeze(params.map((param) => param.name)),
+        requiredNames: Object.freeze(params.filter((param) => !param.optional).map((param) => param.name)),
+        parameterized: malformed || escaped || parts.some(isNotLiteral),
+        bareForm: malformed ? null : buildBareForm(parts),
+        literalPath: malformed ? null : buildLiteralPath(parts),
+        indexKey: readIndexKey(parts),
+        normalized,
+        declaredNames,
+    };
+}
+/**
+ * Reads a param name from `start`, or `""` when no name stands there.
+ *
+ * Every character read of this module calls `String.at`, and not a bracket index. The
+ * two answer the same way for a non-negative index, and the method form says that the
+ * read is a CHARACTER of a string and not a property of an object — which is also what
+ * the object-injection rule of the security scan asks for.
+ */
+function readName(source, start) {
+    const first = source.at(start);
+    if (first === undefined || !NAME_START_RE.test(first))
+        return "";
+    let end = start + 1;
+    while (end < source.length && NAME_PART_RE.test(source.at(end) ?? ""))
+        end += 1;
+    // A trailing hyphen belongs to the literal that follows, and not to the name:
+    // `/x/:id-` declares the param `id` and the literal `-`.
+    let name = source.slice(start, end);
+    while (name.endsWith("-"))
+        name = name.slice(0, -1);
+    return name;
+}
+/**
+ * Reads the source of a `(…)` constraint that starts at `open`, or `null` when no `)`
+ * closes it.
+ *
+ * The reader counts the nesting and it honours an escape, so `([a-z]{2,3})` and `(\()`
+ * both come back whole. A `{` inside a constraint is an ordinary character, and a parser
+ * that treated it as a group opened one that nothing closes.
+ */
+function readRegexp(source, open) {
+    let depth = 0;
+    for (let cursor = open; cursor < source.length; cursor += 1) {
+        const char = source.at(cursor);
+        if (char === "\\") {
+            cursor += 1;
+            continue;
+        }
+        if (char === "(")
+            depth += 1;
+        else if (char === ")") {
+            depth -= 1;
+            if (depth === 0)
+                return source.slice(open + 1, cursor);
+        }
+    }
+    return null;
+}
+/** True for every part that needs a URLPattern match. */
+function isNotLiteral(part) {
+    return part.kind !== "literal";
+}
+/** A modifier that lets a path carry no value for the part. */
+function makesOptional(modifier) {
+    return modifier === "?" || modifier === "*";
+}
+/** Collects every NAMED param, and carries the optionality of each group into it. */
+function collectParams(parts, insideOptionalGroup, into) {
+    for (const part of parts) {
+        if (part.kind === "literal")
+            continue;
+        if (part.kind === "group") {
+            collectParams(part.parts, insideOptionalGroup || makesOptional(part.modifier), into);
+            continue;
+        }
+        // An ANONYMOUS param stays out of the list. URLPattern numbers it from `0`, no
+        // framework router reports such a name, and `resolveFrameworkParams` answers `{}`
+        // for a pattern that declares no name — which is what a bare `*` route means to a
+        // machine. The bare form below still counts it, because `/docs/*` matches `/docs`
+        // never.
+        if (part.name === null || part.groupName === null)
+            continue;
+        into.push({
+            name: part.name,
+            groupName: part.groupName,
+            optional: insideOptionalGroup || makesOptional(part.modifier),
+        });
+    }
+}
+/**
+ * Freezes the parts of one frame, and the parts of every group inside it.
+ *
+ * `Object.freeze` reaches ONE level, and a group carries an array of its own. A caller
+ * that reads `parts[0].parts` would receive a mutable array without this walk, and a
+ * write into it would reach every later reader of the same cached parse.
+ */
+function freezeParts(parts) {
+    for (const part of parts) {
+        if (part.kind === "group")
+            freezeParts(part.parts);
+        Object.freeze(part);
+    }
+    return Object.freeze(parts);
+}
+/**
+ * Builds the path that the pattern matches with every optional part absent, or `null`
+ * when some part needs a value.
+ *
+ * The walk drops an optional part TOGETHER with the `/` that it absorbed, which is the
+ * prefix rule of the module comment.
+ */
+function buildBareForm(parts) {
+    let bare = "";
+    for (const part of parts) {
+        if (part.kind === "literal") {
+            bare += part.text;
+            continue;
+        }
+        if (makesOptional(part.modifier))
+            continue;
+        if (part.kind === "param")
+            return null;
+        const inner = buildBareForm(part.parts);
+        if (inner === null)
+            return null;
+        bare += inner;
+    }
+    return bare;
+}
+/** The name that an anonymous param reports when it has no value. */
+const ANONYMOUS = "(anonymous)";
+/**
+ * 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 function buildPath(pattern, params = {}, options) {
+    const walked = walkParts(parsePattern(pattern, options).parts, params);
+    if (!walked.ok)
+        return walked;
+    const offending = findUnresolvable(walked.path, walked.marks);
+    if (offending) {
+        return {
+            ok: false,
+            reason: "unresolvable",
+            param: offending.param,
+            value: offending.value,
+        };
+    }
+    return { ok: true, path: walked.path };
+}
+/**
+ * Answers the param that writes a segment which resolves away, or `null` when none does.
+ *
+ * The test reads the ASSEMBLED segment, and not the value on its own. `/files/v:version`
+ * with the value `"."` writes the segment `"v."`, which names itself and which the same
+ * pattern matches back; a test of the value alone refused it. Only a value that stands as
+ * the WHOLE segment can resolve that segment away.
+ *
+ * A segment of dots that NO param writes belongs to the pattern itself. The walk keeps it:
+ * the author of the pattern wrote it, and this function answers for the values of a caller.
+ */
+function findUnresolvable(path, marks) {
+    let start = 0;
+    for (const segment of path.split("/")) {
+        const end = start + segment.length;
+        if (isDotSegment(segment)) {
+            const mark = marks.find((candidate) => candidate.start < end && start < candidate.end);
+            if (mark)
+                return mark;
+        }
+        start = end + 1;
+    }
+    return null;
+}
+/** Walks the parts of one frame. A group opens a frame of its own. */
+function walkParts(parts, params) {
+    let path = "";
+    const marks = [];
+    for (const part of parts) {
+        if (part.kind === "literal") {
+            // The text carries every escape resolved already, so `/tags/c\+\+` writes `c++`.
+            path += part.text;
+            continue;
+        }
+        if (part.kind === "param") {
+            const value = readValue(part, params);
+            if (value !== null) {
+                // The span of the VALUE alone, and not of the prefix: `findUnresolvable` asks
+                // whether the value stands as the whole segment.
+                path += part.prefix;
+                const start = path.length;
+                path += encodeValue(value, part);
+                marks.push({ start, end: path.length, param: part.name ?? ANONYMOUS, value });
+                continue;
+            }
+            // `?` and `*` mean zero or more, so the part goes away with its prefix. The
+            // modifier `+` needs one value, and so does a param that carries no modifier.
+            if (makesOptional(part.modifier))
+                continue;
+            return { ok: false, reason: "missing", missing: part.name ?? ANONYMOUS };
+        }
+        const inner = walkParts(part.parts, params);
+        if (inner.ok) {
+            // A group opens a frame of its own, so its marks count from ITS first character.
+            // Rebase them onto this frame as the group text joins the path.
+            const base = path.length;
+            path += inner.path;
+            for (const mark of inner.marks) {
+                marks.push({ ...mark, start: mark.start + base, end: mark.end + base });
+            }
+            continue;
+        }
+        // A group that needs a value it does not have goes away WHOLE when the group carries
+        // an optional modifier. `/books{/:id}?` with no `id` therefore builds `/books`.
+        if (makesOptional(part.modifier))
+            continue;
+        return inner;
+    }
+    return { ok: true, path, marks };
+}
+/**
+ * Reads the value of one param, or `null` when the param has none.
+ *
+ * An EMPTY string counts as no value. An optional param with an empty value then goes
+ * away, rather than writing a separator with nothing behind it.
+ */
+function readValue(part, params) {
+    if (part.name === null)
+        return null;
+    if (!Object.hasOwn(params, part.name))
+        return null;
+    // nosemgrep: gitlab.eslint.detect-object-injection
+    const raw = params[part.name];
+    if (raw === undefined || raw === null)
+        return null;
+    const value = String(raw);
+    // A param that carries `*` or `+` holds a PATH, and an empty segment of that path
+    // names nothing: `/docs/intro` and `docs/intro/` and `a//b` each describe the same
+    // sequence of segments as `docs/intro` and `a/b`. The walk drops the empty segments,
+    // because the pattern can express none of them — `/files/:path*` with `/docs/intro`
+    // built `/files//docs/intro` before, which its OWN route matches never.
+    //
+    // The normalization belongs to the VALUE, and not to the built path. A `{…}` group
+    // writes a doubled separator legitimately — `/a/{b}?/c` matches `/a//c` — so a collapse
+    // of the whole path would break the bare form that the match reads.
+    if (part.modifier === "*" || part.modifier === "+") {
+        const segments = value.split("/").filter((segment) => segment !== "");
+        return segments.length === 0 ? null : segments.join("/");
+    }
+    return value === "" ? null : value;
+}
+/**
+ * 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 function isDotSegment(segment) {
+    const dots = segment.toLowerCase().replaceAll("%2e", ".");
+    return dots === "." || dots === "..";
+}
+/**
+ * Percent-encodes one value, and the modifier decides how much of it.
+ *
+ * A param that carries `*` or `+` matches ACROSS a separator, so its value holds a PATH
+ * and not a segment: `/files/:path*` with `a/b` must build `/files/a/b`. The walk encodes
+ * each segment of such a value and keeps the separators between them.
+ * `encodeURIComponent` over the whole value wrote `a%2Fb`, which the pattern reads back
+ * as ONE segment named `a/b`, and a round trip that changes the value is no round trip.
+ */
+function encodeValue(value, part) {
+    if (part.modifier === "*" || part.modifier === "+") {
+        return value.split("/").map(encodeURIComponent).join("/");
+    }
+    return encodeURIComponent(value);
+}
+/**
+ * Builds the one path that the pattern matches, or `null` when it matches more than one.
+ *
+ * The walk resolves each escape, because {@link LiteralPart.text} already holds the
+ * character alone. A param carries a value that the pattern does not hold, and a modifier
+ * makes its part repeat or disappear: either one describes a SET of paths, and the walk
+ * answers `null` for it.
+ */
+function buildLiteralPath(parts) {
+    let path = "";
+    for (const part of parts) {
+        if (part.kind === "literal") {
+            path += part.text;
+            continue;
+        }
+        if (part.kind === "param" || part.modifier !== "")
+            return null;
+        const inner = buildLiteralPath(part.parts);
+        if (inner === null)
+            return null;
+        path += inner;
+    }
+    return path;
+}
+/**
+ * Reads the key of the bucket index from the parts: the first path segment.
+ *
+ * The key is `"*"` when a param can stand in the first segment, because the concrete
+ * path then carries a segment that the pattern does not name. `getIndexKey` computes the
+ * same key from a concrete path, and the two must agree: a pattern in the wrong bucket
+ * is a route that matches nothing.
+ */
+function readIndexKey(parts) {
+    const first = parts[0];
+    if (first === undefined)
+        return "/";
+    if (first.kind !== "literal")
+        return "*";
+    // The literal reaches past the first separator, so the first segment is complete and
+    // every part after it belongs to a later segment.
+    const complete = first.text.slice(1).includes("/");
+    if (complete)
+        return getIndexKey(first.text);
+    // The literal is the ROOT separator alone, so it opens no segment of its own: the part
+    // after it fills the first segment, or it starts with a `/` and leaves that segment
+    // EMPTY. `getIndexKey` answers `"/"` for the path `"/"` and `""` for the path `"//x"`,
+    // so neither key covers the whole set, and `/{/v2}` sat in a bucket that the path
+    // `//v2` reaches never. The wildcard key covers it: a lookup joins that bucket with
+    // the bucket of its own first segment.
+    if (first.text === PREFIX && parts.length > 1)
+        return "*";
+    // The literal ends inside the first segment, so a part that adds characters to that
+    // segment makes the key unknown. A group that opens with the separator adds none, and
+    // `/books{/:id}?` therefore keeps the literal key `books`.
+    //
+    // The walk reads past every OPTIONAL part, and it stops at the first part that a path
+    // must carry. A test of the next part alone read `/x{/:a}?-b` as the key `x`, while the
+    // path of its bare form is `/x-b` and gives the key `x-b`: the route sat in a bucket
+    // that no path reaches, which is the same defect as the `books{` key of the split.
+    // `Array.at`, for the reason that {@link readName} gives for `String.at`: the read is an
+    // ELEMENT and not a property, and the method form says so. A `slice(1)` said it too,
+    // and it allocated a copy of every part to skip one.
+    for (let index = 1; index < parts.length; index += 1) {
+        const part = parts.at(index);
+        /* c8 ignore next */
+        if (part === undefined)
+            break;
+        // A group with no part of its own carries no character, so it ends nothing and it
+        // decides nothing. A break on it read `/c{}\+` as the key `c`, while the path
+        // `/c+` that the pattern matches gives the key `c+`.
+        if (part.kind === "group" && part.parts.length === 0)
+            continue;
+        if (continuesFirstSegment(part))
+            return "*";
+        if (!isOptionalPart(part))
+            break;
+    }
+    return getIndexKey(first.text);
+}
+/** True when a matching path can carry no characters for the part. */
+function isOptionalPart(part) {
+    return part.kind !== "literal" && makesOptional(part.modifier);
+}
+/** True when the part can add characters to the first path segment. */
+function continuesFirstSegment(part) {
+    if (part.kind === "param")
+        return part.prefix === "";
+    if (part.kind === "literal")
+        return !part.text.startsWith("/");
+    const first = part.parts[0];
+    if (first === undefined)
+        return false;
+    if (first.kind === "literal")
+        return !first.text.startsWith("/");
+    return first.kind !== "param" || first.prefix === "";
+}
+//# sourceMappingURL=pattern-grammar.js.map