@rangojs/router 0.4.0 → 0.4.2

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

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

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

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

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

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

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

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

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

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