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

package/src/TxPubSub.ts

@@ -1,9 +1,49 @@
 /**
- * TxPubSub is a transactional publish/subscribe hub that provides Software Transactional Memory
- * (STM) semantics for message broadcasting. Publishers broadcast messages to all current
- * subscribers, with each subscriber receiving its own copy of every published message.
+ * The `TxPubSub` module provides a transactional publish/subscribe hub for
+ * broadcasting values to scoped subscribers. Each subscriber owns a `TxQueue`,
+ * so every value is offered independently to the queues registered at the time
+ * of publication.
  *
- * Supports multiple queue strategies: bounded, unbounded, dropping, and sliding.
+ * **Mental model**
+ *
+ * A `TxPubSub` is a registry of subscriber queues plus a shutdown flag.
+ * Publishing reads the current subscribers and offers the value to each queue
+ * in one transactional operation. Subscribers only receive values published
+ * after they subscribe, and `subscribe` removes the queue when its scope
+ * closes.
+ *
+ * **Common tasks**
+ *
+ * - Use `bounded` when slow subscribers should apply backpressure to
+ *   publishers.
+ * - Use `dropping` when new messages may be skipped for full subscribers.
+ * - Use `sliding` when full subscribers should keep the newest messages.
+ * - Use `unbounded` when subscriber queues should grow without backpressure.
+ *
+ * **Example** (Broadcasting to a subscriber)
+ *
+ * ```ts
+ * import { Effect, TxPubSub, TxQueue } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const hub = yield* TxPubSub.unbounded<string>()
+ *
+ *   return yield* Effect.scoped(
+ *     Effect.gen(function*() {
+ *       const subscriber = yield* TxPubSub.subscribe(hub)
+ *       yield* TxPubSub.publish(hub, "updated")
+ *       return yield* TxQueue.take(subscriber)
+ *     })
+ *   )
+ * })
+ * ```
+ *
+ * **Gotchas**
+ *
+ * - `size` reports the maximum pending messages in any subscriber queue, not
+ *   the total number of queued copies.
+ * - `shutdown` stops future publishes and shuts down subscriber queues that are
+ *   registered at shutdown time.
  *
  * @since 4.0.0
  */
@@ -291,7 +331,7 @@ export const size = <A>(self: TxPubSub<A>): Effect.Effect<number> =>
   }).pipe(Effect.tx)
 
 /**
- * Checks if the TxPubSub has no pending messages (all subscriber queues are empty).
+ * Checks whether the TxPubSub has no pending messages (all subscriber queues are empty).
  *
  * **Example** (Checking whether a pub/sub is empty)
  *
@@ -311,7 +351,7 @@ export const size = <A>(self: TxPubSub<A>): Effect.Effect<number> =>
 export const isEmpty = <A>(self: TxPubSub<A>): Effect.Effect<boolean> => Effect.map(size(self), (s) => s === 0)
 
 /**
- * Checks if any subscriber queue is at capacity.
+ * Checks whether any subscriber queue is at capacity.
  *
  * **Example** (Checking whether a pub/sub is full)
  *
@@ -339,7 +379,7 @@ export const isFull = <A>(self: TxPubSub<A>): Effect.Effect<boolean> =>
   }).pipe(Effect.tx)
 
 /**
- * Checks if the TxPubSub has been shut down.
+ * Checks whether the TxPubSub has been shut down.
  *
  * **Example** (Checking whether a pub/sub is shut down)
  *
@@ -644,10 +684,18 @@ export const subscribe = <A>(self: TxPubSub<A>): Effect.Effect<TxQueue.TxQueue<A
 /**
  * Creates a subscriber queue and registers it with the pub/sub.
  *
+ * **When to use**
+ *
+ * Use to create and register a subscriber queue inside a larger transaction
+ * when registration must be atomic with other Tx operations.
+ *
  * **Details**
  *
  * This is the transactional acquire step of `subscribe`, exposed so that callers can compose it with other Tx operations in a single transaction, such as `TxSubscriptionRef.changes`.
  *
+ * @see {@link subscribe} for the scoped acquire and release wrapper when no custom transaction composition is needed
+ * @see {@link releaseSubscriber} to remove and shut down a queue returned by `acquireSubscriber`
+ *
  * @category mutations
  * @since 4.0.0
  */
