effect 4.0.0-beta.99 → 4.0.0-rc.109

package/src/Deferred.ts

@@ -33,36 +33,23 @@ const TypeId = "~effect/Deferred"
  *
  * **Example** (Creating a Deferred for inter-fiber communication)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Deferred, Effect, Fiber } from "effect"
  *
- * // Create and use a Deferred for inter-fiber communication
  * const program = Effect.gen(function*() {
- *   // Create a Deferred that will hold a string value
  *   const deferred: Deferred.Deferred<string> = yield* Deferred.make<string>()
- *
- *   // Fork a fiber that will set the deferred value
  *   const producer = yield* Effect.forkChild(
  *     Effect.gen(function*() {
- *       yield* Effect.sleep("100 millis")
  *       yield* Deferred.succeed(deferred, "Hello, World!")
  *     })
  *   )
  *
- *   // Fork a fiber that will await the deferred value
- *   const consumer = yield* Effect.forkChild(
- *     Effect.gen(function*() {
- *       const value = yield* Deferred.await(deferred)
- *       console.log("Received:", value)
- *       return value
- *     })
- *   )
- *
- *   // Wait for both fibers to complete
+ *   const consumer = yield* Effect.forkChild(Deferred.await(deferred))
  *   yield* Fiber.join(producer)
- *   const result = yield* Fiber.join(consumer)
- *   return result
+ *   return yield* Fiber.join(consumer)
  * })
+ *
+ * await Effect.runPromise(program) // => "Hello, World!"
  * ```
  *
  * @category models
@@ -140,11 +127,11 @@ const DeferredProto = {
  *
  * **Example** (Creating a Deferred unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Deferred } from "effect"
  *
  * const deferred = Deferred.makeUnsafe<number>()
- * console.log(deferred)
+ * Deferred.isDoneUnsafe(deferred) // => false
  * ```
  *
  * @category unsafe
@@ -166,15 +153,16 @@ export const makeUnsafe = <A, E = never>(): Deferred<A, E> => {
  *
  * **Example** (Creating a Deferred)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Deferred, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
  *   yield* Deferred.succeed(deferred, 42)
- *   const value = yield* Deferred.await(deferred)
- *   console.log(value) // 42
+ *   return yield* Deferred.await(deferred)
  * })
+ *
+ * await Effect.runPromise(program) // => 42
  * ```
  *
  * @category constructors
@@ -188,8 +176,12 @@ const _await = <A, E>(self: Deferred<A, E>): Effect<A, E> =>
     self.resumes ??= []
     self.resumes.push(resume)
     return internalEffect.sync(() => {
-      const index = self.resumes!.indexOf(resume)
-      self.resumes!.splice(index, 1)
+      // Completion resumes all waiters and clears `resumes`, so a cleanup
+      // running after completion has nothing to unregister.
+      const resumes = self.resumes
+      if (resumes === undefined) return
+      const index = resumes.indexOf(resume)
+      if (index >= 0) resumes.splice(index, 1)
     })
   })
 
@@ -209,16 +201,17 @@ export {
    *
    * **Example** (Awaiting a Deferred value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   yield* Deferred.succeed(deferred, 42)
    *
-   *   const value = yield* Deferred.await(deferred)
-   *   console.log(value) // 42
+   *   return yield* Deferred.await(deferred)
    * })
+   *
+   * await Effect.runPromise(program) // => 42
    * ```
    *
    * @see {@link complete} for completing from an effect and memoizing its result
@@ -246,17 +239,17 @@ export {
  *
  * **Example** (Completing a Deferred from an effect)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Deferred, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
  *   const completed = yield* Deferred.complete(deferred, Effect.succeed(42))
- *   console.log(completed) // true
- *
  *   const value = yield* Deferred.await(deferred)
- *   console.log(value) // 42
+ *   return [completed, value]
  * })
