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

package/dist/TxRef.js

@@ -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
  */
@@ -15,6 +68,10 @@ const TypeId = "~effect/transactions/TxRef";
 /**
  * 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
@@ -41,12 +98,12 @@ const TypeId = "~effect/transactions/TxRef";
  */
 export const make = initial => 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)
  *
@@ -77,6 +134,11 @@ export const makeUnsafe = initial => ({
 /**
  * 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
@@ -111,6 +173,10 @@ export const modify = /*#__PURE__*/dual(2, (self, f) => Effect.Transaction.pipe(
 /**
  * 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
@@ -135,6 +201,10 @@ export const update = /*#__PURE__*/dual(2, (self, f) => modify(self, current =>
 /**
  * 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
@@ -159,6 +229,10 @@ export const get = self => modify(self, current => [current, current]);
 /**
  * Sets the value of the `TxRef`.
  *
+ * **When to use**
+ *
+ * Use to replace the value of a transactional reference.
+ *
  * **Example** (Setting transactional references)
  *
  * ```ts

package/dist/TxRef.js.map

@@ -1 +1 @@
-{"version":3,"file":"TxRef.js","names":["Effect","dual","pipeArguments","TypeId","make","initial","sync","makeUnsafe","pending","Map","pipe","arguments","version","value","modify","self","f","Transaction","flatMap","state","journal","has","set","current","get","returnValue","next","tx","update"],"sources":["../src/TxRef.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;AAUA,OAAO,KAAKA,MAAM,MAAM,aAAa;AACrC,SAASC,IAAI,QAAQ,eAAe;AACpC,SAASC,aAAa,QAAQ,eAAe;AAI7C,MAAMC,MAAM,GAAG,4BAA4B;AA2C3C;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,MAAMC,IAAI,GAAOC,OAAU,IAAKL,MAAM,CAACM,IAAI,CAAC,MAAMC,UAAU,CAACF,OAAO,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAME,UAAU,GAAOF,OAAU,KAAgB;EACtD,CAACF,MAAM,GAAGA,MAAM;EAChBK,OAAO,EAAE,IAAIC,GAAG,EAAE;EAClBC,IAAIA,CAAA;IACF,OAAOR,aAAa,CAAC,IAAI,EAAES,SAAS,CAAC;EACvC,CAAC;EACDC,OAAO,EAAE,CAAC;EACVC,KAAK,EAAER;CACR,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMS,MAAM,gBA+Cfb,IAAI,CAAC,CAAC,EAAE,CACVc,IAAc,EACdC,CAAgD,KAEhDhB,MAAM,CAACiB,WAAW,CAACP,IAAI,CACrBV,MAAM,CAACkB,OAAO,CAAEC,KAAK,IACnBnB,MAAM,CAACM,IAAI,CAAC,MAAK;EACf,IAAI,CAACa,KAAK,CAACC,OAAO,CAACC,GAAG,CAACN,IAAI,CAAC,EAAE;IAC5BI,KAAK,CAACC,OAAO,CAACE,GAAG,CAACP,IAAI,EAAE;MAAEH,OAAO,EAAEG,IAAI,CAACH,OAAO;MAAEC,KAAK,EAAEE,IAAI,CAACF;IAAK,CAAE,CAAC;EACvE;EACA,MAAMU,OAAO,GAAGJ,KAAK,CAACC,OAAO,CAACI,GAAG,CAACT,IAAI,CAAE;EACxC,MAAM,CAACU,WAAW,EAAEC,IAAI,CAAC,GAAGV,CAAC,CAACO,OAAO,CAACV,KAAK,CAAC;EAC5CU,OAAO,CAACV,KAAK,GAAGa,IAAI;EACpB,OAAOD,WAAW;AACpB,CAAC,CAAC,CACH,EACDzB,MAAM,CAAC2B,EAAE,CACV,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMC,MAAM,gBAiDf3B,IAAI,CAAC,CAAC,EAAE,CACVc,IAAc,EACdC,CAAoB,KACIF,MAAM,CAACC,IAAI,EAAGQ,OAAO,IAAK,CAAC,KAAK,CAAC,EAAEP,CAAC,CAACO,OAAO,CAAC,CAAC,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMC,GAAG,GAAOT,IAAc,IAAuBD,MAAM,CAACC,IAAI,EAAGQ,OAAO,IAAK,CAACA,OAAO,EAAEA,OAAO,CAAC,CAAC;AAEzG;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMD,GAAG,gBAiDZrB,IAAI,CAAC,CAAC,EAAE,CACVc,IAAc,EACdF,KAAQ,KACgBe,MAAM,CAACb,IAAI,EAAE,MAAMF,KAAK,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"TxRef.js","names":["Effect","dual","pipeArguments","TypeId","make","initial","sync","makeUnsafe","pending","Map","pipe","arguments","version","value","modify","self","f","Transaction","flatMap","state","journal","has","set","current","get","returnValue","next","tx","update"],"sources":["../src/TxRef.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+DA,OAAO,KAAKA,MAAM,MAAM,aAAa;AACrC,SAASC,IAAI,QAAQ,eAAe;AACpC,SAASC,aAAa,QAAQ,eAAe;AAI7C,MAAMC,MAAM,GAAG,4BAA4B;AAgD3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,OAAO,MAAMC,IAAI,GAAOC,OAAU,IAAKL,MAAM,CAACM,IAAI,CAAC,MAAMC,UAAU,CAACF,OAAO,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAME,UAAU,GAAOF,OAAU,KAAgB;EACtD,CAACF,MAAM,GAAGA,MAAM;EAChBK,OAAO,EAAE,IAAIC,GAAG,EAAE;EAClBC,IAAIA,CAAA;IACF,OAAOR,aAAa,CAAC,IAAI,EAAES,SAAS,CAAC;EACvC,CAAC;EACDC,OAAO,EAAE,CAAC;EACVC,KAAK,EAAER;CACR,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,MAAMS,MAAM,gBAyDfb,IAAI,CAAC,CAAC,EAAE,CACVc,IAAc,EACdC,CAAgD,KAEhDhB,MAAM,CAACiB,WAAW,CAACP,IAAI,CACrBV,MAAM,CAACkB,OAAO,CAAEC,KAAK,IACnBnB,MAAM,CAACM,IAAI,CAAC,MAAK;EACf,IAAI,CAACa,KAAK,CAACC,OAAO,CAACC,GAAG,CAACN,IAAI,CAAC,EAAE;IAC5BI,KAAK,CAACC,OAAO,CAACE,GAAG,CAACP,IAAI,EAAE;MAAEH,OAAO,EAAEG,IAAI,CAACH,OAAO;MAAEC,KAAK,EAAEE,IAAI,CAACF;IAAK,CAAE,CAAC;EACvE;EACA,MAAMU,OAAO,GAAGJ,KAAK,CAACC,OAAO,CAACI,GAAG,CAACT,IAAI,CAAE;EACxC,MAAM,CAACU,WAAW,EAAEC,IAAI,CAAC,GAAGV,CAAC,CAACO,OAAO,CAACV,KAAK,CAAC;EAC5CU,OAAO,CAACV,KAAK,GAAGa,IAAI;EACpB,OAAOD,WAAW;AACpB,CAAC,CAAC,CACH,EACDzB,MAAM,CAAC2B,EAAE,CACV,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,MAAMC,MAAM,gBAyDf3B,IAAI,CAAC,CAAC,EAAE,CACVc,IAAc,EACdC,CAAoB,KACIF,MAAM,CAACC,IAAI,EAAGQ,OAAO,IAAK,CAAC,KAAK,CAAC,EAAEP,CAAC,CAACO,OAAO,CAAC,CAAC,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,MAAMC,GAAG,GAAOT,IAAc,IAAuBD,MAAM,CAACC,IAAI,EAAGQ,OAAO,IAAK,CAACA,OAAO,EAAEA,OAAO,CAAC,CAAC;AAEzG;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,MAAMD,GAAG,gBAyDZrB,IAAI,CAAC,CAAC,EAAE,CACVc,IAAc,EACdF,KAAQ,KACgBe,MAAM,CAACb,IAAI,EAAE,MAAMF,KAAK,CAAC,CAAC","ignoreList":[]}

package/dist/TxSemaphore.d.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
  */
@@ -31,6 +49,11 @@ declare 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
@@ -52,6 +75,10 @@ declare 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
  */
@@ -63,6 +90,10 @@ export interface TxSemaphore extends Inspectable, Pipeable {
 /**
  * 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
@@ -84,6 +115,9 @@ export interface TxSemaphore extends Inspectable, Pipeable {
  * })
  * ```
  *
+ * @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
  */
@@ -91,6 +125,10 @@ export declare 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
@@ -113,6 +151,8 @@ export declare const make: (permits: number) => Effect.Effect<TxSemaphore>;
  * })
  * ```
  *
+ * @see {@link capacity} for reading the fixed total permit count
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -120,6 +160,10 @@ export declare const available: (self: TxSemaphore) => Effect.Effect<number>;
 /**
  * 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
@@ -138,6 +182,8 @@ export declare const available: (self: TxSemaphore) => Effect.Effect<number>;
  * })
  * ```
  *
+ * @see {@link available} for reading the current available permit count
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -146,6 +192,11 @@ export declare const capacity: (self: TxSemaphore) => Effect.Effect<number>;
  * 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
@@ -167,6 +218,10 @@ export declare const capacity: (self: TxSemaphore) => Effect.Effect<number>;
  * })
  * ```
  *
+ * @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
  */
@@ -174,6 +229,11 @@ export declare 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
@@ -201,6 +261,10 @@ export declare 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
  */
@@ -209,6 +273,11 @@ export declare const acquireN: (self: TxSemaphore, n: number) => Effect.Effect<v
  * 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
@@ -227,6 +296,9 @@ export declare const acquireN: (self: TxSemaphore, n: number) => Effect.Effect<v
  * })
  * ```
  *
+ * @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
  */
@@ -236,6 +308,11 @@ export declare 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
@@ -254,6 +331,9 @@ export declare 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
  */
@@ -262,6 +342,10 @@ export declare const tryAcquireN: (self: TxSemaphore, n: number) => Effect.Effec
  * 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
@@ -287,6 +371,9 @@ export declare const tryAcquireN: (self: TxSemaphore, n: number) => Effect.Effec
  * })
  * ```
  *
+ * @see {@link acquire} for manually acquiring one permit
+ * @see {@link releaseN} for returning multiple permits
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -294,6 +381,10 @@ export declare 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.
@@ -322,6 +413,9 @@ export declare 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
  */
@@ -331,6 +425,11 @@ export declare const releaseN: (self: TxSemaphore, n: number) => Effect.Effect<v
  * 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
@@ -360,6 +459,10 @@ export declare const releaseN: (self: TxSemaphore, n: number) => Effect.Effect<v
  * })
  * ```
  *
+ * @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
  */
@@ -369,6 +472,11 @@ export declare 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
@@ -398,6 +506,10 @@ export declare 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
      */
@@ -407,6 +519,11 @@ export declare 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
@@ -436,6 +553,10 @@ export declare 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
      */
@@ -445,6 +566,11 @@ export declare 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
@@ -479,6 +605,9 @@ export declare 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
  */
@@ -487,6 +616,11 @@ export declare 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
@@ -521,6 +655,9 @@ export declare 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
      */
@@ -529,6 +666,11 @@ export declare 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
@@ -563,6 +705,9 @@ export declare 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
      */
@@ -573,6 +718,11 @@ export declare 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
@@ -604,6 +754,9 @@ export declare 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
  */
@@ -611,6 +764,10 @@ export declare const withPermitScoped: (self: TxSemaphore) => Effect.Effect<void
 /**
  * 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
@@ -631,6 +788,8 @@ export declare const withPermitScoped: (self: TxSemaphore) => Effect.Effect<void
  * })
  * ```
  *
+ * @see {@link make} for creating a `TxSemaphore`
+ *
  * @category guards
  * @since 4.0.0
  */

package/dist/TxSemaphore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TxSemaphore.d.ts","sourceRoot":"","sources":["../src/TxSemaphore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TxSemaphore.d.ts","sourceRoot":"","sources":["../src/TxSemaphore.ts"],"names":[],"mappings":"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"}