@rangojs/router 0.0.0-experimental.0b82333f

package/dist/server/handle-store.js

@@ -0,0 +1,142 @@
+/**
+ * Deep clone handle data to create a snapshot.
+ * @internal
+ */
+function cloneHandleData(data) {
+    const clone = {};
+    for (const handleName in data) {
+        clone[handleName] = {};
+        for (const segmentId in data[handleName]) {
+            clone[handleName][segmentId] = [...data[handleName][segmentId]];
+        }
+    }
+    return clone;
+}
+/**
+ * Create a new HandleStore instance.
+ *
+ * @example
+ * ```ts
+ * const handleStore = createHandleStore();
+ *
+ * // In router - track without awaiting
+ * const component = handleStore.track(entry.handler(context));
+ *
+ * // In handler - push handle data (value, promise, or async callback result)
+ * handleStore.push("breadcrumbs", segmentId, { label: "Home", href: "/" });
+ * handleStore.push("meta", segmentId, fetchMetaAsync()); // promise
+ *
+ * // Stream handle data progressively
+ * for await (const handles of handleStore.stream()) {
+ *   console.log("Handle update:", handles);
+ * }
+ * ```
+ */
+export function createHandleStore() {
+    const pending = [];
+    const data = {};
+    // Queue for pending emissions and resolver for waiting consumer
+    let pendingEmissions = [];
+    let emissionResolver = null;
+    let completed = false;
+    // Signal that a new emission is available
+    function signalEmission() {
+        if (emissionResolver) {
+            const resolver = emissionResolver;
+            emissionResolver = null;
+            resolver();
+        }
+    }
+    // Wait for the next emission or completion
+    function waitForEmission() {
+        if (pendingEmissions.length > 0 || completed) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            emissionResolver = resolve;
+        });
+    }
+    return {
+        track(promise) {
+            pending.push(promise);
+            return promise;
+        },
+        get settled() {
+            if (pending.length === 0) {
+                return Promise.resolve();
+            }
+            return Promise.allSettled(pending).then(() => { });
+        },
+        push(handleName, segmentId, value) {
+            if (!data[handleName]) {
+                data[handleName] = {};
+            }
+            if (!data[handleName][segmentId]) {
+                data[handleName][segmentId] = [];
+            }
+            data[handleName][segmentId].push(value);
+            // Queue a snapshot for emission
+            pendingEmissions.push(cloneHandleData(data));
+            signalEmission();
+        },
+        getData() {
+            return this.settled.then(() => data);
+        },
+        async *stream() {
+            // Set up completion handler
+            this.settled.then(() => {
+                completed = true;
+                signalEmission();
+            });
+            // Initial small delay to batch rapid synchronous pushes
+            // This allows multiple handles pushing in quick succession to be batched
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            // If we already have data, yield the accumulated state
+            if (Object.keys(data).length > 0) {
+                // Clear pending emissions since we're yielding current state
+                pendingEmissions = [];
+                yield cloneHandleData(data);
+            }
+            // Continue streaming on each push
+            while (!completed) {
+                await waitForEmission();
+                // Yield all pending emissions (yield latest only)
+                if (pendingEmissions.length > 0) {
+                    // Skip intermediate states, yield the latest
+                    const latest = pendingEmissions[pendingEmissions.length - 1];
+                    pendingEmissions = [];
+                    yield latest;
+                }
+            }
+            // Final yield only if there are pending emissions that weren't yielded
+            // (handles that pushed after our last yield but before completion)
+            if (pendingEmissions.length > 0) {
+                yield cloneHandleData(data);
+            }
+        },
+        getDataForSegment(segmentId) {
+            const result = {};
+            for (const handleName in data) {
+                if (data[handleName][segmentId]) {
+                    result[handleName] = [...data[handleName][segmentId]];
+                }
+            }
+            return result;
+        },
+        replaySegmentData(segmentId, segmentHandles) {
+            for (const handleName in segmentHandles) {
+                if (!data[handleName]) {
+                    data[handleName] = {};
+                }
+                // Replace with replayed data (not append) to avoid handle bleeding between routes.
+                // When a cached segment is restored, its handles should replace any existing data
+                // for that segment, not accumulate on top of data from a different route.
+                data[handleName][segmentId] = [...segmentHandles[handleName]];
+            }
+            // Trigger emission for streaming
+            pendingEmissions.push(cloneHandleData(data));
+            signalEmission();
+        },
+    };
+}
+//# sourceMappingURL=handle-store.js.map

