@rangojs/router 0.4.0 → 0.4.1

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

@@ -1,182 +0,0 @@
-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;
-    fn?: LoaderFn<T, TParams, any>;
-    /** Composable default DSL items merged when the loader is mounted. */
-    use?: () => UseItems<LoaderUseItem>;
-};

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

@@ -1,93 +0,0 @@
-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.backup/types/route-config.d.ts

@@ -1,105 +0,0 @@
-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.backup/types/route-entry.d.ts

@@ -1,95 +0,0 @@
-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;
-    /**
-     * 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>;
-}