effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/Deferred.d.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"
  *
@@ -83,7 +84,8 @@ declare 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"
  *
@@ -116,26 +118,35 @@ declare 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>;
     resumes?: Array<(effect: Effect<A, E>) => void> | undefined;
 }
 /**
- * @since 2.0.0
+ * Checks whether a value is a `Deferred`.
+ *
  * @category Guards
+ * @since 2.0.0
  */
 export declare const isDeferred: <A, E>(u: unknown) => u is Deferred<A, E>;
 /**
- * @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
      */
     interface Variance<in out A, in out E> {
         readonly [TypeId]: {
@@ -145,9 +156,13 @@ export declare namespace Deferred {
     }
 }
 /**
- * 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"
  *
@@ -155,14 +170,15 @@ export declare namespace Deferred {
  * console.log(deferred)
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export declare const makeUnsafe: <A, E = never>() => Deferred<A, E>;
 /**
  * Creates a new `Deferred`.
  *
- * @example
+ * **Example** (Creating a Deferred)
+ *
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -174,8 +190,8 @@ export declare const makeUnsafe: <A, E = never>() => Deferred<A, E>;
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const make: <A, E = never>() => Effect<Deferred<A, E>>;
 declare const _await: <A, E>(self: Deferred<A, E>) => Effect<A, E>;
@@ -184,7 +200,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"
  *
@@ -197,18 +214,26 @@ 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"
  *
@@ -222,18 +247,26 @@ _await as await };
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -247,18 +280,26 @@ export declare 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"
      *
@@ -272,8 +313,8 @@ export declare 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>;
 };
@@ -281,7 +322,8 @@ export declare 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"
  *
@@ -295,15 +337,16 @@ export declare const complete: {
  * })
  * ```
  *
- * @since 2.0.0
  * @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.
      *
-     * @example
+     * **Example** (Completing a Deferred with an effect)
+     *
      * ```ts
      * import { Deferred, Effect } from "effect"
      *
@@ -317,15 +360,16 @@ export declare 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"
      *
@@ -339,8 +383,8 @@ export declare const completeWith: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <A, E>(self: Deferred<A, E>, effect: Effect<A, E>): Effect<boolean>;
 };
@@ -348,7 +392,8 @@ export declare 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"
  *
@@ -361,15 +406,16 @@ export declare const completeWith: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -382,15 +428,16 @@ export declare 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"
      *
@@ -403,16 +450,20 @@ export declare 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>;
 };
 /**
- * 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"
  *
@@ -423,15 +474,19 @@ export declare const done: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -442,15 +497,19 @@ export declare 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"
      *
@@ -461,16 +520,21 @@ export declare const fail: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <A, E>(self: Deferred<A, E>, error: 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"
  *
@@ -481,15 +545,20 @@ export declare const fail: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -500,15 +569,20 @@ export declare 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"
      *
@@ -519,16 +593,20 @@ export declare const failSync: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <A, E>(self: Deferred<A, E>, evaluate: LazyArg<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"
  *
@@ -542,15 +620,19 @@ export declare const failSync: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -564,15 +646,19 @@ export declare 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"
      *
@@ -586,16 +672,21 @@ export declare const failCause: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <A, E>(self: Deferred<A, E>, cause: Cause.Cause<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"
  *
@@ -609,15 +700,20 @@ export declare const failCause: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -631,15 +727,20 @@ export declare 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"
      *
@@ -653,16 +754,20 @@ export declare 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>;
 };
 /**
- * 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"
  *
@@ -676,15 +781,19 @@ export declare const failCauseSync: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -698,15 +807,19 @@ export declare 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"
      *
@@ -720,16 +833,21 @@ export declare const die: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <A, E>(self: Deferred<A, E>, defect: unknown): 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"
  *
@@ -743,15 +861,20 @@ export declare const die: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -765,15 +888,20 @@ export declare 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"
      *
@@ -787,17 +915,21 @@ export declare const dieSync: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <A, E>(self: Deferred<A, E>, evaluate: LazyArg<unknown>): Effect<boolean>;
 };
 /**
- * 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"
  *
@@ -808,15 +940,20 @@ export declare const dieSync: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const interrupt: <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"
  *
@@ -827,15 +964,20 @@ export declare const interrupt: <A, E>(self: Deferred<A, E>) => Effect<boolean>;
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -846,15 +988,20 @@ export declare 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"
      *
@@ -865,8 +1012,8 @@ export declare const interruptWith: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <A, E>(self: Deferred<A, E>, fiberId: number): Effect<boolean>;
 };
@@ -874,7 +1021,8 @@ export declare 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"
  *
@@ -889,16 +1037,16 @@ export declare const interruptWith: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 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.
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const isDoneUnsafe: <A, E>(self: Deferred<A, E>) => boolean;
 /**
@@ -906,7 +1054,8 @@ export declare const isDoneUnsafe: <A, E>(self: Deferred<A, E>) => boolean;
  * `Option.some(effect)` when the `Deferred` is completed, `Option.none()`
  * otherwise.
  *
- * @example
+ * **Example** (Polling Deferred completion)
+ *
  * ```ts
  * import { Deferred, Effect } from "effect"
  *
@@ -921,14 +1070,19 @@ export declare const isDoneUnsafe: <A, E>(self: Deferred<A, E>) => boolean;
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare function poll<A, E>(self: Deferred<A, E>): Effect<Option.Option<Effect<A, E>>>;
 /**
- * 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"
  *
@@ -941,14 +1095,19 @@ export declare function poll<A, E>(self: Deferred<A, E>): Effect<Option.Option<E
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -961,14 +1120,19 @@ export declare 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"
      *
@@ -981,15 +1145,21 @@ export declare const succeed: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <A, E>(self: Deferred<A, E>, value: A): 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"
  *
@@ -1002,14 +1172,20 @@ export declare const succeed: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -1022,14 +1198,20 @@ export declare 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"
      *
@@ -1042,16 +1224,21 @@ export declare const sync: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <A, E>(self: Deferred<A, E>, evaluate: LazyArg<A>): Effect<boolean>;
 };
 /**
- * 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"
  *
@@ -1060,21 +1247,23 @@ export declare const sync: {
  * console.log(success) // true
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export declare const doneUnsafe: <A, E>(self: Deferred<A, E>, effect: Effect<A, E>) => boolean;
 /**
- * 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"
  *
@@ -1101,21 +1290,23 @@ export declare const doneUnsafe: <A, E>(self: Deferred<A, E>, effect: Effect<A,
  * // true
  * ```
  *
- * @since 2.0.0
  * @category Synchronization Utilities
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -1142,21 +1333,23 @@ export declare 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"
      *
@@ -1183,8 +1376,8 @@ export declare 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>;
 };