@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.120

package/src/types/index.ts

@@ -0,0 +1,89 @@
+// Global namespace (must be imported for side effects: `declare global`)
+export type {
+  GetRegisteredRoutes,
+  DefaultHandlerRouteMap,
+  DefaultReverseRouteMap,
+  DefaultEnv,
+} from "./global-namespace.js";
+// Ensure the global namespace declaration is evaluated
+import "./global-namespace.js";
+
+// Route configuration
+export type {
+  DocumentProps,
+  ExtractParams,
+  TrailingSlashMode,
+  RouteConfig,
+  RouteDefinitionOptions,
+  RouteDefinition,
+  ResolvedRouteMap,
+} from "./route-config.js";
+
+// Boundaries (error/notFound)
+export type {
+  ErrorInfo,
+  ErrorBoundaryFallbackProps,
+  ErrorBoundaryHandler,
+  ClientErrorBoundaryFallbackProps,
+  LoaderDataResult,
+  NotFoundInfo,
+  NotFoundBoundaryFallbackProps,
+  NotFoundBoundaryHandler,
+} from "./boundaries.js";
+export { isLoaderDataResult } from "./boundaries.js";
+
+// Handler context and related types
+export type {
+  MiddlewareFn,
+  ScopedRouteMap,
+  Handler,
+  HandlerContext,
+  InternalHandlerContext,
+  GenericParams,
+  RevalidateParams,
+  ShouldRevalidateFn,
+  ActionRef,
+  RouteKeys,
+  ExtractRouteParams,
+  HandlersForRouteMap,
+  Revalidate,
+  Middleware,
+} from "./handler-context.js";
+
+// Segments
+export type {
+  ViewTransitionClass,
+  TransitionConfig,
+  ResolvedSegment,
+  SegmentMetadata,
+  SlotState,
+  RootLayoutProps,
+  MatchResult,
+} from "./segments.js";
+
+// Route entries
+export type { LazyIncludeContext, RouteEntry } from "./route-entry.js";
+
+// Loader types
+export type {
+  LoaderContext,
+  LoaderFn,
+  FetchableLoaderOptions,
+  LoadOptions,
+  LoaderDefinition,
+} from "./loader-types.js";
+
+// Cache types
+export type {
+  CacheContext,
+  CacheOptions,
+  PartialCacheOptions,
+  EntryCacheConfig,
+} from "./cache-types.js";
+
+// Error handling types
+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,126 @@
+/**
+ * RequestScope: the fields every user-facing context shares.
+ *
+ * A handler, middleware, loader, response handler, and the ALS-bound
+ * RequestContext are all different phases of the same request, and they
+ * all carry the same set of request-scoped capabilities: the raw Request,
+ * the parsed URL pair (`url` is cleaned of internal `_rsc*` params,
+ * `originalUrl` retains them), pathname/searchParams, platform bindings
+ * (`env`), and two escape hatches for work that outlives the response
+ * (`waitUntil`) or needs the raw Cloudflare runtime object
+ * (`executionContext`).
+ *
+ * Each public context type intersects `RequestScope<TEnv>` with its own
+ * phase-specific fields (e.g. `params`/`reverse` on HandlerContext,
+ * `headers`/`header()` on MiddlewareContext). That keeps platform surface
+ * in one place and lets the next runtime escape hatch we need land in
+ * one file instead of four.
+ */
+
+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 {
+  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,170 @@
+import type { ReactNode } from "react";
+
+/**
+ * Props for the Document component that wraps the entire application.
+ */
+export type DocumentProps = {
+  children: ReactNode;
+};
+
+/**
+ * Parse constraint values into a union type
+ * "a|b|c" -> "a" | "b" | "c"
+ */
+type ParseConstraint<T extends string> =
+  T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
+
+/**
+ * Extract param info from a param segment
+ *
+ * Handles:
+ * - :param -> { name: "param", optional: false, type: string }
+ * - :param? -> { name: "param", optional: true, type: string }
+ * - :param(a|b) -> { name: "param", optional: false, type: "a" | "b" }
+ * - :param(a|b)? -> { name: "param", optional: true, type: "a" | "b" }
+ */
+type ExtractParamInfo<T extends string> =
+  // Optional + constrained (with optional suffix): :param(a|b)?suffix
+  T extends `${infer Name}(${infer Constraint})?${string}`
+    ? { name: Name; optional: true; type: ParseConstraint<Constraint> }
+    : // Constrained (with optional suffix): :param(a|b)suffix
+      T extends `${infer Name}(${infer Constraint})${string}`
+      ? { name: Name; optional: false; type: ParseConstraint<Constraint> }
+      : // Optional (with optional suffix): :param?suffix
+        T extends `${infer Name}?${string}`
+        ? { name: Name; optional: true; type: string }
+        : // Param with dot-suffix: :param.html
+          T extends `${infer Name}.${string}`
+          ? { name: Name; optional: false; type: string }
+          : // Param with dash-suffix: :param-slug
+            T extends `${infer Name}-${string}`
+            ? { name: Name; optional: false; type: string }
+            : // Param with tilde-suffix: :param~v2
+              T extends `${infer Name}~${string}`
+              ? { name: Name; optional: false; type: string }
+              : // Required: :param (no suffix)
+                { name: T; optional: false; type: string };
+
+/**
+ * Build param object from info
+ */
+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;
+
+/**
+ * Merge two param objects preserving optionality
+ * Uses Pick to preserve the modifiers from source types
+ */
+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" }
+ *
+ * @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 }
+ */
+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";
+
+/**
+ * Route configuration object (alternative to string path)
+ */
+export type RouteConfig = {
+  path: string;
+  trailingSlash?: TrailingSlashMode;
+};
+
+/**
+ * Route definition options (global defaults)
+ */
+export type RouteDefinitionOptions = {
+  trailingSlash?: TrailingSlashMode;
+};
+
+export type RouteDefinition = {
+  [key: string]: string | RouteConfig | RouteDefinition;
+};
+
+/**
+ * Recursively flatten nested routes with depth limit to prevent infinite recursion
+ * Transforms: { products: { detail: "/product/:slug" } } => { "products.detail": "/product/:slug" }
+ * Also handles RouteConfig objects: { api: { path: "/api" } } => { "api": "/api" }
+ */
+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];
+
+/**
+ * Union to intersection helper
+ */
+type UnionToIntersection<U> = (
+  U extends unknown ? (k: U) => void : never
+) extends (k: infer I) => void
+  ? I
+  : never;
+
+/**
+ * Resolved route map - flattened route definitions with full paths
+ */
+export type ResolvedRouteMap<T extends RouteDefinition> = UnionToIntersection<
+  FlattenRoutes<T>
+>;