effect 4.0.1 → 4.0.2

package/src/Cause.ts

@@ -7,6 +7,7 @@
  * includes the `Cause` and `Reason` data types, helpers for building and
  * checking causes, and small error types used by several Effect APIs.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import * as Context from "./Context.ts"
@@ -25,6 +26,7 @@ import type * as Types from "./Types.ts"
 /**
  * Unique brand for `Cause` values, used for runtime type checks via {@link isCause}.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -33,6 +35,7 @@ export const TypeId: "~effect/Cause" = core.CauseTypeId
 /**
  * Unique brand for `Reason` values, used for runtime type checks via {@link isReason}.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -69,6 +72,7 @@ export const ReasonTypeId: "~effect/Cause/Reason" = core.CauseReasonTypeId
  * Cause.fail("Something went wrong") // => Cause.fail("Something went wrong")
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -89,6 +93,7 @@ export interface Cause<out E> extends Pipeable, Inspectable, Equal {
  * Cause.isCause("not a cause") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -107,6 +112,7 @@ export const isCause: (self: unknown) => self is Cause<unknown> = core.isCause
  * Cause.isReason("not a reason") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -138,6 +144,7 @@ export const isReason: (self: unknown) => self is Reason<unknown> = core.isCause
  * }
  * ```
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -164,6 +171,7 @@ export type Reason<E> = Fail<E> | Die | Interrupt
  * @see {@link isDieReason} — narrow to `Die`
  * @see {@link isInterruptReason} — narrow to `Interrupt`
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -190,6 +198,7 @@ export const isFailReason: <E>(self: Reason<E>) => self is Fail<E> = core.isFail
  * @see {@link isFailReason} — narrow to `Fail`
  * @see {@link isInterruptReason} — narrow to `Interrupt`
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -216,6 +225,7 @@ export const isDieReason: <E>(self: Reason<E>) => self is Die = core.isDieReason
  * @see {@link isFailReason} — narrow to `Fail`
  * @see {@link isDieReason} — narrow to `Die`
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -224,6 +234,7 @@ export const isInterruptReason: <E>(self: Reason<E>) => self is Interrupt = core
 /**
  * Companion namespace for the `Cause` interface.
  *
+ * @stability stable
  * @since 2.0.0
  */
 export declare namespace Cause {
@@ -270,6 +281,7 @@ export declare namespace Cause {
 /**
  * Companion namespace for the `Reason` type.
  *
+ * @stability stable
  * @since 4.0.0
  */
 export declare namespace Reason {
@@ -320,6 +332,7 @@ export declare namespace Reason {
  * @see {@link die} for constructing a cause with a single `Die` reason
  * @see {@link isDieReason} for narrowing a `Reason` to `Die`
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -355,6 +368,7 @@ export interface Die extends Cause.ReasonProto<"Die"> {
  * @see {@link fail} for constructing a cause with a single `Fail` reason
  * @see {@link isFailReason} for narrowing a `Reason` to `Fail`
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -382,6 +396,7 @@ export interface Fail<out E> extends Cause.ReasonProto<"Fail"> {
  * }
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -422,6 +437,7 @@ export interface Interrupt extends Cause.ReasonProto<"Interrupt"> {
  *
  * @see {@link combine} — merge two existing causes
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -452,6 +468,7 @@ export const fromReasons: <E>(
  *
  * @see {@link combine} for merging causes where `empty` acts as the identity
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -476,6 +493,7 @@ export const empty: Cause<never> = core.causeEmpty
  * @see {@link die} — for untyped defects
  * @see {@link interrupt} — for fiber interruptions
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -500,6 +518,7 @@ export const fail: <E>(error: E) => Cause<E> = core.causeFail
  * @see {@link fail} — for typed errors
  * @see {@link interrupt} — for fiber interruptions
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -520,6 +539,7 @@ export const die: (defect: unknown) => Cause<never> = core.causeDie
  * @see {@link fail} — for typed errors
  * @see {@link die} — for untyped defects
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -544,6 +564,7 @@ export const interrupt: (fiberId?: number | undefined) => Cause<never> = effect.
  * @see {@link makeDieReason} — create a `Die` reason
  * @see {@link makeInterruptReason} — create an `Interrupt` reason
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -568,6 +589,7 @@ export const makeFailReason = <E>(error: E): Fail<E> => new core.Fail(error)
  * @see {@link makeFailReason} — create a `Fail` reason
  * @see {@link makeInterruptReason} — create an `Interrupt` reason
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -593,6 +615,7 @@ export const makeDieReason = (defect: unknown): Die => new core.Die(defect)
  * @see {@link makeFailReason} — create a `Fail` reason
  * @see {@link makeDieReason} — create a `Die` reason
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -618,6 +641,7 @@ export const makeInterruptReason: (fiberId?: number | undefined) => Interrupt =
  *
  * @see {@link hasInterrupts} — `true` if the cause contains *any* interrupts
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -652,6 +676,7 @@ export const hasInterruptsOnly: <E>(self: Cause<E>) => boolean = effect.hasInter
  * }
  * ```
  *
+ * @stability stable
  * @category mapping
  * @since 2.0.0
  */
@@ -685,6 +710,7 @@ export const map: {
    * }
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -718,6 +744,7 @@ export const map: {
    * }
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -750,6 +777,7 @@ export const map: {
  * @see {@link fromReasons} — build a cause from an array of reasons
  * @see {@link empty} for the identity cause used when combining
  *
+ * @stability stable
  * @category combining
  * @since 4.0.0
  */
@@ -780,6 +808,7 @@ export const combine: {
    * @see {@link fromReasons} — build a cause from an array of reasons
    * @see {@link empty} for the identity cause used when combining
    *
+   * @stability stable
    * @category combining
    * @since 4.0.0
    */
@@ -810,6 +839,7 @@ export const combine: {
    * @see {@link fromReasons} — build a cause from an array of reasons
    * @see {@link empty} for the identity cause used when combining
    *
+   * @stability stable
    * @category combining
    * @since 4.0.0
    */
@@ -852,6 +882,7 @@ export const combine: {
  * @see {@link prettyErrors} — non-lossy conversion to `Array<Error>`
  * @see {@link pretty} — human-readable string rendering
  *
+ * @stability stable
  * @category destructors
  * @since 2.0.0
  */
@@ -877,6 +908,7 @@ export const squash: <E>(self: Cause<E>) => unknown = effect.causeSquash
  * @see {@link hasDies} — check for defects
  * @see {@link hasInterrupts} — check for interruptions
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -904,6 +936,7 @@ export const hasFails: <E>(self: Cause<E>) => boolean = effect.hasFails
  * @see {@link findError} — extract the unwrapped `E` value
  * @see {@link findDie} — extract the first `Die` reason
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -931,6 +964,7 @@ export const findFail: <E>(self: Cause<E>) => Result.Result<Fail<E>, Cause<never
  * @see {@link findFail} — extract the full `Fail` reason
  * @see {@link findErrorOption} — `Option`-based variant
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -956,6 +990,7 @@ export const findError: <E>(self: Cause<E>) => Result.Result<E, Cause<never>> =
  *
  * @see {@link findError} — `Result`-based variant
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -981,6 +1016,7 @@ export const findErrorOption: <E>(input: Cause<E>) => Option<E> = effect.findErr
  * @see {@link hasFails} — check for typed errors
  * @see {@link hasInterrupts} — check for interruptions
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -1007,6 +1043,7 @@ export const hasDies: <E>(self: Cause<E>) => boolean = effect.hasDies
  * @see {@link findDefect} — extract the unwrapped defect value
  * @see {@link findFail} — extract the first `Fail` reason
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -1033,6 +1070,7 @@ export const findDie: <E>(self: Cause<E>) => Result.Result<Die, Cause<E>> = effe
  * @see {@link findDie} — extract the full `Die` reason
  * @see {@link findError} — extract the first typed error
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -1054,6 +1092,7 @@ export const findDefect: <E>(self: Cause<E>) => Result.Result<unknown, Cause<E>>
  * @see {@link hasFails} — check for typed errors
  * @see {@link hasDies} — check for defects
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -1079,6 +1118,7 @@ export const hasInterrupts: <E>(self: Cause<E>) => boolean = effect.hasInterrupt
  *
  * @see {@link interruptors} — collect all interrupting fiber IDs as a `Set`
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -1109,6 +1149,7 @@ export const findInterrupt: <E>(self: Cause<E>) => Result.Result<Interrupt, Caus
  *
  * @see {@link filterInterruptors} — `Result`-based variant
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -1140,6 +1181,7 @@ export const interruptors: <E>(self: Cause<E>) => ReadonlySet<number> = effect.c
  *
  * @see {@link interruptors} — always-succeeding variant
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -1184,6 +1226,7 @@ export const filterInterruptors: <E>(self: Cause<E>) => Result.Result<Set<number
  * @see {@link pretty} — renders the cause as a single string
  * @see {@link squash} — lossy collapse to a single thrown value
  *
+ * @stability stable
  * @category formatting
  * @since 3.2.0
  */
@@ -1231,6 +1274,7 @@ export const prettyErrors: <E>(self: Cause<E>, options?: {
  *
  * @see {@link prettyErrors} — get the individual `Error` instances
  *
+ * @stability stable
  * @category formatting
  * @since 2.0.0
  */
@@ -1261,6 +1305,7 @@ export const pretty: <E>(cause: Cause<E>) => string = effect.causePretty
  * await Effect.runPromiseExit(program) // => Exit.fail(error)
  * ```
  *
+ * @stability stable
  * @category errors
  * @since 2.0.0
  */
@@ -1281,6 +1326,7 @@ export interface YieldableError extends Error, Pipeable, Inspectable {
  * Cause.isNoSuchElementError("nope") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -1289,6 +1335,7 @@ export const isNoSuchElementError: (u: unknown) => u is NoSuchElementError = cor
 /**
  * Unique brand for `NoSuchElementError`.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -1313,6 +1360,7 @@ 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.
  *
+ * @stability stable
  * @category errors
  * @since 4.0.0
  */
@@ -1339,6 +1387,7 @@ export interface NoSuchElementError extends YieldableError {
  *
  * @see {@link isNoSuchElementError} for checking unknown values
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1356,6 +1405,7 @@ export const NoSuchElementError: new(message?: string) => NoSuchElementError = c
  * Cause.isDone("not done") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -1364,6 +1414,7 @@ export const isDone: (u: unknown) => u is Done<any> = core.isDone
 /**
  * Unique brand for `Done` values.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -1402,6 +1453,7 @@ export const DoneTypeId: "~effect/Cause/Done" = core.DoneTypeId
  * await Effect.runPromise(program) // => true
  * ```
  *
+ * @stability stable
  * @category errors
  * @since 4.0.0
  */
@@ -1414,6 +1466,7 @@ export interface Done<A = void> {
 /**
  * Companion namespace for the `Done` interface.
  *
+ * @stability stable
  * @since 4.0.0
  */
 export declare namespace Done {
@@ -1444,6 +1497,7 @@ export declare namespace Done {
  *
  * @see {@link done} — create a failing `Effect` with `Done`
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1469,6 +1523,7 @@ export const Done: <A = void>(value?: A) => Done<A> = core.Done
  *
  * @see {@link Done} — create the signal value without an Effect
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1477,6 +1532,7 @@ export const done: <A = void>(value?: A) => Effect.Effect<never, Done<A>> = core
 /**
  * Unique brand for `TimeoutError`.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -1494,6 +1550,7 @@ export const TimeoutErrorTypeId: "~effect/Cause/TimeoutError" = effect.TimeoutEr
  * Cause.isTimeoutError("nope") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -1507,6 +1564,7 @@ export const isTimeoutError: (u: unknown) => u is TimeoutError = effect.isTimeou
  * Produced by `Effect.timeout` and related APIs. Implements
  * `YieldableError`.
  *
+ * @stability stable
  * @category errors
  * @since 4.0.0
  */
@@ -1526,6 +1584,7 @@ export interface TimeoutError extends YieldableError {
  * new Cause.TimeoutError("Operation timed out").message // => "Operation timed out"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1534,6 +1593,7 @@ export const TimeoutError: new(message?: string) => TimeoutError = effect.Timeou
 /**
  * Unique brand for `IllegalArgumentError`.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -1551,6 +1611,7 @@ export const IllegalArgumentErrorTypeId: "~effect/Cause/IllegalArgumentError" =
  * Cause.isIllegalArgumentError("nope") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -1564,6 +1625,7 @@ export const isIllegalArgumentError: (u: unknown) => u is IllegalArgumentError =
  *
  * Implements `YieldableError`.
  *
+ * @stability stable
  * @category errors
  * @since 4.0.0
  */
@@ -1583,6 +1645,7 @@ export interface IllegalArgumentError extends YieldableError {
  * new Cause.IllegalArgumentError("Invalid argument").message // => "Invalid argument"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1600,6 +1663,7 @@ export const IllegalArgumentError: new(message?: string) => IllegalArgumentError
  * Cause.isExceededCapacityError("nope") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -1608,6 +1672,7 @@ export const isExceededCapacityError: (u: unknown) => u is ExceededCapacityError
 /**
  * Unique brand for `ExceededCapacityError`.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -1626,6 +1691,7 @@ export const ExceededCapacityErrorTypeId: "~effect/Cause/ExceededCapacityError"
  *
  * Implements `YieldableError`.
  *
+ * @stability stable
  * @category errors
  * @since 4.0.0
  */
@@ -1651,6 +1717,7 @@ export interface ExceededCapacityError extends YieldableError {
  *
  * @see {@link isExceededCapacityError} for checking unknown values
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1660,6 +1727,7 @@ export const ExceededCapacityError: new(message?: string) => ExceededCapacityErr
  * Unique brand present on `AsyncFiberError` values and used by
  * `isAsyncFiberError` for runtime checks.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -1680,6 +1748,7 @@ export const AsyncFiberErrorTypeId: "~effect/Cause/AsyncFiberError" = effect.Asy
  * Cause.isAsyncFiberError("nope") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -1710,6 +1779,7 @@ export const isAsyncFiberError: (u: unknown) => u is AsyncFiberError = effect.is
  * isSameFiber // => true
  * ```
  *
+ * @stability stable
  * @category errors
  * @since 4.0.0
  */
@@ -1740,6 +1810,7 @@ export interface AsyncFiberError extends YieldableError {
  *
  * @see {@link isAsyncFiberError} for checking unknown values
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1748,6 +1819,7 @@ export const AsyncFiberError: new(fiber: Fiber<unknown, unknown>) => AsyncFiberE
 /**
  * Unique brand for `UnknownError`.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -1765,6 +1837,7 @@ export const UnknownErrorTypeId: "~effect/Cause/UnknownError" = effect.UnknownEr
  * Cause.isUnknownError("nope") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -1779,6 +1852,7 @@ 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`.
  *
+ * @stability stable
  * @category errors
  * @since 4.0.0
  */
@@ -1800,6 +1874,7 @@ export interface UnknownError extends YieldableError {
  * new Cause.UnknownError({ raw: true }, "Unexpected value").message // => "Unexpected value"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1836,6 +1911,7 @@ export const UnknownError: new(cause: unknown, message?: string) => UnknownError
  * @see {@link annotations} for reading merged annotations from a cause
  * @see {@link reasonAnnotations} for reading annotations from a single reason
  *
+ * @stability stable
  * @category annotations
  * @since 4.0.0
  */
@@ -1871,6 +1947,7 @@ export const annotate: {
    * @see {@link annotations} for reading merged annotations from a cause
    * @see {@link reasonAnnotations} for reading annotations from a single reason
    *
+   * @stability stable
    * @category annotations
    * @since 4.0.0
    */
@@ -1909,6 +1986,7 @@ export const annotate: {
    * @see {@link annotations} for reading merged annotations from a cause
    * @see {@link reasonAnnotations} for reading annotations from a single reason
    *
+   * @stability stable
    * @category annotations
    * @since 4.0.0
    */
@@ -1942,6 +2020,7 @@ export const annotate: {
  *
  * @see {@link annotations} — merged annotations from all reasons in a cause
  *
+ * @stability stable
  * @category annotations
  * @since 4.0.0
  */
@@ -1976,6 +2055,7 @@ export const reasonAnnotations: <E>(self: Reason<E>) => Context.Context<never> =
  *
  * @see {@link reasonAnnotations} — annotations from a single reason
  *
+ * @stability stable
  * @category annotations
  * @since 4.0.0
  */
@@ -1999,6 +2079,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
  *
+ * @stability stable
  * @category services
  * @since 4.0.0
  */
@@ -2021,6 +2102,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
  *
+ * @stability stable
  * @category services
  * @since 4.0.0
  */