effect 4.0.0-beta.70 → 4.0.0-beta.71

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
    */
@@ -163,6 +199,11 @@ const makeUnsafe = <K, A, E>(options: {
  * 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,6 +234,9 @@ 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
  */
@@ -202,6 +246,11 @@ export const make: {
    * 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
    */
@@ -247,6 +299,11 @@ export const make: {
    * 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

package/src/Record.ts

@@ -1,5 +1,76 @@
 /**
- * This module provides utility functions for working with records in TypeScript.
+ * Tools for working with plain JavaScript records as immutable key-value
+ * dictionaries. The module covers construction, lookup, updates, mapping,
+ * filtering, folding, set-like combination, and typed conversions between
+ * records and iterable entries.
+ *
+ * Reach for `Record` when your data is already represented as a plain object
+ * with string or symbol keys and you want typed, data-first or data-last
+ * helpers that return new records instead of mutating the input.
+ *
+ * **Mental model**
+ *
+ * - A `ReadonlyRecord<K, A>` is a plain object whose keys are known by type and
+ *   whose values share a common type.
+ * - Operations such as {@link set}, {@link remove}, {@link map}, and
+ *   {@link filter} allocate new plain objects.
+ * - Lookups and updates that might miss a key return `Option` values through
+ *   APIs such as {@link get}, {@link modify}, {@link replace}, and {@link pop}.
+ * - Many APIs are dual, so they work both as `Record.map(record, f)` and in
+ *   pipelines as `pipe(record, Record.map(f))`.
+ *
+ * **Common tasks**
+ *
+ * - Create records: {@link empty}, {@link singleton}, {@link fromEntries},
+ *   {@link fromIterableBy}, {@link fromIterableWith}
+ * - Inspect records: {@link isEmptyRecord}, {@link size}, {@link has},
+ *   {@link get}, {@link keys}, {@link values}, {@link toEntries}
+ * - Add, update, or remove entries: {@link set}, {@link modify},
+ *   {@link replace}, {@link remove}, {@link pop}
+ * - Transform entries: {@link map}, {@link mapKeys}, {@link mapEntries},
+ *   {@link collect}
+ * - Filter or partition: {@link filter}, {@link filterMap}, {@link getSomes},
+ *   {@link getFailures}, {@link getSuccesses}, {@link partition},
+ *   {@link separate}
+ * - Fold and search: {@link reduce}, {@link every}, {@link some},
+ *   {@link findFirst}
+ * - Combine records: {@link union}, {@link intersection}, {@link difference},
+ *   {@link makeReducerUnion}, {@link makeReducerIntersection}
+ * - Compare records: {@link isSubrecord}, {@link isSubrecordBy},
+ *   {@link makeEquivalence}
+ *
+ * **Gotchas**
+ *
+ * - Iteration-based APIs use `Object.keys`, so they visit enumerable string
+ *   keys. Targeted APIs such as {@link has}, {@link get}, {@link set}, and
+ *   {@link remove} can work with symbol keys, but {@link keys}, {@link values},
+ *   {@link map}, and similar traversal APIs do not visit symbols.
+ * - When duplicate keys are produced by constructors or key-mapping APIs, later
+ *   writes overwrite earlier values according to normal object assignment.
+ *
+ * **Quickstart**
+ *
+ * **Example** (Transforming a record without mutation)
+ *
+ * ```ts
+ * import { Record } from "effect"
+ *
+ * const scores = { alice: 1, bob: 2 }
+ *
+ * const next = Record.set(scores, "carol", 3)
+ * const doubled = Record.map(next, (score) => score * 2)
+ *
+ * console.log(scores) // { alice: 1, bob: 2 }
+ * console.log(doubled) // { alice: 2, bob: 4, carol: 6 }
+ * console.log(Record.get(doubled, "alice")) // Option.some(2)
+ * ```
+ *
+ * **See also**
+ *
+ * - `Struct` for fixed-shape objects where each field may have a
+ *   different type
+ * - `HashMap` for immutable maps with arbitrary key types and Effect
+ *   equality / hashing semantics
  *
  * @since 2.0.0
  */
@@ -2249,6 +2320,21 @@ export const singleton = <K extends string | symbol, A>(key: K, value: A): Recor
  * Creates a `Reducer` for combining `Record`s using union, with values for keys that exist in both records combined
  * using the provided `Combiner`.
  *
+ * **When to use**
+ *
+ * Use to build a reusable reducer for accumulating many records into one
+ * union-shaped record, preserving keys from every input and combining
+ * overlapping values with the supplied combiner.
+ *
+ * **Details**
+ *
+ * The returned reducer uses `Record.union` for combine and an empty record as
+ * `initialValue`, so the default `combineAll` folds from `{}` and accumulates
+ * keys from each input record.
+ *
+ * @see {@link union} for one-off record merging with the same union semantics
+ * @see {@link makeReducerIntersection} for a reducer that keeps only keys present on both sides
+ *
  * @category combining
  * @since 4.0.0
  */
@@ -2263,12 +2349,20 @@ export function makeReducerUnion<K extends string, A>(combiner: Combiner.Combine
  * Creates a `Reducer` whose `combine` operation intersects two records and
  * combines values for keys present in both records.
  *
+ * **When to use**
+ *
+ * Use to build a `Reducer` that combines records by retaining only keys shared
+ * by both inputs and combining matching values with a `Combiner`.
+ *
  * **Gotchas**
  *
  * The reducer's `initialValue` is an empty record. Because intersection with
  * an empty record is empty, the default `combineAll` folds from `{}` and
  * therefore produces `{}` for ordinary non-empty inputs.
  *
+ * @see {@link makeReducerUnion} for a reducer that preserves keys from either input record
+ * @see {@link intersection} for applying the shared-key merge to one pair of records
+ *
  * @category combining
  * @since 4.0.0
  */