@real-router/core 0.55.0 → 0.57.0

package/src/types.ts

@@ -1,69 +0,0 @@
-// packages/core/src/types.ts
-
-/**
- * Core-internal types + re-exports from @real-router/types.
- *
- * Factory types (PluginFactory, GuardFnFactory) and
- * route config types (Route, RouteConfigUpdate) are canonical in @real-router/types
- * and re-exported here for backward compatibility.
- */
-
-import type {
-  LimitsConfig,
-  NavigationOptions,
-  Params,
-  RouterError as RouterErrorType,
-  RouteTreeState,
-  State,
-} from "@real-router/types";
-
-// Re-export from @real-router/types (canonical source)
-export type {
-  GuardFnFactory,
-  PluginFactory,
-  Route,
-  RouteConfigUpdate,
-  EventMethodMap,
-} from "@real-router/types";
-
-/**
- * Event argument tuples for the router's 7 events.
- *
- * Uses explicit `| undefined` unions (not optional `?`) to satisfy
- * `exactOptionalPropertyTypes` when passing undefined args from FSM payloads.
- */
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- must be `type` for Record<string, unknown[]> constraint
-export type RouterEventMap = {
-  $start: [];
-  $stop: [];
-  $$start: [toState: State, fromState: State | undefined];
-  $$leaveApprove: [toState: State, fromState: State | undefined];
-  $$success: [
-    toState: State,
-    fromState: State | undefined,
-    opts: NavigationOptions | undefined,
-  ];
-  $$error: [
-    toState: State | undefined,
-    fromState: State | undefined,
-    error: RouterErrorType | undefined,
-  ];
-  $$cancel: [toState: State, fromState: State | undefined];
-};
-
-/**
- * Immutable limits configuration type.
- */
-export type Limits = Readonly<LimitsConfig>;
-
-/**
- * Extended build result that includes segments for path building.
- * Used internally to avoid duplicate getSegmentsByName calls.
- *
- * @param segments - Route segments from getSegmentsByName (typed as unknown[] for cross-package compatibility)
- * @internal
- */
-export interface BuildStateResultWithSegments<P extends Params = Params> {
-  readonly state: RouteTreeState<P>;
-  readonly segments: readonly unknown[];
-}

package/src/utils/createRequestScope.ts

@@ -1,174 +0,0 @@
-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/getStaticPaths.ts

@@ -1,50 +0,0 @@
-import { getPluginApi } from "../api/getPluginApi";
-
-import type { DefaultDependencies, Router } from "@real-router/types";
-import type { RouteTree } from "route-tree";
-
-export type StaticPathEntries = Record<
-  string,
-  () => Promise<Record<string, string>[]>
->;
-
-function getLeafRouteNames(node: RouteTree): string[] {
-  const result: string[] = [];
-
-  for (const child of node.children.values()) {
-    if (child.children.size === 0) {
-      result.push(child.fullName);
-    } else {
-      result.push(...getLeafRouteNames(child));
-    }
-  }
-
-  return result;
-}
-
-export async function getStaticPaths<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
->(
-  router: Router<Dependencies>,
-  entries?: StaticPathEntries,
-): Promise<string[]> {
-  const tree = getPluginApi(router).getTree();
-  const leafRoutes = getLeafRouteNames(tree);
-  const paths: string[] = [];
-
-  for (const routeName of leafRoutes) {
-    const entryFn = entries?.[routeName];
-
-    if (entryFn) {
-      const paramSets = await entryFn();
-
-      for (const params of paramSets) {
-        paths.push(router.buildPath(routeName, params));
-      }
-    } else {
-      paths.push(router.buildPath(routeName, {}));
-    }
-  }
-
-  return paths;
-}

package/src/utils/hydrateRouter.ts

