effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/RcMap.ts

@@ -40,6 +40,11 @@ const TypeId = "~effect/RcMap"
  * of resources indexed by keys. Resources are lazily acquired and automatically
  * released when no longer in use.
  *
+ * **When to use**
+ *
+ * Use to share scoped resources by key while automatically releasing them after
+ * their last active reference is gone.
+ *
  * **Example** (Inspecting a reference-counted map)
  *
  * ```ts
@@ -67,6 +72,9 @@ const TypeId = "~effect/RcMap"
  * }).pipe(Effect.scoped)
  * ```
  *
+ * @see {@link make} for creating an `RcMap`
+ * @see {@link get} for acquiring or retaining a resource by key
+ *
  * @category models
  * @since 3.5.0
  */
@@ -84,6 +92,15 @@ 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).
  *
+ * **When to use**
+ *
+ * Use when typing code that inspects an `RcMap`'s `state` field and narrows
+ * between open and closed lifecycle states.
+ *
+ * @see {@link RcMap} for the map value that exposes this state
+ * @see {@link State.Open} for the active state with entries
+ * @see {@link State.Closed} for the shutdown state
+ *
  * @category models
  * @since 4.0.0
  */
@@ -92,6 +109,11 @@ export type State<K, A, E> = State.Open<K, A, E> | State.Closed
 /**
  * Namespace containing the internal state types for RcMap.
  *
+ * **When to use**
+ *
+ * Use when referring to the concrete open, closed, and entry state shapes used
+ * by `RcMap`.
+ *
  * @since 4.0.0
  */
 export declare namespace State {
@@ -99,6 +121,11 @@ export declare namespace State {
    * Represents the open/active state of an RcMap, containing the actual
    * resource map that stores entries.
    *
+   * **When to use**
+   *
+   * Use when handling an `RcMap` that can still accept operations and contains
+   * stored entries.
+   *
    * @category models
    * @since 4.0.0
    */
@@ -111,6 +138,10 @@ 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.
    *
+   * **When to use**
+   *
+   * Use when handling an `RcMap` after its owning scope has closed.
+   *
    * @category models
    * @since 4.0.0
    */
@@ -122,6 +153,11 @@ export declare namespace State {
    * Represents an individual entry in the RcMap, containing the resource's
    * metadata including reference count, expiration time, and lifecycle management.
    *
+   * **When to use**
+   *
+   * Use when inspecting the stored resource, reference count, and idle lifecycle
+   * metadata for a single key.
+   *
    * @category models
    * @since 4.0.0
    */
@@ -159,10 +195,15 @@ const makeUnsafe = <K, A, E>(options: {
 })
 
 /**
- * An `RcMap` can contain multiple reference counted resources that can be indexed
+ * Creates an `RcMap` that can contain multiple reference counted resources that can be indexed
  * by a key. The resources are lazily acquired on the first call to `get` and
  * released when the last reference is released.
  *
+ * **When to use**
+ *
+ * Use to create a scoped reference-counted map for resources that should be
+ * acquired once per key and shared while in use.
+ *
  * **Details**
  *
  * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
@@ -193,15 +234,23 @@ const makeUnsafe = <K, A, E>(options: {
  * })
  * ```
  *
+ * @see {@link get} for acquiring or retaining a resource by key
+ * @see {@link invalidate} for removing a resource from the map
+ *
  * @category models
  * @since 3.5.0
  */
 export const make: {
   /**
-   * An `RcMap` can contain multiple reference counted resources that can be indexed
+   * Creates an `RcMap` that can contain multiple reference counted resources that can be indexed
    * by a key. The resources are lazily acquired on the first call to `get` and
    * released when the last reference is released.
    *
+   * **When to use**
+   *
+   * Use to create a scoped reference-counted map for resources that should be
+   * acquired once per key and shared while in use.
+   *
    * **Details**
    *
    * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
@@ -232,6 +281,9 @@ export const make: {
    * })
    * ```
    *
+   * @see {@link get} for acquiring or retaining a resource by key
+   * @see {@link invalidate} for removing a resource from the map
+   *
    * @category models
    * @since 3.5.0
    */
@@ -243,10 +295,15 @@ export const make: {
     }
   ): Effect.Effect<RcMap<K, A, E>, never, Scope.Scope | R>
   /**
-   * An `RcMap` can contain multiple reference counted resources that can be indexed
+   * Creates an `RcMap` that can contain multiple reference counted resources that can be indexed
    * by a key. The resources are lazily acquired on the first call to `get` and
    * released when the last reference is released.
    *
+   * **When to use**
+   *
+   * Use to create a scoped reference-counted map for resources that should be
+   * acquired once per key and shared while in use.
+   *
    * **Details**
    *
    * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
@@ -277,6 +334,9 @@ export const make: {
    * })
    * ```
    *
+   * @see {@link get} for acquiring or retaining a resource by key
+   * @see {@link invalidate} for removing a resource from the map
+   *
    * @category models
    * @since 3.5.0
    */
@@ -330,6 +390,10 @@ export const make: {
  * Gets the resource for a key, acquiring it with the map's lookup function when
  * the key is not already cached.
  *
+ * **When to use**
+ *
+ * Use to acquire or retain the resource for a key within the current scope.
+ *
  * **Details**
  *
  * The resource's reference count is incremented for the current `Scope`, and a
@@ -357,6 +421,9 @@ export const make: {
  * }).pipe(Effect.scoped)
  * ```
  *
+ * @see {@link make} for creating the reference-counted map
+ * @see {@link invalidate} for removing a resource by key
+ *
  * @category combinators
  * @since 3.5.0
  */
@@ -365,6 +432,10 @@ export const get: {
    * Gets the resource for a key, acquiring it with the map's lookup function when
    * the key is not already cached.
    *
+   * **When to use**
+   *
+   * Use to acquire or retain the resource for a key within the current scope.
+   *
    * **Details**
    *
    * The resource's reference count is incremented for the current `Scope`, and a
@@ -392,6 +463,9 @@ export const get: {
    * }).pipe(Effect.scoped)
    * ```
    *
+   * @see {@link make} for creating the reference-counted map
+   * @see {@link invalidate} for removing a resource by key
+   *
    * @category combinators
    * @since 3.5.0
    */
@@ -400,6 +474,10 @@ export const get: {
    * Gets the resource for a key, acquiring it with the map's lookup function when
    * the key is not already cached.
    *
+   * **When to use**
+   *
+   * Use to acquire or retain the resource for a key within the current scope.
+   *
    * **Details**
    *
    * The resource's reference count is incremented for the current `Scope`, and a
@@ -427,6 +505,9 @@ export const get: {
    * }).pipe(Effect.scoped)
    * ```
    *
+   * @see {@link make} for creating the reference-counted map
+   * @see {@link invalidate} for removing a resource by key
+   *
    * @category combinators
    * @since 3.5.0
    */
@@ -522,6 +603,10 @@ const release = <K, A, E>(self: RcMap<K, A, E>, key: K, entry: State.Entry<A, E>
 /**
  * Returns an iterable of all keys currently stored in the `RcMap`.
  *
+ * **When to use**
+ *
+ * Use to inspect which keys currently have stored resources in an `RcMap`.
+ *
  * **Details**
  *
  * If the `RcMap` has been closed, the effect is interrupted.
@@ -547,6 +632,8 @@ const release = <K, A, E>(self: RcMap<K, A, E>, key: K, entry: State.Entry<A, E>
  * }).pipe(Effect.scoped)
  * ```
  *
+ * @see {@link has} for checking one key without enumerating all keys
+ *
  * @category combinators
  * @since 3.8.0
  */
@@ -560,6 +647,10 @@ 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.
  *
+ * **When to use**
+ *
+ * Use to remove a resource by key so the next access performs a fresh lookup.
+ *
  * **Example** (Invalidating a resource)
  *
  * ```ts
@@ -586,6 +677,9 @@ export const keys = <K, A, E>(self: RcMap<K, A, E>): Effect.Effect<Iterable<K>>
  * }).pipe(Effect.scoped)
  * ```
  *
+ * @see {@link get} for acquiring or retaining the resource for a key
+ * @see {@link touch} for extending the idle lifetime without removing the entry
+ *
  * @category combinators
  * @since 3.13.0
  */
@@ -594,6 +688,10 @@ 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.
    *
+   * **When to use**
+   *
+   * Use to remove a resource by key so the next access performs a fresh lookup.
+   *
    * **Example** (Invalidating a resource)
    *
    * ```ts
@@ -620,6 +718,9 @@ export const invalidate: {
    * }).pipe(Effect.scoped)
    * ```
    *
+   * @see {@link get} for acquiring or retaining the resource for a key
+   * @see {@link touch} for extending the idle lifetime without removing the entry
+   *
    * @category combinators
    * @since 3.13.0
    */
@@ -628,6 +729,10 @@ 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.
    *
+   * **When to use**
+   *
+   * Use to remove a resource by key so the next access performs a fresh lookup.
+   *
    * **Example** (Invalidating a resource)
    *
    * ```ts
@@ -654,6 +759,9 @@ export const invalidate: {
    * }).pipe(Effect.scoped)
    * ```
    *
+   * @see {@link get} for acquiring or retaining the resource for a key
+   * @see {@link touch} for extending the idle lifetime without removing the entry
+   *
    * @category combinators
    * @since 3.13.0
    */
@@ -676,10 +784,22 @@ export const invalidate: {
  * Returns whether the `RcMap` currently contains an entry for the specified
  * key.
  *
+ * **When to use**
+ *
+ * Use to check whether a key is already present in an `RcMap` without running
+ * the lookup function or acquiring a missing resource.
+ *
  * **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`.
+ * This operation only checks the current map state.
+ *
+ * **Gotchas**
+ *
+ * Closed maps return `false`, so `false` does not distinguish a missing key
+ * from a closed map.
+ *
+ * @see {@link get} for acquiring or retaining the resource for a key
+ * @see {@link keys} for enumerating all currently stored keys
  *
  * @category combinators
  * @since 3.17.7
@@ -689,10 +809,22 @@ export const has: {
    * Returns whether the `RcMap` currently contains an entry for the specified
    * key.
    *
+   * **When to use**
+   *
+   * Use to check whether a key is already present in an `RcMap` without running
+   * the lookup function or acquiring a missing resource.
+   *
    * **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`.
+   * This operation only checks the current map state.
+   *
+   * **Gotchas**
+   *
+   * Closed maps return `false`, so `false` does not distinguish a missing key
+   * from a closed map.
+   *
+   * @see {@link get} for acquiring or retaining the resource for a key
+   * @see {@link keys} for enumerating all currently stored keys
    *
    * @category combinators
    * @since 3.17.7
@@ -702,10 +834,22 @@ export const has: {
    * Returns whether the `RcMap` currently contains an entry for the specified
    * key.
    *
+   * **When to use**
+   *
+   * Use to check whether a key is already present in an `RcMap` without running
+   * the lookup function or acquiring a missing resource.
+   *
    * **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`.
+   * This operation only checks the current map state.
+   *
+   * **Gotchas**
+   *
+   * Closed maps return `false`, so `false` does not distinguish a missing key
+   * from a closed map.
+   *
+   * @see {@link get} for acquiring or retaining the resource for a key
+   * @see {@link keys} for enumerating all currently stored keys
    *
    * @category combinators
    * @since 3.17.7
@@ -725,6 +869,10 @@ export const has: {
  * `idleTimeToLive` configured, calling `touch` will reset the expiration
  * timer for the specified key.
  *
+ * **When to use**
+ *
+ * Use to keep an idle resource alive longer without acquiring a new reference.
+ *
  * **Example** (Extending resource idle time)
  *
  * ```ts
@@ -752,6 +900,8 @@ export const has: {
  * }).pipe(Effect.scoped)
  * ```
  *
+ * @see {@link invalidate} for removing the resource instead of extending it
+ *
  * @category combinators
  * @since 3.13.0
  */
@@ -761,6 +911,10 @@ export const touch: {
    * `idleTimeToLive` configured, calling `touch` will reset the expiration
    * timer for the specified key.
    *
+   * **When to use**
+   *
+   * Use to keep an idle resource alive longer without acquiring a new reference.
+   *
    * **Example** (Extending resource idle time)
    *
    * ```ts
@@ -788,6 +942,8 @@ export const touch: {
    * }).pipe(Effect.scoped)
    * ```
    *
+   * @see {@link invalidate} for removing the resource instead of extending it
+   *
    * @category combinators
    * @since 3.13.0
    */
@@ -797,6 +953,10 @@ export const touch: {
    * `idleTimeToLive` configured, calling `touch` will reset the expiration
    * timer for the specified key.
    *
+   * **When to use**
+   *
+   * Use to keep an idle resource alive longer without acquiring a new reference.
+   *
    * **Example** (Extending resource idle time)
    *
    * ```ts
@@ -824,6 +984,8 @@ export const touch: {
    * }).pipe(Effect.scoped)
    * ```
    *
+   * @see {@link invalidate} for removing the resource instead of extending it
+   *
    * @category combinators
    * @since 3.13.0
    */

package/src/RcRef.ts

@@ -1,19 +1,40 @@
 /**
- * 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.
+ * The `RcRef` module provides a reference-counted handle for sharing one
+ * scoped resource across many scoped users. An `RcRef<A, E>` is lazy: it
+ * acquires the resource the first time {@link get} needs it, reuses that value
+ * while it is borrowed or kept idle, and finalizes it when the final borrowing
+ * scope closes unless an idle timeout keeps it available.
+ *
+ * **Mental model**
+ *
+ * - {@link make} stores the acquisition effect and captures the surrounding
+ *   `Scope`
+ * - {@link get} borrows the current resource for the caller's scope,
+ *   acquiring it on demand
+ * - Each borrowing scope increments the reference count and installs a release
+ *   finalizer
+ * - When the count reaches zero, the resource is finalized immediately or kept
+ *   for `idleTimeToLive`
+ * - {@link invalidate} stops reusing the current value; active borrowers keep
+ *   it until their scopes close
+ *
+ * **Common tasks**
+ *
+ * - Lazily share a connection, client, cache, worker, or other scoped resource
+ *   with {@link make}
+ * - Borrow the shared resource inside a scoped operation with {@link get}
+ * - Force the next borrow to reacquire after a stale or broken resource with
+ *   {@link invalidate}
+ *
+ * **Gotchas**
+ *
+ * - {@link get} requires `Scope`; use `Effect.scoped` or run it inside an
+ *   existing scoped workflow
+ * - Invalidation does not revoke values already returned to active scopes
+ * - With a finite `idleTimeToLive`, a zero-reference resource remains
+ *   available until the timeout expires
+ * - With an infinite `idleTimeToLive`, an idle resource remains until
+ *   invalidated or the owning scope closes
  *
  * @since 3.5.0
  */
@@ -29,6 +50,11 @@ const TypeId = "~effect/RcRef"
 /**
  * A reference counted reference that manages resource lifecycle.
  *
+ * **When to use**
+ *
+ * Use to share a scoped resource across active users with reference-counted
+ * acquisition and release.
+ *
  * **Details**
  *
  * An RcRef wraps a resource that can be acquired and released multiple times.
@@ -71,6 +97,10 @@ export interface RcRef<out A, out E = never> extends Pipeable {
 /**
  * Namespace containing type-level members associated with `RcRef`.
  *
+ * **When to use**
+ *
+ * Use to reference type-level members associated with `RcRef`.
+ *
  * **Example** (Referencing namespace types)
  *
  * ```ts
@@ -87,6 +117,11 @@ export declare namespace RcRef {
   /**
    * Type-level variance marker for `RcRef`.
    *
+   * **When to use**
+   *
+   * Use to carry the value and error type parameters for `RcRef` in Effect's
+   * type machinery.
+   *
    * **Details**
    *
    * This interface records the covariant value and error types carried by an
@@ -105,6 +140,11 @@ export declare namespace RcRef {
 /**
  * Creates an `RcRef` from an acquire effect.
  *
+ * **When to use**
+ *
+ * Use to create a lazily acquired, reference-counted resource from an acquire
+ * effect.
+ *
  * **Details**
  *
  * The resource is acquired lazily on the first `get` and shared by subsequent
@@ -152,6 +192,11 @@ export const make: <A, E, R>(
 /**
  * Gets the value from an `RcRef`, acquiring it first if needed.
  *
+ * **When to use**
+ *
+ * Use to borrow the current resource within a `Scope`, acquiring it first if
+ * necessary.
+ *
  * **Details**
  *
  * The reference count is incremented for the current `Scope`, and a release
@@ -192,11 +237,21 @@ export const get: <A, E>(self: RcRef<A, E>) => Effect.Effect<A, E, Scope> = inte
 /**
  * Invalidates the currently cached resource, if one has been acquired.
  *
+ * **When to use**
+ *
+ * Use to force future `RcRef.get` calls to acquire a fresh resource when the
+ * currently cached resource should no longer be reused.
+ *
  * **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.
+ * After invalidation, the next `get` acquires a fresh resource.
+ *
+ * **Gotchas**
+ *
+ * Invalidation does not revoke resources already borrowed by active scopes;
+ * those remain usable until their scopes close.
+ *
+ * @see {@link get} for acquiring the current cached resource or the fresh resource after invalidation
  *
  * @category combinators
  * @since 3.19.6