@textjs/app 0.0.0-stage → 1.0.3

package/dist/server/cache-route.js

@@ -0,0 +1,109 @@
+/**
+ * Full-route caching for `app/**\/route.ts` handlers: `export const dynamic`
+ * and `export const revalidate` (Next.js route segment config).
+ *
+ * - `dynamic = "force-static"` or `revalidate = N` (N > 0): `GET` / `HEAD` are
+ *   cached per pathname with stale-while-revalidate. The handler receives a
+ *   build-time-like request (no query string, headers, cookies or body).
+ * - Default, `"force-dynamic"` or `revalidate = 0`: run on every request.
+ */
+import { txError } from "@textjs/core";
+import { markGeneratedCacheControl, PRIVATE_CACHE_CONTROL, runRouteHandler } from "./http.js";
+import { __validateRevalidate, EXPIRE_SECONDS, getOrCompute, implicitTags, normalizeCachePath, runInCacheScope } from "./cache.js";
+export const CACHE_HEADER = "x-textjs-cache";
+// Next.js's `"error"` (static, failing on request reads) is rejected: Text.js can't detect request reads.
+const DYNAMIC_VALUES = new Set(["auto", "force-static", "force-dynamic"]);
+/** Read and validate a route module's `dynamic` / `revalidate` exports. */
+export function routeCacheConfig(mod, where = "route handler") {
+    const dynamic = mod.dynamic ?? "auto";
+    if (typeof dynamic !== "string" || !DYNAMIC_VALUES.has(dynamic))
+        throw txError("TX031", JSON.stringify(dynamic), where);
+    const revalidate = __validateRevalidate(mod.revalidate, where);
+    if (dynamic === "force-dynamic" || revalidate === 0)
+        return { static: false, revalidate: 0 };
+    if (dynamic === "force-static")
+        return { static: true, revalidate };
+    return { static: typeof revalidate === "number" && revalidate > 0, revalidate };
+}
+function toBase64(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(s);
+}
+function fromBase64(b64) {
+    const s = atob(b64);
+    const out = new Uint8Array(new ArrayBuffer(s.length));
+    for (let i = 0; i < s.length; i++)
+        out[i] = s.charCodeAt(i);
+    return out;
+}
+/** The request a static handler sees: same origin and path, nothing request-specific. */
+export function staticRequest(request) {
+    const url = new URL(request.url);
+    return new Request(new URL(url.pathname, url.origin), { method: "GET" });
+}
+/** `Cache-Control` for a cached route (Next.js: `s-maxage=N, stale-while-revalidate=<expire - N>`). */
+export function cacheControlFor(revalidate) {
+    if (revalidate === false || !Number.isFinite(revalidate))
+        return `s-maxage=${EXPIRE_SECONDS}`;
+    const seconds = Math.min(EXPIRE_SECONDS, Math.max(1, Math.ceil(revalidate)));
+    return `s-maxage=${seconds}, stale-while-revalidate=${EXPIRE_SECONDS - seconds}`;
+}
+/** Responses a shared cache must never replay to other visitors. */
+export function isUncacheableResponse(res) {
+    if (res.status >= 500)
+        return true;
+    if (res.headers.has("set-cookie"))
+        return true;
+    const cc = (res.headers.get("cache-control") ?? "").toLowerCase();
+    return /(?:^|,)\s*(?:private|no-store)\b/.test(cc);
+}
+/** Run a route handler with route segment config caching. */
+export async function runRouteHandlerWithCache(mod, request, ctx) {
+    const pathname = normalizeCachePath(ctx.pathname ?? new URL(request.url).pathname);
+    const config = routeCacheConfig(mod, `${ctx.pattern}/route`);
+    const method = request.method.toUpperCase();
+    const tags = implicitTags(pathname, ctx.pattern);
+    const scope = () => ({ tags: new Set(tags), revalidate: config.revalidate, implicitTags: tags, waitUntil: ctx.waitUntil });
+    if (!config.static || (method !== "GET" && method !== "HEAD") || typeof mod.GET !== "function") {
+        return runInCacheScope(scope(), () => runRouteHandler(mod, request, ctx.params));
+    }
+    const input = staticRequest(request);
+    if (ctx.cache === false) {
+        const res = await runInCacheScope(scope(), () => runRouteHandler(mod, input, ctx.params));
+        return method === "HEAD" ? new Response(null, { status: res.status, statusText: res.statusText, headers: res.headers }) : res;
+    }
+    const resolved = await getOrCompute(`route:${pathname}`, async () => {
+        const s = scope();
+        const res = await runInCacheScope(s, () => runRouteHandler(mod, input, ctx.params));
+        if ((res.headers.get("content-type") ?? "").includes("text/event-stream")) {
+            await res.body?.cancel().catch(() => undefined);
+            throw new Error(`Route ${ctx.pattern} is static (dynamic = "force-static" / revalidate) but returned a text/event-stream response. Streaming route handlers must be dynamic: export const dynamic = "force-dynamic".`);
+        }
+        const body = new Uint8Array(await res.arrayBuffer());
+        const value = { status: res.status, statusText: res.statusText, headers: [...res.headers], body: toBase64(body) };
+        // Server errors, cookies and private responses are returned to this request but never stored.
+        return { value, tags: [...s.tags], revalidate: isUncacheableResponse(res) ? 0 : s.revalidate };
+    }, ctx.waitUntil);
+    const stored = resolved.entry.value;
+    const headers = new Headers();
+    for (const [k, v] of stored.headers)
+        headers.append(k, v);
+    let generated = false;
+    if (resolved.entry.revalidate === 0) {
+        if (stored.status >= 500 || !headers.has("cache-control"))
+            headers.set("cache-control", PRIVATE_CACHE_CONTROL);
+    }
+    else {
+        headers.set(CACHE_HEADER, resolved.status);
+        if (!headers.has("cache-control")) {
+            headers.set("cache-control", cacheControlFor(resolved.entry.revalidate));
+            generated = true;
+        }
+    }
+    const body = method === "HEAD" || stored.status === 204 || stored.status === 304 ? null : fromBase64(stored.body);
+    const response = new Response(body, { status: stored.status, statusText: stored.statusText, headers });
+    return generated ? markGeneratedCacheControl(response) : response;
+}
+//# sourceMappingURL=cache-route.js.map

