effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/RcMap.ts

@@ -1,4 +1,22 @@
 /**
+ * The `RcMap` module provides a scoped, reference-counted map for sharing
+ * resources by key. It is useful when many fibers may request the same
+ * resource, such as a connection, client, session, or cached handle, and the
+ * resource should be acquired once, reused while it has active references, and
+ * released automatically when it is no longer needed.
+ *
+ * Each key is resolved with a user-provided lookup effect on first access via
+ * {@link get}. Further accesses to the same key share the in-flight or acquired
+ * resource and increment its reference count for the caller's current
+ * `Scope`. When those scopes close, references are released; resources can be
+ * closed immediately, kept alive for an idle time-to-live, invalidated
+ * explicitly, or bounded by a maximum capacity.
+ *
+ * `RcMap` is designed for Effect resource lifecycles rather than general
+ * mutable caching. The map itself is scoped, lookups require a `Scope`, and
+ * complex keys should provide `Equal` / `Hash` behavior when they need
+ * value-based lookup semantics.
+ *
  * @since 3.5.0
  */
 import * as Cause from "./Cause.ts"
@@ -22,9 +40,8 @@ const TypeId = "~effect/RcMap"
  * of resources indexed by keys. Resources are lazily acquired and automatically
  * released when no longer in use.
  *
- * @since 3.5.0
- * @category models
- * @example
+ * **Example** (Inspecting a reference-counted map)
+ *
  * ```ts
  * import { Effect, RcMap } from "effect"
  *
@@ -49,6 +66,9 @@ const TypeId = "~effect/RcMap"
  *   console.log(`Capacity: ${dbConnectionMap.capacity}`)
  * }).pipe(Effect.scoped)
  * ```
