@farm.js/core 0.1.61 → 0.1.63

package/dist/cache.d.mts

@@ -0,0 +1,333 @@
+/**
+ * Cache key serialization, kept free of server imports: browser code such as
+ * the client data cache builds the same keys, and importing `./cache` would
+ * pull observability and OpenTelemetry into client bundles.
+ */
+type RouteDataCacheKey = string | readonly unknown[];
+declare function createRouteDataCacheKey(key: RouteDataCacheKey): string;
+declare function createFarmCacheKey(parts: readonly unknown[]): string;
+
+type FarmCacheInvalidationSource = "local" | "broadcast" | "live";
+declare function applyFarmCacheInvalidations(keys: unknown, source?: FarmCacheInvalidationSource): void;
+
+interface FarmCacheInvalidationStreamOptions {
+    /** Stop the stream when the owning request is aborted. */
+    signal?: AbortSignal;
+    /** Limit which invalidation keys this client may observe. */
+    filter?: (key: string) => boolean;
+    /** SSE heartbeat interval. Set to false to disable heartbeats. */
+    heartbeatIntervalMs?: number | false;
+    /** EventSource reconnect delay announced to the browser. */
+    retryMs?: number;
+}
+/**
+ * Create an app-owned SSE response that forwards this server instance's cache
+ * invalidations. Authenticate the request before calling this helper and use
+ * `filter` to keep tenant- or user-scoped keys private.
+ */
+declare function createFarmCacheInvalidationStream(options?: FarmCacheInvalidationStreamOptions): Response;
+
+type RevalidateTagProfile = "max" | "default" | "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | {
+    expire?: number;
+};
+interface FarmCacheOptions {
+    /**
+     * Tag cached data so it can be invalidated with revalidateTag/updateTag.
+     */
+    tags?: readonly string[];
+    /**
+     * Path tags let revalidatePath invalidate data tied to a route.
+     */
+    paths?: readonly string[];
+    /**
+     * Time in seconds before the entry becomes stale. False means no TTL.
+     */
+    revalidate?: number | false;
+}
+interface FarmCacheSetOptions extends FarmCacheOptions {
+    createdAt?: number;
+}
+type FarmCacheInvalidationTarget = {
+    key: RouteDataCacheKey;
+} | {
+    path: string;
+} | {
+    tag: string;
+};
+/**
+ * A regular Farm cache key carrying the data shape stored under that key.
+ *
+ * The brand exists only in TypeScript. At runtime the value remains the
+ * original string or structured array, so all existing cache APIs continue to
+ * accept untyped keys. `__farmDefinedCacheKeyData` is reserved for Farm's type
+ * system and must not be declared by application types.
+ */
+type DefinedCacheKey<TData, TKey extends RouteDataCacheKey = RouteDataCacheKey> = TKey & {
+    /** @internal Reserved type-only brand shared by the ESM and CommonJS declarations. */
+    readonly __farmDefinedCacheKeyData: TData;
+};
+type CacheKeyFactory<TData, TArguments extends readonly unknown[], TKey extends RouteDataCacheKey = RouteDataCacheKey> = (...args: TArguments) => DefinedCacheKey<TData, TKey>;
+type InferCacheKeyData<TKey> = TKey extends DefinedCacheKey<infer TData, RouteDataCacheKey> ? TData : unknown;
+/**
+ * Optionally add a data type to an existing string/array cache-key factory.
+ *
+ * This helper does not introduce a new runtime key representation. Calling the
+ * returned factory produces the exact key returned by `factory`.
+ */
+declare function defineCacheKey<TData>(): <const TArguments extends readonly unknown[], const TKey extends RouteDataCacheKey>(factory: (...args: TArguments) => TKey) => CacheKeyFactory<TData, TArguments, TKey>;
+interface FarmCacheEntry<T = unknown> {
+    key: string;
+    value: T;
+    tags: readonly string[];
+    /**
+     * Adapter tag versions captured before the cached value was produced.
+     * A later version makes the entry stale across every server instance.
+     */
+    tagVersions?: Readonly<Record<string, number>>;
+    createdAt: number;
+    createdVersion?: number;
+    revalidate?: number | false;
+    /**
+     * Epoch milliseconds after which no reader can use the entry, so shared
+     * storage may drop it. Set for entries with a finite `revalidate`, and for PPR shells
+     * stored through an adapter (see {@link PPR_SHELL_ADAPTER_TTL_SECONDS}).
+     * Adapters with native expiry (Redis PX, unstorage `ttl`) should honor it.
+     */
+    expiresAt?: number;
+}
+/**
+ * Asynchronous persistence contract used by distributed Farm caches.
+ *
+ * Implementations are responsible for serializing cache entries and making
+ * tag version updates atomic when the backing service supports it.
+ */
+interface FarmCacheAdapter {
+    readonly name?: string;
+    get<T = unknown>(key: string): Promise<FarmCacheEntry<T> | null | undefined>;
+    set<T = unknown>(key: string, entry: FarmCacheEntry<T>): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear?(): Promise<void>;
+    getTagVersions?(tags: readonly string[]): Promise<Readonly<Record<string, number>>>;
+    invalidateTags?(tags: readonly string[]): Promise<void>;
+    /** Atomically acquire a short-lived regeneration lease. */
+    acquireLease?(key: string, ttlMs: number): Promise<string | null | undefined>;
+    /** Release the lease only when the supplied ownership token still matches. */
+    releaseLease?(key: string, token: string): Promise<void>;
+}
+interface FarmClientCacheUserConfig {
+    /**
+     * Module path, relative to the project root, whose default export is a
+     * client cache adapter (`defineClientCacheAdapter`). The module is bundled
+     * into the browser entry; the server never imports it.
+     */
+    adapter?: string;
+    /** Extra version salt, typically a build or deploy id; entries persisted under another salt are dropped. */
+    version?: string;
+    /** Debounce for persisted write-behind flushes, in milliseconds. */
+    flushDelayMs?: number;
+}
+interface FarmCacheUserConfig {
+    /** Shared cache implementation, for example a Redis-backed adapter. */
+    adapter?: FarmCacheAdapter;
+    /** Prefix isolating applications and deployments sharing one adapter. */
+    namespace?: string;
+    /** Maximum process-local entries retained in memory. @default 1024 */
+    maxEntries?: number;
+    /** Browser cache persistence; see the client cache adapter documentation. */
+    client?: FarmClientCacheUserConfig;
+    /**
+     * Coordinate cache fills across processes when the adapter implements
+     * acquireLease/releaseLease. Set false to disable.
+     */
+    lease?: false | {
+        ttlMs?: number;
+        waitTimeoutMs?: number;
+        pollIntervalMs?: number;
+    };
+}
+interface FarmCacheStorage {
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    /** `options.ttl` is in seconds, matching unstorage drivers that support expiry. */
+    setItem<T = unknown>(key: string, value: T, options?: {
+        ttl?: number;
+    }): Promise<unknown>;
+    removeItem(key: string): Promise<unknown>;
+    clear?(base?: string): Promise<unknown>;
+}
+interface StorageFarmCacheAdapterOptions {
+    /** Prefix used inside the supplied storage client. */
+    base?: string;
+}
+/**
+ * Adapt a Farm/unstorage-compatible key-value client to the cache contract.
+ *
+ * This is a portable baseline adapter. Provider-specific adapters should use
+ * their atomic increment/transaction primitives for tag invalidation.
+ */
+declare function storageCacheAdapter(storage: FarmCacheStorage, options?: StorageFarmCacheAdapterOptions): FarmCacheAdapter;
+/**
+ * How long a PPR shell without `revalidate` stays in a shared cache adapter. Every query
+ * string variant stores its own shell, so without an expiry they would pile up forever.
+ */
+declare const PPR_SHELL_ADAPTER_TTL_SECONDS = 86400;
+interface GetFarmCacheEntryOptions {
+    allowStale?: boolean;
+    now?: number;
+}
+interface FarmCacheStaleEntry {
+    tags: Iterable<string>;
+    createdAt: number;
+    createdVersion?: number;
+    revalidate?: number | false;
+}
+declare class FarmDataCache {
+    private entries;
+    private inflight;
+    /** Local entries by tag, so tag counts and pruning never scan unrelated entries. */
+    private entriesByTag;
+    private invalidatedTagVersions;
+    private activeGenerations;
+    private version;
+    private generation;
+    private adapter?;
+    private namespace;
+    private local;
+    private maxEntries;
+    private config;
+    /** PPR shells, kept apart so query-string variants never evict app entries. */
+    private shells?;
+    private isShellCache;
+    private lease;
+    constructor(config?: FarmCacheUserConfig);
+    configure(config?: FarmCacheUserConfig): void;
+    /**
+     * Where PPR shells live: the same adapter and namespace, so path and tag invalidation
+     * reaches them, but their own in-memory LRU of `maxEntries`.
+     * @internal
+     */
+    get pprShellCache(): FarmDataCache;
+    get adapterName(): string;
+    get hasAdapter(): boolean;
+    get size(): number;
+    get<T>(key: string, options?: GetFarmCacheEntryOptions): T | undefined;
+    getEntry<T = unknown>(key: string, options?: GetFarmCacheEntryOptions): FarmCacheEntry<T> | undefined;
+    getEntryAsync<T = unknown>(key: string, options?: GetFarmCacheEntryOptions): Promise<FarmCacheEntry<T> | undefined>;
+    set<T>(key: string, value: T, options?: FarmCacheSetOptions): FarmCacheEntry<T>;
+    setAsync<T>(key: string, value: T, options?: FarmCacheSetOptions, tagVersions?: Readonly<Record<string, number>>): Promise<FarmCacheEntry<T>>;
+    private writeAsync;
+    delete(key: string): boolean;
+    deleteAsync(key: string): Promise<boolean>;
+    clear(): void;
+    private resetLocal;
+    clearAsync(): Promise<void>;
+    isStale(entry: FarmCacheStaleEntry, now?: number): boolean;
+    isStaleAsync(entry: FarmCacheEntry, now?: number): Promise<boolean>;
+    revalidateTag(tag: string, options?: {
+        source?: "revalidateTag" | "updateTag";
+        profile?: RevalidateTagProfile;
+    }): number;
+    revalidateTagAsync(tag: string, options?: {
+        source?: "revalidateTag" | "updateTag";
+        profile?: RevalidateTagProfile;
+    }): Promise<number>;
+    revalidatePath(routePath: string): number;
+    revalidatePathAsync(routePath: string): Promise<number>;
+    getOrSet<T>(key: string, producer: () => Promise<T> | T, options?: FarmCacheOptions): Promise<T>;
+    /** A fill that started before one of its tags was invalidated cannot satisfy later readers. */
+    private wasInvalidatedSince;
+    private fillCacheEntry;
+    private waitForAdapterEntry;
+    private countEntriesForTags;
+    private invalidateTag;
+    private toPublicEntry;
+    private hydrateLocalEntry;
+    private touchEntry;
+    private storeLocalEntry;
+    private deleteLocalEntry;
+    private detachLocalEntry;
+    /**
+     * Drop invalidation versions that no local entry or active fill can be stale against.
+     * Callers pass only the tags whose dependents just changed, so the cost is bounded by
+     * the entries sharing those tags rather than by the whole cache.
+     */
+    private pruneInvalidatedTagVersions;
+    private createAdapterKey;
+    private createAdapterTag;
+    private getAdapterTagVersions;
+    private isAdapterEntryStale;
+}
+declare function getFarmDataCache(): FarmDataCache;
+declare function configureFarmCache(config: FarmCacheUserConfig | undefined): void;
+/**
+ * Wrap an async function so its results are cached and shared across requests,
+ * processes, and restarts.
+ *
+ * The cache key is built from the wrapped function's identity (its name and a
+ * hash of its source), the active locale, `keyParts`, and the call arguments.
+ * Deriving identity from the source — rather than the closure instance — is
+ * deliberate: it keeps the key stable across processes and restarts so a
+ * distributed cache adapter can share entries between server instances.
+ *
+ * The consequence is that two closures with **identical source text but
+ * different captured variables** produce the same identity. Pass those captured
+ * values in `keyParts` so they take part in the key; otherwise the closures
+ * share a cache entry and return each other's data:
+ *
+ * ```ts
+ * // Collides: both closures have identical source, and `table` is captured,
+ * // not an argument, so it never reaches the key.
+ * const makeLoader = (table: string) =>
+ *   unstable_cache(async (id: number) => db.get(table, id));
+ *
+ * // Correct: the captured value disambiguates the two closures.
+ * const makeLoader = (table: string) =>
+ *   unstable_cache(async (id: number) => db.get(table, id), [table]);
+ * ```
+ *
+ * Values passed as call arguments already participate in the key and do not
+ * need to be repeated in `keyParts`.
+ *
+ * The result is shared by every request, so the function cannot read the
+ * request: `cookies()`, `headers()`, `getCspNonce()`, and `getCurrentRequest()`
+ * throw inside it. Read them outside and pass what you need as an argument.
+ *
+ * @param fn The async function to memoize.
+ * @param keyParts Extra values that identify this call site. Include every
+ *   variable the function closes over that is not one of its arguments.
+ * @param options Tags, paths, and revalidation settings for the cached entry.
+ */
+declare function unstable_cache<Args extends unknown[], Result>(fn: (...args: Args) => Result | Promise<Result>, keyParts?: readonly unknown[], options?: FarmCacheOptions): (...args: Args) => Promise<Result>;
+/**
+ * Invalidate every cache entry carrying `tag`.
+ *
+ * Observability note: the `count` on the emitted `cache.revalidateTag` event is
+ * derived from Farm's process-local entry tracking. With a shared `cache.adapter`
+ * configured, entries live in the adapter rather than in local memory, so the
+ * count can read as `0` even though the invalidation is still propagated to the
+ * adapter and applied. Treat it as a best-effort signal, not a distributed count.
+ */
+declare function revalidateTag(_tag: string, _profile?: RevalidateTagProfile): void | Promise<void>;
+declare function updateTag(tag: string): void | Promise<void>;
+/**
+ * Invalidate cached data for a route path (and its PPR shell, if any).
+ *
+ * Observability note: the `count` on the emitted `cache.revalidatePath` event and
+ * the `ppr.shell.invalidated` event are derived from process-local entry tracking.
+ * With a shared `cache.adapter`, PPR shells live in the adapter rather than in
+ * local memory, so the count can read as `0` and `ppr.shell.invalidated` may not
+ * be emitted even though the invalidation is still propagated to the adapter and
+ * applied.
+ */
+declare function revalidatePath(routePath: string): void | Promise<void>;
+declare function invalidate(key: RouteDataCacheKey): void | Promise<void>;
+declare function invalidateRouteData(key: RouteDataCacheKey): void | Promise<void>;
+/**
+ * Apply a normalized set of invalidation targets and return browser cache keys
+ * that should be carried with an action/endpoint response.
+ */
+declare function applyFarmCacheInvalidationTargets(targets: readonly FarmCacheInvalidationTarget[]): Promise<readonly string[]>;
+declare function createPathCacheTag(routePath: string): string;
+declare function createRouteDataCacheTag(key: RouteDataCacheKey): string;
+declare function normalizeRevalidatePath(routePath: string): string;
+
+export { type CacheKeyFactory, type DefinedCacheKey, type FarmCacheAdapter, type FarmCacheEntry, type FarmCacheInvalidationStreamOptions, type FarmCacheInvalidationTarget, type FarmCacheOptions, type FarmCacheSetOptions, type FarmCacheStorage, type FarmCacheUserConfig, type FarmClientCacheUserConfig, FarmDataCache, type GetFarmCacheEntryOptions, type InferCacheKeyData, PPR_SHELL_ADAPTER_TTL_SECONDS, type RevalidateTagProfile, type RouteDataCacheKey, type StorageFarmCacheAdapterOptions, applyFarmCacheInvalidationTargets, applyFarmCacheInvalidations, configureFarmCache, createFarmCacheInvalidationStream, createFarmCacheKey, createPathCacheTag, createRouteDataCacheKey, createRouteDataCacheTag, defineCacheKey, getFarmDataCache, invalidate, invalidateRouteData, normalizeRevalidatePath, revalidatePath, revalidateTag, storageCacheAdapter, unstable_cache, updateTag };

