@real-router/core 0.78.0 → 0.79.1

package/dist/esm/validation.d.mts

@@ -1,518 +1,6 @@
-import { a as MatcherInputNode, i as MatchResult, n as RouteTree, o as ResolvedMatcherOptions, r as BuildPathOptions, s as SegmentMatcherOptions, t as RouteDefinition } from "./types-xg2zHVF6.mjs";
-import { $ as State, B as PluginFactory, D as ForwardToCallback, I as LoggerConfig, J as LimitsConfig, O as GuardFn, Q as SimpleState, R as Options$1, U as Router, W as RouterLogger, X as Params, Y as NavigationOptions, at as Unsubscribe, k as GuardFnFactory, lt as RouteTreeState, u as TreeChangedEvent, v as EventMethodMap, w as DefaultDependencies, y as EventName, z as Plugin } from "./index-CAnGQpnz.mjs";
-import { t as RouterValidator } from "./RouterValidator-CZ8kPkrI.mjs";
-import { n as SerializedRouterState } from "./index-DnSU6huX.mjs";
-
-//#region src/engine/search-params/types.d.ts
-/**
- * Search Params Type Definitions.
- *
- * Consolidated interfaces and type aliases for the search-params module.
- *
- * @module search-params/types
- */
-/**
- * Array parameter encoding format.
- *
- * @remarks
- * - `none` - repeated keys: `a=1&a=2`
- * - `brackets` - bracket notation: `a[]=1&a[]=2`
- * - `index` - indexed notation: `a[0]=1&a[1]=2`
- * - `comma` - comma-separated: `a=1,2`
- */
-type ArrayFormat = "none" | "brackets" | "index" | "comma";
-/**
- * Boolean parameter encoding format.
- *
- * @remarks
- * - `none` - no special handling
- * - `auto` - auto-detect "true"/"false" strings as boolean values
- * - `empty-true` - true values have no value: `?flag` instead of `?flag=true`
- *
- * @remarks
- * Under `empty-true` the bare-key wire form (`?flag`) is reserved for `true`, so
- * a `null` value with `nullFormat: "default"` (which also encodes to a bare key)
- * is **not representable**: it round-trips back as `true`, not `null`. Both null
- * and true collapse to the same token and only `true` decodes back. Pair
- * `empty-true` with `nullFormat: "hidden"`, or avoid null query values.
- */
-type BooleanFormat = "none" | "auto" | "empty-true";
-/**
- * Null parameter encoding format.
- *
- * @remarks
- * - `default` - key only: `?key` (collides with `booleanFormat: "empty-true"`,
- *   which reserves the bare-key form for `true` — null then decodes as `true`)
- * - `hidden` - omit from query string
- */
-type NullFormat = "default" | "hidden";
-/**
- * Number parameter encoding format.
- *
- * @remarks
- * - `none` - no special handling
- * - `auto` - decode canonical decimal numbers (`/^-?(0|[1-9]\d*)(\.\d+)?$/`) to
- *   `Number()`. Recognizes negatives so the parsed type matches what
- *   `build`/`navigate` produce; rejects leading zeros (`"007"`), exponent
- *   notation, unsafe integers, and negative zero (`"-0"` — the grammar matches
- *   it, but an `Object.is` guard rejects it since `build(-0)` emits `"0"`, #898)
- *   — those keep their exact text as strings.
- */
-type NumberFormat = "none" | "auto";
-/**
- * Options for search-params parsing and building.
- */
-interface Options {
-  /** Array parameter encoding format. @default "none" */
-  arrayFormat?: ArrayFormat;
-  /** Boolean parameter encoding format. @default "auto" */
-  booleanFormat?: BooleanFormat;
-  /** Null parameter encoding format. @default "default" */
-  nullFormat?: NullFormat;
-  /** Number parameter encoding format. @default "auto" */
-  numberFormat?: NumberFormat;
-}
-//#endregion
-//#region src/engine/path-matcher/SegmentMatcher.d.ts
-declare class SegmentMatcher {
-  #private;
-  get options(): ResolvedMatcherOptions;
-  constructor(options: SegmentMatcherOptions);
-  registerTree(node: MatcherInputNode): void;
-  match(path: string): MatchResult | undefined;
-  buildPath(name: string, params?: Record<string, unknown>, options?: BuildPathOptions): string;
-  getSegmentsByName(name: string): readonly MatcherInputNode[] | undefined;
-  getMetaByName(name: string): Readonly<Record<string, Record<string, "url" | "query">>> | undefined;
-  hasRoute(name: string): boolean;
-}
-//#endregion
-//#region src/engine/createMatcher.d.ts
-/**
- * Query string formatting options.
- *
- * Controls how arrays, booleans, nulls, and numbers are serialized in query strings.
- */
-type QueryParamsConfig = Readonly<Options>;
-/**
- * Options for creating a path matcher.
- */
-interface CreateMatcherOptions {
-  readonly caseSensitive?: boolean;
-  readonly strictTrailingSlash?: boolean;
-  readonly strictQueryParams?: boolean;
-  readonly urlParamsEncoding?: "default" | "uri" | "uriComponent" | "none";
-  readonly queryParams?: QueryParamsConfig;
-}
-/**
- * Path matcher instance type.
- *
- * Opaque type — consumers use methods (match, buildPath, hasRoute, etc.)
- * without knowing the underlying SegmentMatcher implementation.
- */
-type Matcher = SegmentMatcher;
-//#endregion
-//#region src/engine/validation/route-batch.d.ts
-/**
- * Validates route structure for add operations.
- *
- * Performs comprehensive validation including:
- * - Type check (must be object)
- * - Name validation
- * - Path validation
- * - Duplicate name detection (in tree and batch)
- * - Duplicate path detection (in tree and batch)
- * - Recursive children validation
- *
- * @param route - Route to validate
- * @param methodName - Calling method for error context
- * @param rootNode - Optional root node for duplicate checking
- * @param parentName - Parent route name for building full path (used in recursion)
- * @param seenNames - Set of names already seen in this batch
- * @param seenPathsByParent - Map of paths by parent for path duplicate detection
- * @throws {TypeError} If route structure is invalid
- * @throws {Error} If route already exists (duplicate)
- * @throws {Error} If path already defined (duplicate)
- *
- * @example
- * ```typescript
- * const seenNames = new Set<string>();
- * const seenPaths = new Map<string, Set<string>>();
- *
- * // Validate routes before adding
- * for (const route of routes) {
- *   validateRoute(route, "add", rootNode, "", seenNames, seenPaths);
- * }
- * ```
- */
-declare function validateRoute(route: unknown, methodName: string, rootNode?: RouteTree, parentName?: string, seenNames?: Set<string>, seenPathsByParent?: Map<string, Set<string>>): asserts route is RouteDefinition;
-//#endregion
-//#region src/types/internal.d.ts
-/**
- * Immutable limits configuration type.
- */
-type Limits = Readonly<LimitsConfig>;
-//#endregion
-//#region src/namespaces/DependenciesNamespace/dependenciesStore.d.ts
-interface DependenciesStore<Dependencies extends DefaultDependencies = DefaultDependencies> {
-  dependencies: Partial<Dependencies>;
-  limits: Limits;
-}
-//#endregion
-//#region src/namespaces/RouteLifecycleNamespace/types.d.ts
-interface RouteLifecycleDependencies<Dependencies extends DefaultDependencies = DefaultDependencies> {
-  /** Per-router logger instance (from `getInternals(router).logger`) */
-  logger: RouterLogger;
-  compileFactory: (factory: GuardFnFactory<Dependencies>) => GuardFn;
-  /**
-   * Returns the opt-in DX validator, or `null` when no validation-plugin is
-   * installed. A plain deps field (#1331) — internals are registered before
-   * wiring, so `getInternals(router)` never throws and no try/catch is needed.
-   */
-  getValidator: () => RouterValidator | null;
-}
-//#endregion
-//#region src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.d.ts
-/**
- * Origin lane for a guard clear. Every `clearCanActivate` / `clearCanDeactivate`
- * caller names its lane — there is no origin-blind default — so a new call site
- * cannot silently wipe both the route-config and the external guard (#1171):
- *
- * - `"definition"` — clear only the route-config guard (`update(name, {…: null})`, #952).
- * - `"external"` — clear only the external, component-managed guard
- *   (`removeXGuard()` and post-leave auto-cleanup — the inverse of `addXGuard()`).
- * - `"both"` — clear both (route removal / router teardown; the route is gone).
- */
-type GuardClearScope = "definition" | "external" | "both";
-/**
- * Source of truth for `canActivate` / `canDeactivate` guards.
- *
- * Storage is split by origin into four factory Maps (definition vs external,
- * each ×activate/deactivate); a single compiled-function Map per kind backs
- * navigation ("external wins" — when a route holds both a definition and an
- * external guard, the compiled guard is the external one, regardless of
- * registration order; #1174). `getFunctions()` returns a cached
- * `[deactivate, activate]` tuple for the hot path (stable reference, no
- * per-navigate allocation).
- *
- * All input validation is handled upstream by `getLifecycleApi` and
- * `getRoutesApi` — this class has no static methods.
- *
- * **Ordering convention.** Every paired surface lists **deactivate before
- * activate**: `getFunctions()` / `getFactories()` return `[deactivate,
- * activate]`, `getFactoriesByOrigin()` returns that tuple per origin, and
- * `canNavigateTo(toDeactivate, toActivate, …)` takes deactivate first. Keep
- * any new paired surface consistent with this order.
- */
-declare class RouteLifecycleNamespace<Dependencies extends DefaultDependencies = DefaultDependencies> {
-  #private;
-  setDependencies(deps: RouteLifecycleDependencies<Dependencies>): void;
-  getHandlerCount(type: "activate" | "deactivate"): number;
-  /**
-   * Pre-flights the #961 handler-limit `RangeError` into the route-CRUD PREPARE
-   * phase (#1046). `#registerHandler`'s per-slot limit check throws AFTER the
-   * tree/config swap, so `add`/`replace`/`update` tore post-commit when the
-   * validator was installed and the per-type count was at `maxLifecycleHandlers`.
-   * Running the same check here — before any store mutation — restores atomicity
-   * (#951/#956/#698): a batch that would exceed the limit aborts before a single
-   * write.
-   *
-   * Only NEW slots count (an overwrite leaves the union count unchanged, mirroring
-   * `#registerHandler`). For `replace` (`clearsDefinition = true`) the definition
-   * guards are about to be cleared, so the projection runs against the surviving
-   * EXTERNAL guards only — exactly the post-clear state the install loop sees.
-   * Plugin-gated: a no-op without the validator (the limit is opt-in).
-   *
-   * @param activateNames - route names a `canActivate` would be registered for
-   * @param deactivateNames - route names a `canDeactivate` would be registered for
-   * @param clearsDefinition - true for `replace` (definition guards cleared first)
-   */
-  preflightHandlerLimit(activateNames: Iterable<string>, deactivateNames: Iterable<string>, clearsDefinition: boolean): void;
-  /**
-   * Adds a canActivate guard for a route.
-   *
-   * @param name - Route name (input-validated by facade)
-   * @param handler - Guard function or boolean (input-validated by facade)
-   * @param isFromDefinition - True when guard comes from route definition
-   *   (lands in the definition Map; subject to `clearDefinitionGuards()`).
-   *   False (default) when added via `getLifecycleApi().addActivateGuard(...)`
-   *   (lands in the external Map; survives `replace()`).
-   *
-   * External wins at runtime (#1174): when a route holds both a definition and
-   * an external guard, the compiled function is the external one, regardless of
-   * registration order. Within one origin the most recent add overwrites. Origin
-   * determines which Map the factory is filed under (relevant for
-   * `clearDefinitionGuards()` and `cloneRouter` re-registration).
-   */
-  addCanActivate(name: string, handler: GuardFnFactory<Dependencies> | boolean, isFromDefinition?: boolean, precompiledFn?: GuardFn): void;
-  /**
-   * Adds a canDeactivate guard for a route.
-   *
-   * Symmetric counterpart to {@link addCanActivate}.
-   */
-  addCanDeactivate(name: string, handler: GuardFnFactory<Dependencies> | boolean, isFromDefinition?: boolean, precompiledFn?: GuardFn): void;
-  /**
-   * Removes a canActivate guard for a route. `scope` names the origin lane
-   * (see {@link GuardClearScope}) — there is no origin-blind default, so every
-   * caller commits to a lane and a new call site cannot silently clear both.
-   * Delegates to {@link #clearGuard} (mirrors the add side's `#registerHandler`).
-   *
-   * @param name - Route name (already validated by facade)
-   * @param scope - Which origin(s) to clear: `"definition"` / `"external"` / `"both"`
-   */
-  clearCanActivate(name: string, scope: GuardClearScope): void;
-  /**
-   * Removes a canDeactivate guard for a route. Symmetric counterpart to
-   * {@link clearCanActivate}.
-   *
-   * The `"external"` lane is what makes a route-config `canDeactivate` durable:
-   * post-leave auto-cleanup (`completeTransition`) and `removeDeactivateGuard()`
-   * unregister only the external, component-managed guard (router5 mount/unmount
-   * heritage), while a definition guard survives for re-entry — symmetric with
-   * definition `canActivate`, which lives as long as the route is in the tree
-   * (#1171). Clearing both by default made a config guard one-shot: the first
-   * permitted leave erased it, so re-entry was unguarded, `getRoutesApi().get()`
-   * lost the field, and a clone taken after the leave never received it
-   * (clone invariant #6).
-   *
-   * @param name - Route name (already validated by facade)
-   * @param scope - Which origin(s) to clear: `"definition"` / `"external"` / `"both"`
-   */
-  clearCanDeactivate(name: string, scope: GuardClearScope): void;
-  /**
-   * Clears all lifecycle handlers (canActivate and canDeactivate).
-   * Used by clearRoutes to reset all lifecycle state.
-   */
-  clearAll(): void;
-  /**
-   * Clears only lifecycle handlers that were registered from route definitions.
-   * Used by HMR `replace()` to remove definition-sourced guards without
-   * touching externally-added guards.
-   *
-   * For a slot where BOTH a definition and an external guard exist, the external
-   * factory survives — and the compiled function is RECOMPILED from it (#1192).
-   * Under external-wins (#1174) the compiled slot is already the external guard,
-   * so this recompile is idempotent — it re-derives the surviving external factory
-   * through the same choke point that keeps clearing correct (and stays robust if
-   * the compiled slot were ever out of sync). For a definition-only slot, the
-   * compiled function is dropped.
-   */
-  clearDefinitionGuards(): void;
-  /**
-   * Returns lifecycle factories as a flat `[deactivate, activate]` tuple of
-   * `Record<name, factory>` — the effective view where external wins over
-   * definition for the same slot. Used by `getRoutesApi` to enrich route
-   * objects with their current canActivate / canDeactivate factories and by
-   * the route-removal cleanup path.
-   *
-   * For cloneRouter (which needs to preserve origin on re-registration), use
-   * {@link getFactoriesByOrigin} instead.
-   */
-  getFactories(): [Record<string, GuardFnFactory<Dependencies>>, Record<string, GuardFnFactory<Dependencies>>];
-  /**
-   * Returns factories tagged by origin — definition and external as separate
-   * `[deactivate, activate]` tuples. Used by `cloneRouter` to re-register
-   * guards on the clone with their original origin flag preserved.
-   */
-  getFactoriesByOrigin(): {
-    definition: [Record<string, GuardFnFactory<Dependencies>>, Record<string, GuardFnFactory<Dependencies>>];
-    external: [Record<string, GuardFnFactory<Dependencies>>, Record<string, GuardFnFactory<Dependencies>>];
-  };
-  /**
-   * Returns compiled lifecycle functions for transition execution.
-   *
-   * @returns Tuple of [canDeactivateFunctions, canActivateFunctions] as Maps
-   */
-  getFunctions(): [Map<string, GuardFn>, Map<string, GuardFn>];
-  canNavigateTo(toDeactivate: string[], toActivate: string[], toState: State, fromState: State | undefined): boolean;
-  /**
-   * Compiles a guard factory to its `GuardFn` WITHOUT registering it — surfaces
-   * a throwing / non-function factory eagerly. The prepare-then-commit
-   * add/replace path (`adoptRouteArtifacts`) calls this for every pending guard
-   * BEFORE the store swap (#956), so a malformed factory aborts the mutation
-   * with the store untouched. The returned function is then installed via the
-   * `precompiledFn` argument of {@link addCanActivate} / {@link addCanDeactivate}
-   * — no re-compile, so a factory with compile-time side effects runs exactly
-   * once. Same boolean-shorthand handling + compile + non-function check as the
-   * inline `#registerHandler` path, so a route-config `canActivate: true`
-   * (boolean shorthand, runtime-reachable via the public route type) compiles to
-   * the cached `TRUE_GUARD`/`FALSE_GUARD` instead of throwing on a non-callable.
-   */
-  compileGuardFactory(handler: GuardFnFactory<Dependencies> | boolean, methodName: string): GuardFn;
-}
-//#endregion
-//#region src/namespaces/RoutesNamespace/types.d.ts
-/**
- * Dependencies injected into RoutesNamespace.
- *
- * These are function references from the Router facade,
- * avoiding the need to pass the entire Router object.
- */
-interface RoutesDependencies<Dependencies extends DefaultDependencies = DefaultDependencies> {
-  /** Per-router logger instance (from `getInternals(router).logger`) */
-  logger: RouterLogger;
-  /**
-   * Register a canActivate handler for a route. `precompiledFn` installs an
-   * already-compiled `GuardFn` (from {@link compileGuard}) without re-invoking
-   * the factory — used by the #956 prepare-then-commit path so guards compile
-   * once, before the store swap.
-   */
-  addActivateGuard: (name: string, handler: GuardFnFactory<Dependencies>, precompiledFn?: GuardFn) => void;
-  /** Register a canDeactivate handler for a route (see {@link addActivateGuard}). */
-  addDeactivateGuard: (name: string, handler: GuardFnFactory<Dependencies>, precompiledFn?: GuardFn) => void;
-  /**
-   * Compile a guard factory to its `GuardFn` WITHOUT registering it — surfaces a
-   * throwing / non-function factory eagerly so the add/replace commit can
-   * validate every guard before swapping the store (#956).
-   */
-  compileGuard: (handler: GuardFnFactory<Dependencies>, methodName: string) => GuardFn;
-  /** Create state object */
-  makeState: <P extends Params = Params>(name: string, params?: P, path?: string, meta?: Record<string, Record<string, "url" | "query">>) => State<P>;
-  /** Get current router state */
-  getState: () => State | undefined;
-  /** Compare two states for equality */
-  areStatesEqual: (state1: State | undefined, state2: State | undefined, ignoreQueryParams?: boolean) => boolean;
-  /** Get a dependency by name */
-  getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K];
-  /** Forward state through facade (allows plugin interception) */
-  forwardState: <P extends Params = Params>(name: string, params: P) => SimpleState<P>;
-}
-/**
- * Configuration storage for routes.
- * Stores decoders, encoders, default params, and forward mappings.
- */
-interface RouteConfig {
-  /** Custom param decoders per route */
-  decoders: Record<string, (params: Params) => Params>;
-  /** Custom param encoders per route */
-  encoders: Record<string, (params: Params) => Params>;
-  /** Default params per route */
-  defaultParams: Record<string, Params>;
-  /** Forward mappings (source -> target) */
-  forwardMap: Record<string, string>;
-  /** Dynamic forward callbacks (source -> callback) */
-  forwardFnMap: Record<string, ForwardToCallback<any>>;
-}
-//#endregion
-//#region src/namespaces/RoutesNamespace/routesStore.d.ts
-interface RoutesStore<Dependencies extends DefaultDependencies = DefaultDependencies> {
-  /**
-   * DERIVED VIEW, not stored state: reconstructed from `tree` on every access
-   * via `routeTreeToDefinitions` (the lossless inverse cloneRouter already
-   * relies on — the `~` absolute marker is restored, child order is the
-   * definition order). The tree is the single source of truth, so a third
-   * retained copy of the route table (~30 B/route) is not kept. Every reader
-   * is a cold CRUD/plugin-registration path; the derive is O(N).
-   *
-   * The returned array is a FRESH snapshot each time — mutating it never
-   * affects the store (pass an explicitly-mutated snapshot to
-   * `commitTreeChanges` instead, as `remove` does).
-   */
-  readonly definitions: RouteDefinition[];
-  readonly config: RouteConfig;
-  tree: RouteTree;
-  matcher: Matcher;
-  /**
-   * Per-route-name cache of URL (path) param names, derived from `matcher` and
-   * read by `RoutesNamespace.getUrlParams` (powers `areStatesEqual` /
-   * `isActiveRoute`). Cleared on every `matcher` rebuild so comparisons never
-   * stay frozen to a route's pre-mutation param shape (#723).
-   */
-  readonly urlParamsCache: Map<string, string[]>;
-  resolvedForwardMap: Record<string, string>;
-  routeCustomFields: Record<string, Record<string, unknown>>;
-  rootPath: string;
-  readonly matcherOptions: CreateMatcherOptions | undefined;
-  depsStore: RoutesDependencies<Dependencies> | undefined;
-  lifecycleNamespace: RouteLifecycleNamespace<Dependencies> | undefined;
-  readonly pendingCanActivate: Map<string, GuardFnFactory<Dependencies>>;
-  readonly pendingCanDeactivate: Map<string, GuardFnFactory<Dependencies>>;
-}
-//#endregion
-//#region src/internals.d.ts
-interface RouterInternals<D extends DefaultDependencies = DefaultDependencies> {
-  readonly makeState: <P extends Params = Params>(name: string, params?: P, path?: string, meta?: Record<string, Record<string, "url" | "query">>) => State<P>;
-  readonly forwardState: <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>;
-  readonly buildStateResolved: (resolvedName: string, resolvedParams: Params) => RouteTreeState | undefined;
-  readonly matchPath: <P extends Params = Params>(path: string, options?: Options$1) => State<P> | undefined;
-  readonly getOptions: () => Options$1;
-  readonly addEventListener: <E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]) => Unsubscribe;
-  /**
-   * Route-tree mutation channel — internal access for the `getRoutesApi`
-   * wrapper. A dedicated bridge is required because the public
-   * `addEventListener<E extends EventName>` structurally rejects
-   * `"TREE_CHANGED"` (it is not in the public `EventName` union), is strict on
-   * duplicates, and exposes neither `emit` nor `listenerCount`.
-   */
-  readonly treeChanged: {
-    readonly emit: (event: TreeChangedEvent) => void;
-    readonly subscribe: (handler: (event: TreeChangedEvent) => void) => Unsubscribe;
-    readonly listenerCount: () => number;
-    /**
-     * True while a `TREE_CHANGED` emit is on the stack — `getRoutesApi` reads it
-     * to reject reentrant route-CRUD from a `subscribeChanges` handler (#1032).
-     */
-    readonly isEmitting: () => boolean;
-  };
-  readonly buildPath: (route: string, params?: Params) => string;
-  readonly emitTransitionError: (error: Error) => void;
-  /**
-   * Emits `TRANSITION_SUCCESS` directly (no FSM transition) — used by
-   * `getRoutesApi().replace()` to notify `router.subscribe` listeners when a
-   * structural replace revalidates the active state (#950). Mirrors the success
-   * emission `completeTransition` / `navigateToNotFound` perform.
-   */
-  readonly emitTransitionSuccess: (toState: State, fromState: State | undefined, opts?: NavigationOptions) => void;
-  /**
-   * Commits the not-found (`UNKNOWN_ROUTE`) state for `path` and emits
-   * `TRANSITION_SUCCESS` — the `NavigationNamespace.navigateToNotFound`
-   * primitive. `replace()` uses it when a structural replace drops the active
-   * route, so subscribers are notified instead of the state silently clearing
-   * (#950).
-   */
-  readonly navigateToNotFound: (path: string) => State;
-  readonly start: (path: string) => Promise<State>;
-  /**
-   * Plugin-only navigation entry point — delegates to
-   * `NavigationNamespace.navigateToState` (`getPluginApi(router).navigateToState`).
-   * Hidden from `Router`/`Navigator` to keep the userland surface minimal;
-   * see `core-types/src/api.ts` for usage docs.
-   */
-  readonly navigateToState: (state: State, options?: NavigationOptions) => Promise<State>;
-  readonly interceptors: Map<string, ((next: (...args: any[]) => any, ...args: any[]) => any)[]>;
-  readonly setRootPath: (rootPath: string) => void;
-  readonly getRootPath: () => string;
-  readonly getTree: () => RouteTree;
-  readonly isDisposed: () => boolean;
-  validator: RouterValidator | null;
-  readonly logger: RouterLogger;
-  readonly dependenciesGetStore: () => DependenciesStore<D>;
-  readonly getCloneState: () => {
-    options: Options$1;
-    dependencies: Record<string, unknown>;
-    pluginFactories: PluginFactory<D>[];
-    loggerConfig: LoggerConfig;
-  };
-  readonly routeGetStore: () => RoutesStore<D>;
-  readonly getStateName: () => string | undefined;
-  readonly isTransitioning: () => boolean;
-  readonly clearState: () => void;
-  readonly setState: (state: State) => void;
-  readonly routerExtensions: {
-    keys: string[];
-  }[];
-  readonly contextClaimRecords: Set<string>;
-  /**
-   * One-shot hydration scratchpad populated by `hydrateRouter` immediately
-   * before delegating to `router.start(parsed.path)` and cleared in the
-   * matching `finally`. SSR loader plugins read this slot directly via
-   * `getInternals(router).hydrationState` to short-circuit their own loader
-   * call when the server-resolved namespace value is already present in the
-   * parsed state (#596). `null` outside of an active `hydrateRouter`
-   * invocation.
-   */
-  hydrationState: SerializedRouterState | null;
-}
-declare function getInternals<D extends DefaultDependencies>(router: Router<D>): RouterInternals<D>;
-//#endregion
-export { type Matcher, type RouteTree, type RouterInternals, type RouterValidator, getInternals, validateRoute };
-//# sourceMappingURL=validation.d.mts.map
+import { RouteTree } from "./engine/builder/types.mjs";
+import { Matcher } from "./engine/createMatcher.mjs";
+import { validateRoute } from "./engine/validation/route-batch.mjs";
+import { RouterValidator } from "./types/RouterValidator.mjs";
+import { RouterInternals, getInternals } from "./internals.mjs";
+export { type Matcher, type RouteTree, type RouterInternals, type RouterValidator, getInternals, validateRoute };

