@real-router/core 0.52.0 → 0.54.1

package/src/Router.ts

@@ -214,7 +214,7 @@ export class Router<
             this.#options.get(),
           ),
         interceptorsMap,
-      ) as unknown as RouterInternals["buildPath"],
+      ),
       emitTransitionError: (error) => {
         this.#eventBus.sendFailSafe(undefined, this.#state.get(), error);
       },
@@ -257,11 +257,7 @@ export class Router<
       dependenciesGetStore: () => this.#dependenciesStore,
       // Clone support (issue #173)
       cloneOptions: () => ({ ...this.#options.get() }),
-      cloneDependencies: () =>
-        ({ ...this.#dependenciesStore.dependencies }) as Record<
-          string,
-          unknown
-        >,
+      cloneDependencies: () => ({ ...this.#dependenciesStore.dependencies }),
       getLifecycleFactories: () => this.#routeLifecycle.getFactories(),
       getPluginFactories: () => this.#plugins.getAll(),
       routeGetStore: () => this.#routes.getStore(),
@@ -276,6 +272,7 @@ export class Router<
       },
       routerExtensions: [],
       contextClaimRecords: new Set(),
+      hydrationState: null,
     });
 
     // =========================================================================
@@ -677,16 +674,16 @@ export class Router<
   }
 
   #markDisposed(): void {
-    this.navigate = throwDisposed as never;
-    this.navigateToDefault = throwDisposed as never;
-    this.navigateToNotFound = throwDisposed as never;
-    this.start = throwDisposed as never;
-    this.stop = throwDisposed as never;
-    this.usePlugin = throwDisposed as never;
-
-    this.subscribe = throwDisposed as never;
-    this.subscribeLeave = throwDisposed as never;
-    this.canNavigateTo = throwDisposed as never;
+    this.navigate = throwDisposed;
+    this.navigateToDefault = throwDisposed;
+    this.navigateToNotFound = throwDisposed;
+    this.start = throwDisposed;
+    this.stop = throwDisposed;
+    this.usePlugin = throwDisposed;
+
+    this.subscribe = throwDisposed;
+    this.subscribeLeave = throwDisposed;
+    this.canNavigateTo = throwDisposed;
   }
 }
 

package/src/api/getDependenciesApi.ts

@@ -110,12 +110,7 @@ export function getDependenciesApi<
         "setDependency",
       );
 
-      setDependency(
-        ctx.dependenciesGetStore(),
-        name as string,
-        value,
-        ctx.validator,
-      );
+      setDependency(ctx.dependenciesGetStore(), name, value, ctx.validator);
     },
     setAll: (deps) => {
       throwIfDisposed(ctx.isDisposed);
@@ -144,7 +139,7 @@ export function getDependenciesApi<
 
       const store = ctx.dependenciesGetStore();
 
-      if (!Object.hasOwn(store.dependencies, name as string)) {
+      if (!Object.hasOwn(store.dependencies, name)) {
         ctx.validator?.dependencies.warnRemoveNonExistent(name);
       }
 
@@ -159,10 +154,7 @@ export function getDependenciesApi<
     has: (name) => {
       ctx.validator?.dependencies.validateDependencyName(name, "hasDependency");
 
-      return Object.hasOwn(
-        ctx.dependenciesGetStore().dependencies,
-        name as string,
-      );
+      return Object.hasOwn(ctx.dependenciesGetStore().dependencies, name);
     },
   };
 }

package/src/api/getPluginApi.ts

@@ -200,7 +200,7 @@ export function getPluginApi<
       throwIfDisposed(ctx.isDisposed);
       ctx.emitTransitionError(error);
     },
-    claimContextNamespace: ((namespace: string) => {
+    claimContextNamespace: (namespace: string) => {
       throwIfDisposed(ctx.isDisposed);
 
       if (ctx.contextClaimRecords.has(namespace)) {
@@ -213,13 +213,13 @@ export function getPluginApi<
 
       return {
         write(state: State, value: unknown) {
-          (state.context as Record<string, unknown>)[namespace] = value;
+          state.context[namespace] = value;
         },
         release() {
           ctx.contextClaimRecords.delete(namespace);
         },
       } satisfies ContextNamespaceClaim;
-    }) as PluginApi["claimContextNamespace"],
+    },
   };
 
   cache.set(router, api);

