effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/Cause.ts

@@ -109,6 +109,8 @@ export const ReasonTypeId: "~effect/Cause/Reason" = core.CauseReasonTypeId
 /**
  * A structured representation of how an Effect failed.
  *
+ * **Details**
+ *
  * Access the individual failure entries through the `reasons` array, then
  * narrow each entry with {@link isFailReason}, {@link isDieReason}, or
  * {@link isInterruptReason}.
@@ -180,6 +182,8 @@ export const isReason: (self: unknown) => self is Reason<unknown> = core.isCause
 /**
  * A single entry inside a {@link Cause}'s `reasons` array.
  *
+ * **Details**
+ *
  * Narrow to a concrete type with {@link isFailReason}, {@link isDieReason},
  * or {@link isInterruptReason}.
  *
@@ -213,6 +217,8 @@ export type Reason<E> = Fail<E> | Die | Interrupt
 /**
  * Narrows a {@link Reason} to {@link Fail}.
  *
+ * **When to use**
+ *
  * Useful as a predicate for `Array.filter` when iterating over `cause.reasons`.
  *
  * **Example** (filtering fail reasons)
@@ -236,6 +242,8 @@ export const isFailReason: <E>(self: Reason<E>) => self is Fail<E> = core.isFail
 /**
  * Narrows a {@link Reason} to {@link Die}.
  *
+ * **When to use**
+ *
  * Useful as a predicate for `Array.filter` when iterating over `cause.reasons`.
  *
  * **Example** (filtering die reasons)
@@ -259,6 +267,8 @@ export const isDieReason: <E>(self: Reason<E>) => self is Die = core.isDieReason
 /**
  * Narrows a {@link Reason} to {@link Interrupt}.
  *
+ * **When to use**
+ *
  * Useful as a predicate for `Array.filter` when iterating over `cause.reasons`.
  *
  * **Example** (filtering interrupt reasons)
@@ -306,6 +316,8 @@ export declare namespace Cause {
    * Base interface shared by all reason types ({@link Fail}, {@link Die},
    * {@link Interrupt}).
    *
+   * **Details**
+   *
    * Every reason carries:
    * - `_tag` — discriminant string (`"Fail"`, `"Die"`, or `"Interrupt"`)
    * - `annotations` — tracing metadata attached by the runtime
@@ -351,6 +363,8 @@ export declare namespace Reason {
 /**
  * An untyped defect — typically a programming error or an uncaught exception.
  *
+ * **Details**
+ *
  * The `defect` property is `unknown` because defects are not part of the
  * typed error channel. Use {@link isDieReason} to narrow a {@link Reason}
  * to this type.
@@ -380,6 +394,8 @@ export interface Die extends Cause.ReasonProto<"Die"> {
 /**
  * A typed, expected error produced by `Effect.fail`.
  *
+ * **Details**
+ *
  * The `error` property carries the typed value `E`. Use {@link isFailReason}
  * to narrow a {@link Reason} to this type.
  *
@@ -409,6 +425,8 @@ export interface Fail<out E> extends Cause.ReasonProto<"Fail"> {
  * A fiber interruption signal, optionally carrying the ID of the fiber that
  * initiated the interruption.
  *
+ * **Details**
+ *
  * Use {@link isInterruptReason} to narrow a {@link Reason} to this type.
  *
  * **Example** (accessing the fiber ID)
@@ -436,10 +454,14 @@ export interface Interrupt extends Cause.ReasonProto<"Interrupt"> {
 /**
  * Creates a {@link Cause} from an array of {@link Reason} values.
  *
+ * **When to use**
+ *
  * Use this when you already have individual reasons (e.g. from filtering or
  * transforming another cause's `reasons` array) and need to wrap them back
  * into a `Cause`.
  *
+ * **Details**
+ *
  * - Returns a new `Cause`; does not mutate the input array.
  * - An empty array produces a cause equivalent to {@link empty}.
  *
@@ -468,6 +490,8 @@ export const fromReasons: <E>(
 /**
  * A {@link Cause} with an empty `reasons` array.
  *
+ * **Details**
+ *
  * Represents the absence of failure. Combining any cause with `empty` via
  * {@link combine} returns the original cause unchanged.
  *
@@ -547,6 +571,8 @@ export const interrupt: (fiberId?: number | undefined) => Cause<never> = effect.
 /**
  * Creates a standalone {@link Fail} reason (not wrapped in a {@link Cause}).
  *
+ * **When to use**
+ *
  * Use this when you need to construct individual reasons for
  * {@link fromReasons} or for direct comparison.
  *
@@ -614,6 +640,8 @@ export const makeInterruptReason: (fiberId?: number | undefined) => Interrupt =
  * Returns `true` if every reason in the cause is an {@link Interrupt} (and
  * there is at least one reason).
  *
+ * **When to use**
+ *
  * Useful for deciding whether a failure was entirely due to interruption and
  * can be silently discarded.
  *
@@ -639,6 +667,8 @@ export const hasInterruptsOnly: <E>(self: Cause<E>) => boolean = effect.hasInter
  * provided function. Only {@link Fail} reasons are affected; {@link Die}
  * and {@link Interrupt} reasons pass through unchanged.
  *
+ * **Details**
+ *
  * Returns a new `Cause`; does not mutate the original.
  *
  * **Example** (mapping errors to uppercase)
@@ -663,6 +693,8 @@ export const map: {
    * provided function. Only {@link Fail} reasons are affected; {@link Die}
    * and {@link Interrupt} reasons pass through unchanged.
    *
+   * **Details**
+   *
    * Returns a new `Cause`; does not mutate the original.
    *
    * **Example** (mapping errors to uppercase)
@@ -687,6 +719,8 @@ export const map: {
    * provided function. Only {@link Fail} reasons are affected; {@link Die}
    * and {@link Interrupt} reasons pass through unchanged.
    *
+   * **Details**
+   *
    * Returns a new `Cause`; does not mutate the original.
    *
    * **Example** (mapping errors to uppercase)
@@ -712,6 +746,8 @@ export const map: {
  * Merges two causes into a single cause whose `reasons` array is the union
  * of both inputs (de-duplicated by value equality).
  *
+ * **Details**
+ *
  * - Combining with {@link empty} returns the other cause unchanged.
  * - If the result is structurally equal to `self`, `self` is returned
  *   (referential shortcut).
@@ -737,6 +773,8 @@ export const combine: {
    * Merges two causes into a single cause whose `reasons` array is the union
    * of both inputs (de-duplicated by value equality).
    *
+   * **Details**
+   *
    * - Combining with {@link empty} returns the other cause unchanged.
    * - If the result is structurally equal to `self`, `self` is returned
    *   (referential shortcut).
@@ -762,6 +800,8 @@ export const combine: {
    * Merges two causes into a single cause whose `reasons` array is the union
    * of both inputs (de-duplicated by value equality).
    *
+   * **Details**
+   *
    * - Combining with {@link empty} returns the other cause unchanged.
    * - If the result is structurally equal to `self`, `self` is returned
    *   (referential shortcut).
@@ -789,14 +829,20 @@ export const combine: {
  * Collapses a {@link Cause} into a single `unknown` value, picking the "most
  * important" failure in this order:
  *
+ * **Details**
+ *
  * 1. First {@link Fail} error (the `E` value)
  * 2. First {@link Die} defect
  * 3. A generic `Error("All fibers interrupted without error")` for interrupt-only causes
  * 4. A generic `Error("Empty cause")` for {@link empty}
  *
  * This is the function used by `Effect.runPromise` and `Effect.runSync` to
- * decide what to throw. It is lossy — use {@link prettyErrors} or iterate
- * `cause.reasons` when you need all failures.
+ * decide what to throw.
+ *
+ * **Gotchas**
+ *
+ * This function is lossy. Use {@link prettyErrors} or iterate `cause.reasons`
+ * when you need all failures.
  *
  * **Example** (squashing a cause)
  *
@@ -841,6 +887,8 @@ export const hasFails: <E>(self: Cause<E>) => boolean = effect.hasFails
  * failure value is the original cause narrowed to `Cause<never>`, because it
  * contains no typed error reasons.
  *
+ * **When to use**
+ *
  * Use {@link findError} if you only need the unwrapped error value `E`.
  *
  * **Example** (extracting the first Fail reason)
@@ -868,6 +916,8 @@ export const findFail: <E>(self: Cause<E>) => Result.Result<Fail<E>, Cause<never
  * the failure value is the original cause narrowed to `Cause<never>`, because
  * it contains no typed error reasons.
  *
+ * **When to use**
+ *
  * Use {@link findFail} if you need the full {@link Fail} reason (including
  * annotations). Use {@link findErrorOption} if you prefer an `Option`.
  *
@@ -894,6 +944,8 @@ export const findError: <E>(self: Cause<E>) => Result.Result<E, Cause<never>> =
  * Returns the first typed error value `E` from a cause wrapped in
  * `Option.some`, or `Option.none` if no {@link Fail} reason exists.
  *
+ * **When to use**
+ *
  * This is the `Option`-returning variant of {@link findError} for code that
  * does not need the original cause returned in a failed `Result`.
  *
@@ -941,6 +993,8 @@ export const hasDies: <E>(self: Cause<E>) => boolean = effect.hasDies
  * the cause, including its annotations. If the cause has no `Die` reason, the
  * failure value is the original cause.
  *
+ * **When to use**
+ *
  * Use {@link findDefect} if you only need the unwrapped defect value.
  *
  * **Example** (extracting the first Die reason)
@@ -967,6 +1021,8 @@ export const findDie: <E>(self: Cause<E>) => Result.Result<Die, Cause<E>> = effe
  * {@link Die} reason in the cause. If the cause has no `Die` reason, the
  * failure value is the original cause.
  *
+ * **When to use**
+ *
  * Use {@link findDie} if you need the full `Die` reason (including
  * annotations).
  *
@@ -1038,6 +1094,8 @@ export const findInterrupt: <E>(self: Cause<E>) => Result.Result<Interrupt, Caus
  * cause into a `ReadonlySet`. Interrupt reasons without a `fiberId` are
  * ignored. Returns an empty set when the cause has no interrupting fiber IDs.
  *
+ * **When to use**
+ *
  * This always succeeds. Use {@link filterInterruptors} when you want a
  * `Result` that fails with the original cause if there are no `Interrupt`
  * reasons.
@@ -1066,6 +1124,8 @@ export const interruptors: <E>(self: Cause<E>) => ReadonlySet<number> = effect.c
  * the cause's {@link Interrupt} reasons. If the cause has no `Interrupt`
  * reason, the failure value is the original cause.
  *
+ * **When to use**
+ *
  * Use {@link interruptors} if you always want a `Set` without `Result`
  * wrapping.
  *
@@ -1092,6 +1152,8 @@ export const filterInterruptors: <E>(self: Cause<E>) => Result.Result<Set<number
  * Converts a {@link Cause} into an `Array<Error>` suitable for logging or
  * rethrowing.
  *
+ * **Details**
+ *
  * Each {@link Fail} and {@link Die} reason is converted into a standard
  * `Error`:
  *
@@ -1128,6 +1190,8 @@ export const prettyErrors: <E>(self: Cause<E>) => Array<Error> = effect.causePre
  * Renders a {@link Cause} as a human-readable string for logging or
  * debugging.
  *
+ * **Details**
+ *
  * Delegates to {@link prettyErrors} to convert each reason to an `Error`,
  * then joins their stack traces with newlines. Nested `Error.cause` chains
  * are rendered inline with indentation:
@@ -1166,6 +1230,8 @@ export const pretty: <E>(cause: Cause<E>) => string = effect.causePretty
  * `Effect.gen`. Yielding one of these errors fails the generator with that
  * error as the typed failure value.
  *
+ * **Details**
+ *
  * All built-in error classes in this module ({@link NoSuchElementError},
  * {@link TimeoutError}, {@link IllegalArgumentError},
  * {@link ExceededCapacityError}, {@link AsyncFiberError}, and
@@ -1219,11 +1285,13 @@ export const NoSuchElementErrorTypeId: "~effect/Cause/NoSuchElementError" = core
 /**
  * An error indicating that an expected value was absent.
  *
+ * **Details**
+ *
  * Used by APIs that convert absence into an exception or effect failure, such
  * as `Option.getOrThrow`. Implements {@link YieldableError} so it can be
  * yielded directly in `Effect.gen`.
  *
- * **Notes**
+ * **Gotchas**
  *
  * Safe lookup APIs that return `Option` should document the `None` case rather
  * than describing it as a thrown `NoSuchElementError`.
@@ -1294,6 +1362,8 @@ export const DoneTypeId: "~effect/Cause/Done" = core.DoneTypeId
 /**
  * A graceful completion signal for queues and streams.
  *
+ * **Details**
+ *
  * `Done` indicates that a producer has finished normally — no more elements
  * will arrive. It is distinct from an error or interruption; it represents
  * successful completion. The optional `value` field can carry a final
@@ -1399,6 +1469,8 @@ export const isTimeoutError: (u: unknown) => u is TimeoutError = effect.isTimeou
 /**
  * An error indicating that an operation exceeded its time limit.
  *
+ * **Details**
+ *
  * Produced by `Effect.timeout` and related APIs. Implements
  * {@link YieldableError}.
  *
@@ -1468,6 +1540,8 @@ export const isIllegalArgumentError: (u: unknown) => u is IllegalArgumentError =
  * An error indicating that a function received an argument that violates
  * its contract (e.g. negative where positive was expected).
  *
+ * **Details**
+ *
  * Implements {@link YieldableError}.
  *
  * **Example** (creating and checking)
@@ -1536,6 +1610,8 @@ export const ExceededCapacityErrorTypeId: "~effect/Cause/ExceededCapacityError"
  * An error indicating that a bounded resource (queue, pool, semaphore, etc.)
  * has exceeded its capacity.
  *
+ * **Details**
+ *
  * Implements {@link YieldableError}.
  *
  * **Example** (creating and checking)
@@ -1639,6 +1715,8 @@ export const isUnknownError: (u: unknown) => u is UnknownError = effect.isUnknow
 /**
  * A wrapper for errors whose type is not statically known.
  *
+ * **Details**
+ *
  * Produced by the runtime when an effect throws a non-`Error` value.
  * The original thrown value is stored in the `cause` property (inherited
  * from `Error`). Implements {@link YieldableError}.
@@ -1685,6 +1763,8 @@ export const UnknownError: new(cause: unknown, message?: string) => UnknownError
 /**
  * Attaches metadata to every reason in a {@link Cause}.
  *
+ * **Details**
+ *
  * Annotations are stored as a `Context` on each reason and can be
  * retrieved later via {@link reasonAnnotations} or {@link annotations}.
  * The runtime uses this to attach stack traces and spans.
@@ -1712,6 +1792,8 @@ export const annotate: {
   /**
    * Attaches metadata to every reason in a {@link Cause}.
    *
+   * **Details**
+   *
    * Annotations are stored as a `Context` on each reason and can be
    * retrieved later via {@link reasonAnnotations} or {@link annotations}.
    * The runtime uses this to attach stack traces and spans.
@@ -1742,6 +1824,8 @@ export const annotate: {
   /**
    * Attaches metadata to every reason in a {@link Cause}.
    *
+   * **Details**
+   *
    * Annotations are stored as a `Context` on each reason and can be
    * retrieved later via {@link reasonAnnotations} or {@link annotations}.
    * The runtime uses this to attach stack traces and spans.
@@ -1775,6 +1859,8 @@ export const annotate: {
 /**
  * Reads the annotations from a single {@link Reason} as a `Context`.
  *
+ * **When to use**
+ *
  * Use this when you need tracing metadata (e.g. {@link StackTrace}) from
  * a specific reason rather than the whole cause.
  *
@@ -1789,6 +1875,8 @@ export const reasonAnnotations: <E>(self: Reason<E>) => Context.Context<never> =
 /**
  * Reads the merged annotations from all reasons in a {@link Cause}.
  *
+ * **Details**
+ *
  * Annotations from later reasons overwrite earlier ones when keys collide.
  *
  * @see {@link reasonAnnotations} — annotations from a single reason
@@ -1802,6 +1890,8 @@ export const annotations: <E>(self: Cause<E>) => Context.Context<never> = effect
 /**
  * `Context` key for the stack frame captured at the point of failure.
  *
+ * **Details**
+ *
  * The runtime annotates every reason with this when a stack frame is
  * available. Retrieve it via
  * `Context.get(Cause.reasonAnnotations(reason), Cause.StackTrace)`.
@@ -1815,6 +1905,8 @@ export class StackTrace extends Context.Service<StackTrace, StackFrame>()("effec
  * `Context` key for the stack frame captured at the point of
  * interruption.
  *
+ * **Details**
+ *
  * Similar to {@link StackTrace} but specific to {@link Interrupt} reasons.
  *
  * @category annotations