package/dist/esm/validation.mjs

@@ -1,2 +1,2 @@
-import{c as e,f as t,i as n,l as r,n as i,r as a}from"./buildParamMeta-Bl0uORu6.mjs";function o(e,t){return TypeError(`[router.${e}] ${t}`)}function s(e,t,n){if(!r(e))throw o(n,`Invalid path for route "${t}": unbalanced constraint delimiter ('<' or '>') in "${e}"`);if(e.includes(`<>`))throw o(n,`Invalid path for route "${t}": empty constraint '<>' in "${e}" (a constraint body must be non-empty, e.g. '<[0-9]+>')`)}function c(e,t,n,r){let i=new Set;for(let a of e){if(i.has(a))throw o(n,`Invalid path for route "${t}": duplicate parameter name ':${a}' in "${r}" (a param name must be unique within a route — the second binding would overwrite the first)`);i.add(a)}}function l(t,n,r,i,a){let s=new Set(t);for(let t of n){if(e.test(t))throw o(i,`Invalid path for route "${r}": invalid query-param name "${t}" in "${a}" (a query-param name cannot contain '<' or '>' — a reverse-order modifier typo that leaked a constraint into the query; put the optional '?' after the constraint, ':id<...>?')`);if(s.has(t))throw o(i,`Invalid path for route "${r}": "${t}" is declared as both a path param and a query param in "${a}" — buildPath would emit its value twice (rename one)`)}}function u(e){let t=!0,n=!1,r=!1;for(let i of e){if(r){r=i!==`>`;continue}if(i===`<`){r=!0;continue}if(i===`/`){t=!0;continue}if(t&&=(n=i===`:`||i===`*`,!1),!n&&i.codePointAt(0)>=128)return!0}return!1}function d(e){for(let t=1;t<e.length;t++)if(e[t]===`?`&&e[t-1]!==`>`&&e[t+1]===`/`&&e[t+2]===`*`)return!0;return!1}function f(e,t,r,i){if(n(e))throw o(i,`Invalid path for route "${t}": two optional params directly before a splat are not supported in "${r}" — a single trie slot carries one optional→splat fork, so the omit-outer/take-inner form would silently reshape into the splat. Split into two routes, or drop the '?' on one`);if(d(e))throw o(i,`Invalid path for route "${t}": an unconstrained optional param before a splat is not supported in "${r}" — it is ambiguous (every multi-segment value has two readings). Add a constraint (e.g. ':lang<[a-z]+>?') or model it as two routes`)}function p(e,t,n){switch(e){case`name-less`:case`trailing-marker`:return`Invalid path for route "${t}": parameter marker (':' or '*') without a name in "${n}"`;case`fused-marker`:return`Invalid path for route "${t}": parameter marker (':' or '*') must begin a segment, but "${n}" fuses one to a static prefix (use a boundary marker like "/a/:b")`;case`fused-constraint-suffix`:return`Invalid path for route "${t}": text fused to a constraint '>' in "${n}" (a '<...>' must end its segment or be followed by '/' or an optional '?' — use "/:id<...>/rest", not "/:id<...>rest")`;case`constraint-in-static`:return`Invalid path for route "${t}": constraint '<...>' in a static segment in "${n}" (a '<...>' must follow a parameter marker ':' or '*' — attach it to a param like "/:id<...>", or drop it)`;case`optional-splat`:return`Invalid path for route "${t}": optional splat ('*name?') is not supported in "${n}" — a splat cannot be optional (use a required splat '*name')`;case`unbalanced-constraint`:case`empty-constraint`:return`Invalid path for route "${t}": invalid constraint in "${n}"`}}function m(e,t,n){try{return i(e)}catch(r){throw o(n,`Invalid path for route "${t}": ${(r instanceof Error?r.message:String(r)).replace(/^\[buildParamMeta] /,``)} (in "${e}")`)}}function h(e,t,n,r){if(typeof e!=`string`){let t;throw t=e===null?`null`:Array.isArray(e)?`array`:typeof e,o(n,`Route path must be a string, got ${t}`)}if(e===``)return;if(/\s/.test(e))throw o(n,`Invalid path for route "${t}": whitespace not allowed in "${e}"`);if(!/^([/?~]|[^/]+$)/.test(e))throw o(n,`Route "${t}" has invalid path format: "${e}". Path should start with '/', '~', '?' or be a relative segment.`);if(e.includes(`//`))throw o(n,`Invalid path for route "${t}": double slashes not allowed in "${e}"`);s(e,t,n);let{pathPattern:i,urlParams:d,queryParams:h}=m(e,t,n);c(d,t,n,e),l(d,h,t,n,e);let g=a(i);if(g!==void 0)throw o(n,p(g,t,e));if(f(i,t,e,n),u(i))throw o(n,`Invalid path for route "${t}": non-ASCII static segment in "${e}" — match compares static segments raw and rejects non-ASCII input, so this route would never match. Percent-encode it (e.g. '/caf%C3%A9') or use a param`);let _=r&&r.paramMeta.urlParams.length>0;if(e.startsWith(`~`)&&_)throw o(n,`Absolute path "${e}" cannot be used under parent route with URL parameters`)}const g=/^[A-Z_a-z][\w-]*$/,_=/\S/,v=1e4;function y(e){if(e===null)return`null`;if(typeof e==`object`){try{let t=e.constructor;if(typeof t==`function`&&t.name!==`Object`)return t.name||`object`}catch{}return`object`}return typeof e}function b(e){for(let t of Object.keys(e)){let n=Object.getOwnPropertyDescriptor(e,t);if(n&&(n.get||n.set))return!0}return!1}function x(e,t){if(!e||typeof e!=`object`)throw TypeError(`[router.${t}] Route must be an object, got ${y(e)}`);let n=Object.getPrototypeOf(e);if(n!==Object.prototype&&n!==null)throw TypeError(`[router.${t}] Route must be a plain object, got ${y(e)}`);if(b(e))throw TypeError(`[router.${t}] Route must not have getters or setters`)}function S(e,t){if(e.encodeParams!==void 0&&typeof e.encodeParams!=`function`)throw TypeError(`[router.${t}] Route "${String(e.name)}" encodeParams must be a function`)}function C(e,t){if(e.decodeParams!==void 0&&typeof e.decodeParams!=`function`)throw TypeError(`[router.${t}] Route "${String(e.name)}" decodeParams must be a function`)}function w(e,t){if(typeof e.name!=`string`)throw TypeError(`[router.${t}] Route name must be a string, got ${y(e.name)}`);let n=e.name;if(n===``)throw TypeError(`[router.${t}] Route name cannot be empty`);if(!_.test(n))throw TypeError(`[router.${t}] Route name cannot contain only whitespace`);if(n.length>v)throw TypeError(`[router.${t}] Route name exceeds maximum length of ${v} characters`);if(!n.startsWith(`@@`)){if(n.includes(`.`))throw TypeError(`[router.${t}] Route name "${n}" cannot contain dots. Use children array or { parent } option in addRoute() instead.`);if(!g.test(n))throw TypeError(`[router.${t}] Invalid route name "${n}". Name must start with a letter or underscore, followed by letters, numbers, underscores, or hyphens.`)}}function T(e,t){if(!t.includes(`.`))return e.children.get(t);let n=e;for(let e of t.split(`.`))if(n=n.children.get(e),!n)return;return n}function E(e,t,n){if(T(e,t))throw Error(`[router.${n}] Route "${t}" already exists`)}function D(e,t,n){if(e.has(t))throw Error(`[router.${n}] Duplicate route "${t}" in batch`);e.add(t)}function O(e,t,n,r){let i=t===``?e:T(e,t);if(i){for(let e of i.children.values())if(e.path===n)throw Error(`[router.${r}] Path "${n}" is already defined`)}}function k(e,t,n,r){let i=e.get(t);if(i?.has(n))throw Error(`[router.${r}] Path "${n}" is already defined`);i?i.add(n):e.set(t,new Set([n]))}function A(e,t,n,r=``,i,a){x(e,t);let o=e;w(o,t),h(o.path,o.name,t,n),S(o,t),C(o,t);let s=o.name,c=r?`${r}.${s}`:s;n&&c&&E(n,c,t),i&&D(i,c,t);let l=o.path,u=r;if(n&&O(n,u,l,t),a&&k(a,u,l,t),o.children!==void 0){if(!Array.isArray(o.children))throw TypeError(`[router.${t}] Route "${s}" children must be an array, got ${y(o.children)}`);for(let e of o.children)A(e,t,n,c,i,a)}}export{t as getInternals,A as validateRoute};
+import{a as e,i as t,n,r,u as i}from"./buildParamMeta-bOLhLF9h.mjs";function a(e,t){return TypeError(`[router.${e}] ${t}`)}function o(e,t,n,r){let i=new Set;for(let o of e){if(i.has(o))throw a(n,`Invalid path for route "${t}": duplicate parameter name ':${o}' in "${r}" (a param name must be unique within a route — the second binding would overwrite the first)`);i.add(o)}}function s(e,t,r,i,o){let s=new Set(e);for(let e of t){if(n.test(e))throw a(i,`Invalid path for route "${r}": invalid query-param name "${e}" in "${o}" (a query-param name cannot contain '<' or '>' — it would never round-trip; rename the query param)`);if(s.has(e))throw a(i,`Invalid path for route "${r}": "${e}" is declared as both a path param and a query param in "${o}" — buildPath would emit its value twice (rename one)`)}}function c(e){let t=!0,n=!1;for(let r of e){if(r===`/`){t=!0;continue}if(t&&=(n=r===`:`||r===`*`,!1),!n&&r.codePointAt(0)>=128)return!0}return!1}function l(e,t,n){switch(e){case`name-less`:case`trailing-marker`:return`Invalid path for route "${t}": parameter marker (':' or '*') without a name in "${n}"`;case`fused-marker`:return`Invalid path for route "${t}": parameter marker (':' or '*') must begin a segment, but "${n}" fuses one to a static prefix (use a boundary marker like "/a/:b")`}}function u(e,t){return e.code===`optional-removed`?`Invalid path for route "${t}": optional params are not supported — "${e.segment}". Declare two sibling routes instead: "${e.withoutSegment}" and "${e.requiredForm}" (the route hierarchy already expresses optionality)`:`Invalid path for route "${t}": regex constraints are not supported — '<' and '>' are reserved in path segments ("${e.segment}"). Match the segment as a plain string and validate the value in a guard (canActivate) or app code`}function d(n,i,d,f){if(typeof n!=`string`){let e;throw e=n===null?`null`:Array.isArray(n)?`array`:typeof n,a(d,`Route path must be a string, got ${e}`)}if(n===``)return;if(/\s/.test(n))throw a(d,`Invalid path for route "${i}": whitespace not allowed in "${n}"`);if(!/^([/?~]|[^/]+$)/.test(n))throw a(d,`Route "${i}" has invalid path format: "${n}". Path should start with '/', '~', '?' or be a relative segment.`);if(n.includes(`//`))throw a(d,`Invalid path for route "${i}": double slashes not allowed in "${n}"`);let{pathPattern:p,urlParams:m,queryParams:h}=r(n);o(m,i,d,n),s(m,h,i,d,n);let g=t(p);if(g!==void 0)throw a(d,u(g,i));let _=e(p);if(_!==void 0)throw a(d,l(_,i,n));if(c(p))throw a(d,`Invalid path for route "${i}": non-ASCII static segment in "${n}" — match compares static segments raw and rejects non-ASCII input, so this route would never match. Percent-encode it (e.g. '/caf%C3%A9') or use a param`);let v=f&&f.paramMeta.urlParams.length>0;if(n.startsWith(`~`)&&v)throw a(d,`Absolute path "${n}" cannot be used under parent route with URL parameters`)}const f=/^[A-Z_a-z][\w-]*$/,p=/\S/,m=1e4;function h(e){if(e===null)return`null`;if(typeof e==`object`){try{let t=e.constructor;if(typeof t==`function`&&t.name!==`Object`)return t.name||`object`}catch{}return`object`}return typeof e}function g(e){for(let t of Object.keys(e)){let n=Object.getOwnPropertyDescriptor(e,t);if(n&&(n.get||n.set))return!0}return!1}function _(e,t){if(!e||typeof e!=`object`)throw TypeError(`[router.${t}] Route must be an object, got ${h(e)}`);let n=Object.getPrototypeOf(e);if(n!==Object.prototype&&n!==null)throw TypeError(`[router.${t}] Route must be a plain object, got ${h(e)}`);if(g(e))throw TypeError(`[router.${t}] Route must not have getters or setters`)}function v(e,t){if(e.encodeParams!==void 0&&typeof e.encodeParams!=`function`)throw TypeError(`[router.${t}] Route "${String(e.name)}" encodeParams must be a function`)}function y(e,t){if(e.decodeParams!==void 0&&typeof e.decodeParams!=`function`)throw TypeError(`[router.${t}] Route "${String(e.name)}" decodeParams must be a function`)}function b(e,t){if(typeof e.name!=`string`)throw TypeError(`[router.${t}] Route name must be a string, got ${h(e.name)}`);let n=e.name;if(n===``)throw TypeError(`[router.${t}] Route name cannot be empty`);if(!p.test(n))throw TypeError(`[router.${t}] Route name cannot contain only whitespace`);if(n.length>m)throw TypeError(`[router.${t}] Route name exceeds maximum length of ${m} characters`);if(!n.startsWith(`@@`)){if(n.includes(`.`))throw TypeError(`[router.${t}] Route name "${n}" cannot contain dots. Use children array or { parent } option in addRoute() instead.`);if(!f.test(n))throw TypeError(`[router.${t}] Invalid route name "${n}". Name must start with a letter or underscore, followed by letters, numbers, underscores, or hyphens.`)}}function x(e,t){if(!t.includes(`.`))return e.children.get(t);let n=e;for(let e of t.split(`.`))if(n=n.children.get(e),!n)return;return n}function S(e,t,n){if(x(e,t))throw Error(`[router.${n}] Route "${t}" already exists`)}function C(e,t,n){if(e.has(t))throw Error(`[router.${n}] Duplicate route "${t}" in batch`);e.add(t)}function w(e,t,n,r){let i=t===``?e:x(e,t);if(i){for(let e of i.children.values())if(e.path===n)throw Error(`[router.${r}] Path "${n}" is already defined`)}}function T(e,t,n,r){let i=e.get(t);if(i?.has(n))throw Error(`[router.${r}] Path "${n}" is already defined`);i?i.add(n):e.set(t,new Set([n]))}function E(e,t,n,r=``,i,a){_(e,t);let o=e;b(o,t),d(o.path,o.name,t,n),v(o,t),y(o,t);let s=o.name,c=r?`${r}.${s}`:s;n&&c&&S(n,c,t),i&&C(i,c,t);let l=o.path,u=r;if(n&&w(n,u,l,t),a&&T(a,u,l,t),o.children!==void 0){if(!Array.isArray(o.children))throw TypeError(`[router.${t}] Route "${s}" children must be an array, got ${h(o.children)}`);for(let e of o.children)E(e,t,n,c,i,a)}}export{i as getInternals,E as validateRoute};
 //# sourceMappingURL=validation.mjs.map