@rangojs/router 0.4.0 → 0.4.1

package/dist/types.backup/cache/profile-registry.d.ts

@@ -1,40 +0,0 @@
-/**
- * Cache profile resolution.
- *
- * Named cache profiles for the "use cache" directive define TTL, SWR, and
- * optional default tags. createRouter() resolves the user's profiles once via
- * resolveCacheProfiles() and threads the resulting map onto each request
- * context; the "use cache: <profile>" runtime path reads it from there
- * (request-scoped) — there is no global registry.
- */
-export interface CacheProfile {
-    /** Time-to-live in seconds */
-    ttl: number;
-    /** Stale-while-revalidate window in seconds */
-    swr?: number;
-    /** Default cache tags for invalidation */
-    tags?: string[];
-    /**
-     * When true, a stale entry encountered during a server action's revalidation
-     * render is re-executed in the FOREGROUND (the action response reflects the
-     * refreshed value) instead of being served stale + revalidated in the
-     * background. Only the store write is deferred. Use this for mutation-related
-     * cached data that an action should refresh immediately; ordinary navigations
-     * always keep SWR. Default false: incidental TTL staleness must not turn an
-     * unrelated action into a synchronous cache-refresh barrier — for strong
-     * read-your-own-writes after a mutation, prefer updateTag() (a hard purge, so
-     * the action's own re-render is a fresh foreground miss).
-     *
-     * Honored only by `"use cache"` functions; route-level `cache()` and cached
-     * loaders ignore it (use updateTag() there).
-     */
-    foregroundOnAction?: boolean;
-}
-/**
- * Validate and merge user profiles with the default profile.
- * Returns a new object suitable for both DSL-time and request-scoped use.
- *
- * Used by createRouter() to compute the resolved profile map once,
- * stored on the router instance and passed to every request context.
- */
-export declare function resolveCacheProfiles(profiles?: Record<string, CacheProfile>): Record<string, CacheProfile>;

package/dist/types.backup/cache/read-through-swr.d.ts

@@ -1,60 +0,0 @@
-/**
- * SWR Read-Through Engine
- *
- * Generic read-through cache with stale-while-revalidate support
- * for item-level caching (getItem/setItem).
- *
- * Flow:
- * 1. Lookup cached item by key
- * 2. Fresh hit → deserialize, return
- * 3. Stale hit → deserialize, return, revalidate in background
- * 4. Miss → execute, cache write (blocking when no waitUntil), return
- */
-import type { CacheItemResult, CacheItemOptions } from "./types.js";
-import type { CacheErrorReporter } from "./cache-error.js";
-type WaitUntilHost = {
-    waitUntil?: (fn: () => Promise<void>) => void;
-} & CacheErrorReporter;
-export interface ReadThroughItemConfig<T> {
-    /** Retrieve a cached item by key */
-    getItem: (key: string) => Promise<CacheItemResult | null>;
-    /** Store a serialized item by key */
-    setItem: (key: string, value: string, options?: CacheItemOptions) => Promise<void>;
-    /** Cache key */
-    key: string;
-    /** Execute the underlying function/loader on miss or revalidation */
-    execute: () => Promise<T>;
-    /**
-     * Optional wrapper applied to execute() ONLY on the background
-     * stale-revalidation path (not the foreground miss, where the caller's context
-     * is already established). Used to re-establish the request-context ALS, which
-     * a detached waitUntil task loses on workerd. Defaults to calling execute()
-     * directly.
-     */
-    wrapBackground?: (run: () => Promise<T>) => Promise<T>;
-    /** Serialize result for storage. Return null to skip caching. */
-    serialize: (data: T) => Promise<string | null>;
-    /** Deserialize cached value back to the original type */
-    deserialize: (value: string) => Promise<T>;
-    /** Options passed to setItem on cache write */
-    storeOptions: CacheItemOptions;
-    /** Called on fresh cache hit (before returning data) */
-    onHit?: (cached: CacheItemResult) => void;
-    /** Called on stale cache hit (before scheduling background revalidation) */
-    onStale?: (cached: CacheItemResult) => void;
-    /** Called on cache miss (before executing) */
-    onMiss?: () => void;
-    /** Called after successful cache write */
-    onCached?: () => void;
-    /** Host with optional waitUntil for background tasks */
-    host?: WaitUntilHost | null;
-}
-/**
- * Read-through cache with SWR support for item-level caching.
- *
- * On fresh hit: returns deserialized cached data.
- * On stale hit: returns stale data, schedules background revalidation.
- * On miss: executes, writes to cache (blocking when no waitUntil), returns.
- */
-export declare function readThroughItem<T>(config: ReadThroughItemConfig<T>): Promise<T>;
-export {};

