@orkestrel/router 0.0.13 → 0.0.14

package/dist/src/core/index.d.ts

@@ -1,10 +1,10 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
 
 /**
- * Represents the native-override seam — a predicate deciding whether an entry's `meta`
- * ANSWERS a given `match` call, beyond path matching.
+ * Represents the native-override seam — a predicate deciding whether an entry's
+ * `meta` answers a given `match` call, beyond path matching.
  *
  * @typeParam Meta - The entry payload the predicate reads
  *
@@ -19,7 +19,7 @@ import { EmitterInterface } from '@orkestrel/emitter';
 export declare type AnswerHandler<Meta> = (meta: Meta) => boolean;
 
 /**
- * Canonicalizes a route path for REGISTRY IDENTITY — strips a single trailing
+ * Canonicalizes a route path for registry identity — strips a single trailing
  * slash, except the root `/` (and the empty pattern). The trailing-slash fold
  * {@link compilePath} normalizes a pattern through, so identity agrees with the
  * matcher.
@@ -45,11 +45,11 @@ export declare type AnswerHandler<Meta> = (meta: Meta) => boolean;
 export declare function canonicalizePath(path: string): string;
 
 /**
- * Classifies one path segment into its specificity TIER — the SAME syntax
- * {@link compilePath} rewrites: a syntactically valid `:name` head is a PARAM
- * segment, a final `*name` is a WILDCARD segment, everything else (including a
- * literal segment that merely CONTAINS a `:` mid-string, for example `a:b`) is a
- * LITERAL segment.
+ * Classifies one path segment into its specificity tier — the same syntax
+ * {@link compilePath} rewrites: a syntactically valid `:name` head is a param
+ * segment, a final `*name` is a wildcard segment, and everything else (including a
+ * literal segment that merely contains a `:` mid-string, for example `a:b`) is a
+ * literal segment.
  *
  * @remarks
  * This is the fix over the old engine's bug: the old classifier ranked any
@@ -77,7 +77,7 @@ export declare function canonicalizePath(path: string): string;
 export declare function classifySegment(segment: string, isFinal: boolean): number;
 
 /**
- * Compares two route paths by SPECIFICITY — the comparator that picks the
+ * Compares two route paths by specificity — the comparator that picks the
  * most-specific matching route (literal-over-param-over-wildcard,
  * registration-order-independent).
  *
@@ -168,7 +168,8 @@ export declare interface CompiledPath {
  export declare function compilePath(path: string, sensitive?: boolean): CompiledPath;
 
  /**
-  * Computes the registry key for a method-dimensioned dispatcher route.
+  * Computes the canonical `METHOD /path` registry key for a method-dimensioned
+  * dispatcher route.
   *
   * @remarks
   * Combines the route record's HTTP method with the outer entry's canonical
@@ -188,7 +189,7 @@ export declare interface CompiledPath {
  }>): string;
 
  /**
-  * Computes a route path's SPECIFICITY VECTOR — the per-segment type ranking
+  * Computes a route path's specificity vector — the per-segment type ranking
   * that breaks a tie when several registered routes match the same concrete
   * pathname.
   *
@@ -220,8 +221,8 @@ export declare interface CompiledPath {
  export declare function computeSpecificity(path: string): readonly number[];
 
  /**
-  * Creates a {@link DispatcherInterface} — the fetch-standard, method-
-  * dimensioned dispatch entity over one internal `Router<RouteRecord<TState>>`.
+  * Creates a {@link DispatcherInterface} — the fetch-standard,
+  * method-dimensioned dispatch entity over one internal `Router<RouteRecord<TState>>`.
   *
   * @remarks
   * Prefer this over `new Dispatcher(...)` at call sites that only need the
@@ -262,19 +263,30 @@ export declare interface CompiledPath {
   *   (default `true`), and a `key` dedup identity function
   * @returns A {@link RouterInterface}
   *
-  * @example
+  * @example Register and match
   * ```ts
-  * import { createRouter } from '@src/core'
+  * import { createDispatcher, createRouter } from '@orkestrel/router'
   *
   * const router = createRouter<{ readonly page: string }>()
   * router.add({ path: '/users/:id', meta: { page: 'profile' } })
   * router.match('/users/7') // { path: '/users/:id', params: { id: '7' }, meta: { page: 'profile' } }
+  *
+  * const dispatcher = createDispatcher<{ readonly userId: string }>({
+  * 	routes: [
+  * 		{
+  * 			method: 'GET',
+  * 			path: '/users/:id',
+  * 			handler: (_request, context) => Response.json(context.params),
+  * 		},
+  * 	],
+  * })
+  * const response = await dispatcher.handle(new Request('http://x/users/7'), { userId: 'me' })
   * ```
   */
  export declare function createRouter<Meta>(options?: RouterOptions<Meta>): RouterInterface<Meta>;
 
  /**
-  * URL-decodes one captured param value, tolerating a malformed percent-escape —
+  * Decodes one captured param value from a URL, tolerating a malformed percent-escape —
   * the decode {@link matchPath} applies to each captured group.
   *
   * @remarks
@@ -296,8 +308,8 @@ export declare interface CompiledPath {
  export declare function decodeParam(value: string): string;
 
  /**
-  * Provides an identity pass-through for a {@link RouteInput} that pins its `Path` generic
-  * to the LITERAL registration-site string, so `context.params` types
+  * Provides an identity pass-through for a {@link RouteInput} that pins its `Path`
+  * generic to the literal registration-site string, so `context.params` types
   * correctly through {@link PathParams} without an explicit type argument.
   *
   * @remarks
@@ -335,10 +347,10 @@ export declare interface CompiledPath {
  export declare function defineRoute<const Path extends string, TState = undefined>(input: RouteInput<Path, TState>): RouteInput<Path, TState>;
 
  /**
-  * Represents the fetch-standard, method-dimensioned dispatch entity — layers HTTP method
-  * dispatch and web-standard `Request`/`Response` handling over one internal
-  * `Router<RouteRecord<TState>>`. The core machine the eventual server face
-  * and any fetch-native runtime consumes directly.
+  * Represents the fetch-standard, method-dimensioned dispatch entity — layers HTTP
+  * method dispatch and web-standard `Request`/`Response` handling over one internal
+  * `Router<RouteRecord<TState>>`. The core machine the server face and any
+  * fetch-native runtime consume directly.
   *
   * @typeParam TState - The consumer's opaque per-request state type
   *
@@ -416,35 +428,50 @@ export declare interface CompiledPath {
   *   into every {@link RouteContext} (default `undefined` for stateless use)
   *
   * @remarks
-  * - `router` — the underlying registry, exposed READONLY for introspection
-  *   (the same object `add`/`group`/`match` operate on).
-  * - `emitter` — the observable surface for {@link DispatcherEventMap}.
-  * - `add(input)` / `add(inputs)` — register ONE / MANY {@link RouteInput}s
-  *   (batch registration); throws a `ContractError` on a malformed registration (a
-  *   non-`/`-prefixed path, a non-function handler, or a method outside
-  *   {@link import('./constants.js').METHODS}) — the construction/registration
-  *   boundary guard; `match`/`handle` hot paths carry zero guards.
-  * - `group(prefix)` — a {@link DispatchGroupInterface} scoped under `prefix`.
-  * - `match(method, pathname)` — the raw {@link DispatchResult} for a method +
-  *   pathname pair, with no `Request`/`Response` involvement — the pure
-  *   decision `handle` builds its response from.
-  * - `handle(request, state)` — the full dispatch: parses `request.url`,
-  *   calls `match`, and either invokes the winning handler (auto-stripping
-  *   the body for a derived `HEAD`, auto-answering a derived `OPTIONS` with
-  *   the `Allow` set), or invokes the `unmatched`/`unmethoded` responder.
-  *   Emits `match`/`miss` accordingly. A handler throw propagates uncaught.
-  * - `destroy()` — tears down the `#emitter`; the underlying
-  *   router is left registered (not cleared) so introspection remains valid
-  *   after destroy.
+  * Registration is the guarded boundary: `add` throws on a malformed registration,
+  * while the `match` and `handle` hot paths carry no guard of their own.
   */
  export declare interface DispatcherInterface<TState = undefined> {
+     /**
+      * Holds the underlying registry, exposed readonly for introspection — the same
+      * object `add`, `group`, and `match` operate on.
+      */
      readonly router: RouterInterface<RouteRecord<TState>>;
+     /** Holds the observable surface for {@link DispatcherEventMap}. */
      readonly emitter: EmitterInterface<DispatcherEventMap>;
+     /**
+      * Registers one route input, or many in one call (batch registration); throws a
+      * `ContractError` on a malformed registration.
+      *
+      * @remarks
+      * A registration is malformed when its path is not `/`-prefixed, its handler is not
+      * a function, or its method sits outside {@link import('./constants.js').METHODS}.
+      * Path validation is delegated to the underlying router's own guard.
+      */
      add<Path extends string>(input: RouteInput<Path, TState>): void;
      add(inputs: ReadonlyArray<RouteInput<string, TState>>): void;
+     /** Returns a prefix-scoped registration handle over this dispatcher. */
      group(prefix: string): DispatchGroupInterface<TState>;
+     /**
+      * Decides the raw {@link DispatchResult} for a method and pathname pair, with no
+      * `Request` or `Response` involvement — the pure decision `handle` builds its
+      * response from.
+      */
      match(method: Method, pathname: string): DispatchResult<TState>;
+     /**
+      * Runs the full dispatch: parses the request URL, matches, and invokes either the
+      * winning handler or the `unmatched`/`unmethoded` responder.
+      *
+      * @remarks
+      * A derived `HEAD` runs the matching `GET` handler with the response body stripped,
+      * and a derived `OPTIONS` answers with the `Allow` set. Emits `match` or `miss`
+      * accordingly. A handler throw propagates uncaught.
+      */
      handle(request: Request, state: TState): Promise<Response>;
+     /**
+      * Tears down the emitter; the underlying router is left registered rather than
+      * cleared, so introspection stays valid afterwards.
+      */
      destroy(): void;
  }
 
