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

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
@@ -87,12 +149,12 @@ export interface TxRef<in out A> extends Pipeable {
 export const make = <A>(initial: A) => Effect.sync(() => makeUnsafe(initial))
 
 /**
- * Synchronously creates a new `TxRef` with the specified initial value.
+ * Creates a new `TxRef` synchronously with the specified initial value.
  *
  * **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

package/src/TxSemaphore.ts

@@ -1,21 +1,39 @@
 /**
- * The `TxSemaphore` module provides a transactional semaphore for coordinating
- * access to limited resources from within Effect transactions. A semaphore
- * tracks a fixed number of permits, and transactional operations can acquire,
- * release, or inspect those permits atomically with other transactional state.
- *
- * Use `TxSemaphore` when permit accounting needs to compose with `TxRef` and
- * other transactional updates, such as guarding resource pools, rate-limited
- * sections, or workflows that must reserve capacity consistently before
- * committing related state changes.
+ * Coordinate access to limited resources with a semaphore whose permit count
+ * participates in Effect transactions. A `TxSemaphore` keeps a fixed capacity
+ * and records permit changes in transactional state, so acquiring or releasing
+ * permits can commit atomically with related `TxRef` updates.
+ *
+ * **Mental model**
+ *
+ * - {@link make} creates a semaphore with a fixed number of permits.
+ * - {@link acquire} and {@link acquireN} wait by retrying the transaction when
+ *   there are not enough permits available.
+ * - {@link tryAcquire} and {@link tryAcquireN} update the permit count only
+ *   when enough permits are already available.
+ * - {@link release} and {@link releaseN} return permits, and the total cannot
+ *   exceed the original capacity.
+ * - {@link withPermit} and {@link withPermits} bracket a supplied effect,
+ *   while {@link withPermitScoped} holds one permit until the current scope
+ *   closes.
+ *
+ * **Common tasks**
+ *
+ * - Reserve capacity before committing related transactional state changes.
+ * - Protect a pool, queue, or rate-limited section with permit accounting that
+ *   composes with `TxRef`.
+ * - Inspect the current number of permits with {@link available} and the fixed
+ *   total with {@link capacity}.
  *
  * **Gotchas**
  *
- * - Permit operations are intended for transactional workflows and are wrapped
- *   with `Effect.tx`.
- * - The semaphore capacity is fixed at construction time; releasing more
- *   permits than the original capacity fails.
- * - Creating a semaphore with a negative number of permits defects.
+ * - Permit operations enter `Effect.tx`; group related transactional
+ *   work inside the same boundary when it must commit together.
+ * - Requesting more permits than the semaphore capacity with
+ *   {@link acquireN} can wait forever because the capacity never grows.
+ * - Creating a semaphore with negative permits, acquiring a non-positive number
+ *   of permits, or releasing a non-positive number of permits defects.
+ * - Extra releases are capped at the fixed capacity.
  *
  * @since 4.0.0
  */
@@ -37,6 +55,11 @@ const TypeId = "~effect/transactions/TxSemaphore"
  * operations within Effect transactions for concurrency control over limited
  * resources.
  *
+ * **When to use**
+ *
+ * Use to coordinate permit accounting atomically with other transactional
+ * state changes.
+ *
  * **Example** (Managing permits transactionally)
  *
  * ```ts
@@ -58,6 +81,10 @@ const TypeId = "~effect/transactions/TxSemaphore"
  * })
  * ```
  *
+ * @see {@link make} for creating a transactional semaphore
+ * @see {@link withPermit} for automatically acquiring and releasing one permit
+ * @see {@link acquire} for manually acquiring one permit transactionally
+ *
  * @category models
  * @since 4.0.0
  */
@@ -93,6 +120,10 @@ const makeTxSemaphore = (permitsRef: TxRef.TxRef<number>, capacity: number): TxS
 /**
  * Creates a new TxSemaphore with the specified number of permits.
  *
+ * **When to use**
+ *
+ * Use to create a transactional semaphore with a fixed permit capacity.
+ *
  * **Example** (Creating a semaphore)
  *
  * ```ts
@@ -114,6 +145,9 @@ const makeTxSemaphore = (permitsRef: TxRef.TxRef<number>, capacity: number): TxS
  * })
  * ```
  *
+ * @see {@link available} for reading the current available permit count
+ * @see {@link capacity} for reading the fixed total permit count
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -130,6 +164,10 @@ export const make = (permits: number): Effect.Effect<TxSemaphore> =>
 /**
  * Gets the current number of available permits in the semaphore.
  *
+ * **When to use**
+ *
+ * Use to inspect how many permits are currently available.
+ *
  * **Example** (Checking available permits)
  *
  * ```ts
@@ -152,6 +190,8 @@ export const make = (permits: number): Effect.Effect<TxSemaphore> =>
  * })
  * ```
  *
+ * @see {@link capacity} for reading the fixed total permit count
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -160,6 +200,10 @@ export const available = (self: TxSemaphore): Effect.Effect<number> => TxRef.get
 /**
  * Gets the maximum capacity (total permits) of the semaphore.
  *
+ * **When to use**
+ *
+ * Use to inspect the fixed total number of permits managed by the semaphore.
+ *
  * **Example** (Checking semaphore capacity)
  *
  * ```ts
@@ -178,6 +222,8 @@ export const available = (self: TxSemaphore): Effect.Effect<number> => TxRef.get
  * })
  * ```
  *
+ * @see {@link available} for reading the current available permit count
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -187,6 +233,11 @@ export const capacity = (self: TxSemaphore): Effect.Effect<number> => Effect.suc
  * Acquires a single permit from the semaphore. If no permits are available,
  * the effect will block until one becomes available.
  *
+ * **When to use**
+ *
+ * Use to manually acquire one permit transactionally, waiting until one is
+ * available.
+ *
  * **Example** (Acquiring a permit)
  *
  * ```ts
@@ -208,6 +259,10 @@ export const capacity = (self: TxSemaphore): Effect.Effect<number> => Effect.suc
  * })
  * ```
  *
+ * @see {@link tryAcquire} for a non-blocking single-permit attempt
+ * @see {@link release} for returning one permit
+ * @see {@link withPermit} for automatic acquire and release around an effect
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -223,6 +278,11 @@ export const acquire = (self: TxSemaphore): Effect.Effect<void> =>
 /**
  * Acquires the specified number of permits from the semaphore.
  *
+ * **When to use**
+ *
+ * Use to manually acquire multiple permits transactionally, waiting until all
+ * requested permits are available.
+ *
  * **Details**
  *
  * If fewer than `n` permits are available, the transaction retries until enough
@@ -250,6 +310,10 @@ export const acquire = (self: TxSemaphore): Effect.Effect<void> =>
  * })
  * ```
  *
+ * @see {@link tryAcquireN} for a non-blocking multi-permit attempt
+ * @see {@link releaseN} for returning multiple permits
+ * @see {@link withPermits} for automatic acquire and release around an effect
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -270,6 +334,11 @@ export const acquireN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
  * Tries to acquire a single permit from the semaphore without blocking,
  * returning `true` if successful or `false` if no permits are available.
  *
+ * **When to use**
+ *
+ * Use to attempt a single-permit acquisition without retrying when no permit is
+ * available.
+ *
  * **Example** (Trying to acquire a permit)
  *
  * ```ts
@@ -288,6 +357,9 @@ export const acquireN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
  * })
  * ```
  *
+ * @see {@link acquire} for waiting until one permit is available
+ * @see {@link tryAcquireN} for attempting to acquire multiple permits without blocking
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -304,6 +376,11 @@ export const tryAcquire = (self: TxSemaphore): Effect.Effect<boolean> =>
  * blocking, returning `true` if successful or `false` if not enough permits are
  * available.
  *
+ * **When to use**
+ *
+ * Use to attempt a multi-permit acquisition without retrying when not enough
+ * permits are available.
+ *
  * **Example** (Trying to acquire multiple permits)
  *
  * ```ts
@@ -322,6 +399,9 @@ export const tryAcquire = (self: TxSemaphore): Effect.Effect<boolean> =>
  * })
  * ```
  *
+ * @see {@link acquireN} for waiting until all requested permits are available
+ * @see {@link tryAcquire} for attempting to acquire one permit without blocking
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -341,6 +421,10 @@ export const tryAcquireN = (self: TxSemaphore, n: number): Effect.Effect<boolean
  * Releases one permit back to the semaphore, making it available for
  * acquisition.
  *
+ * **When to use**
+ *
+ * Use to manually return one permit after a transactional acquire.
+ *
  * **Details**
  *
  * If the semaphore is already at capacity, this operation leaves the permit
@@ -366,6 +450,9 @@ export const tryAcquireN = (self: TxSemaphore, n: number): Effect.Effect<boolean
  * })
  * ```
  *
+ * @see {@link acquire} for manually acquiring one permit
+ * @see {@link releaseN} for returning multiple permits
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -375,6 +462,10 @@ export const release = (self: TxSemaphore): Effect.Effect<void> =>
 /**
  * Releases the specified number of permits back to the semaphore.
  *
+ * **When to use**
+ *
+ * Use to manually return multiple permits after a transactional acquire.
+ *
  * **Details**
  *
  * The available permit count is capped at the semaphore capacity.
@@ -403,6 +494,9 @@ export const release = (self: TxSemaphore): Effect.Effect<void> =>
  * })
  * ```
  *
+ * @see {@link acquireN} for manually acquiring multiple permits
+ * @see {@link release} for returning one permit
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -421,6 +515,11 @@ export const releaseN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
  * automatically acquired before execution and released afterwards, even if the
  * effect fails or is interrupted.
  *
+ * **When to use**
+ *
+ * Use to run an effect while automatically acquiring and releasing one
+ * transactional permit.
+ *
  * **Details**
  *
  * The permit acquisition and release operations use atomic semantics to ensure
@@ -450,6 +549,10 @@ export const releaseN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
  * })
  * ```
  *
+ * @see {@link withPermits} for automatically acquiring and releasing multiple permits
+ * @see {@link withPermitScoped} for acquiring one permit for the current scope
+ * @see {@link acquire} for manual single-permit acquisition
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -459,6 +562,11 @@ export const withPermit: {
    * automatically acquired before execution and released afterwards, even if the
    * effect fails or is interrupted.
    *
+   * **When to use**
+   *
+   * Use to run an effect while automatically acquiring and releasing one
+   * transactional permit.
+   *
    * **Details**
    *
    * The permit acquisition and release operations use atomic semantics to ensure
@@ -488,6 +596,10 @@ export const withPermit: {
    * })
    * ```
    *
+   * @see {@link withPermits} for automatically acquiring and releasing multiple permits
+   * @see {@link withPermitScoped} for acquiring one permit for the current scope
+   * @see {@link acquire} for manual single-permit acquisition
+   *
    * @category combinators
    * @since 2.0.0
    */
@@ -497,6 +609,11 @@ export const withPermit: {
    * automatically acquired before execution and released afterwards, even if the
    * effect fails or is interrupted.
    *
+   * **When to use**
+   *
+   * Use to run an effect while automatically acquiring and releasing one
+   * transactional permit.
+   *
    * **Details**
    *
    * The permit acquisition and release operations use atomic semantics to ensure
@@ -526,6 +643,10 @@ export const withPermit: {
    * })
    * ```
    *
+   * @see {@link withPermits} for automatically acquiring and releasing multiple permits
+   * @see {@link withPermitScoped} for acquiring one permit for the current scope
+   * @see {@link acquire} for manual single-permit acquisition
+   *
    * @category combinators
    * @since 2.0.0
    */
@@ -552,6 +673,11 @@ export const withPermit: {
  * Runs an effect while holding the specified number of permits from the
  * semaphore.
  *
+ * **When to use**
+ *
+ * Use to run an effect while automatically acquiring and releasing multiple
+ * transactional permits.
+ *
  * **Details**
  *
  * The permits are acquired before the effect starts and released after it
@@ -586,6 +712,9 @@ export const withPermit: {
  * })
  * ```
  *
+ * @see {@link withPermit} for automatically acquiring and releasing one permit
+ * @see {@link acquireN} for manual multi-permit acquisition
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -594,6 +723,11 @@ export const withPermits: {
    * Runs an effect while holding the specified number of permits from the
    * semaphore.
    *
+   * **When to use**
+   *
+   * Use to run an effect while automatically acquiring and releasing multiple
+   * transactional permits.
+   *
    * **Details**
    *
    * The permits are acquired before the effect starts and released after it
@@ -628,6 +762,9 @@ export const withPermits: {
    * })
    * ```
    *
+   * @see {@link withPermit} for automatically acquiring and releasing one permit
+   * @see {@link acquireN} for manual multi-permit acquisition
+   *
    * @category combinators
    * @since 2.0.0
    */
@@ -636,6 +773,11 @@ export const withPermits: {
    * Runs an effect while holding the specified number of permits from the
    * semaphore.
    *
+   * **When to use**
+   *
+   * Use to run an effect while automatically acquiring and releasing multiple
+   * transactional permits.
+   *
    * **Details**
    *
    * The permits are acquired before the effect starts and released after it
@@ -670,6 +812,9 @@ export const withPermits: {
    * })
    * ```
    *
+   * @see {@link withPermit} for automatically acquiring and releasing one permit
+   * @see {@link acquireN} for manual multi-permit acquisition
+   *
    * @category combinators
    * @since 2.0.0
    */
@@ -697,6 +842,11 @@ export const withPermits: {
  * will be automatically released when the scope is closed, even if effects
  * within the scope fail or are interrupted.
  *
+ * **When to use**
+ *
+ * Use to acquire one transactional permit for the lifetime of the current
+ * scope.
+ *
  * **Details**
  *
  * The permit acquisition and release operations use atomic semantics to ensure
@@ -728,6 +878,9 @@ export const withPermits: {
  * })
  * ```
  *
+ * @see {@link withPermit} for acquiring one permit around a single effect
+ * @see {@link acquire} for manual single-permit acquisition
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -740,6 +893,10 @@ export const withPermitScoped = (self: TxSemaphore): Effect.Effect<void, never,
 /**
  * Determines if the provided value is a TxSemaphore.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before treating it as a `TxSemaphore`.
+ *
  * **Example** (Checking semaphore values)
  *
  * ```ts
@@ -760,6 +917,8 @@ export const withPermitScoped = (self: TxSemaphore): Effect.Effect<void, never,
  * })
  * ```
  *
+ * @see {@link make} for creating a `TxSemaphore`
+ *
  * @category guards
  * @since 4.0.0
  */