+ *
+ * await Effect.runPromise(program) // => [true, 42]
  * ```
  *
  * @see {@link completeWith} for storing an effect directly without memoizing its result
@@ -281,17 +274,17 @@ export const complete: {
    *
    * **Example** (Completing a Deferred from an effect)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   const completed = yield* Deferred.complete(deferred, Effect.succeed(42))
-   *   console.log(completed) // true
-   *
    *   const value = yield* Deferred.await(deferred)
-   *   console.log(value) // 42
+   *   return [completed, value]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, 42]
    * ```
    *
    * @see {@link completeWith} for storing an effect directly without memoizing its result
@@ -316,17 +309,17 @@ export const complete: {
    *
    * **Example** (Completing a Deferred from an effect)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   const completed = yield* Deferred.complete(deferred, Effect.succeed(42))
-   *   console.log(completed) // true
-   *
    *   const value = yield* Deferred.await(deferred)
-   *   console.log(value) // 42
+   *   return [completed, value]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, 42]
    * ```
    *
    * @see {@link completeWith} for storing an effect directly without memoizing its result
@@ -361,17 +354,17 @@ export const complete: {
  *
  * **Example** (Completing a Deferred with an effect)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Deferred, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
  *   const completed = yield* Deferred.completeWith(deferred, Effect.succeed(42))
- *   console.log(completed) // true
- *
  *   const value = yield* Deferred.await(deferred)
- *   console.log(value) // 42
+ *   return [completed, value]
  * })
+ *
+ * await Effect.runPromise(program) // => [true, 42]
  * ```
  *
  * @see {@link complete} for running an effect once and sharing its result
@@ -401,17 +394,17 @@ export const completeWith: {
    *
    * **Example** (Completing a Deferred with an effect)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   const completed = yield* Deferred.completeWith(deferred, Effect.succeed(42))
-   *   console.log(completed) // true
-   *
    *   const value = yield* Deferred.await(deferred)
-   *   console.log(value) // 42
+   *   return [completed, value]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, 42]
    * ```
    *
    * @see {@link complete} for running an effect once and sharing its result
@@ -441,17 +434,17 @@ export const completeWith: {
    *
    * **Example** (Completing a Deferred with an effect)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   const completed = yield* Deferred.completeWith(deferred, Effect.succeed(42))
-   *   console.log(completed) // true
-   *
    *   const value = yield* Deferred.await(deferred)
-   *   console.log(value) // 42
+   *   return [completed, value]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, 42]
    * ```
    *
    * @see {@link complete} for running an effect once and sharing its result
@@ -482,16 +475,16 @@ export const completeWith: {
  *
  * **Example** (Completing a Deferred with an Exit)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Deferred, Effect, Exit } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
  *   yield* Deferred.done(deferred, Exit.succeed(42))
- *
- *   const value = yield* Deferred.await(deferred)
- *   console.log(value) // 42
+ *   return yield* Effect.exit(Deferred.await(deferred))
  * })
+ *
+ * await Effect.runPromise(program) // => Exit.succeed(42)
  * ```
  *
  * @see {@link complete} for completing from an effect and memoizing its result
@@ -518,16 +511,16 @@ export const done: {
    *
    * **Example** (Completing a Deferred with an Exit)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   yield* Deferred.done(deferred, Exit.succeed(42))
-   *
-   *   const value = yield* Deferred.await(deferred)
-   *   console.log(value) // 42
+   *   return yield* Effect.exit(Deferred.await(deferred))
    * })
+   *
+   * await Effect.runPromise(program) // => Exit.succeed(42)
    * ```
    *
    * @see {@link complete} for completing from an effect and memoizing its result
@@ -554,16 +547,16 @@ export const done: {
    *
    * **Example** (Completing a Deferred with an Exit)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   yield* Deferred.done(deferred, Exit.succeed(42))
-   *
-   *   const value = yield* Deferred.await(deferred)
-   *   console.log(value) // 42
+   *   return yield* Effect.exit(Deferred.await(deferred))
    * })
+   *
+   * await Effect.runPromise(program) // => Exit.succeed(42)
    * ```
    *
    * @see {@link complete} for completing from an effect and memoizing its result
@@ -592,14 +585,17 @@ export const done: {
  *
  * **Example** (Failing a Deferred with an error)
  *
- * ```ts
- * import { Deferred, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Deferred, Effect, Exit } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number, string>()
  *   const success = yield* Deferred.fail(deferred, "Operation failed")
