@rangojs/router 0.1.1 → 0.4.0

package/dist/types.backup/cache/cf/cf-cache-types.d.ts

@@ -0,0 +1,300 @@
+import type { ExecutionContext } from "../../types/request-scope.js";
+import type { CacheDefaults } from "../types.js";
+import type { RequestContext } from "../../server/request-context.js";
+/**
+ * Minimal Cloudflare KV Namespace interface.
+ * Avoids hard dependency on @cloudflare/workers-types.
+ */
+export interface KVNamespace {
+    get(key: string, options?: {
+        type?: string;
+    }): Promise<any>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * One L1 read decision, surfaced when `debug` is enabled. Lets an operator
+ * confirm on a real deployment (e.g. via `wrangler tail`) that the store's
+ * observed inputs match its decision: which tier answered, the entry's status,
+ * the stale/revalidating timestamps, the raw CF `Age` header (so its
+ * unreliability can be seen next to the explicit revalidating-at stamp), and
+ * the measured match/body-read durations (where the latency tail shows up).
+ */
+export interface CFCacheReadDebugEvent {
+    /**
+     * Which read method produced this event. Only the JSON read paths (segment
+     * `get` and function `getItem`) participate in debug; the document
+     * `getResponse` path streams its body and is intentionally out of scope.
+     */
+    op: "get" | "getItem";
+    /** Cache key (without the internal fn:/doc: prefix or version path). */
+    key: string;
+    /**
+     * What the read resolved to:
+     * - l1-fresh / l1-stale-revalidate / l1-revalidating-guarded: L1 hit outcomes
+     * - match-timeout / body-timeout: the L1 latency budgets fired
+     * - match-error: the L1 match() itself rejected (a transient Cache API infra
+     *   error) -- a miss that falls through to L2/KV and is reported cache-read,
+     *   distinct from a genuine l1-miss (absence) so the two are separable
+     * - body-error: the L1 body read failed fast (corrupt/non-JSON body) -- a miss
+     *   that falls through to L2/KV, distinct from a body-timeout
+     * - non-200: L1 returned a non-200 (treated as a miss)
+     * - l1-miss: no L1 entry
+     * - kv-fresh / kv-stale / kv-miss: L2 fallback outcomes
+     * - kv-stale-suppressed: a stale L2 hit served WITHOUT revalidation because
+     *   the L1 fall-through was degraded (body-timeout / non-200) -- the herd
+     *   mitigation, distinct from kv-stale so the suppression is visible
+     * - kv-timeout: the L2/KV read budget fired (read abandoned, NOT a genuine
+     *   absence -- distinct from kv-miss so a degradation signal is separable)
+     * - tag-invalidated: a live L1/KV entry whose cache tags were invalidated
+     *   after it was written -- treated as a miss so the next render re-populates
+     *   it (the tag-invalidation read path, distinct from a plain miss)
+     * - error: the read threw
+     */
+    outcome: "l1-fresh" | "l1-stale-revalidate" | "l1-revalidating-guarded" | "match-timeout" | "match-error" | "body-timeout" | "body-error" | "non-200" | "tag-invalidated" | "l1-miss" | "kv-fresh" | "kv-stale" | "kv-stale-suppressed" | "kv-miss" | "kv-timeout" | "error";
+    /** HTTP status of the matched L1 response, when one was returned. */
+    status?: number;
+    /**
+     * Stored cache status header (CACHE_STATUS_HEADER): "HIT" or "REVALIDATING".
+     * Distinct from `isRevalidating`, which also factors in stamp recency -- this
+     * is the raw stored value, so a REVALIDATING entry whose stamp aged out (so
+     * `isRevalidating` is false) is still distinguishable from a plain HIT.
+     */
+    cacheStatus?: string | null;
+    /** Epoch-ms when the entry goes stale (from CACHE_STALE_AT_HEADER). */
+    staleAt?: number;
+    /** Epoch-ms the entry was marked REVALIDATING (from the explicit stamp). */
+    revalidatingAt?: number;
+    /** Raw CF `Age` header, for comparison against revalidatingAt (may be null). */
+    ageHeader?: string | null;
+    isStale?: boolean;
+    isRevalidating?: boolean;
+    shouldRevalidate?: boolean;
+    /** Wall-clock ms spent in cache.match (bounded by edgeLookupTimeoutMs). */
+    matchMs?: number;
+    /**
+     * Wall-clock ms spent resolving the entry's tag-invalidation markers (the
+     * per-request memo -> optional per-colo L1 marker cache -> KV cascade), for a
+     * tagged entry. 0/absent for an untagged entry or a memo hit; a non-trivial
+     * value is the serial marker-read tail that sits between matchMs and
+     * bodyReadMs. Only measured when debug is enabled.
+     */
+    markerMs?: number;
+    /** Wall-clock ms spent reading the body (bounded by edgeReadTimeoutMs). */
+    bodyReadMs?: number;
+}
+/**
+ * Debug sink. `true` logs each {@link CFCacheReadDebugEvent} to console; a
+ * function receives the events for programmatic capture.
+ */
+export type CFCacheDebug = boolean | ((event: CFCacheReadDebugEvent) => void);
+export interface CFCacheStoreOptions<TEnv = unknown> {
+    /**
+     * Cache namespace. If not provided, uses caches.default (recommended).
+     * Only set this if you need isolated cache storage.
+     */
+    namespace?: string;
+    /**
+     * Base URL for cache keys.
+     *
+     * If not provided, derives from request hostname via requestContext:
+     * - Production domains → uses `https://{hostname}/`
+     * - Dev/preview (localhost, workers.dev, pages.dev) → uses internal fallback URL
+     */
+    baseUrl?: string;
+    /** Default cache options */
+    defaults?: CacheDefaults;
+    /**
+     * Cloudflare ExecutionContext for non-blocking cache writes.
+     * Pass the `ctx` from your worker's fetch handler.
+     *
+     * @example
+     * ```typescript
+     * new CFCacheStore({ ctx: env.ctx })
+     * ```
+     */
+    ctx: ExecutionContext;
+    /**
+     * Optional KV namespace for L2 cache persistence.
+     *
+     * When provided, KV acts as a global fallback behind the per-colo Cache API.
+     * On L1 miss, KV is checked and hits are promoted back to L1.
+     * On writes, data is persisted to both L1 and KV.
+     *
+     * @example
+     * ```typescript
+     * new CFCacheStore({ ctx: env.ctx, kv: env.CACHE_KV })
+     * ```
+     *
+     * Tag-based invalidation (updateTag/revalidateTag) requires KV: the
+     * tag-invalidation markers are stored in this same namespace. There is no
+     * separate tag-invalidation store to configure.
+     */
+    kv?: KVNamespace;
+    /**
+     * Optional eager-purge hook, called ONCE per updateTag()/revalidateTag() with
+     * the namespaced Cloudflare Cache-Tags to purge (one batched call for the
+     * whole invalidation, not one per tag). These exactly match the `Cache-Tag`
+     * header this store writes on its tag-lookup marker entries
+     * (`rg:{namespace}:lk:{encodedTag}`), so forwarding them to Cloudflare's
+     * purge-by-tag API evicts the cached lookups in every colo - making
+     * cross-colo invalidation prompt instead of waiting out `tagCacheTtl`.
+     *
+     * Only meaningful with `tagCacheTtl > 0` (otherwise there are no cached
+     * lookups to purge). The values are pre-encoded, so commas in tag names are
+     * safe to pass straight to the purge API.
+     *
+     * @example
+     * ```ts
+     * onRevalidateTag: async (cacheTags) => {
+     *   await fetch(`https://api.cloudflare.com/client/v4/zones/${ZONE}/purge_cache`, {
+     *     method: "POST",
+     *     headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" },
+     *     body: JSON.stringify({ tags: cacheTags }),
+     *   });
+     * }
+     * ```
+     */
+    onRevalidateTag?: (cacheTags: string[]) => Promise<void>;
+    /**
+     * Optional expiration (seconds) for tag-invalidation markers in KV. A marker
+     * must outlive every entry tagged before the invalidation, so this MUST
+     * exceed your largest entry TTL+SWR. Defaults to no expiration (markers
+     * persist; they are tiny - one timestamp per distinct invalidated tag).
+     *
+     * Note the opposite sizing from `tagCacheTtl` below: `tagInvalidationTtl` must
+     * be LARGE (outlive data); `tagCacheTtl` should be SMALL (a staleness ceiling).
+     *
+     * Cardinality matters: each DISTINCT invalidated tag writes one permanent KV
+     * marker (with the no-expiry default). Keep tags LOW-cardinality and never
+     * derive an invalidation tag from untrusted input (e.g.
+     * `revalidateTag(req.query.tag)`) - an attacker could otherwise grow your KV
+     * namespace without bound. Set a `tagInvalidationTtl` only if your tags are
+     * unavoidably high-cardinality AND it can still safely exceed your max entry
+     * TTL+SWR.
+     */
+    tagInvalidationTtl?: number;
+    /**
+     * Optional TTL (seconds) for caching tag-invalidation markers in the per-colo
+     * Cache API (L1), to avoid a KV marker read on every tagged cache read.
+     *
+     * Default `0` = disabled: the marker is read from KV on every tagged read
+     * (today's behavior), giving the strongest cross-colo invalidation latency
+     * (~KV consistency). A positive value caches each marker (including the
+     * "no marker yet" state) in L1 for that many seconds, so within the window a
+     * colo answers from L1 with no KV read.
+     *
+     * The colo that runs `updateTag`/`revalidateTag` writes the fresh marker
+     * straight into its own L1 (write-through), so the invalidating request and
+     * later reads in that colo observe the invalidation immediately. One caveat: a
+     * read already in flight when the invalidation lands (one that began its KV
+     * marker fetch first) can re-cache the PRIOR marker into L1 after the
+     * write-through, so a racing concurrent reader in the same colo may miss the
+     * invalidation for up to `tagCacheTtl` -- the Cache API exposes no
+     * compare-and-set to close this fully. `tagCacheTtl` is therefore a staleness
+     * CEILING, not a promise of zero same-colo latency; keep it small (or wire
+     * `onRevalidateTag`) when that matters. By default OTHER colos only converge
+     * when their cached marker expires, so `tagCacheTtl` is the MAXIMUM extra
+     * cross-colo invalidation latency for them. Recommended 30-60 for high-read,
+     * low-mutation tags; leave at 0 when prompt global invalidation matters and
+     * you cannot wire a purge.
+     *
+     * To make other colos prompt WITHOUT a short TTL, wire `onRevalidateTag` to a
+     * Cloudflare purge-by-tag call: each marker entry carries a namespaced
+     * `Cache-Tag`, and `onRevalidateTag` is handed exactly those tags to purge, so
+     * the cached lookups are evicted everywhere on invalidation. With a purge
+     * wired, `tagCacheTtl` becomes purely a read-cost reducer + fallback window
+     * (safe to set large) rather than the invalidation-latency ceiling.
+     */
+    tagCacheTtl?: number;
+    /**
+     * Cache version string override. When this changes, all cached entries are
+     * effectively invalidated (new keys won't match old entries).
+     *
+     * Defaults to the auto-generated VERSION from the `@rangojs/router:version` virtual module.
+     * Only set this if you need a custom versioning strategy.
+     */
+    version?: string;
+    /**
+     * Latency budget (ms) for an L1 edge cache (CF Cache API) read. A `match`
+     * slower than this is abandoned and treated as a miss, so a degraded colo
+     * cannot stall the request; the read then falls through to its normal miss
+     * path (L2/KV or render).
+     *
+     * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (10). Set to 0 (or any value
+     * <= 0) to disable the budget and always await `match`.
+     */
+    edgeLookupTimeoutMs?: number;
+    /**
+     * Latency budget (ms) for reading the BODY of a matched L1 entry
+     * (response.json()). CF streams the cache body lazily, so the multi-second
+     * tail can appear after `match` already resolved; this bounds it. On timeout
+     * the read is treated as a miss and falls through to L2/KV or render.
+     *
+     * Separate from {@link edgeLookupTimeoutMs} because a healthy body read
+     * (fetch + JSON parse of a potentially large Flight payload) takes a little
+     * longer than a `match`. Defaults to {@link EDGE_READ_TIMEOUT_MS} (20), which
+     * clears a healthy per-colo read yet fails fast on a degraded one. Set to 0
+     * (or any value <= 0) to disable and always await the body.
+     */
+    edgeReadTimeoutMs?: number;
+    /**
+     * Latency budget (ms) for an L2 (KV) read. KV is the last cache tier before a
+     * full render and is a global store (~50ms healthy, seconds when degraded);
+     * this bounds it so a slow namespace cannot pin the request. On timeout the
+     * read is treated as a miss (no L1 promote) and falls through to render.
+     *
+     * Defaults to {@link KV_READ_TIMEOUT_MS} (170) -- a few multiples above the
+     * ~50ms healthy read, with headroom for legitimate tails (large payloads / far
+     * regions) yet still well under a degraded namespace's multi-second tail.
+     * Lower it for a tighter SLA, raise it if your healthy KV p99 runs higher; it
+     * is a degradation guard-rail, not a tuning lever. Set to 0 (or any value
+     * <= 0) to disable and always await KV.
+     */
+    kvReadTimeoutMs?: number;
+    /**
+     * Emit a {@link CFCacheReadDebugEvent} per L1 read. `true` logs to console
+     * (visible via `wrangler tail`); pass a function to capture events directly.
+     * Off by default. Intended for validating cache behavior on a real
+     * deployment before relying on it; not for steady-state production.
+     */
+    debug?: CFCacheDebug;
+    /**
+     * Custom key generator applied to all cache operations.
+     * Receives the full RequestContext (including env) and the default-generated key.
+     * Return value becomes the final cache key (unless route overrides with `key` option).
+     *
+     * Reserved prefixes: tag-invalidation markers live in the SAME KV namespace as
+     * data, keyed `__tag__/<tag>` (and `__tagmarker__/<tag>` for the L1 cache). A
+     * returned key must NOT begin with `__tag__/` or `__tagmarker__/`, or it can
+     * collide with a tag marker and corrupt invalidation. The documented
+     * prepend-style generators below are safe.
+     *
+     * @example Using headers for user segmentation
+     * ```typescript
+     * keyGenerator: (ctx, defaultKey) => {
+     *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
+     *   return `${segment}:${defaultKey}`;
+     * }
+     * ```
+     *
+     * @example Using env bindings for multi-region
+     * ```typescript
+     * keyGenerator: (ctx, defaultKey) => {
+     *   const region = ctx.env.REGION || 'us';
+     *   return `${region}:${defaultKey}`;
+     * }
+     * ```
+     *
+     * @example Using cookies for locale-aware caching
+     * ```typescript
+     * keyGenerator: (ctx, defaultKey) => {
+     *   const locale = cookies().get('locale')?.value || 'en';
+     *   return `${locale}:${defaultKey}`;
+     * }
+     * ```
+     */
+    keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+}

package/dist/types.backup/cache/cf/cf-kv-utils.d.ts

@@ -0,0 +1,22 @@
+/** KV key byte-length ceiling. Cloudflare KV rejects keys larger than this. */
+export declare const KV_MAX_KEY_BYTES = 512;
+/**
+ * Cloudflare KV's minimum `expirationTtl` (seconds). A `put` with a smaller
+ * expirationTtl is rejected outright. Tag-invalidation markers (the only writes
+ * that take a consumer-supplied TTL via tagInvalidationTtl) are floored to this
+ * so a too-small value cannot make EVERY updateTag/revalidateTag throw.
+ */
+export declare const KV_MIN_EXPIRATION_TTL = 60;
+/** UTF-8 byte length of a KV key (multibyte tags can exceed the char count). */
+export declare function kvKeyByteLength(key: string): number;
+/**
+ * Compute the Cache-Control directive for a stale-path REVALIDATING re-put from
+ * the entry's stored hard-expiry deadline (CACHE_EXPIRES_AT_HEADER). Returns the
+ * REMAINING ttl so the re-put preserves the original retention deadline instead
+ * of restarting it -- copying set()'s original full-window max-age would reset
+ * CF's retention clock on every re-arm and pin a perpetually-stale entry forever.
+ * An entry lacking a valid deadline (legacy/tampered) floors to max-age=1, so it
+ * hard-expires in ~1s and self-heals via KV. Mirrors promoteSegmentToL1's math.
+ * @internal
+ */
+export declare function remainingCacheControl(headers: Headers, now: number): string;

package/dist/types.backup/cache/cf/cf-tag-marker-memo.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Cache-API path prefix for the optional per-colo L1 cache of tag-invalidation
+ * markers (enabled by tagCacheTtl). Distinct from data keys (doc:/fn:/segment)
+ * and from the KV marker prefix so the two never collide.
+ */
+export declare const TAG_MARKER_CACHE_PREFIX = "__tagmarker__/";
+/**
+ * Sentinel body for an L1-cached marker meaning "this tag has no invalidation
+ * marker." Distinct from any real ms-epoch timestamp (always a large positive
+ * integer). A Cache API miss (match() === undefined) always means "re-read KV",
+ * never "no marker" - absence is only ever represented by this cached sentinel.
+ */
+export declare const TAG_MARKER_ABSENT = "none";
+export declare function getTagMarkerMemo(ctx: object, store: object): Map<string, number | null>;
+export declare function getTagMarkerInflight(ctx: object, store: object): Map<string, Promise<number | null>>;

package/dist/types.backup/cache/cf/index.d.ts

@@ -0,0 +1,3 @@
+export { CFCacheStore, type CFCacheStoreOptions, type CFCacheDebug, type CFCacheReadDebugEvent, type KVNamespace, } from "./cf-cache-store.js";
+export { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_REVALIDATING_AT_HEADER, } from "./cf-cache-store.js";
+export { EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, } from "./cf-cache-store.js";

package/dist/types.backup/cache/document-cache.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Document-Level Cache Middleware
+ *
+ * Caches full HTTP responses at the edge based on Cache-Control headers.
+ * Routes opt-in to caching by setting s-maxage or stale-while-revalidate headers.
+ *
+ * Flow:
+ * 1. Check cache for existing response
+ * 2. If fresh hit → return cached response
+ * 3. If stale hit (within SWR window) → return cached, revalidate in background
+ * 4. If miss → run handler, cache if response has cache headers
+ */
+import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
+export interface DocumentCacheOptions<TEnv = any> {
+    /**
+     * Skip caching for specific paths (e.g., API routes)
+     */
+    skipPaths?: string[];
+    /**
+     * Custom cache key generator.
+     *
+     * Replaces the default `host + pathname + search` key entirely. On a
+     * multi-domain deployment served by one function you MUST include `url.host`
+     * (or an equivalent tenant discriminator) yourself — the default key is
+     * host-namespaced, but a custom generator's output is used verbatim, so
+     * omitting host bleeds one hostname's cached response to another.
+     */
+    keyGenerator?: (url: URL) => string;
+    /**
+     * Callback to determine if caching should be enabled for this request.
+     * Receives the middleware context and returns true to enable caching.
+     * If not provided, caching is enabled by default.
+     *
+     * @example
+     * ```typescript
+     * createDocumentCacheMiddleware({
+     *   isEnabled: (ctx) => !ctx.request.headers.has('x-skip-cache'),
+     * })
+     * ```
+     */
+    isEnabled?: (ctx: MiddlewareContext<TEnv>) => boolean | Promise<boolean>;
+    /**
+     * Enable debug logging for cache operations.
+     * Logs HIT, MISS, STALE, and REVALIDATED events.
+     * Defaults to false.
+     */
+    debug?: boolean;
+}
+/**
+ * Create document cache middleware
+ *
+ * Add this middleware to your router to enable document-level caching.
+ * It uses the cache store's getResponse/putResponse methods for caching.
+ * Routes opt-in by setting Cache-Control headers with s-maxage.
+ *
+ * @example
+ * ```typescript
+ * // Add middleware to router
+ * const router = createRouter<AppEnv>()
+ *   .use(createDocumentCacheMiddleware({
+ *     isEnabled: (ctx) => ctx.url.pathname !== '/admin',
+ *   }))
+ *   .route("home", (ctx) => {
+ *     ctx.headers.set("Cache-Control", "s-maxage=60, stale-while-revalidate=300");
+ *     return <HomePage />;
+ *   });
+ * ```
+ */
+export declare function createDocumentCacheMiddleware<TEnv = any>(options?: DocumentCacheOptions<TEnv>): MiddlewareFn<TEnv>;

package/dist/types.backup/cache/handle-capture.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Handle Capture
+ *
+ * Captures handle pushes during cached function execution.
+ * Extracted from cache-runtime.ts so tests can import without
+ * pulling in @vitejs/plugin-rsc/rsc dependencies.
+ */
+import type { HandleStore } from "../server/handle-store.js";
+import type { SegmentHandleData } from "./types.js";
+export interface HandleCapture {
+    data: Record<string, SegmentHandleData>;
+}
+/**
+ * Start capturing handle pushes for a cached function execution.
+ *
+ * Concurrency-safe: multiple overlapping captures on the same
+ * HandleStore are independent. Each capture registers a token in a
+ * Set; stopping removes it. No ordering requirement (LIFO not needed).
+ */
+export declare function startHandleCapture(handleStore: HandleStore): {
+    capture: HandleCapture;
+    stop: () => void;
+};

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

@@ -0,0 +1,39 @@
+/**
+ * Handle Snapshot
+ *
+ * Capture and restore handle data for cached segments.
+ * Handle data (breadcrumbs, metadata from ctx.use(Handle)) is collected
+ * during segment resolution and stored alongside cached segments.
+ */
+import type { ResolvedSegment } from "../types.js";
+import type { HandleStore } from "../server/handle-store.js";
+import type { SegmentHandleData } from "./types.js";
+type HandleRecord = Record<string, SegmentHandleData>;
+export declare function encodeHandles(handles: HandleRecord): Promise<string>;
+export declare function decodeHandles(encoded: string): Promise<HandleRecord | null>;
+export declare function encodeHandleValue(value: unknown): Promise<string>;
+/**
+ * Decode a Flight-encoded handle-data string. Returns null on any decode
+ * failure so the caller can skip handle restore without discarding valid
+ * cached/prerendered segments.
+ */
+export declare function decodeHandleValue<T>(encoded: string): Promise<T | null>;
+/**
+ * Capture handle data for a set of segments from the handle store.
+ * Used when caching segments to preserve their handle data.
+ *
+ * `exclude` (shell captures: RequestContext._shellCaptureLoaderHandleValues)
+ * drops DSL-loader-scoped push values from the CACHE WRITE only: loaders
+ * re-run fresh on every HIT, so replaying their captured values would
+ * duplicate the fresh push — and their masked nested promises would stall the
+ * Flight handle encode to its timeout. Threaded as an explicit argument so
+ * every other getDataForSegment consumer (the render-barrier snapshot,
+ * prerender) provably sees every push.
+ */
+export declare function captureHandles(segments: ResolvedSegment[], handleStore: HandleStore, exclude?: WeakSet<object>): Record<string, SegmentHandleData>;
+/**
+ * Restore handle data from a cached snapshot into the handle store.
+ * Used when serving cached segments to replay their handle data.
+ */
+export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore): void;
+export {};

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

