@rangojs/router 0.5.1 → 0.6.0

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

@@ -1,134 +0,0 @@
-/**
- * CacheScope - Runtime cache scope for iterator-based caching
- *
- * Each cache() boundary in the route tree creates a new CacheScope.
- * The scope owns: config, key management, and storage operations.
- *
- * Serialization is delegated to segment-codec.ts.
- * Handle data capture/restore is delegated to handle-snapshot.ts.
- */
-import type { PartialCacheOptions } from "../types.js";
-import type { ResolvedSegment } from "../types.js";
-import type { SegmentCacheStore } from "./types.js";
-import type { RequestContext } from "../server/request-context.js";
-export declare function resolveCacheTags(config: PartialCacheOptions | false, ctx: RequestContext | undefined): string[] | undefined;
-/**
- * CacheScope represents a cache boundary in the route tree.
- *
- * When withCache encounters an entry with cache config, it creates
- * a new CacheScope. The scope owns key management, TTL resolution,
- * and storage operations. Serialization is handled by segment-codec.ts.
- *
- * Store resolution priority:
- * 1. Explicit store in cache() options
- * 2. App-level store from handler config
- *
- * TTL resolution priority:
- * 1. Explicit value in cache() options
- * 2. Explicit store's defaults (if store specified)
- * 3. App-level store's defaults
- * 4. Hardcoded fallback (60 seconds)
- */
-export declare class CacheScope {
-    readonly config: PartialCacheOptions | false;
-    readonly parent: CacheScope | null;
-    /** Explicit store from cache() options, if specified */
-    private readonly explicitStore;
-    constructor(config: PartialCacheOptions | false, parent?: CacheScope | null);
-    /**
-     * Whether caching is enabled for this scope
-     */
-    get enabled(): boolean;
-    /**
-     * Get effective TTL from config or store defaults.
-     *
-     * Unlike profile-registry.ts (which fails fast at config time), the render
-     * path must DEGRADE: a non-finite/negative ttl (NaN/Infinity from a bad
-     * defaults config) would make computeExpiration produce NaN deadlines so the
-     * entry never evicts, or a guaranteed miss for a negative value. Fall back to
-     * DEFAULT_ROUTE_TTL instead of throwing in the foreground render.
-     */
-    get ttl(): number;
-    /**
-     * Get SWR window from config or store defaults.
-     *
-     * A non-finite/negative swr is degraded to undefined (no SWR window) rather
-     * than fed into expiry math; see the ttl getter for the rationale.
-     */
-    get swr(): number | undefined;
-    /**
-     * Get the cache store - resolution priority:
-     * 1. Explicit store from cache() options
-     * 2. App-level store from request context
-     */
-    getStore(): SegmentCacheStore | null;
-    /**
-     * Resolve the cache key using the shared 3-tier priority.
-     * @internal
-     */
-    private resolveKey;
-    /**
-     * Evaluate the cache `condition` predicate. Returns false (skip the cache
-     * operation) when the predicate returns false or throws; returns true when
-     * there is no condition or no request context to evaluate it against.
-     */
-    private conditionAllows;
-    /**
-     * Lookup cached segments for a route (single cache entry per request).
-     * Returns { segments, shouldRevalidate } or null if cache miss.
-     *
-     * @param pathname - URL pathname for cache key generation
-     * @param params - Route params for cache key generation
-     * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
-     */
-    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean): Promise<{
-        segments: ResolvedSegment[];
-        shouldRevalidate: boolean;
-    } | null>;
-    /**
-     * Record this scope's segment-DSL cache({ tags }) into the request tag union
-     * synchronously, under the same gate cacheRoute() uses for a write.
-     *
-     * cacheRoute() already records these tags, but it is invoked inside
-     * requestCtx.waitUntil() by the cache-store middleware (and the proactive path
-     * re-resolves the whole tree before calling it), so its recording is deferred
-     * and RACES the document cache's post-body-drain snapshot of _requestTags. On a
-     * first-write (segment-cache miss) the document tag union could miss these
-     * tags, and updateTag()/revalidateTag() would then fail to invalidate the
-     * cached document until a later write reseeded it. Calling this synchronously
-     * in the request pipeline (before the snapshot) closes that window. Idempotent
-     * (the tag union is a Set), so the duplicate record in cacheRoute is harmless.
-     */
-    recordTags(requestCtx: RequestContext | undefined): void;
-    /**
-     * Cache all segments for a route (non-blocking via waitUntil)
-     * Single cache entry per route request.
-     * Loaders are excluded - they're always fresh unless they have their own cache() config.
-     *
-     * @param pathname - URL pathname for cache key generation
-     * @param params - Route params for cache key generation
-     * @param segments - All resolved segments to cache
-     * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
-     */
-    cacheRoute(pathname: string, params: Record<string, string>, segments: ResolvedSegment[], isIntercept?: boolean): Promise<void>;
-}
-/**
- * Create a cache scope from entry's cache config
- */
-export declare function createCacheScope(config: {
-    options: PartialCacheOptions | false;
-} | undefined, parent?: CacheScope | null): CacheScope | null;
-/**
- * Shell fast path: when the route tree derived NO cache scope and the current
- * request context carries the `_shellImplicitCache` marker (a shell capture,
- * or a HIT tail serving an eligible entry), substitute an implicit doc-level
- * scope so withCacheLookup/withCacheStore treat the WHOLE matched route as a
- * cache() boundary — the shell entry IS a cache() of the handler layer, with
- * loaders as the live carve-outs (resolveFreshLoadersAndYield).
- *
- * An existing scope — including an explicit cache(false) opt-out — always
- * wins: the consumer's cache() semantics (their ttl/swr/store/condition) are
- * never overridden, and cache(false) keeps the tail on the full handler
- * re-run path.
- */
-export declare function resolveShellImplicitCacheScope(scope: CacheScope | null): CacheScope | null;

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

