@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/types/index.ts

@@ -0,0 +1,81 @@
+export type {
+  GetRegisteredRoutes,
+  DefaultHandlerRouteMap,
+  DefaultReverseRouteMap,
+  DefaultEnv,
+} from "./global-namespace.js";
+import "./global-namespace.js";
+
+export type {
+  DocumentProps,
+  ExtractParams,
+  TrailingSlashMode,
+  RouteConfig,
+  RouteDefinitionOptions,
+  RouteDefinition,
+  ResolvedRouteMap,
+} from "./route-config.js";
+
+export type {
+  ErrorInfo,
+  ErrorBoundaryFallbackProps,
+  ErrorBoundaryHandler,
+  ClientErrorBoundaryFallbackProps,
+  LoaderDataResult,
+  NotFoundInfo,
+  NotFoundBoundaryFallbackProps,
+  NotFoundBoundaryHandler,
+} from "./boundaries.js";
+export { isLoaderDataResult } from "./boundaries.js";
+
+export type {
+  MiddlewareFn,
+  ScopedRouteMap,
+  Handler,
+  HandlerContext,
+  InternalHandlerContext,
+  GenericParams,
+  RevalidateParams,
+  ShouldRevalidateFn,
+  ActionRef,
+  RouteKeys,
+  ExtractRouteParams,
+  HandlersForRouteMap,
+  Revalidate,
+  Middleware,
+} from "./handler-context.js";
+
+export type {
+  ViewTransitionClass,
+  TransitionConfig,
+  TransitionWhenFn,
+  TransitionWhenContext,
+  ResolvedSegment,
+  SegmentMetadata,
+  SlotState,
+  RootLayoutProps,
+  MatchResult,
+} from "./segments.js";
+
+export type { LazyIncludeContext, RouteEntry } from "./route-entry.js";
+
+export type {
+  LoaderContext,
+  LoaderFn,
+  FetchableLoaderOptions,
+  LoadOptions,
+  LoaderDefinition,
+} from "./loader-types.js";
+
+export type {
+  CacheContext,
+  CacheOptions,
+  PartialCacheOptions,
+  EntryCacheConfig,
+} from "./cache-types.js";
+
+export type {
+  ErrorPhase,
+  OnErrorContext,
+  OnErrorCallback,
+} from "./error-types.js";

package/src/types/loader-types.ts