@@ -0,0 +1,7 @@
+export type { SegmentCacheStore, CachedEntryData, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, SerializedSegmentData, SegmentHandleData, } from "./types.js";
+export { MemorySegmentCacheStore } from "./memory-segment-store.js";
+export { CFCacheStore, type CFCacheStoreOptions, type CFCacheDebug, type CFCacheReadDebugEvent, type KVNamespace, CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_REVALIDATING_AT_HEADER, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, } from "./cf/index.js";
+export { VercelCacheStore, type VercelCacheStoreOptions, type VercelRuntimeCache, type VercelCacheDebug, type VercelCacheReadDebugEvent, type VercelCacheReadOutcome, VERCEL_MAX_ITEM_BYTES, VERCEL_MAX_TAGS_PER_ITEM, VERCEL_MAX_TAG_BYTES, } from "./vercel/index.js";
+export { CacheScope, createCacheScope } from "./cache-scope.js";
+export { createDocumentCacheMiddleware, type DocumentCacheOptions, } from "./document-cache.js";
+export type { CacheErrorCategory } from "./cache-error.js";

package/dist/types.backup/cache/memory-segment-store.d.ts

@@ -0,0 +1,163 @@
+/**
+ * In-Memory Segment Cache Store
+ *
+ * Simple in-memory implementation of SegmentCacheStore.
+ * Uses globalThis to survive HMR in development.
+ */
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry } from "./types.js";
+import type { RequestContext } from "../server/request-context.js";
+/**
+ * Options for MemorySegmentCacheStore
+ */
+export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
+    /**
+     * Optional name for this store instance. Named stores persist their
+     * backing Map on globalThis so data survives Vite HMR module reloads.
+     * Stores with different names get separate Maps.
+     *
+     * When omitted, the store uses a plain instance-level Map with no
+     * globalThis sharing, which is the safest default for isolation.
+     *
+     * Caveat: two instances constructed with the SAME name share all backing maps
+     * (data + tag index), but each keeps its OWN `defaults` and `keyGenerator` from
+     * its options - those are not shared. Use one instance per name, or keep the
+     * options identical, to avoid surprising divergence.
+     *
+     * @example
+     * ```typescript
+     * // Two named stores are isolated from each other
+     * const fast = new MemorySegmentCacheStore({ name: "fast", defaults: { ttl: 10 } });
+     * const slow = new MemorySegmentCacheStore({ name: "slow", defaults: { ttl: 300 } });
+     * ```
+     */
+    name?: string;
+    /**
+     * Default cache options for cache() boundaries.
+     * When cache() is called without explicit ttl/swr,
+     * these defaults are used.
+     *
+     * @example
+     * ```typescript
+     * const store = new MemorySegmentCacheStore({
+     *   defaults: { ttl: 60, swr: 300 }
+     * });
+     * ```
+     */
+    defaults?: CacheDefaults;
+    /**
+     * Custom key generator applied to all cache operations.
+     * Receives the full RequestContext and the default-generated key.
+     *
+     * @example
+     * ```typescript
+     * keyGenerator: (ctx, defaultKey) => {
+     *   const locale = cookies().get('locale')?.value || 'en';
+     *   return `${locale}:${defaultKey}`;
+     * }
+     * ```
+     */
+    keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    /**
+     * Maximum number of entries kept per internal family (segment, response,
+     * item, shell). On insert, once a family reaches the cap its oldest entry is
+     * evicted FIFO (insertion order) and its tag-index entries are cleaned up, so
+     * a long-lived instance can't grow without bound. Lazy TTL expiry still runs
+     * independently. Defaults to DEFAULT_MAX_ENTRIES (1000).
+     *
+     * @example
+     * ```typescript
+     * const store = new MemorySegmentCacheStore({ maxEntries: 500 });
+     * ```
+     */
+    maxEntries?: number;
+}
+/**
+ * In-memory segment cache store.
+ *
+ * Suitable for development and single-instance deployments.
+ * For production with multiple instances, use a distributed store
+ * like Cloudflare KV or Redis.
+ *
+ * Each family is size-capped at `maxEntries` (default 1000) with FIFO eviction
+ * on insert, so a long-lived instance can't grow unbounded; TTL expiry stays
+ * lazy on top of that.
+ *
+ * Tag-index cleanup is lazy, mirroring the data maps: a tagged entry that
+ * expires but is never re-read or invalidated leaves its forward+reverse index
+ * entries resident until the key is reused, invalidated, or FIFO-evicted. This
+ * is bounded by the distinct-tag count and acceptable for a dev/single-instance
+ * store. FIFO eviction unregisters the evicted key's tags, so the tag maps do
+ * not outlive the capped data maps.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const store = new MemorySegmentCacheStore();
+ *
+ * // With defaults for cache() boundaries
+ * const store = new MemorySegmentCacheStore({
+ *   defaults: { ttl: 60 }
+ * });
+ *
+ * createRSCHandler({
+ *   router,
+ *   cache: { store }
+ * })
+ * ```
+ */
+export declare class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    private cache;
+    private responseCache;
+    private itemCache;
+    private shellCache;
+    /** tag -> set of prefixed cache keys (seg:key, res:key, item:key, shell:key) */
+    private tagIndex;
+    /** prefixed cache key -> set of tags (reverse index for O(tags) unregister) */
+    private keyTags;
+    /**
+     * tag -> epoch ms of its latest invalidateTags() call. The build-shell
+     * read-through's isTagsInvalidatedSince gate: baked shell entries are
+     * immutable in the build manifest, so eviction is answered by comparing
+     * these markers against the entry's build-time createdAt. Per-isolate,
+     * like every other map here — matching this store's tag semantics.
+     */
+    private tagInvalidatedAt;
+    readonly defaults?: CacheDefaults;
+    readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    /** Per-family FIFO entry cap. */
+    readonly maxEntries: number;
+    constructor(options?: MemorySegmentCacheStoreOptions<TEnv>);
+    /**
+     * FIFO cap enforcement, called before inserting `incomingKey` into `map`.
+     * When the key is new and the family is at capacity, the oldest entries are
+     * evicted in insertion order and their tag-index entries unregistered (so the
+     * tag maps don't outlive the capped data map). Overwriting an existing key
+     * grows nothing, so it is a no-op.
+     */
+    private evictIfNeeded;
+    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>;
+    isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    invalidateTags(tags: string[]): Promise<void>;
+    private registerTags;
+    private unregisterTags;
+    getStats(): {
+        size: number;
+        keys: string[];
+    };
+    static resetGlobalCache(): void;
+}