effect 4.0.0-beta.102 → 4.0.0-beta.104

package/src/Cause.ts

@@ -63,12 +63,10 @@ export const ReasonTypeId: "~effect/Cause/Reason" = core.CauseReasonTypeId
  *
  * **Example** (Creating and inspecting a cause)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const cause = Cause.fail("Something went wrong")
- * console.log(cause.reasons.length) // 1
- * console.log(Cause.isFailReason(cause.reasons[0])) // true
+ * Cause.fail("Something went wrong") // => Cause.fail("Something went wrong")
  * ```
  *
  * @category models
@@ -84,11 +82,11 @@ export interface Cause<out E> extends Pipeable, Inspectable, Equal {
  *
  * **Example** (Checking the runtime type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.isCause(Cause.fail("error"))) // true
- * console.log(Cause.isCause("not a cause")) // false
+ * Cause.isCause(Cause.fail("error")) // => true
+ * Cause.isCause("not a cause") // => false
  * ```
  *
  * @category guards
@@ -101,12 +99,12 @@ export const isCause: (self: unknown) => self is Cause<unknown> = core.isCause
  *
  * **Example** (Checking the runtime type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
  * const reason = Cause.fail("error").reasons[0]
- * console.log(Cause.isReason(reason)) // true
- * console.log(Cause.isReason("not a reason")) // false
+ * Cause.isReason(reason) // => true
+ * Cause.isReason("not a reason") // => false
  * ```
  *
  * @category guards
@@ -131,12 +129,12 @@ export const isReason: (self: unknown) => self is Reason<unknown> = core.isCause
  *
  * **Example** (Narrowing a reason)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
  * const reason = Cause.fail("error").reasons[0]
  * if (Cause.isFailReason(reason)) {
- *   console.log(reason.error) // "error"
+ *   reason.error // => "error"
  * }
  * ```
  *
@@ -155,12 +153,12 @@ export type Reason<E> = Fail<E> | Die | Interrupt
  *
  * **Example** (Filtering fail reasons)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
  * const cause = Cause.fail("error")
  * const fails = cause.reasons.filter(Cause.isFailReason)
- * console.log(fails[0].error) // "error"
+ * fails[0].error // => "error"
  * ```
  *
  * @see {@link isDieReason} — narrow to `Die`
@@ -181,12 +179,12 @@ export const isFailReason: <E>(self: Reason<E>) => self is Fail<E> = core.isFail
  *
  * **Example** (Filtering die reasons)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
  * const cause = Cause.die("defect")
  * const dies = cause.reasons.filter(Cause.isDieReason)
- * console.log(dies[0].defect) // "defect"
+ * dies[0].defect // => "defect"
  * ```
  *
  * @see {@link isFailReason} — narrow to `Fail`
@@ -207,12 +205,12 @@ export const isDieReason: <E>(self: Reason<E>) => self is Die = core.isDieReason
  *
  * **Example** (Filtering interrupt reasons)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
  * const cause = Cause.interrupt(123)
  * const interrupts = cause.reasons.filter(Cause.isInterruptReason)
- * console.log(interrupts[0].fiberId) // 123
+ * interrupts[0].fiberId // => 123
  * ```
  *
  * @see {@link isFailReason} — narrow to `Fail`
@@ -234,14 +232,14 @@ export declare namespace Cause {
    *
    * **Example** (Extracting the error type)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import type { Cause } from "effect"
    *
    * // string
    * type E = Cause.Cause.Error<Cause.Cause<string>>
    * ```
    *
-   * @category models
+   * @category utility types
    * @since 4.0.0
    */
   export type Error<T> = T extends Cause<infer E> ? E : never
@@ -280,14 +278,14 @@ export declare namespace Reason {
    *
    * **Example** (Extracting the error type)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import type { Cause } from "effect"
    *
    * // string
    * type E = Cause.Reason.Error<Cause.Reason<string>>
    * ```
    *
-   * @category models
+   * @category utility types
    * @since 4.0.0
    */
   export type Error<T> = T extends Reason<infer E> ? E : never
@@ -309,13 +307,13 @@ export declare namespace Reason {
  *
  * **Example** (Accessing the defect)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
  * const cause = Cause.die("Unexpected")
  * const reason = cause.reasons[0]
  * if (Cause.isDieReason(reason)) {
- *   console.log(reason.defect) // "Unexpected"
+ *   reason.defect // => "Unexpected"
  * }
  * ```
  *
@@ -344,13 +342,13 @@ export interface Die extends Cause.ReasonProto<"Die"> {
  *
  * **Example** (Accessing the error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
  * const cause = Cause.fail("Something went wrong")
  * const reason = cause.reasons[0]
  * if (Cause.isFailReason(reason)) {
- *   console.log(reason.error) // "Something went wrong"
+ *   reason.error // => "Something went wrong"
  * }
  * ```
  *
@@ -374,13 +372,13 @@ export interface Fail<out E> extends Cause.ReasonProto<"Fail"> {
  *
  * **Example** (Accessing the fiber ID)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
  * const cause = Cause.interrupt(123)
  * const reason = cause.reasons[0]
  * if (Cause.isInterruptReason(reason)) {
- *   console.log(reason.fiberId) // 123
+ *   reason.fiberId // => 123
  * }
  * ```
  *
@@ -412,15 +410,14 @@ export interface Interrupt extends Cause.ReasonProto<"Interrupt"> {
  *
  * **Example** (Building a cause from reasons)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
  * const reasons = [
  *   Cause.makeFailReason("err1"),
  *   Cause.makeFailReason("err2")
  * ]
- * const cause = Cause.fromReasons(reasons)
- * console.log(cause.reasons.length) // 2
+ * Cause.fromReasons(reasons) // => Cause.combine(Cause.fail("err1"), Cause.fail("err2"))
  * ```
  *
  * @see {@link combine} — merge two existing causes
@@ -447,13 +444,10 @@ export const fromReasons: <E>(
  *
  * **Example** (Combining with the empty cause)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const cause = Cause.combine(Cause.empty, Cause.fail("boom"))
- *
- * console.log(cause.reasons.length) // 1
- * console.log(Cause.hasFails(cause)) // true
+ * Cause.combine(Cause.empty, Cause.fail("boom")) // => Cause.fail("boom")
  * ```
  *
  * @see {@link combine} for merging causes where `empty` acts as the identity
@@ -473,12 +467,10 @@ export const empty: Cause<never> = core.causeEmpty
  *
  * **Example** (Creating a fail cause)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const cause = Cause.fail("Something went wrong")
- * console.log(cause.reasons.length) // 1
- * console.log(Cause.isFailReason(cause.reasons[0])) // true
+ * Cause.fail("Something went wrong") // => Cause.fromReasons([Cause.makeFailReason("Something went wrong")])
  * ```
  *
  * @see {@link die} — for untyped defects
@@ -499,12 +491,10 @@ export const fail: <E>(error: E) => Cause<E> = core.causeFail
  *
  * **Example** (Creating a die cause)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const cause = Cause.die("Unexpected")
- * console.log(cause.reasons.length) // 1
- * console.log(Cause.isDieReason(cause.reasons[0])) // true
+ * Cause.die("Unexpected") // => Cause.fromReasons([Cause.makeDieReason("Unexpected")])
  * ```
  *
  * @see {@link fail} — for typed errors
@@ -521,12 +511,10 @@ export const die: (defect: unknown) => Cause<never> = core.causeDie
  *
  * **Example** (Creating an interrupt cause)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const cause = Cause.interrupt(123)
- * console.log(cause.reasons.length) // 1
- * console.log(Cause.isInterruptReason(cause.reasons[0])) // true
+ * Cause.interrupt(123) // => Cause.fromReasons([Cause.makeInterruptReason(123)])
  * ```
  *
  * @see {@link fail} — for typed errors
@@ -547,12 +535,10 @@ export const interrupt: (fiberId?: number | undefined) => Cause<never> = effect.
  *
  * **Example** (Creating a Fail reason)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const reason = Cause.makeFailReason("error")
- * console.log(reason._tag) // "Fail"
- * console.log(reason.error) // "error"
+ * Cause.makeFailReason("error") // => Cause.fail("error").reasons[0]
  * ```
  *
  * @see {@link makeDieReason} — create a `Die` reason
@@ -573,12 +559,10 @@ export const makeFailReason = <E>(error: E): Fail<E> => new core.Fail(error)
  *
  * **Example** (Creating a Die reason)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const reason = Cause.makeDieReason("bug")
- * console.log(reason._tag) // "Die"
- * console.log(reason.defect) // "bug"
+ * Cause.makeDieReason("bug") // => Cause.die("bug").reasons[0]
  * ```
  *
  * @see {@link makeFailReason} — create a `Fail` reason
@@ -600,12 +584,10 @@ export const makeDieReason = (defect: unknown): Die => new core.Die(defect)
  *
  * **Example** (Creating an Interrupt reason)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const reason = Cause.makeInterruptReason(42)
- * console.log(reason._tag) // "Interrupt"
- * console.log(reason.fiberId) // 42
+ * Cause.makeInterruptReason(42) // => Cause.interrupt(42).reasons[0]
  * ```
  *
  * @see {@link makeFailReason} — create a `Fail` reason
@@ -626,12 +608,12 @@ export const makeInterruptReason: (fiberId?: number | undefined) => Interrupt =
  *
  * **Example** (Checking interrupt-only causes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.hasInterruptsOnly(Cause.interrupt(123))) // true
- * console.log(Cause.hasInterruptsOnly(Cause.fail("error")))  // false
- * console.log(Cause.hasInterruptsOnly(Cause.empty))          // false
+ * Cause.hasInterruptsOnly(Cause.interrupt(123)) // => true
+ * Cause.hasInterruptsOnly(Cause.fail("error")) // => false
+ * Cause.hasInterruptsOnly(Cause.empty) // => false
  * ```
  *
  * @see {@link hasInterrupts} — `true` if the cause contains *any* interrupts
@@ -659,14 +641,14 @@ export const hasInterruptsOnly: <E>(self: Cause<E>) => boolean = effect.hasInter
  *
  * **Example** (Mapping errors to uppercase)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
  * const cause = Cause.fail("error")
  * const mapped = Cause.map(cause, (e) => e.toUpperCase())
  * const reason = mapped.reasons[0]
  * if (Cause.isFailReason(reason)) {
- *   console.log(reason.error) // "ERROR"
+ *   reason.error // => "ERROR"
  * }
  * ```
  *
@@ -692,14 +674,14 @@ export const map: {
    *
    * **Example** (Mapping errors to uppercase)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cause } from "effect"
    *
    * const cause = Cause.fail("error")
    * const mapped = Cause.map(cause, (e) => e.toUpperCase())
    * const reason = mapped.reasons[0]
    * if (Cause.isFailReason(reason)) {
-   *   console.log(reason.error) // "ERROR"
+   *   reason.error // => "ERROR"
    * }
    * ```
    *
@@ -725,14 +707,14 @@ export const map: {
    *
    * **Example** (Mapping errors to uppercase)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cause } from "effect"
    *
    * const cause = Cause.fail("error")
    * const mapped = Cause.map(cause, (e) => e.toUpperCase())
    * const reason = mapped.reasons[0]
    * if (Cause.isFailReason(reason)) {
-   *   console.log(reason.error) // "ERROR"
+   *   reason.error // => "ERROR"
    * }
    * ```
    *
@@ -758,13 +740,11 @@ export const map: {
  *
  * **Example** (Combining two causes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const cause1 = Cause.fail("error1")
- * const cause2 = Cause.fail("error2")
- * const combined = Cause.combine(cause1, cause2)
- * console.log(combined.reasons.length) // 2
+ * const combined = Cause.combine(Cause.fail("error1"), Cause.fail("error2"))
+ * combined // => Cause.fromReasons([Cause.makeFailReason("error1"), Cause.makeFailReason("error2")])
  * ```
  *
  * @see {@link fromReasons} — build a cause from an array of reasons
@@ -790,13 +770,11 @@ export const combine: {
    *
    * **Example** (Combining two causes)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cause } from "effect"
    *
-   * const cause1 = Cause.fail("error1")
-   * const cause2 = Cause.fail("error2")
-   * const combined = Cause.combine(cause1, cause2)
-   * console.log(combined.reasons.length) // 2
+   * const combined = Cause.combine(Cause.fail("error1"), Cause.fail("error2"))
+   * combined // => Cause.fromReasons([Cause.makeFailReason("error1"), Cause.makeFailReason("error2")])
    * ```
    *
    * @see {@link fromReasons} — build a cause from an array of reasons
@@ -822,13 +800,11 @@ export const combine: {
    *
    * **Example** (Combining two causes)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cause } from "effect"
    *
-   * const cause1 = Cause.fail("error1")
-   * const cause2 = Cause.fail("error2")
-   * const combined = Cause.combine(cause1, cause2)
-   * console.log(combined.reasons.length) // 2
+   * const combined = Cause.combine(Cause.fail("error1"), Cause.fail("error2"))
+   * combined // => Cause.fromReasons([Cause.makeFailReason("error1"), Cause.makeFailReason("error2")])
    * ```
    *
    * @see {@link fromReasons} — build a cause from an array of reasons
@@ -866,11 +842,11 @@ export const combine: {
  *
  * **Example** (Squashing a cause)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.squash(Cause.fail("error")))    // "error"
- * console.log(Cause.squash(Cause.die("defect")))    // "defect"
+ * Cause.squash(Cause.fail("error")) // => "error"
+ * Cause.squash(Cause.die("defect")) // => "defect"
  * ```
  *
  * @see {@link prettyErrors} — non-lossy conversion to `Array<Error>`
@@ -891,11 +867,11 @@ export const squash: <E>(self: Cause<E>) => unknown = effect.causeSquash
  *
  * **Example** (Checking for typed errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.hasFails(Cause.fail("error"))) // true
- * console.log(Cause.hasFails(Cause.die("defect"))) // false
+ * Cause.hasFails(Cause.fail("error")) // => true
+ * Cause.hasFails(Cause.die("defect")) // => false
  * ```
  *
  * @see {@link hasDies} — check for defects
@@ -919,13 +895,10 @@ export const hasFails: <E>(self: Cause<E>) => boolean = effect.hasFails
  *
  * **Example** (Extracting the first Fail reason)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Result } from "effect"
  *
- * const result = Cause.findFail(Cause.fail("error"))
- * if (!Result.isFailure(result)) {
- *   console.log(result.success.error) // "error"
- * }
+ * Cause.findFail(Cause.fail("error")) // => Result.succeed(Cause.makeFailReason("error"))
  * ```
  *
  * @see {@link findError} — extract the unwrapped `E` value
@@ -949,13 +922,10 @@ export const findFail: <E>(self: Cause<E>) => Result.Result<Fail<E>, Cause<never
  *
  * **Example** (Extracting the first error value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Result } from "effect"
  *
- * const result = Cause.findError(Cause.fail("error"))
- * if (!Result.isFailure(result)) {
- *   console.log(result.success) // "error"
- * }
+ * Cause.findError(Cause.fail("error")) // => Result.succeed("error")
  * ```
  *
  * @see {@link findFail} — extract the full `Fail` reason
@@ -977,14 +947,11 @@ export const findError: <E>(self: Cause<E>) => Result.Result<E, Cause<never>> =
  *
  * **Example** (Extracting an error as Option)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Option } from "effect"
  *
- * const some = Cause.findErrorOption(Cause.fail("error"))
- * console.log(Option.isSome(some)) // true
- *
- * const none = Cause.findErrorOption(Cause.die("defect"))
- * console.log(Option.isNone(none)) // true
+ * Cause.findErrorOption(Cause.fail("error")) // => Option.some("error")
+ * Cause.findErrorOption(Cause.die("defect")) // => Option.none()
  * ```
  *
  * @see {@link findError} — `Result`-based variant
@@ -1004,11 +971,11 @@ export const findErrorOption: <E>(input: Cause<E>) => Option<E> = effect.findErr
  *
  * **Example** (Checking for defects)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.hasDies(Cause.die("defect"))) // true
- * console.log(Cause.hasDies(Cause.fail("error"))) // false
+ * Cause.hasDies(Cause.die("defect")) // => true
+ * Cause.hasDies(Cause.fail("error")) // => false
  * ```
  *
  * @see {@link hasFails} — check for typed errors
@@ -1031,13 +998,10 @@ export const hasDies: <E>(self: Cause<E>) => boolean = effect.hasDies
  *
  * **Example** (Extracting the first Die reason)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Result } from "effect"
  *
- * const result = Cause.findDie(Cause.die("defect"))
- * if (!Result.isFailure(result)) {
- *   console.log(result.success.defect) // "defect"
- * }
+ * Cause.findDie(Cause.die("defect")) // => Result.succeed(Cause.makeDieReason("defect"))
  * ```
  *
  * @see {@link findDefect} — extract the unwrapped defect value
@@ -1060,13 +1024,10 @@ export const findDie: <E>(self: Cause<E>) => Result.Result<Die, Cause<E>> = effe
  *
  * **Example** (Extracting the first defect)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Result } from "effect"
  *
- * const result = Cause.findDefect(Cause.die("defect"))
- * if (!Result.isFailure(result)) {
- *   console.log(result.success) // "defect"
- * }
+ * Cause.findDefect(Cause.die("defect")) // => Result.succeed("defect")
  * ```
  *
  * @see {@link findDie} — extract the full `Die` reason
@@ -1082,11 +1043,11 @@ export const findDefect: <E>(self: Cause<E>) => Result.Result<unknown, Cause<E>>
  *
  * **Example** (Checking for interruptions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.hasInterrupts(Cause.interrupt(123))) // true
- * console.log(Cause.hasInterrupts(Cause.fail("error")))  // false
+ * Cause.hasInterrupts(Cause.interrupt(123)) // => true
+ * Cause.hasInterrupts(Cause.fail("error")) // => false
  * ```
  *
  * @see {@link hasInterruptsOnly} — `true` only when *all* reasons are interrupts
@@ -1110,13 +1071,10 @@ export const hasInterrupts: <E>(self: Cause<E>) => boolean = effect.hasInterrupt
  *
  * **Example** (Extracting the first interrupt)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Result } from "effect"
  *
- * const result = Cause.findInterrupt(Cause.interrupt(42))
- * if (!Result.isFailure(result)) {
- *   console.log(result.success.fiberId) // 42
- * }
+ * Cause.findInterrupt(Cause.interrupt(42)) // => Result.succeed(Cause.makeInterruptReason(42))
  * ```
  *
  * @see {@link interruptors} — collect all interrupting fiber IDs as a `Set`
@@ -1138,7 +1096,7 @@ export const findInterrupt: <E>(self: Cause<E>) => Result.Result<Interrupt, Caus
  *
  * **Example** (Collecting interruptors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
  * const cause = Cause.combine(
@@ -1146,12 +1104,12 @@ export const findInterrupt: <E>(self: Cause<E>) => Result.Result<Interrupt, Caus
  *   Cause.interrupt(2)
  * )
  *
- * console.log(Cause.interruptors(cause)) // Set(2) { 1, 2 }
+ * Cause.interruptors(cause) // => new Set([1, 2])
  * ```
  *
  * @see {@link filterInterruptors} — `Result`-based variant
  *
- * @category accessors
+ * @category getters
  * @since 2.0.0
  */
 export const interruptors: <E>(self: Cause<E>) => ReadonlySet<number> = effect.causeInterruptors
@@ -1174,13 +1132,10 @@ export const interruptors: <E>(self: Cause<E>) => ReadonlySet<number> = effect.c
  *
  * **Example** (Extracting interruptors with Result)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Result } from "effect"
  *
- * const result = Cause.filterInterruptors(Cause.interrupt(1))
- * if (!Result.isFailure(result)) {
- *   console.log(result.success) // Set(1) { 1 }
- * }
+ * Cause.filterInterruptors(Cause.interrupt(1)) // => Result.succeed(new Set([1]))
  * ```
  *
  * @see {@link interruptors} — always-succeeding variant
@@ -1220,18 +1175,16 @@ export const filterInterruptors: <E>(self: Cause<E>) => Result.Result<Set<number
  *
  * **Example** (Converting a cause to errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const cause = Cause.fail(new Error("boom"))
- * const errors = Cause.prettyErrors(cause)
- * console.log(errors[0].message) // "boom"
+ * Cause.prettyErrors(Cause.fail(new Error("boom")))[0].message // => "boom"
  * ```
  *
  * @see {@link pretty} — renders the cause as a single string
  * @see {@link squash} — lossy collapse to a single thrown value
  *
- * @category rendering
+ * @category formatting
  * @since 3.2.0
  */
 export const prettyErrors: <E>(self: Cause<E>, options?: {
@@ -1270,16 +1223,15 @@ export const prettyErrors: <E>(self: Cause<E>, options?: {
  *
  * **Example** (Rendering a cause)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const rendered = Cause.pretty(Cause.fail("something went wrong"))
- * console.log(rendered.includes("something went wrong")) // true
+ * Cause.pretty(Cause.fail("something went wrong")).includes("something went wrong") // => true
  * ```
  *
  * @see {@link prettyErrors} — get the individual `Error` instances
  *
- * @category rendering
+ * @category formatting
  * @since 2.0.0
  */
 export const pretty: <E>(cause: Cause<E>) => string = effect.causePretty
@@ -1297,14 +1249,16 @@ export const pretty: <E>(cause: Cause<E>) => string = effect.causePretty
  *
  * **Example** (Yielding an error in Effect.gen)
  *
- * ```ts
- * import { Cause, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Effect, Exit } from "effect"
  *
  * const error = new Cause.NoSuchElementError("not found")
  *
  * const program = Effect.gen(function*() {
  *   return yield* error // fails the effect with NoSuchElementError
  * })
+ *
+ * await Effect.runPromiseExit(program) // => Exit.fail(error)
  * ```
  *
  * @category errors
@@ -1320,11 +1274,11 @@ export interface YieldableError extends Error, Pipeable, Inspectable {
  *
  * **Example** (Checking the runtime type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.isNoSuchElementError(new Cause.NoSuchElementError())) // true
- * console.log(Cause.isNoSuchElementError("nope")) // false
+ * Cause.isNoSuchElementError(new Cause.NoSuchElementError()) // => true
+ * Cause.isNoSuchElementError("nope") // => false
  * ```
  *
  * @category guards
@@ -1359,16 +1313,6 @@ export const NoSuchElementErrorTypeId: "~effect/Cause/NoSuchElementError" = core
  * expected case. This error is mainly for APIs that intentionally turn absence
  * into a thrown value or failed effect.
  *
- * **Example** (Creating and checking a NoSuchElementError)
- *
- * ```ts
- * import { Cause } from "effect"
- *
- * const error = new Cause.NoSuchElementError("Element not found")
- * console.log(error._tag)    // "NoSuchElementError"
- * console.log(error.message) // "Element not found"
- * ```
- *
  * @category errors
  * @since 4.0.0
  */
@@ -1387,11 +1331,10 @@ export interface NoSuchElementError extends YieldableError {
  *
  * **Example** (Creating a NoSuchElementError)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const error = new Cause.NoSuchElementError("Element not found")
- * console.log(error.message) // "Element not found"
+ * new Cause.NoSuchElementError("Element not found").message // => "Element not found"
  * ```
  *
  * @see {@link isNoSuchElementError} for checking unknown values
@@ -1406,11 +1349,11 @@ export const NoSuchElementError: new(message?: string) => NoSuchElementError = c
  *
  * **Example** (Checking the runtime type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.isDone(Cause.Done())) // true
- * console.log(Cause.isDone("not done"))   // false
+ * Cause.isDone(Cause.Done()) // => true
+ * Cause.isDone("not done") // => false
  * ```
  *
  * @category guards
@@ -1443,7 +1386,7 @@ export const DoneTypeId: "~effect/Cause/Done" = core.DoneTypeId
  *
  * **Example** (Signaling queue completion)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1451,9 +1394,12 @@ export const DoneTypeId: "~effect/Cause/Done" = core.DoneTypeId
  *   yield* Queue.offer(queue, 1)
  *   yield* Queue.end(queue)
  *
+ *   yield* Queue.take(queue)
  *   const result = yield* Effect.flip(Queue.take(queue))
- *   console.log(Cause.isDone(result)) // true
+ *   return Cause.isDone(result)
  * })
+ *
+ * await Effect.runPromise(program) // => true
  * ```
  *
  * @category errors
@@ -1513,14 +1459,12 @@ export const Done: <A = void>(value?: A) => Done<A> = core.Done
  *
  * **Example** (Failing with Done)
  *
- * ```ts
- * import { Cause, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Effect, Exit } from "effect"
  *
  * const program = Cause.done("finished")
  *
- * Effect.runPromiseExit(program).then((exit) => {
- *   console.log(exit._tag) // "Failure"
- * })
+ * await Effect.runPromiseExit(program) // => Exit.fail(Cause.Done("finished"))
  * ```
  *
  * @see {@link Done} — create the signal value without an Effect
@@ -1543,11 +1487,11 @@ export const TimeoutErrorTypeId: "~effect/Cause/TimeoutError" = effect.TimeoutEr
  *
  * **Example** (Checking the runtime type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.isTimeoutError(new Cause.TimeoutError())) // true
- * console.log(Cause.isTimeoutError("nope")) // false
+ * Cause.isTimeoutError(new Cause.TimeoutError()) // => true
+ * Cause.isTimeoutError("nope") // => false
  * ```
  *
  * @category guards
@@ -1563,16 +1507,6 @@ export const isTimeoutError: (u: unknown) => u is TimeoutError = effect.isTimeou
  * Produced by `Effect.timeout` and related APIs. Implements
  * `YieldableError`.
  *
- * **Example** (Creating and checking a TimeoutError)
- *
- * ```ts
- * import { Cause } from "effect"
- *
- * const error = new Cause.TimeoutError("Operation timed out")
- * console.log(error._tag)    // "TimeoutError"
- * console.log(error.message) // "Operation timed out"
- * ```
- *
  * @category errors
  * @since 4.0.0
  */
@@ -1586,11 +1520,10 @@ export interface TimeoutError extends YieldableError {
  *
  * **Example** (Creating a TimeoutError)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const error = new Cause.TimeoutError("Operation timed out")
- * console.log(error.message) // "Operation timed out"
+ * new Cause.TimeoutError("Operation timed out").message // => "Operation timed out"
  * ```
  *
  * @category constructors
@@ -1611,11 +1544,11 @@ export const IllegalArgumentErrorTypeId: "~effect/Cause/IllegalArgumentError" =
  *
  * **Example** (Checking the runtime type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.isIllegalArgumentError(new Cause.IllegalArgumentError())) // true
- * console.log(Cause.isIllegalArgumentError("nope")) // false
+ * Cause.isIllegalArgumentError(new Cause.IllegalArgumentError()) // => true
+ * Cause.isIllegalArgumentError("nope") // => false
  * ```
  *
  * @category guards
@@ -1631,16 +1564,6 @@ export const isIllegalArgumentError: (u: unknown) => u is IllegalArgumentError =
  *
  * Implements `YieldableError`.
  *
- * **Example** (Creating and checking an IllegalArgumentError)
- *
- * ```ts
- * import { Cause } from "effect"
- *
- * const error = new Cause.IllegalArgumentError("Expected positive number")
- * console.log(error._tag)    // "IllegalArgumentError"
- * console.log(error.message) // "Expected positive number"
- * ```
- *
  * @category errors
  * @since 4.0.0
  */
@@ -1654,11 +1577,10 @@ export interface IllegalArgumentError extends YieldableError {
  *
  * **Example** (Creating an IllegalArgumentError)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const error = new Cause.IllegalArgumentError("Invalid argument")
- * console.log(error.message) // "Invalid argument"
+ * new Cause.IllegalArgumentError("Invalid argument").message // => "Invalid argument"
  * ```
  *
  * @category constructors
@@ -1671,11 +1593,11 @@ export const IllegalArgumentError: new(message?: string) => IllegalArgumentError
  *
  * **Example** (Checking the runtime type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.isExceededCapacityError(new Cause.ExceededCapacityError())) // true
- * console.log(Cause.isExceededCapacityError("nope")) // false
+ * Cause.isExceededCapacityError(new Cause.ExceededCapacityError()) // => true
+ * Cause.isExceededCapacityError("nope") // => false
  * ```
  *
  * @category guards
@@ -1704,16 +1626,6 @@ export const ExceededCapacityErrorTypeId: "~effect/Cause/ExceededCapacityError"
  *
  * Implements `YieldableError`.
  *
- * **Example** (Creating and checking an ExceededCapacityError)
- *
- * ```ts
- * import { Cause } from "effect"
- *
- * const error = new Cause.ExceededCapacityError("Queue full")
- * console.log(error._tag)    // "ExceededCapacityError"
- * console.log(error.message) // "Queue full"
- * ```
- *
  * @category errors
  * @since 4.0.0
  */
@@ -1731,11 +1643,10 @@ export interface ExceededCapacityError extends YieldableError {
  *
  * **Example** (Creating an ExceededCapacityError)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const error = new Cause.ExceededCapacityError("Queue full")
- * console.log(error.message) // "Queue full"
+ * new Cause.ExceededCapacityError("Queue full").message // => "Queue full"
  * ```
  *
  * @see {@link isExceededCapacityError} for checking unknown values
@@ -1759,15 +1670,14 @@ export const AsyncFiberErrorTypeId: "~effect/Cause/AsyncFiberError" = effect.Asy
  *
  * **Example** (Checking the runtime type)
  *
- * ```ts
- * import { Cause } from "effect"
- * import type { Fiber } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Effect } from "effect"
  *
- * declare const fiber: Fiber.Fiber<unknown, unknown>
+ * const fiber = Effect.runFork(Effect.void)
  *
  * const error = new Cause.AsyncFiberError(fiber)
- * console.log(Cause.isAsyncFiberError(error)) // true
- * console.log(Cause.isAsyncFiberError("nope")) // false
+ * Cause.isAsyncFiberError(error) // => true
+ * Cause.isAsyncFiberError("nope") // => false
  * ```
  *
  * @category guards
@@ -1790,15 +1700,14 @@ export const isAsyncFiberError: (u: unknown) => u is AsyncFiberError = effect.is
  *
  * **Example** (Accessing the fiber)
  *
- * ```ts
- * import { Cause } from "effect"
- * import type { Fiber } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Effect } from "effect"
  *
- * declare const fiber: Fiber.Fiber<unknown, unknown>
+ * const fiber = Effect.runFork(Effect.void)
  *
- * const error = new Cause.AsyncFiberError(fiber)
- * console.log(error._tag) // "AsyncFiberError"
- * console.log(error.fiber === fiber) // true
+ * const value = new Cause.AsyncFiberError(fiber)
+ * const isSameFiber = value.fiber === fiber
+ * isSameFiber // => true
  * ```
  *
  * @category errors
@@ -1821,14 +1730,12 @@ export interface AsyncFiberError extends YieldableError {
  *
  * **Example** (Creating an AsyncFiberError)
  *
- * ```ts
- * import { Cause } from "effect"
- * import type { Fiber } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Effect } from "effect"
  *
- * declare const fiber: Fiber.Fiber<unknown, unknown>
+ * const fiber = Effect.runFork(Effect.void)
  *
- * const error = new Cause.AsyncFiberError(fiber)
- * console.log(error.message) // "An asynchronous Effect was executed with Effect.runSync"
+ * new Cause.AsyncFiberError(fiber).message // => "An asynchronous Effect was executed with Effect.runSync"
  * ```
  *
  * @see {@link isAsyncFiberError} for checking unknown values
@@ -1851,11 +1758,11 @@ export const UnknownErrorTypeId: "~effect/Cause/UnknownError" = effect.UnknownEr
  *
  * **Example** (Checking the runtime type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * console.log(Cause.isUnknownError(new Cause.UnknownError("x"))) // true
- * console.log(Cause.isUnknownError("nope")) // false
+ * Cause.isUnknownError(new Cause.UnknownError("x")) // => true
+ * Cause.isUnknownError("nope") // => false
  * ```
  *
  * @category guards
@@ -1872,16 +1779,6 @@ export const isUnknownError: (u: unknown) => u is UnknownError = effect.isUnknow
  * typed error. The original value is stored in the `cause` property inherited
  * from `Error`. Implements `YieldableError`.
  *
- * **Example** (Creating and checking an UnknownError)
- *
- * ```ts
- * import { Cause } from "effect"
- *
- * const error = new Cause.UnknownError("original", "Something unknown")
- * console.log(error._tag)    // "UnknownError"
- * console.log(error.message) // "Something unknown"
- * ```
- *
  * @category errors
  * @since 4.0.0
  */
@@ -1897,11 +1794,10 @@ export interface UnknownError extends YieldableError {
  *
  * **Example** (Creating an UnknownError)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause } from "effect"
  *
- * const error = new Cause.UnknownError({ raw: true }, "Unexpected value")
- * console.log(error.message) // "Unexpected value"
+ * new Cause.UnknownError({ raw: true }, "Unexpected value").message // => "Unexpected value"
  * ```
  *
  * @category constructors
@@ -1928,15 +1824,13 @@ export const UnknownError: new(cause: unknown, message?: string) => UnknownError
  *
  * **Example** (Annotating a cause)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Context } from "effect"
  *
  * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
  *
- * const cause = Cause.fail("error")
- * const annotated = Cause.annotate(cause, Context.make(RequestId, "req-1"))
- *
- * console.log(Context.getOrUndefined(Cause.annotations(annotated), RequestId)) // "req-1"
+ * const annotated = Cause.annotate(Cause.fail("error"), Context.make(RequestId, "req-1"))
+ * Context.getOrUndefined(Cause.annotations(annotated), RequestId) // => "req-1"
  * ```
  *
  * @see {@link annotations} for reading merged annotations from a cause
@@ -1965,15 +1859,13 @@ export const annotate: {
    *
    * **Example** (Annotating a cause)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cause, Context } from "effect"
    *
    * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
    *
-   * const cause = Cause.fail("error")
-   * const annotated = Cause.annotate(cause, Context.make(RequestId, "req-1"))
-   *
-   * console.log(Context.getOrUndefined(Cause.annotations(annotated), RequestId)) // "req-1"
+   * const annotated = Cause.annotate(Cause.fail("error"), Context.make(RequestId, "req-1"))
+   * Context.getOrUndefined(Cause.annotations(annotated), RequestId) // => "req-1"
    * ```
    *
    * @see {@link annotations} for reading merged annotations from a cause
@@ -2005,15 +1897,13 @@ export const annotate: {
    *
    * **Example** (Annotating a cause)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cause, Context } from "effect"
    *
    * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
    *
-   * const cause = Cause.fail("error")
-   * const annotated = Cause.annotate(cause, Context.make(RequestId, "req-1"))
-   *
-   * console.log(Context.getOrUndefined(Cause.annotations(annotated), RequestId)) // "req-1"
+   * const annotated = Cause.annotate(Cause.fail("error"), Context.make(RequestId, "req-1"))
+   * Context.getOrUndefined(Cause.annotations(annotated), RequestId) // => "req-1"
    * ```
    *
    * @see {@link annotations} for reading merged annotations from a cause
@@ -2039,7 +1929,7 @@ export const annotate: {
  *
  * **Example** (Reading reason annotations)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Context } from "effect"
  *
  * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
@@ -2047,7 +1937,7 @@ export const annotate: {
  * const reason = Cause.makeFailReason("error")
  * const annotated = reason.annotate(Context.make(RequestId, "req-1"))
  *
- * console.log(Context.getOrUndefined(Cause.reasonAnnotations(annotated), RequestId)) // "req-1"
+ * Context.getOrUndefined(Cause.reasonAnnotations(annotated), RequestId) // => "req-1"
  * ```
  *
  * @see {@link annotations} — merged annotations from all reasons in a cause
@@ -2071,7 +1961,7 @@ export const reasonAnnotations: <E>(self: Reason<E>) => Context.Context<never> =
  *
  * **Example** (Reading merged annotations)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Context } from "effect"
  *
  * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
@@ -2081,7 +1971,7 @@ export const reasonAnnotations: <E>(self: Reason<E>) => Context.Context<never> =
  *   Context.make(RequestId, "req-1")
  * )
  *
- * console.log(Context.getOrUndefined(Cause.annotations(cause), RequestId)) // "req-1"
+ * Context.getOrUndefined(Cause.annotations(cause), RequestId) // => "req-1"
  * ```
  *
  * @see {@link reasonAnnotations} — annotations from a single reason
@@ -2109,7 +1999,7 @@ export const annotations: <E>(self: Cause<E>) => Context.Context<never> = effect
  * @see {@link annotations} for reading merged annotations from a cause
  * @see {@link InterruptorStackTrace} for the interrupt-specific stack-frame annotation
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class StackTrace extends Context.Service<StackTrace, StackFrame>()("effect/Cause/StackTrace") {}
@@ -2131,7 +2021,7 @@ export class StackTrace extends Context.Service<StackTrace, StackFrame>()("effec
  * @see {@link reasonAnnotations} for reading annotations from a single reason
  * @see {@link annotate} for attaching annotations to a cause
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class InterruptorStackTrace