@@ -1,79 +0,0 @@
-/**
- * Cache Tag API
- *
- * Provides cacheTag() for tagging cached entries at runtime inside "use cache"
- * functions. Tags are scoped via AsyncLocalStorage; calling cacheTag() outside
- * a "use cache" execution throws.
- *
- * The runtime (cache-runtime.ts) wraps "use cache" execution in
- * runWithCacheTagScope(), collects the runtime tags, and merges them with the
- * profile/DSL tags before storing.
- */
-import { type RequestContext } from "../server/request-context.js";
-export declare function normalizeTag(tag: string): string | null;
-export declare function normalizeTags(tags: Iterable<string>): string[];
-/**
- * Tag content for later invalidation via updateTag() / revalidateTag().
- *
- * cacheTag() serves two forms depending on what is active when it runs:
- *
- * 1. Inside a "use cache" function — the DEFAULT. The tags go to the current
- *    cache entry; `revalidateTag(tag)` drops that entry. Tags are additive
- *    (multiple calls accumulate), and normalizeTag() is the single chokepoint so
- *    a padded write matches an unpadded invalidate.
- *
- * 2. Render-callable (#648) — no "use cache" scope active, but a request context
- *    is present. The tags record onto the request's DOCUMENT artifact
- *    (ctx._requestTags) instead of throwing. The collection layers already exist:
- *    PPR shell capture unions _requestTags into the shell entry, the document
- *    cache tags the full-page entry with it, and prerender build contexts seed
- *    their own set — so a server component that renders into a shell makes
- *    `revalidateTag("campaign:spring")` evict that shell with ZERO cache()/"use
- *    cache" in its tree. This is PPR's DERIVATIVE invalidation: PPR is
- *    execution-PRESERVING (everything still runs underneath; only document bytes
- *    are shortcut), so its tags ride this existing instrument rather than a
- *    first-class ppr key/tag API. The shell-expiry invariant holds by
- *    construction — baked ⇒ evicts (bake-lane loaders execute during capture and
- *    record here), hole ⇒ fresh (masked loaders behind a renderable loading()
- *    never execute during capture, so nothing under a hole can tag the shell).
- *
- * Inside a cache() DSL segment the render-callable form records at the DOCUMENT
- * level, not the segment (only the "use cache" runtime enters the tag scope) — a
- * documented semantic, not a filtered one. An empty/whitespace-only tag is
- * dropped in both forms (the render-callable form silently, via normalizeTags in
- * recordRequestTags; the scope form with a dev warning).
- *
- * With neither a scope nor a request context, cacheTag() throws.
- *
- * @example
- * ```typescript
- * // Form 1 — inside "use cache":
- * async function getProduct(ctx) {
- *   "use cache";
- *   cacheTag(`product:${ctx.params.id}`, "products");
- *   return db.getProduct(ctx.params.id);
- * }
- *
- * // Form 2 — render-callable, tags the shell/document from a server component:
- * function CampaignBanner() {
- *   cacheTag("campaign:spring");
- *   return <aside>Spring sale</aside>;
- * }
- * ```
- */
-export declare function cacheTag(...tags: string[]): void;
-export declare function recordRequestTags(tags: Iterable<string> | undefined, ctx?: RequestContext | undefined): void;
-/**
- * Run a function within a cache tag scope. Any cacheTag() calls inside `fn`
- * accumulate into the returned Set.
- *
- * The returned Set is the LIVE reference - the caller must await `result`
- * before reading `tags`, because an async cached function may call cacheTag()
- * after an await boundary.
- *
- * @internal Used by cache-runtime.ts to wrap "use cache" execution.
- */
-export declare function runWithCacheTagScope<T>(fn: () => T): {
-    result: T;
-    tags: Set<string>;
-};

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

