@farm.js/core 0.1.51-beta.3 → 0.1.61

package/dist/cache.d.mts

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

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