@@ -0,0 +1,212 @@
+import type { ContextVar } from "../context-var.js";
+import type { Handle } from "../handle.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+import type { ScopedReverseFunction } from "../reverse.js";
+import type { SearchSchema, ResolveSearchSchema } from "../search-params.js";
+import type { UseItems, LoaderUseItem } from "../route-types.js";
+import type {
+  DefaultEnv,
+  DefaultReverseRouteMap,
+  DefaultVars,
+} from "./global-namespace.js";
+import type { RequestScope } from "./request-scope.js";
+
+/**
+ * Context passed to loader functions during execution
+ *
+ * Loaders run after middleware but before handlers, so they have access
+ * to middleware-set variables via get().
+ *
+ * @template TParams - Route params type (e.g., { slug: string })
+ * @template TEnv - Environment type for bindings/variables
+ *
+ * @example
+ * ```typescript
+ * const CartLoader = createLoader(async (ctx) => {
+ *   "use server";
+ *   const user = ctx.get("user");  // From auth middleware
+ *   return await db.cart.get(user.id);
+ * });
+ *
+ * // With typed params:
+ * const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
+ *   "use server";
+ *   const { slug } = ctx.params;  // slug is typed as string
+ *   return await db.products.findBySlug(slug);
+ * });
+ * ```
+ */
+export type LoaderContext<
+  TParams = Record<string, string | undefined>,
+  TEnv = DefaultEnv,
+  TBody = unknown,
+  TSearch extends SearchSchema = {},
+> = RequestScope<TEnv> & {
+  params: TParams;
+  /**
+   * Route params extracted from the URL pattern match (server-side only).
+   * Unlike `params`, these cannot be overridden by client-provided loader params.
+   * Use this when you need trusted, server-matched route params for auth or
+   * resource scoping.
+   */
+  routeParams: Record<string, string>;
+  search: {} extends TSearch ? {} : ResolveSearchSchema<TSearch>;
+  get: {
+    <T>(contextVar: ContextVar<T>): T | undefined;
+  } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
+  /**
+   * Access another loader's data, or read handle data after rendered().
+   *
+   * For loaders: returns a promise (loaders run in parallel).
+   * For handles: returns collected data (only after `await ctx.rendered()`).
+   */
+  use: {
+    <T, TLoaderParams = any>(
+      loader: LoaderDefinition<T, TLoaderParams>,
+    ): Promise<T>;
+    <TData, TAccumulated = TData[]>(
+      handle: Handle<TData, TAccumulated>,
+    ): TAccumulated;
+  };
+  /**
+   * **Experimental.** Wait for all non-loader segments to settle.
+   *
+   * After the returned promise resolves, handle data is available via
+   * `ctx.use(handle)`. Supported in DSL loaders, including on streaming
+   * trees that use `loading()` — the barrier waits for the streaming
+   * handlers to finish pushing before it resolves. Throws if called from a
+   * handler-invoked loader, or if a handler is already awaiting this loader
+   * via `ctx.use()` (that would deadlock — use a loader-to-loader
+   * dependency instead).
+   *
+   * @example
+   * ```typescript
+   * const PricesLoader = createLoader(async (ctx) => {
+   *   "use server";
+   *   await ctx.rendered();
+   *   const products = ctx.use(Products); // reads handle data
+   *   return pricing.getLive(products.map(p => p.id));
+   * });
+   * ```
+   */
+  rendered: () => Promise<void>;
+  /**
+   * HTTP method (GET, POST, PUT, PATCH, DELETE)
+   * Available when loader is called via load({ method: "POST", ... })
+   */
+  method: string;
+  /**
+   * Request body for POST/PUT/PATCH/DELETE requests
+   * Available when loader is called via load({ method: "POST", body: {...} })
+   */
+  body: TBody | undefined;
+  /**
+   * Form data when loader is invoked via action (fetchable loaders)
+   * Available when loader is called via form submission
+   */
+  formData?: FormData;
+  /**
+   * Generate URLs from route names.
+   * Same scoped reverse as route handlers — `.name` resolves within the
+   * current include() scope, `name` resolves globally.
+   */
+  reverse: ScopedReverseFunction<
+    Record<string, string>,
+    DefaultReverseRouteMap
+  >;
+};
+
+/**
+ * Loader function signature
+ *
+ * @template T - The return type of the loader
+ * @template TParams - Route params type (defaults to generic Record)
+ * @template TEnv - Environment type for bindings/variables
+ *
+ * @example
+ * ```typescript
+ * const myLoader: LoaderFn<{ items: Item[] }> = async (ctx) => {
+ *   "use server";
+ *   return { items: await db.items.list() };
+ * };
+ *
+ * // With typed params:
+ * const productLoader: LoaderFn<Product, { slug: string }> = async (ctx) => {
+ *   "use server";
+ *   const { slug } = ctx.params;  // typed as string
+ *   return await db.products.findBySlug(slug);
+ * };
+ * ```
+ */
+export type LoaderFn<
+  T,
+  TParams = Record<string, string | undefined>,
+  TEnv = DefaultEnv,
+> = (ctx: LoaderContext<TParams, TEnv>) => Promise<T> | T;
+
+/**
+ * Options for fetchable loaders
+ *
+ * Middleware uses the same MiddlewareFn signature as route/app middleware,
+ * enabling reuse of the same middleware functions everywhere.
+ */
+export type FetchableLoaderOptions = {
+  fetchable?: true;
+  middleware?: MiddlewareFn[];
+};
+
+/**
+ * Options for load() calls - type-safe union based on method
+ */
+export type LoadOptions =
+  | {
+      method?: "GET";
+      params?: Record<string, string>;
+    }
+  | {
+      method: "POST" | "PUT" | "PATCH" | "DELETE";
+      params?: Record<string, string>;
+      body?: FormData | Record<string, any>;
+    };
+
+/**
+ * Loader definition object
+ *
+ * Created via createLoader(). Contains the loader name and function.
+ * On client builds, the fn is stripped by the bundler (via "use server" directive).
+ *
+ * @template T - The return type of the loader
+ * @template TParams - Route params type (for type-safe params access)
+ *
+ * @example
+ * ```typescript
+ * // Definition (same file works on server and client)
+ * export const CartLoader = createLoader(async (ctx) => {
+ *   "use server";
+ *   return await db.cart.get(ctx.get("user").id);
+ * });
+ *
+ * // With typed params:
+ * export const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
+ *   "use server";
+ *   const { slug } = ctx.params;  // slug is typed as string
+ *   return await db.products.findBySlug(slug);
+ * });
+ *
+ * // Client usage (preferred — cache-safe, always fresh)
+ * const { data } = useLoader(CartLoader);
+ *
+ * // Server escape hatch (handler needs data directly)
+ * const cart = await ctx.use(CartLoader);
+ * ```
+ */
+export type LoaderDefinition<
+  T = any,
+  TParams = Record<string, string | undefined>,
+> = {
+  __brand: "loader";
+  $$id: string; // Injected by Vite plugin (exposeInternalIds) - unique identifier
+  fn?: LoaderFn<T, TParams, any>; // Optional - server-side only, stored in registry for RSC
+  /** Composable default DSL items merged when the loader is mounted. */
+  use?: () => UseItems<LoaderUseItem>;
+};

