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

package/dist/Deferred.d.ts

@@ -1,67 +1,60 @@
 /**
- * This module provides utilities for working with `Deferred`, a powerful concurrency
- * primitive that represents an asynchronous variable that can be set exactly once.
- * Multiple fibers can await the same `Deferred` and will all be notified when it
- * completes.
- *
- * A `Deferred<A, E>` can be:
- * - **Completed successfully** with a value of type `A`
- * - **Failed** with an error of type `E`
- * - **Interrupted** if the fiber setting it is interrupted
- *
- * Key characteristics:
- * - **Single assignment**: Can only be completed once
- * - **Multiple waiters**: Many fibers can await the same `Deferred`
- * - **Fiber-safe**: Thread-safe operations across concurrent fibers
- * - **Composable**: Works seamlessly with other Effect operations
- *
- * **Example** (Coordinating fibers with a Deferred)
+ * The `Deferred` module provides a one-shot coordination cell for Effect
+ * programs. A `Deferred<A, E>` starts empty, can be completed exactly once, and
+ * allows any number of fibers to wait until that completion is available.
+ *
+ * `Deferred` is useful when one fiber must hand a single result, failure, or
+ * interruption signal to other fibers. Awaiters suspend without blocking an OS
+ * thread and resume with the same completion once a producer wins the race to
+ * complete the cell.
+ *
+ * **Mental model**
+ *
+ * - `Deferred.make` creates an empty cell
+ * - `Deferred.await` waits for the cell and then observes its stored
+ *   success, failure, defect, or interruption
+ * - Completion functions such as {@link succeed}, {@link fail},
+ *   {@link failCause}, {@link interrupt}, and {@link complete} return
+ *   `true` when they complete the cell, or `false` when another fiber already
+ *   completed it
+ * - Once completed, the result is stable for both current and future awaiters
+ *
+ * **Common tasks**
+ *
+ * - Create a cell with {@link make}
+ * - Wait for a result with {@link _await await}
+ * - Complete with a value or failure using {@link succeed}, {@link fail},
+ *   {@link failCause}, {@link die}, or {@link interrupt}
+ * - Complete from another effect using {@link complete} or {@link completeWith}
+ * - Check completion state with {@link isDone} or inspect it with {@link poll}
+ *
+ * **Gotchas**
+ *
+ * - A `Deferred` is for a single handoff; use `Queue` when producers emit many
+ *   values over time
+ * - `complete` runs an effect once and shares its memoized result, while
+ *   `completeWith` stores an effect directly and each awaiter may run it
+ * - Interrupting a fiber that is waiting on a `Deferred` removes that waiter;
+ *   it does not complete the `Deferred`
+ *
+ * **Example** (Opening a start gate)
  *
  * ```ts
  * import { Deferred, Effect, Fiber } from "effect"
  *
- * // Basic usage: coordinate between fibers
  * const program = Effect.gen(function*() {
- *   const deferred = yield* Deferred.make<string, never>()
+ *   const ready = yield* Deferred.make<void>()
  *
- *   // Fiber 1: waits for the value
- *   const waiter = yield* Effect.forkChild(
+ *   const worker = yield* Effect.forkChild(
  *     Effect.gen(function*() {
- *       const value = yield* Deferred.await(deferred)
- *       console.log("Received:", value)
- *       return value
+ *       yield* Deferred.await(ready)
+ *       return "started"
  *     })
  *   )
  *
- *   // Fiber 2: sets the value after a delay
- *   const setter = yield* Effect.forkChild(
- *     Effect.gen(function*() {
- *       yield* Effect.sleep("1 second")
- *       yield* Deferred.succeed(deferred, "Hello from setter!")
- *     })
- *   )
- *
- *   // Wait for both fibers
- *   yield* Fiber.join(waiter)
- *   yield* Fiber.join(setter)
- * })
- *
- * // Producer-consumer pattern
- * const producerConsumer = Effect.gen(function*() {
- *   const buffer = yield* Deferred.make<Array<number>, never>()
- *
- *   const producer = Effect.gen(function*() {
- *     const data = [1, 2, 3, 4, 5]
- *     yield* Deferred.succeed(buffer, data)
- *   })
+ *   yield* Deferred.succeed(ready, undefined)
  *
- *   const consumer = Effect.gen(function*() {
- *     const data = yield* Deferred.await(buffer)
- *     return data.reduce((sum, n) => sum + n, 0)
- *   })
- *
- *   const [, result] = yield* Effect.all([producer, consumer])
- *   return result // 15
+ *   return yield* Fiber.join(worker)
  * })
  * ```
  *
@@ -82,9 +75,8 @@ declare const TypeId = "~effect/Deferred";
  *
  * **When to use**
  *
- * Use `Deferred` for primitive actions whose completions require the
- * coordinated action of multiple fibers, and for building higher-level
- * concurrent or asynchronous structures.
+ * Use to coordinate multiple fibers around a value or failure that will be
+ * supplied exactly once.
  *
  * **Example** (Creating a Deferred for inter-fiber communication)
  *
@@ -130,6 +122,11 @@ export interface Deferred<in out A, in out E = never> extends Deferred.Variance<
 /**
  * Checks whether a value is a `Deferred`.
  *
+ * **When to use**
+ *
+ * Use to validate unknown values at runtime boundaries before treating them as
+ * `Deferred` values.
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -137,12 +134,21 @@ export declare const isDeferred: <A, E>(u: unknown) => u is Deferred<A, E>;
 /**
  * Companion namespace containing type-level metadata for `Deferred`.
  *
+ * **When to use**
+ *
+ * Use to reference type-level metadata associated with `Deferred`.
+ *
  * @since 2.0.0
  */
 export declare namespace Deferred {
     /**
      * Type-level variance marker for the value and error channels of `Deferred`.
      *
+     * **When to use**
+     *
+     * Use to carry the value and error type parameters for `Deferred` in Effect's
+     * type machinery.
+     *
      * **Details**
      *
      * This interface is part of the public type structure and is not intended to
@@ -159,12 +165,12 @@ export declare namespace Deferred {
     }
 }
 /**
- * Synchronously creates an empty `Deferred` outside the `Effect` runtime.
+ * Creates an empty `Deferred` synchronously outside the `Effect` runtime.
  *
  * **When to use**
  *
- * Prefer `Deferred.make` in effectful code so allocation is represented in
- * `Effect`; use this only when direct synchronous allocation is required.
+ * Use to allocate a `Deferred` synchronously when direct allocation outside
+ * `Effect` is required.
  *
  * **Example** (Creating a Deferred unsafely)
  *
@@ -182,6 +188,10 @@ export declare const makeUnsafe: <A, E = never>() => Deferred<A, E>;
 /**
  * Creates a new `Deferred`.
  *
+ * **When to use**
+ *
+ * Use to allocate an empty `Deferred` inside an `Effect` workflow.
+ *
  * **Example** (Creating a Deferred)
  *
  * ```ts
@@ -205,6 +215,15 @@ export {
  * Retrieves the value of the `Deferred`, suspending the fiber running the
  * workflow until the result is available.
  *
+ * **When to use**
+ *
+ * Use to wait for a `Deferred` to be completed and resume with its success,
+ * failure, defect, or interruption.
+ *
+ * **Details**
+ *
+ * Awaiters observe the completion effect stored in the `Deferred`.
+ *
  * **Example** (Awaiting a Deferred value)
  *
  * ```ts
@@ -219,6 +238,9 @@ export {
  * })
  * ```
  *
+ * @see {@link complete} for completing from an effect and memoizing its result
+ * @see {@link completeWith} for completing with an effect directly
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -229,9 +251,8 @@ _await as await };
  *
  * **When to use**
  *
- * Use `Deferred.complete` when the effect should be evaluated once and the
- * resulting `Exit` memoized. Use `Deferred.completeWith` when you need to store
- * an effect directly without memoizing its result.
+ * Use when completion should run an effect once and share its result with all
+ * awaiters.
  *
  * **Details**
  *
@@ -253,6 +274,8 @@ _await as await };
  * })
  * ```
  *
+ * @see {@link completeWith} for storing an effect directly without memoizing its result
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -263,9 +286,8 @@ export declare const complete: {
      *
      * **When to use**
      *
-     * Use `Deferred.complete` when the effect should be evaluated once and the
-     * resulting `Exit` memoized. Use `Deferred.completeWith` when you need to store
-     * an effect directly without memoizing its result.
+     * Use when completion should run an effect once and share its result with all
+     * awaiters.
      *
      * **Details**
      *
@@ -287,6 +309,8 @@ export declare const complete: {
      * })
      * ```
      *
+     * @see {@link completeWith} for storing an effect directly without memoizing its result
+     *
      * @category utils
      * @since 2.0.0
      */
@@ -297,9 +321,8 @@ export declare const complete: {
      *
      * **When to use**
      *
-     * Use `Deferred.complete` when the effect should be evaluated once and the
-     * resulting `Exit` memoized. Use `Deferred.completeWith` when you need to store
-     * an effect directly without memoizing its result.
+     * Use when completion should run an effect once and share its result with all
+     * awaiters.
      *
      * **Details**
      *
@@ -321,14 +344,30 @@ export declare const complete: {
      * })
      * ```
      *
+     * @see {@link completeWith} for storing an effect directly without memoizing its result
+     *
      * @category utils
      * @since 2.0.0
      */
     <A, E, R>(self: Deferred<A, E>, effect: Effect<A, E, R>): Effect<boolean, never, R>;
 };
 /**
- * Completes the deferred with the result of the specified effect. If the
- * deferred has already been completed, the method will produce false.
+ * Attempts to complete the `Deferred` with the specified effect directly.
+ *
+ * **When to use**
+ *
+ * Use to store an already environment-free effect as the completion without
+ * running it during completion.
+ *
+ * **Details**
+ *
+ * The returned effect succeeds with `true` when this call completed the
+ * `Deferred`, or `false` if it was already completed.
+ *
+ * **Gotchas**
+ *
+ * The supplied effect is not memoized by `completeWith`; each awaiter may run
+ * the stored effect independently.
  *
  * **Example** (Completing a Deferred with an effect)
  *
@@ -345,13 +384,30 @@ export declare const complete: {
  * })
  * ```
  *
+ * @see {@link complete} for running an effect once and sharing its result
+ * @see {@link done} for completing from an already computed `Exit`
+ *
  * @category utils
  * @since 2.0.0
  */
 export declare const completeWith: {
     /**
-     * Completes the deferred with the result of the specified effect. If the
-     * deferred has already been completed, the method will produce false.
+     * Attempts to complete the `Deferred` with the specified effect directly.
+     *
+     * **When to use**
+     *
+     * Use to store an already environment-free effect as the completion without
+     * running it during completion.
+     *
+     * **Details**
+     *
+     * The returned effect succeeds with `true` when this call completed the
+     * `Deferred`, or `false` if it was already completed.
+     *
+     * **Gotchas**
+     *
+     * The supplied effect is not memoized by `completeWith`; each awaiter may run
+     * the stored effect independently.
      *
      * **Example** (Completing a Deferred with an effect)
      *
@@ -368,13 +424,30 @@ export declare const completeWith: {
      * })
      * ```
      *
+     * @see {@link complete} for running an effect once and sharing its result
+     * @see {@link done} for completing from an already computed `Exit`
+     *
      * @category utils
      * @since 2.0.0
      */
     <A, E>(effect: Effect<A, E>): (self: Deferred<A, E>) => Effect<boolean>;
     /**
-     * Completes the deferred with the result of the specified effect. If the
-     * deferred has already been completed, the method will produce false.
+     * Attempts to complete the `Deferred` with the specified effect directly.
+     *
+     * **When to use**
+     *
+     * Use to store an already environment-free effect as the completion without
+     * running it during completion.
+     *
+     * **Details**
+     *
+     * The returned effect succeeds with `true` when this call completed the
+     * `Deferred`, or `false` if it was already completed.
+     *
+     * **Gotchas**
+     *
+     * The supplied effect is not memoized by `completeWith`; each awaiter may run
+     * the stored effect independently.
      *
      * **Example** (Completing a Deferred with an effect)
      *
@@ -391,15 +464,27 @@ export declare const completeWith: {
      * })
      * ```
      *
+     * @see {@link complete} for running an effect once and sharing its result
+     * @see {@link done} for completing from an already computed `Exit`
+     *
      * @category utils
      * @since 2.0.0
      */
     <A, E>(self: Deferred<A, E>, effect: Effect<A, E>): Effect<boolean>;
 };
 /**
- * Exits the `Deferred` with the specified `Exit` value, which will be
+ * Completes the `Deferred` with the specified `Exit` value, which will be
  * propagated to all fibers waiting on the value of the `Deferred`.
  *
+ * **When to use**
+ *
+ * Use to complete a `Deferred` from an already computed `Exit`.
+ *
+ * **Details**
+ *
+ * The returned effect succeeds with `true` when this call completed the
+ * `Deferred`, or `false` if it was already completed.
+ *
  * **Example** (Completing a Deferred with an Exit)
  *
  * ```ts
@@ -414,14 +499,28 @@ export declare const completeWith: {
  * })
  * ```
  *
+ * @see {@link complete} for completing from an effect and memoizing its result
+ * @see {@link completeWith} for storing an effect directly
+ * @see {@link succeed} for completing with a success value
+ * @see {@link failCause} for completing with a failure cause
+ *
  * @category utils
  * @since 2.0.0
  */
 export declare const done: {
     /**
-     * Exits the `Deferred` with the specified `Exit` value, which will be
+     * Completes the `Deferred` with the specified `Exit` value, which will be
      * propagated to all fibers waiting on the value of the `Deferred`.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` from an already computed `Exit`.
+     *
+     * **Details**
+     *
+     * The returned effect succeeds with `true` when this call completed the
+     * `Deferred`, or `false` if it was already completed.
+     *
      * **Example** (Completing a Deferred with an Exit)
      *
      * ```ts
@@ -436,14 +535,28 @@ export declare const done: {
      * })
      * ```
      *
+     * @see {@link complete} for completing from an effect and memoizing its result
+     * @see {@link completeWith} for storing an effect directly
+     * @see {@link succeed} for completing with a success value
+     * @see {@link failCause} for completing with a failure cause
+     *
      * @category utils
      * @since 2.0.0
      */
     <A, E>(exit: Exit.Exit<A, E>): (self: Deferred<A, E>) => Effect<boolean>;
     /**
-     * Exits the `Deferred` with the specified `Exit` value, which will be
+     * Completes the `Deferred` with the specified `Exit` value, which will be
      * propagated to all fibers waiting on the value of the `Deferred`.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` from an already computed `Exit`.
+     *
+     * **Details**
+     *
+     * The returned effect succeeds with `true` when this call completed the
+     * `Deferred`, or `false` if it was already completed.
+     *
      * **Example** (Completing a Deferred with an Exit)
      *
      * ```ts
@@ -458,6 +571,11 @@ export declare const done: {
      * })
      * ```
      *
+     * @see {@link complete} for completing from an effect and memoizing its result
+     * @see {@link completeWith} for storing an effect directly
+     * @see {@link succeed} for completing with a success value
+     * @see {@link failCause} for completing with a failure cause
+     *
      * @category utils
      * @since 2.0.0
      */
@@ -466,6 +584,10 @@ export declare const done: {
 /**
  * Attempts to complete the `Deferred` with the specified error.
  *
+ * **When to use**
+ *
+ * Use to complete a `Deferred` with a typed failure value.
+ *
  * **Details**
  *
  * Fibers waiting on the `Deferred` fail with that error only if this call
@@ -491,6 +613,10 @@ export declare const fail: {
     /**
      * Attempts to complete the `Deferred` with the specified error.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` with a typed failure value.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` fail with that error only if this call
@@ -516,6 +642,10 @@ export declare const fail: {
     /**
      * Attempts to complete the `Deferred` with the specified error.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` with a typed failure value.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` fail with that error only if this call
@@ -543,6 +673,10 @@ export declare const fail: {
  * Computes an error when the returned effect is run, then attempts to complete
  * the `Deferred` with that error.
  *
+ * **When to use**
+ *
+ * Use to lazily compute a typed failure value when the completion effect runs.
+ *
  * **Details**
  *
  * Fibers waiting on the `Deferred` fail with the computed error only if this
@@ -569,6 +703,10 @@ export declare const failSync: {
      * Computes an error when the returned effect is run, then attempts to complete
      * the `Deferred` with that error.
      *
+     * **When to use**
+     *
+     * Use to lazily compute a typed failure value when the completion effect runs.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` fail with the computed error only if this
@@ -595,6 +733,10 @@ export declare const failSync: {
      * Computes an error when the returned effect is run, then attempts to complete
      * the `Deferred` with that error.
      *
+     * **When to use**
+     *
+     * Use to lazily compute a typed failure value when the completion effect runs.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` fail with the computed error only if this
@@ -621,6 +763,10 @@ export declare const failSync: {
 /**
  * Attempts to complete the `Deferred` with the specified `Cause`.
  *
+ * **When to use**
+ *
+ * Use to complete a `Deferred` with a full failure cause.
+ *
  * **Details**
  *
  * Fibers waiting on the `Deferred` observe that cause only if this call
@@ -649,6 +795,10 @@ export declare const failCause: {
     /**
      * Attempts to complete the `Deferred` with the specified `Cause`.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` with a full failure cause.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` observe that cause only if this call
@@ -677,6 +827,10 @@ export declare const failCause: {
     /**
      * Attempts to complete the `Deferred` with the specified `Cause`.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` with a full failure cause.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` observe that cause only if this call
@@ -707,6 +861,10 @@ export declare const failCause: {
  * Computes a `Cause` when the returned effect is run, then attempts to
  * complete the `Deferred` with that cause.
  *
+ * **When to use**
+ *
+ * Use to lazily compute a full failure cause when the completion effect runs.
+ *
  * **Details**
  *
  * Fibers waiting on the `Deferred` observe the computed cause only if this
@@ -736,6 +894,10 @@ export declare const failCauseSync: {
      * Computes a `Cause` when the returned effect is run, then attempts to
      * complete the `Deferred` with that cause.
      *
+     * **When to use**
+     *
+     * Use to lazily compute a full failure cause when the completion effect runs.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` observe the computed cause only if this
@@ -765,6 +927,10 @@ export declare const failCauseSync: {
      * Computes a `Cause` when the returned effect is run, then attempts to
      * complete the `Deferred` with that cause.
      *
+     * **When to use**
+     *
+     * Use to lazily compute a full failure cause when the completion effect runs.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` observe the computed cause only if this
@@ -794,6 +960,10 @@ export declare const failCauseSync: {
 /**
  * Attempts to complete the `Deferred` with a defect.
  *
+ * **When to use**
+ *
+ * Use to complete a `Deferred` with an unexpected defect.
+ *
  * **Details**
  *
  * Fibers waiting on the `Deferred` die with that defect only if this call
@@ -822,6 +992,10 @@ export declare const die: {
     /**
      * Attempts to complete the `Deferred` with a defect.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` with an unexpected defect.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` die with that defect only if this call
@@ -850,6 +1024,10 @@ export declare const die: {
     /**
      * Attempts to complete the `Deferred` with a defect.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` with an unexpected defect.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` die with that defect only if this call
@@ -880,6 +1058,10 @@ export declare const die: {
  * Computes a defect when the returned effect is run, then attempts to complete
  * the `Deferred` with that defect.
  *
+ * **When to use**
+ *
+ * Use to lazily compute an unexpected defect when the completion effect runs.
+ *
  * **Details**
  *
  * Fibers waiting on the `Deferred` die with the computed defect only if this
@@ -909,6 +1091,10 @@ export declare const dieSync: {
      * Computes a defect when the returned effect is run, then attempts to complete
      * the `Deferred` with that defect.
      *
+     * **When to use**
+     *
+     * Use to lazily compute an unexpected defect when the completion effect runs.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` die with the computed defect only if this
@@ -938,6 +1124,10 @@ export declare const dieSync: {
      * Computes a defect when the returned effect is run, then attempts to complete
      * the `Deferred` with that defect.
      *
+     * **When to use**
+     *
+     * Use to lazily compute an unexpected defect when the completion effect runs.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` die with the computed defect only if this
@@ -967,6 +1157,10 @@ export declare const dieSync: {
 /**
  * Attempts to complete the `Deferred` with interruption by the current fiber.
  *
+ * **When to use**
+ *
+ * Use to complete a `Deferred` as interrupted by the current fiber.
+ *
  * **Details**
  *
  * Fibers waiting on the `Deferred` are interrupted with the current fiber id
@@ -994,6 +1188,10 @@ export declare const interrupt: <A, E>(self: Deferred<A, E>) => Effect<boolean>;
  * Attempts to complete the `Deferred` with interruption by the specified
  * `FiberId`.
  *
+ * **When to use**
+ *
+ * Use to complete a `Deferred` as interrupted by a specific fiber id.
+ *
  * **Details**
  *
  * Fibers waiting on the `Deferred` are interrupted with that fiber id only if
@@ -1020,6 +1218,10 @@ export declare const interruptWith: {
      * Attempts to complete the `Deferred` with interruption by the specified
      * `FiberId`.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` as interrupted by a specific fiber id.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` are interrupted with that fiber id only if
@@ -1046,6 +1248,10 @@ export declare const interruptWith: {
      * Attempts to complete the `Deferred` with interruption by the specified
      * `FiberId`.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` as interrupted by a specific fiber id.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` are interrupted with that fiber id only if
@@ -1073,6 +1279,10 @@ export declare const interruptWith: {
  * Returns `true` if this `Deferred` has already been completed with a value or
  * an error, `false` otherwise.
  *
+ * **When to use**
+ *
+ * Use to check completion status inside an `Effect` workflow.
+ *
  * **Example** (Checking Deferred completion)
  *
  * ```ts
@@ -1094,8 +1304,15 @@ export declare const interruptWith: {
  */
 export declare const isDone: <A, E>(self: Deferred<A, E>) => Effect<boolean>;
 /**
- * Returns `true` if this `Deferred` has already been completed with a value or
- * an error, `false` otherwise.
+ * Returns whether this `Deferred` has already been completed synchronously.
+ *
+ * **When to use**
+ *
+ * Use to check `Deferred` completion synchronously in code that cannot return
+ * an `Effect`, such as low-level integration code.
+ *
+ * @see {@link isDone} for checking completion inside `Effect`
+ * @see {@link poll} for reading the completed effect when available
  *
  * @category getters
  * @since 4.0.0
@@ -1106,6 +1323,11 @@ export declare const isDoneUnsafe: <A, E>(self: Deferred<A, E>) => boolean;
  * `Option.some(effect)` when the `Deferred` is completed, `Option.none()`
  * otherwise.
  *
+ * **When to use**
+ *
+ * Use to inspect whether a `Deferred` is already completed and retrieve its
+ * stored completion effect when available.
+ *
  * **Example** (Polling Deferred completion)
  *
  * ```ts
@@ -1129,6 +1351,10 @@ export declare function poll<A, E>(self: Deferred<A, E>): Effect<Option.Option<E
 /**
  * Attempts to complete the `Deferred` with the specified value.
  *
+ * **When to use**
+ *
+ * Use to complete a `Deferred` with a successful value.
+ *
  * **Details**
  *
  * Fibers waiting on the `Deferred` receive the value only if this call
@@ -1156,6 +1382,10 @@ export declare const succeed: {
     /**
      * Attempts to complete the `Deferred` with the specified value.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` with a successful value.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` receive the value only if this call
@@ -1183,6 +1413,10 @@ export declare const succeed: {
     /**
      * Attempts to complete the `Deferred` with the specified value.
      *
+     * **When to use**
+     *
+     * Use to complete a `Deferred` with a successful value.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` receive the value only if this call
@@ -1212,6 +1446,10 @@ export declare const succeed: {
  * Computes a value when the returned effect is run, then attempts to complete
  * the `Deferred` with that value.
  *
+ * **When to use**
+ *
+ * Use to lazily compute a successful value when the completion effect runs.
+ *
  * **Details**
  *
  * Fibers waiting on the `Deferred` receive the computed value only if this call
@@ -1240,6 +1478,10 @@ export declare const sync: {
      * Computes a value when the returned effect is run, then attempts to complete
      * the `Deferred` with that value.
      *
+     * **When to use**
+     *
+     * Use to lazily compute a successful value when the completion effect runs.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` receive the computed value only if this call
@@ -1268,6 +1510,10 @@ export declare const sync: {
      * Computes a value when the returned effect is run, then attempts to complete
      * the `Deferred` with that value.
      *
+     * **When to use**
+     *
+     * Use to lazily compute a successful value when the completion effect runs.
+     *
      * **Details**
      *
      * Fibers waiting on the `Deferred` receive the computed value only if this call
@@ -1294,9 +1540,14 @@ export declare const sync: {
     <A, E>(self: Deferred<A, E>, evaluate: LazyArg<A>): Effect<boolean>;
 };
 /**
- * Synchronously attempts to complete the `Deferred` with the specified
+ * Attempts to complete the `Deferred` synchronously with the specified
  * completion effect.
  *
+ * **When to use**
+ *
+ * Use to complete a `Deferred` synchronously in low-level code that already has
+ * the completion effect.
+ *
  * **Details**
  *
  * This mutates the `Deferred` directly and should be reserved for low-level
@@ -1321,6 +1572,11 @@ export declare const doneUnsafe: <A, E>(self: Deferred<A, E>, effect: Effect<A,
  * Runs an `Effect` and attempts to complete a `Deferred` with the effect's
  * result.
  *
+ * **When to use**
+ *
+ * Use to pipe an effect result into a `Deferred` while preserving success,
+ * failure, defects, and interruption.
+ *
  * **Details**
  *
  * If the effect succeeds, fails, dies, or is interrupted, that result is used
@@ -1364,6 +1620,11 @@ export declare const into: {
      * Runs an `Effect` and attempts to complete a `Deferred` with the effect's
      * result.
      *
+     * **When to use**
+     *
+     * Use to pipe an effect result into a `Deferred` while preserving success,
+     * failure, defects, and interruption.
+     *
      * **Details**
      *
      * If the effect succeeds, fails, dies, or is interrupted, that result is used
@@ -1407,6 +1668,11 @@ export declare const into: {
      * Runs an `Effect` and attempts to complete a `Deferred` with the effect's
      * result.
      *
+     * **When to use**
+     *
+     * Use to pipe an effect result into a `Deferred` while preserving success,
+     * failure, defects, and interruption.
+     *
      * **Details**
      *
      * If the effect succeeds, fails, dies, or is interrupted, that result is used