1/**
2 * Records the full reason an `Effect` failed.
3 *
4 * A `Cause<E>` can contain typed failures, unexpected defects, interruptions,
5 * and annotations. Keeping those details together lets code inspect or format
6 * failures without first collapsing them to a single error value. This module
7 * includes the `Cause` and `Reason` data types, helpers for building and
8 * checking causes, and small error types used by several Effect APIs.
9 *
10 * @since 2.0.0
11 */
12import * as Context from "./Context.ts"
13import type * as Effect from "./Effect.ts"
14import type { Equal } from "./Equal.ts"
15import type { Fiber } from "./Fiber.ts"
16import type { Inspectable } from "./Inspectable.ts"
17import * as core from "./internal/core.ts"
18import * as effect from "./internal/effect.ts"
19import type { Option } from "./Option.ts"
20import type { Pipeable } from "./Pipeable.ts"
21import type { StackFrame } from "./References.ts"
22import type * as Result from "./Result.ts"
23import type * as Types from "./Types.ts"
24
25/**
26 * Unique brand for `Cause` values, used for runtime type checks via {@link isCause}.
27 *
28 * @category type IDs
29 * @since 4.0.0
30 */
31export const TypeId: "~effect/Cause" = core.CauseTypeId
32
33/**
34 * Unique brand for `Reason` values, used for runtime type checks via {@link isReason}.
35 *
36 * @category type IDs
37 * @since 4.0.0
38 */
39export const ReasonTypeId: "~effect/Cause/Reason" = core.CauseReasonTypeId
40
41/**
42 * A structured representation of how an Effect failed.
43 *
44 * **When to use**
45 *
46 * Use to preserve the full structured failure information for an effect instead
47 * of collapsing it to a single error value.
48 *
49 * **Details**
50 *
51 * Access the individual failure entries through the `reasons` array, then
52 * narrow each entry with {@link isFailReason}, {@link isDieReason}, or
53 * {@link isInterruptReason}.
54 *
55 * - Use {@link hasFails} / {@link hasDies} / {@link hasInterrupts} to test
56 * for the presence of specific reason kinds without iterating.
57 * - Use {@link findError} / {@link findDefect} to extract the first value
58 * of a given kind.
59 * - Use {@link combine} to merge two causes.
60 *
61 * `Cause` implements `Equal` — two causes with the same reasons (by value)
62 * compare as equal.
63 *
64 * **Example** (Creating and inspecting a cause)
65 *
66 * ```ts import.meta.vitest
67 * import { Cause } from "effect"
68 *
69 * Cause.fail("Something went wrong") // => Cause.fail("Something went wrong")
70 * ```
71 *
72 * @category models
73 * @since 2.0.0
74 */
75export interface Cause<out E> extends Pipeable, Inspectable, Equal {
76 readonly [TypeId]: typeof TypeId
77 readonly reasons: ReadonlyArray<Reason<E>>
78}
79
80/**
81 * Checks whether an arbitrary value is a `Cause`.
82 *
83 * **Example** (Checking the runtime type)
84 *
85 * ```ts import.meta.vitest
86 * import { Cause } from "effect"
87 *
88 * Cause.isCause(Cause.fail("error")) // => true
89 * Cause.isCause("not a cause") // => false
90 * ```
91 *
92 * @category guards
93 * @since 2.0.0
94 */
95export const isCause: (self: unknown) => self is Cause<unknown> = core.isCause
96
97/**
98 * Checks whether an arbitrary value is a `Reason` (`Fail`, `Die`, or `Interrupt`).
99 *
100 * **Example** (Checking the runtime type)
101 *
102 * ```ts import.meta.vitest
103 * import { Cause } from "effect"
104 *
105 * const reason = Cause.fail("error").reasons[0]
106 * Cause.isReason(reason) // => true
107 * Cause.isReason("not a reason") // => false
108 * ```
109 *
110 * @category guards
111 * @since 4.0.0
112 */
113export const isReason: (self: unknown) => self is Reason<unknown> = core.isCauseReason
114
115/**
116 * A single entry inside a `Cause`'s `reasons` array.
117 *
118 * **Details**
119 *
120 * Narrow to a concrete type with {@link isFailReason}, {@link isDieReason},
121 * or {@link isInterruptReason}.
122 *
123 * - `Fail<E>` — typed error, access via `.error`
124 * - `Die` — untyped defect, access via `.defect`
125 * - `Interrupt` — fiber interruption, access via `.fiberId`
126 *
127 * Every reason carries an `annotations` map and an `annotate` method for
128 * attaching tracing metadata.
129 *
130 * **Example** (Narrowing a reason)
131 *
132 * ```ts import.meta.vitest
133 * import { Cause } from "effect"
134 *
135 * const reason = Cause.fail("error").reasons[0]
136 * if (Cause.isFailReason(reason)) {
137 * reason.error // => "error"
138 * }
139 * ```
140 *
141 * @category models
142 * @since 4.0.0
143 */
144export type Reason<E> = Fail<E> | Die | Interrupt
145
146/**
147 * Narrows a `Reason` to `Fail`.
148 *
149 * **When to use**
150 *
151 * Use as a predicate for `Array.filter` to pick out typed `Fail` reasons when
152 * iterating over `cause.reasons`.
153 *
154 * **Example** (Filtering fail reasons)
155 *
156 * ```ts import.meta.vitest
157 * import { Cause } from "effect"
158 *
159 * const cause = Cause.fail("error")
160 * const fails = cause.reasons.filter(Cause.isFailReason)
161 * fails[0].error // => "error"
162 * ```
163 *
164 * @see {@link isDieReason} — narrow to `Die`
165 * @see {@link isInterruptReason} — narrow to `Interrupt`
166 *
167 * @category guards
168 * @since 4.0.0
169 */
170export const isFailReason: <E>(self: Reason<E>) => self is Fail<E> = core.isFailReason
171
172/**
173 * Narrows a `Reason` to `Die`.
174 *
175 * **When to use**
176 *
177 * Use as a predicate for `Array.filter` to pick out `Die` (defect) reasons when
178 * iterating over `cause.reasons`.
179 *
180 * **Example** (Filtering die reasons)
181 *
182 * ```ts import.meta.vitest
183 * import { Cause } from "effect"
184 *
185 * const cause = Cause.die("defect")
186 * const dies = cause.reasons.filter(Cause.isDieReason)
187 * dies[0].defect // => "defect"
188 * ```
189 *
190 * @see {@link isFailReason} — narrow to `Fail`
191 * @see {@link isInterruptReason} — narrow to `Interrupt`
192 *
193 * @category guards
194 * @since 4.0.0
195 */
196export const isDieReason: <E>(self: Reason<E>) => self is Die = core.isDieReason
197
198/**
199 * Narrows a `Reason` to `Interrupt`.
200 *
201 * **When to use**
202 *
203 * Use as a predicate for `Array.filter` to pick out `Interrupt` reasons when
204 * iterating over `cause.reasons`.
205 *
206 * **Example** (Filtering interrupt reasons)
207 *
208 * ```ts import.meta.vitest
209 * import { Cause } from "effect"
210 *
211 * const cause = Cause.interrupt(123)
212 * const interrupts = cause.reasons.filter(Cause.isInterruptReason)
213 * interrupts[0].fiberId // => 123
214 * ```
215 *
216 * @see {@link isFailReason} — narrow to `Fail`
217 * @see {@link isDieReason} — narrow to `Die`
218 *
219 * @category guards
220 * @since 4.0.0
221 */
222export const isInterruptReason: <E>(self: Reason<E>) => self is Interrupt = core.isInterruptReason
223
224/**
225 * Companion namespace for the `Cause` interface.
226 *
227 * @since 2.0.0
228 */
229export declare namespace Cause {
230 /**
231 * Extracts the error type `E` from a `Cause<E>`.
232 *
233 * **Example** (Extracting the error type)
234 *
235 * ```ts import.meta.vitest
236 * import type { Cause } from "effect"
237 *
238 * // string
239 * type E = Cause.Cause.Error<Cause.Cause<string>>
240 * ```
241 *
242 * @category utility types
243 * @since 4.0.0
244 */
245 export type Error<T> = T extends Cause<infer E> ? E : never
246
247 /**
248 * Base interface shared by all reason types (`Fail`, `Die`, `Interrupt`).
249 *
250 * **Details**
251 *
252 * Every reason carries:
253 * - `_tag` — discriminant string (`"Fail"`, `"Die"`, or `"Interrupt"`)
254 * - `annotations` — tracing metadata attached by the runtime
255 * - `annotate()` — returns a copy with additional annotations
256 *
257 * @category models
258 * @since 4.0.0
259 */
260 export interface ReasonProto<Tag extends string> extends Inspectable, Equal {
261 readonly [ReasonTypeId]: typeof ReasonTypeId
262 readonly _tag: Tag
263 readonly annotations: ReadonlyMap<string, unknown>
264 annotate(annotations: Context.Context<never>, options?: {
265 readonly overwrite?: boolean | undefined
266 }): this
267 }
268}
269
270/**
271 * Companion namespace for the `Reason` type.
272 *
273 * @since 4.0.0
274 */
275export declare namespace Reason {
276 /**
277 * Extracts the error type `E` from a `Reason<E>`.
278 *
279 * **Example** (Extracting the error type)
280 *
281 * ```ts import.meta.vitest
282 * import type { Cause } from "effect"
283 *
284 * // string
285 * type E = Cause.Reason.Error<Cause.Reason<string>>
286 * ```
287 *
288 * @category utility types
289 * @since 4.0.0
290 */
291 export type Error<T> = T extends Reason<infer E> ? E : never
292}
293
294/**
295 * An untyped defect — typically a programming error or an uncaught exception.
296 *
297 * **When to use**
298 *
299 * Use when inspecting `Cause` reasons that represent defects instead of typed
300 * failures or interruptions.
301 *
302 * **Details**
303 *
304 * The `defect` property is `unknown` because defects are not part of the
305 * typed error channel. Use {@link isDieReason} to narrow a `Reason`
306 * to this type.
307 *
308 * **Example** (Accessing the defect)
309 *
310 * ```ts import.meta.vitest
311 * import { Cause } from "effect"
312 *
313 * const cause = Cause.die("Unexpected")
314 * const reason = cause.reasons[0]
315 * if (Cause.isDieReason(reason)) {
316 * reason.defect // => "Unexpected"
317 * }
318 * ```
319 *
320 * @see {@link die} for constructing a cause with a single `Die` reason
321 * @see {@link isDieReason} for narrowing a `Reason` to `Die`
322 *
323 * @category models
324 * @since 2.0.0
325 */
326export interface Die extends Cause.ReasonProto<"Die"> {
327 readonly defect: unknown
328}
329
330/**
331 * A typed, expected error produced by `Effect.fail`.
332 *
333 * **When to use**
334 *
335 * Use when inspecting `Cause` reasons that represent expected failures from the
336 * typed error channel.
337 *
338 * **Details**
339 *
340 * The `error` property carries the typed value `E`. Use {@link isFailReason}
341 * to narrow a `Reason` to this type.
342 *
343 * **Example** (Accessing the error)
344 *
345 * ```ts import.meta.vitest
346 * import { Cause } from "effect"
347 *
348 * const cause = Cause.fail("Something went wrong")
349 * const reason = cause.reasons[0]
350 * if (Cause.isFailReason(reason)) {
351 * reason.error // => "Something went wrong"
352 * }
353 * ```
354 *
355 * @see {@link fail} for constructing a cause with a single `Fail` reason
356 * @see {@link isFailReason} for narrowing a `Reason` to `Fail`
357 *
358 * @category models
359 * @since 2.0.0
360 */
361export interface Fail<out E> extends Cause.ReasonProto<"Fail"> {
362 readonly error: E
363}
364
365/**
366 * A fiber interruption signal, optionally carrying the ID of the fiber that
367 * initiated the interruption.
368 *
369 * **Details**
370 *
371 * Use {@link isInterruptReason} to narrow a `Reason` to this type.
372 *
373 * **Example** (Accessing the fiber ID)
374 *
375 * ```ts import.meta.vitest
376 * import { Cause } from "effect"
377 *
378 * const cause = Cause.interrupt(123)
379 * const reason = cause.reasons[0]
380 * if (Cause.isInterruptReason(reason)) {
381 * reason.fiberId // => 123
382 * }
383 * ```
384 *
385 * @category models
386 * @since 2.0.0
387 */
388export interface Interrupt extends Cause.ReasonProto<"Interrupt"> {
389 readonly fiberId: number | undefined
390}
391
392/**
393 * Creates a `Cause` from an array of `Reason` values.
394 *
395 * **When to use**
396 *
397 * Use when you already have individual reasons (e.g. from filtering or
398 * transforming another cause's `reasons` array) and need to wrap them back
399 * into a `Cause`.
400 *
401 * **Details**
402 *
403 * - Returns a new `Cause`.
404 * - An empty array produces a cause equivalent to `empty`.
405 *
406 * **Gotchas**
407 *
408 * The `reasons` array is stored as provided. Treat the array as immutable
409 * after passing it to this function.
410 *
411 * **Example** (Building a cause from reasons)
412 *
413 * ```ts import.meta.vitest
414 * import { Cause } from "effect"
415 *
416 * const reasons = [
417 * Cause.makeFailReason("err1"),
418 * Cause.makeFailReason("err2")
419 * ]
420 * Cause.fromReasons(reasons) // => Cause.combine(Cause.fail("err1"), Cause.fail("err2"))
421 * ```
422 *
423 * @see {@link combine} — merge two existing causes
424 *
425 * @category constructors
426 * @since 4.0.0
427 */
428export const fromReasons: <E>(
429 reasons: ReadonlyArray<Reason<E>>
430) => Cause<E> = core.causeFromReasons
431
432/**
433 * Represents a `Cause` with an empty `reasons` array.
434 *
435 * **When to use**
436 *
437 * Use to represent the absence of failure when constructing or combining
438 * causes.
439 *
440 * **Details**
441 *
442 * Represents the absence of failure. Combining any cause with `empty` via
443 * {@link combine} returns the original cause unchanged.
444 *
445 * **Example** (Combining with the empty cause)
446 *
447 * ```ts import.meta.vitest
448 * import { Cause } from "effect"
449 *
450 * Cause.combine(Cause.empty, Cause.fail("boom")) // => Cause.fail("boom")
451 * ```
452 *
453 * @see {@link combine} for merging causes where `empty` acts as the identity
454 *
455 * @category constructors
456 * @since 2.0.0
457 */
458export const empty: Cause<never> = core.causeEmpty
459
460/**
461 * Creates a `Cause` containing a single `Fail` reason with the
462 * given typed error.
463 *
464 * **When to use**
465 *
466 * Use to construct a cause from an expected typed error.
467 *
468 * **Example** (Creating a fail cause)
469 *
470 * ```ts import.meta.vitest
471 * import { Cause } from "effect"
472 *
473 * Cause.fail("Something went wrong") // => Cause.fromReasons([Cause.makeFailReason("Something went wrong")])
474 * ```
475 *
476 * @see {@link die} — for untyped defects
477 * @see {@link interrupt} — for fiber interruptions
478 *
479 * @category constructors
480 * @since 2.0.0
481 */
482export const fail: <E>(error: E) => Cause<E> = core.causeFail
483
484/**
485 * Creates a `Cause` containing a single `Die` reason with the
486 * given defect.
487 *
488 * **When to use**
489 *
490 * Use to construct a cause from an untyped defect or unexpected thrown value.
491 *
492 * **Example** (Creating a die cause)
493 *
494 * ```ts import.meta.vitest
495 * import { Cause } from "effect"
496 *
497 * Cause.die("Unexpected") // => Cause.fromReasons([Cause.makeDieReason("Unexpected")])
498 * ```
499 *
500 * @see {@link fail} — for typed errors
501 * @see {@link interrupt} — for fiber interruptions
502 *
503 * @category constructors
504 * @since 2.0.0
505 */
506export const die: (defect: unknown) => Cause<never> = core.causeDie
507
508/**
509 * Creates a `Cause` containing a single `Interrupt` reason,
510 * optionally carrying the interrupting fiber's ID.
511 *
512 * **Example** (Creating an interrupt cause)
513 *
514 * ```ts import.meta.vitest
515 * import { Cause } from "effect"
516 *
517 * Cause.interrupt(123) // => Cause.fromReasons([Cause.makeInterruptReason(123)])
518 * ```
519 *
520 * @see {@link fail} — for typed errors
521 * @see {@link die} — for untyped defects
522 *
523 * @category constructors
524 * @since 2.0.0
525 */
526export const interrupt: (fiberId?: number | undefined) => Cause<never> = effect.causeInterrupt
527
528/**
529 * Creates a standalone `Fail` reason (not wrapped in a `Cause`).
530 *
531 * **When to use**
532 *
533 * Use when constructing a standalone typed failure reason for
534 * {@link fromReasons} or direct comparison.
535 *
536 * **Example** (Creating a Fail reason)
537 *
538 * ```ts import.meta.vitest
539 * import { Cause } from "effect"
540 *
541 * Cause.makeFailReason("error") // => Cause.fail("error").reasons[0]
542 * ```
543 *
544 * @see {@link makeDieReason} — create a `Die` reason
545 * @see {@link makeInterruptReason} — create an `Interrupt` reason
546 *
547 * @category constructors
548 * @since 4.0.0
549 */
550export const makeFailReason = <E>(error: E): Fail<E> => new core.Fail(error)
551
552/**
553 * Creates a standalone `Die` reason (not wrapped in a `Cause`).
554 *
555 * **When to use**
556 *
557 * Use when constructing a standalone defect reason for {@link fromReasons} or
558 * direct comparison.
559 *
560 * **Example** (Creating a Die reason)
561 *
562 * ```ts import.meta.vitest
563 * import { Cause } from "effect"
564 *
565 * Cause.makeDieReason("bug") // => Cause.die("bug").reasons[0]
566 * ```
567 *
568 * @see {@link makeFailReason} — create a `Fail` reason
569 * @see {@link makeInterruptReason} — create an `Interrupt` reason
570 *
571 * @category constructors
572 * @since 4.0.0
573 */
574export const makeDieReason = (defect: unknown): Die => new core.Die(defect)
575
576/**
577 * Creates a standalone `Interrupt` reason (not wrapped in a `Cause`),
578 * optionally carrying the interrupting fiber's ID.
579 *
580 * **When to use**
581 *
582 * Use when constructing a standalone interrupt reason for {@link fromReasons}
583 * or direct comparison.
584 *
585 * **Example** (Creating an Interrupt reason)
586 *
587 * ```ts import.meta.vitest
588 * import { Cause } from "effect"
589 *
590 * Cause.makeInterruptReason(42) // => Cause.interrupt(42).reasons[0]
591 * ```
592 *
593 * @see {@link makeFailReason} — create a `Fail` reason
594 * @see {@link makeDieReason} — create a `Die` reason
595 *
596 * @category constructors
597 * @since 4.0.0
598 */
599export const makeInterruptReason: (fiberId?: number | undefined) => Interrupt = effect.makeInterruptReason
600
601/**
602 * Returns `true` if every reason in the cause is an `Interrupt` (and
603 * there is at least one reason).
604 *
605 * **When to use**
606 *
607 * Use when you need to detect failures caused only by interruption.
608 *
609 * **Example** (Checking interrupt-only causes)
610 *
611 * ```ts import.meta.vitest
612 * import { Cause } from "effect"
613 *
614 * Cause.hasInterruptsOnly(Cause.interrupt(123)) // => true
615 * Cause.hasInterruptsOnly(Cause.fail("error")) // => false
616 * Cause.hasInterruptsOnly(Cause.empty) // => false
617 * ```
618 *
619 * @see {@link hasInterrupts} — `true` if the cause contains *any* interrupts
620 *
621 * @category predicates
622 * @since 4.0.0
623 */
624export const hasInterruptsOnly: <E>(self: Cause<E>) => boolean = effect.hasInterruptsOnly
625
626/**
627 * Transforms the typed error values inside a `Cause` using the
628 * provided function. Only `Fail` reasons are affected; `Die` and `Interrupt`
629 * reasons pass through unchanged.
630 *
631 * **When to use**
632 *
633 * Use to transform expected typed failures while preserving defects and
634 * interruptions unchanged.
635 *
636 * **Details**
637 *
638 * If at least one `Fail` reason exists, this returns a new `Cause`
639 * containing the mapped failures. If the cause has no `Fail` reasons, the
640 * original cause is returned unchanged.
641 *
642 * **Example** (Mapping errors to uppercase)
643 *
644 * ```ts import.meta.vitest
645 * import { Cause } from "effect"
646 *
647 * const cause = Cause.fail("error")
648 * const mapped = Cause.map(cause, (e) => e.toUpperCase())
649 * const reason = mapped.reasons[0]
650 * if (Cause.isFailReason(reason)) {
651 * reason.error // => "ERROR"
652 * }
653 * ```
654 *
655 * @category mapping
656 * @since 2.0.0
657 */
658export const map: {
659 <E, E2>(f: (error: Types.NoInfer<E>) => E2): (self: Cause<E>) => Cause<E2>
660 <E, E2>(self: Cause<E>, f: (error: Types.NoInfer<E>) => E2): Cause<E2>
661} = effect.causeMap
662
663/**
664 * Merges two causes into a single cause whose `reasons` array is the union
665 * of both inputs (de-duplicated by value equality).
666 *
667 * **When to use**
668 *
669 * Use to merge independent causes into one structured failure value.
670 *
671 * **Details**
672 *
673 * - Combining with `empty` returns the other cause unchanged.
674 * - If the result is structurally equal to `self`, `self` is returned
675 * (referential shortcut).
676 *
677 * **Example** (Combining two causes)
678 *
679 * ```ts import.meta.vitest
680 * import { Cause } from "effect"
681 *
682 * const combined = Cause.combine(Cause.fail("error1"), Cause.fail("error2"))
683 * combined // => Cause.fromReasons([Cause.makeFailReason("error1"), Cause.makeFailReason("error2")])
684 * ```
685 *
686 * @see {@link fromReasons} — build a cause from an array of reasons
687 * @see {@link empty} for the identity cause used when combining
688 *
689 * @category combining
690 * @since 4.0.0
691 */
692export const combine: {
693 <E2>(that: Cause<E2>): <E>(self: Cause<E>) => Cause<E | E2>
694 <E, E2>(self: Cause<E>, that: Cause<E2>): Cause<E | E2>
695} = core.causeCombine
696
697/**
698 * Collapses a `Cause` into a single `unknown` value, picking the "most
699 * important" failure in this order:
700 *
701 * **When to use**
702 *
703 * Use to collapse a structured cause to the single value that synchronous and
704 * promise runners would throw.
705 *
706 * **Details**
707 *
708 * 1. First `Fail` error (the `E` value)
709 * 2. First `Die` defect
710 * 3. A generic `Error("All fibers interrupted without error")` for interrupt-only causes
711 * 4. A generic `Error("Empty cause")` for `empty`
712 *
713 * This is the function used by `Effect.runPromise` and `Effect.runSync` to
714 * decide what to throw.
715 *
716 * **Gotchas**
717 *
718 * This function is lossy. Use {@link prettyErrors} or iterate `cause.reasons`
719 * when you need all failures.
720 *
721 * **Example** (Squashing a cause)
722 *
723 * ```ts import.meta.vitest
724 * import { Cause } from "effect"
725 *
726 * Cause.squash(Cause.fail("error")) // => "error"
727 * Cause.squash(Cause.die("defect")) // => "defect"
728 * ```
729 *
730 * @see {@link prettyErrors} — non-lossy conversion to `Array<Error>`
731 * @see {@link pretty} — human-readable string rendering
732 *
733 * @category destructors
734 * @since 2.0.0
735 */
736export const squash: <E>(self: Cause<E>) => unknown = effect.causeSquash
737
738/**
739 * Returns `true` if the cause contains at least one `Fail` reason.
740 *
741 * **When to use**
742 *
743 * Use to check whether a cause includes typed failures before extracting,
744 * mapping, or rendering them.
745 *
746 * **Example** (Checking for typed errors)
747 *
748 * ```ts import.meta.vitest
749 * import { Cause } from "effect"
750 *
751 * Cause.hasFails(Cause.fail("error")) // => true
752 * Cause.hasFails(Cause.die("defect")) // => false
753 * ```
754 *
755 * @see {@link hasDies} — check for defects
756 * @see {@link hasInterrupts} — check for interruptions
757 *
758 * @category predicates
759 * @since 4.0.0
760 */
761export const hasFails: <E>(self: Cause<E>) => boolean = effect.hasFails
762
763/**
764 * Returns a `Result` whose success value is the first `Fail` reason in
765 * the cause, including its annotations. If the cause has no `Fail` reason, the
766 * failure value is the original cause narrowed to `Cause<never>`, because it
767 * contains no typed error reasons.
768 *
769 * **When to use**
770 *
771 * Use when you need the full `Fail` reason from a `Cause`, including
772 * annotations.
773 *
774 * **Example** (Extracting the first Fail reason)
775 *
776 * ```ts import.meta.vitest
777 * import { Cause, Result } from "effect"
778 *
779 * Cause.findFail(Cause.fail("error")) // => Result.succeed(Cause.makeFailReason("error"))
780 * ```
781 *
782 * @see {@link findError} — extract the unwrapped `E` value
783 * @see {@link findDie} — extract the first `Die` reason
784 *
785 * @category filtering
786 * @since 4.0.0
787 */
788export const findFail: <E>(self: Cause<E>) => Result.Result<Fail<E>, Cause<never>> = effect.findFail
789
790/**
791 * Returns a `Result` whose success value is the first typed error value `E`
792 * from a `Fail` reason in the cause. If the cause has no `Fail` reason,
793 * the failure value is the original cause narrowed to `Cause<never>`, because
794 * it contains no typed error reasons.
795 *
796 * **When to use**
797 *
798 * Use when you need the first typed error value from a `Cause` as a `Result`
799 * that preserves the original cause when no match is found.
800 *
801 * **Example** (Extracting the first error value)
802 *
803 * ```ts import.meta.vitest
804 * import { Cause, Result } from "effect"
805 *
806 * Cause.findError(Cause.fail("error")) // => Result.succeed("error")
807 * ```
808 *
809 * @see {@link findFail} — extract the full `Fail` reason
810 * @see {@link findErrorOption} — `Option`-based variant
811 *
812 * @category filtering
813 * @since 4.0.0
814 */
815export const findError: <E>(self: Cause<E>) => Result.Result<E, Cause<never>> = effect.findError
816
817/**
818 * Returns the first typed error value `E` from a cause wrapped in
819 * `Option.some`, or `Option.none` if no `Fail` reason exists.
820 *
821 * **When to use**
822 *
823 * Use when you need the first typed error value from a `Cause` as an `Option`,
824 * discarding the original cause.
825 *
826 * **Example** (Extracting an error as Option)
827 *
828 * ```ts import.meta.vitest
829 * import { Cause, Option } from "effect"
830 *
831 * Cause.findErrorOption(Cause.fail("error")) // => Option.some("error")
832 * Cause.findErrorOption(Cause.die("defect")) // => Option.none()
833 * ```
834 *
835 * @see {@link findError} — `Result`-based variant
836 *
837 * @category filtering
838 * @since 4.0.0
839 */
840export const findErrorOption: <E>(input: Cause<E>) => Option<E> = effect.findErrorOption
841
842/**
843 * Returns `true` if the cause contains at least one `Die` reason.
844 *
845 * **When to use**
846 *
847 * Use to check whether a cause includes defects before extracting or rendering
848 * them.
849 *
850 * **Example** (Checking for defects)
851 *
852 * ```ts import.meta.vitest
853 * import { Cause } from "effect"
854 *
855 * Cause.hasDies(Cause.die("defect")) // => true
856 * Cause.hasDies(Cause.fail("error")) // => false
857 * ```
858 *
859 * @see {@link hasFails} — check for typed errors
860 * @see {@link hasInterrupts} — check for interruptions
861 *
862 * @category predicates
863 * @since 4.0.0
864 */
865export const hasDies: <E>(self: Cause<E>) => boolean = effect.hasDies
866
867/**
868 * Returns a `Result` whose success value is the first `Die` reason in
869 * the cause, including its annotations. If the cause has no `Die` reason, the
870 * failure value is the original cause.
871 *
872 * **When to use**
873 *
874 * Use when you need the full `Die` reason from a `Cause`, including
875 * annotations.
876 *
877 * **Example** (Extracting the first Die reason)
878 *
879 * ```ts import.meta.vitest
880 * import { Cause, Result } from "effect"
881 *
882 * Cause.findDie(Cause.die("defect")) // => Result.succeed(Cause.makeDieReason("defect"))
883 * ```
884 *
885 * @see {@link findDefect} — extract the unwrapped defect value
886 * @see {@link findFail} — extract the first `Fail` reason
887 *
888 * @category filtering
889 * @since 4.0.0
890 */
891export const findDie: <E>(self: Cause<E>) => Result.Result<Die, Cause<E>> = effect.findDie
892
893/**
894 * Returns a `Result` whose success value is the first defect value from a
895 * `Die` reason in the cause. If the cause has no `Die` reason, the
896 * failure value is the original cause.
897 *
898 * **When to use**
899 *
900 * Use when you need the first defect value from a `Cause` as a `Result`,
901 * without the full `Die` reason.
902 *
903 * **Example** (Extracting the first defect)
904 *
905 * ```ts import.meta.vitest
906 * import { Cause, Result } from "effect"
907 *
908 * Cause.findDefect(Cause.die("defect")) // => Result.succeed("defect")
909 * ```
910 *
911 * @see {@link findDie} — extract the full `Die` reason
912 * @see {@link findError} — extract the first typed error
913 *
914 * @category filtering
915 * @since 4.0.0
916 */
917export const findDefect: <E>(self: Cause<E>) => Result.Result<unknown, Cause<E>> = effect.findDefect
918
919/**
920 * Returns `true` if the cause contains at least one `Interrupt` reason.
921 *
922 * **Example** (Checking for interruptions)
923 *
924 * ```ts import.meta.vitest
925 * import { Cause } from "effect"
926 *
927 * Cause.hasInterrupts(Cause.interrupt(123)) // => true
928 * Cause.hasInterrupts(Cause.fail("error")) // => false
929 * ```
930 *
931 * @see {@link hasInterruptsOnly} — `true` only when *all* reasons are interrupts
932 * @see {@link hasFails} — check for typed errors
933 * @see {@link hasDies} — check for defects
934 *
935 * @category predicates
936 * @since 4.0.0
937 */
938export const hasInterrupts: <E>(self: Cause<E>) => boolean = effect.hasInterrupts
939
940/**
941 * Returns a `Result` whose success value is the first `Interrupt` reason
942 * in the cause, including its annotations. If the cause has no `Interrupt`
943 * reason, the failure value is the original cause.
944 *
945 * **When to use**
946 *
947 * Use when you need the first `Interrupt` reason from a `Cause`, including the
948 * fiber ID and annotations.
949 *
950 * **Example** (Extracting the first interrupt)
951 *
952 * ```ts import.meta.vitest
953 * import { Cause, Result } from "effect"
954 *
955 * Cause.findInterrupt(Cause.interrupt(42)) // => Result.succeed(Cause.makeInterruptReason(42))
956 * ```
957 *
958 * @see {@link interruptors} — collect all interrupting fiber IDs as a `Set`
959 *
960 * @category filtering
961 * @since 4.0.0
962 */
963export const findInterrupt: <E>(self: Cause<E>) => Result.Result<Interrupt, Cause<E>> = effect.findInterrupt
964
965/**
966 * Collects the defined fiber IDs from all `Interrupt` reasons in the
967 * cause into a `ReadonlySet`. Interrupt reasons without a `fiberId` are
968 * ignored. Returns an empty set when the cause has no interrupting fiber IDs.
969 *
970 * **When to use**
971 *
972 * Use when you need interrupting fiber IDs as a set, with absence represented
973 * as an empty set.
974 *
975 * **Example** (Collecting interruptors)
976 *
977 * ```ts import.meta.vitest
978 * import { Cause } from "effect"
979 *
980 * const cause = Cause.combine(
981 * Cause.interrupt(1),
982 * Cause.interrupt(2)
983 * )
984 *
985 * Cause.interruptors(cause) // => new Set([1, 2])
986 * ```
987 *
988 * @see {@link filterInterruptors} — `Result`-based variant
989 *
990 * @category getters
991 * @since 2.0.0
992 */
993export const interruptors: <E>(self: Cause<E>) => ReadonlySet<number> = effect.causeInterruptors
994
995/**
996 * Returns a `Result` whose success value is the set of defined fiber IDs from
997 * the cause's `Interrupt` reasons. If the cause has no `Interrupt`
998 * reason, the failure value is the original cause.
999 *
1000 * **When to use**
1001 *
1002 * Use when you need absence of interrupt reasons to fail with the original
1003 * cause.
1004 *
1005 * **Gotchas**
1006 *
1007 * Interrupt reasons without a `fiberId` still count as interrupts, so the
1008 * function succeeds with an empty `Set` when every interrupt reason has an
1009 * undefined fiber ID.
1010 *
1011 * **Example** (Extracting interruptors with Result)
1012 *
1013 * ```ts import.meta.vitest
1014 * import { Cause, Result } from "effect"
1015 *
1016 * Cause.filterInterruptors(Cause.interrupt(1)) // => Result.succeed(new Set([1]))
1017 * ```
1018 *
1019 * @see {@link interruptors} — always-succeeding variant
1020 *
1021 * @category filtering
1022 * @since 4.0.0
1023 */
1024export const filterInterruptors: <E>(self: Cause<E>) => Result.Result<Set<number>, Cause<E>> =
1025 effect.causeFilterInterruptors
1026
1027/**
1028 * Converts a `Cause` into an `Array<Error>` suitable for logging or
1029 * rethrowing.
1030 *
1031 * **When to use**
1032 *
1033 * Use to convert every renderable failure in a cause into individual `Error`
1034 * values before logging or rethrowing.
1035 *
1036 * **Details**
1037 *
1038 * Each `Fail` and `Die` reason is converted into a standard
1039 * `Error`:
1040 *
1041 * - **Objects / Error instances** — `message`, `name`, `stack`, and `cause`
1042 * are preserved. Extra enumerable properties are copied. Stack traces are
1043 * cleaned up and enriched with span annotations when available.
1044 * - **Strings** — used directly as the `Error` message.
1045 * - **Other primitives** (`null`, `undefined`, numbers, …) — wrapped in an
1046 * `Error` with message `"Unknown error: <value>"`.
1047 *
1048 * `Interrupt` reasons are collected separately. If the cause contains
1049 * **only** interrupts (no `Fail` or `Die`), a single `InterruptError` is
1050 * returned whose `cause` lists the interrupting fiber IDs.
1051 *
1052 * An empty cause returns an empty array.
1053 *
1054 * **Example** (Converting a cause to errors)
1055 *
1056 * ```ts import.meta.vitest
1057 * import { Cause } from "effect"
1058 *
1059 * Cause.prettyErrors(Cause.fail(new Error("boom")))[0].message // => "boom"
1060 * ```
1061 *
1062 * @see {@link pretty} — renders the cause as a single string
1063 * @see {@link squash} — lossy collapse to a single thrown value
1064 *
1065 * @category formatting
1066 * @since 3.2.0
1067 */
1068export const prettyErrors: <E>(self: Cause<E>, options?: {
1069 readonly includeCauseInStack?: boolean | undefined
1070}) => Array<Error> = effect.causePrettyErrors
1071
1072/**
1073 * Formats a `Cause` as a human-readable string for logging or debugging.
1074 *
1075 * **When to use**
1076 *
1077 * Use to render a whole cause as one human-readable string for logs or
1078 * diagnostics.
1079 *
1080 * **Details**
1081 *
1082 * Delegates to {@link prettyErrors} to convert each reason to an `Error`,
1083 * then joins their stack traces with newlines. Nested `Error.cause` chains
1084 * are rendered inline with indentation:
1085 *
1086 * ```text
1087 * ErrorName: message
1088 * at ...
1089 * at ... {
1090 * [cause]: NestedError: message
1091 * at ...
1092 * }
1093 * ```
1094 *
1095 * Span annotations are appended to the relevant stack frames when available.
1096 *
1097 * **Gotchas**
1098 *
1099 * Rendering an empty cause produces an empty string because there are no
1100 * errors to render.
1101 *
1102 * **Example** (Rendering a cause)
1103 *
1104 * ```ts import.meta.vitest
1105 * import { Cause } from "effect"
1106 *
1107 * Cause.pretty(Cause.fail("something went wrong")).includes("something went wrong") // => true
1108 * ```
1109 *
1110 * @see {@link prettyErrors} — get the individual `Error` instances
1111 *
1112 * @category formatting
1113 * @since 2.0.0
1114 */
1115export const pretty: <E>(cause: Cause<E>) => string = effect.causePretty
1116
1117/**
1118 * Base interface for error classes that can be yielded directly inside
1119 * `Effect.gen`. Yielding one of these errors fails the generator with that
1120 * error as the typed failure value.
1121 *
1122 * **Details**
1123 *
1124 * All built-in error classes in this module (`NoSuchElementError`,
1125 * `TimeoutError`, `IllegalArgumentError`, `ExceededCapacityError`,
1126 * `AsyncFiberError`, and `UnknownError`) implement this interface.
1127 *
1128 * **Example** (Yielding an error in Effect.gen)
1129 *
1130 * ```ts import.meta.vitest
1131 * import { Cause, Effect, Exit } from "effect"
1132 *
1133 * const error = new Cause.NoSuchElementError("not found")
1134 *
1135 * const program = Effect.gen(function*() {
1136 * return yield* error // fails the effect with NoSuchElementError
1137 * })
1138 *
1139 * await Effect.runPromiseExit(program) // => Exit.fail(error)
1140 * ```
1141 *
1142 * @category errors
1143 * @since 2.0.0
1144 */
1145export interface YieldableError extends Error, Pipeable, Inspectable {
1146 readonly [Effect.TypeId]: Effect.Variance<never, this, never>
1147 [Symbol.iterator](): Effect.EffectIterator<Effect.Effect<never, this, never>>
1148}
1149
1150/**
1151 * Checks whether an arbitrary value is a `NoSuchElementError`.
1152 *
1153 * **Example** (Checking the runtime type)
1154 *
1155 * ```ts import.meta.vitest
1156 * import { Cause } from "effect"
1157 *
1158 * Cause.isNoSuchElementError(new Cause.NoSuchElementError()) // => true
1159 * Cause.isNoSuchElementError("nope") // => false
1160 * ```
1161 *
1162 * @category guards
1163 * @since 4.0.0
1164 */
1165export const isNoSuchElementError: (u: unknown) => u is NoSuchElementError = core.isNoSuchElementError
1166
1167/**
1168 * Unique brand for `NoSuchElementError`.
1169 *
1170 * @category type IDs
1171 * @since 4.0.0
1172 */
1173export const NoSuchElementErrorTypeId: "~effect/Cause/NoSuchElementError" = core.NoSuchElementErrorTypeId
1174
1175/**
1176 * An error indicating that an expected value was absent.
1177 *
1178 * **When to use**
1179 *
1180 * Use to model APIs that intentionally turn absence into an error.
1181 *
1182 * **Details**
1183 *
1184 * Used by APIs that convert absence into an exception or effect failure, such
1185 * as `Option.getOrThrow`. Implements `YieldableError` so it can be
1186 * yielded directly in `Effect.gen`.
1187 *
1188 * **Gotchas**
1189 *
1190 * Prefer APIs that return `Option` or a typed failure when absence is an
1191 * expected case. This error is mainly for APIs that intentionally turn absence
1192 * into a thrown value or failed effect.
1193 *
1194 * @category errors
1195 * @since 4.0.0
1196 */
1197export interface NoSuchElementError extends YieldableError {
1198 readonly [NoSuchElementErrorTypeId]: typeof NoSuchElementErrorTypeId
1199 readonly _tag: "NoSuchElementError"
1200}
1201
1202/**
1203 * Constructs a `NoSuchElementError` with an optional message.
1204 *
1205 * **When to use**
1206 *
1207 * Use to create the error value for APIs that intentionally fail when an
1208 * expected element is absent.
1209 *
1210 * **Example** (Creating a NoSuchElementError)
1211 *
1212 * ```ts import.meta.vitest
1213 * import { Cause } from "effect"
1214 *
1215 * new Cause.NoSuchElementError("Element not found").message // => "Element not found"
1216 * ```
1217 *
1218 * @see {@link isNoSuchElementError} for checking unknown values
1219 *
1220 * @category constructors
1221 * @since 4.0.0
1222 */
1223export const NoSuchElementError: new(message?: string) => NoSuchElementError = core.NoSuchElementError
1224
1225/**
1226 * Checks whether an arbitrary value is a `Done` signal.
1227 *
1228 * **Example** (Checking the runtime type)
1229 *
1230 * ```ts import.meta.vitest
1231 * import { Cause } from "effect"
1232 *
1233 * Cause.isDone(Cause.Done()) // => true
1234 * Cause.isDone("not done") // => false
1235 * ```
1236 *
1237 * @category guards
1238 * @since 4.0.0
1239 */
1240export const isDone: (u: unknown) => u is Done<any> = core.isDone
1241
1242/**
1243 * Unique brand for `Done` values.
1244 *
1245 * @category type IDs
1246 * @since 4.0.0
1247 */
1248export const DoneTypeId: "~effect/Cause/Done" = core.DoneTypeId
1249
1250/**
1251 * A graceful completion signal for queues and streams.
1252 *
1253 * **When to use**
1254 *
1255 * Use to model normal producer completion through a stream or queue error
1256 * channel.
1257 *
1258 * **Details**
1259 *
1260 * `Done` indicates that a producer has finished normally — no more elements
1261 * will arrive. It is distinct from an error or interruption; it represents
1262 * successful completion. The optional `value` field can carry a final
1263 * leftover payload.
1264 *
1265 * **Example** (Signaling queue completion)
1266 *
1267 * ```ts import.meta.vitest
1268 * import { Cause, Effect, Queue } from "effect"
1269 *
1270 * const program = Effect.gen(function*() {
1271 * const queue = yield* Queue.bounded<number, Cause.Done>(10)
1272 * yield* Queue.offer(queue, 1)
1273 * yield* Queue.end(queue)
1274 *
1275 * yield* Queue.take(queue)
1276 * const result = yield* Effect.flip(Queue.take(queue))
1277 * return Cause.isDone(result)
1278 * })
1279 *
1280 * await Effect.runPromise(program) // => true
1281 * ```
1282 *
1283 * @category errors
1284 * @since 4.0.0
1285 */
1286export interface Done<A = void> {
1287 readonly [DoneTypeId]: typeof DoneTypeId
1288 readonly _tag: "Done"
1289 readonly value: A
1290}
1291
1292/**
1293 * Companion namespace for the `Done` interface.
1294 *
1295 * @since 4.0.0
1296 */
1297export declare namespace Done {
1298 /**
1299 * Extracts the value type `A` from a `Done<A>` that may be nested in an
1300 * error union.
1301 *
1302 * @category utility types
1303 * @since 4.0.0
1304 */
1305 export type Extract<E> = E extends Done<infer L> ? L : never
1306
1307 /**
1308 * Filters a type union to only keep `Done` members.
1309 *
1310 * @category filtering
1311 * @since 4.0.0
1312 */
1313 export type Only<E> = E extends Done<infer L> ? Done<L> : never
1314}
1315
1316/**
1317 * Creates a `Done` signal with an optional value.
1318 *
1319 * **When to use**
1320 *
1321 * Use when you need to construct a low-level pull completion signal directly.
1322 *
1323 * @see {@link done} — create a failing `Effect` with `Done`
1324 *
1325 * @category constructors
1326 * @since 4.0.0
1327 */
1328export const Done: <A = void>(value?: A) => Done<A> = core.Done
1329
1330/**
1331 * Creates an Effect that fails with a `Done` error. Shorthand for
1332 * `Effect.fail(Cause.Done(value))`.
1333 *
1334 * **When to use**
1335 *
1336 * Use when you model stream or queue completion through the error channel.
1337 *
1338 * **Example** (Failing with Done)
1339 *
1340 * ```ts import.meta.vitest
1341 * import { Cause, Effect, Exit } from "effect"
1342 *
1343 * const program = Cause.done("finished")
1344 *
1345 * await Effect.runPromiseExit(program) // => Exit.fail(Cause.Done("finished"))
1346 * ```
1347 *
1348 * @see {@link Done} — create the signal value without an Effect
1349 *
1350 * @category constructors
1351 * @since 4.0.0
1352 */
1353export const done: <A = void>(value?: A) => Effect.Effect<never, Done<A>> = core.done
1354
1355/**
1356 * Unique brand for `TimeoutError`.
1357 *
1358 * @category type IDs
1359 * @since 4.0.0
1360 */
1361export const TimeoutErrorTypeId: "~effect/Cause/TimeoutError" = effect.TimeoutErrorTypeId
1362
1363/**
1364 * Checks whether an arbitrary value is a `TimeoutError`.
1365 *
1366 * **Example** (Checking the runtime type)
1367 *
1368 * ```ts import.meta.vitest
1369 * import { Cause } from "effect"
1370 *
1371 * Cause.isTimeoutError(new Cause.TimeoutError()) // => true
1372 * Cause.isTimeoutError("nope") // => false
1373 * ```
1374 *
1375 * @category guards
1376 * @since 4.0.0
1377 */
1378export const isTimeoutError: (u: unknown) => u is TimeoutError = effect.isTimeoutError
1379
1380/**
1381 * An error indicating that an operation exceeded its time limit.
1382 *
1383 * **Details**
1384 *
1385 * Produced by `Effect.timeout` and related APIs. Implements
1386 * `YieldableError`.
1387 *
1388 * @category errors
1389 * @since 4.0.0
1390 */
1391export interface TimeoutError extends YieldableError {
1392 readonly [TimeoutErrorTypeId]: typeof TimeoutErrorTypeId
1393 readonly _tag: "TimeoutError"
1394}
1395
1396/**
1397 * Constructs a `TimeoutError` with an optional message.
1398 *
1399 * **Example** (Creating a TimeoutError)
1400 *
1401 * ```ts import.meta.vitest
1402 * import { Cause } from "effect"
1403 *
1404 * new Cause.TimeoutError("Operation timed out").message // => "Operation timed out"
1405 * ```
1406 *
1407 * @category constructors
1408 * @since 4.0.0
1409 */
1410export const TimeoutError: new(message?: string) => TimeoutError = effect.TimeoutError
1411
1412/**
1413 * Unique brand for `IllegalArgumentError`.
1414 *
1415 * @category type IDs
1416 * @since 4.0.0
1417 */
1418export const IllegalArgumentErrorTypeId: "~effect/Cause/IllegalArgumentError" = effect.IllegalArgumentErrorTypeId
1419
1420/**
1421 * Checks whether an arbitrary value is an `IllegalArgumentError`.
1422 *
1423 * **Example** (Checking the runtime type)
1424 *
1425 * ```ts import.meta.vitest
1426 * import { Cause } from "effect"
1427 *
1428 * Cause.isIllegalArgumentError(new Cause.IllegalArgumentError()) // => true
1429 * Cause.isIllegalArgumentError("nope") // => false
1430 * ```
1431 *
1432 * @category guards
1433 * @since 4.0.0
1434 */
1435export const isIllegalArgumentError: (u: unknown) => u is IllegalArgumentError = effect.isIllegalArgumentError
1436
1437/**
1438 * An error indicating that a function received an argument that violates
1439 * its contract (e.g. negative where positive was expected).
1440 *
1441 * **Details**
1442 *
1443 * Implements `YieldableError`.
1444 *
1445 * @category errors
1446 * @since 4.0.0
1447 */
1448export interface IllegalArgumentError extends YieldableError {
1449 readonly [IllegalArgumentErrorTypeId]: typeof IllegalArgumentErrorTypeId
1450 readonly _tag: "IllegalArgumentError"
1451}
1452
1453/**
1454 * Constructs an `IllegalArgumentError` with an optional message.
1455 *
1456 * **Example** (Creating an IllegalArgumentError)
1457 *
1458 * ```ts import.meta.vitest
1459 * import { Cause } from "effect"
1460 *
1461 * new Cause.IllegalArgumentError("Invalid argument").message // => "Invalid argument"
1462 * ```
1463 *
1464 * @category constructors
1465 * @since 4.0.0
1466 */
1467export const IllegalArgumentError: new(message?: string) => IllegalArgumentError = effect.IllegalArgumentError
1468
1469/**
1470 * Checks whether an arbitrary value is an `ExceededCapacityError`.
1471 *
1472 * **Example** (Checking the runtime type)
1473 *
1474 * ```ts import.meta.vitest
1475 * import { Cause } from "effect"
1476 *
1477 * Cause.isExceededCapacityError(new Cause.ExceededCapacityError()) // => true
1478 * Cause.isExceededCapacityError("nope") // => false
1479 * ```
1480 *
1481 * @category guards
1482 * @since 4.0.0
1483 */
1484export const isExceededCapacityError: (u: unknown) => u is ExceededCapacityError = effect.isExceededCapacityError
1485
1486/**
1487 * Unique brand for `ExceededCapacityError`.
1488 *
1489 * @category type IDs
1490 * @since 4.0.0
1491 */
1492export const ExceededCapacityErrorTypeId: "~effect/Cause/ExceededCapacityError" = effect.ExceededCapacityErrorTypeId
1493
1494/**
1495 * An error indicating that a bounded resource (queue, pool, semaphore, etc.)
1496 * has exceeded its capacity.
1497 *
1498 * **When to use**
1499 *
1500 * Use to model bounded-resource failures where an operation cannot proceed
1501 * because capacity has been exhausted.
1502 *
1503 * **Details**
1504 *
1505 * Implements `YieldableError`.
1506 *
1507 * @category errors
1508 * @since 4.0.0
1509 */
1510export interface ExceededCapacityError extends YieldableError {
1511 readonly [ExceededCapacityErrorTypeId]: typeof ExceededCapacityErrorTypeId
1512 readonly _tag: "ExceededCapacityError"
1513}
1514
1515/**
1516 * Constructs an `ExceededCapacityError` with an optional message.
1517 *
1518 * **When to use**
1519 *
1520 * Use to create the error value for bounded-resource capacity failures.
1521 *
1522 * **Example** (Creating an ExceededCapacityError)
1523 *
1524 * ```ts import.meta.vitest
1525 * import { Cause } from "effect"
1526 *
1527 * new Cause.ExceededCapacityError("Queue full").message // => "Queue full"
1528 * ```
1529 *
1530 * @see {@link isExceededCapacityError} for checking unknown values
1531 *
1532 * @category constructors
1533 * @since 4.0.0
1534 */
1535export const ExceededCapacityError: new(message?: string) => ExceededCapacityError = effect.ExceededCapacityError
1536
1537/**
1538 * Unique brand present on `AsyncFiberError` values and used by
1539 * `isAsyncFiberError` for runtime checks.
1540 *
1541 * @category type IDs
1542 * @since 4.0.0
1543 */
1544export const AsyncFiberErrorTypeId: "~effect/Cause/AsyncFiberError" = effect.AsyncFiberErrorTypeId
1545
1546/**
1547 * Checks whether an arbitrary value is an `AsyncFiberError`.
1548 *
1549 * **Example** (Checking the runtime type)
1550 *
1551 * ```ts import.meta.vitest
1552 * import { Cause, Effect } from "effect"
1553 *
1554 * const fiber = Effect.runFork(Effect.void)
1555 *
1556 * const error = new Cause.AsyncFiberError(fiber)
1557 * Cause.isAsyncFiberError(error) // => true
1558 * Cause.isAsyncFiberError("nope") // => false
1559 * ```
1560 *
1561 * @category guards
1562 * @since 4.0.0
1563 */
1564export const isAsyncFiberError: (u: unknown) => u is AsyncFiberError = effect.isAsyncFiberError
1565
1566/**
1567 * An error that occurs when trying to run an async fiber with Effect.runSync.
1568 *
1569 * **When to use**
1570 *
1571 * Use to inspect failures produced when synchronous runners encounter an effect
1572 * that cannot complete synchronously.
1573 *
1574 * **Details**
1575 *
1576 * The `fiber` property stores the fiber that could not be synchronously
1577 * resolved. This error implements `YieldableError`.
1578 *
1579 * **Example** (Accessing the fiber)
1580 *
1581 * ```ts import.meta.vitest
1582 * import { Cause, Effect } from "effect"
1583 *
1584 * const fiber = Effect.runFork(Effect.void)
1585 *
1586 * const value = new Cause.AsyncFiberError(fiber)
1587 * const isSameFiber = value.fiber === fiber
1588 * isSameFiber // => true
1589 * ```
1590 *
1591 * @category errors
1592 * @since 4.0.0
1593 */
1594export interface AsyncFiberError extends YieldableError {
1595 readonly [AsyncFiberErrorTypeId]: typeof AsyncFiberErrorTypeId
1596 readonly _tag: "AsyncFiberError"
1597 readonly fiber: Fiber<unknown, unknown>
1598}
1599
1600/**
1601 * Constructs an `AsyncFiberError` for a fiber that could not be resolved
1602 * synchronously.
1603 *
1604 * **When to use**
1605 *
1606 * Use to create the error value for a fiber that could not be completed by a
1607 * synchronous runner.
1608 *
1609 * **Example** (Creating an AsyncFiberError)
1610 *
1611 * ```ts import.meta.vitest
1612 * import { Cause, Effect } from "effect"
1613 *
1614 * const fiber = Effect.runFork(Effect.void)
1615 *
1616 * new Cause.AsyncFiberError(fiber).message // => "An asynchronous Effect was executed with Effect.runSync"
1617 * ```
1618 *
1619 * @see {@link isAsyncFiberError} for checking unknown values
1620 *
1621 * @category constructors
1622 * @since 4.0.0
1623 */
1624export const AsyncFiberError: new(fiber: Fiber<unknown, unknown>) => AsyncFiberError = effect.AsyncFiberError
1625
1626/**
1627 * Unique brand for `UnknownError`.
1628 *
1629 * @category type IDs
1630 * @since 4.0.0
1631 */
1632export const UnknownErrorTypeId: "~effect/Cause/UnknownError" = effect.UnknownErrorTypeId
1633
1634/**
1635 * Checks whether an arbitrary value is an `UnknownError`.
1636 *
1637 * **Example** (Checking the runtime type)
1638 *
1639 * ```ts import.meta.vitest
1640 * import { Cause } from "effect"
1641 *
1642 * Cause.isUnknownError(new Cause.UnknownError("x")) // => true
1643 * Cause.isUnknownError("nope") // => false
1644 * ```
1645 *
1646 * @category guards
1647 * @since 4.0.0
1648 */
1649export const isUnknownError: (u: unknown) => u is UnknownError = effect.isUnknownError
1650
1651/**
1652 * A wrapper for errors whose type is not statically known.
1653 *
1654 * **Details**
1655 *
1656 * Used when a thrown or rejected value is not represented by a more specific
1657 * typed error. The original value is stored in the `cause` property inherited
1658 * from `Error`. Implements `YieldableError`.
1659 *
1660 * @category errors
1661 * @since 4.0.0
1662 */
1663export interface UnknownError extends YieldableError {
1664 readonly [UnknownErrorTypeId]: typeof UnknownErrorTypeId
1665 readonly _tag: "UnknownError"
1666}
1667
1668/**
1669 * Constructs an `UnknownError`. The first argument is the original
1670 * cause (stored in `Error.cause`); the second is an optional human-readable
1671 * message.
1672 *
1673 * **Example** (Creating an UnknownError)
1674 *
1675 * ```ts import.meta.vitest
1676 * import { Cause } from "effect"
1677 *
1678 * new Cause.UnknownError({ raw: true }, "Unexpected value").message // => "Unexpected value"
1679 * ```
1680 *
1681 * @category constructors
1682 * @since 4.0.0
1683 */
1684export const UnknownError: new(cause: unknown, message?: string) => UnknownError = effect.UnknownError
1685
1686/**
1687 * Attaches metadata to every reason in a `Cause`.
1688 *
1689 * **When to use**
1690 *
1691 * Use to attach diagnostic metadata to every reason in a cause.
1692 *
1693 * **Details**
1694 *
1695 * Annotations are stored as a `Context` on each reason and can be
1696 * retrieved later via {@link reasonAnnotations} or {@link annotations}.
1697 * The runtime uses this to attach stack traces and spans.
1698 *
1699 * - Returns a new `Cause`.
1700 * - By default, existing keys are preserved. Pass `{ overwrite: true }` to
1701 * replace them.
1702 *
1703 * **Example** (Annotating a cause)
1704 *
1705 * ```ts import.meta.vitest
1706 * import { Cause, Context } from "effect"
1707 *
1708 * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
1709 *
1710 * const annotated = Cause.annotate(Cause.fail("error"), Context.make(RequestId, "req-1"))
1711 * Context.getOrUndefined(Cause.annotations(annotated), RequestId) // => "req-1"
1712 * ```
1713 *
1714 * @see {@link annotations} for reading merged annotations from a cause
1715 * @see {@link reasonAnnotations} for reading annotations from a single reason
1716 *
1717 * @category annotations
1718 * @since 4.0.0
1719 */
1720export const annotate: {
1721 (
1722 annotations: Context.Context<never>,
1723 options?: { readonly overwrite?: boolean | undefined }
1724 ): <E>(self: Cause<E>) => Cause<E>
1725 <E>(
1726 self: Cause<E>,
1727 annotations: Context.Context<never>,
1728 options?: { readonly overwrite?: boolean | undefined }
1729 ): Cause<E>
1730} = core.causeAnnotate
1731
1732/**
1733 * Reads the annotations from a single `Reason` as a `Context`.
1734 *
1735 * **When to use**
1736 *
1737 * Use when you need tracing metadata (e.g. `StackTrace`) from
1738 * a specific reason rather than the whole cause.
1739 *
1740 * **Example** (Reading reason annotations)
1741 *
1742 * ```ts import.meta.vitest
1743 * import { Cause, Context } from "effect"
1744 *
1745 * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
1746 *
1747 * const reason = Cause.makeFailReason("error")
1748 * const annotated = reason.annotate(Context.make(RequestId, "req-1"))
1749 *
1750 * Context.getOrUndefined(Cause.reasonAnnotations(annotated), RequestId) // => "req-1"
1751 * ```
1752 *
1753 * @see {@link annotations} — merged annotations from all reasons in a cause
1754 *
1755 * @category annotations
1756 * @since 4.0.0
1757 */
1758export const reasonAnnotations: <E>(self: Reason<E>) => Context.Context<never> = effect.reasonAnnotations
1759
1760/**
1761 * Reads the merged annotations from all reasons in a `Cause`.
1762 *
1763 * **When to use**
1764 *
1765 * Use to read diagnostic metadata merged from the whole cause.
1766 *
1767 * **Gotchas**
1768 *
1769 * When multiple reasons contain the same annotation key, the value from the
1770 * later reason wins.
1771 *
1772 * **Example** (Reading merged annotations)
1773 *
1774 * ```ts import.meta.vitest
1775 * import { Cause, Context } from "effect"
1776 *
1777 * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
1778 *
1779 * const cause = Cause.annotate(
1780 * Cause.fail("error"),
1781 * Context.make(RequestId, "req-1")
1782 * )
1783 *
1784 * Context.getOrUndefined(Cause.annotations(cause), RequestId) // => "req-1"
1785 * ```
1786 *
1787 * @see {@link reasonAnnotations} — annotations from a single reason
1788 *
1789 * @category annotations
1790 * @since 4.0.0
1791 */
1792export const annotations: <E>(self: Cause<E>) => Context.Context<never> = effect.causeAnnotations
1793
1794/**
1795 * Context annotation used to store the stack frame captured at the point of failure.
1796 *
1797 * **When to use**
1798 *
1799 * Use to read the failure stack-frame annotation from a `Reason` when building
1800 * diagnostics, logging, or custom cause renderers.
1801 *
1802 * **Details**
1803 *
1804 * The runtime annotates every reason with this when a stack frame is
1805 * available. Retrieve it via
1806 * `Context.get(Cause.reasonAnnotations(reason), Cause.StackTrace)`.
1807 *
1808 * @see {@link reasonAnnotations} for reading annotations from a single reason
1809 * @see {@link annotations} for reading merged annotations from a cause
1810 * @see {@link InterruptorStackTrace} for the interrupt-specific stack-frame annotation
1811 *
1812 * @category services
1813 * @since 4.0.0
1814 */
1815export class StackTrace extends Context.Service<StackTrace, StackFrame>()("effect/Cause/StackTrace") {}
1816
1817/**
1818 * Context annotation used to store the stack frame captured at the point of
1819 * interruption.
1820 *
1821 * **When to use**
1822 *
1823 * Use when you need the stack-frame annotation used by interrupt-only cause
1824 * rendering.
1825 *
1826 * **Details**
1827 *
1828 * Similar to `StackTrace` but specific to `Interrupt` reasons.
1829 *
1830 * @see {@link StackTrace} for stack frames attached to failures
1831 * @see {@link reasonAnnotations} for reading annotations from a single reason
1832 * @see {@link annotate} for attaching annotations to a cause
1833 *
1834 * @category services
1835 * @since 4.0.0
1836 */
1837export class InterruptorStackTrace
1838 extends Context.Service<InterruptorStackTrace, StackFrame>()("effect/Cause/InterruptorStackTrace")
1839{}