@rangojs/router 0.4.3 → 0.5.1

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

@@ -0,0 +1,407 @@
+/**
+ * Cache Store Types
+ *
+ * Generic caching interface supporting multiple value types.
+ * Designed to be implemented by different backends:
+ * - MemoryCacheStore (dev/testing)
+ * - Cloudflare Cache API adapter
+ * - Cloudflare KV adapter
+ * - Redis adapter
+ */
+import type { ResolvedSegment } from "../types.js";
+import type { RequestContext } from "../server/request-context.js";
+/**
+ * Result from cache get() including data and revalidation status
+ */
+export interface CacheGetResult {
+    /** The cached entry data */
+    data: CachedEntryData;
+    /**
+     * Whether the caller should trigger background revalidation.
+     * True when entry is stale AND not already being revalidated.
+     * The store atomically marks the entry as REVALIDATING when returning true.
+     */
+    shouldRevalidate: boolean;
+}
+/**
+ * Low-level segment cache store interface.
+ *
+ * Implementations handle the actual storage (memory, KV, Redis, etc.).
+ * The store deals with serialized data - RSC serialization is handled
+ * by the cache provider layer.
+ *
+ * @typeParam TEnv - Platform bindings type (e.g., Cloudflare env)
+ */
+export interface SegmentCacheStore<TEnv = unknown> {
+    /**
+     * Default cache options for this store.
+     * Used by cache() boundaries when ttl/swr are not explicitly specified.
+     */
+    readonly defaults?: CacheDefaults;
+    /**
+     * Custom key generator applied to all cache operations using this store.
+     * Receives the full RequestContext and the default-generated key.
+     * Return value becomes the final cache key (unless route overrides with `key` option).
+     *
+     * Resolution priority:
+     * 1. Route-level `key` function (full override)
+     * 2. Store-level `keyGenerator` (modifies default key)
+     * 3. Default key generation (prefix:pathname:params)
+     *
+     * @example Using headers for cache segmentation
+     * ```typescript
+     * keyGenerator: (ctx, defaultKey) => {
+     *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
+     *   return `${segment}:${defaultKey}`;
+     * }
+     * ```
+     *
+     * @example Using env bindings (Cloudflare)
+     * ```typescript
+     * keyGenerator: (ctx, defaultKey) => {
+     *   const region = ctx.env.REGION || 'us';
+     *   return `${region}:${defaultKey}`;
+     * }
+     * ```
+     *
+     * @example Using cookies for locale
+     * ```typescript
+     * keyGenerator: (ctx, defaultKey) => {
+     *   const locale = cookies().get('locale')?.value || 'en';
+     *   return `${locale}:${defaultKey}`;
+     * }
+     * ```
+     */
+    readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    /**
+     * Get cached entry data by key
+     * @returns Cache result with data and staleness, or null if not found/expired
+     */
+    get(key: string): Promise<CacheGetResult | null>;
+    /**
+     * Store entry data with TTL
+     * @param key - Cache key
+     * @param data - Serialized entry data
+     * @param ttl - Time-to-live in seconds
+     * @param swr - Optional stale-while-revalidate window in seconds
+     */
+    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
+    /**
+     * Delete a cached entry
+     * @returns true if deleted, false if not found
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Clear all cached entries (optional, for testing)
+     */
+    clear?(): Promise<void>;
+    /**
+     * Get a cached Response by key.
+     * Returns the response and whether it should be revalidated (SWR).
+     */
+    getResponse?(key: string): Promise<{
+        response: Response;
+        shouldRevalidate: boolean;
+    } | null>;
+    /**
+     * Store a Response with TTL and optional SWR window.
+     * @param key - Cache key
+     * @param response - Response to cache (will be cloned)
+     * @param ttl - Time-to-live in seconds
+     * @param swr - Optional stale-while-revalidate window in seconds
+     * @param tags - Optional cache tags for invalidation
+     */
+    putResponse?(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
+    /**
+     * Get a cached PPR shell entry by key.
+     * Returns the stored prelude/postponed pair (see ShellCacheEntry) and whether
+     * it should be revalidated (SWR). Used by the shell-cache middleware to serve
+     * a cached HTML shell and resume fizz for just the live holes.
+     *
+     * Optional: a store that does not implement the shell family disables the
+     * shell-cache middleware (it fails open to the normal HTML render path).
+     */
+    getShell?(key: string): Promise<{
+        entry: ShellCacheEntry;
+        shouldRevalidate?: boolean;
+    } | null>;
+    /**
+     * Store a PPR shell entry with TTL and optional SWR window.
+     * The prelude bytes and postponed state are version- and generation-coupled
+     * and travel together in a single entry (they must never mix across a React
+     * upgrade — the reactVersion field on the entry gates that at read time).
+     * @param key - Cache key
+     * @param entry - The shell prelude/postponed/version/createdAt bundle
+     * @param ttlSeconds - Time-to-live in seconds
+     * @param swrSeconds - Optional stale-while-revalidate window in seconds
+     * @param tags - Optional cache tags for invalidation (participates in
+     *   invalidateTags via the same tag machinery as the item family)
+     */
+    putShell?(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<void>;
+    /**
+     * Get a cached function result by key.
+     * Returns the serialized value, optional handle data, and staleness flag.
+     */
+    getItem?(key: string): Promise<CacheItemResult | null>;
+    /**
+     * Store a function result with TTL and optional SWR window.
+     * @param key - Cache key (format: use-cache:{functionId}:{serializedArgs})
+     * @param value - RSC-serialized return value
+     * @param options - TTL, SWR, handle data, and tags
+     */
+    setItem?(key: string, value: string, options?: CacheItemOptions): Promise<void>;
+    /**
+     * Invalidate every cache entry (segment, response, item) tagged with any of
+     * `tags`. Store-level primitive that the public updateTag()/revalidateTag()
+     * APIs delegate to. Receives ALL of one invalidation call's tags at once so
+     * stores can batch their work (e.g. a single CDN purge request rather than
+     * one per tag). Stores that do not support tags simply omit this method.
+     * @param tags - The cache tags to invalidate
+     */
+    invalidateTags?(tags: string[]): Promise<void>;
+    /**
+     * True when ANY of `tags` was invalidated (invalidateTags/updateTag) at or
+     * after `sinceMs` (>= so a same-millisecond invalidation wins, favouring
+     * freshness). Consulted by the build-time shell read-through
+     * (rsc/shell-build-manifest.ts): a baked shell entry is immutable in the
+     * build manifest, so "was it evicted" is answered by the store's tag
+     * markers against the entry's createdAt rather than by deleting anything.
+     * Optional: without it, TAGGED build entries are not served (untagged ones
+     * are unaffected — they are evictable only by deploy/buildVersion anyway).
+     * Fail open to `false` on marker-read errors: a transient store fault must
+     * degrade to "still valid", the same posture as the envelope tag checks.
+     */
+    isTagsInvalidatedSince?(tags: string[], sinceMs: number): Promise<boolean>;
+}
+/**
+ * Result from getItem() for function-level caching ("use cache").
+ */
+export interface CacheItemResult {
+    /** RSC-serialized return value */
+    value: string;
+    /** RSC-encoded handle data captured during execution (breadcrumbs, metadata,
+     *  etc.). Encoded via the Flight codec so Promise/ReactNode handle values
+     *  survive JSON-serializing stores — see handle-snapshot.ts encodeHandles. */
+    handles?: string;
+    /** Whether the entry is stale and should be revalidated */
+    shouldRevalidate: boolean;
+    /**
+     * The entry's cache tags (including runtime cacheTag() tags), surfaced on read
+     * so a "use cache" HIT can still contribute its tags to the request-scoped tag
+     * set used by document-level caching. On a hit the cached function is not
+     * re-run, so its runtime tags are only available here, not from re-execution.
+     */
+    tags?: string[];
+}
+/**
+ * A cached PPR (Partial Pre-rendering) shell entry.
+ *
+ * One entry carries BOTH artifacts a resume needs — the rendered HTML prelude
+ * and React's postponed state — because the pair is version- and
+ * generation-coupled and must never be mixed across a React upgrade or a build
+ * change. The reactVersion and buildVersion fields are the read-time gates that
+ * enforce both halves: isValidShellHit (rsc/shell-serve.ts) treats an entry
+ * whose reactVersion differs from the running React, or whose buildVersion
+ * differs from the running build, as a miss (the postponed blob encodes hole
+ * positions against one exact tree; resuming it against a different React or a
+ * different app build tree-mismatches inside resume(), AFTER the 200 + prelude
+ * are committed — an unrecoverable broken serve).
+ */
+export interface ShellCacheEntry {
+    /** Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing). */
+    prelude: string;
+    /**
+     * JSON.stringify of React's postponed state, or null when the shell settled
+     * with no holes (the DATA variant — served without a fizz resume).
+     */
+    postponed: string | null;
+    /** React.version captured at prerender time; the read-time invalidation gate. */
+    reactVersion: string;
+    /**
+     * Build version captured at prerender time (the RSC handler's `version` —
+     * the `@rangojs/router:version` build stamp by default, bumped per build and
+     * on dev RSC-module edits). The second read-time gate: a persistent shared
+     * store (KV/runtime-cache) survives deploys, and an app-code change that
+     * keeps the same React version would otherwise leave a stale-build
+     * prelude+postponed live under the same key. Optional only for entries
+     * stored before the field existed — those are treated as a miss and the
+     * recapture re-stamps them (pre-release, no compat shim).
+     */
+    buildVersion?: string;
+    /**
+     * The initialTheme the CAPTURE render was built with (the derived context's
+     * reqCtx.theme). The resume tail must render ThemeProvider with the SAME
+     * initialTheme the frozen prelude was rendered with: React resume requires the
+     * tree above the holes to match the prerendered tree, and initialTheme is
+     * per-request METADATA, not part of the cached segments — a visitor whose
+     * theme differs from the capturer's would otherwise produce a divergent resume
+     * tree (broken stitching/hydration). The visitor's real theme is applied
+     * pre-paint by the FOUC script and re-synced from the cookie post-mount by
+     * ThemeProvider.
+     */
+    initialTheme?: string;
+    /**
+     * The CAPTURE DATA SNAPSHOT: every cache-store read-hit and write the capture
+     * render performed, in stored/serialized form. Replaying these on a HIT (via
+     * the SeededShellStore overlay, for the tail render only) reproduces the
+     * shell's cached content byte-identically, so the freshly rendered hydration
+     * payload matches the frozen prelude even after the underlying cache entries
+     * have drifted (expired, been recomputed, or been tag-invalidated).
+     *
+     * Optional: an entry captured before this field existed simply has no
+     * snapshot and keeps the pre-snapshot behavior (the tail reads live, so any
+     * shell-baked cached value that drifted mismatches the prelude). Recapture
+     * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
+     */
+    snapshot?: ShellSnapshotRecord[];
+    /**
+     * True when the capture's HANDLER layer declared per-request liveness: a
+     * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the
+     * capture mask turns it into a never-filling hole), such a push was still
+     * pending when the entry was written, or a handler-invoked loader
+     * (ctx.use(loader) from a handler body — the consumption lane, #672)
+     * executed during the capture. The serve tail then must NOT take the
+     * handler-free fast path (the implicit doc-cache hit): only a handler
+     * re-run can mint that hole's live promise or refresh that consumed value.
+     * DSL-loader pushes never set this — loaders re-run fresh on every HIT, so
+     * their holes always fill.
+     */
+    handlerLiveHoles?: boolean;
+    /** Epoch ms when the shell was captured. */
+    createdAt: number;
+}
+/**
+ * The families a shell snapshot pins. The item/segment/response families are
+ * cache-store reads/writes (recorded by RecordingShellStore); the loader family
+ * pins the settled CONTAINER of a bake-lane loader (a loader on an entry with
+ * no renderable loading(), executed during capture — see
+ * docs/design/loader-container-bake.md). Excludes the shell family itself
+ * (getShell/putShell) — the snapshot rides INSIDE a shell entry, so recording
+ * it would be self-referential.
+ */
+export type ShellSnapshotFamily = "item" | "segment" | "response" | "loader";
+/**
+ * The stored form of a loader-family snapshot value: the bake-lane loader's
+ * settled container, Flight-serialized AFTER eliding every still-pending nested
+ * promise to a hole marker (the marker paths are holes, not shell material; on
+ * a HIT the overlay re-slots the fresh run's promises there). Flight (not JSON)
+ * so typed values (Date/Map) survive the round trip.
+ */
+export interface ShellSnapshotLoaderValue {
+    /** RSC-serialized elided container (see loader-snapshot.ts). */
+    value: string;
+}
+/** A serialized cached Response for the response family of a shell snapshot. */
+export interface ShellSnapshotResponseValue {
+    status: number;
+    /** Client-facing header pairs (per-client signal headers excluded at record). */
+    headers: [string, string][];
+    /** base64-encoded response body (binary-safe, JSON-serializable). */
+    body: string;
+}
+/** The stored form of an item-family (use cache / loader cache) snapshot value. */
+export interface ShellSnapshotItemValue {
+    /** RSC-serialized return value. */
+    value: string;
+    /** RSC-encoded handle data, if any. */
+    handles?: string;
+    /** The entry's cache tags. */
+    tags?: string[];
+}
+/**
+ * One recorded cache-store read-hit or write from the capture render. `value`
+ * carries the entry in its stored/serialized shape so it round-trips through a
+ * JSON-serializing store (KV, CF, Vercel) with the rest of the ShellCacheEntry:
+ * - `item`    -> {@link ShellSnapshotItemValue}
+ * - `segment` -> {@link CachedEntryData} (already JSON-able)
+ * - `response`-> {@link ShellSnapshotResponseValue}
+ */
+export interface ShellSnapshotRecord {
+    family: ShellSnapshotFamily;
+    key: string;
+    value: ShellSnapshotItemValue | CachedEntryData | ShellSnapshotResponseValue | ShellSnapshotLoaderValue;
+}
+/**
+ * Options for setItem() for function-level caching ("use cache").
+ */
+export interface CacheItemOptions {
+    /** RSC-encoded handle data to store alongside the value (see encodeHandles). */
+    handles?: string;
+    /** Time-to-live in seconds */
+    ttl?: number;
+    /** Stale-while-revalidate window in seconds */
+    swr?: number;
+    /** Cache tags for invalidation */
+    tags?: string[];
+}
+/**
+ * Serialized segment data stored in cache
+ * Note: loading is preserved to ensure consistent tree structure between cached and fresh renders
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface SerializedSegmentData {
+    /** RSC-encoded component string */
+    encoded: string;
+    /** RSC-encoded layout string (if present) */
+    encodedLayout?: string;
+    /** RSC-encoded loading skeleton string (if present), or "null" for explicit null */
+    encodedLoading?: string;
+    /** RSC-encoded loaderData (if present) */
+    encodedLoaderData?: string;
+    /** RSC-encoded loaderDataPromise (if present) */
+    encodedLoaderDataPromise?: string;
+    /** Segment metadata (everything except component, layout, loading, and loader data) */
+    metadata: Omit<ResolvedSegment, "component" | "layout" | "loading" | "loaderData" | "loaderDataPromise">;
+}
+/**
+ * Raw data stored in cache for an entry
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface CachedEntryData {
+    /** Serialized segments for this entry */
+    segments: SerializedSegmentData[];
+    /** RSC-encoded handle data keyed by segment ID. Encoded via the Flight codec
+     *  (see handle-snapshot.ts encodeHandles) so Promise/ReactNode handle values
+     *  round-trip through JSON-serializing stores instead of being flattened. */
+    handles: string;
+    /** Expiration timestamp (ms since epoch) */
+    expiresAt: number;
+    /** Cache tags for invalidation */
+    tags?: string[];
+    /** Timestamp (ms since epoch) when tags were attached, for distributed invalidation */
+    taggedAt?: number;
+}
+/**
+ * Default cache options applied to all cache() boundaries.
+ * Individual cache() calls can override any of these values.
+ *
+ * @example
+ * ```ts
+ * const store = new CFCacheStore({
+ *   defaults: { ttl: 60, swr: 300 }
+ * });
+ * ```
+ */
+export interface CacheDefaults {
+    /**
+     * Default time-to-live in seconds.
+     * After TTL expires, cached entry is considered stale.
+     * Must be a finite, non-negative number; an invalid value (NaN/Infinity/
+     * negative) falls back to the default at read time.
+     */
+    ttl?: number;
+    /**
+     * Default stale-while-revalidate window in seconds.
+     * During SWR window, stale content is served while revalidating in background.
+     * Must be a finite, non-negative number; an invalid value (NaN/Infinity/
+     * negative) falls back to the default at read time.
+     */
+    swr?: number;
+}
+/**
+ * Handle data for a single segment
+ * Structure: { handleName: [values...] }
+ */
+export type SegmentHandleData = Record<string, unknown[]>;

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