package/dist/types.backup/cache/segment-codec.d.ts

@@ -1,78 +0,0 @@
-/**
- * Segment Codec
- *
- * RSC serialization/deserialization for cached segments.
- * Handles the Flight protocol stream <-> string conversion
- * and the segment-level encode/decode lifecycle.
- */
-import type { ResolvedSegment } from "../types.js";
-import type { SerializedSegmentData } from "./types.js";
-/**
- * Convert a ReadableStream to a string.
- */
-export declare function streamToString(stream: ReadableStream<Uint8Array>): Promise<string>;
-/**
- * Convert a string to a ReadableStream.
- */
-export declare function stringToStream(str: string): ReadableStream<Uint8Array>;
-/**
- * RSC-serialize a value using React Server Components stream.
- * Used for serializing loaderData, layout, loading components etc.
- *
- * Returns undefined for null/undefined inputs (component fields that are absent).
- * For contexts where null is a valid result (loader caching, "use cache"),
- * use serializeResult() instead which preserves null through RSC Flight.
- */
-export declare function rscSerialize(value: unknown): Promise<string | undefined>;
-/**
- * RSC-deserialize a value from a stored string.
- */
-export declare function rscDeserialize<T>(encoded: string | undefined): Promise<T | undefined>;
-/**
- * RSC-serialize any value including null.
- * Unlike rscSerialize(), this does NOT skip null — it serializes it through
- * RSC Flight so that a loader returning null produces a valid cached entry
- * rather than a permanent cache miss.
- *
- * Returns null only on serialization failure.
- */
-export declare function serializeResult(value: unknown): Promise<string | null>;
-/**
- * RSC-deserialize a cached result string.
- * Counterpart to serializeResult() — always receives a non-empty string.
- */
-export declare function deserializeResult<T>(encoded: string): Promise<T>;
-/**
- * RSC-deserialize a single encoded component string back to a React element.
- * Used by the static handler runtime to revive pre-rendered components.
- * Identical to deserializeResult<unknown>.
- */
-export declare const deserializeComponent: (encoded: string) => Promise<unknown>;
-/**
- * Serialize segments for storage.
- * Each segment's component, layout, loading, and loaderData are RSC-serialized.
- * Metadata is preserved as-is.
- */
-export declare function serializeSegments(segments: ResolvedSegment[]): Promise<SerializedSegmentData[]>;
-/**
- * Build ResolvedSegments that carry the STORED fragment strings verbatim
- * instead of decoding them (PPR fast-path payload splice, issue #700; see
- * segment-fragments.ts). The ReactNode fields (component/layout/loading)
- * become {@link segmentFragment} envelopes the outer Flight render serializes
- * as a string copy; the CONSUMER (SSR resume + browser hydration) expands them
- * through its own deserializer. Loader data fields are NOT enveloped — they
- * are consumer data of any shape (a marker there could collide) and decode
- * server-side exactly as deserializeSegments does; on the doc/prerender
- * records this path serves they are absent in practice (loaders are never
- * cached with the route record).
- *
- * The loading "null" sentinel decodes here (not on the consumer): loading:null
- * must survive as null, and shipping the raw sentinel would change the
- * deduplicateLoaderSegments loading-presence check.
- */
-export declare function fragmentSegments(data: SerializedSegmentData[]): Promise<ResolvedSegment[]>;
-/**
- * Deserialize segments from storage.
- * Reconstructs ResolvedSegment objects from RSC-serialized data.
- */
-export declare function deserializeSegments(data: SerializedSegmentData[]): Promise<ResolvedSegment[]>;

