@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/dist/types/types/loader-types.d.ts

@@ -0,0 +1,234 @@
+import type { ContextVar } from "../context-var.js";
+import type { Handle } from "../handle.js";
+import type { HandlePush } from "../defer.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>;
+    /**
+     * Read a context variable — or READ collected handle data after
+     * `await ctx.rendered()` (the rendered-barrier contract; handle reads
+     * moved here from ctx.use(handle), which is now the write).
+     */
+    get: {
+        <T>(contextVar: ContextVar<T>): T | undefined;
+        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): TAccumulated;
+    } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
+    /**
+     * Access another loader's data, or WRITE handle data (meta, breadcrumbs, …)
+     * — handler parity: `ctx.use(Meta)({ title })` pushes exactly like it does
+     * in a handler. Handle READS live on `ctx.get(handle)` (after rendered()).
+     *
+     * For loaders: returns a promise (loaders run in parallel).
+     * For handles: returns the push function, legal for the whole body,
+     * streaming loaders included. Delivery is async by the race model: pushes
+     * that settle before the handler barrier ride the SSR handle snapshot;
+     * later ones stream to the client and apply post-hydration (document lane)
+     * or progressively (navigation/action lanes). To guarantee a loader's
+     * handles are in the SSR'd document, register it as
+     * `loader(Def, { stream: "navigation" })` so the document render awaits it
+     * (see {@link LoaderOptions}).
+     *
+     * @example
+     * ```typescript
+     * export const ProductLoader = createLoader(async (ctx) => {
+     *   "use server";
+     *   const product = await getProduct(ctx.params.slug);
+     *   ctx.use(Meta)({ title: product.name });
+     *   ctx.use(Breadcrumbs)({ label: product.name });
+     *   return product;
+     * });
+     * ```
+     */
+    use: {
+        <T, TLoaderParams = any>(loader: LoaderDefinition<T, TLoaderParams>): Promise<T>;
+        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): HandlePush<TData>;
+    };
+    /**
+     * **Experimental.** Wait for all non-loader segments to settle.
+     *
+     * After the returned promise resolves, handle data is available via
+     * `ctx.get(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.get(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;
+/**
+ * Delivery mode for a DSL-registered loader: `loader(Def, { stream })`.
+ *
+ * Default (omitted): the loader streams on every render. Its data, its
+ * `ctx.use(Handle)` pushes, and any `notFound()`/`redirect()` it throws may land
+ * AFTER the document Response is constructed, so none of them are guaranteed to
+ * be in the SSR'd HTML.
+ *
+ * `"navigation"` narrows streaming to client navigations only: on a DOCUMENT
+ * request the loader is awaited before first flush. `useLoader` still suspends,
+ * but on an already-settled promise, so no fallback paints. This is the
+ * SSR-completeness opt-in — the name is about WHERE streaming still applies, not
+ * about disabling it. Choose it when the loader feeds something that must exist
+ * in the document: `<head>` meta via a handle, or a real 404 status (an awaited
+ * `notFound()` deterministically precedes Response construction, where the
+ * streamed default only wins that race opportunistically). It does NOT change
+ * PPR capture behavior: capture renders mask loaders and skip this await.
+ *
+ * Scoped per LOADER, not per segment: a baked loader alongside a deliberately
+ * dynamic sibling awaits only itself, and the sibling keeps streaming behind its
+ * `loading()`/Suspense boundary.
+ */
+export type LoaderOptions = {
+    stream?: "navigation";
+};
+/**
+ * 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;
+    fn?: LoaderFn<T, TParams, any>;
+    /** Composable default DSL items merged when the loader is mounted. */
+    use?: () => UseItems<LoaderUseItem>;
+};

package/dist/types/types/request-scope.d.ts

@@ -0,0 +1,93 @@
+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 declare function fireAndForgetWaitUntil(fn: () => Promise<void>): void;
+/**
+ * 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/dist/types/types/route-config.d.ts

@@ -0,0 +1,105 @@
+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;
+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;
+} : T extends `${infer _Start}:${infer Param}/${infer Rest}` ? MergeParams<ParamFromInfo<ExtractParamInfo<Param>>, ExtractParams<`/${Rest}`, readonly [...Depth, unknown]>> : 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>>;
+export {};

package/dist/types/types/route-entry.d.ts

@@ -0,0 +1,98 @@
+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;
+    /** 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;
+    /** Owning router id; scopes search-schema/root-scope registration during
+     *  lazy include evaluation (route-map-builder.ts registries) */
+    routerId?: string;
+    /**
+     * 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>;
+    /**
+     * 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>;
+}