package/dist/cache.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Cache key serialization, kept free of server imports: browser code such as
+ * the client data cache builds the same keys, and importing `./cache` would
+ * pull observability and OpenTelemetry into client bundles.
+ */
+type RouteDataCacheKey = string | readonly unknown[];
+declare function createRouteDataCacheKey(key: RouteDataCacheKey): string;
+declare function createFarmCacheKey(parts: readonly unknown[]): string;
+
+type FarmCacheInvalidationSource = "local" | "broadcast" | "live";
+declare function applyFarmCacheInvalidations(keys: unknown, source?: FarmCacheInvalidationSource): void;
+
+interface FarmCacheInvalidationStreamOptions {
+    /** Stop the stream when the owning request is aborted. */
+    signal?: AbortSignal;
+    /** Limit which invalidation keys this client may observe. */
+    filter?: (key: string) => boolean;
+    /** SSE heartbeat interval. Set to false to disable heartbeats. */
+    heartbeatIntervalMs?: number | false;
+    /** EventSource reconnect delay announced to the browser. */
+    retryMs?: number;
+}
+/**
+ * Create an app-owned SSE response that forwards this server instance's cache
+ * invalidations. Authenticate the request before calling this helper and use
+ * `filter` to keep tenant- or user-scoped keys private.
+ */
+declare function createFarmCacheInvalidationStream(options?: FarmCacheInvalidationStreamOptions): Response;
+
+type RevalidateTagProfile = "max" | "default" | "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | {
+    expire?: number;
+};
+interface FarmCacheOptions {
+    /**
+     * Tag cached data so it can be invalidated with revalidateTag/updateTag.
+     */
+    tags?: readonly string[];
+    /**
+     * Path tags let revalidatePath invalidate data tied to a route.
+     */
+    paths?: readonly string[];
+    /**
+     * Time in seconds before the entry becomes stale. False means no TTL.
+     */
+    revalidate?: number | false;
+}
+interface FarmCacheSetOptions extends FarmCacheOptions {
+    createdAt?: number;
+}
+type FarmCacheInvalidationTarget = {
+    key: RouteDataCacheKey;
+} | {
+    path: string;
+} | {
+    tag: string;
+};
+/**
+ * A regular Farm cache key carrying the data shape stored under that key.
+ *
+ * The brand exists only in TypeScript. At runtime the value remains the
+ * original string or structured array, so all existing cache APIs continue to
+ * accept untyped keys. `__farmDefinedCacheKeyData` is reserved for Farm's type
+ * system and must not be declared by application types.
+ */
+type DefinedCacheKey<TData, TKey extends RouteDataCacheKey = RouteDataCacheKey> = TKey & {
+    /** @internal Reserved type-only brand shared by the ESM and CommonJS declarations. */
+    readonly __farmDefinedCacheKeyData: TData;
+};
+type CacheKeyFactory<TData, TArguments extends readonly unknown[], TKey extends RouteDataCacheKey = RouteDataCacheKey> = (...args: TArguments) => DefinedCacheKey<TData, TKey>;
+type InferCacheKeyData<TKey> = TKey extends DefinedCacheKey<infer TData, RouteDataCacheKey> ? TData : unknown;
+/**
+ * Optionally add a data type to an existing string/array cache-key factory.
+ *
+ * This helper does not introduce a new runtime key representation. Calling the
+ * returned factory produces the exact key returned by `factory`.
+ */
+declare function defineCacheKey<TData>(): <const TArguments extends readonly unknown[], const TKey extends RouteDataCacheKey>(factory: (...args: TArguments) => TKey) => CacheKeyFactory<TData, TArguments, TKey>;
+interface FarmCacheEntry<T = unknown> {
+    key: string;
+    value: T;
+    tags: readonly string[];
+    /**
+     * Adapter tag versions captured before the cached value was produced.
+     * A later version makes the entry stale across every server instance.
+     */
+    tagVersions?: Readonly<Record<string, number>>;
+    createdAt: number;
+    createdVersion?: number;
+    revalidate?: number | false;
+    /**
+     * Epoch milliseconds after which no reader can use the entry, so shared
+     * storage may drop it. Set for entries with a finite `revalidate`, and for PPR shells
+     * stored through an adapter (see {@link PPR_SHELL_ADAPTER_TTL_SECONDS}).
+     * Adapters with native expiry (Redis PX, unstorage `ttl`) should honor it.
+     */
+    expiresAt?: number;
+}
+/**
+ * Asynchronous persistence contract used by distributed Farm caches.
+ *
+ * Implementations are responsible for serializing cache entries and making
+ * tag version updates atomic when the backing service supports it.
+ */
+interface FarmCacheAdapter {
+    readonly name?: string;
+    get<T = unknown>(key: string): Promise<FarmCacheEntry<T> | null | undefined>;
+    set<T = unknown>(key: string, entry: FarmCacheEntry<T>): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear?(): Promise<void>;
+    getTagVersions?(tags: readonly string[]): Promise<Readonly<Record<string, number>>>;
+    invalidateTags?(tags: readonly string[]): Promise<void>;
+    /** Atomically acquire a short-lived regeneration lease. */
+    acquireLease?(key: string, ttlMs: number): Promise<string | null | undefined>;
+    /** Release the lease only when the supplied ownership token still matches. */
+    releaseLease?(key: string, token: string): Promise<void>;
+}
+interface FarmClientCacheUserConfig {
+    /**
+     * Module path, relative to the project root, whose default export is a
+     * client cache adapter (`defineClientCacheAdapter`). The module is bundled
+     * into the browser entry; the server never imports it.
+     */
+    adapter?: string;
+    /** Extra version salt, typically a build or deploy id; entries persisted under another salt are dropped. */
+    version?: string;
+    /** Debounce for persisted write-behind flushes, in milliseconds. */
+    flushDelayMs?: number;
+}
+interface FarmCacheUserConfig {
+    /** Shared cache implementation, for example a Redis-backed adapter. */
+    adapter?: FarmCacheAdapter;
+    /** Prefix isolating applications and deployments sharing one adapter. */
+    namespace?: string;
+    /** Maximum process-local entries retained in memory. @default 1024 */
+    maxEntries?: number;
+    /** Browser cache persistence; see the client cache adapter documentation. */
+    client?: FarmClientCacheUserConfig;
+    /**
+     * Coordinate cache fills across processes when the adapter implements
+     * acquireLease/releaseLease. Set false to disable.
+     */
+    lease?: false | {
+        ttlMs?: number;
+        waitTimeoutMs?: number;
+        pollIntervalMs?: number;
+    };
+}
+interface FarmCacheStorage {
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    /** `options.ttl` is in seconds, matching unstorage drivers that support expiry. */
+    setItem<T = unknown>(key: string, value: T, options?: {
+        ttl?: number;
+    }): Promise<unknown>;
+    removeItem(key: string): Promise<unknown>;
+    clear?(base?: string): Promise<unknown>;
+}
+interface StorageFarmCacheAdapterOptions {
+    /** Prefix used inside the supplied storage client. */
+    base?: string;
+}
+/**
+ * Adapt a Farm/unstorage-compatible key-value client to the cache contract.
+ *
+ * This is a portable baseline adapter. Provider-specific adapters should use
+ * their atomic increment/transaction primitives for tag invalidation.
+ */
+declare function storageCacheAdapter(storage: FarmCacheStorage, options?: StorageFarmCacheAdapterOptions): FarmCacheAdapter;
+/**
+ * How long a PPR shell without `revalidate` stays in a shared cache adapter. Every query
+ * string variant stores its own shell, so without an expiry they would pile up forever.
+ */
+declare const PPR_SHELL_ADAPTER_TTL_SECONDS = 86400;
+interface GetFarmCacheEntryOptions {
+    allowStale?: boolean;
+    now?: number;
+}
+interface FarmCacheStaleEntry {
+    tags: Iterable<string>;
+    createdAt: number;
+    createdVersion?: number;
+    revalidate?: number | false;
+}
+declare class FarmDataCache {
+    private entries;
+    private inflight;
+    /** Local entries by tag, so tag counts and pruning never scan unrelated entries. */
+    private entriesByTag;
+    private invalidatedTagVersions;
+    private activeGenerations;
+    private version;
+    private generation;
+    private adapter?;
+    private namespace;
+    private local;
+    private maxEntries;
+    private config;
+    /** PPR shells, kept apart so query-string variants never evict app entries. */
+    private shells?;
+    private isShellCache;
+    private lease;
+    constructor(config?: FarmCacheUserConfig);
+    configure(config?: FarmCacheUserConfig): void;
+    /**
+     * Where PPR shells live: the same adapter and namespace, so path and tag invalidation
+     * reaches them, but their own in-memory LRU of `maxEntries`.
+     * @internal
+     */
+    get pprShellCache(): FarmDataCache;
+    get adapterName(): string;
+    get hasAdapter(): boolean;
+    get size(): number;
+    get<T>(key: string, options?: GetFarmCacheEntryOptions): T | undefined;
+    getEntry<T = unknown>(key: string, options?: GetFarmCacheEntryOptions): FarmCacheEntry<T> | undefined;
+    getEntryAsync<T = unknown>(key: string, options?: GetFarmCacheEntryOptions): Promise<FarmCacheEntry<T> | undefined>;
+    set<T>(key: string, value: T, options?: FarmCacheSetOptions): FarmCacheEntry<T>;
+    setAsync<T>(key: string, value: T, options?: FarmCacheSetOptions, tagVersions?: Readonly<Record<string, number>>): Promise<FarmCacheEntry<T>>;
+    private writeAsync;
+    delete(key: string): boolean;
+    deleteAsync(key: string): Promise<boolean>;
+    clear(): void;
+    private resetLocal;
+    clearAsync(): Promise<void>;
+    isStale(entry: FarmCacheStaleEntry, now?: number): boolean;
+    isStaleAsync(entry: FarmCacheEntry, now?: number): Promise<boolean>;
+    revalidateTag(tag: string, options?: {
+        source?: "revalidateTag" | "updateTag";
+        profile?: RevalidateTagProfile;
+    }): number;
+    revalidateTagAsync(tag: string, options?: {
+        source?: "revalidateTag" | "updateTag";
+        profile?: RevalidateTagProfile;
+    }): Promise<number>;
+    revalidatePath(routePath: string): number;
+    revalidatePathAsync(routePath: string): Promise<number>;
+    getOrSet<T>(key: string, producer: () => Promise<T> | T, options?: FarmCacheOptions): Promise<T>;
+    /** A fill that started before one of its tags was invalidated cannot satisfy later readers. */
+    private wasInvalidatedSince;
+    private fillCacheEntry;
+    private waitForAdapterEntry;
+    private countEntriesForTags;
+    private invalidateTag;
+    private toPublicEntry;
+    private hydrateLocalEntry;
+    private touchEntry;
+    private storeLocalEntry;
+    private deleteLocalEntry;
+    private detachLocalEntry;
+    /**
+     * Drop invalidation versions that no local entry or active fill can be stale against.
+     * Callers pass only the tags whose dependents just changed, so the cost is bounded by
+     * the entries sharing those tags rather than by the whole cache.
+     */
+    private pruneInvalidatedTagVersions;
+    private createAdapterKey;
+    private createAdapterTag;
+    private getAdapterTagVersions;
+    private isAdapterEntryStale;
+}
+declare function getFarmDataCache(): FarmDataCache;
+declare function configureFarmCache(config: FarmCacheUserConfig | undefined): void;
+/**
+ * Wrap an async function so its results are cached and shared across requests,
+ * processes, and restarts.
+ *
+ * The cache key is built from the wrapped function's identity (its name and a
+ * hash of its source), the active locale, `keyParts`, and the call arguments.
+ * Deriving identity from the source — rather than the closure instance — is
+ * deliberate: it keeps the key stable across processes and restarts so a
+ * distributed cache adapter can share entries between server instances.
+ *
+ * The consequence is that two closures with **identical source text but
+ * different captured variables** produce the same identity. Pass those captured
+ * values in `keyParts` so they take part in the key; otherwise the closures
+ * share a cache entry and return each other's data:
+ *
+ * ```ts
+ * // Collides: both closures have identical source, and `table` is captured,
+ * // not an argument, so it never reaches the key.
+ * const makeLoader = (table: string) =>
+ *   unstable_cache(async (id: number) => db.get(table, id));
+ *
+ * // Correct: the captured value disambiguates the two closures.
+ * const makeLoader = (table: string) =>
+ *   unstable_cache(async (id: number) => db.get(table, id), [table]);
+ * ```
+ *
+ * Values passed as call arguments already participate in the key and do not
+ * need to be repeated in `keyParts`.
+ *
+ * The result is shared by every request, so the function cannot read the
+ * request: `cookies()`, `headers()`, `getCspNonce()`, and `getCurrentRequest()`
+ * throw inside it. Read them outside and pass what you need as an argument.
+ *
+ * @param fn The async function to memoize.
+ * @param keyParts Extra values that identify this call site. Include every
+ *   variable the function closes over that is not one of its arguments.
+ * @param options Tags, paths, and revalidation settings for the cached entry.
+ */
+declare function unstable_cache<Args extends unknown[], Result>(fn: (...args: Args) => Result | Promise<Result>, keyParts?: readonly unknown[], options?: FarmCacheOptions): (...args: Args) => Promise<Result>;
+/**
+ * Invalidate every cache entry carrying `tag`.
+ *
+ * Observability note: the `count` on the emitted `cache.revalidateTag` event is
+ * derived from Farm's process-local entry tracking. With a shared `cache.adapter`
+ * configured, entries live in the adapter rather than in local memory, so the
+ * count can read as `0` even though the invalidation is still propagated to the
+ * adapter and applied. Treat it as a best-effort signal, not a distributed count.
+ */
+declare function revalidateTag(_tag: string, _profile?: RevalidateTagProfile): void | Promise<void>;
+declare function updateTag(tag: string): void | Promise<void>;
+/**
+ * Invalidate cached data for a route path (and its PPR shell, if any).
+ *
+ * Observability note: the `count` on the emitted `cache.revalidatePath` event and
+ * the `ppr.shell.invalidated` event are derived from process-local entry tracking.
+ * With a shared `cache.adapter`, PPR shells live in the adapter rather than in
+ * local memory, so the count can read as `0` and `ppr.shell.invalidated` may not
+ * be emitted even though the invalidation is still propagated to the adapter and
+ * applied.
+ */
+declare function revalidatePath(routePath: string): void | Promise<void>;
+declare function invalidate(key: RouteDataCacheKey): void | Promise<void>;
+declare function invalidateRouteData(key: RouteDataCacheKey): void | Promise<void>;
+/**
+ * Apply a normalized set of invalidation targets and return browser cache keys
+ * that should be carried with an action/endpoint response.
+ */
+declare function applyFarmCacheInvalidationTargets(targets: readonly FarmCacheInvalidationTarget[]): Promise<readonly string[]>;
+declare function createPathCacheTag(routePath: string): string;
+declare function createRouteDataCacheTag(key: RouteDataCacheKey): string;
+declare function normalizeRevalidatePath(routePath: string): string;
+
+export { type CacheKeyFactory, type DefinedCacheKey, type FarmCacheAdapter, type FarmCacheEntry, type FarmCacheInvalidationStreamOptions, type FarmCacheInvalidationTarget, type FarmCacheOptions, type FarmCacheSetOptions, type FarmCacheStorage, type FarmCacheUserConfig, type FarmClientCacheUserConfig, FarmDataCache, type GetFarmCacheEntryOptions, type InferCacheKeyData, PPR_SHELL_ADAPTER_TTL_SECONDS, type RevalidateTagProfile, type RouteDataCacheKey, type StorageFarmCacheAdapterOptions, applyFarmCacheInvalidationTargets, applyFarmCacheInvalidations, configureFarmCache, createFarmCacheInvalidationStream, createFarmCacheKey, createPathCacheTag, createRouteDataCacheKey, createRouteDataCacheTag, defineCacheKey, getFarmDataCache, invalidate, invalidateRouteData, normalizeRevalidatePath, revalidatePath, revalidateTag, storageCacheAdapter, unstable_cache, updateTag };