package/dist/types.backup/cache/shell-snapshot.d.ts

@@ -1,162 +0,0 @@
-/**
- * Capture data snapshot: recording + seeding stores for PPR shell parity.
- *
- * The scar tissue this fixes: a PPR HIT serves frozen prelude bytes, then a
- * FULL FRESH Flight render for hydration. Any shell-baked (non-hole) content
- * that drifts between capture time and hit time — a cache() segment with a
- * shorter ttl than the shell, a tag-invalidated item — makes the fresh payload
- * disagree with the prelude, so React throws a hydration text mismatch and
- * regenerates the tree client-side (wiping the FOUC theme class, flashing
- * content). See docs/design/ppr-shell-resume.md.
- *
- * The fix (Next.js resume-data-cache analog, adapted to Rango's cache rings):
- * the CAPTURE render records every cache-store read-hit and write it performed
- * (the {@link RecordingShellStore}); the record rides inside the ShellCacheEntry
- * as its `snapshot`; on a HIT the tail render reads through a
- * {@link SeededShellStore} overlay that serves those recorded values AS FRESH,
- * so the shell region reproduces byte-identically while everything NOT recorded
- * (the holes — masked loaders were never executed at capture, so their reads
- * were never recorded) stays live.
- *
- * The invariant, verbatim: the snapshot is exactly the set of cache-store reads
- * the capture render performed; replaying them on a HIT reproduces the shell
- * content byte-identically; everything not recorded stays live.
- */
-import type { SegmentCacheStore, CacheGetResult, CacheItemResult, CacheItemOptions, CachedEntryData, ShellCacheEntry, ShellSnapshotRecord } from "./types.js";
-/**
- * A store wrapper the CAPTURE render reads through. Every call passes through to
- * the underlying store unchanged; for the item/segment/response families it also
- * RECORDS, last-write-wins per (family, key):
- *   - read-hits (get/getItem/getResponse returning non-null) — the value that
- *     fed the shell,
- *   - writes (set/setItem/putResponse) — the value a MISS computed and baked.
- * The shell family (getShell/putShell) is never recorded (the snapshot rides
- * inside a shell entry). Reads that MISS are not recorded (a miss produced no
- * shell content; if the render then computed and wrote, that write is recorded).
- *
- * Deferred writes: cache writes run under waitUntil (fire-and-forget on Node,
- * executionContext on workerd), so their setItem/set calls — hence their records
- * — may land after the shell has quiesced. The capture collects those write
- * promises via {@link trackWrite} and awaits them ({@link settleWrites}) before
- * draining, so a MISS-at-capture value is still pinned.
- */
-export declare class RecordingShellStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
-    private readonly inner;
-    private readonly records;
-    private readonly writes;
-    constructor(inner: SegmentCacheStore<TEnv>);
-    get defaults(): SegmentCacheStore<TEnv>["defaults"];
-    get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"];
-    private record;
-    /** Track a deferred cache-write promise so the capture can await it pre-drain. */
-    trackWrite(p: Promise<unknown>): void;
-    /**
-     * Record a segment-family write into the snapshot WITHOUT touching the inner
-     * store. The shell fast path's implicit doc-cache scope writes through this
-     * (via {@link SnapshotOnlySegmentStore}): the recorded doc entry must ride
-     * ONLY inside the shell entry — a passthrough write would leave a doc-keyed
-     * entry in the real store that the NEXT capture's lookup would hit, replaying
-     * the previous generation's segments instead of re-running handlers (breaking
-     * SWR recapture freshness).
-     */
-    recordSegmentWrite(key: string, data: CachedEntryData): void;
-    /**
-     * Await the tracked deferred writes so their records are present before drain.
-     * Drains ITERATIVELY: a write task can schedule a NESTED write (the ring-3
-     * cacheRoute path schedules its actual store.set in a second waitUntil while the
-     * first is running), so each awaited batch may enqueue more. Loop until the
-     * queue empties or the deadline passes. Bounded: a pathologically slow write
-     * must never stall the capture task, so a key that does not settle in time is
-     * left unpinned (it drifts, the pre-snapshot behavior) rather than hanging.
-     */
-    settleWrites(timeoutMs: number): Promise<void>;
-    /** The recorded snapshot (last-write-wins per family+key), or undefined if empty. */
-    drainSnapshot(): ShellSnapshotRecord[] | undefined;
-    get(key: string): Promise<CacheGetResult | null>;
-    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
-    delete(key: string): Promise<boolean>;
-    clear(): Promise<void>;
-    getResponse(key: string): Promise<{
-        response: Response;
-        shouldRevalidate: boolean;
-    } | null>;
-    putResponse(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
-    getItem(key: string): Promise<CacheItemResult | null>;
-    setItem(key: string, value: string, options?: CacheItemOptions): Promise<void>;
-    getShell(key: string): Promise<{
-        entry: ShellCacheEntry;
-        shouldRevalidate?: boolean;
-    } | null>;
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<void>;
-    invalidateTags(tags: string[]): Promise<void>;
-}
-/** True iff `store` is a RecordingShellStore (duck-typed across module copies). */
-export declare function getRecordingStore<TEnv>(store: SegmentCacheStore<TEnv> | undefined): RecordingShellStore<TEnv> | undefined;
-/**
- * The store the shell fast path's IMPLICIT doc-cache scope resolves during a
- * capture: reads pass through the recording store (a real-store hit is
- * recorded, exactly like any capture read), but segment WRITES are recorded
- * into the snapshot only — see {@link RecordingShellStore.recordSegmentWrite}
- * for why passthrough would break SWR recapture. Routes with their OWN
- * cache() config never see this store (their scope resolves the app-level
- * recording store and keeps today's record-and-write behavior).
- */
-export declare class SnapshotOnlySegmentStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
-    private readonly recording;
-    constructor(recording: RecordingShellStore<TEnv>);
-    get defaults(): SegmentCacheStore<TEnv>["defaults"];
-    get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"];
-    get(key: string): Promise<CacheGetResult | null>;
-    set(key: string, data: CachedEntryData): Promise<void>;
-    delete(key: string): Promise<boolean>;
-}
-/**
- * Materialize the loader-family seed from a shell snapshot for a HIT's tail
- * render: Flight-deserialize each recorded (promise-elided) bake-lane
- * container into a segment-key -> container Map, which serveShellHit assigns
- * to the tail context's `_shellLoaderSeed` for the resolveLoaderData overlay.
- * Lives here so every snapshot family is decoded in this module (the
- * item/segment/response families via {@link SeededShellStore}); the loader
- * family is not a store read, so it seeds the context instead of a store.
- *
- * Deserializations run in parallel; a record that fails to decode is skipped
- * (that loader drifts — the pre-snapshot behavior — instead of failing the
- * HIT). Returns undefined when the snapshot carries no loader records, without
- * touching the Flight codec (kept lazy for cold paths and non-RSC configs).
- */
-export declare function buildShellLoaderSeed(snapshot: ShellSnapshotRecord[]): Promise<Map<string, unknown> | undefined>;
-/**
- * A read-through overlay the HIT tail render reads through. For a key present in
- * the snapshot it serves the recorded value AS FRESH (shouldRevalidate: false —
- * a pinned key must NOT kick SWR background revalidation) so the tail's payload
- * matches the frozen prelude. Every other read falls through to the real store
- * (the holes — masked loaders were never recorded — stay live). ALL writes pass
- * through unchanged: a live hole's loader may legitimately write. The shell
- * family always passes through.
- */
-export declare class SeededShellStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
-    private readonly inner;
-    private readonly items;
-    private readonly segments;
-    private readonly responses;
-    constructor(inner: SegmentCacheStore<TEnv>, snapshot: ShellSnapshotRecord[]);
-    get defaults(): SegmentCacheStore<TEnv>["defaults"];
-    get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"];
-    get(key: string): Promise<CacheGetResult | null>;
-    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
-    delete(key: string): Promise<boolean>;
-    clear(): Promise<void>;
-    getResponse(key: string): Promise<{
-        response: Response;
-        shouldRevalidate: boolean;
-    } | null>;
-    putResponse(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
-    getItem(key: string): Promise<CacheItemResult | null>;
-    setItem(key: string, value: string, options?: CacheItemOptions): Promise<void>;
-    getShell(key: string): Promise<{
-        entry: ShellCacheEntry;
-        shouldRevalidate?: boolean;
-    } | null>;
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<void>;
-    invalidateTags(tags: string[]): Promise<void>;
-}