- *   console.log(success) // true
+ *   const exit = yield* Effect.exit(Deferred.await(deferred))
+ *   return [success, exit]
  * })
+ *
+ * await Effect.runPromise(program) // => [true, Exit.fail("Operation failed")]
  * ```
  *
  * @category completion
@@ -621,14 +617,17 @@ export const fail: {
    *
    * **Example** (Failing a Deferred with an error)
    *
-   * ```ts
-   * import { Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number, string>()
    *   const success = yield* Deferred.fail(deferred, "Operation failed")
-   *   console.log(success) // true
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.fail("Operation failed")]
    * ```
    *
    * @category completion
@@ -650,14 +649,17 @@ export const fail: {
    *
    * **Example** (Failing a Deferred with an error)
    *
-   * ```ts
-   * import { Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number, string>()
    *   const success = yield* Deferred.fail(deferred, "Operation failed")
-   *   console.log(success) // true
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.fail("Operation failed")]
    * ```
    *
    * @category completion
@@ -683,14 +685,17 @@ export const fail: {
  *
  * **Example** (Failing a Deferred with a lazy error)
  *
- * ```ts
- * import { Deferred, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Deferred, Effect, Exit } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number, string>()
  *   const success = yield* Deferred.failSync(deferred, () => "Lazy error")
- *   console.log(success) // true
+ *   const exit = yield* Effect.exit(Deferred.await(deferred))
+ *   return [success, exit]
  * })
+ *
+ * await Effect.runPromise(program) // => [true, Exit.fail("Lazy error")]
  * ```
  *
  * @category completion
@@ -714,14 +719,17 @@ export const failSync: {
    *
    * **Example** (Failing a Deferred with a lazy error)
    *
-   * ```ts
-   * import { Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number, string>()
    *   const success = yield* Deferred.failSync(deferred, () => "Lazy error")
-   *   console.log(success) // true
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.fail("Lazy error")]
    * ```
    *
    * @category completion
@@ -745,14 +753,17 @@ export const failSync: {
    *
    * **Example** (Failing a Deferred with a lazy error)
    *
-   * ```ts
-   * import { Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number, string>()
    *   const success = yield* Deferred.failSync(deferred, () => "Lazy error")
-   *   console.log(success) // true
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.fail("Lazy error")]
    * ```
    *
    * @category completion
@@ -780,17 +791,17 @@ export const failSync: {
  *
  * **Example** (Failing a Deferred with a Cause)
  *
- * ```ts
- * import { Cause, Deferred, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Deferred, Effect, Exit } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number, string>()
- *   const success = yield* Deferred.failCause(
- *     deferred,
- *     Cause.fail("Operation failed")
- *   )
- *   console.log(success) // true
+ *   const success = yield* Deferred.failCause(deferred, Cause.fail("Operation failed"))
+ *   const exit = yield* Effect.exit(Deferred.await(deferred))
+ *   return [success, exit]
  * })
+ *
+ * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Operation failed"))]
  * ```
  *
  * @category completion
@@ -812,17 +823,17 @@ export const failCause: {
    *
    * **Example** (Failing a Deferred with a Cause)
    *
-   * ```ts
-   * import { Cause, Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Cause, Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number, string>()
-   *   const success = yield* Deferred.failCause(
-   *     deferred,
-   *     Cause.fail("Operation failed")
-   *   )
-   *   console.log(success) // true
+   *   const success = yield* Deferred.failCause(deferred, Cause.fail("Operation failed"))
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Operation failed"))]
    * ```
    *
    * @category completion
@@ -844,17 +855,17 @@ export const failCause: {
    *
    * **Example** (Failing a Deferred with a Cause)
    *
-   * ```ts
-   * import { Cause, Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Cause, Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number, string>()
-   *   const success = yield* Deferred.failCause(
-   *     deferred,
-   *     Cause.fail("Operation failed")
-   *   )
-   *   console.log(success) // true
+   *   const success = yield* Deferred.failCause(deferred, Cause.fail("Operation failed"))
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Operation failed"))]
    * ```
    *
    * @category completion
@@ -883,17 +894,17 @@ export const failCause: {
  *
  * **Example** (Failing a Deferred with a lazy Cause)
  *
- * ```ts
- * import { Cause, Deferred, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Deferred, Effect, Exit } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number, string>()
- *   const success = yield* Deferred.failCauseSync(
- *     deferred,
- *     () => Cause.fail("Lazy error")
- *   )
- *   console.log(success) // true
+ *   const success = yield* Deferred.failCauseSync(deferred, () => Cause.fail("Lazy error"))
+ *   const exit = yield* Effect.exit(Deferred.await(deferred))
+ *   return [success, exit]
  * })
