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

package/src/Deferred.ts

@@ -15,7 +15,8 @@
  * - **Fiber-safe**: Thread-safe operations across concurrent fibers
  * - **Composable**: Works seamlessly with other Effect operations
  *
- * @example
+ * **Example** (Coordinating fibers with a Deferred)
+ *
  * ```ts
  * import { Deferred, Effect, Fiber } from "effect"
  *
@@ -89,7 +90,8 @@ const TypeId = "~effect/Deferred"
  * require the coordinated action of multiple fibers, and for building
  * higher-level concurrent or asynchronous structures.
  *
- * @example
+ * **Example** (Creating a Deferred for inter-fiber communication)
+ *
  * ```ts
  * import { Deferred, Effect, Fiber } from "effect"
  *
@@ -122,8 +124,8 @@ const TypeId = "~effect/Deferred"
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Deferred<in out A, in out E = never> extends Deferred.Variance<A, E>, Pipeable {
   effect?: Effect<A, E>
@@ -131,19 +133,28 @@ export interface Deferred<in out A, in out E = never> extends Deferred.Variance<
 }
 
 /**
- * @since 2.0.0
+ * Checks whether a value is a `Deferred`.
+ *
  * @category Guards
+ * @since 2.0.0
  */
 export const isDeferred = <A, E>(u: unknown): u is Deferred<A, E> => hasProperty(u, TypeId)
 
 /**
- * @since 2.0.0
+ * Companion namespace containing type-level metadata for `Deferred`.
+ *
  * @category models
+ * @since 2.0.0
  */
 export declare namespace Deferred {
   /**
-   * @since 2.0.0
+   * Type-level variance marker for the value and error channels of `Deferred`.
+   *
+   * This interface is part of the public type structure and is not intended to
+   * be constructed directly.
+   *
    * @category models
+   * @since 2.0.0
    */
   export interface Variance<in out A, in out E> {
     readonly [TypeId]: {
@@ -164,9 +175,13 @@ const DeferredProto = {
 }
 
 /**
- * Unsafely creates a new `Deferred`
+ * Synchronously creates an empty `Deferred` outside the `Effect` runtime.
+ *
+ * Prefer `Deferred.make` in effectful code so allocation is represented in
+ * `Effect`; use this only when direct synchronous allocation is required.
+ *
+ * **Example** (Creating a Deferred unsafely)
  *
- * @example
  * ```ts
  * import { Deferred } from "effect"
  *
@@ -174,8 +189,8 @@ const DeferredProto = {
  * console.log(deferred)
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export const makeUnsafe = <A, E = never>(): Deferred<A, E> => {
   const self = Object.create(DeferredProto)
@@ -187,7 +202,8 @@ export const makeUnsafe = <A, E = never>(): Deferred<A, E> => {
 /**
  * Creates a new `Deferred`.
  *
- * @example
+ * **Example** (Creating a Deferred)
+ *
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -199,8 +215,8 @@ export const makeUnsafe = <A, E = never>(): Deferred<A, E> => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <A, E = never>(): Effect<Deferred<A, E>> => internalEffect.sync(() => makeUnsafe())
 
@@ -220,7 +236,8 @@ export {
    * Retrieves the value of the `Deferred`, suspending the fiber running the
    * workflow until the result is available.
    *
-   * @example
+   * **Example** (Awaiting a Deferred value)
+   *
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -233,20 +250,28 @@ export {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   _await as await
 }
 
 /**
- * Completes the deferred with the result of the specified effect. If the
- * deferred has already been completed, the method will produce false.
+ * Completes the `Deferred` with the supplied `Effect` without running or
+ * memoizing it.
+ *
+ * Awaiting fibers run the stored effect when they await, so repeated awaits can
+ * repeat the effect. Returns `false` if the `Deferred` has already been
+ * completed.
+ *
+ * Use `Deferred.complete` when the effect should be evaluated once and the
+ * resulting `Exit` memoized.
  *
  * Note that `Deferred.completeWith` will be much faster, so consider using
  * that if you do not need to memoize the result of the specified effect.
  *
- * @example
+ * **Example** (Completing a Deferred from an effect)
+ *
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -260,18 +285,26 @@ export {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 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.
+   * Completes the `Deferred` with the supplied `Effect` without running or
+   * memoizing it.
+   *
+   * Awaiting fibers run the stored effect when they await, so repeated awaits can
+   * repeat the effect. Returns `false` if the `Deferred` has already been
+   * completed.
+   *
+   * Use `Deferred.complete` when the effect should be evaluated once and the
+   * resulting `Exit` memoized.
    *
    * Note that `Deferred.completeWith` will be much faster, so consider using
    * that if you do not need to memoize the result of the specified effect.
    *
-   * @example
+   * **Example** (Completing a Deferred from an effect)
+   *
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -285,18 +318,26 @@ export const complete: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E, R>(effect: Effect<A, E, R>): (self: Deferred<A, E>) => 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.
+   * Completes the `Deferred` with the supplied `Effect` without running or
+   * memoizing it.
+   *
+   * Awaiting fibers run the stored effect when they await, so repeated awaits can
+   * repeat the effect. Returns `false` if the `Deferred` has already been
+   * completed.
+   *
+   * Use `Deferred.complete` when the effect should be evaluated once and the
+   * resulting `Exit` memoized.
    *
    * Note that `Deferred.completeWith` will be much faster, so consider using
    * that if you do not need to memoize the result of the specified effect.
    *
-   * @example
+   * **Example** (Completing a Deferred from an effect)
+   *
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -310,8 +351,8 @@ export const complete: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E, R>(self: Deferred<A, E>, effect: Effect<A, E, R>): Effect<boolean, never, R>
 } = dual(
@@ -324,7 +365,8 @@ 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.
  *
- * @example
+ * **Example** (Completing a Deferred with an effect)
+ *
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -338,15 +380,16 @@ export const complete: {
  * })
  * ```
  *
- * @since 2.0.0
  * @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.
    *
-   * @example
+   * **Example** (Completing a Deferred with an effect)
+   *
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -360,15 +403,16 @@ export const completeWith: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @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.
    *
-   * @example
+   * **Example** (Completing a Deferred with an effect)
+   *
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -382,8 +426,8 @@ export const completeWith: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, effect: Effect<A, E>): Effect<boolean>
 } = dual(
@@ -396,7 +440,8 @@ 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`.
  *
- * @example
+ * **Example** (Completing a Deferred with an Exit)
+ *
  * ```ts
  * import { Deferred, Effect, Exit } from "effect"
  *
@@ -409,15 +454,16 @@ export const completeWith: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 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`.
    *
-   * @example
+   * **Example** (Completing a Deferred with an Exit)
+   *
    * ```ts
    * import { Deferred, Effect, Exit } from "effect"
    *
@@ -430,15 +476,16 @@ export const done: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @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
    * propagated to all fibers waiting on the value of the `Deferred`.
    *
-   * @example
+   * **Example** (Completing a Deferred with an Exit)
+   *
    * ```ts
    * import { Deferred, Effect, Exit } from "effect"
    *
@@ -451,17 +498,21 @@ export const done: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, exit: Exit.Exit<A, E>): Effect<boolean>
 } = completeWith as any
 
 /**
- * Fails the `Deferred` with the specified error, which will be propagated to
- * all fibers waiting on the value of the `Deferred`.
+ * Attempts to complete the `Deferred` with the specified error.
+ *
+ * Fibers waiting on the `Deferred` fail with that error only if this call
+ * completes it. The returned effect succeeds with `true` when this call
+ * completed the `Deferred`, or `false` if it was already completed.
+ *
+ * **Example** (Failing a Deferred with an error)
  *
- * @example
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -472,15 +523,19 @@ export const done: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const fail: {
   /**
-   * Fails the `Deferred` with the specified error, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Attempts to complete the `Deferred` with the specified error.
+   *
+   * Fibers waiting on the `Deferred` fail with that error only if this call
+   * completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Failing a Deferred with an error)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -491,15 +546,19 @@ export const fail: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <E>(error: E): <A>(self: Deferred<A, E>) => Effect<boolean>
   /**
-   * Fails the `Deferred` with the specified error, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Attempts to complete the `Deferred` with the specified error.
+   *
+   * Fibers waiting on the `Deferred` fail with that error only if this call
+   * completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Failing a Deferred with an error)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -510,17 +569,22 @@ export const fail: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, error: E): Effect<boolean>
 } = dual(2, <A, E>(self: Deferred<A, E>, error: E): Effect<boolean> => done(self, core.exitFail(error)))
 
 /**
- * Fails the `Deferred` with the specified error, which will be propagated to
- * all fibers waiting on the value of the `Deferred`.
+ * Computes an error when the returned effect is run, then attempts to complete
+ * the `Deferred` with that error.
+ *
+ * Fibers waiting on the `Deferred` fail with the computed error only if this
+ * call completes it. The returned effect succeeds with `true` when this call
+ * completed the `Deferred`, or `false` if it was already completed.
+ *
+ * **Example** (Failing a Deferred with a lazy error)
  *
- * @example
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -531,15 +595,20 @@ export const fail: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const failSync: {
   /**
-   * Fails the `Deferred` with the specified error, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Computes an error when the returned effect is run, then attempts to complete
+   * the `Deferred` with that error.
+   *
+   * Fibers waiting on the `Deferred` fail with the computed error only if this
+   * call completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Failing a Deferred with a lazy error)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -550,15 +619,20 @@ export const failSync: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <E>(evaluate: LazyArg<E>): <A>(self: Deferred<A, E>) => Effect<boolean>
   /**
-   * Fails the `Deferred` with the specified error, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Computes an error when the returned effect is run, then attempts to complete
+   * the `Deferred` with that error.
+   *
+   * Fibers waiting on the `Deferred` fail with the computed error only if this
+   * call completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Failing a Deferred with a lazy error)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -569,8 +643,8 @@ export const failSync: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, evaluate: LazyArg<E>): Effect<boolean>
 } = dual(
@@ -580,10 +654,14 @@ export const failSync: {
 )
 
 /**
- * Fails the `Deferred` with the specified `Cause`, which will be propagated to
- * all fibers waiting on the value of the `Deferred`.
+ * Attempts to complete the `Deferred` with the specified `Cause`.
+ *
+ * Fibers waiting on the `Deferred` observe that cause only if this call
+ * completes it. The returned effect succeeds with `true` when this call
+ * completed the `Deferred`, or `false` if it was already completed.
+ *
+ * **Example** (Failing a Deferred with a Cause)
  *
- * @example
  * ```ts
  * import { Cause, Deferred, Effect } from "effect"
  *
@@ -597,15 +675,19 @@ export const failSync: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const failCause: {
   /**
-   * Fails the `Deferred` with the specified `Cause`, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Attempts to complete the `Deferred` with the specified `Cause`.
+   *
+   * Fibers waiting on the `Deferred` observe that cause only if this call
+   * completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Failing a Deferred with a Cause)
    *
-   * @example
    * ```ts
    * import { Cause, Deferred, Effect } from "effect"
    *
@@ -619,15 +701,19 @@ export const failCause: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <E>(cause: Cause.Cause<E>): <A>(self: Deferred<A, E>) => Effect<boolean>
   /**
-   * Fails the `Deferred` with the specified `Cause`, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Attempts to complete the `Deferred` with the specified `Cause`.
+   *
+   * Fibers waiting on the `Deferred` observe that cause only if this call
+   * completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Failing a Deferred with a Cause)
    *
-   * @example
    * ```ts
    * import { Cause, Deferred, Effect } from "effect"
    *
@@ -641,8 +727,8 @@ export const failCause: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, cause: Cause.Cause<E>): Effect<boolean>
 } = dual(
@@ -651,10 +737,15 @@ export const failCause: {
 )
 
 /**
- * Fails the `Deferred` with the specified `Cause`, which will be propagated to
- * all fibers waiting on the value of the `Deferred`.
+ * Computes a `Cause` when the returned effect is run, then attempts to
+ * complete the `Deferred` with that cause.
+ *
+ * Fibers waiting on the `Deferred` observe the computed cause only if this
+ * call completes it. The returned effect succeeds with `true` when this call
+ * completed the `Deferred`, or `false` if it was already completed.
+ *
+ * **Example** (Failing a Deferred with a lazy Cause)
  *
- * @example
  * ```ts
  * import { Cause, Deferred, Effect } from "effect"
  *
@@ -668,15 +759,20 @@ export const failCause: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const failCauseSync: {
   /**
-   * Fails the `Deferred` with the specified `Cause`, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Computes a `Cause` when the returned effect is run, then attempts to
+   * complete the `Deferred` with that cause.
+   *
+   * Fibers waiting on the `Deferred` observe the computed cause only if this
+   * call completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Failing a Deferred with a lazy Cause)
    *
-   * @example
    * ```ts
    * import { Cause, Deferred, Effect } from "effect"
    *
@@ -690,15 +786,20 @@ export const failCauseSync: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <E>(evaluate: LazyArg<Cause.Cause<E>>): <A>(self: Deferred<A, E>) => Effect<boolean>
   /**
-   * Fails the `Deferred` with the specified `Cause`, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Computes a `Cause` when the returned effect is run, then attempts to
+   * complete the `Deferred` with that cause.
+   *
+   * Fibers waiting on the `Deferred` observe the computed cause only if this
+   * call completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Failing a Deferred with a lazy Cause)
    *
-   * @example
    * ```ts
    * import { Cause, Deferred, Effect } from "effect"
    *
@@ -712,8 +813,8 @@ export const failCauseSync: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, evaluate: LazyArg<Cause.Cause<E>>): Effect<boolean>
 } = dual(
@@ -723,10 +824,14 @@ export const failCauseSync: {
 )
 
 /**
- * Kills the `Deferred` with the specified defect, which will be propagated to
- * all fibers waiting on the value of the `Deferred`.
+ * Attempts to complete the `Deferred` with a defect.
+ *
+ * Fibers waiting on the `Deferred` die with that defect only if this call
+ * completes it. The returned effect succeeds with `true` when this call
+ * completed the `Deferred`, or `false` if it was already completed.
+ *
+ * **Example** (Killing a Deferred with a defect)
  *
- * @example
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -740,15 +845,19 @@ export const failCauseSync: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const die: {
   /**
-   * Kills the `Deferred` with the specified defect, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Attempts to complete the `Deferred` with a defect.
+   *
+   * Fibers waiting on the `Deferred` die with that defect only if this call
+   * completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Killing a Deferred with a defect)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -762,15 +871,19 @@ export const die: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   (defect: unknown): <A, E>(self: Deferred<A, E>) => Effect<boolean>
   /**
-   * Kills the `Deferred` with the specified defect, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Attempts to complete the `Deferred` with a defect.
+   *
+   * Fibers waiting on the `Deferred` die with that defect only if this call
+   * completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Killing a Deferred with a defect)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -784,17 +897,22 @@ export const die: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, defect: unknown): Effect<boolean>
 } = dual(2, <A, E>(self: Deferred<A, E>, defect: unknown): Effect<boolean> => done(self, core.exitDie(defect)))
 
 /**
- * Kills the `Deferred` with the specified defect, which will be propagated to
- * all fibers waiting on the value of the `Deferred`.
+ * Computes a defect when the returned effect is run, then attempts to complete
+ * the `Deferred` with that defect.
+ *
+ * Fibers waiting on the `Deferred` die with the computed defect only if this
+ * call completes it. The returned effect succeeds with `true` when this call
+ * completed the `Deferred`, or `false` if it was already completed.
+ *
+ * **Example** (Killing a Deferred with a lazy defect)
  *
- * @example
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -808,15 +926,20 @@ export const die: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const dieSync: {
   /**
-   * Kills the `Deferred` with the specified defect, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Computes a defect when the returned effect is run, then attempts to complete
+   * the `Deferred` with that defect.
+   *
+   * Fibers waiting on the `Deferred` die with the computed defect only if this
+   * call completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Killing a Deferred with a lazy defect)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -830,15 +953,20 @@ export const dieSync: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   (evaluate: LazyArg<unknown>): <A, E>(self: Deferred<A, E>) => Effect<boolean>
   /**
-   * Kills the `Deferred` with the specified defect, which will be propagated to
-   * all fibers waiting on the value of the `Deferred`.
+   * Computes a defect when the returned effect is run, then attempts to complete
+   * the `Deferred` with that defect.
+   *
+   * Fibers waiting on the `Deferred` die with the computed defect only if this
+   * call completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Killing a Deferred with a lazy defect)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -852,8 +980,8 @@ export const dieSync: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, evaluate: LazyArg<unknown>): Effect<boolean>
 } = dual(
@@ -863,11 +991,15 @@ export const dieSync: {
 )
 
 /**
- * Completes the `Deferred` with interruption. This will interrupt all fibers
- * waiting on the value of the `Deferred` with the `FiberId` of the fiber
- * calling this method.
+ * Attempts to complete the `Deferred` with interruption by the current fiber.
+ *
+ * Fibers waiting on the `Deferred` are interrupted with the current fiber id
+ * only if this call completes it. The returned effect succeeds with `true`
+ * when this call completed the `Deferred`, or `false` if it was already
+ * completed.
+ *
+ * **Example** (Interrupting a Deferred)
  *
- * @example
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -878,17 +1010,22 @@ export const dieSync: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const interrupt = <A, E>(self: Deferred<A, E>): Effect<boolean> =>
   core.withFiber((fiber) => interruptWith(self, fiber.id))
 
 /**
- * Completes the `Deferred` with interruption. This will interrupt all fibers
- * waiting on the value of the `Deferred` with the specified `FiberId`.
+ * Attempts to complete the `Deferred` with interruption by the specified
+ * `FiberId`.
+ *
+ * Fibers waiting on the `Deferred` are interrupted with that fiber id only if
+ * this call completes it. The returned effect succeeds with `true` when this
+ * call completed the `Deferred`, or `false` if it was already completed.
+ *
+ * **Example** (Interrupting a Deferred with a fiber id)
  *
- * @example
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -899,15 +1036,20 @@ export const interrupt = <A, E>(self: Deferred<A, E>): Effect<boolean> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const interruptWith: {
   /**
-   * Completes the `Deferred` with interruption. This will interrupt all fibers
-   * waiting on the value of the `Deferred` with the specified `FiberId`.
+   * Attempts to complete the `Deferred` with interruption by the specified
+   * `FiberId`.
+   *
+   * Fibers waiting on the `Deferred` are interrupted with that fiber id only if
+   * this call completes it. The returned effect succeeds with `true` when this
+   * call completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Interrupting a Deferred with a fiber id)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -918,15 +1060,20 @@ export const interruptWith: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   (fiberId: number): <A, E>(self: Deferred<A, E>) => Effect<boolean>
   /**
-   * Completes the `Deferred` with interruption. This will interrupt all fibers
-   * waiting on the value of the `Deferred` with the specified `FiberId`.
+   * Attempts to complete the `Deferred` with interruption by the specified
+   * `FiberId`.
+   *
+   * Fibers waiting on the `Deferred` are interrupted with that fiber id only if
+   * this call completes it. The returned effect succeeds with `true` when this
+   * call completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Interrupting a Deferred with a fiber id)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -937,8 +1084,8 @@ export const interruptWith: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, fiberId: number): Effect<boolean>
 } = dual(
@@ -951,7 +1098,8 @@ export const interruptWith: {
  * Returns `true` if this `Deferred` has already been completed with a value or
  * an error, `false` otherwise.
  *
- * @example
+ * **Example** (Checking Deferred completion)
+ *
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -966,8 +1114,8 @@ export const interruptWith: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const isDone = <A, E>(self: Deferred<A, E>): Effect<boolean> => internalEffect.sync(() => isDoneUnsafe(self))
 
@@ -975,8 +1123,8 @@ export const isDone = <A, E>(self: Deferred<A, E>): Effect<boolean> => internalE
  * Returns `true` if this `Deferred` has already been completed with a value or
  * an error, `false` otherwise.
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const isDoneUnsafe = <A, E>(self: Deferred<A, E>): boolean => self.effect !== undefined
 
@@ -985,7 +1133,8 @@ export const isDoneUnsafe = <A, E>(self: Deferred<A, E>): boolean => self.effect
  * `Option.some(effect)` when the `Deferred` is completed, `Option.none()`
  * otherwise.
  *
- * @example
+ * **Example** (Polling Deferred completion)
+ *
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -1000,17 +1149,22 @@ export const isDoneUnsafe = <A, E>(self: Deferred<A, E>): boolean => self.effect
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export function poll<A, E>(self: Deferred<A, E>): Effect<Option.Option<Effect<A, E>>> {
   return internalEffect.sync(() => Option.fromUndefinedOr(self.effect))
 }
 
 /**
- * Completes the `Deferred` with the specified value.
+ * Attempts to complete the `Deferred` with the specified value.
+ *
+ * Fibers waiting on the `Deferred` receive the value only if this call
+ * completes it. The returned effect succeeds with `true` when this call
+ * completed the `Deferred`, or `false` if it was already completed.
+ *
+ * **Example** (Completing a Deferred with a value)
  *
- * @example
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -1023,14 +1177,19 @@ export function poll<A, E>(self: Deferred<A, E>): Effect<Option.Option<Effect<A,
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const succeed: {
   /**
-   * Completes the `Deferred` with the specified value.
+   * Attempts to complete the `Deferred` with the specified value.
+   *
+   * Fibers waiting on the `Deferred` receive the value only if this call
+   * completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Completing a Deferred with a value)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -1043,14 +1202,19 @@ export const succeed: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(value: A): <E>(self: Deferred<A, E>) => Effect<boolean>
   /**
-   * Completes the `Deferred` with the specified value.
+   * Attempts to complete the `Deferred` with the specified value.
+   *
+   * Fibers waiting on the `Deferred` receive the value only if this call
+   * completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Completing a Deferred with a value)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -1063,16 +1227,22 @@ export const succeed: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, value: A): Effect<boolean>
 } = dual(2, <A, E>(self: Deferred<A, E>, value: A): Effect<boolean> => done(self, core.exitSucceed(value)))
 
 /**
- * Completes the `Deferred` with the specified lazily evaluated value.
+ * Computes a value when the returned effect is run, then attempts to complete
+ * the `Deferred` with that value.
+ *
+ * Fibers waiting on the `Deferred` receive the computed value only if this call
+ * completes it. The returned effect succeeds with `true` when this call
+ * completed the `Deferred`, or `false` if it was already completed.
+ *
+ * **Example** (Completing a Deferred with a lazy value)
  *
- * @example
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -1085,14 +1255,20 @@ export const succeed: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const sync: {
   /**
-   * Completes the `Deferred` with the specified lazily evaluated value.
+   * Computes a value when the returned effect is run, then attempts to complete
+   * the `Deferred` with that value.
+   *
+   * Fibers waiting on the `Deferred` receive the computed value only if this call
+   * completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Completing a Deferred with a lazy value)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -1105,14 +1281,20 @@ export const sync: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(evaluate: LazyArg<A>): <E>(self: Deferred<A, E>) => Effect<boolean>
   /**
-   * Completes the `Deferred` with the specified lazily evaluated value.
+   * Computes a value when the returned effect is run, then attempts to complete
+   * the `Deferred` with that value.
+   *
+   * Fibers waiting on the `Deferred` receive the computed value only if this call
+   * completes it. The returned effect succeeds with `true` when this call
+   * completed the `Deferred`, or `false` if it was already completed.
+   *
+   * **Example** (Completing a Deferred with a lazy value)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -1125,8 +1307,8 @@ export const sync: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, evaluate: LazyArg<A>): Effect<boolean>
 } = dual(
@@ -1136,10 +1318,15 @@ export const sync: {
 )
 
 /**
- * Unsafely exits the `Deferred` with the specified `Exit` value, which will be
- * propagated to all fibers waiting on the value of the `Deferred`.
+ * Synchronously attempts to complete the `Deferred` with the specified
+ * completion effect.
+ *
+ * This mutates the `Deferred` directly and should be reserved for low-level
+ * code; prefer the effectful completion APIs when possible. Returns `true` if
+ * this call completed the `Deferred`, or `false` if it was already completed.
+ *
+ * **Example** (Completing a Deferred unsafely)
  *
- * @example
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -1148,8 +1335,8 @@ export const sync: {
  * console.log(success) // true
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export const doneUnsafe = <A, E>(self: Deferred<A, E>, effect: Effect<A, E>): boolean => {
   if (self.effect) return false
@@ -1164,16 +1351,18 @@ export const doneUnsafe = <A, E>(self: Deferred<A, E>, effect: Effect<A, E>): bo
 }
 
 /**
- * Converts an `Effect` into an operation that completes a `Deferred` with its result.
+ * Runs an `Effect` and attempts to complete a `Deferred` with the effect's
+ * result.
  *
  * **Details**
  *
- * The `into` function takes an effect and a `Deferred` and ensures that the `Deferred`
- * is completed based on the outcome of the effect. If the effect succeeds, the `Deferred` is
- * completed with the success value. If the effect fails, the `Deferred` is completed with the
- * failure. Additionally, if the effect is interrupted, the `Deferred` will also be interrupted.
+ * If the effect succeeds, fails, dies, or is interrupted, that result is used
+ * as the attempted completion. The returned effect cannot fail; it succeeds
+ * with `true` if it completed the `Deferred`, or `false` if the `Deferred` was
+ * already completed.
+ *
+ * **Example** (Completing a Deferred from an effect result)
  *
- * @example
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -1200,21 +1389,23 @@ export const doneUnsafe = <A, E>(self: Deferred<A, E>, effect: Effect<A, E>): bo
  * // true
  * ```
  *
- * @since 2.0.0
  * @category Synchronization Utilities
+ * @since 2.0.0
  */
 export const into: {
   /**
-   * Converts an `Effect` into an operation that completes a `Deferred` with its result.
+   * Runs an `Effect` and attempts to complete a `Deferred` with the effect's
+   * result.
    *
    * **Details**
    *
-   * The `into` function takes an effect and a `Deferred` and ensures that the `Deferred`
-   * is completed based on the outcome of the effect. If the effect succeeds, the `Deferred` is
-   * completed with the success value. If the effect fails, the `Deferred` is completed with the
-   * failure. Additionally, if the effect is interrupted, the `Deferred` will also be interrupted.
+   * If the effect succeeds, fails, dies, or is interrupted, that result is used
+   * as the attempted completion. The returned effect cannot fail; it succeeds
+   * with `true` if it completed the `Deferred`, or `false` if the `Deferred` was
+   * already completed.
+   *
+   * **Example** (Completing a Deferred from an effect result)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -1241,21 +1432,23 @@ export const into: {
    * // true
    * ```
    *
-   * @since 2.0.0
    * @category Synchronization Utilities
+   * @since 2.0.0
    */
   <A, E>(deferred: Deferred<A, E>): <R>(self: Effect<A, E, R>) => Effect<boolean, never, R>
   /**
-   * Converts an `Effect` into an operation that completes a `Deferred` with its result.
+   * Runs an `Effect` and attempts to complete a `Deferred` with the effect's
+   * result.
    *
    * **Details**
    *
-   * The `into` function takes an effect and a `Deferred` and ensures that the `Deferred`
-   * is completed based on the outcome of the effect. If the effect succeeds, the `Deferred` is
-   * completed with the success value. If the effect fails, the `Deferred` is completed with the
-   * failure. Additionally, if the effect is interrupted, the `Deferred` will also be interrupted.
+   * If the effect succeeds, fails, dies, or is interrupted, that result is used
+   * as the attempted completion. The returned effect cannot fail; it succeeds
+   * with `true` if it completed the `Deferred`, or `false` if the `Deferred` was
+   * already completed.
+   *
+   * **Example** (Completing a Deferred from an effect result)
    *
-   * @example
    * ```ts
    * import { Deferred, Effect } from "effect"
    *
@@ -1282,8 +1475,8 @@ export const into: {
    * // true
    * ```
    *
-   * @since 2.0.0
    * @category Synchronization Utilities
+   * @since 2.0.0
    */
   <A, E, R>(self: Effect<A, E, R>, deferred: Deferred<A, E>): Effect<boolean, never, R>
 } = dual(