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

package/dist/ScopedRef.js

@@ -47,6 +47,12 @@ const makeUnsafe = (scope, value) => {
  * Creates a new `ScopedRef` from an effect that resourcefully produces a
  * value.
  *
+ * **When to use**
+ *
+ * Use when creating a `ScopedRef` whose initial value requires acquiring
+ * resources that must be released.
+ *
+ * @see {@link make} for creating a `ScopedRef` from a value that does not require resource acquisition
  * @category constructors
  * @since 2.0.0
  */
@@ -58,22 +64,54 @@ export const fromAcquire = /*#__PURE__*/Effect.fnUntraced(function* (acquire) {
   return self;
 }, Effect.uninterruptible);
 /**
- * Retrieves the current value of the scoped reference.
+ * Retrieves the current value of the scoped reference synchronously.
+ *
+ * **When to use**
+ *
+ * Use when you need immediate synchronous access to the current `ScopedRef`
+ * value and can guarantee that reading outside the `Effect` API is safe.
+ *
+ * @see {@link get} for Effect-wrapped access in Effect programs
  *
  * @category getters
  * @since 4.0.0
  */
 export const getUnsafe = self => self.backing.backing.ref.current[1];
 /**
- * Retrieves the current value of the scoped reference.
+ * Retrieves the current value of the scoped reference effectfully.
+ *
+ * **When to use**
+ *
+ * Use to read the value currently stored in a `ScopedRef` inside an `Effect`
+ * workflow.
+ *
+ * @see {@link getUnsafe} for reading the current value synchronously when an unsafe read is acceptable
  *
  * @category getters
  * @since 2.0.0
  */
 export const get = self => Effect.sync(() => getUnsafe(self));
 /**
- * Creates a new `ScopedRef` from the specified value. This method should
- * not be used for values whose creation require the acquisition of resources.
+ * Creates a new `ScopedRef` from the specified value.
+ *
+ * **When to use**
+ *
+ * Use to create a `ScopedRef` when the initial value is already available or
+ * can be produced without acquiring resources.
+ *
+ * **Details**
+ *
+ * The `evaluate` function runs when the returned effect runs. The returned
+ * effect requires a `Scope`, and the reference closes the currently stored
+ * value's scope when that outer scope closes.
+ *
+ * **Gotchas**
+ *
+ * Do not use `make` for an initial value whose creation acquires resources; use
+ * `fromAcquire` so acquisition and finalization are tracked.
+ *
+ * @see {@link fromAcquire} for creating a `ScopedRef` from an effect that acquires the initial value
+ * @see {@link set} for replacing the current value with a resourcefully acquired value
  *
  * @category constructors
  * @since 2.0.0
@@ -88,13 +126,19 @@ export const make = evaluate => Effect.suspend(() => {
  * Sets the value of this reference to the specified resourcefully-created
  * value, releasing any resources associated with the old value.
  *
+ * **When to use**
+ *
+ * Use to replace the current value of an existing `ScopedRef` with a
+ * resourcefully acquired value while releasing resources for the previous
+ * value.
+ *
  * **Details**
  *
  * This method will not return until either the reference is successfully
  * changed to the new value, with old resources released, or until the attempt
  * to acquire a new value fails.
  *
- * @category getters
+ * @category setters
  * @since 2.0.0
  */
 export const set = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(function* (self, acquire) {

package/dist/ScopedRef.js.map

@@ -1 +1 @@
-{"version":3,"file":"ScopedRef.js","names":["Effect","Exit","dual","PipeInspectableProto","Scope","Synchronized","TypeId","Proto","toJSON","_id","value","backing","ref","current","makeUnsafe","scope","self","Object","create","fromAcquire","fnUntraced","acquire","pipe","provide","tapCause","cause","close","failCause","addFinalizer","exit","uninterruptible","getUnsafe","get","sync","make","evaluate","suspend","as","set","void","effect","semaphore","withPermit"],"sources":["../src/ScopedRef.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"ScopedRef.js","names":["Effect","Exit","dual","PipeInspectableProto","Scope","Synchronized","TypeId","Proto","toJSON","_id","value","backing","ref","current","makeUnsafe","scope","self","Object","create","fromAcquire","fnUntraced","acquire","pipe","provide","tapCause","cause","close","failCause","addFinalizer","exit","uninterruptible","getUnsafe","get","sync","make","evaluate","suspend","as","set","void","effect","semaphore","withPermit"],"sources":["../src/ScopedRef.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/Semaphore.d.ts

@@ -1,22 +1,34 @@
 /**
- * The `Semaphore` module provides a counting semaphore for coordinating
- * concurrent access to shared or limited resources. A semaphore tracks a fixed
- * number of permits: effects acquire permits before entering a critical section
- * and release them when they leave.
- *
- * Use semaphores to bound parallel work, protect rate-limited services, or
- * serialize access to resources that cannot safely handle unlimited
- * concurrency. Prefer {@link withPermit} and {@link withPermits} when possible,
- * because they release permits automatically when the protected effect exits.
- * Use {@link take} and {@link release} for lower-level protocols that need
- * manual control.
+ * The `Semaphore` module provides counting semaphores for limiting concurrent
+ * access to shared resources. A semaphore owns a pool of permits; effects take
+ * permits before running protected work and return them when the work exits.
+ *
+ * **Mental model**
+ *
+ * - The permit count is the maximum amount of guarded work that can run at once
+ * - {@link withPermit} and {@link withPermits} acquire permits around one
+ *   effect and release them on success, failure, or interruption
+ * - {@link take} and {@link release} expose the lower-level protocol when
+ *   acquisition and release cannot be scoped to one effect
+ * - {@link resize} changes future availability while preserving permits that
+ *   are already taken
+ *
+ * **Common tasks**
+ *
+ * - Create a semaphore: {@link make}, {@link makeUnsafe}
+ * - Guard one effect: {@link withPermit}, {@link withPermits}
+ * - Run only when permits are immediately available:
+ *   {@link withPermitsIfAvailable}
+ * - Manage permits manually: {@link take}, {@link release}, {@link releaseAll}
+ * - Change capacity: {@link resize}
  *
  * **Gotchas**
  *
- * - Pending acquisitions wait until enough permits are available.
- * - {@link withPermitsIfAvailable} does not wait; it returns `Option.none` when
- *   the requested permits cannot be acquired immediately.
- * - Manual `take` / `release` usage must keep permit counts balanced.
+ * - Pending acquisitions wait until enough permits are available
+ * - {@link withPermitsIfAvailable} never waits; it returns `Option.none` when
+ *   the requested permits are not available immediately
+ * - Manual {@link take} / {@link release} usage must keep permit counts
+ *   balanced; prefer scoped helpers when possible
  *
  * @since 4.0.0
  */
@@ -25,6 +37,11 @@ import type * as Option from "./Option.ts";
 /**
  * A counting semaphore that coordinates concurrent access with permits.
  *
+ * **When to use**
+ *
+ * Use to coordinate concurrent effects that need bounded access to a shared
+ * resource.
+ *
  * **Details**
  *
  * Effects can acquire permits, wait until enough permits are available,
@@ -46,18 +63,29 @@ import type * as Option from "./Option.ts";
  * })
  * ```
  *
+ * @see {@link make} for creating a semaphore inside Effect code
+ * @see {@link makeUnsafe} for creating a semaphore synchronously
+ *
  * @category models
  * @since 4.0.0
  */
 export interface Semaphore {
     /**
      * Adjusts the number of permits available in the semaphore.
+     *
+     * **When to use**
+     *
+     * Use to change the total permit count of an existing semaphore.
      */
     resize(this: Semaphore, permits: number): Effect.Effect<void>;
     /**
      * Runs an effect with the given number of permits and releases the permits
      * when the effect completes.
      *
+     * **When to use**
+     *
+     * Use to run an effect while holding a specified number of semaphore permits.
+     *
      * **Details**
      *
      * This function acquires the specified number of permits before executing
@@ -70,6 +98,10 @@ export interface Semaphore {
      * Runs an effect with the given number of permits and releases the permits
      * when the effect completes.
      *
+     * **When to use**
+     *
+     * Use to run an effect while holding exactly one semaphore permit.
+     *
      * **Details**
      *
      * This function acquires the specified number of permits before executing
@@ -82,6 +114,11 @@ export interface Semaphore {
      * Runs an effect only if the specified number of permits are immediately
      * available.
      *
+     * **When to use**
+     *
+     * Use when guarded work should run only if the requested permits are
+     * immediately available.
+     *
      * **Details**
      *
      * This function attempts to acquire the specified number of permits. If they
@@ -94,26 +131,39 @@ export interface Semaphore {
      * Acquires the specified number of permits and returns the resulting
      * available permits, suspending the task if they are not yet available.
      * Concurrent pending `take` calls are processed in a first-in, first-out manner.
+     *
+     * **When to use**
+     *
+     * Use to manually acquire permits for lower-level coordination protocols.
      */
     take(this: Semaphore, permits: number): Effect.Effect<number>;
     /**
      * Releases the specified number of permits and returns the resulting
      * available permits.
+     *
+     * **When to use**
+     *
+     * Use to manually return permits acquired by a lower-level coordination
+     * protocol.
      */
     release(this: Semaphore, permits: number): Effect.Effect<number>;
     /**
      * Releases all permits held by this semaphore and returns the resulting available permits.
+     *
+     * **When to use**
+     *
+     * Use to return every currently taken permit to the semaphore at once.
      */
     readonly releaseAll: Effect.Effect<number>;
 }
 /**
- * Synchronously creates a `Semaphore` initialized with the specified total
+ * Creates a `Semaphore` synchronously with the specified total
  * number of permits.
  *
  * **When to use**
  *
- * Use this low-level constructor when an immediate semaphore value is required;
- * otherwise prefer the effectful `make` constructor.
+ * Use to construct a semaphore synchronously when an immediate value is
+ * required outside an Effect workflow.
  *
  * **Example** (Creating an unsafe semaphore)
  *
@@ -150,8 +200,8 @@ export declare const makeUnsafe: (permits: number) => Semaphore;
  *
  * **When to use**
  *
- * Use the returned semaphore to limit concurrency with `withPermit` or
- * `withPermits`, or to manually `take` and `release` permits.
+ * Use to create a semaphore inside Effect code for bounding concurrency with
+ * automatic or manual permit management.
  *
  * **Example** (Creating a semaphore)
  *
@@ -180,21 +230,63 @@ export declare const makeUnsafe: (permits: number) => Semaphore;
  */
 export declare const make: (permits: number) => Effect.Effect<Semaphore>;
 /**
- * Adjusts the number of permits available in the semaphore.
+ * Sets the total number of permits managed by the semaphore.
+ *
+ * **When to use**
+ *
+ * Use to change the concurrency limit of an existing semaphore while keeping
+ * current acquisitions in place.
+ *
+ * **Details**
+ *
+ * Existing acquisitions remain taken after resizing. If the new total is less
+ * than the currently taken permit count, new acquisitions wait until enough
+ * permits are released.
+ *
+ * @see {@link make} for creating a semaphore with an initial permit count
+ * @see {@link release} for returning permits without changing semaphore capacity
  *
  * @category combinators
  * @since 4.0.0
  */
 export declare const resize: {
     /**
-     * Adjusts the number of permits available in the semaphore.
+     * Sets the total number of permits managed by the semaphore.
+     *
+     * **When to use**
+     *
+     * Use to change the concurrency limit of an existing semaphore while keeping
+     * current acquisitions in place.
+     *
+     * **Details**
+     *
+     * Existing acquisitions remain taken after resizing. If the new total is less
+     * than the currently taken permit count, new acquisitions wait until enough
+     * permits are released.
+     *
+     * @see {@link make} for creating a semaphore with an initial permit count
+     * @see {@link release} for returning permits without changing semaphore capacity
      *
      * @category combinators
      * @since 4.0.0
      */
     (permits: number): (self: Semaphore) => Effect.Effect<void>;
     /**
-     * Adjusts the number of permits available in the semaphore.
+     * Sets the total number of permits managed by the semaphore.
+     *
+     * **When to use**
+     *
+     * Use to change the concurrency limit of an existing semaphore while keeping
+     * current acquisitions in place.
+     *
+     * **Details**
+     *
+     * Existing acquisitions remain taken after resizing. If the new total is less
+     * than the currently taken permit count, new acquisitions wait until enough
+     * permits are released.
+     *
+     * @see {@link make} for creating a semaphore with an initial permit count
+     * @see {@link release} for returning permits without changing semaphore capacity
      *
      * @category combinators
      * @since 4.0.0
@@ -205,6 +297,21 @@ export declare const resize: {
  * Runs an effect with the given number of permits and releases the permits when
  * the effect completes.
  *
+ * **When to use**
+ *
+ * Use to run an effect while holding a specified number of semaphore permits
+ * for the duration of that effect.
+ *
+ * **Details**
+ *
+ * The effect waits until enough permits are available. Acquired permits are
+ * released when the wrapped effect exits.
+ *
+ * @see {@link withPermit} for acquiring exactly one permit
+ * @see {@link withPermitsIfAvailable} for running only when permits are immediately available
+ * @see {@link take} for manually acquiring permits
+ * @see {@link release} for manually returning permits
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -213,6 +320,21 @@ export declare const withPermits: {
      * Runs an effect with the given number of permits and releases the permits when
      * the effect completes.
      *
+     * **When to use**
+     *
+     * Use to run an effect while holding a specified number of semaphore permits
+     * for the duration of that effect.
+     *
+     * **Details**
+     *
+     * The effect waits until enough permits are available. Acquired permits are
+     * released when the wrapped effect exits.
+     *
+     * @see {@link withPermit} for acquiring exactly one permit
+     * @see {@link withPermitsIfAvailable} for running only when permits are immediately available
+     * @see {@link take} for manually acquiring permits
+     * @see {@link release} for manually returning permits
+     *
      * @category combinators
      * @since 4.0.0
      */
@@ -221,6 +343,21 @@ export declare const withPermits: {
      * Runs an effect with the given number of permits and releases the permits when
      * the effect completes.
      *
+     * **When to use**
+     *
+     * Use to run an effect while holding a specified number of semaphore permits
+     * for the duration of that effect.
+     *
+     * **Details**
+     *
+     * The effect waits until enough permits are available. Acquired permits are
+     * released when the wrapped effect exits.
+     *
+     * @see {@link withPermit} for acquiring exactly one permit
+     * @see {@link withPermitsIfAvailable} for running only when permits are immediately available
+     * @see {@link take} for manually acquiring permits
+     * @see {@link release} for manually returning permits
+     *
      * @category combinators
      * @since 4.0.0
      */
@@ -230,6 +367,16 @@ export declare const withPermits: {
  * Runs an effect with a single permit and releases the permit when the effect
  * completes.
  *
+ * **When to use**
+ *
+ * Use to guard an effect with exactly one semaphore permit while automatically
+ * releasing that permit when the effect exits.
+ *
+ * @see {@link withPermits} for acquiring more than one permit
+ * @see {@link withPermitsIfAvailable} for running only when permits are immediately available
+ * @see {@link take} for manually acquiring permits
+ * @see {@link release} for manually returning permits
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -238,6 +385,16 @@ export declare const withPermit: {
      * Runs an effect with a single permit and releases the permit when the effect
      * completes.
      *
+     * **When to use**
+     *
+     * Use to guard an effect with exactly one semaphore permit while automatically
+     * releasing that permit when the effect exits.
+     *
+     * @see {@link withPermits} for acquiring more than one permit
+     * @see {@link withPermitsIfAvailable} for running only when permits are immediately available
+     * @see {@link take} for manually acquiring permits
+     * @see {@link release} for manually returning permits
+     *
      * @category combinators
      * @since 4.0.0
      */
@@ -246,6 +403,16 @@ export declare const withPermit: {
      * Runs an effect with a single permit and releases the permit when the effect
      * completes.
      *
+     * **When to use**
+     *
+     * Use to guard an effect with exactly one semaphore permit while automatically
+     * releasing that permit when the effect exits.
+     *
+     * @see {@link withPermits} for acquiring more than one permit
+     * @see {@link withPermitsIfAvailable} for running only when permits are immediately available
+     * @see {@link take} for manually acquiring permits
+     * @see {@link release} for manually returning permits
+     *
      * @category combinators
      * @since 4.0.0
      */
@@ -255,6 +422,20 @@ export declare const withPermit: {
  * Runs an effect only if the specified number of permits are immediately
  * available.
  *
+ * **When to use**
+ *
+ * Use when guarded work should run only if the requested permits are
+ * immediately available.
+ *
+ * **Details**
+ *
+ * When the permits are unavailable, the effect is not run and the result is
+ * `Option.none`. When permits are available, the effect is run, its result is
+ * wrapped in `Option.some`, and the acquired permits are released when the
+ * effect exits.
+ *
+ * @see {@link withPermits} for the variant that waits until permits are available
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -263,6 +444,20 @@ export declare const withPermitsIfAvailable: {
      * Runs an effect only if the specified number of permits are immediately
      * available.
      *
+     * **When to use**
+     *
+     * Use when guarded work should run only if the requested permits are
+     * immediately available.
+     *
+     * **Details**
+     *
+     * When the permits are unavailable, the effect is not run and the result is
+     * `Option.none`. When permits are available, the effect is run, its result is
+     * wrapped in `Option.some`, and the acquired permits are released when the
+     * effect exits.
+     *
+     * @see {@link withPermits} for the variant that waits until permits are available
+     *
      * @category combinators
      * @since 4.0.0
      */
@@ -271,30 +466,83 @@ export declare const withPermitsIfAvailable: {
      * Runs an effect only if the specified number of permits are immediately
      * available.
      *
+     * **When to use**
+     *
+     * Use when guarded work should run only if the requested permits are
+     * immediately available.
+     *
+     * **Details**
+     *
+     * When the permits are unavailable, the effect is not run and the result is
+     * `Option.none`. When permits are available, the effect is run, its result is
+     * wrapped in `Option.some`, and the acquired permits are released when the
+     * effect exits.
+     *
+     * @see {@link withPermits} for the variant that waits until permits are available
+     *
      * @category combinators
      * @since 4.0.0
      */
     <A, E, R>(self: Semaphore, permits: number, effect: Effect.Effect<A, E, R>): Effect.Effect<Option.Option<A>, E, R>;
 };
 /**
- * Acquires the specified number of permits and returns the resulting available
- * permits, suspending the task if they are not yet available.
+ * Acquires the specified number of permits and returns the acquired permit
+ * count.
+ *
+ * **When to use**
+ *
+ * Use to manually acquire permits when a lower-level permit protocol needs
+ * explicit acquisition and release control.
+ *
+ * **Details**
+ *
+ * The effect waits until enough permits are available.
+ *
+ * @see {@link withPermit} for automatically acquiring and releasing one permit around an effect
+ * @see {@link withPermits} for automatically acquiring and releasing multiple permits around an effect
+ * @see {@link release} for returning manually acquired permits
  *
  * @category combinators
  * @since 4.0.0
  */
 export declare const take: {
     /**
-     * Acquires the specified number of permits and returns the resulting available
-     * permits, suspending the task if they are not yet available.
+     * Acquires the specified number of permits and returns the acquired permit
+     * count.
+     *
+     * **When to use**
+     *
+     * Use to manually acquire permits when a lower-level permit protocol needs
+     * explicit acquisition and release control.
+     *
+     * **Details**
+     *
+     * The effect waits until enough permits are available.
+     *
+     * @see {@link withPermit} for automatically acquiring and releasing one permit around an effect
+     * @see {@link withPermits} for automatically acquiring and releasing multiple permits around an effect
+     * @see {@link release} for returning manually acquired permits
      *
      * @category combinators
      * @since 4.0.0
      */
     (permits: number): (self: Semaphore) => Effect.Effect<number>;
     /**
-     * Acquires the specified number of permits and returns the resulting available
-     * permits, suspending the task if they are not yet available.
+     * Acquires the specified number of permits and returns the acquired permit
+     * count.
+     *
+     * **When to use**
+     *
+     * Use to manually acquire permits when a lower-level permit protocol needs
+     * explicit acquisition and release control.
+     *
+     * **Details**
+     *
+     * The effect waits until enough permits are available.
+     *
+     * @see {@link withPermit} for automatically acquiring and releasing one permit around an effect
+     * @see {@link withPermits} for automatically acquiring and releasing multiple permits around an effect
+     * @see {@link release} for returning manually acquired permits
      *
      * @category combinators
      * @since 4.0.0
@@ -305,6 +553,27 @@ export declare const take: {
  * Releases the specified number of permits and returns the resulting available
  * permits.
  *
+ * **When to use**
+ *
+ * Use to manually return permits acquired with `take` when a lower-level
+ * permit protocol needs explicit release control.
+ *
+ * **Details**
+ *
+ * Running the effect releases the requested permits, wakes waiting acquirers
+ * when permits become available, and returns the current available permit
+ * count.
+ *
+ * **Gotchas**
+ *
+ * Manual `take` / `release` usage must keep permit counts balanced. Prefer
+ * `withPermit` or `withPermits` when the acquisition can be scoped to one
+ * effect.
+ *
+ * @see {@link take} for manually acquiring permits
+ * @see {@link releaseAll} for returning every currently taken permit
+ * @see {@link withPermits} for automatic acquire and release around an effect
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -313,6 +582,27 @@ export declare const release: {
      * Releases the specified number of permits and returns the resulting available
      * permits.
      *
+     * **When to use**
+     *
+     * Use to manually return permits acquired with `take` when a lower-level
+     * permit protocol needs explicit release control.
+     *
+     * **Details**
+     *
+     * Running the effect releases the requested permits, wakes waiting acquirers
+     * when permits become available, and returns the current available permit
+     * count.
+     *
+     * **Gotchas**
+     *
+     * Manual `take` / `release` usage must keep permit counts balanced. Prefer
+     * `withPermit` or `withPermits` when the acquisition can be scoped to one
+     * effect.
+     *
+     * @see {@link take} for manually acquiring permits
+     * @see {@link releaseAll} for returning every currently taken permit
+     * @see {@link withPermits} for automatic acquire and release around an effect
+     *
      * @category combinators
      * @since 4.0.0
      */
@@ -321,6 +611,27 @@ export declare const release: {
      * Releases the specified number of permits and returns the resulting available
      * permits.
      *
+     * **When to use**
+     *
+     * Use to manually return permits acquired with `take` when a lower-level
+     * permit protocol needs explicit release control.
+     *
+     * **Details**
+     *
+     * Running the effect releases the requested permits, wakes waiting acquirers
+     * when permits become available, and returns the current available permit
+     * count.
+     *
+     * **Gotchas**
+     *
+     * Manual `take` / `release` usage must keep permit counts balanced. Prefer
+     * `withPermit` or `withPermits` when the acquisition can be scoped to one
+     * effect.
+     *
+     * @see {@link take} for manually acquiring permits
+     * @see {@link releaseAll} for returning every currently taken permit
+     * @see {@link withPermits} for automatic acquire and release around an effect
+     *
      * @category combinators
      * @since 4.0.0
      */
@@ -330,6 +641,14 @@ export declare const release: {
  * Releases all permits held by this semaphore and returns the resulting
  * available permits.
  *
+ * **When to use**
+ *
+ * Use to return every currently taken permit to a semaphore at once, typically
+ * during cleanup of manual `take` / `release` protocols.
+ *
+ * @see {@link release} for releasing a known permit count
+ * @see {@link withPermits} for automatic acquire and release around an effect
+ *
  * @category combinators
  * @since 4.0.0
  */