effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/TxRef.js

@@ -15,9 +15,8 @@ const TypeId = "~effect/transactions/TxRef";
 /**
  * Creates a new `TxRef` with the specified initial value.
  *
- * @since 4.0.0
- * @category Constructors
- * @example
+ * **Example** (Creating transactional references)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -36,14 +35,19 @@ const TypeId = "~effect/transactions/TxRef";
  *   console.log(yield* TxRef.get(name)) // "Bob"
  * })
  * ```
+ *
+ * @category Constructors
+ * @since 4.0.0
  */
 export const make = initial => Effect.sync(() => makeUnsafe(initial));
 /**
- * Creates a new `TxRef` with the specified initial value.
+ * Synchronously creates a new `TxRef` with the specified initial value.
+ *
+ * Prefer `make` in Effect code so allocation stays inside the Effect workflow.
+ * Use `makeUnsafe` only when a `TxRef` must be constructed outside an effect.
+ *
+ * **Example** (Creating transactional references unsafely)
  *
- * @since 4.0.0
- * @category Constructors
- * @example
  * ```ts
  * import { TxRef } from "effect"
  *
@@ -55,6 +59,9 @@ export const make = initial => Effect.sync(() => makeUnsafe(initial));
  * console.log(counter.value) // 0
  * console.log(config.value) // { timeout: 5000, retries: 3 }
  * ```
+ *
+ * @category Constructors
+ * @since 4.0.0
  */
 export const makeUnsafe = initial => ({
   [TypeId]: TypeId,
@@ -68,9 +75,8 @@ export const makeUnsafe = initial => ({
 /**
  * Modifies the value of the `TxRef` using the provided function.
  *
- * @since 4.0.0
- * @category Combinators
- * @example
+ * **Example** (Modifying transactional references)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -84,6 +90,9 @@ export const makeUnsafe = initial => ({
  *   console.log(yield* TxRef.get(counter)) // 1 (the new value: current + 1)
  * })
  * ```
+ *
+ * @category Combinators
+ * @since 4.0.0
  */
 export const modify = /*#__PURE__*/dual(2, (self, f) => Effect.Transaction.pipe(Effect.flatMap(state => Effect.sync(() => {
   if (!state.journal.has(self)) {
@@ -100,9 +109,8 @@ export const modify = /*#__PURE__*/dual(2, (self, f) => Effect.Transaction.pipe(
 /**
  * Updates the value of the `TxRef` using the provided function.
  *
- * @since 4.0.0
- * @category Combinators
- * @example
+ * **Example** (Updating transactional references)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -117,14 +125,16 @@ export const modify = /*#__PURE__*/dual(2, (self, f) => Effect.Transaction.pipe(
  *   console.log(yield* TxRef.get(counter)) // 20
  * })
  * ```
+ *
+ * @category Combinators
+ * @since 4.0.0
  */
 export const update = /*#__PURE__*/dual(2, (self, f) => modify(self, current => [void 0, f(current)]));
 /**
  * Reads the current value of the `TxRef`.
  *
- * @since 4.0.0
- * @category Combinators
- * @example
+ * **Example** (Reading transactional references)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -139,14 +149,16 @@ export const update = /*#__PURE__*/dual(2, (self, f) => modify(self, current =>
  *   console.log(value) // 42
  * })
  * ```
+ *
+ * @category Combinators
+ * @since 4.0.0
  */
 export const get = self => modify(self, current => [current, current]);
 /**
  * Sets the value of the `TxRef`.
  *
- * @since 4.0.0
- * @category Combinators
- * @example
+ * **Example** (Setting transactional references)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -161,6 +173,9 @@ export const get = self => modify(self, current => [current, current]);
  *   console.log(yield* TxRef.get(counter)) // 100
  * })
  * ```
+ *
+ * @category Combinators
+ * @since 4.0.0
  */
 export const set = /*#__PURE__*/dual(2, (self, value) => update(self, () => value));
 //# sourceMappingURL=TxRef.js.map

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;AAuC3C;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMC,IAAI,GAAOC,OAAU,IAAKL,MAAM,CAACM,IAAI,CAAC,MAAMC,UAAU,CAACF,OAAO,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;AAkBA,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;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAMS,MAAM,gBA2Cfb,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;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAMC,MAAM,gBA6Cf3B,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;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAMC,GAAG,GAAOT,IAAc,IAAuBD,MAAM,CAACC,IAAI,EAAGQ,OAAO,IAAK,CAACA,OAAO,EAAEA,OAAO,CAAC,CAAC;AAEzG;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAMD,GAAG,gBA6CZrB,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;;;;;;;;;;AAUA,OAAO,KAAKA,MAAM,MAAM,aAAa;AACrC,SAASC,IAAI,QAAQ,eAAe;AACpC,SAASC,aAAa,QAAQ,eAAe;AAI7C,MAAMC,MAAM,GAAG,4BAA4B;AAyC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,MAAMC,IAAI,GAAOC,OAAU,IAAKL,MAAM,CAACM,IAAI,CAAC,MAAMC,UAAU,CAACF,OAAO,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;AAuBA,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":[]}

package/dist/TxSemaphore.d.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
  */
 import * as Effect from "./Effect.ts";
@@ -13,7 +31,8 @@ declare 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"
  *
@@ -33,8 +52,8 @@ declare 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;
@@ -44,7 +63,8 @@ export interface TxSemaphore extends Inspectable, Pipeable {
 /**
  * Creates a new TxSemaphore with the specified number of permits.
  *
- * @example
+ * **Example** (Creating a semaphore)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -68,14 +88,15 @@ export interface TxSemaphore extends Inspectable, Pipeable {
  * @returns Effect that succeeds with a new TxSemaphore
  * @throws Defect if permits is negative
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare 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"
  *
@@ -99,14 +120,15 @@ export declare 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 4.0.0
  */
 export declare const available: (self: TxSemaphore) => Effect.Effect<number>;
 /**
  * Gets the maximum capacity (total permits) of the semaphore.
  *
- * @example
+ * **Example** (Checking semaphore capacity)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -126,15 +148,16 @@ export declare const available: (self: TxSemaphore) => Effect.Effect<number>;
  * @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 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.
  *
- * @example
+ * **Example** (Acquiring a permit)
+ *
  * ```ts
  * import { Console, Effect, TxSemaphore } from "effect"
  *
@@ -157,15 +180,20 @@ export declare const capacity: (self: TxSemaphore) => Effect.Effect<number>;
  * @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 4.0.0
  */
 export declare const acquire: (self: TxSemaphore) => Effect.Effect<void>;
 /**
- * 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"
  *
@@ -185,15 +213,16 @@ export declare const acquire: (self: TxSemaphore) => Effect.Effect<void>;
  * @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 4.0.0
  */
 export declare 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"
  *
@@ -213,15 +242,16 @@ export declare const acquireN: (self: TxSemaphore, n: number) => Effect.Effect<v
  * @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 declare 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"
  *
@@ -242,14 +272,19 @@ export declare const tryAcquire: (self: TxSemaphore) => Effect.Effect<boolean>;
  * @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 declare 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"
  *
@@ -271,14 +306,18 @@ export declare const tryAcquireN: (self: TxSemaphore, n: number) => Effect.Effec
  * @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 4.0.0
  */
 export declare 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"
  *
@@ -301,8 +340,8 @@ export declare const release: (self: TxSemaphore) => Effect.Effect<void>;
  * @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 4.0.0
  */
 export declare const releaseN: (self: TxSemaphore, n: number) => Effect.Effect<void>;
 /**
@@ -313,7 +352,8 @@ export declare const releaseN: (self: TxSemaphore, n: number) => Effect.Effect<v
  * **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"
  *
@@ -340,8 +380,8 @@ export declare const releaseN: (self: TxSemaphore, n: number) => Effect.Effect<v
  * @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 4.0.0
  */
 export declare const withPermit: {
     /**
@@ -352,7 +392,8 @@ export declare 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"
      *
@@ -379,8 +420,8 @@ export declare const withPermit: {
      * @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 4.0.0
      */
     (self: TxSemaphore): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
     /**
@@ -391,7 +432,8 @@ export declare 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"
      *
@@ -418,20 +460,21 @@ export declare const withPermit: {
      * @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 4.0.0
      */
     <A, E, R>(self: TxSemaphore, 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"
  *
@@ -459,19 +502,20 @@ export declare const withPermit: {
  * @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 4.0.0
  */
 export declare 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"
      *
@@ -499,19 +543,20 @@ export declare const withPermits: {
      * @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 4.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"
      *
@@ -539,8 +584,8 @@ export declare const withPermits: {
      * @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 4.0.0
      */
     <A, E, R>(self: TxSemaphore, n: number, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>;
 };
@@ -552,7 +597,8 @@ export declare 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"
  *
@@ -580,14 +626,15 @@ export declare 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 4.0.0
  */
 export declare const withPermitScoped: (self: TxSemaphore) => Effect.Effect<void, never, Scope.Scope>;
 /**
  * Determines if the provided value is a TxSemaphore.
  *
- * @example
+ * **Example** (Checking semaphore values)
+ *
  * ```ts
  * import { Effect, TxSemaphore } from "effect"
  *
@@ -606,8 +653,8 @@ export declare const withPermitScoped: (self: TxSemaphore) => Effect.Effect<void
  * })
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isTxSemaphore: (u: unknown) => u is TxSemaphore;
 export {};

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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"}