package/dist/types.backup/cache/tag-invalidation.d.ts

@@ -1,74 +0,0 @@
-/**
- * Cache Tag Invalidation API
- *
- * Two on-demand invalidation verbs, mirroring the distinction popularized by
- * Next.js so consumers can pick the right consistency model:
- *
- * - updateTag(...tags): read-your-own-writes. Awaitable - resolves only after
- *   in-process invalidation across every configured store completes. Use in a
- *   Server Action and `await` it before the action re-renders, so the action's
- *   own response reflects the mutation.
- *
- * - revalidateTag(...tags): fire-and-forget via waitUntil - the response is not
- *   blocked. Use in Route Handlers / webhooks. NOTE: both verbs hard-purge; the
- *   only difference is awaitability. revalidateTag does NOT serve stale content -
- *   the next read after the invalidation lands is a hard miss that re-renders.
- *   (The name mirrors Next.js, where it is SWR; here it is background-purge.)
- *
- * Both fan out across the app-level store (ctx._cacheStore) and every explicit
- * per-scope store from cache({ store }) registered for this handler
- * (ctx._explicitTaggedStores), calling the store-level invalidateTags()
- * primitive for each tag. A single configured store (the common case) owns its
- * own tag index and distributed invalidation - there is no separate
- * tag-invalidation store.
- */
-/**
- * Immediately expire every cache entry tagged with any of `tags`, resolving
- * once in-process invalidation across all configured stores completes.
- *
- * Read-your-own-writes: because the returned promise resolves before you return
- * from a Server Action, awaiting it guarantees the action's own re-render (and
- * any subsequent read) sees fresh data.
- *
- * @example
- * ```typescript
- * async function updateProduct(formData: FormData) {
- *   "use server";
- *   await db.updateProduct(formData);
- *   await updateTag("products");   // next render is fresh
- * }
- * ```
- */
-export declare function updateTag(...tags: string[]): Promise<void>;
-/**
- * Invalidate every cache entry tagged with any of `tags` in the background,
- * without blocking the current response (fire-and-forget via waitUntil).
- *
- * This is NOT stale-while-revalidate: like updateTag() it hard-purges, so the
- * next read after the invalidation lands is a miss that re-renders fresh. The
- * only difference from updateTag() is awaitability - revalidateTag() defers the
- * purge off the response path and is not awaited.
- *
- * Use in Route Handlers / webhooks. For read-your-own-writes inside a Server
- * Action, use updateTag() instead so the action's own response is fresh.
- *
- * Fire-and-forget: because this returns void and runs in the background, a
- * failed durable marker write (e.g. a transient KV outage) is NOT surfaced to
- * the caller. It IS reported - logged loudly and routed through the router's
- * `onError` callback (phase `cache`, `metadata.category === "cache-invalidate"`)
- * via reportingAsync - so the failure is observable in telemetry even though it
- * cannot be awaited. If you need the invalidation to be CONFIRMED (and to retry
- * on failure), use `await updateTag()` instead, which rejects when a store's
- * durable write fails.
- *
- * @example
- * ```typescript
- * // route handler invoked by an external webhook
- * export async function POST() {
- *   "use server";
- *   revalidateTag("products");
- *   return new Response("ok");
- * }
- * ```
- */
-export declare function revalidateTag(...tags: string[]): void;