@@ -479,8 +506,8 @@ export declare interface CompiledPath {
 
  /**
   * Represents a prefix-scoped registration handle over a
-  * {@link import('./Dispatcher.js').Dispatcher} — the method-dimensioned
-  * counterpart of `Group` (`Group.ts`).
+  * {@link import('./Dispatcher.js').Dispatcher} — the method-dimensioned counterpart of
+  * `Group`.
   *
   * @typeParam TState - The consumer's opaque per-request state type, matching
   *   the owning dispatcher
@@ -517,25 +544,32 @@ export declare interface CompiledPath {
   *   the owning dispatcher
   *
   * @remarks
-  * - `prefix` — the path prefix this group prepends to every route it
-  *   registers (and to every nested group's own prefix).
-  * - `add(input)` / `add(inputs)` — register ONE / MANY {@link RouteInput}s on
-  *   the OWNING dispatcher, each input's `path` composed as
-  *   `prefix + input.path` (batch registration, mirroring
-  *   {@link DispatcherInterface.add}).
-  * - `group(prefix)` — a nested group whose prefix is `this.prefix + prefix`.
+  * Nesting composes prefixes left to right with no depth limit.
   */
  export declare interface DispatchGroupInterface<TState> {
+     /**
+      * Holds the path prefix this group prepends to every route it registers, and to
+      * every nested group's own prefix.
+      */
      readonly prefix: string;
+     /**
+      * Registers one route input, or many in one call, on the owning dispatcher with this
+      * group's prefix composed onto each path.
+      *
+      * @remarks
+      * Batch registration mirrors {@link DispatcherInterface.add}, and the owning
+      * dispatcher's own registration guard still applies.
+      */
      add<Path extends string>(input: RouteInput<Path, TState>): void;
      add(inputs: ReadonlyArray<RouteInput<string, TState>>): void;
+     /** Returns a nested group whose prefix is this prefix followed by the given one. */
      group(prefix: string): DispatchGroupInterface<TState>;
  }
 
  /**
-  * Represents the outcome of {@link DispatcherInterface.match} — a discriminated union
-  * over the dispatch tiers: a full hit, a path-matches-but-method-
-  * doesn't (405 territory), or nothing matched at all (404 territory).
+  * Represents the outcome of {@link DispatcherInterface.match} — a discriminated
+  * union over the dispatch tiers: a full hit, a path that matches with no route for
+  * the method (405 territory), or nothing matched at all (404 territory).
   *
   * @typeParam TState - The consumer's opaque per-request state type
   *
@@ -616,33 +650,51 @@ export declare interface CompiledPath {
   * @typeParam Meta - The entry payload type, matching the owning router
   *
   * @remarks
-  * - `prefix` — the path prefix this group prepends to every entry it
-  *   registers (and to every nested group's own prefix).
-  * - `add(entry)` / `add(entries)` — register ONE / MANY entries on the
-  *   OWNING router, each entry's `path` composed as `prefix + entry.path`
-  *   (batch registration, mirroring {@link RouterInterface.add}).
-  * - `group(prefix)` — a nested group whose prefix is `this.prefix + prefix`;
-  *   nesting composes prefixes left to right with no depth limit.
+  * Nesting composes prefixes left to right with no depth limit.
   */
  export declare interface GroupInterface<Meta> {
+     /**
+      * Holds the path prefix this group prepends to every entry it registers, and to
+      * every nested group's own prefix.
+      */
      readonly prefix: string;
+     /**
+      * Registers one entry, or many in one call, on the owning router with this group's
+      * prefix composed onto each path.
+      *
+      * @remarks
+      * Batch registration mirrors {@link RouterInterface.add}, and the owning router's own
+      * registration guard still applies.
+      */
      add(entry: RouteEntry<Meta>): void;
      add(entries: ReadonlyArray<RouteEntry<Meta>>): void;
+     /** Returns a nested group whose prefix is this prefix followed by the given one. */
      group(prefix: string): GroupInterface<Meta>;
  }
 
  /**
-  * Names the identifier CONTINUATION characters after the first — mirrors the
+  * Names the identifier continuation characters after the first — mirrors the
   * runtime classifier's `[A-Za-z0-9_]*` tail class.
   */
  export declare type IdentifierChar = IdentifierStartChar | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
 
+ /**
+  * Captures the identifier at the front of a string literal, or an empty string when the
+  * literal does not begin with an identifier-start char.
+  *
+  * @typeParam S - The string literal to read the head from
+  *
+  * @remarks
+  * The type-level mirror of the runtime head match anchored on an identifier-start char:
+  * an {@link IdentifierStartChar} opens the run and {@link TakeIdentifierTail} consumes
+  * the rest of it.
+  */
  export declare type IdentifierHead<S extends string> = S extends `${infer Head}${infer Tail}` ? Head extends IdentifierStartChar ? TakeIdentifierTail<Tail, Head> : '' : '';
 
  /**
-  * Names the identifier START characters an identifier-grammar param name may
-  * begin with — mirrors the runtime classifier's `[A-Za-z_]` head class
-  * (`classifySegment` / `compilePath`, `helpers.ts`).
+  * Names the identifier start characters an identifier-grammar param name may begin
+  * with — mirrors the runtime classifier's `[A-Za-z_]` head class, the one
+  * `classifySegment` and `compilePath` share.
   */
  export declare type IdentifierStartChar = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | '_';
 
@@ -700,9 +752,9 @@ export declare interface CompiledPath {
  export declare function matchPath(compiled: CompiledPath, pathname: string): Readonly<Record<string, string>> | undefined;
 
  /**
-  * Names the HTTP methods a {@link DispatcherInterface} dimensions dispatch
-  * over — derived from {@link import('./constants.js').METHOD_LIST}, whose
-  * membership counterpart is {@link import('./constants.js').METHODS}.
+  * Names the HTTP methods a {@link DispatcherInterface} dimensions dispatch over —
+  * derived from {@link import('./constants.js').METHOD_LIST}, whose membership
+  * counterpart is {@link import('./constants.js').METHODS}.
   *
   * @remarks
   * Resolves to `'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' |
@@ -715,10 +767,10 @@ export declare interface CompiledPath {
  export declare type Method = (typeof METHOD_LIST)[number];
 
  /**
-  * Lists the HTTP methods a {@link import('./types.js').DispatcherInterface}
-  * registers routes under, in canonical order — the single source the
-  * {@link import('./types.js').Method} type, {@link METHODS}, and
-  * `parseMethod` are all derived from.
+  * Lists the HTTP methods a {@link import('./types.js').DispatcherInterface} registers
+  * routes under, in canonical order — a frozen literal tuple, and the single source the
+  * {@link import('./types.js').Method} type, {@link METHODS}, and `parseMethod` are all
+  * derived from.
   *
   * @remarks
   * A frozen tuple of the verbs: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`,
@@ -736,10 +788,9 @@ export declare interface CompiledPath {
  export declare const METHOD_LIST: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 
  /**
-  * Holds the complete set of HTTP methods a
-  * {@link import('./types.js').DispatcherInterface} registers routes under —
-  * backs the registration guard (`add` rejects any `method` outside this set)
-  * and the auto-`OPTIONS` `Allow` derivation.
+  * Holds every HTTP method a {@link import('./types.js').DispatcherInterface} registers
+  * routes under as a `ReadonlySet` — backs the registration guard (`add` rejects any
+  * `method` outside this set) and the auto-`OPTIONS` `Allow` derivation.
   *
   * @remarks
   * A `ReadonlySet` built from {@link METHOD_LIST}, so it carries exactly the
@@ -920,9 +971,9 @@ export declare interface CompiledPath {
 
  /**
   * Represents the path-matching + registry engine — registers `{ path, meta, name? }`
-  * entries (compiling each path once) and resolves a concrete pathname to the
-  * MOST SPECIFIC matching entry. The shared machine both the `Navigator`
-  * (browser) and the `Dispatcher` (core, method-dimensioned) compose.
+  * entries (compiling each path once) and resolves a concrete pathname to the most
+  * specific matching entry. The shared machine both the `Navigator` (browser) and
+  * the `Dispatcher` (core, method-dimensioned) compose.
   *
   * @typeParam Meta - The opaque payload each entry carries and a match returns
   *
@@ -981,47 +1032,66 @@ export declare interface CompiledPath {
  /**
   * Represents the path-matching + registry engine contract (the behavioral-interface
   * role for the one-class-per-file `Router`). Registers `{ path, meta, name? }`
-  * entries (compiling each path once) and resolves a concrete pathname to the
-  * MOST SPECIFIC matching entry — a literal segment beats a param beats a
-  * wildcard at the earliest differing segment, registration-order-independent.
-  * The shared engine both the `Navigator` (browser) and the `Dispatcher`
-  * (core, method-dimensioned) compose.
+  * entries (compiling each path once) and resolves a concrete pathname to the most
+  * specific matching entry — a literal segment beats a param beats a wildcard at the
+  * earliest differing segment, registration-order-independent. The shared engine both
+  * the `Navigator` (browser) and the `Dispatcher` (core, method-dimensioned) compose.
   *
   * @typeParam Meta - The opaque payload each entry carries and a match returns
   *
   * @remarks
-  * - `count` — the number of registered entries.
-  * - `add(entry)` / `add(entries)` — register ONE / MANY entries (batch registration);
-  *   each path is compiled once here. When constructed with a `key` option,
-  *   an entry whose key already exists replaces the prior one in place;
-  *   otherwise every entry is kept, even duplicate paths.
-  * - `match(pathname, answers?)` — the MOST-SPECIFIC matching entry as a
-  *   {@link RouterMatch} (its winning `path`, decoded `params`, `meta`, and
-  *   `name`), or `undefined`. The optional {@link AnswerHandler} predicate
-  *   filters candidates by `meta` first; omitted ⇒ every path match is
-  *   eligible.
-  * - `entries()` — ALL registered entries in registration order.
-  * - `entries(pathname)` — only entries whose path matches `pathname` (the
-  *   plural accessor's filtered form; backs a consumer's allow/405 set).
-  * - `group(prefix)` — a {@link GroupInterface} scoped under `prefix`; entries
-  *   added through the group are registered on this same router with `prefix`
-  *   prepended to each path.
-  * - `clear()` — drop every entry, leaving the router reusable.
+  * Registration is the guarded boundary and matching is the hot path: `add` validates
+  * each entry and throws, while `match` carries no guard of its own.
   */
  export declare interface RouterInterface<Meta> {
+     /** Holds the number of registered entries. */
      readonly count: number;
+     /**
+      * Registers one entry, or many in one call (batch registration), compiling each path
+      * once; throws a `ContractError` on a malformed path.
+      *
+      * @remarks
+      * When the router was constructed with a `key` option, an entry whose key already
+      * exists replaces the prior one in place; otherwise every entry is kept, even a
+      * duplicate path.
+      */
      add(entry: RouteEntry<Meta>): void;
      add(entries: ReadonlyArray<RouteEntry<Meta>>): void;
+     /**
+      * Resolves the most-specific matching entry for a pathname, or `undefined` when
+      * nothing matches.
+      *
+      * @remarks
+      * A hit is a {@link RouterMatch} carrying the winning `path`, the decoded `params`,
+      * the `meta` payload, and the optional `name`. The optional {@link AnswerHandler}
+      * predicate filters candidates by `meta` first; omitted, every path match is eligible.
+      */
      match(pathname: string, answers?: AnswerHandler<Meta>): RouterMatch<Meta> | undefined;
+     /**
+      * Lists every registered entry in registration order, or only those whose path
+      * matches a given pathname.
+      *
+      * @remarks
+      * The filtered form is the plural accessor's second shape, and it backs a consumer's
+      * allow set for a 405 answer.
+      */
      entries(): ReadonlyArray<RouteEntry<Meta>>;
      entries(pathname: string): ReadonlyArray<RouteEntry<Meta>>;
+     /**
+      * Returns a prefix-scoped registration handle over this router.
+      *
+      * @remarks
+      * Entries added through the group are registered on this same router with `prefix`
+      * prepended to each path.
+      */
      group(prefix: string): GroupInterface<Meta>;
+     /** Drops every entry, leaving the router reusable. */
      clear(): void;
  }
 
  /**
-  * Represents one matched route — the winning entry's PATTERN, decoded params, `meta`
-  * payload, and optional `name`.
+  * Represents one matched route — the winning entry's registered pattern, its decoded
+  * params, its `meta` payload, and its optional `name`.
   *
   * @typeParam Meta - The payload the winning entry carries
   *
@@ -1041,8 +1111,8 @@ export declare interface CompiledPath {
  }
 
  /**
-  * Represents the options for `createRouter` — an optional initial entry set, the case-
-  * sensitivity toggle, and the dedup identity function.
+  * Represents the options for `createRouter` — an optional initial entry set, the
+  * case-sensitivity toggle, and the dedup identity function.
   *
   * @typeParam Meta - The entry payload type
   *
@@ -1065,12 +1135,40 @@ export declare interface CompiledPath {
      readonly key?: (entry: RouteEntry<Meta>) => string;
  }
 
+ /**
+  * Contributes one path segment's type-level param record — the type-level mirror of
+  * the runtime `classifySegment` and `compilePath` segment parser.
+  *
+  * @typeParam Segment - One `/`-split path segment literal
+  *
+  * @remarks
+  * A `:` head followed by an identifier captures that identifier, stopping at the first
+  * non-identifier char, so `:name.json` captures only `name`. A segment whose `:` is not
+  * at the segment start (`a:b`) is literal and captures nothing — the classification fix
+  * this type mirrors. A `*name` segment, valid only as the grammar's final segment,
+  * captures the identifier the same way. A non-capturing segment resolves to `unknown`
+  * (the intersection identity) rather than `Record<string, never>` — an index-signature
+  * type intersected with a later `{ id: string }` would otherwise conflict (`string` is
+  * not assignable to the index signature's `never`); {@link PathParams} normalizes the
+  * eventual `unknown` (parameterless) result down to a clean empty record.
+  */
  export declare type SegmentParam<Segment extends string> = Segment extends `:${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : {
      readonly [K in Name]: string;
  } : unknown : Segment extends `*${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : {
      readonly [K in Name]: string;
  } : unknown : unknown;
 
+ /**
+  * Consumes the identifier-continuation run at the front of a string literal, char by
+  * char, appending each onto the accumulator.
+  *
+  * @typeParam S - The string literal whose front is being consumed
+  * @typeParam Acc - The identifier characters taken so far
+  *
+  * @remarks
+  * Stops (returning `Acc` unchanged) at the first non-identifier char or at the end of
+  * the string, so the accumulator holds exactly the leading {@link IdentifierChar} run.
+  */
  export declare type TakeIdentifierTail<S extends string, Acc extends string> = S extends `${infer Head}${infer Tail}` ? Head extends IdentifierChar ? TakeIdentifierTail<Tail, `${Acc}${Head}`> : Acc : Acc;
 
  /**