@@ -1,4 +0,0 @@
-/** Encode ArrayBuffer to base64 string. */
-export declare function bufferToBase64(buffer: ArrayBuffer): string;
-/** Decode base64 string to ArrayBuffer. */
-export declare function base64ToBuffer(base64: string): ArrayBuffer;

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

@@ -1,105 +0,0 @@
-/** Header storing timestamp when entry becomes stale */
-export declare const CACHE_STALE_AT_HEADER = "x-edge-cache-stale-at";
-/** Header storing cache status: HIT | REVALIDATING */
-export declare const CACHE_STATUS_HEADER = "x-edge-cache-status";
-/**
- * Header storing this entry's cache tags as a JSON array. JSON-encoded (not the
- * comma-delimited CF `Cache-Tag` format) so tags containing commas round-trip
- * safely; the read paths parse this to run the tag-invalidation check.
- */
-export declare const CACHE_TAGS_HEADER = "x-edge-cache-tags";
-/** Header storing the ms-epoch timestamp when this entry's tags were attached. */
-export declare const CACHE_TAGGED_AT_HEADER = "x-edge-cache-tagged-at";
-/**
- * KV key prefix for tag-invalidation markers. A marker stores the ms-epoch
- * timestamp of the most recent invalidation of a tag; reads treat any entry
- * whose taggedAt is older than its tags' latest marker as invalidated. Markers
- * live in the SAME KV namespace as the cached entries - there is no separate
- * tag-invalidation store.
- */
-export declare const TAG_MARKER_PREFIX = "__tag__/";
-/**
- * Header storing the epoch-ms timestamp when an entry was marked REVALIDATING.
- * The SWR thundering-herd guard reads this to decide whether the in-flight
- * revalidation is still recent. It replaces a prior reliance on the HTTP `Age`
- * header: CF's Cache API does not populate `Age` reliably per-colo (and our own
- * unit MockCache never set it), so an absent `Age` defaulted to 0 and made every
- * REVALIDATING entry look "just revalidated" forever -- a dropped/never-finished
- * background revalidation could then pin an entry stale until hard expiry. An
- * explicit timestamp we write ourselves (same pattern as CACHE_STALE_AT_HEADER)
- * is reliable and lets the MAX_REVALIDATION_INTERVAL re-arm actually fire.
- */
-export declare const CACHE_REVALIDATING_AT_HEADER = "x-edge-cache-revalidating-at";
-/**
- * Header storing the absolute epoch-ms hard-expiry deadline (staleAt +
- * swrWindow*1000) of an L1 entry. The stale-path REVALIDATING re-put reads this
- * to recompute a SHRINKING Cache-Control max-age instead of copying set()'s
- * original full-window max-age. Without it, every MAX_REVALIDATION_INTERVAL
- * re-arm re-puts the full window and restarts CF's retention clock, pinning a
- * perpetually-stale entry (one whose background revalidation keeps failing) past
- * its intended hard-expiry indefinitely. Mirrors the KVSegmentEnvelope `e`
- * field and the remaining-ttl math in promoteSegmentToL1/promoteItemToL1.
- * @internal
- */
-export declare const CACHE_EXPIRES_AT_HEADER = "x-edge-cache-expires-at";
-/**
- * Header stashing the route author's original Cache-Control on L1 document
- * entries. putResponse/promoteResponseToL1 overwrite Cache-Control with a long
- * `max-age` so the CF Cache API retains the entry across the whole SWR window;
- * getResponse restores this original value before serving so the client and any
- * upstream CDN see the author's intended directive, not the internal edge TTL.
- */
-export declare const CACHE_ORIG_CC_HEADER = "x-edge-cache-orig-cc";
-/**
- * Maximum age in seconds for REVALIDATING status before allowing new revalidation.
- * After this period, a stale entry in REVALIDATING status will trigger revalidation again.
- * @internal
- */
-export declare const MAX_REVALIDATION_INTERVAL = 30;
-/**
- * Maximum time (ms) to wait for an L1 edge cache (CF Cache API) read before
- * giving up and treating it as a miss. The Cache API is normally sub-millisecond
- * per-colo, so a slow `match` signals a degraded colo; we don't want it adding
- * latency to the request. On timeout the lookup is abandoned, a warning is
- * logged, and the read falls through to its normal miss path (L2/KV or render).
- *
- * This is the default; override per store via
- * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
- */
-export declare const EDGE_LOOKUP_TIMEOUT_MS = 10;
-/**
- * Maximum time (ms) to wait for the BODY of a matched L1 entry to be read
- * (response.json()) before treating the read as a miss.
- *
- * This is separate from {@link EDGE_LOOKUP_TIMEOUT_MS} on purpose. CF's Cache
- * API resolves `match()` with a lazily-streamed body, so a fast `match` can be
- * followed by a multi-second stall while the body bytes are fetched -- the
- * latency tail lives here, after the match budget has already passed. The
- * default bounds that tail aggressively: a healthy per-colo body read (fetch +
- * JSON parse) settles in low single-digit milliseconds, so 20ms clears a
- * healthy read while still failing fast to L2/KV (or render) on a degraded colo
- * instead of pinning the request behind a seconds-long read. Raise it per store
- * if large Flight payloads legitimately need longer.
- *
- * Override per store via `CFCacheStoreOptions.edgeReadTimeoutMs` (<= 0 disables).
- */
-export declare const EDGE_READ_TIMEOUT_MS = 20;
-/**
- * Maximum time (ms) to wait for an L2 (KV) read (`kv.get(key, {type:"json"})`)
- * before treating it as a miss. Unlike the L1 budgets, KV is a GLOBAL store: the
- * file header documents ~50ms healthy reads, and a degraded namespace can tail
- * to seconds. KV is the LAST cache tier before a full render, so an unbounded
- * read here pins the whole request behind a degraded global lookup.
- *
- * The default (170ms) sits a few multiples above the documented ~50ms healthy
- * read, leaving headroom for legitimate latency tails (larger payloads,
- * far-from-colo regions) so a healthy-but-slow read does not false-miss into a
- * render, while still abandoning a genuinely degraded namespace well before its
- * multi-second tail can pin the request. A deployment with a tighter SLA can
- * lower it, and one whose healthy p99 runs higher should raise it: measure the
- * KV read p99 (Workers Analytics) and add margin. It is a degradation
- * guard-rail, not a tuning lever for "slow KV is normal here".
- *
- * Override per store via `CFCacheStoreOptions.kvReadTimeoutMs` (<= 0 disables).
- */
-export declare const KV_READ_TIMEOUT_MS = 170;