effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/ScopedCache.ts

@@ -1,4 +1,28 @@
 /**
+ * The `ScopedCache` module provides a cache for values that acquire scoped
+ * resources during lookup. Each cached entry owns a `Scope`, so resources
+ * created while computing a value stay alive for as long as that entry remains
+ * cached and are released when the entry is removed.
+ *
+ * A `ScopedCache` is itself created inside a scope. Calls to {@link get} run the
+ * lookup effect on cache misses, share the same in-flight lookup among
+ * concurrent callers for the same key, and store the resulting exit according
+ * to a time-to-live policy. Entries can be inserted manually with {@link set},
+ * refreshed with {@link refresh}, inspected without triggering lookup with
+ * {@link getOption}, and removed with {@link invalidate} or
+ * {@link invalidateAll}. Capacity limits evict the oldest entries.
+ *
+ * **Lifecycle notes**
+ *
+ * - Entry scopes are closed when entries expire, are invalidated, are evicted,
+ *   are replaced, or when the cache's owning scope closes
+ * - Successful and failed lookup exits are both cached according to the
+ *   configured TTL
+ * - Expired entries may remain counted by {@link size} until a cache operation
+ *   observes and removes them
+ * - Once the owning scope closes, the cache is closed and lookup-style
+ *   operations interrupt instead of acquiring new values
+ *
  * @since 4.0.0
  */
 import * as Arr from "./Array.ts"
