@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/cache/cache-key-utils.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared Cache Key Utilities
+ *
+ * Deterministic normalization of search params and route params
+ * for cache key generation. Used by cache-runtime, cache-scope,
+ * document-cache, and loader-cache.
+ */
+
+import { encodeKV } from "../encode-kv.js";
+
+/**
+ * Reserved URL query params that the router owns and must never key the cache
+ * on. `_rsc*` is the router's internal navigation/action/loader prefix (matched
+ * by prefix). `__no_cache` is the single `__`-prefixed param the router reads
+ * (handler.ts / testing dispatch.ts use it to bypass the store); it and the
+ * other router-internal `__`-prefixed request params are matched by an EXACT
+ * allowlist, not a blanket `__` prefix. A blanket `__` filter would silently
+ * collapse consumer params like `__variant=a` vs `__variant=b` onto one cache
+ * slot; an allowlist keeps the router's own params out of the key while leaving
+ * consumer `__` params intact.
+ */
+const RESERVED_SEARCH_PARAMS = new Set([
+  "__no_cache",
+  "__rsc",
+  "__html",
+  "__debug_manifest",
+  "__prerender_collect",
+]);
+
+function isReservedSearchParam(key: string): boolean {
+  return key.startsWith("_rsc") || RESERVED_SEARCH_PARAMS.has(key);
+}
+
+/**
+ * Build a sorted, deterministic query string from URLSearchParams,
+ * excluding the router's reserved params (see isReservedSearchParam).
+ *
+ * Returns empty string when no user-facing params exist.
+ */
+export function sortedSearchString(searchParams: URLSearchParams): string {
+  const pairs: [string, string][] = [];
+  for (const [k, v] of searchParams) {
+    if (!isReservedSearchParam(k)) {
+      pairs.push([k, v]);
+    }
+  }
+  return encodeKV(pairs, { sort: true });
+}
+
+/**
+ * Build a sorted, deterministic string from route params.
+ *
+ * Returns empty string when params is empty or undefined.
+ */
+export function sortedRouteParams(
+  params: Record<string, string> | undefined,
+): string {
+  if (!params) return "";
+  return encodeKV(Object.entries(params), { sort: true });
+}

package/src/cache/cache-policy.ts