package/src/api/getRoutesApi.ts

@@ -360,7 +360,8 @@ function updateRouteConfig<
       const decoder = updates.decodeParams;
 
       store.config.decoders[name] = (params: Params): Params =>
-        (decoder(params) as Params | undefined) ?? params;
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime fallback if user-provided decoder violates its return type
+        decoder(params) ?? params;
     }
   }
 
@@ -371,7 +372,8 @@ function updateRouteConfig<
       const encoder = updates.encodeParams;
 
       store.config.encoders[name] = (params: Params): Params =>
-        (encoder(params) as Params | undefined) ?? params;
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime fallback if user-provided encoder violates its return type
+        encoder(params) ?? params;
     }
   }
 }

package/src/internals.ts

@@ -1,8 +1,9 @@
-import type { DependenciesStore } from "./namespaces/DependenciesNamespace";
+import type { DependenciesStore } from "./namespaces";
 import type { RoutesStore } from "./namespaces/RoutesNamespace";
 import type { Router as RouterClass } from "./Router";
 import type { EventMethodMap, GuardFnFactory, PluginFactory } from "./types";
 import type { RouterValidator } from "./types/RouterValidator";
+import type { SerializedRouterState } from "./utils";
 import type {
   DefaultDependencies,
   EventName,
@@ -105,6 +106,17 @@ export interface RouterInternals<
   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;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- existential type: stores RouterInternals for all Dependencies types

package/src/namespaces/DependenciesNamespace/dependenciesStore.ts

@@ -13,7 +13,7 @@ export interface DependenciesStore<
 export function createDependenciesStore<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 >(
-  initialDependencies: Partial<Dependencies> = {} as Dependencies,
+  initialDependencies: Partial<Dependencies> = {},
 ): DependenciesStore<Dependencies> {
   const dependencies = Object.create(null) as Partial<Dependencies>;
 

package/src/namespaces/NavigationNamespace/NavigationNamespace.ts

@@ -105,7 +105,8 @@ export class NavigationNamespace {
       /* v8 ignore next 3 -- @preserve: reachable only via validator-driven
          throws from buildNavigateState (validateStateBuilderArgs) — covered
          in @real-router/validation-plugin's suite, not in core. */
-      return Promise.reject(error as Error);
+      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- preserve original throw shape from user-provided buildNavigateState
+      return Promise.reject(error);
     }
 
     if (!toState) {
@@ -197,7 +198,8 @@ export class NavigationNamespace {
     try {
       ({ route, params } = deps.resolveDefault());
     } catch (error) {
-      return Promise.reject(error as Error);
+      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- preserve original throw shape from user-provided resolveDefault callback
+      return Promise.reject(error);
     }
 
     if (!route) {
@@ -233,6 +235,7 @@ export class NavigationNamespace {
       phase: "activating",
       ...(fromState && { from: fromState.name }),
       reason: "success",
+      replace: true,
       segments,
     };
 
@@ -240,7 +243,7 @@ export class NavigationNamespace {
 
     const state: State = {
       name: constants.UNKNOWN_ROUTE,
-      params: EMPTY_PARAMS as Params,
+      params: EMPTY_PARAMS,
       path,
       transition: transitionMeta,
       context: {},
@@ -404,7 +407,8 @@ export class NavigationNamespace {
         fromState,
       );
 
-      return Promise.reject(error as Error);
+      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- preserve original throw shape from guards or transition pipeline
+      return Promise.reject(error);
     }
   }
 

package/src/namespaces/NavigationNamespace/transition/completeTransition.ts

@@ -42,6 +42,10 @@ function buildTransitionMeta(
     meta.reload = opts.reload;
   }
 
+  if (opts.replace !== undefined) {
+    meta.replace = opts.replace;
+  }
+
   if (opts.redirected !== undefined) {
     meta.redirected = opts.redirected;
   }

package/src/namespaces/RoutesNamespace/RoutesNamespace.ts

@@ -64,7 +64,7 @@ export function createRouteState<P extends RouteParams = RouteParams>(
   return {
     name: resolvedName,
     params: matchResult.params as P,
-    meta: matchResult.meta as Record<string, Record<string, "url" | "query">>,
+    meta: matchResult.meta,
   };
 }
 
@@ -255,7 +255,7 @@ export class RoutesNamespace<
 
     const decodedParams =
       typeof this.#store.config.decoders[name] === "function"
-        ? this.#store.config.decoders[name](params as Params)
+        ? this.#store.config.decoders[name](params)
         : params;
 
     const { name: routeName, params: routeParams } = this.#deps.forwardState<P>(
@@ -503,7 +503,7 @@ export class RoutesNamespace<
       return {
         ...this.#store.config.defaultParams[routeName],
         ...params,
-      } as P;
+      };
     }
 
     return params;

package/src/namespaces/StateNamespace/StateNamespace.ts

@@ -129,7 +129,7 @@ export class StateNamespace {
     } else if (!params || params === EMPTY_PARAMS) {
       mergedParams = EMPTY_PARAMS as P;
     } else {
-      mergedParams = Object.freeze({ ...params }) as P;
+      mergedParams = Object.freeze({ ...params });
     }
 
     const state = {
@@ -141,7 +141,7 @@ export class StateNamespace {
     } as State<P>;
 
     if (meta) {
-      setStateMetaParams(state, meta as unknown as Params);
+      setStateMetaParams(state, meta);
     }
 
     return skipFreeze ? state : freezeStateInPlace(state);

package/src/utils/createRequestScope.ts

@@ -0,0 +1,174 @@
+import { cloneRouter } from "../api/cloneRouter";
+
+import type { Router as RouterClass } from "../Router";
+import type { DefaultDependencies, Router } from "@real-router/types";
+
+/**
+ * Subset of Node's `http.IncomingMessage` that `createRequestScope` relies on:
+ * a `"close"` event indicating that the client disconnected (or the response
+ * was fully sent) and the standard `removeListener` cleanup hook.
+ */
+export interface IncomingMessageLike {
+  on: (event: "close", listener: () => void) => unknown;
+  removeListener?: (event: "close", listener: () => void) => unknown;
+}
+
+/**
+ * Web `Request`-shaped object — anything carrying an `AbortSignal`. Web
+ * runtimes (Bun, Cloudflare Workers, Vite RSC) surface client-disconnect via
+ * `request.signal` directly, so no listener attachment is needed.
+ */
+export interface RequestLike {
+  signal: AbortSignal;
+}
+
+export type RequestScopeSource = IncomingMessageLike | RequestLike;
+
+export interface RequestScope<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> extends AsyncDisposable {
+  /**
+   * Per-request router clone. Carries `abortSignal` injected into its
+   * dependencies — loaders can `getDep("abortSignal")` and pass it to fetch /
+   * `withTimeout` for cooperative cancellation when the client disconnects.
+   */
+  readonly router: RouterClass<Dependencies>;
+
+  /**
+   * Aborts when the request closes (Node `IncomingMessage`'s `"close"` event)
+   * or when the upstream Web `Request.signal` aborts.
+   */
+  readonly signal: AbortSignal;
+
+  /**
+   * Detach the close listener (if attached to a Node `IncomingMessage`) and
+   * dispose the cloned router. Idempotent — safe to call multiple times or in
+   * combination with `Symbol.asyncDispose`.
+   */
+  dispose: () => Promise<void>;
+}
+
+function isRequestLike(request: RequestScopeSource): request is RequestLike {
+  return (
+    "signal" in request &&
+    typeof (request as Partial<RequestLike>).signal === "object" &&
+    (request as Partial<RequestLike>).signal !== undefined &&
+    typeof request.signal.aborted === "boolean"
+  );
+}
+
+/**
+ * Build a per-request router scope: clones `base`, attaches an `AbortSignal`
+ * tied to the request's lifetime, and exposes `dispose()` (plus
+ * `Symbol.asyncDispose` for `await using` declarations).
+ *
+ * Replaces the four-step boilerplate that every server entry repeats:
+ *
+ * 1. `new AbortController()` per request
+ * 2. `req.on("close", () => controller.abort())`
+ * 3. `cloneRouter(base, { ...deps, abortSignal: signal })`
+ * 4. `try { ... } finally { router.dispose() }`
+ *
+ * The signal is injected into the router clone under `abortSignal` so existing
+ * loaders that read `getDep("abortSignal")` keep working without changes.
+ *
+ * ## `await using` compatibility
+ *
+ * The scope implements `Symbol.asyncDispose`, so `await using scope = …` is
+ * supported on runtimes that ship the well-known `Symbol.asyncDispose`:
+ *
+ * - **Node.js 24+** (full support; partial in 20.4–20.17 only for `fs`/`stream`)
+ * - **Bun 1.0.23+**, **Deno 1.37+**
+ * - **Chrome / Edge 127+**, **Firefox 141+**
+ * - **Safari**: not yet supported (irrelevant in practice — this helper is
+ *   server-side only and never reaches the browser)
+ *
+ * On Node.js 22 LTS the well-known symbol is unavailable, so `await using`
+ * fails. **The bundled SSR examples therefore use the explicit
+ * `try/finally` + `await scope.dispose()` form**, which works on every
+ * runtime. Use `await using` only when you control the deployment target and
+ * know it ships the symbol.
+ *
+ * @example
+ * ```typescript
+ * // Explicit dispose — works on Node 18+, all browsers, every CI image
+ * export async function render(url: string, req: IncomingMessage) {
+ *   const scope = createRequestScope(req, baseRouter, { currentUser });
+ *   try {
+ *     scope.router.usePlugin(ssrDataPluginFactory(loaders));
+ *     return await renderShell(scope.router, url);
+ *   } finally {
+ *     await scope.dispose();
+ *   }
+ * }
+ *
+ * // `await using` — Node 24+, Bun, Deno, modern browsers
+ * export async function render(url: string, req: IncomingMessage) {
+ *   await using scope = createRequestScope(req, baseRouter, { currentUser });
+ *   scope.router.usePlugin(ssrDataPluginFactory(loaders));
+ *   return await renderShell(scope.router, url);
+ * }
+ *
+ * // Web runtime (signal already on the request)
+ * async function handler(request: Request) {
+ *   const scope = createRequestScope(request, baseRouter, { db });
+ *   try {
+ *     scope.router.usePlugin(rscServerPluginFactory(loaders));
+ *     return await render(scope.router, request.url);
+ *   } finally {
+ *     await scope.dispose();
+ *   }
+ * }
+ * ```
+ */
+export function createRequestScope<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  request: RequestScopeSource,
+  base: Router<Dependencies>,
+  deps?: Partial<Dependencies>,
+): RequestScope<Dependencies> {
+  let detach: (() => void) | undefined;
+  let signal: AbortSignal;
+
+  if (isRequestLike(request)) {
+    signal = request.signal;
+  } else {
+    const controller = new AbortController();
+    const onClose = (): void => {
+      controller.abort();
+    };
+
+    request.on("close", onClose);
+    signal = controller.signal;
+    detach = () => {
+      request.removeListener?.("close", onClose);
+    };
+  }
+
+  const router = cloneRouter(base, {
+    ...deps,
+    abortSignal: signal,
+  } as Dependencies);
+
+  let disposed = false;
+
+  const dispose = (): Promise<void> => {
+    if (disposed) {
+      return Promise.resolve();
+    }
+
+    disposed = true;
+    detach?.();
+    router.dispose();
+
+    return Promise.resolve();
+  };
+
+  return {
+    router,
+    signal,
+    dispose,
+    [Symbol.asyncDispose]: dispose,
+  };
+}

package/src/utils/hydrateRouter.ts

@@ -1,16 +1,51 @@
+import { getInternals } from "../internals";
+
+import type { SerializedRouterState } from "./serializeRouterState";
 import type { Router, State } from "@real-router/types";
 
 /**
- * Hydrate a fresh router from server-serialized State (#563).
+ * Custom deserializer signature for {@link hydrateRouter} (#606). Compatible
+ * with `JSON.parse` (default), `devalue.parse`, `superjson.parse`, or any
+ * user-supplied function.
+ */
+export type Deserialize = (json: string) => unknown;
+
+export interface HydrateRouterOptions {
+  /**
+   * Custom deserializer (e.g., `devalue.parse` / `superjson.parse`) for
+   * matching the `serialize` passed to {@link serializeRouterState}. Defaults
+   * to `JSON.parse`. Ignored when `source` is already an object.
+   *
+   * @default JSON.parse
+   *
+   * @example
+   * ```typescript
+   * import * as devalue from "devalue";
+   * await hydrateRouter(router, ssrJson, { deserialize: devalue.parse });
+   * ```
+   */
+  deserialize?: Deserialize;
+}
+
+/**
+ * Hydrate a fresh router from server-serialized State (#563, #596).
+ *
+ * Accepts either a JSON string (parsed via `JSON.parse` by default, or
+ * `options.deserialize` when provided) or a State-shaped object. Extracts
+ * `state.path` and delegates to `router.start(state.path)` — the canonical
+ * URL is the source of truth for the router on hydration.
  *
- * Accepts either a JSON string (parsed via `JSON.parse`) or a State-shaped
- * object. Extracts `state.path` and delegates to `router.start(state.path)` —
- * the canonical URL is the source of truth for the router on hydration.
+ * The full parsed state (incl. `state.context.<namespace>` payloads) is
+ * deposited into a one-shot scratchpad on `RouterInternals.hydrationState`
+ * before `start()` is invoked and cleared in the matching `finally`. SSR
+ * loader plugins (`@real-router/ssr-data-plugin`,
+ * `@real-router/rsc-server-plugin`) read this scratchpad to skip their loader
+ * call when the server-resolved namespace value is already present — avoiding
+ * the post-hydration loader re-run on first paint.
  *
- * The serialized State (produced by `serializeRouterState`) is still useful
- * for application-level concerns: `state.context.<namespace>` payloads (e.g.
- * server-side data from `ssr-data-plugin`) can be read separately by app code
- * before or after `hydrateRouter` resolves.
+ * Single-shot semantics: the scratchpad is consumed during the first `start()`
+ * triggered by `hydrateRouter` regardless of route mismatch; subsequent
+ * `start()` calls run loaders normally.
  *
  * @example
  * ```typescript
@@ -19,15 +54,36 @@ import type { Router, State } from "@real-router/types";
  * router.usePlugin(browserPluginFactory());
  * await hydrateRouter(router, window.__SSR_STATE__);
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With non-JSON types (Date / Map / Set / RegExp / BigInt) via devalue (#606)
+ * import * as devalue from "devalue";
+ *
+ * await hydrateRouter(router, window.__SSR_STATE__, {
+ *   deserialize: devalue.parse,
+ * });
+ * ```
  */
-export function hydrateRouter(
+export async function hydrateRouter(
   router: Router,
   source: string | { path: string },
+  options?: HydrateRouterOptions,
 ): Promise<State> {
+  const deserialize: Deserialize = options?.deserialize ?? JSON.parse;
   const parsed =
     typeof source === "string"
-      ? (JSON.parse(source) as { path: string })
-      : source;
+      ? (deserialize(source) as SerializedRouterState)
+      : (source as SerializedRouterState);
+
+  const ctx = getInternals(router);
+  const previous = ctx.hydrationState;
+
+  ctx.hydrationState = parsed;
 
-  return router.start(parsed.path);
+  try {
+    return await router.start(parsed.path);
+  } finally {
+    ctx.hydrationState = previous;
+  }
 }

package/src/utils/index.ts

@@ -1,11 +1,27 @@
+export { createRequestScope } from "./createRequestScope";
+
+export type {
+  IncomingMessageLike,
+  RequestLike,
+  RequestScope,
+  RequestScopeSource,
+} from "./createRequestScope";
+
 export { getStaticPaths } from "./getStaticPaths";
 
 export { hydrateRouter } from "./hydrateRouter";
 
+export type { Deserialize, HydrateRouterOptions } from "./hydrateRouter";
+
 export { serializeRouterState } from "./serializeRouterState";
 
-export type { SerializeRouterStateOptions } from "./serializeRouterState";
+export type {
+  SerializedRouterState,
+  SerializeRouterStateOptions,
+} from "./serializeRouterState";
 
 export { serializeState } from "./serializeState";
 
+export type { Serialize, SerializeStateOptions } from "./serializeState";
+
 export type { StaticPathEntries } from "./getStaticPaths";

package/src/utils/serializeRouterState.ts

@@ -1,6 +1,20 @@
 import { serializeState } from "./serializeState";
 
-import type { State } from "@real-router/types";
+import type { Serialize } from "./serializeState";
+import type { Params, State } from "@real-router/types";
+
+/**
+ * Parsed shape produced by {@link serializeRouterState} (after `JSON.parse`).
+ *
+ * Identical to {@link State} minus `transition` (per-navigation `TransitionMeta`
+ * is meaningless after hydration; the client builds its own on commit). Used as
+ * the input shape for {@link hydrateRouter} and as the type of the one-shot
+ * hydration scratchpad consumed by SSR loader plugins.
+ */
+export type SerializedRouterState<P extends Params = Params> = Omit<
+  State<P>,
+  "transition"
+>;
 
 export interface SerializeRouterStateOptions {
   /**
@@ -11,6 +25,25 @@ export interface SerializeRouterStateOptions {
    * @default []
    */
   excludeContext?: readonly string[];
+
+  /**
+   * Custom serializer (e.g., `devalue.stringify` / `superjson.stringify`) to
+   * support non-JSON types in `state.params` and `state.context.<ns>` payloads
+   * (Date / Map / Set / RegExp / BigInt). Defaults to `JSON.stringify`.
+   *
+   * Pair with the matching `deserialize` on `hydrateRouter` to round-trip the
+   * extended types on the client.
+   *
+   * @default JSON.stringify
+   *
+   * @example
+   * ```typescript
+   * import * as devalue from "devalue";
+   *
+   * const json = serializeRouterState(state, { serialize: devalue.stringify });
+   * ```
+   */
+  serialize?: Serialize;
 }
 
 /**
@@ -42,6 +75,16 @@ export interface SerializeRouterStateOptions {
  * const state = await router.start(url);
  * const json = serializeRouterState(state, { excludeContext: ["rsc"] });
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Non-JSON types (Date / Map / Set / RegExp / BigInt) via devalue (#606)
+ * import * as devalue from "devalue";
+ *
+ * const json = serializeRouterState(state, { serialize: devalue.stringify });
+ * // On the client:
+ * await hydrateRouter(router, json, { deserialize: devalue.parse });
+ * ```
  */
 export function serializeRouterState(
   state: State,
@@ -53,7 +96,7 @@ export function serializeRouterState(
 
   if (exclude?.length) {
     const filtered: Record<string, unknown> = {};
-    const source = state.context as Record<string, unknown>;
+    const source = state.context;
 
     for (const key of Object.keys(source)) {
       if (!exclude.includes(key)) {
@@ -64,10 +107,14 @@ export function serializeRouterState(
     context = filtered;
   }
 
-  return serializeState({
+  const payload = {
     name: state.name,
     params: state.params,
     path: state.path,
     context,
-  });
+  };
+
+  return options?.serialize
+    ? serializeState(payload, { serialize: options.serialize })
+    : serializeState(payload);
 }