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

package/src/TxDeferred.ts

@@ -1,6 +1,29 @@
 /**
- * A transactional deferred value — a write-once cell that can be read within transactions.
- * Readers retry until a value is set; once set, the value is immutable.
+ * Transactional deferred values for coordinating Effect transactions.
+ *
+ * A `TxDeferred<A, E>` is a write-once cell whose completion is a
+ * `Result<A, E>` stored in transactional state. Readers can wait for the value
+ * from inside a transaction: while the cell is empty the transaction retries,
+ * and when another transaction completes the deferred the waiting transaction
+ * can resume with either the success value or the typed failure.
+ *
+ * **Mental model**
+ *
+ * `TxDeferred` is the transaction-aware counterpart to a regular deferred
+ * value. Completion is single-assignment, reads participate in transaction
+ * retry semantics, and all observers see the same committed result once the
+ * deferred has been completed.
+ *
+ * **Common tasks**
+ *
+ * Create an empty deferred with {@link make}, wait for completion with
+ * `await`, inspect the current state with {@link poll}, and complete it with
+ * {@link done}, {@link succeed}, or {@link fail}.
+ *
+ * **Gotchas**
+ *
+ * Only the first completion wins. Later completion attempts return `false`
+ * instead of replacing the stored result.
  *
  * @since 4.0.0
  */
@@ -25,6 +48,11 @@ const TypeId = "~effect/transactions/TxDeferred"
  * Readers block (retry the transaction) until a value is committed, and writers
  * succeed only on the first call; subsequent writes return `false`.
  *
+ * **When to use**
+ *
+ * Use to coordinate transaction-local readers and one-time completion with a
+ * success or failure result.
+ *
  * **Example** (Completing a transactional deferred)
  *
  * ```ts
@@ -79,6 +107,10 @@ const makeTxDeferred = <A, E>(ref: TxRef.TxRef<Option<Result<A, E>>>): TxDeferre
 /**
  * Creates a new empty `TxDeferred`.
  *
+ * **When to use**
+ *
+ * Use to create a transactional deferred that can be completed exactly once.
+ *
  * **Example** (Creating a transactional deferred)
  *
  * ```ts
