import * as Deferred from "./Deferred.ts"; import * as Duration from "./Duration.ts"; import type * as Effect from "./Effect.ts"; import * as Exit from "./Exit.ts"; import * as Fiber from "./Fiber.ts"; import * as MutableHashMap from "./MutableHashMap.ts"; import * as Option from "./Option.ts"; import type { Pipeable } from "./Pipeable.ts"; import * as Predicate from "./Predicate.ts"; import * as Scope from "./Scope.ts"; declare const TypeId = "~effect/ScopedCache"; /** * A scoped cache whose values are acquired by a lookup effect and stored in * per-entry scopes. * * **When to use** * * Use to cache values that acquire scoped resources and must release those * resources when entries are removed or the owning scope closes. * * **Details** * * Concurrent requests for the same key share the same in-flight lookup. * Entries can expire based on the lookup exit, are evicted when capacity is * exceeded, and release their entry scopes when invalidated, evicted, or when * the cache's owning scope closes. Expired entries are cleaned up lazily on * access to that key or a `keys`/`values`/`entries` scan, never in the background. * * @see {@link make} for creating a scoped cache with a fixed time-to-live * @see {@link makeWith} for creating a scoped cache with dynamic time-to-live * * @stability stable * @category models * @since 2.0.0 */ export interface ScopedCache extends Pipeable { readonly [TypeId]: typeof TypeId; state: State; readonly capacity: number; readonly lookup: (key: Key) => Effect.Effect; readonly timeToLive: (exit: Exit.Exit, key: Key) => Duration.Duration; } /** * Represents whether a `ScopedCache` is open or closed. * * **When to use** * * Use when inspecting the low-level lifecycle state of a scoped cache. * * **Details** * * `Open` stores cached entries in access order for reuse and eviction. * `Closed` means the owning scope has closed and the cache can no longer * perform lookup operations. * * @stability stable * @category models * @since 4.0.0 */ export type State = { readonly _tag: "Open"; readonly map: MutableHashMap.MutableHashMap>; } | { readonly _tag: "Closed"; }; /** * A single scoped cache entry. * * **When to use** * * Use when inspecting the open state of a `ScopedCache` and you need the stored * deferred result, entry scope, or expiration timestamp for a key. * * **Details** * * The entry contains the deferred lookup result shared by readers, the scope * that owns resources acquired while computing the value, and an optional * expiration time in milliseconds. Removing the entry closes its scope. * * @see {@link State} for the open/closed cache state that stores entries by key * * @stability stable * @category models * @since 4.0.0 */ export interface Entry { expiresAt: number | undefined; readonly deferred: Deferred.Deferred; readonly scope: Scope.Closeable; awaiters: number; fiber?: Fiber.Fiber; } /** * Creates a `ScopedCache` from a lookup function, maximum capacity, and a * time-to-live function computed from each lookup exit and key. * * **When to use** * * Use when you need a scoped cache whose entry lifetime depends on each lookup * result or key. * * **Details** * * The cache must be constructed in a `Scope`. Each lookup runs in its own entry * scope, and that scope is closed when the entry is invalidated, is evicted by * capacity, or when the cache's owning scope closes. Expired entries are cleaned * up on access to that key or a `keys`/`values`/`entries` scan, not in the background. * `requireServicesAt` controls whether lookup services are captured at * construction time or required when lookup operations run. * * @see {@link make} for creating a scoped cache with one fixed time-to-live * * @stability stable * @category constructors * @since 2.0.0 */ export declare const makeWith: (options: { readonly lookup: (key: Key) => Effect.Effect; readonly capacity: number; readonly timeToLive?: ((exit: Exit.Exit, key: Key) => Duration.Input) | undefined; readonly requireServicesAt?: ServiceMode | undefined; }) => Effect.Effect : never>, never, ("lookup" extends ServiceMode ? never : R) | Scope.Scope>; /** * Creates a `ScopedCache` with a fixed time-to-live for every lookup result. * * **When to use** * * Use to create a scoped cache when every cached lookup result should share the * same lifetime. * * **Details** * * This is the constant-TTL variant of `makeWith`: values are acquired by the * lookup effect in per-entry scopes, capacity can evict older entries, and * entry scopes are closed when entries are invalidated, are evicted, or when * the cache's owning scope closes. Expiry cleanup is lazy: expired entries close * on access to that key or a `keys`/`values`/`entries` scan, not in the background. * * @see {@link makeWith} for computing time-to-live from each lookup result and key * * @stability stable * @category constructors * @since 2.0.0 */ export declare const make: (options: { readonly lookup: (key: Key) => Effect.Effect; readonly capacity: number; readonly timeToLive?: Duration.Input | undefined; readonly requireServicesAt?: ServiceMode | undefined; }) => Effect.Effect : never>, never, ("lookup" extends ServiceMode ? never : R) | Scope.Scope>; /** * Gets the value for a key, running the cache lookup when no unexpired entry is * present. * * **When to use** * * Use to retrieve a scoped cached value by key when a missing or expired entry * should run the cache lookup and share the in-flight lookup with concurrent * callers. * * **Details** * * Concurrent `get` calls for the same key share the same in-flight lookup. * Successful and failed lookup exits are cached according to the configured * TTL. If the cache is closed, the effect is interrupted. * * @see {@link getOption} for reading only when an unexpired entry is already cached * @see {@link getSuccess} for inspecting an already-completed successful entry * @see {@link refresh} for forcing a new lookup * * @stability stable * @category combinators * @since 4.0.0 */ export declare const get: { /** * Gets the value for a key, running the cache lookup when no unexpired entry is * present. * * **When to use** * * Use to retrieve a scoped cached value by key when a missing or expired entry * should run the cache lookup and share the in-flight lookup with concurrent * callers. * * **Details** * * Concurrent `get` calls for the same key share the same in-flight lookup. * Successful and failed lookup exits are cached according to the configured * TTL. If the cache is closed, the effect is interrupted. * * @see {@link getOption} for reading only when an unexpired entry is already cached * @see {@link getSuccess} for inspecting an already-completed successful entry * @see {@link refresh} for forcing a new lookup * * @stability stable * @category combinators * @since 4.0.0 */ (key: Key): (self: ScopedCache) => Effect.Effect; /** * Gets the value for a key, running the cache lookup when no unexpired entry is * present. * * **When to use** * * Use to retrieve a scoped cached value by key when a missing or expired entry * should run the cache lookup and share the in-flight lookup with concurrent * callers. * * **Details** * * Concurrent `get` calls for the same key share the same in-flight lookup. * Successful and failed lookup exits are cached according to the configured * TTL. If the cache is closed, the effect is interrupted. * * @see {@link getOption} for reading only when an unexpired entry is already cached * @see {@link getSuccess} for inspecting an already-completed successful entry * @see {@link refresh} for forcing a new lookup * * @stability stable * @category combinators * @since 4.0.0 */ (self: ScopedCache, key: Key): Effect.Effect; }; /** * Reads an existing unexpired cache entry without running the lookup function. * * **When to use** * * Use to read a scoped value only when it is already cached, without starting * the lookup for missing or expired keys. * * **Details** * * Returns `Option.none` when the key is absent or expired. If an entry exists, * the effect waits for its cached result and returns `Option.some(value)` on * success, or fails with the cached lookup error. * * @see {@link get} for running the lookup on missing or expired keys * @see {@link getSuccess} for inspecting only already-completed successful entries * * @stability stable * @category combinators * @since 4.0.0 */ export declare const getOption: { /** * Reads an existing unexpired cache entry without running the lookup function. * * **When to use** * * Use to read a scoped value only when it is already cached, without starting * the lookup for missing or expired keys. * * **Details** * * Returns `Option.none` when the key is absent or expired. If an entry exists, * the effect waits for its cached result and returns `Option.some(value)` on * success, or fails with the cached lookup error. * * @see {@link get} for running the lookup on missing or expired keys * @see {@link getSuccess} for inspecting only already-completed successful entries * * @stability stable * @category combinators * @since 4.0.0 */ (key: Key): (self: ScopedCache) => Effect.Effect, E>; /** * Reads an existing unexpired cache entry without running the lookup function. * * **When to use** * * Use to read a scoped value only when it is already cached, without starting * the lookup for missing or expired keys. * * **Details** * * Returns `Option.none` when the key is absent or expired. If an entry exists, * the effect waits for its cached result and returns `Option.some(value)` on * success, or fails with the cached lookup error. * * @see {@link get} for running the lookup on missing or expired keys * @see {@link getSuccess} for inspecting only already-completed successful entries * * @stability stable * @category combinators * @since 4.0.0 */ (self: ScopedCache, key: Key): Effect.Effect, E>; }; /** * Retrieves the value associated with the specified key from the cache, only if * it contains a resolved successful value. * * **When to use** * * Use to inspect an already-completed successful scoped cache entry without * running or awaiting the lookup effect. * * **Details** * * Returns `Option.some` for a resolved successful entry. Returns `Option.none` * for missing, expired, failed, or still-pending entries. * * @see {@link get} for awaiting or starting the lookup effect * @see {@link getOption} for awaiting an already-cached entry without starting a lookup * * @stability stable * @category combinators * @since 4.0.0 */ export declare const getSuccess: { /** * Retrieves the value associated with the specified key from the cache, only if * it contains a resolved successful value. * * **When to use** * * Use to inspect an already-completed successful scoped cache entry without * running or awaiting the lookup effect. * * **Details** * * Returns `Option.some` for a resolved successful entry. Returns `Option.none` * for missing, expired, failed, or still-pending entries. * * @see {@link get} for awaiting or starting the lookup effect * @see {@link getOption} for awaiting an already-cached entry without starting a lookup * * @stability stable * @category combinators * @since 4.0.0 */ (key: Key): (self: ScopedCache) => Effect.Effect>; /** * Retrieves the value associated with the specified key from the cache, only if * it contains a resolved successful value. * * **When to use** * * Use to inspect an already-completed successful scoped cache entry without * running or awaiting the lookup effect. * * **Details** * * Returns `Option.some` for a resolved successful entry. Returns `Option.none` * for missing, expired, failed, or still-pending entries. * * @see {@link get} for awaiting or starting the lookup effect * @see {@link getOption} for awaiting an already-cached entry without starting a lookup * * @stability stable * @category combinators * @since 4.0.0 */ (self: ScopedCache, key: Key): Effect.Effect>; }; /** * Sets a successful value for a key without running the lookup function. * * **When to use** * * Use to seed or overwrite a scoped cache entry with an already available * successful value. * * **Details** * * This replaces and closes any existing entry scope for the key, applies the * cache's TTL using a successful exit for the value, and may evict older * entries if the cache capacity is exceeded. * * @see {@link get} for reading or computing a cached value * @see {@link refresh} for replacing an entry by running the lookup function * * @stability stable * @category combinators * @since 4.0.0 */ export declare const set: { /** * Sets a successful value for a key without running the lookup function. * * **When to use** * * Use to seed or overwrite a scoped cache entry with an already available * successful value. * * **Details** * * This replaces and closes any existing entry scope for the key, applies the * cache's TTL using a successful exit for the value, and may evict older * entries if the cache capacity is exceeded. * * @see {@link get} for reading or computing a cached value * @see {@link refresh} for replacing an entry by running the lookup function * * @stability stable * @category combinators * @since 4.0.0 */ (key: Key, value: A): (self: ScopedCache) => Effect.Effect; /** * Sets a successful value for a key without running the lookup function. * * **When to use** * * Use to seed or overwrite a scoped cache entry with an already available * successful value. * * **Details** * * This replaces and closes any existing entry scope for the key, applies the * cache's TTL using a successful exit for the value, and may evict older * entries if the cache capacity is exceeded. * * @see {@link get} for reading or computing a cached value * @see {@link refresh} for replacing an entry by running the lookup function * * @stability stable * @category combinators * @since 4.0.0 */ (self: ScopedCache, key: Key, value: A): Effect.Effect; }; /** * Checks whether the cache contains an entry for the specified key. * * **When to use** * * Use to test whether an unexpired entry exists for a key without running the * cache lookup. * * **Details** * * This does not start lookups and does not refresh access order. Expired * entries are treated as absent and their scopes are closed while checking. If * the cache is closed, the effect is interrupted. * * @see {@link getOption} for reading an existing cached entry * @see {@link get} for running the lookup on missing or expired keys * * @stability stable * @category combinators * @since 4.0.0 */ export declare const has: { /** * Checks whether the cache contains an entry for the specified key. * * **When to use** * * Use to test whether an unexpired entry exists for a key without running the * cache lookup. * * **Details** * * This does not start lookups and does not refresh access order. Expired * entries are treated as absent and their scopes are closed while checking. If * the cache is closed, the effect is interrupted. * * @see {@link getOption} for reading an existing cached entry * @see {@link get} for running the lookup on missing or expired keys * * @stability stable * @category combinators * @since 4.0.0 */ (key: Key): (self: ScopedCache) => Effect.Effect; /** * Checks whether the cache contains an entry for the specified key. * * **When to use** * * Use to test whether an unexpired entry exists for a key without running the * cache lookup. * * **Details** * * This does not start lookups and does not refresh access order. Expired * entries are treated as absent and their scopes are closed while checking. If * the cache is closed, the effect is interrupted. * * @see {@link getOption} for reading an existing cached entry * @see {@link get} for running the lookup on missing or expired keys * * @stability stable * @category combinators * @since 4.0.0 */ (self: ScopedCache, key: Key): Effect.Effect; }; /** * Removes the entry associated with a key and closes its entry scope. * * **When to use** * * Use to remove a single key from a scoped cache and release any resources owned * by that entry before a later lookup computes it again. * * **Details** * * If the key is absent, this is a no-op. * * **Gotchas** * * If the cache is closed, the effect is interrupted. * * @see {@link refresh} for replacing a key by running a new lookup immediately * @see {@link invalidateWhen} for invalidating only when a cached value matches a predicate * @see {@link invalidateAll} for removing every cached entry * * @stability stable * @category combinators * @since 4.0.0 */ export declare const invalidate: { /** * Removes the entry associated with a key and closes its entry scope. * * **When to use** * * Use to remove a single key from a scoped cache and release any resources owned * by that entry before a later lookup computes it again. * * **Details** * * If the key is absent, this is a no-op. * * **Gotchas** * * If the cache is closed, the effect is interrupted. * * @see {@link refresh} for replacing a key by running a new lookup immediately * @see {@link invalidateWhen} for invalidating only when a cached value matches a predicate * @see {@link invalidateAll} for removing every cached entry * * @stability stable * @category combinators * @since 4.0.0 */ (key: Key): (self: ScopedCache) => Effect.Effect; /** * Removes the entry associated with a key and closes its entry scope. * * **When to use** * * Use to remove a single key from a scoped cache and release any resources owned * by that entry before a later lookup computes it again. * * **Details** * * If the key is absent, this is a no-op. * * **Gotchas** * * If the cache is closed, the effect is interrupted. * * @see {@link refresh} for replacing a key by running a new lookup immediately * @see {@link invalidateWhen} for invalidating only when a cached value matches a predicate * @see {@link invalidateAll} for removing every cached entry * * @stability stable * @category combinators * @since 4.0.0 */ (self: ScopedCache, key: Key): Effect.Effect; }; /** * Invalidates the entry associated with the specified key in the cache when the * predicate returns true for the cached value. * * **When to use** * * Use to remove an already-cached scoped value only when the successful cached * value satisfies a predicate. * * **Details** * * Returns `true` only when a successful cached value matches and is removed. It * returns `false` for absent, expired, failed, or non-matching entries. * * **Gotchas** * * A matching invalidation closes the entry scope and releases its resources. * * @see {@link invalidate} for unconditional removal by key * * @stability stable * @category combinators * @since 4.0.0 */ export declare const invalidateWhen: { /** * Invalidates the entry associated with the specified key in the cache when the * predicate returns true for the cached value. * * **When to use** * * Use to remove an already-cached scoped value only when the successful cached * value satisfies a predicate. * * **Details** * * Returns `true` only when a successful cached value matches and is removed. It * returns `false` for absent, expired, failed, or non-matching entries. * * **Gotchas** * * A matching invalidation closes the entry scope and releases its resources. * * @see {@link invalidate} for unconditional removal by key * * @stability stable * @category combinators * @since 4.0.0 */ (key: Key, f: Predicate.Predicate): (self: ScopedCache) => Effect.Effect; /** * Invalidates the entry associated with the specified key in the cache when the * predicate returns true for the cached value. * * **When to use** * * Use to remove an already-cached scoped value only when the successful cached * value satisfies a predicate. * * **Details** * * Returns `true` only when a successful cached value matches and is removed. It * returns `false` for absent, expired, failed, or non-matching entries. * * **Gotchas** * * A matching invalidation closes the entry scope and releases its resources. * * @see {@link invalidate} for unconditional removal by key * * @stability stable * @category combinators * @since 4.0.0 */ (self: ScopedCache, key: Key, f: Predicate.Predicate): Effect.Effect; }; /** * Forces a refresh of the value associated with the specified key in the cache. * * **When to use** * * Use to recompute a scoped cache entry immediately, even when an unexpired * value is already cached. * * **Details** * * It will always invoke the lookup function to construct a new value, * overwriting any existing value for that key. * * @see {@link get} for reusing an unexpired entry before running the lookup * @see {@link invalidate} for removing an entry without recomputing it * * @stability stable * @category combinators * @since 4.0.0 */ export declare const refresh: { /** * Forces a refresh of the value associated with the specified key in the cache. * * **When to use** * * Use to recompute a scoped cache entry immediately, even when an unexpired * value is already cached. * * **Details** * * It will always invoke the lookup function to construct a new value, * overwriting any existing value for that key. * * @see {@link get} for reusing an unexpired entry before running the lookup * @see {@link invalidate} for removing an entry without recomputing it * * @stability stable * @category combinators * @since 4.0.0 */ (key: Key): (self: ScopedCache) => Effect.Effect; /** * Forces a refresh of the value associated with the specified key in the cache. * * **When to use** * * Use to recompute a scoped cache entry immediately, even when an unexpired * value is already cached. * * **Details** * * It will always invoke the lookup function to construct a new value, * overwriting any existing value for that key. * * @see {@link get} for reusing an unexpired entry before running the lookup * @see {@link invalidate} for removing an entry without recomputing it * * @stability stable * @category combinators * @since 4.0.0 */ (self: ScopedCache, key: Key): Effect.Effect; }; /** * Removes every entry from the cache and closes each entry scope. * * **When to use** * * Use to clear a scoped cache and release resources owned by all cached entries. * * **Details** * * If the cache is closed, the effect is interrupted. * * @see {@link invalidate} for removing one cached entry * * @stability stable * @category combinators * @since 4.0.0 */ export declare const invalidateAll: (self: ScopedCache) => Effect.Effect; /** * Retrieves the approximate number of entries in the cache. * * **When to use** * * Use to inspect how many entries are currently stored in the scoped cache. * * **Gotchas** * * Note that expired entries are counted until they are accessed and removed. * The size reflects the current number of entries stored, not the number * of valid entries. * * @stability stable * @category combinators * @since 4.0.0 */ export declare const size: (self: ScopedCache) => Effect.Effect; /** * Retrieves all active keys from the cache, automatically filtering out expired entries. * * **When to use** * * Use to inspect currently cached unexpired keys without running cache lookups. * * **Gotchas** * * Expired entries are removed and their scopes are closed while filtering. * * @see {@link entries} for retrieving successful cached key-value pairs * @see {@link values} for retrieving only successfully cached values * * @stability stable * @category combinators * @since 4.0.0 */ export declare const keys: (self: ScopedCache) => Effect.Effect>; /** * Retrieves all successfully cached values from the cache, excluding failed * lookups and expired entries. * * **When to use** * * Use to inspect currently successful cached values without running cache * lookups. * * **Gotchas** * * Expired entries are removed and their scopes are closed while filtering. * * @see {@link entries} for retrieving successful cached key-value pairs * @see {@link keys} for retrieving only cached keys * * @stability stable * @category combinators * @since 4.0.0 */ export declare const values: (self: ScopedCache) => Effect.Effect>; /** * Retrieves all key-value pairs from the cache as an array. This function * only returns entries with successfully resolved values, filtering out any * failed lookups or expired entries. * * **When to use** * * Use to inspect the currently successful cached key-value pairs without * running cache lookups. * * **Gotchas** * * Expired entries are removed and their scopes are closed while filtering. * * @see {@link keys} for retrieving only cached keys * @see {@link values} for retrieving only cached values * * @stability stable * @category combinators * @since 4.0.0 */ export declare const entries: (self: ScopedCache) => Effect.Effect>; export {}; //# sourceMappingURL=ScopedCache.d.ts.map