@@ -1,89 +0,0 @@
-import { getInternals } from "../internals";
-
-import type { SerializedRouterState } from "./serializeRouterState";
-import type { Router, State } from "@real-router/types";
-
-/**
- * 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.
- *
- * 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.
- *
- * 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
- * // Client
- * const router = createAppRouter();
- * 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 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"
-      ? (deserialize(source) as SerializedRouterState)
-      : (source as SerializedRouterState);
-
-  const ctx = getInternals(router);
-  const previous = ctx.hydrationState;
-
-  ctx.hydrationState = parsed;
-
-  try {
-    return await router.start(parsed.path);
-  } finally {
-    ctx.hydrationState = previous;
-  }
-}

package/src/utils/index.ts

@@ -1,27 +0,0 @@
-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 {
-  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,120 +0,0 @@
-import { serializeState } from "./serializeState";
-
-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 {
-  /**
-   * Plugin context namespaces to strip from the serialized output.
-   * Use when a plugin populates `state.context.<ns>` with non-JSON-serializable
-   * values (e.g., RSC payload: ReactNode trees containing functions/symbols).
-   *
-   * @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;
-}
-
-/**
- * XSS-safe JSON serialization of router State for SSR → client transport (#563).
- *
- * Strips `state.transition` (per-navigation `TransitionMeta` — meaningless after
- * hydration; the client's hydration commit produces its own `transition`).
- * Keeps `name`, `params`, `path`, and `context` (plugin context namespaces are
- * preserved as-is — server's `state.context.data` from `ssr-data-plugin` and
- * any other plugin claims travel to the client untouched).
- *
- * Pass `options.excludeContext` to strip specific namespaces from the output —
- * required for plugins that publish non-JSON-serializable values (e.g., RSC
- * `ReactNode` trees from `@real-router/rsc-server-plugin`).
- *
- * @example
- * ```typescript
- * // Server
- * const state = await router.start(req.url);
- * const html = `<script>window.__SSR_STATE__=${serializeRouterState(state)}</script>`;
- *
- * // Client
- * await hydrateRouter(router, window.__SSR_STATE__);
- * ```
- *
- * @example
- * ```typescript
- * // With RSC plugin: strip the "rsc" namespace before transport
- * 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,
-  options?: SerializeRouterStateOptions,
-): string {
-  const exclude = options?.excludeContext;
-
-  let context = state.context;
-
-  if (exclude?.length) {
-    const filtered: Record<string, unknown> = {};
-    const source = state.context;
-
-    for (const key of Object.keys(source)) {
-      if (!exclude.includes(key)) {
-        filtered[key] = source[key];
-      }
-    }
-
-    context = filtered;
-  }
-
-  const payload = {
-    name: state.name,
-    params: state.params,
-    path: state.path,
-    context,
-  };
-
-  return options?.serialize
-    ? serializeState(payload, { serialize: options.serialize })
-    : serializeState(payload);
-}

package/src/utils/serializeState.ts

@@ -1,63 +0,0 @@
-/**
- * Custom serializer signature for {@link serializeState} (#606).
- *
- * Compatible with `JSON.stringify` (default) as well as `devalue.stringify`,
- * `superjson.stringify`, or any user-supplied function that returns a JSON
- * string. The output is run through XSS-safe character escapes regardless
- * of which serializer produced it.
- */
-export type Serialize = (data: unknown) => string;
-
-export interface SerializeStateOptions {
-  /**
-   * Custom serializer (e.g., `devalue.stringify` / `superjson.stringify`) to
-   * support non-JSON types (Date / Map / Set / RegExp / BigInt). Defaults to
-   * `JSON.stringify`. Output is still XSS-escaped.
-   *
-   * @default JSON.stringify
-   */
-  serialize?: Serialize;
-}
-
-/**
- * XSS-safe JSON serialization for embedding data in HTML `<script>` tags.
- *
- * Escapes `<`, `>`, and `&` to their Unicode equivalents to prevent
- * injection via `</script>` or HTML entities inside inline scripts.
- *
- * Pass `options.serialize` to use a custom serializer such as `devalue` or
- * `superjson` for non-JSON types (Date/Map/Set/RegExp/BigInt). The serializer
- * must return a string; XSS-escape is applied to its output.
- *
- * @example
- * ```typescript
- * const json = serializeState({ name: "home", path: "/" });
- * const html = `<script>window.__STATE__=${json}</script>`;
- * ```
- *
- * @example
- * ```typescript
- * import * as devalue from "devalue";
- *
- * const json = serializeState(
- *   { date: new Date(), tags: new Set(["a", "b"]) },
- *   { serialize: devalue.stringify },
- * );
- * ```
- */
-export function serializeState(
-  data: unknown,
-  options?: SerializeStateOptions,
-): string {
-  const serialize = options?.serialize ?? JSON.stringify;
-  // JSON.stringify returns undefined for top-level `undefined`, Symbol,
-  // function, and other non-serializable values (lib.d.ts types it as
-  // `string` but the runtime can return undefined). A custom serializer
-  // that returns undefined for unsupported input is normalized the same way.
-  const serialized = (serialize(data) as string | undefined) ?? "null";
-
-  return serialized
-    .replaceAll("<", String.raw`\u003c`)
-    .replaceAll(">", String.raw`\u003e`)
-    .replaceAll("&", String.raw`\u0026`);
-}

package/src/validation.ts

@@ -1,12 +0,0 @@
-/**
- * Subpath export for @real-router/validation-plugin.
- *
- * Provides access to router internals so the plugin can install
- * ctx.validator and run retrospective validation at registration time.
- */
-
-export type { RouterValidator } from "./types/RouterValidator";
-
-export { getInternals } from "./internals";
-
-export type { RouterInternals } from "./internals";