package/src/types/request-scope.ts

@@ -0,0 +1,112 @@
+import type { DefaultEnv } from "./global-namespace.js";
+
+/**
+ * Minimal subset of Cloudflare Workers' ExecutionContext that the router
+ * uses. Defined locally so the package does not depend on
+ * `@cloudflare/workers-types`. Consumers that want the full type can cast.
+ *
+ * On non-Cloudflare runtimes (Node, dev server, tests), this is undefined
+ * — portable apps should prefer `ctx.waitUntil(...)`, which degrades
+ * gracefully. `ctx.executionContext` is the escape hatch for libraries
+ * (MCP, Durable Object routing, etc.) that type their arguments as the
+ * raw ExecutionContext.
+ */
+export interface ExecutionContext {
+  waitUntil(promise: Promise<any>): void;
+  passThroughOnException(): void;
+}
+
+/**
+ * Fallback `waitUntil` body used when no Cloudflare `ExecutionContext`
+ * is available (Node, dev, tests). Runs the work fire-and-forget and
+ * logs errors so they don't silently swallow.
+ *
+ * Exported so every `waitUntil` call site degrades identically instead
+ * of inventing its own fallback policy.
+ */
+export function fireAndForgetWaitUntil(fn: () => Promise<void>): void {
+  // Defer fn() invocation to a microtask so a SYNCHRONOUS throw in a non-async
+  // callback (e.g. `() => { somethingThatThrows(); return p; }`) becomes a
+  // rejected promise we catch here, not an exception that escapes into the
+  // request flow. waitUntil is fire-and-forget: a background-task failure must
+  // never break the response.
+  Promise.resolve()
+    .then(fn)
+    .catch((err) => console.error("[waitUntil] Background task failed:", err));
+}
+
+/**
+ * Fields present on every user-facing request context.
+ *
+ * @template TEnv - Platform bindings type (Cloudflare env, etc.).
+ */
+export interface RequestScope<TEnv = DefaultEnv> {
+  /**
+   * The original incoming Request object (transport URL intact).
+   * Use `url` / `searchParams` for application logic — those have
+   * internal `_rsc*` params stripped. `request` preserves the raw URL
+   * when you need original headers, method, or body.
+   */
+  request: Request;
+
+  /**
+   * The request URL with internal `_rsc*` transport params stripped.
+   * Use this for routing, link generation, and display.
+   */
+  url: URL;
+
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params. Use `url` for application logic
+   * — this is only needed for advanced cases like debugging or custom
+   * cache keying.
+   */
+  originalUrl: URL;
+
+  /** URL pathname (same as `url.pathname`). */
+  pathname: string;
+
+  /**
+   * Query parameters from the URL (system params like `_rsc*` are
+   * filtered). Always a standard `URLSearchParams` instance.
+   */
+  searchParams: URLSearchParams;
+
+  /**
+   * Platform bindings (DB, KV, secrets, etc.). On Cloudflare Workers
+   * these are the `env` object passed to the Worker's `fetch()` handler.
+   */
+  env: TEnv;
+
+  /**
+   * Schedule work to run after the response is sent.
+   * On Cloudflare Workers, delegates to `executionContext.waitUntil()`.
+   * On Node / dev / tests, runs as fire-and-forget with error logging.
+   *
+   * @example
+   * ```typescript
+   * ctx.waitUntil(async () => {
+   *   await cacheStore.set(key, data, ttl);
+   * });
+   * ```
+   */
+  waitUntil(fn: () => Promise<void>): void;
+
+  /**
+   * Raw Cloudflare Workers `ExecutionContext`, when running on a
+   * Cloudflare-compatible runtime. Undefined elsewhere.
+   *
+   * Escape hatch for libraries that type their arguments as
+   * `ExecutionContext` (MCP `fetch`, `routeAgentRequest`, etc.).
+   * For the common "do work after the response" case, prefer
+   * `ctx.waitUntil(...)` — it is platform-neutral.
+   *
+   * @example
+   * ```typescript
+   * path.any("/mcp", (ctx) =>
+   *   emailMcp.fetch(ctx.request, ctx.env, ctx.executionContext!),
+   * );
+   * ```
+   */
+  executionContext?: ExecutionContext;
+}