+ *
+ * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Lazy error"))]
  * ```
  *
  * @category completion
@@ -917,17 +928,17 @@ export const failCauseSync: {
    *
    * **Example** (Failing a Deferred with a lazy Cause)
    *
-   * ```ts
-   * import { Cause, Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Cause, Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number, string>()
-   *   const success = yield* Deferred.failCauseSync(
-   *     deferred,
-   *     () => Cause.fail("Lazy error")
-   *   )
-   *   console.log(success) // true
+   *   const success = yield* Deferred.failCauseSync(deferred, () => Cause.fail("Lazy error"))
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Lazy error"))]
    * ```
    *
    * @category completion
@@ -951,17 +962,17 @@ export const failCauseSync: {
    *
    * **Example** (Failing a Deferred with a lazy Cause)
    *
-   * ```ts
-   * import { Cause, Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Cause, Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number, string>()
-   *   const success = yield* Deferred.failCauseSync(
-   *     deferred,
-   *     () => Cause.fail("Lazy error")
-   *   )
-   *   console.log(success) // true
+   *   const success = yield* Deferred.failCauseSync(deferred, () => Cause.fail("Lazy error"))
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Lazy error"))]
    * ```
    *
    * @category completion
@@ -989,17 +1000,18 @@ export const failCauseSync: {
  *
  * **Example** (Killing a Deferred with a defect)
  *
- * ```ts
- * import { Deferred, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Deferred, Effect, Exit } from "effect"
  *
+ * const defect = new Error("Something went wrong")
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
- *   const success = yield* Deferred.die(
- *     deferred,
- *     new Error("Something went wrong")
- *   )
- *   console.log(success) // true
+ *   const success = yield* Deferred.die(deferred, defect)
+ *   const exit = yield* Effect.exit(Deferred.await(deferred))
+ *   return [success, exit]
  * })
+ *
+ * await Effect.runPromise(program) // => [true, Exit.die(defect)]
  * ```
  *
  * @category completion
@@ -1021,17 +1033,18 @@ export const die: {
    *
    * **Example** (Killing a Deferred with a defect)
    *
-   * ```ts
-   * import { Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Deferred, Effect, Exit } from "effect"
    *
+   * const defect = new Error("Something went wrong")
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
-   *   const success = yield* Deferred.die(
-   *     deferred,
-   *     new Error("Something went wrong")
-   *   )
-   *   console.log(success) // true
+   *   const success = yield* Deferred.die(deferred, defect)
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.die(defect)]
    * ```
    *
    * @category completion
@@ -1053,17 +1066,18 @@ export const die: {
    *
    * **Example** (Killing a Deferred with a defect)
    *
-   * ```ts
-   * import { Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Deferred, Effect, Exit } from "effect"
    *
+   * const defect = new Error("Something went wrong")
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
-   *   const success = yield* Deferred.die(
-   *     deferred,
-   *     new Error("Something went wrong")
-   *   )
-   *   console.log(success) // true
+   *   const success = yield* Deferred.die(deferred, defect)
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.die(defect)]
    * ```
    *
    * @category completion
@@ -1088,17 +1102,18 @@ export const die: {
  *
  * **Example** (Killing a Deferred with a lazy defect)
  *
- * ```ts
- * import { Deferred, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Deferred, Effect, Exit } from "effect"
  *
+ * const defect = new Error("Lazy error")
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
- *   const success = yield* Deferred.dieSync(
- *     deferred,
- *     () => new Error("Lazy error")
- *   )
- *   console.log(success) // true
+ *   const success = yield* Deferred.dieSync(deferred, () => defect)
+ *   const exit = yield* Effect.exit(Deferred.await(deferred))
+ *   return [success, exit]
  * })
