effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Deferred.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)
  * })
  * ```
  *
@@ -88,9 +81,8 @@ 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)
  *
@@ -137,6 +129,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
  */
@@ -145,12 +142,21 @@ export const isDeferred = <A, E>(u: unknown): u is Deferred<A, E> => hasProperty
 /**
  * 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
@@ -182,8 +188,8 @@ const DeferredProto = {
  *
  * **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)
  *
@@ -207,6 +213,10 @@ export 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
@@ -241,6 +251,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
@@ -255,6 +274,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
    */
@@ -267,9 +289,8 @@ export {
  *
  * **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**
  *
@@ -291,6 +312,8 @@ export {
  * })
  * ```
  *
+ * @see {@link completeWith} for storing an effect directly without memoizing its result
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -301,9 +324,8 @@ export 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**
    *
@@ -325,6 +347,8 @@ export const complete: {
    * })
    * ```
    *
+   * @see {@link completeWith} for storing an effect directly without memoizing its result
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -335,9 +359,8 @@ export 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**
    *
@@ -359,6 +382,8 @@ export const complete: {
    * })
    * ```
    *
+   * @see {@link completeWith} for storing an effect directly without memoizing its result
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -370,8 +395,22 @@ export const complete: {
 )
 
 /**
- * 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)
  *
@@ -388,13 +427,30 @@ export 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 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)
    *
@@ -411,13 +467,30 @@ export 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)
    *
@@ -434,6 +507,9 @@ export 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
    */
@@ -448,6 +524,15 @@ export const completeWith: {
  * Exits 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
@@ -462,6 +547,11 @@ export 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
  */
@@ -470,6 +560,15 @@ export const done: {
    * Exits 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
@@ -484,6 +583,11 @@ export 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
    */
@@ -492,6 +596,15 @@ export const done: {
    * Exits 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
@@ -506,6 +619,11 @@ export 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
    */
@@ -515,6 +633,10 @@ export 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
@@ -540,6 +662,10 @@ export 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
@@ -565,6 +691,10 @@ export 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
@@ -593,6 +723,10 @@ export 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
@@ -619,6 +753,10 @@ export 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
@@ -645,6 +783,10 @@ export 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
@@ -676,6 +818,10 @@ export 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
@@ -704,6 +850,10 @@ export 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
@@ -732,6 +882,10 @@ export 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
@@ -766,6 +920,10 @@ export 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
@@ -795,6 +953,10 @@ export 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
@@ -824,6 +986,10 @@ export 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
@@ -858,6 +1024,10 @@ export 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
@@ -886,6 +1056,10 @@ export 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
@@ -914,6 +1088,10 @@ export 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
@@ -945,6 +1123,10 @@ export 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
@@ -974,6 +1156,10 @@ export 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
@@ -1003,6 +1189,10 @@ export 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
@@ -1037,6 +1227,10 @@ export 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
@@ -1066,6 +1260,10 @@ export 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
@@ -1092,6 +1290,10 @@ export 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
@@ -1118,6 +1320,10 @@ export 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
@@ -1150,6 +1356,10 @@ export 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
@@ -1172,8 +1382,15 @@ export const interruptWith: {
 export const isDone = <A, E>(self: Deferred<A, E>): Effect<boolean> => internalEffect.sync(() => isDoneUnsafe(self))
 
 /**
- * Returns `true` if this `Deferred` has already been completed with a value or
- * an error, `false` otherwise.
+ * Synchronously returns whether this `Deferred` has already been completed.
+ *
+ * **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
@@ -1185,6 +1402,11 @@ export const isDoneUnsafe = <A, E>(self: Deferred<A, E>): boolean => self.effect
  * `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
@@ -1211,6 +1433,10 @@ export function poll<A, E>(self: Deferred<A, E>): Effect<Option.Option<Effect<A,
 /**
  * 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
@@ -1238,6 +1464,10 @@ export 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
@@ -1265,6 +1495,10 @@ export 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
@@ -1295,6 +1529,10 @@ export 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
@@ -1323,6 +1561,10 @@ export 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
@@ -1351,6 +1593,10 @@ export 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
@@ -1385,6 +1631,11 @@ export const sync: {
  * Synchronously attempts to complete the `Deferred` 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
@@ -1420,6 +1671,11 @@ export const doneUnsafe = <A, E>(self: Deferred<A, E>, effect: Effect<A, E>): bo
  * 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
@@ -1463,6 +1719,11 @@ export 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
@@ -1506,6 +1767,11 @@ export 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