@@ -0,0 +1 @@
+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-cache-store.js";

package/dist/types.backup/cache/vercel/vercel-cache-store.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Vercel Runtime Cache Store
+ *
+ * A SegmentCacheStore backed by Vercel's Runtime Cache (`getCache()` from
+ * `@vercel/functions`). It is the production store analogue to CFCacheStore, but
+ * far smaller: Vercel's Runtime Cache already IS a distributed, tag-aware cache
+ * (regional storage, global tag-expire within ~300ms), so none of CFCacheStore's
+ * L1/L2 tiering, KV tag-marker comparison, marker memoization, or per-tier
+ * timeout budgets are needed here - the platform does that work. What this store
+ * adds on top of the raw primitive is the parts Vercel does NOT give us:
+ *
+ *   1. Stale-while-revalidate. `getCache` has no stale-but-serve: a TTL'd entry
+ *      simply becomes a miss. We store our own {staleAt, expiresAt} envelope and
+ *      set the Vercel ttl to (ttl + swr) so the entry survives its SWR window,
+ *      computing staleness ourselves via the shared cache-policy helpers.
+ *   2. A single-keyspace family split. `getCache` is one flat keyspace, whereas
+ *      the interface has three value families (segments, "use cache" items, full
+ *      responses). The memory store keeps three separate Maps; here they must be
+ *      namespaced by a prefix or a set() of a response would clobber a segment
+ *      cached under the same router key.
+ *   3. The platform guardrails: the 2 MB per-item ceiling (oversized writes
+ *      silently no-op on Vercel, so we skip + report), the per-item tag cap, and
+ *      cross-deploy non-reconciliation (TTL/tag updates are not reconciled across
+ *      deployments - bake a build id into `version` or the getCache namespace).
+ *
+ * Dependency stance: this module imports NOTHING from `@vercel/functions`. The
+ * runtime cache handle (and `waitUntil`) are injected through the constructor and
+ * typed against the local VercelRuntimeCache shape below, exactly as CFCacheStore
+ * takes its `kv`/`ctx` bindings by injection. The consumer passes the real
+ * `getCache(...)` result, which satisfies the shape structurally. That keeps the
+ * router free of a hard Vercel dependency.
+ */
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry } from "../types.js";
+import type { RequestContext } from "../../server/request-context.js";
+/**
+ * Minimal structural shape of the Vercel Runtime Cache returned by `getCache()`
+ * from `@vercel/functions`. Declared locally so @rangojs/router carries no hard
+ * dependency on `@vercel/functions`; the real handle satisfies it structurally.
+ *
+ * @see https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package#getcache
+ */
+export interface VercelRuntimeCache {
+    /** Returns the stored value, or a nullish value on miss. Never throws on miss. */
+    get(key: string): Promise<unknown>;
+    /** Stores a value with optional TTL (seconds), tags, and observability name. */
+    set(key: string, value: unknown, options?: {
+        ttl?: number;
+        tags?: string[];
+        name?: string;
+    }): Promise<void>;
+    /** Removes a value by key. */
+    delete(key: string): Promise<void>;
+    /** Expires every entry tagged with any of `tag`. Global, ~300ms propagation. */
+    expireTag(tag: string | string[]): Promise<void>;
+}
+/**
+ * Vercel Runtime Cache hard per-item ceiling: 2 MB. Writes above this silently
+ * no-op on the platform, so the store measures the serialized envelope and skips
+ * (fail-open) entries at or above this size.
+ */
+export declare const VERCEL_MAX_ITEM_BYTES: number;
+/**
+ * Per-item tag ceiling. Vercel's getCache API reference lists 128 tags per item
+ * (https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package#getcache).
+ * Tags beyond this are dropped with a warning at write time. Does NOT cap
+ * invalidateTags() - an invalidation must reach every requested tag.
+ */
+export declare const VERCEL_MAX_TAGS_PER_ITEM: number;
+/** Max tag length in UTF-8 bytes accepted by Vercel; longer tags are skipped. */
+export declare const VERCEL_MAX_TAG_BYTES: number;
+/** Read-path outcome for the debug sink. */
+export type VercelCacheReadOutcome = "miss" | "fresh" | "stale-revalidate" | "expired" | "corrupt" | "error";
+/** Diagnostic event emitted on every read when `debug` is set. */
+export interface VercelCacheReadDebugEvent {
+    op: "get" | "getItem" | "getResponse" | "getShell";
+    key: string;
+    outcome: VercelCacheReadOutcome;
+    staleAt?: number;
+    expiresAt?: number;
+    shouldRevalidate?: boolean;
+    /** Wall-clock ms spent in the backing cache.get(). */
+    readMs?: number;
+}
+/** `true` logs each read outcome; a function receives the structured event. */
+export type VercelCacheDebug = boolean | ((event: VercelCacheReadDebugEvent) => void);
+/**
+ * Options for VercelCacheStore.
+ */
+export interface VercelCacheStoreOptions<TEnv = unknown> {
+    /**
+     * The Vercel Runtime Cache handle - `getCache()` from `@vercel/functions`.
+     * Required. Construct it with a build-hash namespace to bust stale-shaped
+     * entries across deployments, since Vercel does not reconcile TTL/tags between
+     * deploys:
+     *
+     * ```ts
+     * import { getCache } from "@vercel/functions";
+     * new VercelCacheStore({ cache: getCache({ namespace: BUILD_ID }) });
+     * ```
+     */
+    cache: VercelRuntimeCache;
+    /**
+     * `waitUntil` from `@vercel/functions`. Used only to run the stale-read lock
+     * write (herd dampening) off the response path - the router already
+     * backgrounds the actual writes. When omitted, the lock write runs detached
+     * (fire-and-forget) instead.
+     */
+    waitUntil?: (promise: Promise<unknown>) => void;
+    /**
+     * Default ttl/swr for cache() boundaries when not explicitly specified.
+     */
+    defaults?: CacheDefaults;
+    /**
+     * Custom key generator applied to all cache operations (region/locale/user
+     * segmentation). Receives the request context and the default key.
+     */
+    keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    /**
+     * Build/version id folded into every stored key as `v/{version}/...`. A second
+     * cross-deploy busting layer in addition to (or instead of) the getCache
+     * namespace. Changing it invalidates everything this store wrote previously.
+     */
+    version?: string;
+    /**
+     * Max serialized entry size in bytes before a write is skipped. Defaults to
+     * VERCEL_MAX_ITEM_BYTES (2 MB - the platform's hard cap).
+     */
+    maxItemBytes?: number;
+    /**
+     * Human-readable label passed as the Vercel `set({ name })` option for
+     * observability in the Vercel dashboard.
+     */
+    name?: string;
+    /**
+     * Read diagnostics. `true` logs each read outcome to the console; a function
+     * receives the structured VercelCacheReadDebugEvent.
+     */
+    debug?: VercelCacheDebug;
+}
+/**
+ * Vercel Runtime Cache-backed segment cache store.
+ *
+ * Suitable for production deployments on Vercel Functions (Node runtime). The
+ * store is best-effort: every read failure degrades to a miss and every write
+ * failure to a no-op (reported, never thrown) - the sole exception is
+ * invalidateTags(), which rejects when the injected cache's expireTag() rejects
+ * so an awaited updateTag() can surface the failure.
+ *
+ * Read-your-own-writes caveat: this honesty is only as strong as the cache
+ * handle. The official `@vercel/functions` cache (`BuildCache.expireTag`)
+ * CATCHES backend failures and resolves, so with the official client a failed
+ * expireTag is invisible here and an awaited updateTag() can report success that
+ * did not happen. Treat tag invalidation on the official Vercel client as
+ * best-effort, not a hard read-your-own-writes guarantee. (A custom cache handle
+ * that propagates expireTag rejections does get the strict guarantee, which is
+ * what the unit suite exercises.)
+ *
+ * Key hashing / family isolation. The store namespaces its three value tiers as
+ * `rg:{s|i|r}:{key}` so segment, `"use cache"`, and response entries occupy
+ * disjoint keyspaces. That separation is only as strong as the cache's
+ * `keyHashFunction`: `getCache`'s default is djb2, which folds every key to 32
+ * bits (8 hex chars), so at a large live-key count a collision can let one
+ * entry's body be served for another key (same-family) or be misread as corrupt
+ * (cross-family). For deployments with many cached keys, pass a wider hash so
+ * the family split is real isolation, e.g. `getCache({ keyHashFunction })` with
+ * a sha256-based function.
+ *
+ * @example
+ * ```ts
+ * import { getCache, waitUntil } from "@vercel/functions";
+ * import { VercelCacheStore } from "@rangojs/router/cache";
+ *
+ * export const router = createRouter({
+ *   cache: () => ({
+ *     store: new VercelCacheStore({
+ *       // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
+ *       // would be undefined here) so cross-deploy busting via `version` works.
+ *       cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+ *       waitUntil,
+ *       defaults: { ttl: 60, swr: 300 },
+ *     }),
+ *   }),
+ * });
+ * ```
+ */
+export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    readonly defaults?: CacheDefaults;
+    readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    private readonly cache;
+    private readonly waitUntil?;
+    private readonly version?;
+    private readonly maxItemBytes;
+    private readonly name?;
+    private readonly debug?;
+    constructor(options: VercelCacheStoreOptions<TEnv>);
+    get(key: string): Promise<CacheGetResult | null>;
+    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    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>;
+    /**
+     * Build-shell read-through gate (SegmentCacheStore.isTagsInvalidatedSince).
+     * The platform's expireTag() DELETES tagged entries and keeps no queryable
+     * history, so invalidateTags() below writes its own "tm" marker entries and
+     * this compares them against the baked entry's build-time createdAt
+     * (>= so a same-millisecond invalidation wins). Fails open to `false` on
+     * read errors — the same posture as the CF marker check.
+     */
+    isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    invalidateTags(tags: string[]): Promise<void>;
+    private toStoreKey;
+    private write;
+    /**
+     * Normalize a value read back from the cache. Entries written by this store
+     * are pre-serialized JSON strings (see write()); legacy entries (written
+     * before that change, or by a client that deserializes for us) come back as
+     * objects. Parse strings, pass objects through, and treat a non-JSON string
+     * as corrupt (returns undefined, so the caller reports + evicts).
+     */
+    private decodeRaw;
+    /**
+     * Stale-read herd dampening via a tiny companion lock key. On a stale read,
+     * check `{storeKey}:lock`; if absent, claim it (write a short-TTL marker) and
+     * return true so THIS reader triggers revalidation. If present, another
+     * same-region reader already claimed it, so return false and serve the stale
+     * entry as fresh without piling on. Best-effort and non-blocking; never throws.
+     *
+     * Only the STALE path pays the extra lock read; the fresh-hit path takes no
+     * lock round trip. Unlike the prior whole-envelope re-stamp, a stale read now
+     * writes only the tiny lock, never the (potentially large) payload.
+     *
+     * Non-atomic (getCache has no compare-and-set): two readers can both find no
+     * lock and both revalidate. The window is REVALIDATION_LOCK_MS wide, after
+     * which the lock expires and the entry is re-claimed (or a fresh write has
+     * superseded it). A read-compare would not close the race without CAS.
+     */
+    private claimRevalidation;
+    /** Measure a pre-serialized entry against the per-item size cap (see write). */
+    private withinSizeLimit;
+    /**
+     * Drop tags Vercel cannot round-trip: over-length tags, and tags carrying a
+     * URL metacharacter the `@vercel/functions` client does not encode (see
+     * VERCEL_UNSAFE_TAG_CHARS). Runs on BOTH paths - the write path
+     * (clampTagsForWrite) and invalidateTags - so a tag that would silently fail
+     * invalidation is never stored in the first place. `category` reports the
+     * drop under the caller's real operation (write vs invalidate).
+     */
+    private validateTags;
+    /** validateTags + the per-item tag cap. Used on the write path. */
+    private clampTagsForWrite;
+    private safeDelete;
+    private emitDebug;
+    private asSegmentEnvelope;
+    private asItemEnvelope;
+    private asShellEnvelope;
+    private asResponseEnvelope;
+}