+ *
+ * await Effect.runPromise(program) // => [true, Exit.die(defect)]
  * ```
  *
  * @category completion
@@ -1121,17 +1136,18 @@ export const dieSync: {
    *
    * **Example** (Killing a Deferred with a lazy defect)
    *
-   * ```ts
-   * import { Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Deferred, Effect, Exit } from "effect"
    *
+   * const defect = new Error("Lazy error")
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
-   *   const success = yield* Deferred.dieSync(
-   *     deferred,
-   *     () => new Error("Lazy error")
-   *   )
-   *   console.log(success) // true
+   *   const success = yield* Deferred.dieSync(deferred, () => defect)
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.die(defect)]
    * ```
    *
    * @category completion
@@ -1154,17 +1170,18 @@ export const dieSync: {
    *
    * **Example** (Killing a Deferred with a lazy defect)
    *
-   * ```ts
-   * import { Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Deferred, Effect, Exit } from "effect"
    *
+   * const defect = new Error("Lazy error")
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
-   *   const success = yield* Deferred.dieSync(
-   *     deferred,
-   *     () => new Error("Lazy error")
-   *   )
-   *   console.log(success) // true
+   *   const success = yield* Deferred.dieSync(deferred, () => defect)
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.die(defect)]
    * ```
    *
    * @category completion
@@ -1193,14 +1210,19 @@ export const dieSync: {
  *
  * **Example** (Interrupting a Deferred)
  *
- * ```ts
- * import { Deferred, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Deferred, Effect, Exit } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
  *   const success = yield* Deferred.interrupt(deferred)
- *   console.log(success) // true
+ *   const exit = yield* Effect.exit(Deferred.await(deferred))
+ *   return [success, exit] as const
  * })
+ *
+ * const [success, exit] = await Effect.runPromise(program)
+ * success // => true
+ * Exit.hasInterrupts(exit) // => true
  * ```
  *
  * @category completion
@@ -1225,14 +1247,17 @@ export const interrupt = <A, E>(self: Deferred<A, E>): Effect<boolean> =>
  *
  * **Example** (Interrupting a Deferred with a fiber id)
  *
- * ```ts
- * import { Deferred, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Deferred, Effect, Exit } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
  *   const success = yield* Deferred.interruptWith(deferred, 42)
- *   console.log(success) // true
+ *   const exit = yield* Effect.exit(Deferred.await(deferred))
+ *   return [success, exit]
  * })
+ *
+ * await Effect.runPromise(program) // => [true, Exit.interrupt(42)]
  * ```
  *
  * @category completion
@@ -1255,14 +1280,17 @@ export const interruptWith: {
    *
    * **Example** (Interrupting a Deferred with a fiber id)
    *
-   * ```ts
-   * import { Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   const success = yield* Deferred.interruptWith(deferred, 42)
-   *   console.log(success) // true
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.interrupt(42)]
    * ```
    *
    * @category completion
@@ -1285,14 +1313,17 @@ export const interruptWith: {
    *
    * **Example** (Interrupting a Deferred with a fiber id)
    *
-   * ```ts
-   * import { Deferred, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Deferred, Effect, Exit } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   const success = yield* Deferred.interruptWith(deferred, 42)
-   *   console.log(success) // true
+   *   const exit = yield* Effect.exit(Deferred.await(deferred))
+   *   return [success, exit]
    * })
+   *
+   * await Effect.runPromise(program) // => [true, Exit.interrupt(42)]
    * ```
    *
    * @category completion
@@ -1315,21 +1346,21 @@ export const interruptWith: {
  *
  * **Example** (Checking Deferred completion)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Deferred, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
  *   const beforeCompletion = yield* Deferred.isDone(deferred)
- *   console.log(beforeCompletion) // false
- *
  *   yield* Deferred.succeed(deferred, 42)
  *   const afterCompletion = yield* Deferred.isDone(deferred)
- *   console.log(afterCompletion) // true
+ *   return [beforeCompletion, afterCompletion]
  * })
+ *
+ * await Effect.runPromise(program) // => [false, true]
  * ```
  *