package/src/types/route-config.ts

@@ -0,0 +1,138 @@
+import type { ReactNode } from "react";
+
+/**
+ * Props for the Document component that wraps the entire application.
+ */
+export type DocumentProps = {
+  children: ReactNode;
+};
+
+type ParseConstraint<T extends string> =
+  T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
+
+// Named catch-all (`:name*` / `:name+`) is matched BEFORE the `?`/suffix
+// branches. Its modifier is anchored to the END of the token (no trailing
+// `${string}`) so it is a true suffix and never mis-splits a constraint body
+// such as `id(\d+)`. Both are a required `string`: a matched catch-all always
+// binds a value (possibly ""), so the key is always present.
+type ExtractParamInfo<T extends string> =
+  T extends `${infer Name}(${infer Constraint})?${string}`
+    ? { name: Name; optional: true; type: ParseConstraint<Constraint> }
+    : T extends `${infer Name}(${infer Constraint})${string}`
+      ? { name: Name; optional: false; type: ParseConstraint<Constraint> }
+      : T extends `${infer Name}*`
+        ? { name: Name; optional: false; type: string }
+        : T extends `${infer Name}+`
+          ? { name: Name; optional: false; type: string }
+          : T extends `${infer Name}?${string}`
+            ? { name: Name; optional: true; type: string }
+            : T extends `${infer Name}.${string}`
+              ? { name: Name; optional: false; type: string }
+              : T extends `${infer Name}-${string}`
+                ? { name: Name; optional: false; type: string }
+                : T extends `${infer Name}~${string}`
+                  ? { name: Name; optional: false; type: string }
+                  : { name: T; optional: false; type: string };
+
+type ParamFromInfo<Info> = Info extends {
+  name: infer N extends string;
+  optional: true;
+  type: infer V;
+}
+  ? { [K in N]?: V }
+  : Info extends {
+        name: infer N extends string;
+        optional: false;
+        type: infer V;
+      }
+    ? { [K in N]: V }
+    : never;
+
+type MergeParams<A, B> = Pick<A, keyof A> & Pick<B, keyof B> extends infer O
+  ? { [K in keyof O]: O[K] }
+  : never;
+
+/**
+ * Extract route params from a pattern with depth limit to prevent infinite recursion
+ *
+ * Supports:
+ * - Required params: /:slug -> { slug: string }
+ * - Optional params: /:locale? -> { locale?: string }
+ * - Constrained params: /:locale(en|gb) -> { locale: "en" | "gb" }
+ * - Optional + constrained: /:locale(en|gb)? -> { locale?: "en" | "gb" }
+ * - Named catch-all: /:path+ (one-or-more), /:slug* (zero-or-more) -> string
+ *
+ * @example
+ * ExtractParams<"/products/:id"> // { id: string }
+ * ExtractParams<"/:locale?/blog/:slug"> // { locale?: string; slug: string }
+ * ExtractParams<"/:locale(en|gb)/blog"> // { locale: "en" | "gb" }
+ * ExtractParams<"/:locale(en|gb)?/blog/:slug"> // { locale?: "en" | "gb"; slug: string }
+ * ExtractParams<"/docs/:slug*"> // { slug: string }
+ * ExtractParams<"/shop/:path+"> // { path: string }
+ */
+export type ExtractParams<
+  T extends string,
+  Depth extends readonly unknown[] = [],
+> = Depth["length"] extends 10
+  ? { [key: string]: string | undefined } // Fallback to generic params if too deep
+  : // Match param with remaining path: :param.../rest
+    T extends `${infer _Start}:${infer Param}/${infer Rest}`
+    ? MergeParams<
+        ParamFromInfo<ExtractParamInfo<Param>>,
+        ExtractParams<`/${Rest}`, readonly [...Depth, unknown]>
+      >
+    : // Match param at end: :param...
+      T extends `${infer _Start}:${infer Param}`
+      ? ParamFromInfo<ExtractParamInfo<Param>>
+      : {};
+
+/**
+ * Trailing slash handling mode
+ * - "never": Redirect URLs with trailing slash to without
+ * - "always": Redirect URLs without trailing slash to with
+ * - "ignore": Match both with and without trailing slash
+ */
+export type TrailingSlashMode = "never" | "always" | "ignore";
+
+export type RouteConfig = {
+  path: string;
+  trailingSlash?: TrailingSlashMode;
+};
+
+export type RouteDefinitionOptions = {
+  trailingSlash?: TrailingSlashMode;
+};
+
+export type RouteDefinition = {
+  [key: string]: string | RouteConfig | RouteDefinition;
+};
+
+type FlattenRoutes<
+  T extends RouteDefinition,
+  Prefix extends string = "",
+  Depth extends readonly unknown[] = [],
+> = Depth["length"] extends 5
+  ? never
+  : {
+      [K in keyof T]: T[K] extends string
+        ? Record<`${Prefix}${K & string}`, T[K]>
+        : T[K] extends RouteConfig
+          ? Record<`${Prefix}${K & string}`, T[K]["path"]>
+          : T[K] extends RouteDefinition
+            ? FlattenRoutes<
+                T[K],
+                `${Prefix}${K & string}.`,
+                readonly [...Depth, unknown]
+              >
+            : never;
+    }[keyof T];
+
+type UnionToIntersection<U> = (
+  U extends unknown ? (k: U) => void : never
+) extends (k: infer I) => void
+  ? I
+  : never;
+
+export type ResolvedRouteMap<T extends RouteDefinition> = UnionToIntersection<
+  FlattenRoutes<T>
+>;