@@ -663,10 +711,24 @@ export const acquireSubscriber = <A>(
 /**
  * Removes a subscriber queue from the pub/sub and shuts it down.
  *
+ * **When to use**
+ *
+ * Use to release a manually acquired subscriber queue inside a larger
+ * transaction, removing it from the pub/sub and shutting it down together with
+ * related transactional cleanup.
+ *
  * **Details**
  *
  * This is the transactional release step of `subscribe`, exposed so that callers can compose it with other Tx operations in a single transaction.
  *
+ * **Gotchas**
+ *
+ * The supplied queue is shut down after being removed, so callers should pass a
+ * queue acquired for this pub/sub.
+ *
+ * @see {@link acquireSubscriber} for the matching transactional acquire step
+ * @see {@link subscribe} for the scoped acquire and release wrapper
+ *
  * @category mutations
  * @since 4.0.0
  */
@@ -674,10 +736,24 @@ export const releaseSubscriber: {
   /**
    * Removes a subscriber queue from the pub/sub and shuts it down.
    *
+   * **When to use**
+   *
+   * Use to release a manually acquired subscriber queue inside a larger
+   * transaction, removing it from the pub/sub and shutting it down together with
+   * related transactional cleanup.
+   *
    * **Details**
    *
    * This is the transactional release step of `subscribe`, exposed so that callers can compose it with other Tx operations in a single transaction.
    *
+   * **Gotchas**
+   *
+   * The supplied queue is shut down after being removed, so callers should pass a
+   * queue acquired for this pub/sub.
+   *
+   * @see {@link acquireSubscriber} for the matching transactional acquire step
+   * @see {@link subscribe} for the scoped acquire and release wrapper
+   *
    * @category mutations
    * @since 4.0.0
    */
@@ -685,10 +761,24 @@ export const releaseSubscriber: {
   /**
    * Removes a subscriber queue from the pub/sub and shuts it down.
    *
+   * **When to use**
+   *
+   * Use to release a manually acquired subscriber queue inside a larger
+   * transaction, removing it from the pub/sub and shutting it down together with
+   * related transactional cleanup.
+   *
    * **Details**
    *
    * This is the transactional release step of `subscribe`, exposed so that callers can compose it with other Tx operations in a single transaction.
    *
+   * **Gotchas**
+   *
+   * The supplied queue is shut down after being removed, so callers should pass a
+   * queue acquired for this pub/sub.
+   *
+   * @see {@link acquireSubscriber} for the matching transactional acquire step
+   * @see {@link subscribe} for the scoped acquire and release wrapper
+   *
    * @category mutations
    * @since 4.0.0
    */
@@ -796,7 +886,7 @@ export const awaitShutdown = <A>(self: TxPubSub<A>): Effect.Effect<void> =>
 // =============================================================================
 
 /**
- * Checks if the given value is a TxPubSub.
+ * Checks whether the given value is a TxPubSub.
  *
  * **Example** (Checking for a TxPubSub)
  *

package/src/TxQueue.ts

@@ -1,11 +1,52 @@
 /**
- * TxQueue is a transactional queue data structure that provides Software Transactional Memory (STM)
- * semantics for queue operations. It uses TxRef for transactional state management and supports
- * multiple queue strategies: bounded, unbounded, dropping, and sliding.
- *
- * Accessed values are tracked by the transaction in order to detect conflicts and to track changes.
- * A transaction will retry whenever a conflict is detected or whenever the transaction explicitly
- * calls `Effect.txRetry` and any of the accessed TxQueue values change.
+ * The `TxQueue` module provides queues whose state changes participate in
+ * Effect transactions. A `TxQueue<A, E>` stores values of type `A`, exposes
+ * write-only {@link TxEnqueue} and read-only {@link TxDequeue} handles, and can
+ * complete or fail with causes observed by consumers.
+ *
+ * **Mental model**
+ *
+ * - Queue contents and lifecycle state are transactional, so a transaction can
+ *   offer, take, inspect, and update other transactional values atomically
+ * - {@link take}, {@link takeAll}, {@link takeN}, {@link takeBetween}, and
+ *   {@link peek} retry while the queue has no required value available
+ * - {@link bounded} queues retry producers when full; {@link dropping}
+ *   rejects new values; {@link sliding} removes old values; {@link unbounded}
+ *   always accepts while open
+ * - {@link interrupt}, {@link fail}, {@link failCause}, {@link end}, and
+ *   {@link shutdown} move the queue toward completion and affect later offers
+ *   and takes
+ *
+ * **Common tasks**
+ *
+ * - Create queues: {@link bounded}, {@link dropping}, {@link sliding},
+ *   {@link unbounded}
+ * - Produce values: {@link offer}, {@link offerAll}
+ * - Consume values: {@link take}, {@link poll}, {@link peek}, {@link takeN},
+ *   {@link takeBetween}, {@link takeAll}
+ * - Inspect state: {@link size}, {@link isEmpty}, {@link isFull},
+ *   {@link isOpen}, {@link isClosing}, {@link isDone}
+ * - Finish queues: {@link end}, {@link fail}, {@link failCause},
+ *   {@link interrupt}, {@link shutdown}, {@link awaitCompletion}
+ *
+ * **Gotchas**
+ *
+ * - {@link take} and {@link peek} are blocking in transactional terms: they
+ *   use `Effect.txRetry` until an item is offered or the queue reaches a
+ *   terminal state. Use {@link poll} when absence should be immediate.
+ * - {@link offer} returns `false` for closing or done queues, and for full
+ *   {@link dropping} queues
+ * - Closing queues keep serving buffered values; done queues fail blocking
+ *   consumers with the stored cause, while {@link poll} returns `Option.none`
+ * - `TxQueue` is for coordinating transactional state. Use `Queue` for general
+ *   fiber communication outside an atomic transaction.
+ *
+ * **See also**
+ *
+ * - {@link TxEnqueue} for write-only queue handles
+ * - {@link TxDequeue} for read-only queue handles
+ * - {@link TxChunk} and {@link TxRef} for the transactional storage used by
+ *   this module
  *
  * @since 4.0.0
  */
@@ -245,7 +286,7 @@ export interface TxQueue<in out A, in out E = never> extends TxEnqueue<A, E>, Tx
 }
 
 /**
- * Checks if the given value is a TxEnqueue.
+ * Checks whether the given value is a TxEnqueue.
  *
  * **Example** (Checking enqueue handles)
  *
@@ -266,7 +307,7 @@ export interface TxQueue<in out A, in out E = never> extends TxEnqueue<A, E>, Tx
 export const isTxEnqueue = <A = unknown, E = unknown>(u: unknown): u is TxEnqueue<A, E> => hasProperty(u, EnqueueTypeId)
 
 /**
- * Checks if the given value is a TxDequeue.
+ * Checks whether the given value is a TxDequeue.
  *
  * **Example** (Checking dequeue handles)
  *
@@ -287,7 +328,7 @@ export const isTxEnqueue = <A = unknown, E = unknown>(u: unknown): u is TxEnqueu
 export const isTxDequeue = <A = unknown, E = unknown>(u: unknown): u is TxDequeue<A, E> => hasProperty(u, DequeueTypeId)
 
 /**
- * Checks if the given value is a TxQueue.
+ * Checks whether the given value is a TxQueue.
  *
  * **Example** (Checking queue handles)
  *
@@ -1286,7 +1327,7 @@ export const peek = <A, E>(self: TxDequeue<A, E>): Effect.Effect<A, E> =>
 export const size = (self: TxQueueState): Effect.Effect<number> => TxChunk.size(self.items)
 
 /**
- * Checks if the queue is empty.
+ * Checks whether the queue is empty.
  *
  * **Example** (Checking whether a queue is empty)
  *
@@ -1311,7 +1352,7 @@ export const size = (self: TxQueueState): Effect.Effect<number> => TxChunk.size(
 export const isEmpty = (self: TxQueueState): Effect.Effect<boolean> => TxChunk.isEmpty(self.items)
 
 /**
- * Checks if the queue is at capacity.
+ * Checks whether the queue is at capacity.
  *
  * **Example** (Checking whether a queue is full)
  *
@@ -1339,7 +1380,7 @@ export const isFull = (self: TxQueueState): Effect.Effect<boolean> =>
     : Effect.map(size(self), (currentSize) => currentSize >= self.capacity)
 
 /**
- * Gracefully interrupts the queue with the current fiber's interruption cause.
+ * Interrupts the queue gracefully with the current fiber's interruption cause.
  *
  * **Details**
  *
@@ -1678,7 +1719,7 @@ export const shutdown = <A, E>(self: TxEnqueue<A, E>): Effect.Effect<boolean> =>
   }).pipe(Effect.tx)
 
 /**
- * Checks if the queue is in the open state.
+ * Checks whether the queue is in the open state.
  *
  * **Example** (Checking open state)
  *
@@ -1704,7 +1745,7 @@ export const isOpen = (self: TxQueueState): Effect.Effect<boolean> =>
   Effect.map(TxRef.get(self.stateRef), (state) => state._tag === "Open")
 
 /**
- * Checks if the queue is in the closing state.
+ * Checks whether the queue is in the closing state.
  *
  * **Example** (Checking closing state)
  *
@@ -1731,7 +1772,7 @@ export const isClosing = (self: TxQueueState): Effect.Effect<boolean> =>
   Effect.map(TxRef.get(self.stateRef), (state) => state._tag === "Closing")
 
 /**
- * Checks if the queue is done (completed or failed).
+ * Checks whether the queue is done (completed or failed).
  *
  * **Example** (Checking done state)
  *
@@ -1757,7 +1798,7 @@ export const isDone = (self: TxQueueState): Effect.Effect<boolean> =>
   Effect.map(TxRef.get(self.stateRef), (state) => state._tag === "Done")
 
 /**
- * Checks if the queue is shutdown (legacy compatibility).
+ * Checks whether the queue is shutdown (legacy compatibility).
  *
  * **Example** (Checking shutdown state)
  *

package/src/TxReentrantLock.ts

@@ -1,8 +1,44 @@
 /**
- * TxReentrantLock is a transactional read/write lock with reentrant semantics using Software
- * Transactional Memory (STM). Multiple readers can hold the lock concurrently, OR a single
- * writer can hold exclusive access. A fiber holding a write lock may acquire additional
- * read or write locks (reentrancy).
+ * The `TxReentrantLock` module provides a transactional read/write lock whose
+ * ownership is tracked per fiber. Multiple fibers may hold read locks at the
+ * same time, while a write lock gives one fiber exclusive access.
+ *
+ * **Mental model**
+ *
+ * The lock stores reader counts and an optional writer count in transactional
+ * state. A fiber can reacquire locks it already owns, so nested read or write
+ * sections are safe as long as each acquisition is matched by a release. A
+ * write acquisition waits when another fiber owns a read or write lock, and a
+ * read acquisition waits when another fiber owns the write lock.
+ *
+ * **Common tasks**
+ *
+ * - Use `withReadLock` to run an effect that may share access with other
+ *   readers.
+ * - Use `withWriteLock` or `withLock` to run an effect with exclusive access.
+ * - Use `readLock` or `writeLock` when lock ownership should be tied to an
+ *   existing scope.
+ *
+ * **Example** (Protecting a read/write workflow)
+ *
+ * ```ts
+ * import { Effect, Ref, TxReentrantLock } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const lock = yield* TxReentrantLock.make()
+ *   const state = yield* Ref.make(0)
+ *
+ *   yield* TxReentrantLock.withWriteLock(lock, Ref.update(state, (n) => n + 1))
+ *   return yield* TxReentrantLock.withReadLock(lock, Ref.get(state))
+ * })
+ * ```
+ *
+ * **Gotchas**
+ *
+ * - Manual acquisitions are counted; release the same number of times or use
+ *   the scoped and `with*` helpers.
+ * - Releasing a lock from a fiber that does not own it leaves the lock
+ *   unchanged and returns `0`.
  *
  * @since 4.0.0
  */
@@ -157,9 +193,19 @@ export const acquireRead = (self: TxReentrantLock): Effect.Effect<number> =>
   )
 
 /**
- * Acquires a write lock. Blocks if any other fiber holds any lock.
- * If the current fiber already holds the write lock, the count is incremented (reentrancy).
- * If the current fiber holds a read lock, the write lock is granted (upgrade).
+ * Acquires the write lock for the current fiber.
+ *
+ * **When to use**
+ *
+ * Use to enter an exclusive section manually when `withWriteLock` is not the
+ * right shape.
+ *
+ * **Details**
+ *
+ * Blocks if any other fiber holds a read or write lock. If the current fiber
+ * already holds the write lock, the count is incremented. If the current fiber
+ * holds a read lock, the write lock is granted as an upgrade.
+ *
  * Returns the current number of write locks held by this fiber.
  *
  * **Example** (Acquiring a write lock)
@@ -217,7 +263,14 @@ export const acquireWrite = (self: TxReentrantLock): Effect.Effect<number> =>
   )
 
 /**
- * Releases a read lock held by the current fiber.
+ * Releases one read lock held by the current fiber.
+ *
+ * **When to use**
+ *
+ * Use to leave a manually acquired read lock.
+ *
+ * **Details**
+ *
  * Returns the remaining number of read locks held by this fiber.
  *
  * **Example** (Releasing a read lock)
@@ -256,7 +309,14 @@ export const releaseRead = (self: TxReentrantLock): Effect.Effect<number> =>
   )
 
 /**
- * Releases a write lock held by the current fiber.
+ * Releases one write lock held by the current fiber.
+ *
+ * **When to use**
+ *
+ * Use to leave a manually acquired write lock.
+ *
+ * **Details**
+ *
  * Returns the remaining number of write locks held by this fiber.
  *
  * **Example** (Releasing a write lock)
@@ -530,7 +590,11 @@ export const withWriteLock: {
 }) as any
 
 /**
- * Alias for `withWriteLock`. Runs the provided effect while holding a write lock.
+ * Runs an effect while holding a write lock.
+ *
+ * **When to use**
+ *
+ * Use as the short alias for {@link withWriteLock}.
  *
  * **Example** (Running an effect with exclusive access)
  *
@@ -552,7 +616,11 @@ export const withWriteLock: {
  */
 export const withLock: {
   /**
-   * Alias for `withWriteLock`. Runs the provided effect while holding a write lock.
+   * Runs an effect while holding a write lock.
+   *
+   * **When to use**
+   *
+   * Use as the short alias for {@link withWriteLock}.
    *
    * **Example** (Running an effect with exclusive access)
    *
@@ -574,7 +642,11 @@ export const withLock: {
    */
   <A, E, R>(effect: Effect.Effect<A, E, R>): (self: TxReentrantLock) => Effect.Effect<A, E, R>
   /**
-   * Alias for `withWriteLock`. Runs the provided effect while holding a write lock.
+   * Runs an effect while holding a write lock.
+   *
+   * **When to use**
+   *
+   * Use as the short alias for {@link withWriteLock}.
    *
    * **Example** (Running an effect with exclusive access)
    *
@@ -656,7 +728,7 @@ export const writeLocks = (self: TxReentrantLock): Effect.Effect<number> =>
   })
 
 /**
- * Checks if the lock is held by any fiber (read or write).
+ * Checks whether the lock is held by any fiber (read or write).
  *
  * **Example** (Checking whether a lock is held)
  *
@@ -680,7 +752,7 @@ export const locked = (self: TxReentrantLock): Effect.Effect<boolean> =>
   })
 
 /**
- * Checks if any fiber holds a read lock.
+ * Checks whether any fiber holds a read lock.
  *
  * **Example** (Checking whether a read lock is held)
  *
@@ -704,7 +776,7 @@ export const readLocked = (self: TxReentrantLock): Effect.Effect<boolean> =>
   })
 
 /**
- * Checks if any fiber holds a write lock.
+ * Checks whether any fiber holds a write lock.
  *
  * **Example** (Checking whether a write lock is held)
  *
@@ -732,7 +804,7 @@ export const writeLocked = (self: TxReentrantLock): Effect.Effect<boolean> =>
 // =============================================================================
 
 /**
- * Checks if the given value is a TxReentrantLock.
+ * Checks whether the given value is a TxReentrantLock.
  *
  * **Example** (Checking for TxReentrantLock values)
  *