package/dist/types.backup/cache/taint.d.ts

@@ -1,71 +0,0 @@
-/**
- * Taint symbol for request-scoped objects.
- *
- * Objects branded with NOCACHE_SYMBOL (ctx, env, req) are excluded from
- * "use cache" cache keys and trigger handle capture mode so that side
- * effects (breadcrumbs, metadata) are recorded and replayed on cache hit.
- */
-export declare const NOCACHE_SYMBOL: unique symbol;
-/**
- * Check if a value is tainted (request-scoped, should not be in cache key).
- */
-export declare function isTainted(value: unknown): boolean;
-/**
- * Symbol stamped on tainted ctx during "use cache" function execution.
- * cookies(), headers(), ctx.set(), ctx.header(), etc. check this flag and
- * throw if present — reads would cache per-request data under a shared key,
- * and side effects would be lost on cache hit.
- *
- * The value is a numeric reference count, not a boolean. Multiple concurrent
- * cached functions sharing the same ctx/requestCtx each increment on entry
- * and decrement on exit. Guards fire when count > 0.
- */
-export declare const INSIDE_CACHE_EXEC: unique symbol;
-/**
- * Increment the INSIDE_CACHE_EXEC ref count on an object.
- */
-export declare function stampCacheExec(obj: object): void;
-/**
- * Decrement the INSIDE_CACHE_EXEC ref count on an object.
- * Deletes the symbol when the count reaches zero so the `in` check
- * used by guards no longer fires.
- */
-export declare function unstampCacheExec(obj: object): void;
-/**
- * Throw if ctx is inside a "use cache" execution.
- * Call from side-effecting ctx methods (set, header, etc.) and cookie mutations.
- */
-export declare function assertNotInsideCacheExec(ctx: unknown, methodName: string): void;
-/**
- * Symbol stamped on ctx when resolving handlers inside a cache() DSL boundary.
- * Separate from INSIDE_CACHE_EXEC ("use cache") because cache() allows
- * ctx.set() (children are also cached) but blocks response-level side effects
- * (headers, cookies, status) which are lost on cache hit.
- */
-export declare const INSIDE_CACHE_SCOPE: unique symbol;
-/**
- * Mark ctx as inside a cache() scope. Must be paired with unstampCacheScope.
- */
-export declare function stampCacheScope(obj: object): void;
-/**
- * Remove cache() scope mark.
- */
-export declare function unstampCacheScope(obj: object): void;
-/**
- * Throw if ctx is inside a cache() DSL boundary.
- * Call from response-level side effects (header, setCookie, setStatus, etc.)
- * which are lost on cache hit because the handler body is skipped.
- * ctx.set() is allowed inside cache() — children are also cached and can
- * read the value.
- */
-export declare function assertNotInsideCacheScope(ctx: unknown, methodName: string): void;
-/**
- * Brand symbol for functions wrapped by registerCachedFunction().
- * Used at runtime to detect when a "use cache" function is misused
- * (e.g., passed as middleware).
- */
-export declare const CACHED_FN_SYMBOL: unique symbol;
-/**
- * Check if a value is a "use cache" wrapped function.
- */
-export declare function isCachedFunction(value: unknown): boolean;