@@ -0,0 +1,199 @@
+/**
+ * Shared Cache Policy Utilities
+ *
+ * Resolution cascades for TTL, SWR, cache key, and cache store.
+ * Consolidates the multi-tier resolution pattern:
+ *   explicit option → store defaults → fallback constant
+ */
+
+import type { CacheDefaults, SegmentCacheStore } from "./types.js";
+import { _getRequestContext } from "../server/request-context.js";
+import type { RequestContext } from "../server/request-context.js";
+import { normalizeTags } from "./cache-tag.js";
+import { reportCacheError } from "./cache-error.js";
+
+/**
+ * Default TTL for route-level cache() DSL and loader cache.
+ * Applied when neither the cache options nor the store defaults specify a TTL.
+ */
+export const DEFAULT_ROUTE_TTL = 60;
+
+/**
+ * Default TTL for function-level "use cache" (setItem).
+ * Applied when neither the item options nor the store defaults specify a TTL.
+ */
+export const DEFAULT_FUNCTION_TTL = 900;
+
+/**
+ * A finite, non-negative seconds value? A NaN/Infinity ttl/swr (from a bad
+ * cache() option or store defaults) flows into computeExpiration ->
+ * staleAt/expiresAt = NaN, where every `now > NaN` is false so the entry never
+ * evicts and is served fresh forever; a negative value makes every read a miss.
+ * Shared with cache-scope.ts (the segment getters) so every cache path validates
+ * the same way. profile-registry.ts uses the same predicate but fails fast at
+ * config time; the resolvers here degrade because they run on the live path.
+ */
+export function isFiniteNonNegativeSeconds(value: number): boolean {
+  return Number.isFinite(value) && value >= 0;
+}
+
+function warnInvalidSeconds(label: string, value: number): void {
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(`[cache] Invalid ${label} ${value}; falling back to default`);
+  }
+}
+
+/**
+ * Resolve effective TTL from the 3-tier cascade:
+ * explicit → store defaults → fallback. A non-finite/negative resolved value
+ * degrades to the fallback (loader cache and "use cache" setItem both resolve
+ * ttl here, so this is where those paths are guarded; the segment cache is
+ * guarded in cache-scope.ts).
+ */
+export function resolveTtl(
+  explicit: number | undefined,
+  defaults: CacheDefaults | undefined,
+  fallback: number,
+): number {
+  let value: number;
+  if (explicit !== undefined) value = explicit;
+  else if (defaults?.ttl !== undefined) value = defaults.ttl;
+  else return fallback;
+  if (isFiniteNonNegativeSeconds(value)) return value;
+  warnInvalidSeconds("ttl", value);
+  return fallback;
+}
+
+/**
+ * Resolve effective SWR window from the 2-tier cascade:
+ * explicit → store defaults.
+ * Returns 0 when unset (no SWR window) or when the resolved value is
+ * non-finite/negative (degrade rather than feed bad math into expiry).
+ */
+export function resolveSwrWindow(
+  explicit: number | undefined,
+  defaults: CacheDefaults | undefined,
+): number {
+  let value: number;
+  if (explicit !== undefined) value = explicit;
+  else if (defaults?.swr !== undefined) value = defaults.swr;
+  else return 0;
+  if (isFiniteNonNegativeSeconds(value)) return value;
+  warnInvalidSeconds("swr", value);
+  return 0;
+}
+
+/**
+ * Compute staleAt and expiresAt timestamps from TTL and SWR window.
+ *
+ * - staleAt: when the entry becomes stale (TTL boundary)
+ * - expiresAt: when the entry should be evicted (TTL + SWR)
+ *
+ * When swrWindow is 0, staleAt === expiresAt (no SWR).
+ */
+export function computeExpiration(
+  ttlSeconds: number,
+  swrSeconds: number = 0,
+): { staleAt: number; expiresAt: number } {
+  const now = Date.now();
+  const staleAt = now + ttlSeconds * 1000;
+  const expiresAt = staleAt + swrSeconds * 1000;
+  return { staleAt, expiresAt };
+}
+
+export async function resolveCacheKey(
+  keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined,
+  store: SegmentCacheStore | null,
+  defaultKey: string,
+  _label: string,
+): Promise<string> {
+  const requestCtx = _getRequestContext();
+
+  if (keyFn && requestCtx) {
+    return await keyFn(requestCtx);
+  }
+
+  if (store?.keyGenerator && requestCtx) {
+    return await store.keyGenerator(requestCtx, defaultKey);
+  }
+
+  return defaultKey;
+}
+
+export function resolveTagsOption<TEnv>(
+  tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined,
+  ctx: RequestContext<TEnv> | undefined,
+  label: string,
+): string[] | undefined {
+  if (!tags) return undefined;
+  if (typeof tags === "function") {
+    if (!ctx) {
+      console.warn(
+        `[${label}] Dynamic tags function present but no request context; ` +
+          `caching without tags (this entry will not be tag-invalidatable).`,
+      );
+      return undefined;
+    }
+    try {
+      return normalizeTagList(tags(ctx));
+    } catch (error) {
+      reportCacheError(
+        error,
+        "cache-write",
+        `[${label}] Tags function failed, caching without tags`,
+        ctx,
+      );
+      return undefined;
+    }
+  }
+  return normalizeTagList(tags);
+}
+
+/**
+ * Normalize a resolved tags array so the WRITE path matches the invalidate path:
+ * updateTag()/revalidateTag()/cacheTag() all drop empty/whitespace-only tags via
+ * normalizeTag(). Without this, an empty tag attached at write time would enter
+ * the store index but could never be invalidated (the verbs normalize it away),
+ * and on CFCacheStore would also cost a wasted KV marker read per request.
+ * Returns undefined when nothing usable remains, keeping the entry header-free.
+ */
+function normalizeTagList(tags: string[]): string[] | undefined {
+  const out = normalizeTags(tags);
+  return out.length > 0 ? out : undefined;
+}
+
+export function resolveCacheStore(
+  explicitStore: SegmentCacheStore | undefined,
+): SegmentCacheStore | null {
+  if (explicitStore) {
+    registerExplicitTaggedStore(explicitStore);
+    return explicitStore;
+  }
+  return _getRequestContext()?._cacheStore ?? null;
+}
+
+/**
+ * Upper bound on the per-handler explicit-store registry. A module-singleton
+ * store (the recommended pattern) dedupes to a single entry and never approaches
+ * this. The cap bounds the niche case of an explicit store constructed PER
+ * request/boundary (e.g. a ctx-bound CFCacheStore, which must take a per-request
+ * ctx): without it the registry - which intentionally persists across requests so
+ * a server action's updateTag() can reach stores a prior render registered -
+ * would accumulate one dead instance per request and fan invalidation out to
+ * finished execution contexts. LRU-touch on re-resolution keeps a live, re-used
+ * store from being evicted by that churn.
+ */
+const EXPLICIT_STORE_REGISTRY_CAP = 64;
+
+function registerExplicitTaggedStore(store: SegmentCacheStore): void {
+  const set = _getRequestContext()?._explicitTaggedStores;
+  if (!set) return;
+  // LRU touch: move an already-present store to the most-recent position (Set
+  // preserves insertion order) so a store re-resolved every request stays live.
+  set.delete(store);
+  set.add(store);
+  if (set.size > EXPLICIT_STORE_REGISTRY_CAP) {
+    const oldest = set.values().next().value;
+    if (oldest !== undefined) set.delete(oldest);
+  }
+}