@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.81

package/src/types/index.ts

@@ -0,0 +1,88 @@
+// 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,
+  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,210 @@
+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 {
+  DefaultEnv,
+  DefaultReverseRouteMap,
+  DefaultVars,
+} from "./global-namespace.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 = {},
+> = {
+  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>;
+  request: Request;
+  searchParams: URLSearchParams;
+  search: {} extends TSearch ? {} : ResolveSearchSchema<TSearch>;
+  pathname: string;
+  url: URL;
+  env: TEnv;
+  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)`. Only supported in DSL loaders on non-streaming
+   * trees (no `loading()`). Throws if called from a handler-invoked
+   * loader or when the tree uses streaming.
+   *
+   * @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
+};

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>
+>;

package/src/types/route-entry.ts

@@ -0,0 +1,120 @@
+import type { AllUseItems } from "../route-types.js";
+import type { TrailingSlashMode, ResolvedRouteMap } from "./route-config.js";
+
+/**
+ * Context captured for lazy include evaluation
+ */
+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;
+}
+
+/**
+ * Internal route entry stored in router
+ */
+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
+  >;
+}