@@ -21,8 +45,16 @@ import * as Scope from "./Scope.ts"
 const TypeId = "~effect/ScopedCache"
 
 /**
- * @since 4.0.0
+ * A scoped cache whose values are acquired by a lookup effect and stored in
+ * per-entry scopes.
+ *
+ * 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, expired,
+ * or when the cache's owning scope closes.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface ScopedCache<in out Key, in out A, in out E = never, out R = never> extends Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -33,8 +65,14 @@ export interface ScopedCache<in out Key, in out A, in out E = never, out R = nev
 }
 
 /**
- * @since 4.0.0
+ * Represents whether a `ScopedCache` is open or closed.
+ *
+ * `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.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export type State<K, A, E> = {
   readonly _tag: "Open"
@@ -44,11 +82,14 @@ export type State<K, A, E> = {
 }
 
 /**
- * Represents a cache entry containing a deferred value and optional expiration time.
- * This is used internally by the cache implementation to track cached values and their lifetimes.
+ * A single scoped cache entry.
+ *
+ * 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.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface Entry<A, E> {
   expiresAt: number | undefined
@@ -57,8 +98,17 @@ export interface Entry<A, E> {
 }
 
 /**
- * @since 4.0.0
+ * Creates a `ScopedCache` from a lookup function, maximum capacity, and a
+ * time-to-live function computed from each lookup exit and key.
+ *
+ * The cache must be constructed in a `Scope`. Each lookup runs in its own entry
+ * scope, and that scope is closed when the entry expires, is invalidated, is
+ * evicted by capacity, or when the cache's owning scope closes.
+ * `requireServicesAt` controls whether lookup services are captured at
+ * construction time or required when lookup operations run.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const makeWith = <
   Key,
@@ -103,8 +153,15 @@ export const makeWith = <
   })
 
 /**
- * @since 4.0.0
+ * Creates a `ScopedCache` with a fixed time-to-live for every lookup result.
+ *
+ * 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 expire, are invalidated, are evicted, or
+ * when the cache's owning scope closes.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = <
   Key,
@@ -144,18 +201,39 @@ const Proto = {
 const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Duration => Duration.infinity
 
 /**
- * @since 4.0.0
+ * Gets the value for a key, running the cache lookup when no unexpired entry is
+ * present.
+ *
+ * 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.
+ *
  * @category Combinators
+ * @since 4.0.0
  */
 export const get: {
   /**
-   * @since 4.0.0
+   * Gets the value for a key, running the cache lookup when no unexpired entry is
+   * present.
+   *
+   * 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.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key): <E, R>(self: ScopedCache<Key, A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * @since 4.0.0
+   * Gets the value for a key, running the cache lookup when no unexpired entry is
+   * present.
+   *
+   * 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.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: ScopedCache<Key, A, E, R>, key: Key): Effect.Effect<A, E, R>
 } = dual(
@@ -176,12 +254,26 @@ export const get: {
         }
         const scope = Scope.makeUnsafe()
         const deferred = Deferred.makeUnsafe</**
-         * @since 4.0.0
+         * Gets the value for a key, running the cache lookup when no unexpired entry is
+         * present.
+         *
+         * 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.
+         *
          * @category Combinators
+         * @since 4.0.0
          */
         A, /**
-         * @since 4.0.0
+         * Gets the value for a key, running the cache lookup when no unexpired entry is
+         * present.
+         *
+         * 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.
+         *
          * @category Combinators
+         * @since 4.0.0
          */
         E>()
         const entry: Entry<A, E> = {
@@ -233,18 +325,36 @@ const checkCapacity = <K, A, E>(
 }
 
 /**
- * @since 4.0.0
+ * Reads an existing unexpired cache entry without running the lookup function.
+ *
+ * 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.
+ *
  * @category Combinators
+ * @since 4.0.0
  */
 export const getOption: {
   /**
-   * @since 4.0.0
+   * Reads an existing unexpired cache entry without running the lookup function.
+   *
+   * 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.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key): <E, R>(self: ScopedCache<Key, A, E, R>) => Effect.Effect<Option.Option<A>, E>
   /**
-   * @since 4.0.0
+   * Reads an existing unexpired cache entry without running the lookup function.
+   *
+   * 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.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: ScopedCache<Key, A, E, R>, key: Key): Effect.Effect<Option.Option<A>, E>
 } = dual(
@@ -290,24 +400,24 @@ const getImpl = <Key, A, E, R>(
  * Retrieves the value associated with the specified key from the cache, only if
  * it contains a resolved successful value.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const getSuccess: {
   /**
    * Retrieves the value associated with the specified key from the cache, only if
    * it contains a resolved successful value.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, R>(key: Key): <E>(self: ScopedCache<Key, A, E, R>) => Effect.Effect<Option.Option<A>>
   /**
    * Retrieves the value associated with the specified key from the cache, only if
    * it contains a resolved successful value.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: ScopedCache<Key, A, E, R>, key: Key): Effect.Effect<Option.Option<A>>
 } = dual(
@@ -330,27 +440,36 @@ export const getSuccess: {
 )
 
 /**
- * Sets the value associated with the specified key in the cache. This will
- * overwrite any existing value for that key, skipping the lookup function.
+ * Stores a successful value for a key without running the lookup function.
+ *
+ * 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.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const set: {
   /**
-   * Sets the value associated with the specified key in the cache. This will
-   * overwrite any existing value for that key, skipping the lookup function.
+   * Stores a successful value for a key without running the lookup function.
+   *
+   * 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.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key, value: A): <E, R>(self: ScopedCache<Key, A, E, R>) => Effect.Effect<void>
   /**
-   * Sets the value associated with the specified key in the cache. This will
-   * overwrite any existing value for that key, skipping the lookup function.
+   * Stores a successful value for a key without running the lookup function.
+   *
+   * 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.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: ScopedCache<Key, A, E, R>, key: Key, value: A): Effect.Effect<void>
 } = dual(
@@ -365,18 +484,24 @@ export const set: {
         const state = self.state
         const exit = core.exitSucceed(value)
         const deferred = Deferred.makeUnsafe</**
-         * Sets the value associated with the specified key in the cache. This will
-         * overwrite any existing value for that key, skipping the lookup function.
+         * Stores a successful value for a key without running the lookup function.
+         *
+         * 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.
          *
-         * @since 4.0.0
          * @category Combinators
+         * @since 4.0.0
          */
         A, /**
-         * Sets the value associated with the specified key in the cache. This will
-         * overwrite any existing value for that key, skipping the lookup function.
+         * Stores a successful value for a key without running the lookup function.
+         *
+         * 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.
          *
-         * @since 4.0.0
          * @category Combinators
+         * @since 4.0.0
          */
         E>()
         Deferred.doneUnsafe(deferred, exit)
@@ -399,22 +524,22 @@ export const set: {
 /**
  * Checks if the cache contains an entry for the specified key.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const has: {
   /**
    * Checks if the cache contains an entry for the specified key.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key): <E, R>(self: ScopedCache<Key, A, E, R>) => Effect.Effect<boolean>
   /**
    * Checks if the cache contains an entry for the specified key.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: ScopedCache<Key, A, E, R>, key: Key): Effect.Effect<boolean>
 } = dual(
@@ -426,24 +551,33 @@ export const has: {
 )
 
 /**
- * Invalidates the entry associated with the specified key in the cache.
+ * Removes the entry associated with a key and closes its entry scope.
+ *
+ * If the key is absent, this is a no-op. If the cache is closed, the effect is
+ * interrupted.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const invalidate: {
   /**
-   * Invalidates the entry associated with the specified key in the cache.
+   * Removes the entry associated with a key and closes its entry scope.
+   *
+   * If the key is absent, this is a no-op. If the cache is closed, the effect is
+   * interrupted.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key): <E, R>(self: ScopedCache<Key, A, E, R>) => Effect.Effect<void>
   /**
-   * Invalidates the entry associated with the specified key in the cache.
+   * Removes the entry associated with a key and closes its entry scope.
+   *
+   * If the key is absent, this is a no-op. If the cache is closed, the effect is
+   * interrupted.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: ScopedCache<Key, A, E, R>, key: Key): Effect.Effect<void>
 } = dual(2, <Key, A, E, R>(self: ScopedCache<Key, A, E, R>, key: Key): Effect.Effect<void> =>
@@ -465,24 +599,24 @@ export const invalidate: {
  * Conditionally invalidates the entry associated with the specified key in the cache
  * if the predicate returns true for the cached value.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const invalidateWhen: {
   /**
    * Conditionally invalidates the entry associated with the specified key in the cache
    * if the predicate returns true for the cached value.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key, f: Predicate.Predicate<A>): <E, R>(self: ScopedCache<Key, A, E, R>) => Effect.Effect<boolean>
   /**
    * Conditionally invalidates the entry associated with the specified key in the cache
    * if the predicate returns true for the cached value.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: ScopedCache<Key, A, E, R>, key: Key, f: Predicate.Predicate<A>): Effect.Effect<boolean>
 } = dual(
@@ -517,8 +651,8 @@ export const invalidateWhen: {
  * It will always invoke the lookup function to construct a new value,
  * overwriting any existing value for that key.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const refresh: {
   /**
@@ -527,8 +661,8 @@ export const refresh: {
    * It will always invoke the lookup function to construct a new value,
    * overwriting any existing value for that key.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key): <E, R>(self: ScopedCache<Key, A, E, R>) => Effect.Effect<A, E, R>
   /**
@@ -537,8 +671,8 @@ export const refresh: {
    * It will always invoke the lookup function to construct a new value,
    * overwriting any existing value for that key.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: ScopedCache<Key, A, E, R>, key: Key): Effect.Effect<A, E, R>
 } = dual(
@@ -554,8 +688,8 @@ export const refresh: {
        * It will always invoke the lookup function to construct a new value,
        * overwriting any existing value for that key.
        *
-       * @since 4.0.0
        * @category Combinators
+       * @since 4.0.0
        */
       A, /**
        * Forces a refresh of the value associated with the specified key in the cache.
@@ -563,8 +697,8 @@ export const refresh: {
        * It will always invoke the lookup function to construct a new value,
        * overwriting any existing value for that key.
        *
-       * @since 4.0.0
        * @category Combinators
+       * @since 4.0.0
        */
       E>()
       const entry: Entry<A, E> = {
@@ -602,10 +736,12 @@ export const refresh: {
 )
 
 /**
- * Invalidates all entries in the cache.
+ * Removes every entry from the cache and closes each entry scope.
+ *
+ * If the cache is closed, the effect is interrupted.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const invalidateAll = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Effect<void> =>
   core.withFiber((parent) => {
@@ -634,8 +770,8 @@ const invalidateAllImpl = <Key, A, E>(
  * The size reflects the current number of entries stored, not the number
  * of valid entries.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const size = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Effect<number> =>
   effect.sync(() => self.state._tag === "Closed" ? 0 : MutableHashMap.size(self.state.map))
@@ -643,8 +779,8 @@ export const size = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Effe
 /**
  * Retrieves all active keys from the cache, automatically filtering out expired entries.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const keys = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Effect<Array<Key>> =>
   core.withFiber((fiber) => {
@@ -668,8 +804,8 @@ export const keys = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Effe
  * Retrieves all successfully cached values from the cache, excluding failed
  * lookups and expired entries.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const values = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Effect<Array<A>> =>
   effect.map(entries(self), Arr.map(([, value]) => value))
@@ -679,8 +815,8 @@ export const values = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Ef
  * only returns entries with successfully resolved values, filtering out any
  * failed lookups or expired entries.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const entries = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Effect<Array<[Key, A]>> =>
   core.withFiber((fiber) => {

package/src/ScopedRef.ts

@@ -1,4 +1,24 @@
 /**
+ * The `ScopedRef` module provides a mutable reference for values that are tied
+ * to scoped resources. Each value stored in a `ScopedRef` is acquired within its
+ * own `Scope`, and replacing the value safely releases the resources associated
+ * with the previous value.
+ *
+ * Use `ScopedRef` when an application needs to keep a current resource-backed
+ * value, such as a live client, connection, subscription, or cached handle, and
+ * later swap it for a newly acquired value without leaking the old resources.
+ * Reads are simple, while updates are synchronized and resource-safe.
+ *
+ * **Gotchas**
+ *
+ * - A `ScopedRef` must itself be created and used within a `Scope`; when that
+ *   scope closes, the currently stored value is finalized.
+ * - Use {@link fromAcquire} or {@link set} for resourceful values so acquisition
+ *   and finalization are tracked correctly.
+ * - Use {@link make} only for values that do not acquire resources.
+ * - Updating a `ScopedRef` waits for the replacement acquisition and old
+ *   finalization to complete before returning.
+ *
  * @since 2.0.0
  */
 import * as Effect from "./Effect.ts"
@@ -18,8 +38,8 @@ const TypeId = "~effect/ScopedRef"
  * resources). The reference itself takes care of properly releasing resources
  * for the old value whenever a new value is obtained.
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface ScopedRef<in out A> extends Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -50,8 +70,8 @@ const makeUnsafe = <A>(
  * Creates a new `ScopedRef` from an effect that resourcefully produces a
  * value.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromAcquire: <A, E, R>(
   acquire: Effect.Effect<A, E, R>
@@ -71,16 +91,16 @@ export const fromAcquire: <A, E, R>(
 /**
  * Retrieves the current value of the scoped reference.
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const getUnsafe = <A>(self: ScopedRef<A>): A => self.backing.backing.ref.current[1]
 
 /**
  * Retrieves the current value of the scoped reference.
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const get = <A>(self: ScopedRef<A>): Effect.Effect<A> => Effect.sync(() => getUnsafe(self))
 
@@ -88,8 +108,8 @@ export const get = <A>(self: ScopedRef<A>): Effect.Effect<A> => Effect.sync(() =
  * Creates a new `ScopedRef` from the specified value. This method should
  * not be used for values whose creation require the acquisition of resources.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <A>(evaluate: LazyArg<A>): Effect.Effect<ScopedRef<A>, never, Scope.Scope> =>
   Effect.suspend(() => {
@@ -107,8 +127,8 @@ export const make = <A>(evaluate: LazyArg<A>): Effect.Effect<ScopedRef<A>, never
  * changed to the new value, with old resources released, or until the attempt
  * to acquire a new value fails.
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const set: {
   /**
@@ -119,8 +139,8 @@ export const set: {
    * changed to the new value, with old resources released, or until the attempt
    * to acquire a new value fails.
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <A, R, E>(acquire: Effect.Effect<A, E, R>): (self: ScopedRef<A>) => Effect.Effect<void, E, Exclude<R, Scope.Scope>>
   /**
@@ -131,8 +151,8 @@ export const set: {
    * changed to the new value, with old resources released, or until the attempt
    * to acquire a new value fails.
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <A, R, E>(self: ScopedRef<A>, acquire: Effect.Effect<A, E, R>): Effect.Effect<void, E, Exclude<R, Scope.Scope>>
 } = dual(