effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/TxSemaphore.ts

@@ -1,4 +1,22 @@
 /**
+ * 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.
+ *
+ * **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.
+ *
  * @since 4.0.0
  */
 
@@ -19,7 +37,8 @@ const TypeId = "~effect/transactions/TxSemaphore"
  * TxSemaphore provides atomic permit acquisition and release operations within Effect transactions,
  * ensuring thread-safe concurrency control for limited resources.
  *
- * @example
+ * **Example** (Managing permits transactionally)
+ *
  * ```ts
  * import { Effect, TxSemaphore } from "effect"
  *
@@ -39,8 +58,8 @@ const TypeId = "~effect/transactions/TxSemaphore"
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TxSemaphore extends Inspectable, Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -74,7 +93,8 @@ const makeTxSemaphore = (permitsRef: TxRef.TxRef<number>, capacity: number): TxS
 /**
  * Creates a new TxSemaphore with the specified number of permits.
  *
- * @example
+ * **Example** (Creating a semaphore)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -94,12 +114,8 @@ const makeTxSemaphore = (permitsRef: TxRef.TxRef<number>, capacity: number): TxS
  * })
  * ```
  *
- * @param permits - The initial number of permits (must be non-negative)
- * @returns Effect that succeeds with a new TxSemaphore
- * @throws Defect if permits is negative
- *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = (permits: number): Effect.Effect<TxSemaphore> =>
   Effect.gen(function*() {
@@ -114,7 +130,8 @@ export const make = (permits: number): Effect.Effect<TxSemaphore> =>
 /**
  * Gets the current number of available permits in the semaphore.
  *
- * @example
+ * **Example** (Checking available permits)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -135,18 +152,16 @@ export const make = (permits: number): Effect.Effect<TxSemaphore> =>
  * })
  * ```
  *
- * @param self - The TxSemaphore to inspect
- * @returns Effect that succeeds with the current number of available permits
- *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const available = (self: TxSemaphore): Effect.Effect<number> => TxRef.get(self.permitsRef)
 
 /**
  * Gets the maximum capacity (total permits) of the semaphore.
  *
- * @example
+ * **Example** (Checking semaphore capacity)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -163,11 +178,8 @@ export const available = (self: TxSemaphore): Effect.Effect<number> => TxRef.get
  * })
  * ```
  *
- * @param self - The TxSemaphore to inspect
- * @returns Effect that succeeds with the semaphore's maximum capacity
- *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const capacity = (self: TxSemaphore): Effect.Effect<number> => Effect.succeed(self.capacity)
 
@@ -175,7 +187,8 @@ 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.
  *
- * @example
+ * **Example** (Acquiring a permit)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -195,11 +208,8 @@ export const capacity = (self: TxSemaphore): Effect.Effect<number> => Effect.suc
  * })
  * ```
  *
- * @param self - The TxSemaphore from which to acquire a permit
- * @returns Effect that succeeds when a permit is acquired
- *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const acquire = (self: TxSemaphore): Effect.Effect<void> =>
   Effect.gen(function*() {
@@ -211,10 +221,15 @@ export const acquire = (self: TxSemaphore): Effect.Effect<void> =>
   }).pipe(Effect.tx)
 
 /**
- * Acquires the specified number of permits from the semaphore. If not enough
- * permits are available, the effect will block until they become available.
+ * Acquires the specified number of permits from the semaphore.
+ *
+ * If fewer than `n` permits are available, the transaction retries until enough
+ * permits are released. Passing a non-positive `n` dies with a defect. Passing a
+ * value greater than the semaphore capacity will wait forever unless the
+ * semaphore's capacity can somehow be changed externally.
+ *
+ * **Example** (Acquiring multiple permits)
  *
- * @example
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -230,12 +245,8 @@ export const acquire = (self: TxSemaphore): Effect.Effect<void> =>
  * })
  * ```
  *
- * @param self - The TxSemaphore from which to acquire permits
- * @param n - The number of permits to acquire (must be positive)
- * @returns Effect that succeeds when the permits are acquired
- *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const acquireN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
   if (n <= 0) {
@@ -254,7 +265,8 @@ export const acquireN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
  * Tries to acquire a single permit from the semaphore without blocking.
  * Returns true if successful, false if no permits are available.
  *
- * @example
+ * **Example** (Trying to acquire a permit)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -271,11 +283,8 @@ export const acquireN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
  * })
  * ```
  *
- * @param self - The TxSemaphore from which to try acquiring a permit
- * @returns Effect that succeeds with true if permit acquired, false otherwise
- *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const tryAcquire = (self: TxSemaphore): Effect.Effect<boolean> =>
   TxRef.modify(self.permitsRef, (permits: number) => {
@@ -289,7 +298,8 @@ export const tryAcquire = (self: TxSemaphore): Effect.Effect<boolean> =>
  * Tries to acquire the specified number of permits from the semaphore without blocking.
  * Returns true if successful, false if not enough permits are available.
  *
- * @example
+ * **Example** (Trying to acquire multiple permits)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -306,12 +316,8 @@ export const tryAcquire = (self: TxSemaphore): Effect.Effect<boolean> =>
  * })
  * ```
  *
- * @param self - The TxSemaphore from which to try acquiring permits
- * @param n - The number of permits to try acquiring (must be positive)
- * @returns Effect that succeeds with true if permits acquired, false otherwise
- *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const tryAcquireN = (self: TxSemaphore, n: number): Effect.Effect<boolean> => {
   if (n <= 0) {
@@ -326,9 +332,14 @@ export const tryAcquireN = (self: TxSemaphore, n: number): Effect.Effect<boolean
 }
 
 /**
- * Releases a single permit back to the semaphore, making it available for acquisition.
+ * Releases one permit back to the semaphore, making it available for
+ * acquisition.
+ *
+ * If the semaphore is already at capacity, this operation leaves the permit
+ * count unchanged.
+ *
+ * **Example** (Releasing a permit)
  *
- * @example
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -347,11 +358,8 @@ export const tryAcquireN = (self: TxSemaphore, n: number): Effect.Effect<boolean
  * })
  * ```
  *
- * @param self - The TxSemaphore to which to release a permit
- * @returns Effect that succeeds when the permit is released
- *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const release = (self: TxSemaphore): Effect.Effect<void> =>
   TxRef.update(self.permitsRef, (permits: number) => permits >= self.capacity ? permits : permits + 1)
@@ -359,7 +367,11 @@ export const release = (self: TxSemaphore): Effect.Effect<void> =>
 /**
  * Releases the specified number of permits back to the semaphore.
  *
- * @example
+ * The available permit count is capped at the semaphore capacity. Passing a
+ * non-positive `n` dies with a defect.
+ *
+ * **Example** (Releasing multiple permits)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -378,12 +390,8 @@ export const release = (self: TxSemaphore): Effect.Effect<void> =>
  * })
  * ```
  *
- * @param self - The TxSemaphore to which to release permits
- * @param n - The number of permits to release (must be positive)
- * @returns Effect that succeeds when the permits are released
- *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const releaseN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
   if (n <= 0) {
@@ -403,7 +411,8 @@ export const releaseN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
  * **Note**: The permit acquisition and release operations use atomic semantics
  * to ensure proper resource management with Effect's scoped operations.
  *
- * @example
+ * **Example** (Running an effect with a permit)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -426,12 +435,8 @@ export const releaseN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
  * })
  * ```
  *
- * @param self - The TxSemaphore to acquire a permit from
- * @param effect - The effect to execute with the permit
- * @returns Effect that succeeds with the result of the provided effect
- *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const withPermit: {
   /**
@@ -442,7 +447,8 @@ export const withPermit: {
    * **Note**: The permit acquisition and release operations use atomic semantics
    * to ensure proper resource management with Effect's scoped operations.
    *
-   * @example
+   * **Example** (Running an effect with a permit)
+   *
    * ```ts
    * import { Console, Effect, TxSemaphore } from "effect"
    *
@@ -465,12 +471,8 @@ export const withPermit: {
    * })
    * ```
    *
-   * @param self - The TxSemaphore to acquire a permit from
-   * @param effect - The effect to execute with the permit
-   * @returns Effect that succeeds with the result of the provided effect
-   *
-   * @since 4.0.0
    * @category combinators
+   * @since 2.0.0
    */
   (self: TxSemaphore): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
   /**
@@ -481,7 +483,8 @@ export const withPermit: {
    * **Note**: The permit acquisition and release operations use atomic semantics
    * to ensure proper resource management with Effect's scoped operations.
    *
-   * @example
+   * **Example** (Running an effect with a permit)
+   *
    * ```ts
    * import { Console, Effect, TxSemaphore } from "effect"
    *
@@ -504,12 +507,8 @@ export const withPermit: {
    * })
    * ```
    *
-   * @param self - The TxSemaphore to acquire a permit from
-   * @param effect - The effect to execute with the permit
-   * @returns Effect that succeeds with the result of the provided effect
-   *
-   * @since 4.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <A, E, R>(self: TxSemaphore, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = ((...args: Array<any>) => {
@@ -531,14 +530,15 @@ export const withPermit: {
 }) as any
 
 /**
- * Executes an effect with the specified number of permits from the semaphore.
- * The permits are automatically acquired before execution and released afterwards,
- * even if the effect fails or is interrupted.
+ * Runs an effect while holding the specified number of permits from the
+ * semaphore.
  *
- * **Note**: The permit acquisition and release operations use atomic semantics
- * to ensure proper resource management with Effect's scoped operations.
+ * The permits are acquired before the effect starts and released after it
+ * completes, fails, or is interrupted. Passing a non-positive `n` dies with a
+ * defect; passing a value greater than the semaphore capacity can wait forever.
+ *
+ * **Example** (Running an effect with multiple permits)
  *
- * @example
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -561,24 +561,20 @@ export const withPermit: {
  * })
  * ```
  *
- * @param self - The TxSemaphore to acquire permits from
- * @param n - The number of permits to acquire (must be positive)
- * @param effect - The effect to execute with the permits
- * @returns Effect that succeeds with the result of the provided effect
- *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const withPermits: {
   /**
-   * Executes an effect with the specified number of permits from the semaphore.
-   * The permits are automatically acquired before execution and released afterwards,
-   * even if the effect fails or is interrupted.
+   * Runs an effect while holding the specified number of permits from the
+   * semaphore.
    *
-   * **Note**: The permit acquisition and release operations use atomic semantics
-   * to ensure proper resource management with Effect's scoped operations.
+   * The permits are acquired before the effect starts and released after it
+   * completes, fails, or is interrupted. Passing a non-positive `n` dies with a
+   * defect; passing a value greater than the semaphore capacity can wait forever.
+   *
+   * **Example** (Running an effect with multiple permits)
    *
-   * @example
    * ```ts
    * import { Console, Effect, TxSemaphore } from "effect"
    *
@@ -601,24 +597,20 @@ export const withPermits: {
    * })
    * ```
    *
-   * @param self - The TxSemaphore to acquire permits from
-   * @param n - The number of permits to acquire (must be positive)
-   * @param effect - The effect to execute with the permits
-   * @returns Effect that succeeds with the result of the provided effect
-   *
-   * @since 4.0.0
    * @category combinators
+   * @since 2.0.0
    */
   (self: TxSemaphore, n: number): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * Executes an effect with the specified number of permits from the semaphore.
-   * The permits are automatically acquired before execution and released afterwards,
-   * even if the effect fails or is interrupted.
+   * Runs an effect while holding the specified number of permits from the
+   * semaphore.
    *
-   * **Note**: The permit acquisition and release operations use atomic semantics
-   * to ensure proper resource management with Effect's scoped operations.
+   * The permits are acquired before the effect starts and released after it
+   * completes, fails, or is interrupted. Passing a non-positive `n` dies with a
+   * defect; passing a value greater than the semaphore capacity can wait forever.
+   *
+   * **Example** (Running an effect with multiple permits)
    *
-   * @example
    * ```ts
    * import { Console, Effect, TxSemaphore } from "effect"
    *
@@ -641,13 +633,8 @@ export const withPermits: {
    * })
    * ```
    *
-   * @param self - The TxSemaphore to acquire permits from
-   * @param n - The number of permits to acquire (must be positive)
-   * @param effect - The effect to execute with the permits
-   * @returns Effect that succeeds with the result of the provided effect
-   *
-   * @since 4.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <A, E, R>(self: TxSemaphore, n: number, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = ((...args: Array<any>) => {
@@ -676,7 +663,8 @@ export const withPermits: {
  * **Note**: The permit acquisition and release operations use atomic semantics
  * to ensure proper resource management with Effect's scoped operations.
  *
- * @example
+ * **Example** (Acquiring a scoped permit)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -701,11 +689,8 @@ export const withPermits: {
  * })
  * ```
  *
- * @param self - The TxSemaphore to acquire a permit from
- * @returns Effect that succeeds when the permit is acquired (within scope)
- *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const withPermitScoped = (self: TxSemaphore): Effect.Effect<void, never, Scope.Scope> =>
   Effect.acquireRelease(
@@ -716,7 +701,8 @@ export const withPermitScoped = (self: TxSemaphore): Effect.Effect<void, never,
 /**
  * Determines if the provided value is a TxSemaphore.
  *
- * @example
+ * **Example** (Checking semaphore values)
+ *
  * ```ts
  * import { Effect, TxSemaphore } from "effect"
  *
@@ -735,7 +721,7 @@ export const withPermitScoped = (self: TxSemaphore): Effect.Effect<void, never,
  * })
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isTxSemaphore = (u: unknown): u is TxSemaphore => hasProperty(u, TypeId)