package/src/types/route-entry.ts

@@ -0,0 +1,114 @@
+import type { AllUseItems } from "../route-types.js";
+import type { TrailingSlashMode, ResolvedRouteMap } from "./route-config.js";
+
+export interface LazyIncludeContext {
+  urlPrefix: string;
+  namePrefix: string | undefined;
+  parent: unknown; // EntryData - avoid circular import
+  /** Counter snapshot from pattern extraction for consistent shortCode indices */
+  counters?: Record<string, number>;
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+  /** Root scope flag for dot-local reverse resolution */
+  rootScoped?: boolean;
+  /**
+   * Positional include scope token composed from the parent scope plus this
+   * include's sibling index (`${parentScope}I${idx}`). Applied to direct-
+   * descendant shortCodes during lazy evaluation so routes inside the
+   * include cannot collide with siblings declared outside it.
+   */
+  includeScope?: string;
+}
+
+export interface RouteEntry<TEnv = any> {
+  prefix: string;
+  /**
+   * Pre-computed static prefix for fast short-circuit matching.
+   * Extracted from prefix at registration time (everything before first param).
+   *
+   * Examples:
+   * - "/api" -> staticPrefix = "/api"
+   * - "/site/:locale" -> staticPrefix = "/site"
+   * - "/:locale" -> staticPrefix = "" (empty, can't optimize)
+   *
+   * At runtime: if staticPrefix && !pathname.startsWith(staticPrefix), skip entry.
+   */
+  staticPrefix: string;
+  /**
+   * Route patterns map. For lazy entries, this starts as empty and is
+   * populated on first request.
+   */
+  routes: ResolvedRouteMap<any>;
+  /**
+   * Trailing slash config per route key
+   * If not specified for a route, defaults to pattern-based detection
+   */
+  trailingSlash?: Record<string, TrailingSlashMode>;
+  /**
+   * Supported handler shapes:
+   *   - sync: () => Array<AllUseItems>
+   *   - lazy import: () => Promise<{ default: () => Array<AllUseItems> }>
+   *   - lazy function: () => Promise<() => Array<AllUseItems>>
+   *
+   * Direct Promise<Array> is NOT supported and rejected at runtime.
+   */
+  handler: () =>
+    | Array<AllUseItems>
+    | Promise<{ default: () => Array<AllUseItems> }>
+    | Promise<() => Array<AllUseItems>>;
+  mountIndex: number;
+
+  /**
+   * Router ID that owns this entry. Used to namespace the manifest cache
+   * so multi-router setups (host routing) don't share cached EntryData
+   * across routers with overlapping mountIndex + routeKey combinations.
+   */
+  routerId?: string;
+
+  /**
+   * Route keys in this entry that have pre-render handlers.
+   * Used by the non-trie match path to set the `pr` flag.
+   */
+  prerenderRouteKeys?: Set<string>;
+
+  /**
+   * Route keys in this entry that are wrapped with `Passthrough()`.
+   * Used by the non-trie match path to set the `pt` flag.
+   */
+  passthroughRouteKeys?: Set<string>;
+
+  // === Lazy evaluation fields ===
+
+  /**
+   * Whether this entry is lazily evaluated.
+   * When true, routes are populated on first matching request.
+   */
+  lazy?: boolean;
+
+  /**
+   * For lazy entries: the UrlPatterns to evaluate
+   */
+  lazyPatterns?: unknown;
+
+  /**
+   * For lazy entries: captured context at definition time
+   */
+  lazyContext?: LazyIncludeContext;
+
+  /**
+   * For lazy entries: whether patterns have been evaluated
+   */
+  lazyEvaluated?: boolean;
+
+  /**
+   * Cache profiles for DSL-time cache("profileName") resolution.
+   * Set on all entries (lazy and non-lazy) so loadManifest() can
+   * propagate them into the HelperContext Store.
+   */
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+}