package/dist/server/handle-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-store.js","sourceRoot":"","sources":["../../src/server/handle-store.ts"],"names":[],"mappings":"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"}

package/dist/server/loader-registry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Server-side loader registry for GET-based fetching
+ *
+ * Loaders are loaded lazily via dynamic imports when first requested.
+ * The RSC handler looks up loaders by $$id to execute them.
+ */
+import type { LoaderFn } from "../types.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+interface RegisteredLoader {
+    fn: LoaderFn<any, any, any>;
+    middleware: MiddlewareFn[];
+}
+type LazyLoaderImport = () => Promise<{
+    $$id: string;
+}>;
+/**
+ * Set the lazy loader imports map (called by the loader manifest)
+ */
+export declare function setLoaderImports(imports: Record<string, LazyLoaderImport>): void;
+/**
+ * Register a fetchable loader by $$id
+ * Called by createLoader when fetchable option is provided
+ */
+export declare function registerLoader(id: string, fn: LoaderFn<any, any, any>, middleware?: MiddlewareFn[]): void;
+/**
+ * Get a registered loader by $$id (synchronous)
+ * Returns undefined if loader is not registered
+ */
+export declare function getLoader(id: string): RegisteredLoader | undefined;
+/**
+ * Get a loader by $$id, loading it lazily if needed
+ * This is the primary method for the RSC handler to get loaders
+ *
+ * In production: IDs are hashed, looked up via the lazy import map
+ * In dev: IDs are "filePath#exportName", resolved via dynamic import
+ */
+export declare function getLoaderLazy(id: string): Promise<RegisteredLoader | undefined>;
+/**
+ * Check if a loader is registered by $$id
+ */
+export declare function hasLoader(id: string): boolean;
+/**
+ * Get all registered loader IDs (for debugging)
+ */
+export declare function getRegisteredLoaderIds(): string[];
+/**
+ * Register a loader by its $$id (injected by Vite plugin)
+ * This is called during module loading to cache loaders
+ */
+export declare function registerLoaderById(loader: {
+    $$id: string;
+    fn?: LoaderFn<any, any, any>;
+}): void;
+export {};
+//# sourceMappingURL=loader-registry.d.ts.map

package/dist/server/loader-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader-registry.d.ts","sourceRoot":"","sources":["../../src/server/loader-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D,UAAU,gBAAgB;IACxB,EAAE,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5B,UAAU,EAAE,YAAY,EAAE,CAAC;CAC5B;AAaD,KAAK,gBAAgB,GAAG,MAAM,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAGxD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GACxC,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC3B,UAAU,GAAE,YAAY,EAAO,GAC9B,IAAI,CAIN;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAElE;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CA0DvC;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;CAC9B,GAAG,IAAI,CAgBP"}

package/dist/server/loader-registry.js

