@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/dist/types/server/handle-store.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Handle data structure: handleName -> segmentId -> entries[]
+ *
+ * @example
+ * ```ts
+ * {
+ *   "breadcrumbs": {
+ *     "$root.layout": [{ label: "Home", href: "/" }],
+ *     "shop.layout": [{ label: "Shop", href: "/shop" }],
+ *   }
+ * }
+ * ```
+ */
+export type HandleData = Record<string, Record<string, unknown[]>>;
+/**
+ * Build a HandleData snapshot from a HandleStore using segment ordering.
+ * Reads data directly from the store for each segment in order.
+ */
+export declare function buildHandleSnapshot(handleStore: HandleStore, segmentOrder: string[]): HandleData;
+/**
+ * HandleStore tracks pending handler promises and stores handle data.
+ *
+ * Combines two responsibilities:
+ * 1. Promise tracking - know when all handlers have resolved
+ * 2. Data storage - collect handle data pushed by handlers
+ * 3. Streaming - emit handle data via async iterator on each push
+ */
+export interface HandleStore {
+    /**
+     * Track a handler promise (non-blocking).
+     * Returns the promise unchanged - just registers it for tracking.
+     */
+    track<T>(promise: Promise<T>): Promise<T>;
+    /**
+     * Signal that no more track() calls will be made.
+     * settled will not resolve until seal() is called AND all tracked
+     * promises have settled. Calling stream() or getData() auto-seals.
+     */
+    seal(): void;
+    /**
+     * Promise that resolves when the store is sealed AND all tracked
+     * handlers have settled.
+     */
+    readonly settled: Promise<void>;
+    /**
+     * Optional error callback for late streaming-handle failures.
+     * Called when push() throws LateHandlePushError (handle pushed after
+     * stream completion). Allows the router to surface these errors
+     * to onError and telemetry.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Push handle data for a specific handle and segment.
+     * Multiple pushes to the same handle/segment accumulate in an array.
+     * Each push triggers an emission on the stream.
+     */
+    push(handleName: string, segmentId: string, data: unknown): void;
+    /**
+     * Get all collected handle data after all handlers have settled.
+     * Waits for `settled`, then returns the finalized data.
+     */
+    getData(): Promise<HandleData>;
+    /**
+     * Get an async iterator that yields handle data on each push.
+     * The iterator completes when all handlers have settled.
+     * Each yield contains the full accumulated state (not just the delta).
+     */
+    stream(): AsyncGenerator<HandleData, void, unknown>;
+    /**
+     * Get handle data for a specific segment (for caching).
+     * Returns data in format: { handleName: [values...] }
+     */
+    getDataForSegment(segmentId: string): Record<string, unknown[]>;
+    /**
+     * Replay cached handle data back into the store (for cache hits).
+     * Used to restore handle data when serving cached segments.
+     */
+    replaySegmentData(segmentId: string, segmentHandles: Record<string, unknown[]>): void;
+}
+/**
+ * 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 declare function createHandleStore(): HandleStore;

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

@@ -0,0 +1,32 @@
+/**
+ * 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 LoaderRegistryEntry } from "./fetchable-loader-store.js";
+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;
+/**
+ * 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<LoaderRegistryEntry | undefined>;
+/**
+ * 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 {};