@fedify/uri-template 2.0.0-pr.475.1 → 2.3.0-dev.1137

package/dist/mod.d.ts

@@ -0,0 +1,795 @@
+//#region src/router/errors.d.ts
+/**
+ * Common base class for router-level errors.
+ */
+declare class RouterError extends Error {
+  /**
+   * @param message Human-readable summary.
+   */
+  constructor(message: string);
+}
+/**
+ * Raised when a route template is not a path template.
+ */
+declare class RouteTemplatePathError extends RouterError {
+  /**
+   * The route template that failed validation.
+   */
+  readonly template: string;
+  constructor(
+  /**
+   * The route template that failed validation.
+   */
+  template: string);
+}
+/**
+ * Raised when the same variable name appears in multiple variable
+ * specifications whose modifiers imply contradictory `multiple` semantics
+ * within a single route template (for example, `{x}` together with `{x*}`).
+ */
+declare class ConflictingVarSpecError extends RouterError {
+  /**
+   * The route template containing the conflicting variable specifications.
+   */
+  readonly template: string;
+  /**
+   * The variable name with conflicting variable specifications.
+   */
+  readonly variable: string;
+  constructor(
+  /**
+   * The route template containing the conflicting variable specifications.
+   */
+  template: string,
+  /**
+   * The variable name with conflicting variable specifications.
+   */
+  variable: string);
+}
+/**
+ * Raised under the default `exact` route option when the `variables` keys
+ * do not exactly match the route template's variables: the set of supplied
+ * keys must equal the set of template variables (no unknown keys, none
+ * missing).  All mismatched names — both unknown and missing — are reported.
+ */
+declare class RouteTemplateOptionsNotMatchedError extends RouterError {
+  /**
+   * The route template whose variables were not matched exactly.
+   */
+  readonly template: string;
+  /**
+   * The mismatched variable names: keys not declared by the template
+   * together with template variables absent from the options.
+   */
+  readonly variable: readonly string[];
+  constructor(
+  /**
+   * The route template whose variables were not matched exactly.
+   */
+  template: string,
+  /**
+   * The mismatched variable names: keys not declared by the template
+   * together with template variables absent from the options.
+   */
+  variable: readonly string[]);
+}
+/**
+ * Raised when a variable appears more than once in a route template while
+ * its `duplicable` constraint is `false` (the default).
+ */
+declare class DuplicateRouteVariableError extends RouterError {
+  /**
+   * The route template containing the duplicated variable.
+   */
+  readonly template: string;
+  /**
+   * The variable name that appears more than once.
+   */
+  readonly variable: string;
+  constructor(
+  /**
+   * The route template containing the duplicated variable.
+   */
+  template: string,
+  /**
+   * The variable name that appears more than once.
+   */
+  variable: string);
+}
+/**
+ * Raised when a variable specification uses the explode (`*`) or prefix
+ * (`:N`) modifier while the corresponding `explodable`/`prefixable`
+ * constraint is `false` (the default).
+ */
+declare class DisallowedVarSpecModifierError extends RouterError {
+  /**
+   * The route template containing the disallowed modifier.
+   */
+  readonly template: string;
+  /**
+   * The variable name whose specification uses the modifier.
+   */
+  readonly variable: string;
+  /**
+   * The disallowed modifier.
+   */
+  readonly modifier: "explode" | "prefix";
+  constructor(
+  /**
+   * The route template containing the disallowed modifier.
+   */
+  template: string,
+  /**
+   * The variable name whose specification uses the modifier.
+   */
+  variable: string,
+  /**
+   * The disallowed modifier.
+   */
+  modifier: "explode" | "prefix");
+}
+/**
+ * Raised when a variable is used with an expression operator that is not in
+ * its `operatables` allow-list.
+ */
+declare class DisallowedOperatorError extends RouterError {
+  /**
+   * The route template containing the disallowed operator.
+   */
+  readonly template: string;
+  /**
+   * The variable name used with the disallowed operator.
+   */
+  readonly variable: string;
+  /**
+   * The disallowed expression operator (`""`, `"+"`, `"#"`, `"."`, `"/"`,
+   * `";"`, `"?"`, or `"&"`).
+   */
+  readonly operator: string;
+  constructor(
+  /**
+   * The route template containing the disallowed operator.
+   */
+  template: string,
+  /**
+   * The variable name used with the disallowed operator.
+   */
+  variable: string,
+  /**
+   * The disallowed expression operator (`""`, `"+"`, `"#"`, `"."`, `"/"`,
+   * `";"`, `"?"`, or `"&"`).
+   */
+  operator: string);
+}
+//#endregion
+//#region src/const.d.ts
+/**
+ * Operators implemented by this package, including `""` for simple string
+ * expansion with no explicit operator.
+ */
+declare const OPERATORS: readonly ["", "+", ".", "/", ";", "?", "&", "#"];
+/**
+ * Union of supported URI Template operators.
+ */
+type Operator = typeof OPERATORS[number];
+//#endregion
+//#region src/types.d.ts
+/**
+ * Path-shaped URI Template accepted by the router.
+ *
+ * The empty path is accepted so trailing-slash-insensitive routing can retry
+ * the root path (`/`) as an empty path.
+ */
+type Path = "" | `/${string}` | `{/${string}}${string}`;
+/**
+ * Primitive value accepted by {@link Template.expand}.
+ */
+type PrimitiveValue = string | number | boolean | null | undefined;
+/**
+ * Associative composite value accepted by
+ * {@link Template.expand}.
+ *
+ * Keys are expanded as URI Template associative names. Values may be primitive
+ * values or primitive lists.
+ */
+type AssociativeValue = Record<string, PrimitiveValue | readonly PrimitiveValue[]>;
+/**
+ * Any value shape accepted for one template variable during expansion.
+ */
+type ExpandValue = PrimitiveValue | readonly PrimitiveValue[] | AssociativeValue;
+/**
+ * Context object accepted by {@link Template.expand}.
+ * Each variable resolves to a primitive, an ordered list of primitives,
+ * or an associative map.
+ */
+type ExpandContext = Record<string, ExpandValue>;
+/**
+ * Parsed RFC 6570 variable specification inside an expression.
+ *
+ * Produced by the expression parser and consumed by the expansion module.
+ */
+interface VarSpec {
+  /** Variable name to look up in the expansion context. */
+  readonly name: string;
+  /** Whether the varspec uses the Level 4 explode modifier (`*`). */
+  readonly explode: boolean;
+  /** Prefix length from a Level 4 prefix modifier (`:N`), if present. */
+  readonly prefix?: number;
+}
+/**
+ * Token produced by parsing a URI Template.
+ *
+ * Literal tokens are copied directly. Expression tokens are expanded with a
+ * context object.
+ */
+type Token = {
+  readonly kind: "literal";
+  readonly text: string;
+} | {
+  readonly kind: "expression";
+  readonly operator: Operator;
+  readonly vars: readonly VarSpec[];
+};
+/**
+ * Options controlling URI Template parsing and expansion diagnostics.
+ */
+interface TemplateOptions {
+  /**
+   * If `true`, the first parse or expansion error will be automatically
+   * thrown after being reported. `true` is the default value. If `false`,
+   * errors will be reported to by the `report` function, but none will be
+   * thrown unless the `report` function itself throws.
+   */
+  strict: boolean;
+  /**
+   * A function that will be called with any errors encountered while parsing
+   * or expanding.  Defaults to a no-op; pass a callback (for example, one
+   * backed by your application's logger) to observe diagnostics. In strict
+   * mode, errors are still thrown after this reporter runs.
+   * @param error The error that was encountered while parsing or expanding the
+   *              template.
+   */
+  report: Reporter;
+}
+/**
+ * Callback used to report recoverable parse and expansion diagnostics.
+ */
+type Reporter = (error: Error) => void;
+//#endregion
+//#region src/template/errors.d.ts
+/**
+ * Errors raised when an RFC 6570 URI template fails to parse or expand.
+ *
+ * Parse-time hierarchy:
+ *
+ * ~~~~
+ * TemplateParseError
+ * ├── UnclosedExpressionError
+ * ├── StrayClosingBraceError
+ * ├── NestedOpeningBraceError
+ * ├── EmptyExpressionError
+ * ├── ReservedOperatorError
+ * ├── UnknownOperatorError
+ * ├── InvalidLiteralError
+ * ├── InvalidVarSpecError
+ * │   ├── EmptyVarNameError
+ * │   ├── InvalidVarNameError
+ * │   ├── InvalidPrefixError
+ * │   └── TrailingCommaError
+ * └── UnexpectedCharacterError
+ * ~~~~
+ *
+ * Expansion-time hierarchy:
+ *
+ * ~~~~
+ * TemplateExpansionError
+ * └── PrefixModifierNotApplicableError
+ * ~~~~
+ *
+ * Parse errors carry the original `template` and the 0-based `position` where
+ * the offending input was located. Expansion errors carry the runtime variable
+ * name whose value cannot be expanded.
+ *
+ * @module
+ */
+/**
+ * Common base class for every parse-time error produced by the RFC 6570 parser.
+ */
+declare class TemplateParseError extends Error {
+  readonly template: string;
+  readonly position: number;
+  readonly hint: string;
+  /**
+   * @param template     The full URI template string that was being parsed.
+   * @param position     0-based index into `template` where the problem was
+   *                     detected.  When the offending input spans a range,
+   *                     this is the start of that range.
+   * @param hint         Short, actionable instruction for the user.
+   * @param message      Human-readable summary.
+   */
+  constructor(template: string, position: number, hint: string, message: string);
+}
+/**
+ * Raised when an opening `{` has no matching `}` before the template ends.
+ *
+ * Fix: close the expression with `}` or pct-encode the literal `{` as `%7B`.
+ * RFC 6570 does not define an escape syntax.
+ */
+declare class UnclosedExpressionError extends TemplateParseError {
+  constructor(template: string, position: number);
+}
+/**
+ * Raised when a `}` appears outside of any expression.
+ *
+ * Fix: remove the stray `}` or precede it with a matching `{`.
+ */
+declare class StrayClosingBraceError extends TemplateParseError {
+  constructor(template: string, position: number);
+}
+/**
+ * Raised when a `{` appears inside another expression before that expression
+ * is closed.  RFC 6570 expressions cannot nest.
+ *
+ * Fix: close the outer expression with `}` before opening a new one.
+ */
+declare class NestedOpeningBraceError extends TemplateParseError {
+  constructor(template: string, position: number);
+}
+/**
+ * Raised when a literal section of the template contains a character that is
+ * outside the RFC 6570 `literals` set: CTL, SP, `"`, `'`, lone `%`, `<`, `>`,
+ * `\\`, `^`, `` ` ``, `|`.
+ *
+ * Fix: pct-encode the offending character or remove it.
+ */
+declare class InvalidLiteralError extends TemplateParseError {
+  readonly char: string;
+  constructor(template: string, position: number, char: string);
+}
+/**
+ * Raised for `{}` — an expression that contains neither operator nor varspec.
+ *
+ * Fix: insert at least one varname between the braces, e.g. `{var}`.
+ */
+declare class EmptyExpressionError extends TemplateParseError {
+  constructor(template: string, position: number);
+}
+/**
+ * Raised when the operator slot holds one of the characters reserved by
+ * RFC 6570 §2.2 for future extensions: `=`, `,`, `!`, `@`, `|`.
+ *
+ * Fix: drop the reserved operator or replace it with one of the implemented
+ * operators (`+`, `#`, `.`, `/`, `;`, `?`, `&`).
+ */
+declare class ReservedOperatorError extends TemplateParseError {
+  readonly operator: string;
+  constructor(template: string, position: number, operator: string);
+}
+/**
+ * Raised when the operator slot holds a character that is neither a defined
+ * RFC 6570 operator nor part of the varname grammar.
+ *
+ * Fix: use one of the implemented operators (`+`, `#`, `.`, `/`, `;`, `?`,
+ * `&`) or remove the character.
+ */
+declare class UnknownOperatorError extends TemplateParseError {
+  readonly operator: string;
+  constructor(template: string, position: number, operator: string);
+}
+/**
+ * Common base for malformed varspec errors so users can `instanceof`-filter.
+ */
+declare class InvalidVarSpecError extends TemplateParseError {
+  readonly varSpec: string;
+  constructor(template: string, position: number, hint: string, message: string, varSpec: string);
+}
+/**
+ * Raised when a varspec contains no varname (e.g. `{,foo}` or `{foo,}`).
+ */
+declare class EmptyVarNameError extends InvalidVarSpecError {
+  constructor(template: string, position: number);
+}
+/**
+ * Raised when a varname contains characters outside the RFC 6570 varchar set
+ * (`ALPHA / DIGIT / "_" / pct-encoded`, optionally separated by `.`).
+ */
+declare class InvalidVarNameError extends InvalidVarSpecError {
+  readonly offendingChar: string;
+  constructor(template: string, position: number, varSpec: string, offendingChar: string);
+}
+/**
+ * Raised when a prefix modifier (`:N`) is malformed: missing digits, leading
+ * zero, or `N` outside the range `1..9999`.
+ */
+declare class InvalidPrefixError extends InvalidVarSpecError {
+  readonly prefix: string;
+  constructor(template: string, position: number, varSpec: string, prefix: string);
+}
+/**
+ * Raised when a varspec ends with a trailing comma followed by `}` or end of
+ * variable-list (e.g. `{a,b,}`).
+ */
+declare class TrailingCommaError extends InvalidVarSpecError {
+  constructor(template: string, position: number);
+}
+/**
+ * Raised when an unexpected character appears between a varspec and the next
+ * separator (`,` or `}`), e.g. `{a b}` or `{a:3x}`.
+ */
+declare class UnexpectedCharacterError extends TemplateParseError {
+  readonly char: string;
+  constructor(template: string, position: number, char: string);
+}
+/**
+ * Common base class for runtime expansion errors.
+ */
+declare class TemplateExpansionError extends Error {
+  readonly variableName: string;
+  readonly hint: string;
+  /**
+   * @param variableName The variable whose resolved value cannot be expanded.
+   * @param hint Short, actionable instruction for the user.
+   * @param message Human-readable summary.
+   */
+  constructor(variableName: string, hint: string, message: string);
+}
+/**
+ * Raised when a prefix modifier is applied to a composite value.
+ *
+ * RFC 6570 §2.4.1 defines prefix modifiers for string values only; lists and
+ * associative arrays must use normal or explode expansion instead.
+ */
+declare class PrefixModifierNotApplicableError extends TemplateExpansionError {
+  readonly prefix: number;
+  readonly valueType: "list" | "associative";
+  constructor(variableName: string, prefix: number, valueType: "list" | "associative");
+}
+//#endregion
+//#region src/template/template.d.ts
+/**
+ * Parsed RFC 6570 URI Template that can be expanded repeatedly.
+ *
+ * This class owns tokenization and delegates expression expansion to the
+ * expansion module.  Instances are immutable after construction.
+ */
+declare class Template {
+  #private;
+  /**
+   * URI template string to parse. See [RFC 6570] for syntax details.
+   *
+   * [RFC 6570]: https://datatracker.ietf.org/doc/html/rfc6570
+   */
+  readonly uriTemplate: string;
+  /**
+   * Options for parsing the template. By default, `strict` is `true` and
+   * `report` is a no-op. If `strict` is `true`, the first error encountered
+   * while parsing or expanding will be automatically thrown after being
+   * reported. If `strict` is `false`, errors will be reported but none will
+   * be thrown unless the `report` function itself throws. The rest of the
+   * part remains as literal text.
+   */
+  readonly options: Partial<TemplateOptions>;
+  constructor(
+  /**
+   * URI template string to parse. See [RFC 6570] for syntax details.
+   *
+   * [RFC 6570]: https://datatracker.ietf.org/doc/html/rfc6570
+   */
+
+  uriTemplate: string,
+  /**
+   * Options for parsing the template. By default, `strict` is `true` and
+   * `report` is a no-op. If `strict` is `true`, the first error encountered
+   * while parsing or expanding will be automatically thrown after being
+   * reported. If `strict` is `false`, errors will be reported but none will
+   * be thrown unless the `report` function itself throws. The rest of the
+   * part remains as literal text.
+   */
+
+  options?: Partial<TemplateOptions>);
+  /**
+   * Parses a URI Template using default strict parsing options.
+   */
+  static parse(uriTemplate: string, options?: Partial<TemplateOptions>): Template;
+  /**
+   * Immutable parsed token stream for diagnostics and router integration.
+   */
+  get tokens(): readonly Token[];
+  /**
+   * Expands this template against a variable context.
+   */
+  readonly expand: (context: ExpandContext) => string;
+  /**
+   * Matches a URI against this template, returning the variable context if the
+   * URI matches or `null` if it does not.
+   */
+  readonly match: (uri: string) => ExpandContext | null;
+  readonly toString: () => string;
+}
+//#endregion
+//#region src/router/types.d.ts
+/**
+ * Options for the {@link Router}.
+ */
+interface RouterOptions {
+  /**
+   * Whether to ignore trailing slashes when matching paths.
+   */
+  trailingSlashInsensitive?: boolean;
+}
+/**
+ * Fully-resolved per-variable matching constraint.  Every template variable
+ * is constrained even when it is not listed in {@link RouteOptions.variables};
+ * the listed entries only override the defaults.  All fields are required;
+ * call sites pass a {@link Partial} and {@link fillRouteOptions} fills the
+ * missing fields with their defaults.
+ */
+interface VariableConstraint {
+  /**
+   * When `true`, an unbound or empty binding still matches (opt-out of the
+   * non-empty requirement).  Defaults to `false`.
+   */
+  readonly nullable: boolean;
+  /**
+   * Whether the variable binds to a list of values rather than a single
+   * scalar.  When omitted it is derived from the variable specification:
+   * explode (`*`) implies `true`, a prefix modifier (`:N`) implies `false`,
+   * and a plain variable defaults to `false` but may be set either way.
+   * Specifying a value that contradicts the derived one is a registration
+   * error.
+   */
+  readonly multiple: boolean;
+  /**
+   * Whether the variable may appear more than once in the route template.
+   * Defaults to `false`: a variable that occurs in multiple variable
+   * specifications is a registration error (`DuplicateRouteVariableError`).
+   * Set to `true` to allow repeated occurrences (their bindings must still
+   * agree at match time).
+   */
+  readonly duplicable: boolean;
+  /**
+   * Whether a variable specification may use the prefix modifier (`:N`).
+   * Defaults to `false`: a `{var:N}` specification is a registration error
+   * (`DisallowedVarSpecModifierError`).  Incompatible with `multiple: true`
+   * (a prefix yields a single truncated scalar); that combination is
+   * already rejected by the `multiple` derivation.
+   */
+  readonly prefixable: boolean;
+  /**
+   * Whether a variable specification may use the explode modifier (`*`).
+   * Defaults to `false`: a `{var*}` specification is a registration error
+   * (`DisallowedVarSpecModifierError`).  Only meaningful with
+   * `multiple: true` (explode yields a list); the `multiple` derivation
+   * already forces and checks that coupling.
+   */
+  readonly explodable: boolean;
+  /**
+   * Allow-list of expression operators the variable may be used with.
+   * Defaults to `[]`, which permits every operator.  When non-empty, using
+   * the variable under an operator outside this list is a registration
+   * error (`DisallowedOperatorError`).
+   */
+  readonly operatables: readonly Operator[];
+}
+/**
+ * Fully-resolved options attached to a registered route.  All fields are
+ * required; {@link fillRouteOptions} resolves a {@link Partial} input against
+ * a {@link RouterPathPattern} into this shape.
+ */
+interface RouteOptions {
+  /**
+   * Per-variable constraint, keyed by variable name.  After resolution this
+   * contains an entry for every template variable, not just the overridden
+   * ones.
+   */
+  readonly variables: Readonly<Record<string, VariableConstraint>>;
+  /**
+   * When `true` (the default), the `variables` keys must exactly match the
+   * template's variables: a key that is not an actual template variable is
+   * a registration error (typo guard).  When `false`, such keys are
+   * silently ignored.
+   */
+  readonly exact: boolean;
+}
+/**
+ * The subset of a per-variable constraint that {@link ConstraintValue}
+ * inspects to compute a matched value's static type.  Only `multiple` and
+ * `nullable` shape the value: `multiple: true` yields `readonly string[]`,
+ * `nullable: true` additionally admits `null`.
+ *
+ * `explodable` is a *registration permission* (it lets a varspec use the
+ * explode modifier `{var*}` without throwing) and deliberately does **not**
+ * affect the computed value type.  An exploded route still resolves
+ * `multiple` to `true` via {@link fillMultiple}, so callers that want the
+ * matched value narrowed to `readonly string[]` must pass `multiple: true`
+ * in the {@link Router.route} type argument, not merely `explodable: true`.
+ */
+interface MinimalConstraint {
+  readonly multiple?: boolean;
+  readonly nullable?: boolean;
+  readonly explodable?: boolean;
+}
+/**
+ * Computes the value type of a single matched variable from its constraint:
+ * `multiple: true` yields `readonly string[]`, otherwise `string`;
+ * `nullable: true` additionally admits `null`.
+ *
+ * The trailing `extends infer R ? R : never` is an identity that forces
+ * TypeScript to evaluate the conditional union eagerly.
+ */
+type ConstraintValue<C extends MinimalConstraint> = ((C extends {
+  multiple: true;
+} ? readonly string[] : string) | (C extends {
+  nullable: true;
+} ? null : never)) extends infer R ? R : never;
+/**
+ * Computes the `values` record type from a map of variable constraints.  An
+ * empty map (the default) widens to `Record<string, string>` because the
+ * matched route is not known at the type level.
+ */
+type RouteValues<TConstraints extends Record<string, MinimalConstraint>> = [keyof TConstraints] extends [never] ? Record<string, ConstraintValue<{
+  multiple: false;
+  nullable: false;
+}>> : { [K in keyof TConstraints]: ConstraintValue<TConstraints[K]> };
+/**
+ * The result of {@link Router.route}.  The type argument is the per-variable
+ * constraint map; pass it at the call site to narrow `values` (for example,
+ * `router.route<{ tags: { nullable: false; multiple: true } }>(...)`).
+ */
+interface RouterRouteResult<TConstraints extends Record<string, MinimalConstraint>> {
+  /**
+   * The matched route name.
+   */
+  name: string;
+  /**
+   * The URI template of the matched route.
+   */
+  template: Path;
+  /**
+   * The values extracted from the URI.
+   */
+  values: RouteValues<TConstraints>;
+}
+/**
+ * Parsed path template ready to be registered in a {@link Router}.
+ *
+ * Instances returned by {@link Router.compile} are immutable and may be shared
+ * safely between routers and router clones.
+ */
+interface RouterPathPattern {
+  /**
+   * The original path template string.
+   */
+  readonly path: Path;
+  /**
+   * Parsed URI Template.
+   */
+  readonly template: Template;
+  /**
+   * Variable names found in the template.
+   */
+  readonly variables: ReadonlySet<string>;
+}
+/**
+ * Resolved route definition produced internally and returned by
+ * {@link Router#clone} round-trips.  Unlike {@link PartialRouterRoute}, the
+ * path is already compiled and the options are fully resolved.
+ */
+type RouterRoute = readonly [pathOrPattern: RouterPathPattern, name: string, options: RouteOptions];
+/**
+ * Route definition accepted by {@link Router#register}, the {@link Router}
+ * constructor, and {@link Router.from}.  The first element is either a path
+ * template string or a pre-parsed {@link RouterPathPattern} from
+ * {@link Router.compile}; the second element is the route name; the optional
+ * third element is the per-route options (missing fields are filled with
+ * their defaults).
+ */
+type PartialRouterRoute = readonly [pathOrPattern: Path | RouterPathPattern, name: string, options?: {
+  readonly variables?: Readonly<Record<string, Partial<VariableConstraint>>>;
+  readonly exact?: boolean;
+}];
+//#endregion
+//#region src/router/router.d.ts
+/**
+ * Router that resolves URIs against registered RFC 6570 templates.
+ */
+declare class Router {
+  #private;
+  /**
+   * Whether to ignore trailing slashes when matching paths.
+   */
+  trailingSlashInsensitive: boolean;
+  /**
+   * Create a new {@link Router}.
+   *
+   * The first argument may be an iterable of routes, an options object, or
+   * omitted.  When two arguments are passed, they are interpreted as
+   * `(routes, options)`.
+   *
+   * @param routes Routes to register on the new router.
+   * @param options Options for the router.
+   */
+  constructor(routes: Iterable<PartialRouterRoute>, options?: RouterOptions);
+  constructor(options?: RouterOptions);
+  /**
+   * Creates a new {@link Router}.  Mirrors the constructor argument
+   * interface and is provided for ergonomic call sites that prefer a
+   * static factory over `new`.
+   */
+  static from(routes: Iterable<PartialRouterRoute>, options?: RouterOptions): Router;
+  static from(options?: RouterOptions): Router;
+  /**
+   * Compiles a path template without registering it in a router.
+   * @param path The path pattern.
+   * @returns A parsed path pattern.
+   */
+  static compile(path: Path): RouterPathPattern;
+  /**
+   * Returns the variable names in a path template without registering it.
+   * @param path The path pattern.
+   * @returns The names of the variables in the path pattern.
+   */
+  static variables: (path: Path) => Set<string>;
+  /**
+   * Checks if a path name exists in the router.
+   * @param name The name of the path.
+   * @returns `true` if the path name exists, otherwise `false`.
+   */
+  has: (name: string) => boolean;
+  /**
+   * Adds a new path rule to the router.
+   * @param pathOrPattern The path template, or a pre-parsed
+   *                      {@link RouterPathPattern} produced by
+   *                      {@link Router.compile}.
+   * @param name The name of the path.
+   * @param options Per-route options, including per-variable constraints.
+   */
+  add: (...args: PartialRouterRoute) => void;
+  /**
+   * Registers multiple path rules at once.
+   * @param routes Iterable of `[pathOrPattern, name]` pairs to register.
+   */
+  register: (routes: Iterable<PartialRouterRoute>) => void;
+  /**
+   * Resolves a path name and values from a URI, if any match.
+   * @param url The URI to resolve.
+   * @returns The name of the path and its values, if any match.  Otherwise,
+   *          `null`.
+   */
+  route: <TConstraints extends Record<string, MinimalConstraint> = Record<never, never>>(url: Path) => RouterRouteResult<TConstraints> | null;
+  /**
+   * Constructs a URL/path from a path name and values.
+   * @param name The name of the path.
+   * @param values The values to expand the path with.
+   * @returns The URL/path, if the name exists.  Otherwise, `null`.
+   */
+  build: <TConstraints extends Record<string, VariableConstraint> = Record<never, never>>(name: string, values: RouterRouteResult<TConstraints>["values"]) => Path | null;
+  /**
+   * Creates a shallow clone of the router.  The clone shares immutable
+   * registered path patterns with the original, but changes to the route set
+   * (adding, removing, or re-registering routes) do not affect the other
+   * router.
+   * @returns A new router with the same routes and options as this one.
+   */
+  clone: () => Router;
+}
+//#endregion
+//#region src/utils.d.ts
+declare const isExpression: <T extends {
+  kind: string;
+}>(token: T) => token is Extract<T, {
+  kind: "expression";
+}>;
+/**
+ * Returns whether `path` is a path-shaped URI Template accepted by the
+ * router.
+ *
+ * A path is either an empty string, a literal string starting with `/`, or a
+ * path-expansion expression (`{/var}`).
+ * Templates that fail to parse — and therefore could never be routed —
+ * return `false`.
+ */
+declare function isPath(path: string): path is Path;
+declare function assertPath(path: string): asserts path is Path;
+//#endregion
+export { type AssociativeValue, ConflictingVarSpecError, type ConstraintValue, DisallowedOperatorError, DisallowedVarSpecModifierError, DuplicateRouteVariableError, EmptyExpressionError, EmptyVarNameError, type ExpandContext, type ExpandValue, InvalidLiteralError, InvalidPrefixError, InvalidVarNameError, InvalidVarSpecError, NestedOpeningBraceError, type Operator, type Path, PrefixModifierNotApplicableError, type PrimitiveValue, type Reporter, ReservedOperatorError, type RouteOptions, RouteTemplateOptionsNotMatchedError, RouteTemplatePathError, type RouteValues, Router, RouterError, type RouterOptions, type RouterPathPattern, type RouterRoute, type RouterRouteResult, StrayClosingBraceError, Template, TemplateExpansionError, type TemplateOptions, TemplateParseError, type Token, TrailingCommaError, UnclosedExpressionError, UnexpectedCharacterError, UnknownOperatorError, type VarSpec, type VariableConstraint, assertPath, isExpression, isPath };