@@ -0,0 +1,132 @@
+/**
+ * Server-side loader registry for GET-based fetching
+ *
+ * Loaders are loaded lazily via dynamic imports when first requested.
+ * The RSC handler looks up loaders by $$id to execute them.
+ */
+import { getFetchableLoader } from "./fetchable-loader-store.js";
+// Server-side cache - maps loader $$id to function and middleware
+// This is a CACHE populated by getLoaderLazy() when loaders are first accessed.
+// The source of truth is fetchableLoaderRegistry in loader.ts, which is populated
+// when createLoader() runs. This cache exists to:
+// 1. Avoid repeated lookups/imports for the same loader
+// 2. Support lazy loading in production (loaders imported on-demand)
+// 3. Provide a stable reference for the RSC handler
+const loaderRegistry = new Map();
+let lazyLoaderImports = null;
+/**
+ * Set the lazy loader imports map (called by the loader manifest)
+ */
+export function setLoaderImports(imports) {
+    lazyLoaderImports = new Map(Object.entries(imports));
+}
+/**
+ * Register a fetchable loader by $$id
+ * Called by createLoader when fetchable option is provided
+ */
+export function registerLoader(id, fn, middleware = []) {
+    // Always update the registry entry. During HMR, the module is re-executed
+    // with the new loader function, so we must replace the stale reference.
+    loaderRegistry.set(id, { fn, middleware });
+}
+/**
+ * Get a registered loader by $$id (synchronous)
+ * Returns undefined if loader is not registered
+ */
+export function getLoader(id) {
+    return loaderRegistry.get(id);
+}
+/**
+ * Get a loader by $$id, loading it lazily if needed
+ * This is the primary method for the RSC handler to get loaders
+ *
+ * In production: IDs are hashed, looked up via the lazy import map
+ * In dev: IDs are "filePath#exportName", resolved via dynamic import
+ */
+export async function getLoaderLazy(id) {
+    // Check if already cached in main registry
+    const existing = loaderRegistry.get(id);
+    if (existing) {
+        return existing;
+    }
+    // Check the fetchable loader registry (populated by createLoader)
+    const fetchable = getFetchableLoader(id);
+    if (fetchable) {
+        // Cache in main registry for future requests
+        loaderRegistry.set(id, fetchable);
+        return fetchable;
+    }
+    // Try to lazy load from the import map (production mode)
+    if (lazyLoaderImports && lazyLoaderImports.size > 0) {
+        const lazyImport = lazyLoaderImports.get(id);
+        if (lazyImport) {
+            try {
+                // Import the loader module - this triggers createLoader which registers fn
+                await lazyImport();
+                // Now try to get from fetchable registry (createLoader registered it)
+                const registered = getFetchableLoader(id);
+                if (registered) {
+                    loaderRegistry.set(id, registered);
+                    return registered;
+                }
+            }
+            catch (error) {
+                console.error(`[LoaderRegistry] Failed to load loader "${id}":`, error);
+            }
+        }
+    }
+    // Dev mode fallback: parse the ID and use Vite's dynamic import
+    // ID format in dev: "src/path/to/file.ts#ExportName"
+    const hashIndex = id.indexOf("#");
+    if (hashIndex !== -1) {
+        const filePath = id.slice(0, hashIndex);
+        try {
+            // In dev mode, Vite handles dynamic imports
+            // Just importing the module triggers createLoader which registers the fn
+            await import(/* @vite-ignore */ `/${filePath}`);
+            // Now try to get from fetchable registry
+            const registered = getFetchableLoader(id);
+            if (registered) {
+                loaderRegistry.set(id, registered);
+                return registered;
+            }
+        }
+        catch (error) {
+            console.error(`[LoaderRegistry] Failed to load loader "${id}":`, error);
+        }
+    }
+    return undefined;
+}
+/**
+ * Check if a loader is registered by $$id
+ */
+export function hasLoader(id) {
+    return loaderRegistry.has(id) || getFetchableLoader(id) !== undefined;
+}
+/**
+ * Get all registered loader IDs (for debugging)
+ */
+export function getRegisteredLoaderIds() {
+    return Array.from(loaderRegistry.keys());
+}
+/**
+ * Register a loader by its $$id (injected by Vite plugin)
+ * This is called during module loading to cache loaders
+ */
+export function registerLoaderById(loader) {
+    if (!loader.$$id) {
+        return;
+    }
+    // For fetchable loaders, fn is stored in the fetchable registry by $$id.
+    // Always re-check the fetchable registry so HMR picks up the new function.
+    const fetchable = getFetchableLoader(loader.$$id);
+    if (fetchable) {
+        loaderRegistry.set(loader.$$id, fetchable);
+        return;
+    }
+    // Fall back to using fn from the loader object (non-fetchable loaders)
+    if (loader.fn) {
+        loaderRegistry.set(loader.$$id, { fn: loader.fn, middleware: [] });
+    }
+}
+//# sourceMappingURL=loader-registry.js.map

package/dist/server/loader-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader-registry.js","sourceRoot":"","sources":["../../src/server/loader-registry.ts"],"names":[],"mappings":"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"}