@@ -133,6 +165,13 @@ export {
    * Reads the deferred value. Retries the transaction if the deferred has not
    * been completed yet.
    *
+   * **When to use**
+   *
+   * Use to read the success value of a `TxDeferred` while retrying until the
+   * deferred is completed.
+   *
+   * @see {@link poll} for inspecting the current completion state without retrying the transaction
+   *
    * @category getters
    * @since 4.0.0
    */
@@ -143,6 +182,10 @@ export {
  * Reads the current state of the deferred without retrying. Returns `None` if
  * not yet completed.
  *
+ * **When to use**
+ *
+ * Use to inspect a `TxDeferred` without retrying when it is not completed yet.
+ *
  * **Example** (Polling a deferred)
  *
  * ```ts
@@ -168,6 +211,10 @@ export const poll = <A, E>(self: TxDeferred<A, E>): Effect.Effect<Option<Result<
  * Completes the deferred with a `Result`. Returns `true` if this was the first
  * completion, `false` if already completed.
  *
+ * **When to use**
+ *
+ * Use to complete a `TxDeferred` with an already computed `Result`.
+ *
  * **Example** (Completing with a result)
  *
  * ```ts
@@ -190,6 +237,10 @@ export const done: {
    * Completes the deferred with a `Result`. Returns `true` if this was the first
    * completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with an already computed `Result`.
+   *
    * **Example** (Completing with a result)
    *
    * ```ts
@@ -212,6 +263,10 @@ export const done: {
    * Completes the deferred with a `Result`. Returns `true` if this was the first
    * completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with an already computed `Result`.
+   *
    * **Example** (Completing with a result)
    *
    * ```ts
@@ -245,6 +300,10 @@ export const done: {
  * Completes the deferred with a success value. Returns `true` if this was the
  * first completion, `false` if already completed.
  *
+ * **When to use**
+ *
+ * Use to complete a `TxDeferred` with a successful value.
+ *
  * **Example** (Completing with a success value)
  *
  * ```ts
@@ -267,6 +326,10 @@ export const succeed: {
    * Completes the deferred with a success value. Returns `true` if this was the
    * first completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with a successful value.
+   *
    * **Example** (Completing with a success value)
    *
    * ```ts
@@ -289,6 +352,10 @@ export const succeed: {
    * Completes the deferred with a success value. Returns `true` if this was the
    * first completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with a successful value.
+   *
    * **Example** (Completing with a success value)
    *
    * ```ts
@@ -316,6 +383,10 @@ export const succeed: {
  * Completes the deferred with a failure. Returns `true` if this was the first
  * completion, `false` if already completed.
  *
+ * **When to use**
+ *
+ * Use to complete a `TxDeferred` with a typed failure value.
+ *
  * **Example** (Completing with a failure)
  *
  * ```ts
@@ -338,6 +409,10 @@ export const fail: {
    * Completes the deferred with a failure. Returns `true` if this was the first
    * completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with a typed failure value.
+   *
    * **Example** (Completing with a failure)
    *
    * ```ts
@@ -360,6 +435,10 @@ export const fail: {
    * Completes the deferred with a failure. Returns `true` if this was the first
    * completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with a typed failure value.
+   *
    * **Example** (Completing with a failure)
    *
    * ```ts
@@ -386,6 +465,10 @@ export const fail: {
 /**
  * Determines if the provided value is a `TxDeferred`.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before treating it as a transactional deferred.
+ *
  * **Example** (Checking transactional deferreds)
  *
  * ```ts

package/src/TxHashMap.ts

@@ -360,7 +360,7 @@ export const fromIterable = <K, V>(
   })
 
 /**
- * Safely lookup the value for the specified key in the TxHashMap.
+ * Looks up the value for the specified key in the TxHashMap.
  *
  * **Example** (Looking up values safely)
  *
@@ -393,7 +393,7 @@ export const fromIterable = <K, V>(
  */
 export const get: {
   /**
-   * Safely lookup the value for the specified key in the TxHashMap.
+   * Looks up the value for the specified key in the TxHashMap.
    *
    * **Example** (Looking up values safely)
    *
@@ -426,7 +426,7 @@ export const get: {
    */
   <K1 extends K, K>(key: K1): <V>(self: TxHashMap<K, V>) => Effect.Effect<Option.Option<V>>
   /**
-   * Safely lookup the value for the specified key in the TxHashMap.
+   * Looks up the value for the specified key in the TxHashMap.
    *
    * **Example** (Looking up values safely)
    *
@@ -588,7 +588,7 @@ export const set: {
 )
 
 /**
- * Checks if the specified key exists in the TxHashMap.
+ * Checks whether the specified key exists in the TxHashMap.
  *
  * **Example** (Checking for keys)
  *
@@ -620,7 +620,7 @@ export const set: {
  */
 export const has: {
   /**
-   * Checks if the specified key exists in the TxHashMap.
+   * Checks whether the specified key exists in the TxHashMap.
    *
    * **Example** (Checking for keys)
    *
@@ -652,7 +652,7 @@ export const has: {
    */
   <K1 extends K, K>(key: K1): <V>(self: TxHashMap<K, V>) => Effect.Effect<boolean>
   /**
-   * Checks if the specified key exists in the TxHashMap.
+   * Checks whether the specified key exists in the TxHashMap.
    *
    * **Example** (Checking for keys)
    *
@@ -909,7 +909,7 @@ export const size = <K, V>(self: TxHashMap<K, V>): Effect.Effect<number> =>
   })
 
 /**
- * Checks if the TxHashMap is empty.
+ * Checks whether the TxHashMap is empty.
  *
  * **Example** (Checking for an empty map)
  *
@@ -944,7 +944,7 @@ export const isEmpty = <K, V>(self: TxHashMap<K, V>): Effect.Effect<boolean> =>
   })
 
 /**
- * Checks if the TxHashMap is non-empty.
+ * Checks whether the TxHashMap is non-empty.
  *
  * **Example** (Checking for a non-empty map)
  *
@@ -3108,7 +3108,7 @@ export const filterMap: {
 )
 
 /**
- * Checks if any entry in the TxHashMap matches the given predicate.
+ * Checks whether any entry in the TxHashMap matches the given predicate.
  *
  * **Example** (Checking entries with a predicate)
  *
@@ -3151,7 +3151,7 @@ export const filterMap: {
  */
 export const hasBy: {
   /**
-   * Checks if any entry in the TxHashMap matches the given predicate.
+   * Checks whether any entry in the TxHashMap matches the given predicate.
    *
    * **Example** (Checking entries with a predicate)
    *
@@ -3194,7 +3194,7 @@ export const hasBy: {
    */
   <K, V>(predicate: (value: V, key: K) => boolean): (self: TxHashMap<K, V>) => Effect.Effect<boolean>
   /**
-   * Checks if any entry in the TxHashMap matches the given predicate.
+   * Checks whether any entry in the TxHashMap matches the given predicate.
    *
    * **Example** (Checking entries with a predicate)
    *
@@ -3386,7 +3386,7 @@ export const findFirst: {
 )
 
 /**
- * Checks if at least one entry in the TxHashMap satisfies the given predicate.
+ * Checks whether at least one entry in the TxHashMap satisfies the given predicate.
  *
  * **Example** (Checking whether some entries match)
  *
@@ -3428,7 +3428,7 @@ export const findFirst: {
  */
 export const some: {
   /**
-   * Checks if at least one entry in the TxHashMap satisfies the given predicate.
+   * Checks whether at least one entry in the TxHashMap satisfies the given predicate.
    *
    * **Example** (Checking whether some entries match)
    *
@@ -3470,7 +3470,7 @@ export const some: {
    */
   <K, V>(predicate: (value: V, key: K) => boolean): (self: TxHashMap<K, V>) => Effect.Effect<boolean>
   /**
-   * Checks if at least one entry in the TxHashMap satisfies the given predicate.
+   * Checks whether at least one entry in the TxHashMap satisfies the given predicate.
    *
    * **Example** (Checking whether some entries match)
    *
@@ -3520,7 +3520,7 @@ export const some: {
 )
 
 /**
- * Checks if all entries in the TxHashMap satisfy the given predicate.
+ * Checks whether all entries in the TxHashMap satisfy the given predicate.
  *
  * **Example** (Checking whether every entry matches)
  *
@@ -3562,7 +3562,7 @@ export const some: {
  */
 export const every: {
   /**
-   * Checks if all entries in the TxHashMap satisfy the given predicate.
+   * Checks whether all entries in the TxHashMap satisfy the given predicate.
    *
    * **Example** (Checking whether every entry matches)
    *
@@ -3604,7 +3604,7 @@ export const every: {
    */
   <K, V>(predicate: (value: V, key: K) => boolean): (self: TxHashMap<K, V>) => Effect.Effect<boolean>
   /**
-   * Checks if all entries in the TxHashMap satisfy the given predicate.
+   * Checks whether all entries in the TxHashMap satisfy the given predicate.
    *
    * **Example** (Checking whether every entry matches)
    *
@@ -3796,7 +3796,7 @@ export const forEach: {
 )
 
 /**
- * Effectfully maps each entry to a `TxHashMap` and flattens the produced maps.
+ * Maps each entry effectfully to a `TxHashMap` and flattens the produced maps.
  *
  * **Details**
  *
@@ -3850,7 +3850,7 @@ export const forEach: {
  */
 export const flatMap: {
   /**
-   * Effectfully maps each entry to a `TxHashMap` and flattens the produced maps.
+   * Maps each entry effectfully to a `TxHashMap` and flattens the produced maps.
    *
    * **Details**
    *
@@ -3904,7 +3904,7 @@ export const flatMap: {
    */
   <A, V, K>(f: (value: V, key: K) => Effect.Effect<TxHashMap<K, A>>): (self: TxHashMap<K, V>) => Effect.Effect<TxHashMap<K, A>>
   /**
-   * Effectfully maps each entry to a `TxHashMap` and flattens the produced maps.
+   * Maps each entry effectfully to a `TxHashMap` and flattens the produced maps.
    *
    * **Details**
    *
@@ -3969,7 +3969,7 @@ export const flatMap: {
     Effect.gen(function*() {
       const currentMap = yield* TxRef.get(self.ref)
       const result = yield* empty</**
-       * Effectfully maps each entry to a `TxHashMap` and flattens the produced maps.
+       * Maps each entry effectfully to a `TxHashMap` and flattens the produced maps.
        *
        * **Details**
        *
@@ -4022,7 +4022,7 @@ export const flatMap: {
        * @since 4.0.0
        */
       K, /**
-       * Effectfully maps each entry to a `TxHashMap` and flattens the produced maps.
+       * Maps each entry effectfully to a `TxHashMap` and flattens the produced maps.
        *
        * **Details**
        *

package/src/TxHashSet.ts

@@ -283,7 +283,7 @@ export const fromHashSet = <V>(hashSet: HashSet.HashSet<V>): Effect.Effect<TxHas
   })
 
 /**
- * Checks if a value is a TxHashSet.
+ * Checks whether a value is a TxHashSet.
  *
  * **Example** (Checking for a TxHashSet)
  *
@@ -617,7 +617,7 @@ export const remove: {
   }).pipe(Effect.tx))
 
 /**
- * Checks if the TxHashSet contains the specified value.
+ * Checks whether the TxHashSet contains the specified value.
  *
  * **Example** (Checking membership)
  *
@@ -653,7 +653,7 @@ export const remove: {
  */
 export const has: {
   /**
-   * Checks if the TxHashSet contains the specified value.
+   * Checks whether the TxHashSet contains the specified value.
    *
    * **Example** (Checking membership)
    *
@@ -689,7 +689,7 @@ export const has: {
    */
   <V>(value: V): (self: TxHashSet<V>) => Effect.Effect<boolean>
   /**
-   * Checks if the TxHashSet contains the specified value.
+   * Checks whether the TxHashSet contains the specified value.
    *
    * **Example** (Checking membership)
    *
@@ -726,7 +726,7 @@ export const has: {
   <V>(self: TxHashSet<V>, value: V): Effect.Effect<boolean>
 } = dual<
   /**
-   * Checks if the TxHashSet contains the specified value.
+   * Checks whether the TxHashSet contains the specified value.
    *
    * **Example** (Checking membership)
    *
@@ -762,7 +762,7 @@ export const has: {
    */
   <V>(value: V) => (self: TxHashSet<V>) => Effect.Effect<boolean>,
   /**
-   * Checks if the TxHashSet contains the specified value.
+   * Checks whether the TxHashSet contains the specified value.
    *
    * **Example** (Checking membership)
    *
@@ -833,7 +833,7 @@ export const size = <V>(self: TxHashSet<V>): Effect.Effect<number> =>
   })
 
 /**
- * Checks if the TxHashSet is empty.
+ * Checks whether the TxHashSet is empty.
  *
  * **Example** (Checking whether a set is empty)
  *
@@ -1258,7 +1258,7 @@ export const difference: {
   }).pipe(Effect.tx))
 
 /**
- * Checks if a TxHashSet is a subset of another TxHashSet.
+ * Checks whether a TxHashSet is a subset of another TxHashSet.
  *
  * **Example** (Checking subset relationships)
  *
@@ -1282,7 +1282,7 @@ export const difference: {
  */
 export const isSubset: {
   /**
-   * Checks if a TxHashSet is a subset of another TxHashSet.
+   * Checks whether a TxHashSet is a subset of another TxHashSet.
    *
    * **Example** (Checking subset relationships)
    *
@@ -1306,7 +1306,7 @@ export const isSubset: {
    */
   <V1>(that: TxHashSet<V1>): <V0>(self: TxHashSet<V0>) => Effect.Effect<boolean>
   /**
-   * Checks if a TxHashSet is a subset of another TxHashSet.
+   * Checks whether a TxHashSet is a subset of another TxHashSet.
    *
    * **Example** (Checking subset relationships)
    *
@@ -1331,7 +1331,7 @@ export const isSubset: {
   <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>): Effect.Effect<boolean>
 } = dual<
   /**
-   * Checks if a TxHashSet is a subset of another TxHashSet.
+   * Checks whether a TxHashSet is a subset of another TxHashSet.
    *
    * **Example** (Checking subset relationships)
    *
@@ -1355,7 +1355,7 @@ export const isSubset: {
    */
   <V1>(that: TxHashSet<V1>) => <V0>(self: TxHashSet<V0>) => Effect.Effect<boolean>,
   /**
-   * Checks if a TxHashSet is a subset of another TxHashSet.
+   * Checks whether a TxHashSet is a subset of another TxHashSet.
    *
    * **Example** (Checking subset relationships)
    *
@@ -1386,7 +1386,7 @@ export const isSubset: {
   }).pipe(Effect.tx))
 
 /**
- * Tests whether at least one value in the TxHashSet satisfies the predicate.
+ * Checks whether at least one value in the TxHashSet satisfies the predicate.
  *
  * **Example** (Testing whether some values match)
  *
@@ -1409,7 +1409,7 @@ export const isSubset: {
  */
 export const some: {
   /**
-   * Tests whether at least one value in the TxHashSet satisfies the predicate.
+   * Checks whether at least one value in the TxHashSet satisfies the predicate.
    *
    * **Example** (Testing whether some values match)
    *
@@ -1432,7 +1432,7 @@ export const some: {
    */
   <V>(predicate: Predicate<V>): (self: TxHashSet<V>) => Effect.Effect<boolean>
   /**
-   * Tests whether at least one value in the TxHashSet satisfies the predicate.
+   * Checks whether at least one value in the TxHashSet satisfies the predicate.
    *
    * **Example** (Testing whether some values match)
    *
@@ -1456,7 +1456,7 @@ export const some: {
   <V>(self: TxHashSet<V>, predicate: Predicate<V>): Effect.Effect<boolean>
 } = dual<
   /**
-   * Tests whether at least one value in the TxHashSet satisfies the predicate.
+   * Checks whether at least one value in the TxHashSet satisfies the predicate.
    *
    * **Example** (Testing whether some values match)
    *
@@ -1479,7 +1479,7 @@ export const some: {
    */
   <V>(predicate: Predicate<V>) => (self: TxHashSet<V>) => Effect.Effect<boolean>,
   /**
-   * Tests whether at least one value in the TxHashSet satisfies the predicate.
+   * Checks whether at least one value in the TxHashSet satisfies the predicate.
    *
    * **Example** (Testing whether some values match)
    *
@@ -1508,7 +1508,7 @@ export const some: {
   }))
 
 /**
- * Tests whether all values in the TxHashSet satisfy the predicate.
+ * Checks whether all values in the TxHashSet satisfy the predicate.
  *
  * **Example** (Testing whether every value matches)
  *
@@ -1531,7 +1531,7 @@ export const some: {
  */
 export const every: {
   /**
-   * Tests whether all values in the TxHashSet satisfy the predicate.
+   * Checks whether all values in the TxHashSet satisfy the predicate.
    *
    * **Example** (Testing whether every value matches)
    *
@@ -1554,7 +1554,7 @@ export const every: {
    */
   <V>(predicate: Predicate<V>): (self: TxHashSet<V>) => Effect.Effect<boolean>
   /**
-   * Tests whether all values in the TxHashSet satisfy the predicate.
+   * Checks whether all values in the TxHashSet satisfy the predicate.
    *
    * **Example** (Testing whether every value matches)
    *
@@ -1578,7 +1578,7 @@ export const every: {
   <V>(self: TxHashSet<V>, predicate: Predicate<V>): Effect.Effect<boolean>
 } = dual<
   /**
-   * Tests whether all values in the TxHashSet satisfy the predicate.
+   * Checks whether all values in the TxHashSet satisfy the predicate.
    *
    * **Example** (Testing whether every value matches)
    *
@@ -1601,7 +1601,7 @@ export const every: {
    */
   <V>(predicate: Predicate<V>) => (self: TxHashSet<V>) => Effect.Effect<boolean>,
   /**
-   * Tests whether all values in the TxHashSet satisfy the predicate.
+   * Checks whether all values in the TxHashSet satisfy the predicate.
    *
    * **Example** (Testing whether every value matches)
    *

package/src/TxPriorityQueue.ts

@@ -1,6 +1,33 @@
 /**
- * A transactional priority queue. Elements are dequeued in order determined by the
- * provided `Order` instance. All operations participate in the STM transaction system.
+ * The `TxPriorityQueue` module provides a mutable priority queue whose state is
+ * stored in a transactional reference. Elements are kept in the order defined by
+ * the `Order` supplied at construction time, and dequeue operations return the
+ * first element according to that ordering.
+ *
+ * A `TxPriorityQueue<A>` is useful when multiple fibers coordinate through a
+ * shared queue and the queue operation needs to compose with other
+ * transactional state changes. Every operation returns an `Effect`; group
+ * several queue operations with `Effect.tx` when the whole sequence must commit
+ * or retry as one transaction.
+ *
+ * **Common tasks**
+ *
+ * - Create queues with {@link empty}, {@link fromIterable}, or {@link make}
+ * - Insert values with {@link offer} and {@link offerAll}
+ * - Read priority order with {@link peek}, {@link peekOption}, and
+ *   {@link toArray}
+ * - Remove values with {@link take}, {@link takeOption}, {@link takeAll}, and
+ *   {@link takeUpTo}
+ * - Keep or remove subsets with {@link retainIf} and {@link removeIf}
+ *
+ * **Gotchas**
+ *
+ * - `take` and `peek` retry when the queue is empty; use `takeOption` or
+ *   `peekOption` when empty queues should be represented as `Option.none`.
+ * - `Order.Number` is ascending, so lower numbers are dequeued first. Provide a
+ *   reversed order when larger values should have higher priority.
+ * - The queue preserves all values with equal priority; equal values are not
+ *   merged or deduplicated.
  *
  * @since 4.0.0
  */
@@ -284,8 +311,12 @@ export const isEmpty = <A>(self: TxPriorityQueue<A>): Effect.Effect<boolean> =>
 export const isNonEmpty = <A>(self: TxPriorityQueue<A>): Effect.Effect<boolean> => Effect.map(size(self), (n) => n > 0)
 
 /**
- * Observes the smallest element without removing it. Retries if the queue is
- * empty.
+ * Observes the smallest element without removing it.
+ *
+ * **When to use**
+ *
+ * Use to inspect the next prioritized value and retry transactionally while
+ * the queue is empty.
  *
  * **Example** (Peeking at the next value)
  *
@@ -313,9 +344,13 @@ export const peek = <A>(self: TxPriorityQueue<A>): Effect.Effect<A> =>
   }).pipe(Effect.tx)
 
 /**
- * Observes the smallest element without removing it. Returns `None` if the
+ * Observes the smallest element without removing it, returning `None` when the
  * queue is empty.
  *
+ * **When to use**
+ *
+ * Use to inspect the next prioritized value without retrying on an empty queue.
+ *
  * **Example** (Peeking without retrying)
  *
  * ```ts
@@ -689,7 +724,7 @@ export const removeIf: {
 )
 
 /**
- * Retains only elements matching the predicate.
+ * Keeps only elements matching the predicate.
  *
  * **Example** (Retaining matching values)
  *
@@ -709,7 +744,7 @@ export const removeIf: {
  */
 export const retainIf: {
   /**
-   * Retains only elements matching the predicate.
+   * Keeps only elements matching the predicate.
    *
    * **Example** (Retaining matching values)
    *
@@ -729,7 +764,7 @@ export const retainIf: {
    */
   <A>(predicate: Predicate<A>): (self: TxPriorityQueue<A>) => Effect.Effect<void>
   /**
-   * Retains only elements matching the predicate.
+   * Keeps only elements matching the predicate.
    *
    * **Example** (Retaining matching values)
    *