+ *
+ * @category models
+ * @since 3.5.0
  */
 export interface RcMap<in out K, in out A, in out E = never> extends Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -63,27 +83,8 @@ export interface RcMap<in out K, in out A, in out E = never> extends Pipeable {
 /**
  * Represents the internal state of an RcMap, which can be either Open (active)
  * or Closed (shutdown and no longer accepting operations).
- *
- * @since 4.0.0
  * @category Models
- * @example
- * ```ts
- * import type { RcMap } from "effect"
- *
- * // State is a union type that can be either:
- * declare const openState: RcMap.State.Open<string, number, never>
- * declare const closedState: RcMap.State.Closed
- *
- * // Check the state type
- * declare const state: RcMap.State<string, number, never>
- * if (state._tag === "Open") {
- *   // Access the internal map when open
- *   console.log("Map is open, contains entries")
- * } else {
- *   // State is closed
- *   console.log("Map is closed")
- * }
- * ```
+ * @since 4.0.0
  */
 export type State<K, A, E> = State.Open<K, A, E> | State.Closed
 
@@ -91,43 +92,13 @@ export type State<K, A, E> = State.Open<K, A, E> | State.Closed
  * Namespace containing the internal state types for RcMap.
  *
  * @since 4.0.0
- * @category Models
- * @example
- * ```ts
- * import type { RcMap } from "effect"
- *
- * // The State namespace contains types for RcMap internal state:
- * // - Open: Contains the active resource map
- * // - Closed: Indicates the map is shut down
- * // - Entry: Individual resource entries with metadata
- *
- * declare const openState: RcMap.State.Open<string, number, never>
- * declare const closedState: RcMap.State.Closed
- * declare const entry: RcMap.State.Entry<number, never>
- * ```
  */
 export declare namespace State {
   /**
    * Represents the open/active state of an RcMap, containing the actual
    * resource map that stores entries.
-   *
-   * @since 4.0.0
    * @category Models
-   * @example
-   * ```ts
-   * import type { RcMap } from "effect"
-   * import * as MutableHashMap from "effect/MutableHashMap"
-   *
-   * // State.Open contains the active resource map
-   * declare const openState: RcMap.State.Open<string, number, never>
-   *
-   * // Access the internal map when state is open
-   * if (openState._tag === "Open") {
-   *   // The map contains Entry objects indexed by keys
-   *   const hasKey = MutableHashMap.has(openState.map, "someKey")
-   *   console.log(`Map contains key: ${hasKey}`)
-   * }
-   * ```
+   * @since 4.0.0
    */
   export interface Open<K, A, E> {
     readonly _tag: "Open"
@@ -137,22 +108,8 @@ export declare namespace State {
   /**
    * Represents the closed state of an RcMap, indicating that the map has been
    * shut down and will no longer accept new operations.
-   *
-   * @since 4.0.0
    * @category Models
-   * @example
-   * ```ts
-   * import type { RcMap } from "effect"
-   *
-   * // State.Closed indicates the RcMap is shut down
-   * declare const closedState: RcMap.State.Closed
-   *
-   * // Check for closed state
-   * if (closedState._tag === "Closed") {
-   *   console.log("RcMap is closed, no operations allowed")
-   *   // Any attempt to get resources will result in interruption
-   * }
-   * ```
+   * @since 4.0.0
    */
   export interface Closed {
     readonly _tag: "Closed"
@@ -161,27 +118,8 @@ export declare namespace State {
   /**
    * Represents an individual entry in the RcMap, containing the resource's
    * metadata including reference count, expiration time, and lifecycle management.
-   *
-   * @since 4.0.0
    * @category Models
-   * @example
-   * ```ts
-   * import type { RcMap } from "effect"
-   *
-   * // Entry contains all metadata for a resource in the map
-   * declare const entry: RcMap.State.Entry<string, never>
-   *
-   * // Entry properties:
-   * // - deferred: Promise-like structure for the resource value
-   * // - scope: Manages the resource's lifecycle
-   * // - finalizer: Effect to run when cleaning up
-   * // - fiber: Optional background fiber for expiration
-   * // - expiresAt: Timestamp when resource expires
-   * // - refCount: Number of active references
-   *
-   * console.log(`Reference count: ${entry.refCount}`)
-   * console.log(`Expires at: ${entry.expiresAt}`)
-   * ```
+   * @since 4.0.0
    */
   export interface Entry<A, E> {
     readonly deferred: Deferred.Deferred<A, E>
@@ -228,9 +166,8 @@ const makeUnsafe = <K, A, E>(options: {
  * - `capacity`: The maximum number of resources that can be held in the map.
  * - `idleTimeToLive`: When the reference count reaches zero, the resource will be released after this duration.
  *
- * @since 3.5.0
- * @category models
- * @example
+ * **Example** (Creating a reference-counted map)
+ *
  * ```ts
  * import { Effect, RcMap } from "effect"
  *
@@ -251,6 +188,9 @@ const makeUnsafe = <K, A, E>(options: {
  *   )
  * })
  * ```
+ *
+ * @category models
+ * @since 3.5.0
  */
 export const make: {
   /**
@@ -265,9 +205,8 @@ export const make: {
    * - `capacity`: The maximum number of resources that can be held in the map.
    * - `idleTimeToLive`: When the reference count reaches zero, the resource will be released after this duration.
    *
-   * @since 3.5.0
-   * @category models
-   * @example
+   * **Example** (Creating a reference-counted map)
+   *
    * ```ts
    * import { Effect, RcMap } from "effect"
    *
@@ -288,6 +227,9 @@ export const make: {
    *   )
    * })
    * ```
+   *
+   * @category models
+   * @since 3.5.0
    */
   <K, A, E, R>(
     options: {
@@ -308,9 +250,8 @@ export const make: {
    * - `capacity`: The maximum number of resources that can be held in the map.
    * - `idleTimeToLive`: When the reference count reaches zero, the resource will be released after this duration.
    *
-   * @since 3.5.0
-   * @category models
-   * @example
+   * **Example** (Creating a reference-counted map)
+   *
    * ```ts
    * import { Effect, RcMap } from "effect"
    *
@@ -331,6 +272,9 @@ export const make: {
    *   )
    * })
    * ```
+   *
+   * @category models
+   * @since 3.5.0
    */
   <K, A, E, R>(
     options: {
@@ -379,13 +323,18 @@ export const make: {
   })
 
 /**
- * Retrieves a value from the RcMap by key. If the resource doesn't exist, it will be
- * acquired using the lookup function. The resource is reference counted and will be
- * released when the scope closes.
+ * Gets the resource for a key, acquiring it with the map's lookup function when
+ * the key is not already cached.
+ *
+ * **Details**
+ *
+ * The resource's reference count is incremented for the current `Scope`, and a
+ * release finalizer is added to that scope. When the current scope closes, the
+ * reference is released; the resource is closed when the last reference is
+ * released, subject to the map's idle time-to-live setting.
+ *
+ * **Example** (Acquiring a resource)
  *
- * @since 3.5.0
- * @category combinators
- * @example
  * ```ts
  * import { Effect, RcMap } from "effect"
  *
@@ -403,16 +352,24 @@ export const make: {
  *   console.log(resource) // "Resource: database"
  * }).pipe(Effect.scoped)
  * ```
+ *
+ * @category combinators
+ * @since 3.5.0
  */
 export const get: {
   /**
-   * Retrieves a value from the RcMap by key. If the resource doesn't exist, it will be
-   * acquired using the lookup function. The resource is reference counted and will be
-   * released when the scope closes.
+   * Gets the resource for a key, acquiring it with the map's lookup function when
+   * the key is not already cached.
+   *
+   * **Details**
+   *
+   * The resource's reference count is incremented for the current `Scope`, and a
+   * release finalizer is added to that scope. When the current scope closes, the
+   * reference is released; the resource is closed when the last reference is
+   * released, subject to the map's idle time-to-live setting.
+   *
+   * **Example** (Acquiring a resource)
    *
-   * @since 3.5.0
-   * @category combinators
-   * @example
    * ```ts
    * import { Effect, RcMap } from "effect"
    *
@@ -430,16 +387,24 @@ export const get: {
    *   console.log(resource) // "Resource: database"
    * }).pipe(Effect.scoped)
    * ```
+   *
+   * @category combinators
+   * @since 3.5.0
    */
   <K>(key: K): <A, E>(self: RcMap<K, A, E>) => Effect.Effect<A, E, Scope.Scope>
   /**
-   * Retrieves a value from the RcMap by key. If the resource doesn't exist, it will be
-   * acquired using the lookup function. The resource is reference counted and will be
-   * released when the scope closes.
+   * Gets the resource for a key, acquiring it with the map's lookup function when
+   * the key is not already cached.
+   *
+   * **Details**
+   *
+   * The resource's reference count is incremented for the current `Scope`, and a
+   * release finalizer is added to that scope. When the current scope closes, the
+   * reference is released; the resource is closed when the last reference is
+   * released, subject to the map's idle time-to-live setting.
+   *
+   * **Example** (Acquiring a resource)
    *
-   * @since 3.5.0
-   * @category combinators
-   * @example
    * ```ts
    * import { Effect, RcMap } from "effect"
    *
@@ -457,6 +422,9 @@ export const get: {
    *   console.log(resource) // "Resource: database"
    * }).pipe(Effect.scoped)
    * ```
+   *
+   * @category combinators
+   * @since 3.5.0
    */
   <K, A, E>(self: RcMap<K, A, E>, key: K): Effect.Effect<A, E, Scope.Scope>
 } = dual(
@@ -548,11 +516,14 @@ const release = <K, A, E>(self: RcMap<K, A, E>, key: K, entry: State.Entry<A, E>
   })
 
 /**
- * Returns an array of all keys currently stored in the RcMap.
+ * Returns an iterable of all keys currently stored in the `RcMap`.
+ *
+ * **Details**
+ *
+ * If the `RcMap` has been closed, the effect is interrupted.
+ *
+ * **Example** (Listing keys)
  *
- * @since 3.5.0
- * @category combinators
- * @example
  * ```ts
  * import { Effect, RcMap } from "effect"
  *
@@ -571,6 +542,9 @@ const release = <K, A, E>(self: RcMap<K, A, E>, key: K, entry: State.Entry<A, E>
  *   console.log(allKeys) // ["foo", "bar", "baz"]
  * }).pipe(Effect.scoped)
  * ```
+ *
+ * @category combinators
+ * @since 3.5.0
  */
 export const keys = <K, A, E>(self: RcMap<K, A, E>): Effect.Effect<Iterable<K>> => {
   return Effect.suspend(() =>
@@ -582,9 +556,8 @@ export const keys = <K, A, E>(self: RcMap<K, A, E>): Effect.Effect<Iterable<K>>
  * Invalidates and removes a specific key from the RcMap. If the resource is not
  * currently in use (reference count is 0), it will be immediately released.
  *
- * @since 3.5.0
- * @category combinators
- * @example
+ * **Example** (Invalidating a resource)
+ *
  * ```ts
  * import { Effect, RcMap } from "effect"
  *
@@ -608,15 +581,17 @@ export const keys = <K, A, E>(self: RcMap<K, A, E>): Effect.Effect<Iterable<K>>
  *   yield* RcMap.get(map, "cache")
  * }).pipe(Effect.scoped)
  * ```
+ *
+ * @category combinators
+ * @since 3.5.0
  */
 export const invalidate: {
   /**
    * Invalidates and removes a specific key from the RcMap. If the resource is not
    * currently in use (reference count is 0), it will be immediately released.
    *
-   * @since 3.5.0
-   * @category combinators
-   * @example
+   * **Example** (Invalidating a resource)
+   *
    * ```ts
    * import { Effect, RcMap } from "effect"
    *
@@ -640,15 +615,17 @@ export const invalidate: {
    *   yield* RcMap.get(map, "cache")
    * }).pipe(Effect.scoped)
    * ```
+   *
+   * @category combinators
+   * @since 3.5.0
    */
   <K>(key: K): <A, E>(self: RcMap<K, A, E>) => Effect.Effect<void>
   /**
    * Invalidates and removes a specific key from the RcMap. If the resource is not
    * currently in use (reference count is 0), it will be immediately released.
    *
-   * @since 3.5.0
-   * @category combinators
-   * @example
+   * **Example** (Invalidating a resource)
+   *
    * ```ts
    * import { Effect, RcMap } from "effect"
    *
@@ -672,6 +649,9 @@ export const invalidate: {
    *   yield* RcMap.get(map, "cache")
    * }).pipe(Effect.scoped)
    * ```
+   *
+   * @category combinators
+   * @since 3.5.0
    */
   <K, A, E>(self: RcMap<K, A, E>, key: K): Effect.Effect<void>
 } = dual(
@@ -689,18 +669,42 @@ export const invalidate: {
 )
 
 /**
- * @since 3.17.7
+ * Returns whether the `RcMap` currently contains an entry for the specified
+ * key.
+ *
+ * **Details**
+ *
+ * This operation only checks the current map state; it does not run the lookup
+ * function or acquire a missing resource. Closed maps return `false`.
+ *
  * @category combinators
+ * @since 3.17.7
  */
 export const has: {
   /**
-   * @since 3.17.7
+   * Returns whether the `RcMap` currently contains an entry for the specified
+   * key.
+   *
+   * **Details**
+   *
+   * This operation only checks the current map state; it does not run the lookup
+   * function or acquire a missing resource. Closed maps return `false`.
+   *
    * @category combinators
+   * @since 3.17.7
    */
   <K>(key: K): <A, E>(self: RcMap<K, A, E>) => Effect.Effect<boolean>
   /**
-   * @since 3.17.7
+   * Returns whether the `RcMap` currently contains an entry for the specified
+   * key.
+   *
+   * **Details**
+   *
+   * This operation only checks the current map state; it does not run the lookup
+   * function or acquire a missing resource. Closed maps return `false`.
+   *
    * @category combinators
+   * @since 3.17.7
    */
   <K, A, E>(self: RcMap<K, A, E>, key: K): Effect.Effect<boolean>
 } = dual(
@@ -717,9 +721,8 @@ export const has: {
  * `idleTimeToLive` configured, calling `touch` will reset the expiration
  * timer for the specified key.
  *
- * @since 3.5.0
- * @category combinators
- * @example
+ * **Example** (Extending resource idle time)
+ *
  * ```ts
  * import { Effect, RcMap } from "effect"
  *
@@ -744,6 +747,9 @@ export const has: {
  *   // from the time it was touched
  * }).pipe(Effect.scoped)
  * ```
+ *
+ * @category combinators
+ * @since 3.5.0
  */
 export const touch: {
   /**
@@ -751,9 +757,8 @@ export const touch: {
    * `idleTimeToLive` configured, calling `touch` will reset the expiration
    * timer for the specified key.
    *
-   * @since 3.5.0
-   * @category combinators
-   * @example
+   * **Example** (Extending resource idle time)
+   *
    * ```ts
    * import { Effect, RcMap } from "effect"
    *
@@ -778,6 +783,9 @@ export const touch: {
    *   // from the time it was touched
    * }).pipe(Effect.scoped)
    * ```
+   *
+   * @category combinators
+   * @since 3.5.0
    */
   <K>(key: K): <A, E>(self: RcMap<K, A, E>) => Effect.Effect<void>
   /**
@@ -785,9 +793,8 @@ export const touch: {
    * `idleTimeToLive` configured, calling `touch` will reset the expiration
    * timer for the specified key.
    *
-   * @since 3.5.0
-   * @category combinators
-   * @example
+   * **Example** (Extending resource idle time)
+   *
    * ```ts
    * import { Effect, RcMap } from "effect"
    *
@@ -812,6 +819,9 @@ export const touch: {
    *   // from the time it was touched
    * }).pipe(Effect.scoped)
    * ```
+   *
+   * @category combinators
+   * @since 3.5.0
    */
   <K, A, E>(self: RcMap<K, A, E>, key: K): Effect.Effect<void>
 } = dual(

package/src/RcRef.ts

@@ -1,4 +1,20 @@
 /**
+ * The `RcRef` module provides reference-counted access to a shared resource
+ * whose lifecycle is managed by `Scope`. An `RcRef<A, E>` lazily acquires its
+ * resource the first time it is requested, shares that resource across active
+ * users, and releases it when the final scope holding a reference closes.
+ *
+ * Use `RcRef` when several scoped operations should reuse the same expensive
+ * or stateful resource, such as a connection, client, cache, or worker, without
+ * making each operation acquire and release its own copy. `make` defines how
+ * the resource is acquired, `get` borrows the current resource for the active
+ * scope, and `invalidate` forces a future `get` to acquire a fresh resource.
+ *
+ * The resource is tied to scopes rather than ordinary object reachability:
+ * every `get` must run with a `Scope`, and the reference count is decremented
+ * when that scope closes. If `idleTimeToLive` is configured, a resource whose
+ * reference count reaches zero can remain cached briefly before release.
+ *
  * @since 3.5.0
  */
 import type * as Duration from "./Duration.ts"
@@ -17,9 +33,8 @@ const TypeId = "~effect/RcRef"
  * The resource is lazily acquired on the first call to `get` and automatically
  * released when the last reference is released.
  *
- * @since 3.5.0
- * @category models
- * @example
+ * **Example** (Sharing a lazily acquired resource)
+ *
  * ```ts
  * import { Effect, RcRef } from "effect"
  *
@@ -43,15 +58,19 @@ const TypeId = "~effect/RcRef"
  *   return [connection1, connection2]
  * })
  * ```
+ *
+ * @category models
+ * @since 3.5.0
  */
 export interface RcRef<out A, out E = never> extends Pipeable {
   readonly [TypeId]: RcRef.Variance<A, E>
 }
 
 /**
- * @since 3.5.0
- * @category models
- * @example
+ * Namespace containing type-level members associated with `RcRef`.
+ *
+ * **Example** (Referencing namespace types)
+ *
  * ```ts
  * import type { RcRef } from "effect"
  *
@@ -59,21 +78,22 @@ export interface RcRef<out A, out E = never> extends Pipeable {
  * type MyRcRef = RcRef.RcRef<string, Error>
  * type MyVariance = RcRef.RcRef.Variance<string, Error>
  * ```
+ *
+ * @category models
+ * @since 3.5.0
  */
 export declare namespace RcRef {
   /**
-   * @since 3.5.0
-   * @category models
-   * @example
-   * ```ts
-   * import type { RcRef } from "effect"
+   * Type-level variance marker for `RcRef`.
+   *
+   * **Notes**
    *
-   * // Variance interface defines covariance for type parameters
-   * type StringRcRefVariance = RcRef.RcRef.Variance<string, Error>
+   * This interface records the covariant value and error types carried by an
+   * `RcRef`. It is used by Effect's type machinery and is not normally
+   * referenced directly by users.
    *
-   * // Shows that both A and E are covariant
-   * declare const variance: StringRcRefVariance
-   * ```
+   * @category models
+   * @since 3.5.0
    */
   export interface Variance<A, E> {
     readonly _A: Types.Covariant<A>
@@ -82,17 +102,18 @@ export declare namespace RcRef {
 }
 
 /**
- * Create an `RcRef` from an acquire `Effect`.
+ * Creates an `RcRef` from an acquire effect.
  *
- * An RcRef wraps a reference counted resource that can be acquired and released
- * multiple times.
+ * **Details**
  *
- * The resource is lazily acquired on the first call to `get` and released when
- * the last reference is released.
+ * The resource is acquired lazily on the first `get` and shared by subsequent
+ * gets while it remains cached. Each `get` adds a reference to the current
+ * `Scope`. When the last reference is released, the resource is closed
+ * immediately by default, or after `idleTimeToLive` when that option is
+ * provided.
+ *
+ * **Example** (Creating a reference-counted resource)
  *
- * @since 3.5.0
- * @category constructors
- * @example
  * ```ts
  * import { Effect, RcRef } from "effect"
  *
@@ -112,6 +133,9 @@ export declare namespace RcRef {
  *   )
  * })
  * ```
+ *
+ * @category constructors
+ * @since 3.5.0
  */
 export const make: <A, E, R>(
   options: {
@@ -125,15 +149,17 @@ export const make: <A, E, R>(
 ) => Effect.Effect<RcRef<A, E>, never, R | Scope> = internal.make
 
 /**
- * Get the value from an RcRef.
+ * Gets the value from an `RcRef`, acquiring it first if needed.
  *
- * This will acquire the resource if it hasn't been acquired yet, or increment
- * the reference count if it has. The resource will be automatically released
- * when the returned scope is closed.
+ * **Details**
+ *
+ * The reference count is incremented for the current `Scope`, and a release
+ * finalizer is added to that scope. When the current scope closes, the
+ * reference is released; the resource is closed when the final reference is
+ * released, subject to any configured idle time-to-live.
+ *
+ * **Example** (Sharing one acquired value)
  *
- * @since 3.5.0
- * @category combinators
- * @example
  * ```ts
  * import { Effect, RcRef } from "effect"
  *
@@ -156,11 +182,22 @@ export const make: <A, E, R>(
  *   return value1
  * })
  * ```
+ *
+ * @category combinators
+ * @since 3.5.0
  */
 export const get: <A, E>(self: RcRef<A, E>) => Effect.Effect<A, E, Scope> = internal.get
 
 /**
- * @since 3.19.6
+ * Invalidates the currently cached resource, if one has been acquired.
+ *
+ * **Details**
+ *
+ * After invalidation, the next `get` acquires a fresh resource. If the current
+ * resource is still referenced by active scopes, it remains usable until those
+ * scopes close; otherwise it is closed immediately.
+ *
  * @category combinators
+ * @since 3.19.6
  */
 export const invalidate: <A, E>(self: RcRef<A, E>) => Effect.Effect<void> = internal.invalidate