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

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