package/dist/server/request-context.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Request Context - AsyncLocalStorage for passing request-scoped data throughout rendering
+ *
+ * This is the unified context used everywhere:
+ * - Middleware execution
+ * - Route handlers and loaders
+ * - Server components during rendering
+ * - Error boundaries and streaming
+ *
+ * Available via getRequestContext() anywhere in the request lifecycle.
+ */
+import type { CookieOptions } from "../router/middleware.js";
+import type { LoaderDefinition } from "../types.js";
+import type { Handle } from "../handle.js";
+import { type HandleStore } from "./handle-store.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
+/**
+ * Unified request context available via getRequestContext()
+ *
+ * This is the same context passed to middleware and handlers.
+ * Use this when you need access to request data outside of route handlers.
+ */
+export interface RequestContext<TEnv = unknown, TParams = Record<string, string>> {
+    /** Platform bindings (Cloudflare env, etc.) */
+    env: TEnv;
+    /** Original HTTP request */
+    request: Request;
+    /** Parsed URL (system params like _rsc* are NOT filtered here) */
+    url: URL;
+    /** URL pathname */
+    pathname: string;
+    /** URL search params (system params like _rsc* are NOT filtered here) */
+    searchParams: URLSearchParams;
+    /** Variables set by middleware (same as ctx.var) */
+    var: Record<string, any>;
+    /** Get a variable set by middleware */
+    get: <K extends string>(key: K) => any;
+    /** Set a variable (shared with middleware and handlers) */
+    set: <K extends string>(key: K, value: any) => void;
+    /**
+     * Route params (populated after route matching)
+     * Initially empty, then set to matched params
+     */
+    params: TParams;
+    /**
+     * Stub response for setting headers/cookies
+     * Headers set here are merged into the final response
+     */
+    res: Response;
+    /** Get a cookie value from the request */
+    cookie(name: string): string | undefined;
+    /** Get all cookies from the request */
+    cookies(): Record<string, string>;
+    /** Set a cookie on the response */
+    setCookie(name: string, value: string, options?: CookieOptions): void;
+    /** Delete a cookie */
+    deleteCookie(name: string, options?: Pick<CookieOptions, "domain" | "path">): void;
+    /** Set a response header */
+    header(name: string, value: string): void;
+    /**
+     * Access loader data or push handle data.
+     *
+     * For loaders: Returns a promise that resolves to the loader data.
+     * Loaders are executed in parallel and memoized per request.
+     *
+     * For handles: Returns a push function to add data for this segment.
+     * Handle data accumulates across all matched route segments.
+     *
+     * @example
+     * ```typescript
+     * // Loader usage
+     * const cart = await ctx.use(CartLoader);
+     *
+     * // Handle usage
+     * const push = ctx.use(Breadcrumbs);
+     * push({ label: "Shop", href: "/shop" });
+     * ```
+     */
+    use: {
+        <T, TLoaderParams = any>(loader: LoaderDefinition<T, TLoaderParams>): Promise<T>;
+        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): (data: TData | Promise<TData> | (() => Promise<TData>)) => void;
+    };
+    /** HTTP method (GET, POST, PUT, PATCH, DELETE, etc.) */
+    method: string;
+    /** @internal Handle store for tracking handle data across segments */
+    _handleStore: HandleStore;
+    /** @internal Cache store for segment caching (optional, used by CacheScope) */
+    _cacheStore?: SegmentCacheStore;
+    /**
+     * Schedule work to run after the response is sent.
+     * On Cloudflare Workers, uses ctx.waitUntil().
+     * On Node.js, runs as fire-and-forget.
+     *
+     * @example
+     * ```typescript
+     * ctx.waitUntil(async () => {
+     *   await cacheStore.set(key, data, ttl);
+     * });
+     * ```
+     */
+    waitUntil(fn: () => Promise<void>): void;
+    /**
+     * Register a callback to run when the response is created.
+     * Callbacks are sync and receive the response. They can:
+     * - Inspect response status/headers
+     * - Return a modified response
+     * - Schedule async work via waitUntil
+     *
+     * @example
+     * ```typescript
+     * ctx.onResponse((res) => {
+     *   if (res.status === 200) {
+     *     ctx.waitUntil(async () => await cacheIt());
+     *   }
+     *   return res;
+     * });
+     * ```
+     */
+    onResponse(callback: (response: Response) => Response): void;
+    /** @internal Registered onResponse callbacks */
+    _onResponseCallbacks: Array<(response: Response) => Response>;
+    /**
+     * Current theme setting (only available when theme is enabled in router config)
+     *
+     * Returns the theme value from the cookie, or the default theme if not set.
+     * This is the user's preference ("light", "dark", or "system"), not the resolved value.
+     *
+     * @example
+     * ```typescript
+     * route("settings", (ctx) => {
+     *   const currentTheme = ctx.theme; // "light" | "dark" | "system" | undefined
+     *   return <SettingsPage theme={currentTheme} />;
+     * });
+     * ```
+     */
+    theme?: Theme;
+    /**
+     * Set the theme (only available when theme is enabled in router config)
+     *
+     * Sets a cookie with the new theme value. The change takes effect on the next request.
+     *
+     * @example
+     * ```typescript
+     * route("settings", (ctx) => {
+     *   if (ctx.method === "POST") {
+     *     const formData = await ctx.request.formData();
+     *     const newTheme = formData.get("theme") as Theme;
+     *     ctx.setTheme(newTheme);
+     *   }
+     *   return <SettingsPage />;
+     * });
+     * ```
+     */
+    setTheme?: (theme: Theme) => void;
+    /** @internal Theme configuration (null if theme not enabled) */
+    _themeConfig?: ResolvedThemeConfig | null;
+}
+/**
+ * Run a function within a request context
+ * Used by the RSC handler to provide context to server actions
+ */
+export declare function runWithRequestContext<TEnv, T>(context: RequestContext<TEnv>, fn: () => T): T;
+/**
+ * Get the current request context
+ * Returns undefined if not running within a request context
+ */
+export declare function getRequestContext<TEnv = unknown>(): RequestContext<TEnv> | undefined;
+/**
+ * Update params on the current request context
+ * Called after route matching to populate route params
+ */
+export declare function setRequestContextParams(params: Record<string, string>): void;
+/**
+ * Get the current request context, throwing if not available
+ * Use this when context is required (e.g., in loader actions)
+ */
+export declare function requireRequestContext<TEnv = unknown>(): RequestContext<TEnv>;
+/**
+ * Cloudflare Workers ExecutionContext (subset we need)
+ */
+export interface ExecutionContext {
+    waitUntil(promise: Promise<any>): void;
+    passThroughOnException(): void;
+}
+/**
+ * Options for creating a request context
+ */
+export interface CreateRequestContextOptions<TEnv> {
+    env: TEnv;
+    request: Request;
+    url: URL;
+    variables: Record<string, any>;
+    /** Optional cache store for segment caching (used by CacheScope) */
+    cacheStore?: SegmentCacheStore;
+    /** Optional Cloudflare execution context for waitUntil support */
+    executionContext?: ExecutionContext;
+    /** Optional theme configuration (enables ctx.theme and ctx.setTheme) */
+    themeConfig?: ResolvedThemeConfig | null;
+}
+/**
+ * Create a full request context with all methods implemented
+ *
+ * This is used by the RSC handler to create the unified context that's:
+ * - Available via getRequestContext() throughout the request
+ * - Passed to middleware as ctx
+ * - Passed to handlers as ctx
+ */
+export declare function createRequestContext<TEnv>(options: CreateRequestContextOptions<TEnv>): RequestContext<TEnv>;
+/**
+ * Options for creating the use() function
+ */
+export interface CreateUseFunctionOptions<TEnv> {
+    handleStore: HandleStore;
+    loaderPromises: Map<string, Promise<any>>;
+    getContext: () => RequestContext<TEnv>;
+}
+/**
+ * Create the use() function for loader and handle composition.
+ *
+ * This is the unified implementation used by both RequestContext and HandlerContext.
+ * - For loaders: executes and memoizes loader functions
+ * - For handles: returns a push function to add handle data
+ */
+export declare function createUseFunction<TEnv>(options: CreateUseFunctionOptions<TEnv>): RequestContext["use"];
+//# sourceMappingURL=request-context.d.ts.map

package/dist/server/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"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"}