package/dist/server/cache-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-route.js","sourceRoot":"","sources":["../../src/server/cache-route.ts"],"names":[],"mappings":"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"}

package/dist/server/cache.d.ts

@@ -0,0 +1,131 @@
+/**
+ * `@textjs/app/cache` — the data cache: `unstable_cache()` / `cache()` with
+ * tags and time-based revalidation, `revalidateTag()` / `revalidatePath()`,
+ * stale-while-revalidate semantics and a pluggable store (in-memory by default).
+ *
+ * State lives on `globalThis` so the CLI, the route-handler bundle and user
+ * code share one cache even when they load separate copies of this module.
+ */
+type Awaitable<T> = T | Promise<T>;
+export interface CacheEntry {
+    /** Serialized value (JSON for the data cache, `{ status, headers, body }` for routes). */
+    value: unknown;
+    /** Epoch ms when the computation that produced `value` started. */
+    lastModified: number;
+    /** Seconds until the entry turns stale; `false` = only on-demand revalidation. */
+    revalidate: number | false;
+    tags: string[];
+}
+export interface TagState {
+    /** Latest `revalidateTag()` / `revalidatePath()` that expired one of the tags (epoch ms, `0` = never). */
+    expiredAt: number;
+    /** Latest `revalidateTag(tag, "max")` that marked one of the tags stale. */
+    staleAt: number;
+}
+/**
+ * A cache backend. Implement this to share the cache across instances
+ * (Redis, Upstash, Workers KV, …) and point `cacheHandler` in
+ * `text.config.ts` at a module that default-exports it.
+ */
+export interface CacheStore {
+    get(key: string): Awaitable<CacheEntry | undefined>;
+    set(key: string, entry: CacheEntry): Awaitable<void>;
+    delete(key: string): Awaitable<void>;
+    /** Record that `tags` were revalidated at `at`. */
+    markTags(tags: readonly string[], mode: "expire" | "stale", at: number): Awaitable<void>;
+    getTagState(tags: readonly string[]): Awaitable<TagState>;
+}
+export interface MemoryCacheStoreOptions {
+    /** Maximum entries before the least recently used are evicted (default `1000`). */
+    maxEntries?: number;
+    /** Approximate maximum size in bytes (default 50 MB). */
+    maxSize?: number;
+    /** Maximum remembered tag revalidations before the oldest are dropped (default `10000`). */
+    maxTags?: number;
+}
+/** The default store: a per-process LRU map. */
+export declare class MemoryCacheStore implements CacheStore {
+    #private;
+    constructor(options?: MemoryCacheStoreOptions);
+    get size(): number;
+    get(key: string): CacheEntry | undefined;
+    set(key: string, entry: CacheEntry): void;
+    delete(key: string): void;
+    markTags(tags: readonly string[], mode: "expire" | "stale", at: number): void;
+    getTagState(tags: readonly string[]): TagState;
+    clear(): void;
+}
+/** Collects tags and the shortest `revalidate` of everything cached while a route handler runs. */
+export interface CacheScope {
+    tags: Set<string>;
+    revalidate: number | false;
+    /** Path-derived tags (`revalidatePath`) inherited by data cached inside the scope. */
+    implicitTags: readonly string[];
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+/** Strictly increasing timestamps, so a revalidation in the same millisecond as a write still wins. */
+export declare function cacheNow(): number;
+/** Replace the cache backend (`text.config.ts` → `cacheHandler` does this for you). */
+export declare function setCacheStore(store: CacheStore): void;
+export declare function getCacheStore(): CacheStore;
+/** @internal Test hooks: a fake clock, error sink, or a fresh in-memory store. */
+export declare function __configureCache(options: {
+    clock?: () => number;
+    onError?: (error: unknown, key: string) => void;
+    reset?: boolean;
+}): void;
+export declare function currentCacheScope(): CacheScope | undefined;
+export declare function runInCacheScope<T>(scope: CacheScope, fn: () => T): T;
+/** Entries older than a year are regenerated in the foreground (Next.js `expireTime`). */
+export declare const EXPIRE_SECONDS = 31536000;
+export type CacheStatus = "HIT" | "STALE" | "MISS";
+interface ResolvedEntry {
+    entry: CacheEntry;
+    status: CacheStatus;
+}
+export interface Computed {
+    value: unknown;
+    tags: readonly string[];
+    /** `0` = don't store (dynamic). */
+    revalidate: number | false;
+}
+export declare function classifyEntry(entry: CacheEntry, tags: TagState, now: number): "fresh" | "stale" | "expired";
+/**
+ * Read `key`, serving stale entries while one deduplicated background
+ * refresh runs (registered with `waitUntil` on serverless runtimes).
+ */
+export declare function getOrCompute(key: string, fn: () => Promise<Computed>, waitUntil?: (p: Promise<unknown>) => void): Promise<ResolvedEntry>;
+export interface CacheOptions {
+    /** Tags for `revalidateTag()`. */
+    tags?: string[];
+    /** Seconds before the value turns stale (served while refreshing). `false` (default) = until revalidated. */
+    revalidate?: number | false;
+}
+declare function validateRevalidate(value: unknown, where: string): number | false;
+/** A collision-free cache key for arguments (`undefined` ≠ `null`, `Map` / `Set` / `Date` / `bigint` by value). */
+export declare function serializeCacheArgs(value: unknown, seen?: Set<object>): string;
+/**
+ * Cache the result of an async function (Next.js `unstable_cache`). Results
+ * are JSON-serialized, so every call returns a fresh copy. The cache key is
+ * `keyParts` (or the function source) plus the JSON-encoded arguments.
+ */
+export declare function unstable_cache<Args extends unknown[], R>(fn: (...args: Args) => Promise<R> | R, keyParts?: readonly string[], options?: CacheOptions): (...args: Args) => Promise<R>;
+/** `unstable_cache` with an options object: `cache(fn, { key, tags, revalidate })`. */
+export declare function cache<Args extends unknown[], R>(fn: (...args: Args) => Promise<R> | R, options?: CacheOptions & {
+    key?: string | string[];
+}): (...args: Args) => Promise<R>;
+/**
+ * Invalidate every entry tagged `tag`. By default the next request recomputes
+ * in the foreground; pass `"max"` to serve the stale value while it refreshes.
+ */
+export declare function revalidateTag(tag: string | readonly string[], profile?: "max"): Promise<void>;
+export declare function normalizeCachePath(path: string): string;
+/** Tags a route entry carries: `_P:<path>` for itself and `_L:<prefix>` for every enclosing segment. */
+export declare function implicitTags(pathname: string, pattern?: string): string[];
+/**
+ * Invalidate a cached path (`"page"`, the default) or everything below it
+ * (`"layout"`). Dynamic patterns work too: `revalidatePath("/api/posts/[id]")`.
+ */
+export declare function revalidatePath(path: string, type?: "page" | "layout"): Promise<void>;
+export { validateRevalidate as __validateRevalidate };
+//# sourceMappingURL=cache.d.ts.map

package/dist/server/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/server/cache.ts"],"names":[],"mappings":"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"}

package/dist/server/cache.js

@@ -0,0 +1,409 @@
+/**
+ * `@textjs/app/cache` — the data cache: `unstable_cache()` / `cache()` with
+ * tags and time-based revalidation, `revalidateTag()` / `revalidatePath()`,
+ * stale-while-revalidate semantics and a pluggable store (in-memory by default).
+ *
+ * State lives on `globalThis` so the CLI, the route-handler bundle and user
+ * code share one cache even when they load separate copies of this module.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+function sizeOf(value) {
+    if (typeof value === "string")
+        return value.length * 2;
+    try {
+        return (JSON.stringify(value)?.length ?? 0) * 2;
+    }
+    catch {
+        return 1024;
+    }
+}
+/** The default store: a per-process LRU map. */
+export class MemoryCacheStore {
+    #entries = new Map();
+    #tags = new Map();
+    #maxEntries;
+    #maxSize;
+    #maxTags;
+    #size = 0;
+    constructor(options = {}) {
+        this.#maxEntries = options.maxEntries ?? 1000;
+        this.#maxSize = options.maxSize ?? 50 * 1024 * 1024;
+        this.#maxTags = options.maxTags ?? 10_000;
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    get(key) {
+        const hit = this.#entries.get(key);
+        if (!hit)
+            return undefined;
+        this.#entries.delete(key);
+        this.#entries.set(key, hit);
+        return hit.entry;
+    }
+    set(key, entry) {
+        this.delete(key);
+        const size = sizeOf(entry.value);
+        if (size > this.#maxSize)
+            return;
+        this.#entries.set(key, { entry, size });
+        this.#size += size;
+        for (const [k, v] of this.#entries) {
+            if (this.#entries.size <= this.#maxEntries && this.#size <= this.#maxSize)
+                break;
+            this.#entries.delete(k);
+            this.#size -= v.size;
+        }
+    }
+    delete(key) {
+        const hit = this.#entries.get(key);
+        if (!hit)
+            return;
+        this.#entries.delete(key);
+        this.#size -= hit.size;
+    }
+    markTags(tags, mode, at) {
+        for (const tag of tags) {
+            const s = this.#tags.get(tag) ?? { expiredAt: 0, staleAt: 0 };
+            if (mode === "expire")
+                s.expiredAt = Math.max(s.expiredAt, at);
+            else
+                s.staleAt = Math.max(s.staleAt, at);
+            this.#tags.delete(tag);
+            this.#tags.set(tag, s);
+        }
+        // Forgetting the oldest revalidation is safe for entries written after it;
+        // drop the entries that may still predate it too.
+        for (const [tag, st] of this.#tags) {
+            if (this.#tags.size <= this.#maxTags)
+                break;
+            this.#tags.delete(tag);
+            for (const [key, hit] of this.#entries)
+                if (hit.entry.lastModified <= Math.max(st.expiredAt, st.staleAt) && hit.entry.tags.includes(tag))
+                    this.delete(key);
+        }
+    }
+    getTagState(tags) {
+        const out = { expiredAt: 0, staleAt: 0 };
+        for (const tag of tags) {
+            const s = this.#tags.get(tag);
+            if (!s)
+                continue;
+            out.expiredAt = Math.max(out.expiredAt, s.expiredAt);
+            out.staleAt = Math.max(out.staleAt, s.staleAt);
+        }
+        return out;
+    }
+    clear() {
+        this.#entries.clear();
+        this.#tags.clear();
+        this.#size = 0;
+    }
+}
+const STATE = Symbol.for("textjs.cache");
+function state() {
+    const g = globalThis;
+    let s = g[STATE];
+    if (!s) {
+        s = {
+            store: new MemoryCacheStore(),
+            inflight: new Map(),
+            generation: 0,
+            scope: new AsyncLocalStorage(),
+            clock: Date.now,
+            last: 0,
+            onError: (error, key) => console.error(`▼ Text.js: background revalidation failed for ${key}\n`, error),
+        };
+        g[STATE] = s;
+    }
+    return s;
+}
+/** Strictly increasing timestamps, so a revalidation in the same millisecond as a write still wins. */
+export function cacheNow() {
+    const s = state();
+    let t = Math.floor(s.clock());
+    if (t <= s.last)
+        t = s.last + 1;
+    s.last = t;
+    return t;
+}
+/** Replace the cache backend (`text.config.ts` → `cacheHandler` does this for you). */
+export function setCacheStore(store) {
+    const s = state();
+    s.store = store;
+    s.inflight.clear();
+}
+export function getCacheStore() {
+    return state().store;
+}
+/** @internal Test hooks: a fake clock, error sink, or a fresh in-memory store. */
+export function __configureCache(options) {
+    const s = state();
+    if (options.clock) {
+        s.clock = options.clock;
+        s.last = 0;
+    }
+    if (options.onError)
+        s.onError = options.onError;
+    if (options.reset) {
+        s.store = new MemoryCacheStore();
+        s.inflight.clear();
+        s.last = 0;
+    }
+}
+export function currentCacheScope() {
+    return state().scope.getStore();
+}
+export function runInCacheScope(scope, fn) {
+    return state().scope.run(scope, fn);
+}
+function track(scope, tags, revalidate) {
+    if (!scope)
+        return;
+    for (const t of tags)
+        scope.tags.add(t);
+    if (revalidate !== false && (scope.revalidate === false || revalidate < scope.revalidate))
+        scope.revalidate = revalidate;
+}
+// ---------------------------------------------------------------------------
+// Core: stale-while-revalidate lookup
+// ---------------------------------------------------------------------------
+/** Entries older than a year are regenerated in the foreground (Next.js `expireTime`). */
+export const EXPIRE_SECONDS = 31_536_000;
+export function classifyEntry(entry, tags, now) {
+    if (tags.expiredAt > entry.lastModified)
+        return "expired";
+    const age = now - entry.lastModified;
+    if (entry.revalidate !== false && age > EXPIRE_SECONDS * 1000)
+        return "expired";
+    if (tags.staleAt > entry.lastModified)
+        return "stale";
+    if (entry.revalidate !== false && age > entry.revalidate * 1000)
+        return "stale";
+    return "fresh";
+}
+async function compute(key, fn) {
+    const s = state();
+    const startedAt = cacheNow();
+    const result = await fn();
+    const entry = { value: result.value, lastModified: startedAt, revalidate: result.revalidate, tags: [...new Set(result.tags)] };
+    if (result.revalidate !== 0)
+        await s.store.set(key, entry);
+    return { entry, status: "MISS" };
+}
+function dedupe(key, fn) {
+    const s = state();
+    const running = s.inflight.get(key);
+    if (running && running.generation === s.generation)
+        return running.promise;
+    const generation = s.generation;
+    const p = compute(key, fn).finally(() => {
+        if (s.inflight.get(key)?.promise === p)
+            s.inflight.delete(key);
+    });
+    s.inflight.set(key, { generation, promise: p });
+    return p;
+}
+/**
+ * Read `key`, serving stale entries while one deduplicated background
+ * refresh runs (registered with `waitUntil` on serverless runtimes).
+ */
+export async function getOrCompute(key, fn, waitUntil) {
+    const s = state();
+    const entry = await s.store.get(key);
+    if (entry) {
+        const verdict = classifyEntry(entry, await s.store.getTagState(entry.tags), cacheNow());
+        if (verdict === "fresh")
+            return { entry, status: "HIT" };
+        if (verdict === "stale") {
+            if (s.inflight.get(key)?.generation !== s.generation) {
+                const refresh = dedupe(key, fn).catch((error) => {
+                    s.onError(error, key);
+                });
+                if (waitUntil)
+                    waitUntil(refresh);
+            }
+            return { entry, status: "STALE" };
+        }
+    }
+    return dedupe(key, fn);
+}
+function validateRevalidate(value, where) {
+    if (value === undefined || value === false)
+        return false;
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+        return value;
+    throw new TypeError(`Invalid revalidate value ${JSON.stringify(value)} in ${where}; must be a non-negative number or false.`);
+}
+function validateTags(tags, where) {
+    if (tags === undefined)
+        return [];
+    if (!Array.isArray(tags) || tags.some((t) => typeof t !== "string"))
+        throw new TypeError(`Invalid tags in ${where}; must be an array of strings.`);
+    return tags;
+}
+/** A collision-free cache key for arguments (`undefined` ≠ `null`, `Map` / `Set` / `Date` / `bigint` by value). */
+export function serializeCacheArgs(value, seen = new Set()) {
+    if (value === undefined)
+        return "u";
+    if (value === null)
+        return "n";
+    switch (typeof value) {
+        case "string":
+            return JSON.stringify(value);
+        case "number":
+            return Object.is(value, -0) ? "-0" : Number.isNaN(value) ? "NaN" : String(value);
+        case "boolean":
+            return value ? "t" : "f";
+        case "bigint":
+            return `${value}n`;
+        case "function":
+        case "symbol":
+            throw new TypeError(`unstable_cache arguments must be serializable; got a ${typeof value}.`);
+    }
+    const obj = value;
+    if (seen.has(obj))
+        throw new TypeError("unstable_cache arguments must not be circular.");
+    seen.add(obj);
+    try {
+        if (Array.isArray(obj))
+            return `[${obj.map((v) => serializeCacheArgs(v, seen)).join(",")}]`;
+        if (obj instanceof Date)
+            return `D${obj.getTime()}`;
+        if (obj instanceof URL)
+            return `L${JSON.stringify(obj.href)}`;
+        if (obj instanceof URLSearchParams)
+            return `Q${JSON.stringify(obj.toString())}`;
+        if (obj instanceof RegExp)
+            return `R${JSON.stringify(obj.toString())}`;
+        if (obj instanceof Map)
+            return `M[${[...obj].map(([k, v]) => `${serializeCacheArgs(k, seen)}:${serializeCacheArgs(v, seen)}`).sort().join(",")}]`;
+        if (obj instanceof Set)
+            return `S[${[...obj].map((v) => serializeCacheArgs(v, seen)).sort().join(",")}]`;
+        const keys = Object.keys(obj).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${serializeCacheArgs(obj[k], seen)}`).join(",")}}`;
+    }
+    finally {
+        seen.delete(obj);
+    }
+}
+/** `file:line:col` of the code that called `unstable_cache()` (stable across processes running one build). */
+function callSite() {
+    const frames = (new Error().stack ?? "").split("\n").map((l) => l.trim()).filter((l) => l.startsWith("at "));
+    // [callSite, unstable_cache, (cache), caller, …]
+    let i = 2;
+    if (frames[i]?.startsWith("at cache "))
+        i++;
+    return (frames[i] ?? "").replace(/^at\s+/, "");
+}
+const warnedKeys = new Map();
+function hashString(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36);
+}
+/**
+ * Cache the result of an async function (Next.js `unstable_cache`). Results
+ * are JSON-serialized, so every call returns a fresh copy. The cache key is
+ * `keyParts` (or the function source) plus the JSON-encoded arguments.
+ */
+export function unstable_cache(fn, keyParts, options = {}) {
+    const where = `unstable_cache(${keyParts?.join(", ") ?? fn.name ?? "anonymous"})`;
+    const revalidate = validateRevalidate(options.revalidate, where);
+    const tags = validateTags(options.tags, where);
+    let base;
+    if (keyParts && keyParts.length > 0)
+        base = keyParts.join("\u0000");
+    else {
+        base = `fn:${hashString(fn.toString())}:${hashString(callSite())}`;
+        // Closures created at one call site (in a loop, per request) share source and site: they'd share entries.
+        const prior = warnedKeys.get(base)?.deref();
+        if (prior && prior !== fn) {
+            console.warn(`▼ Text.js: unstable_cache(${fn.name || "anonymous"}) was created more than once from the same code without keyParts; the instances share cache entries. Pass keyParts that identify what the function closes over.`);
+        }
+        warnedKeys.set(base, new WeakRef(fn));
+    }
+    return async (...args) => {
+        const parent = currentCacheScope();
+        if (revalidate === 0) {
+            track(parent, tags, 0);
+            return fn(...args);
+        }
+        const key = `data:${base}:${serializeCacheArgs(args)}`;
+        const inherited = parent?.implicitTags ?? [];
+        const resolved = await getOrCompute(key, async () => {
+            const child = { tags: new Set([...tags, ...inherited]), revalidate, implicitTags: inherited, waitUntil: parent?.waitUntil };
+            const value = await runInCacheScope(child, () => fn(...args));
+            let json;
+            try {
+                json = value === undefined ? null : (JSON.stringify(value) ?? null);
+            }
+            catch (error) {
+                throw new TypeError(`${where} returned a value that can't be cached as JSON: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return { value: json, tags: [...child.tags], revalidate: child.revalidate };
+        }, parent?.waitUntil);
+        track(parent, resolved.entry.tags, resolved.entry.revalidate);
+        const json = resolved.entry.value;
+        return (json === null ? undefined : JSON.parse(json));
+    };
+}
+/** `unstable_cache` with an options object: `cache(fn, { key, tags, revalidate })`. */
+export function cache(fn, options = {}) {
+    const key = options.key === undefined ? undefined : Array.isArray(options.key) ? options.key : [options.key];
+    return unstable_cache(fn, key, options);
+}
+function after(promise) {
+    const scope = currentCacheScope();
+    const p = promise.catch((error) => state().onError(error, "revalidate"));
+    scope?.waitUntil?.(p);
+    return p;
+}
+/**
+ * Invalidate every entry tagged `tag`. By default the next request recomputes
+ * in the foreground; pass `"max"` to serve the stale value while it refreshes.
+ */
+export function revalidateTag(tag, profile) {
+    const tags = typeof tag === "string" ? [tag] : [...tag];
+    state().generation++;
+    return after(Promise.resolve(state().store.markTags(tags, profile === "max" ? "stale" : "expire", cacheNow())));
+}
+export function normalizeCachePath(path) {
+    let p = (path.startsWith("/") ? path : `/${path}`).split(/[?#]/)[0];
+    try {
+        p = decodeURIComponent(p);
+    }
+    catch {
+        // keep the raw path
+    }
+    return p.length > 1 ? p.replace(/\/+$/, "") || "/" : p;
+}
+/** Tags a route entry carries: `_P:<path>` for itself and `_L:<prefix>` for every enclosing segment. */
+export function implicitTags(pathname, pattern) {
+    const out = new Set();
+    for (const p of pattern && pattern !== pathname ? [pathname, pattern] : [pathname]) {
+        const path = normalizeCachePath(p);
+        out.add(`_P:${path}`);
+        out.add("_L:/");
+        let prefix = "";
+        for (const seg of path.split("/").filter(Boolean)) {
+            prefix += `/${seg}`;
+            out.add(`_L:${prefix}`);
+        }
+    }
+    return [...out];
+}
+/**
+ * Invalidate a cached path (`"page"`, the default) or everything below it
+ * (`"layout"`). Dynamic patterns work too: `revalidatePath("/api/posts/[id]")`.
+ */
+export function revalidatePath(path, type = "page") {
+    const p = normalizeCachePath(path);
+    state().generation++;
+    return after(Promise.resolve(state().store.markTags([type === "layout" ? `_L:${p}` : `_P:${p}`], "expire", cacheNow())));
+}
+export { validateRevalidate as __validateRevalidate };
+//# sourceMappingURL=cache.js.map