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

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
  */
@@ -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
    */

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
  */

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
  */

package/src/TxRef.ts

@@ -1,10 +1,63 @@
 /**
- * TxRef is a transactional value, it can be read and modified within the body of a transaction.
+ * The `TxRef` module provides transactional references for coordinating mutable
+ * state with Effect transactions. A `TxRef<A>` stores a current value, but
+ * reads and writes inside `Effect.tx` are recorded in a transaction journal and
+ * committed together only when the outermost transaction succeeds.
  *
- * Accessed values are tracked by the transaction in order to detect conflicts and in order to
- * track changes, a transaction will retry whenever a conflict is detected or whenever the
- * transaction explicitely calls to `Effect.txRetry` and any of the accessed TxRef values
- * change.
+ * **Mental model**
+ *
+ * - {@link make} creates a reference whose value can participate in
+ *   optimistic transactions.
+ * - {@link get}, {@link set}, {@link update}, and {@link modify} read and
+ *   write the transaction journal when a transaction is active.
+ * - At commit time, the transaction checks whether any accessed reference was
+ *   changed by another transaction. If so, it retries with a fresh journal.
+ * - `Effect.txRetry` suspends the transaction until one of the `TxRef` values
+ *   read by the transaction changes.
+ *
+ * **Common tasks**
+ *
+ * - Create transactional state with {@link make}.
+ * - Read the current value with {@link get}.
+ * - Replace or transform the value with {@link set} and {@link update}.
+ * - Return a derived result while writing a new value with {@link modify}.
+ * - Wrap related reads and writes in one `Effect.tx` boundary so they commit or
+ *   roll back as a unit.
+ *
+ * **Example** (Committing multiple updates atomically)
+ *
+ * ```ts
+ * import { Effect, TxRef } from "effect"
+ *
+ * const transfer = Effect.gen(function*() {
+ *   const checking = yield* TxRef.make(100)
+ *   const savings = yield* TxRef.make(0)
+ *
+ *   yield* Effect.tx(Effect.gen(function*() {
+ *     const balance = yield* TxRef.get(checking)
+ *     if (balance < 30) {
+ *       return yield* Effect.fail("insufficient funds")
+ *     }
+ *     yield* TxRef.set(checking, balance - 30)
+ *     yield* TxRef.update(savings, (amount) => amount + 30)
+ *   }))
+ *
+ *   return {
+ *     checking: yield* TxRef.get(checking),
+ *     savings: yield* TxRef.get(savings)
+ *   }
+ * })
+ * ```
+ *
+ * **Gotchas**
+ *
+ * - Group related operations in the same `Effect.tx` call; separate
+ *   transactions can observe and commit intermediate states.
+ * - A transaction body can run more than once after a conflict or
+ *   `Effect.txRetry`, so keep externally visible effects outside the
+ *   transaction body or make them idempotent.
+ * - If a transaction fails, its journal is discarded and other fibers continue
+ *   to see the last committed values.
  *
  * @since 4.0.0
  */
@@ -19,6 +72,11 @@ const TypeId = "~effect/transactions/TxRef"
 /**
  * TxRef is a transactional value, it can be read and modified within the body of a transaction.
  *
+ * **When to use**
+ *
+ * Use to store mutable state that must be read and modified inside Effect
+ * transactions.
+ *
  * **Details**
  *
  * Accessed values are tracked by the transaction in order to detect conflicts and in order to
@@ -60,6 +118,10 @@ export interface TxRef<in out A> extends Pipeable {
 /**
  * Creates a new `TxRef` with the specified initial value.
  *
+ * **When to use**
+ *
+ * Use to create a transactional reference inside an `Effect` workflow.
+ *
  * **Example** (Creating transactional references)
  *
  * ```ts
@@ -91,8 +153,8 @@ export const make = <A>(initial: A) => Effect.sync(() => makeUnsafe(initial))
  *
  * **When to use**
  *
- * Prefer `make` in Effect code so allocation stays inside the Effect workflow.
- * Use `makeUnsafe` only when a `TxRef` must be constructed outside an effect.
+ * Use to construct a transactional reference synchronously when it must be
+ * created outside an `Effect` workflow.
  *
  * **Example** (Creating transactional references unsafely)
  *
@@ -124,6 +186,11 @@ export const makeUnsafe = <A>(initial: A): TxRef<A> => ({
 /**
  * Modifies the value of the `TxRef` using the provided function.
  *
+ * **When to use**
+ *
+ * Use to update a transactional reference and return a computed result from the
+ * same transaction step.
+ *
  * **Example** (Modifying transactional references)
  *
  * ```ts
@@ -147,6 +214,11 @@ export const modify: {
   /**
    * Modifies the value of the `TxRef` using the provided function.
    *
+   * **When to use**
+   *
+   * Use to update a transactional reference and return a computed result from the
+   * same transaction step.
+   *
    * **Example** (Modifying transactional references)
    *
    * ```ts
@@ -170,6 +242,11 @@ export const modify: {
   /**
    * Modifies the value of the `TxRef` using the provided function.
    *
+   * **When to use**
+   *
+   * Use to update a transactional reference and return a computed result from the
+   * same transaction step.
+   *
    * **Example** (Modifying transactional references)
    *
    * ```ts
@@ -212,6 +289,10 @@ export const modify: {
 /**
  * Updates the value of the `TxRef` using the provided function.
  *
+ * **When to use**
+ *
+ * Use to transform a transactional reference when no result value is needed.
+ *
  * **Example** (Updating transactional references)
  *
  * ```ts
@@ -236,6 +317,10 @@ export const update: {
   /**
    * Updates the value of the `TxRef` using the provided function.
    *
+   * **When to use**
+   *
+   * Use to transform a transactional reference when no result value is needed.
+   *
    * **Example** (Updating transactional references)
    *
    * ```ts
@@ -260,6 +345,10 @@ export const update: {
   /**
    * Updates the value of the `TxRef` using the provided function.
    *
+   * **When to use**
+   *
+   * Use to transform a transactional reference when no result value is needed.
+   *
    * **Example** (Updating transactional references)
    *
    * ```ts
@@ -289,6 +378,10 @@ export const update: {
 /**
  * Reads the current value of the `TxRef`.
  *
+ * **When to use**
+ *
+ * Use to read the current value of a transactional reference.
+ *
  * **Example** (Reading transactional references)
  *
  * ```ts
@@ -314,6 +407,10 @@ export const get = <A>(self: TxRef<A>): Effect.Effect<A> => modify(self, (curren
 /**
  * Sets the value of the `TxRef`.
  *
+ * **When to use**
+ *
+ * Use to replace the value of a transactional reference.
+ *
  * **Example** (Setting transactional references)
  *
  * ```ts
@@ -338,6 +435,10 @@ export const set: {
   /**
    * Sets the value of the `TxRef`.
    *
+   * **When to use**
+   *
+   * Use to replace the value of a transactional reference.
+   *
    * **Example** (Setting transactional references)
    *
    * ```ts
@@ -362,6 +463,10 @@ export const set: {
   /**
    * Sets the value of the `TxRef`.
    *
+   * **When to use**
+   *
+   * Use to replace the value of a transactional reference.
+   *
    * **Example** (Setting transactional references)
    *
    * ```ts