@rangojs/router 0.4.0 → 0.4.1

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

@@ -1,407 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-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

@@ -1,267 +0,0 @@
-/**
- * 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;
-}