- * @category getters
+ * @category predicates
  * @since 2.0.0
  */
 export const isDone = <A, E>(self: Deferred<A, E>): Effect<boolean> => internalEffect.sync(() => isDoneUnsafe(self))
@@ -1345,7 +1376,7 @@ export const isDone = <A, E>(self: Deferred<A, E>): Effect<boolean> => internalE
  * @see {@link isDone} for checking completion inside `Effect`
  * @see {@link poll} for reading the completed effect when available
  *
- * @category getters
+ * @category predicates
  * @since 4.0.0
  */
 export const isDoneUnsafe = <A, E>(self: Deferred<A, E>): boolean => self.effect !== undefined
@@ -1362,18 +1393,19 @@ export const isDoneUnsafe = <A, E>(self: Deferred<A, E>): boolean => self.effect
  *
  * **Example** (Polling Deferred completion)
  *
- * ```ts
- * import { Deferred, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Deferred, Effect, Option } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
  *   const beforeCompletion = yield* Deferred.poll(deferred)
- *   console.log(beforeCompletion._tag === "None") // true
- *
  *   yield* Deferred.succeed(deferred, 42)
  *   const afterCompletion = yield* Deferred.poll(deferred)
- *   console.log(afterCompletion._tag === "Some") // true
+ *   const afterValue = yield* Effect.transposeOption(afterCompletion)
+ *   return [beforeCompletion, afterValue]
  * })
+ *
+ * await Effect.runPromise(program) // => [Option.none(), Option.some(42)]
  * ```
  *
  * @category getters
@@ -1398,16 +1430,17 @@ export function poll<A, E>(self: Deferred<A, E>): Effect<Option.Option<Effect<A,
  *
  * **Example** (Completing a Deferred with a value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Deferred, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
  *   yield* Deferred.succeed(deferred, 42)
  *
- *   const value = yield* Deferred.await(deferred)
- *   console.log(value) // 42
+ *   return yield* Deferred.await(deferred)
  * })
+ *
+ * await Effect.runPromise(program) // => 42
  * ```
  *
  * @category completion
@@ -1429,16 +1462,17 @@ export const succeed: {
    *
    * **Example** (Completing a Deferred with a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   yield* Deferred.succeed(deferred, 42)
    *
-   *   const value = yield* Deferred.await(deferred)
-   *   console.log(value) // 42
+   *   return yield* Deferred.await(deferred)
    * })
+   *
+   * await Effect.runPromise(program) // => 42
    * ```
    *
    * @category completion
@@ -1460,16 +1494,17 @@ export const succeed: {
    *
    * **Example** (Completing a Deferred with a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   yield* Deferred.succeed(deferred, 42)
    *
-   *   const value = yield* Deferred.await(deferred)
-   *   console.log(value) // 42
+   *   return yield* Deferred.await(deferred)
    * })
+   *
+   * await Effect.runPromise(program) // => 42
    * ```
    *
    * @category completion
@@ -1495,16 +1530,16 @@ export const succeed: {
  *
  * **Example** (Completing a Deferred with a lazy value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Deferred, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
  *   yield* Deferred.sync(deferred, () => 42)
- *
- *   const value = yield* Deferred.await(deferred)
- *   console.log(value) // 42
+ *   return yield* Deferred.await(deferred)
  * })
+ *
+ * await Effect.runPromise(program) // => 42
  * ```
  *
  * @category completion
@@ -1528,16 +1563,16 @@ export const sync: {
    *
    * **Example** (Completing a Deferred with a lazy value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   yield* Deferred.sync(deferred, () => 42)
-   *
-   *   const value = yield* Deferred.await(deferred)
-   *   console.log(value) // 42
+   *   return yield* Deferred.await(deferred)
    * })
+   *
+   * await Effect.runPromise(program) // => 42
    * ```
    *
    * @category completion
@@ -1561,16 +1596,16 @@ export const sync: {
    *
    * **Example** (Completing a Deferred with a lazy value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const deferred = yield* Deferred.make<number>()
    *   yield* Deferred.sync(deferred, () => 42)
-   *
-   *   const value = yield* Deferred.await(deferred)
-   *   console.log(value) // 42
+   *   return yield* Deferred.await(deferred)
    * })
+   *
+   * await Effect.runPromise(program) // => 42
    * ```
    *
    * @category completion
@@ -1600,12 +1635,11 @@ export const sync: {
  *
  * **Example** (Completing a Deferred unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Deferred, Effect } from "effect"
  *
  * const deferred = Deferred.makeUnsafe<number>()
- * const success = Deferred.doneUnsafe(deferred, Effect.succeed(42))
- * console.log(success) // true
+ * Deferred.doneUnsafe(deferred, Effect.succeed(42)) // => true
  * ```
  *
  * @category unsafe
@@ -1641,33 +1675,22 @@ export const doneUnsafe = <A, E>(self: Deferred<A, E>, effect: Effect<A, E>): bo
  *
  * **Example** (Completing a Deferred from an effect result)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Deferred, Effect } from "effect"
  *
- * // Define an effect that succeeds
  * const successEffect = Effect.succeed(42)
  *
  * const program = Effect.gen(function*() {
- *   // Create a deferred
  *   const deferred = yield* Deferred.make<number, string>()
- *
- *   // Complete the deferred using the successEffect
  *   const isCompleted = yield* Deferred.into(successEffect, deferred)
- *
- *   // Access the value of the deferred
  *   const value = yield* Deferred.await(deferred)
- *   console.log(value)
- *
- *   return isCompleted
+ *   return [isCompleted, value]
  * })
  *
- * Effect.runPromise(program).then(console.log)
- * // Output:
- * // 42
- * // true
+ * await Effect.runPromise(program) // => [true, 42]
  * ```
  *
- * @category Synchronization Utilities
+ * @category completion
  * @since 4.0.0
  */
 export const into: {
@@ -1689,33 +1712,22 @@ export const into: {
    *
    * **Example** (Completing a Deferred from an effect result)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect } from "effect"
    *
-   * // Define an effect that succeeds
    * const successEffect = Effect.succeed(42)
    *
    * const program = Effect.gen(function*() {
-   *   // Create a deferred
    *   const deferred = yield* Deferred.make<number, string>()
-   *
-   *   // Complete the deferred using the successEffect
    *   const isCompleted = yield* Deferred.into(successEffect, deferred)
-   *
-   *   // Access the value of the deferred
    *   const value = yield* Deferred.await(deferred)
-   *   console.log(value)
-   *
-   *   return isCompleted
+   *   return [isCompleted, value]
    * })
    *
-   * Effect.runPromise(program).then(console.log)
-   * // Output:
-   * // 42
-   * // true
+   * await Effect.runPromise(program) // => [true, 42]
    * ```
    *
-   * @category Synchronization Utilities
+   * @category completion
    * @since 4.0.0
    */
   <A, E>(deferred: Deferred<A, E>): <R>(self: Effect<A, E, R>) => Effect<boolean, never, R>
@@ -1737,33 +1749,22 @@ export const into: {
    *
    * **Example** (Completing a Deferred from an effect result)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Deferred, Effect } from "effect"
    *
-   * // Define an effect that succeeds
    * const successEffect = Effect.succeed(42)
    *
    * const program = Effect.gen(function*() {
-   *   // Create a deferred
    *   const deferred = yield* Deferred.make<number, string>()
-   *
-   *   // Complete the deferred using the successEffect
    *   const isCompleted = yield* Deferred.into(successEffect, deferred)
-   *
-   *   // Access the value of the deferred
    *   const value = yield* Deferred.await(deferred)
-   *   console.log(value)
-   *
-   *   return isCompleted
+   *   return [isCompleted, value]
    * })
    *
-   * Effect.runPromise(program).then(console.log)
-   * // Output:
-   * // 42
-   * // true
+   * await Effect.runPromise(program) // => [true, 42]
    * ```
    *
-   * @category Synchronization Utilities
+   * @category completion
    * @since 4.0.0
    */
   <A, E, R>(self: Effect<A, E, R>, deferred: Deferred<A, E>): Effect<boolean, never, R>