effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Exit.ts

@@ -28,7 +28,7 @@
  *
  * - A `Failure` wraps a `Cause<E>`, not a bare `E`. Use Cause utilities to drill into it.
  * - {@link mapError} and {@link mapBoth} only transform typed errors (Fail reasons in the Cause). If the Cause contains only defects or interruptions, the original failure passes through unchanged.
- * - Filter-based APIs ({@link filterSuccess}, {@link filterValue}, etc.) return `Filter.fail` markers for pipeline composition. They are not `Option` values or Effect failures.
+ * - Filter-based APIs ({@link filterSuccess}, {@link filterValue}, etc.) return `Result.fail` values for pipeline composition. They are not `Option` values or Effect failures.
  * - {@link findError} and {@link findDefect} return only the first matching reason from the Cause.
  *
  * ## Quickstart
@@ -71,8 +71,8 @@ const TypeId = core.ExitTypeId
  *
  * **When to use**
  *
- * - Use when you need to synchronously inspect whether a computation succeeded or failed
- * - Use as an alternative to try/catch for Effect-based code
+ * Use when you need to synchronously inspect whether an Effect computation
+ * succeeded or failed.
  *
  * **Details**
  *
@@ -108,12 +108,21 @@ export type Exit<A, E = never> = Success<A, E> | Failure<A, E>
 /**
  * Namespace containing helper types shared by `Exit` values.
  *
+ * **When to use**
+ *
+ * Use to reference helper types that describe the shared structure of `Exit`
+ * values.
+ *
  * @since 2.0.0
  */
 export declare namespace Exit {
   /**
    * Base interface shared by both Success and Failure.
    *
+   * **When to use**
+   *
+   * Use to describe the common protocol implemented by every `Exit` value.
+   *
    * **Details**
    *
    * Every Exit is also an Effect, so you can yield it in `Effect.gen`.
@@ -131,7 +140,7 @@ export declare namespace Exit {
  *
  * **When to use**
  *
- * - Use {@link isSuccess} to narrow an `Exit` to `Success`
+ * Use when you use {@link isSuccess} to narrow an `Exit` to `Success`
  * - Access the value via the `value` property after narrowing
  *
  * **Example** (Accessing the success value)
@@ -163,7 +172,7 @@ export interface Success<out A, out E = never> extends Exit.Proto<A, E> {
  *
  * **When to use**
  *
- * - Use {@link isFailure} to narrow an `Exit` to `Failure`
+ * Use when you use {@link isFailure} to narrow an `Exit` to `Failure`
  * - Access the cause via the `cause` property after narrowing
  *
  * **Details**
@@ -199,7 +208,7 @@ export interface Failure<out A, out E> extends Exit.Proto<A, E> {
  *
  * **When to use**
  *
- * - Use to validate unknown values at system boundaries
+ * Use to validate unknown values at system boundaries
  * - Works as a type guard, narrowing to `Exit<unknown, unknown>`
  *
  * **Details**
@@ -230,7 +239,7 @@ export const isExit: (u: unknown) => u is Exit<unknown, unknown> = core.isExit
  *
  * **When to use**
  *
- * - Use to wrap a known success value into an Exit
+ * Use to wrap a known success value into an Exit
  * - Use when constructing test data or returning explicit results
  *
  * **Details**
@@ -248,7 +257,7 @@ export const isExit: (u: unknown) => u is Exit<unknown, unknown> = core.isExit
  * ```
  *
  * @see {@link fail} to create a failed Exit
- * @see {@link void} for a pre-allocated success with no value
+ * @see {@link void_ void} for a pre-allocated success with no value
  *
  * @category constructors
  * @since 2.0.0
@@ -260,7 +269,7 @@ export const succeed: <A>(a: A) => Exit<A> = core.exitSucceed
  *
  * **When to use**
  *
- * - Use when you already have a `Cause<E>` and want to wrap it in an Exit
+ * Use when you already have a `Cause<E>` and want to wrap it in an Exit
  * - Use for advanced error handling where you need full control over the Cause structure
  *
  * **Details**
@@ -291,7 +300,7 @@ export const failCause: <E>(cause: Cause.Cause<E>) => Exit<never, E> = core.exit
  *
  * **When to use**
  *
- * - Use for expected, recoverable failures
+ * Use when you need expected, recoverable failures
  *
  * **Details**
  *
@@ -322,7 +331,7 @@ export const fail: <E>(e: E) => Exit<never, E> = core.exitFail
  *
  * **When to use**
  *
- * - Use for unexpected, unrecoverable errors that should not appear in the typed error channel
+ * Use when you need unexpected, unrecoverable errors that should not appear in the typed error channel
  *
  * **Details**
  *
@@ -353,7 +362,7 @@ export const die: (defect: unknown) => Exit<never> = core.exitDie
  *
  * **When to use**
  *
- * - Use to signal that a fiber was interrupted
+ * Use to signal that a fiber was interrupted
  *
  * **Details**
  *
@@ -385,7 +394,7 @@ export {
    *
    * **When to use**
    *
-   * - Use when you need a success Exit but do not care about the value
+   * Use when you need a success Exit but do not care about the value
    * - Avoids allocating a new Exit for a common case
    *
    * **Details**
@@ -415,7 +424,7 @@ export {
  *
  * **When to use**
  *
- * - Use as a type guard to narrow `Exit<A, E>` to `Success<A, E>`
+ * Use as a type guard to narrow `Exit<A, E>` to `Success<A, E>`
  * - After narrowing, the `value` property becomes accessible
  *
  * **Example** (Narrowing to Success)
@@ -443,7 +452,7 @@ export const isSuccess: <A, E>(self: Exit<A, E>) => self is Success<A, E> = effe
  *
  * **When to use**
  *
- * - Use as a type guard to narrow `Exit<A, E>` to `Failure<A, E>`
+ * Use as a type guard to narrow `Exit<A, E>` to `Failure<A, E>`
  * - After narrowing, the `cause` property becomes accessible
  *
  * **Example** (Narrowing to Failure)
@@ -471,7 +480,7 @@ export const isFailure: <A, E>(self: Exit<A, E>) => self is Failure<A, E> = effe
  *
  * **When to use**
  *
- * - Use to distinguish typed failures from defects or interruptions
+ * Use to distinguish typed failures from defects or interruptions
  *
  * **Details**
  *
@@ -503,7 +512,7 @@ export const hasFails: <A, E>(self: Exit<A, E>) => self is Failure<A, E> = effec
  *
  * **When to use**
  *
- * - Use to check for unexpected errors
+ * Use to check for unexpected errors
  *
  * **Details**
  *
@@ -535,7 +544,7 @@ export const hasDies: <A, E>(self: Exit<A, E>) => self is Failure<A, E> = effect
  *
  * **When to use**
  *
- * - Use to check if a fiber was interrupted
+ * Use to check if a fiber was interrupted
  *
  * **Details**
  *
@@ -563,31 +572,38 @@ export const hasDies: <A, E>(self: Exit<A, E>) => self is Failure<A, E> = effect
 export const hasInterrupts: <A, E>(self: Exit<A, E>) => self is Failure<A, E> = effect.exitHasInterrupts
 
 /**
- * Extracts the Success variant from an Exit for use in filter pipelines.
+ * Extracts the Success variant from an Exit as a Result.
  *
  * **When to use**
  *
- * - Use with Filter-based composition
+ * Use when composing Exit checks with `Filter` or other `Result`-based
+ * filtering APIs.
  *
  * **Details**
  *
- * - Returns the `Success<A>` if the Exit succeeded, or a `Filter.fail` wrapping the Failure otherwise
+ * Returns `Result.succeed(success)` when the Exit is a Success, or
+ * `Result.fail(failure)` with the original Failure otherwise.
+ *
+ * **Gotchas**
+ *
+ * This is not an `Option` accessor or an Effect failure. A failed extraction is
+ * represented as data in the `Result` failure channel.
  *
  * **Example** (Filtering for success)
  *
  * ```ts
- * import { Exit, Filter } from "effect"
+ * import { Exit, Result } from "effect"
  *
  * const exit = Exit.succeed(42)
  * const result = Exit.filterSuccess(exit)
- * // If exit is a success, result is the Success object
- * // If exit is a failure, result is a Filter.fail marker
+ *
+ * console.log(Result.isSuccess(result)) // true
  * ```
  *
  * @see {@link filterFailure} for the inverse
  * @see {@link filterValue} to extract the raw value instead of the Success object
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const filterSuccess: <A, E>(
@@ -595,107 +611,130 @@ export const filterSuccess: <A, E>(
 ) => Result.Result<Success<A>, Failure<never, E>> = effect.exitFilterSuccess
 
 /**
- * Extracts the success value from an Exit for use in filter pipelines.
+ * Extracts the success value from an Exit as a Result.
  *
  * **When to use**
  *
- * - Use with Filter-based composition when you want the raw value, not the Success wrapper
+ * Use when composing Exit checks with `Filter` or other `Result`-based
+ * filtering APIs and you want the raw success value rather than the Success
+ * wrapper.
  *
  * **Details**
  *
- * - Returns the value `A` if the Exit succeeded, or a `Filter.fail` wrapping the Failure otherwise
+ * Returns `Result.succeed(value)` when the Exit is a Success, or
+ * `Result.fail(failure)` with the original Failure otherwise.
+ *
+ * **Gotchas**
+ *
+ * This is not an `Option` accessor or an Effect failure. A failed extraction is
+ * represented as data in the `Result` failure channel.
  *
  * **Example** (Filtering for the value)
  *
  * ```ts
- * import { Exit, Filter } from "effect"
+ * import { Exit, Result } from "effect"
  *
  * const exit = Exit.succeed(42)
  * const result = Exit.filterValue(exit)
- * // If exit is a success, result is 42
- * // If exit is a failure, result is a Filter.fail marker
+ *
+ * console.log(Result.isSuccess(result) && result.success) // 42
  * ```
  *
  * @see {@link filterSuccess} to get the full Success object
  * @see {@link getSuccess} to get the value as an Option instead
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const filterValue: <A, E>(self: Exit<A, E>) => Result.Result<A, Failure<never, E>> = effect.exitFilterValue
 
 /**
- * Extracts the Failure variant from an Exit for use in filter pipelines.
+ * Extracts the Failure variant from an Exit as a Result.
  *
  * **When to use**
  *
- * - Use with Filter-based composition
+ * Use when composing Exit checks with `Filter` or other `Result`-based
+ * filtering APIs.
  *
  * **Details**
  *
- * - Returns the `Failure<never, E>` if the Exit failed, or a `Filter.fail` wrapping the Success otherwise
+ * Returns `Result.succeed(failure)` when the Exit is a Failure, or
+ * `Result.fail(success)` with the original Success otherwise.
+ *
+ * **Gotchas**
+ *
+ * This is not an `Option` accessor or an Effect failure. A failed extraction is
+ * represented as data in the `Result` failure channel.
  *
  * **Example** (Filtering for failure)
  *
  * ```ts
- * import { Exit, Filter } from "effect"
+ * import { Exit, Result } from "effect"
  *
  * const exit = Exit.fail("err")
  * const result = Exit.filterFailure(exit)
- * // If exit is a failure, result is the Failure object
- * // If exit is a success, result is a Filter.fail marker
+ *
+ * console.log(Result.isSuccess(result)) // true
  * ```
  *
  * @see {@link filterSuccess} for the inverse
  * @see {@link filterCause} to extract the Cause directly
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const filterFailure: <A, E>(self: Exit<A, E>) => Result.Result<Failure<never, E>, Success<A>> =
   effect.exitFilterFailure
 
 /**
- * Extracts the Cause from a failed Exit for use in filter pipelines.
+ * Extracts the Cause from a failed Exit as a Result.
  *
  * **When to use**
  *
- * - Use with Filter-based composition when you want the raw Cause, not the Failure wrapper
+ * Use when composing Exit checks with `Filter` or other `Result`-based
+ * filtering APIs and you want the raw Cause rather than the Failure wrapper.
  *
  * **Details**
  *
- * - Returns the `Cause<E>` if the Exit failed, or a `Filter.fail` wrapping the Success otherwise
+ * Returns `Result.succeed(cause)` when the Exit is a Failure, or
+ * `Result.fail(success)` with the original Success otherwise.
+ *
+ * **Gotchas**
+ *
+ * This is not an `Option` accessor or an Effect failure. A failed extraction is
+ * represented as data in the `Result` failure channel.
  *
  * **Example** (Filtering for the cause)
  *
  * ```ts
- * import { Exit, Filter } from "effect"
+ * import { Exit, Result } from "effect"
  *
  * const exit = Exit.fail("err")
  * const result = Exit.filterCause(exit)
- * // If exit is a failure, result is the Cause
- * // If exit is a success, result is a Filter.fail marker
+ *
+ * console.log(Result.isSuccess(result)) // true
  * ```
  *
  * @see {@link filterFailure} to get the full Failure object
  * @see {@link getCause} to get the Cause as an Option instead
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const filterCause: <A, E>(self: Exit<A, E>) => Result.Result<Cause.Cause<E>, Success<A>> = effect.exitFilterCause
 
 /**
- * Extracts the first typed error value from a failed Exit for use in filter
- * pipelines.
+ * Extracts the first typed error value from a failed Exit as a Result.
  *
  * **When to use**
  *
- * - Use when you need just the first `E` from the Cause
+ * Use when composing Exit checks with `Filter` or other `Result`-based
+ * filtering APIs and you only need the first typed error in the Cause.
  *
  * **Details**
  *
- * - Returns the error `E` if one exists, or `Filter.fail` wrapping the original Exit if the Exit has no typed errors
+ * Returns `Result.succeed(error)` when the Cause contains a Fail reason, or
+ * `Result.fail(exit)` with the original Exit otherwise.
  *
  * **Gotchas**
  *
@@ -705,35 +744,37 @@ export const filterCause: <A, E>(self: Exit<A, E>) => Result.Result<Cause.Cause<
  * **Example** (Finding the first typed error)
  *
  * ```ts
- * import { Exit, Filter } from "effect"
+ * import { Exit, Result } from "effect"
  *
  * const exit = Exit.fail("not found")
  * const result = Exit.findError(exit)
- * // result is "not found"
+ * console.log(Result.isSuccess(result) && result.success) // "not found"
  *
  * const defect = Exit.die(new Error("bug"))
  * const noError = Exit.findError(defect)
- * // noError is a Filter.fail marker
+ * console.log(Result.isFailure(noError)) // true
  * ```
  *
  * @see {@link findErrorOption} to get the error as an Option instead
  * @see {@link findDefect} to find defects instead
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const findError: <A, E>(input: Exit<A, E>) => Result.Result<E, Exit<A, E>> = effect.exitFindError
 
 /**
- * Extracts the first defect from a failed Exit for use in filter pipelines.
+ * Extracts the first defect from a failed Exit as a Result.
  *
  * **When to use**
  *
- * - Use when you need to inspect unexpected errors
+ * Use when composing Exit checks with `Filter` or other `Result`-based
+ * filtering APIs and you only need the first defect in the Cause.
  *
  * **Details**
  *
- * - Returns the defect value if one exists, or `Filter.fail` wrapping the original Exit if the Exit has no defects
+ * Returns `Result.succeed(defect)` when the Cause contains a Die reason, or
+ * `Result.fail(exit)` with the original Exit otherwise.
  *
  * **Gotchas**
  *
@@ -743,21 +784,21 @@ export const findError: <A, E>(input: Exit<A, E>) => Result.Result<E, Exit<A, E>
  * **Example** (Finding the first defect)
  *
  * ```ts
- * import { Exit, Filter } from "effect"
+ * import { Exit, Result } from "effect"
  *
  * const exit = Exit.die("boom")
  * const result = Exit.findDefect(exit)
- * // result is "boom"
+ * console.log(Result.isSuccess(result) && result.success) // "boom"
  *
  * const typed = Exit.fail("err")
  * const noDefect = Exit.findDefect(typed)
- * // noDefect is a Filter.fail marker
+ * console.log(Result.isFailure(noDefect)) // true
  * ```
  *
  * @see {@link findError} to find typed errors instead
  * @see {@link hasDies} to check for defects without extracting them
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const findDefect: <A, E>(input: Exit<A, E>) => Result.Result<unknown, Exit<A, E>> = effect.exitFindDefect
@@ -767,7 +808,7 @@ export const findDefect: <A, E>(input: Exit<A, E>) => Result.Result<unknown, Exi
  *
  * **When to use**
  *
- * - Use for exhaustive handling of both outcomes
+ * Use when you need exhaustive handling of both outcomes
  *
  * **Details**
  *
@@ -801,7 +842,7 @@ export const match: {
    *
    * **When to use**
    *
-   * - Use for exhaustive handling of both outcomes
+   * Use when you need exhaustive handling of both outcomes
    *
    * **Details**
    *
@@ -840,7 +881,7 @@ export const match: {
    *
    * **When to use**
    *
-   * - Use for exhaustive handling of both outcomes
+   * Use when you need exhaustive handling of both outcomes
    *
    * **Details**
    *
@@ -882,7 +923,7 @@ export const match: {
  *
  * **When to use**
  *
- * - Use to apply a transformation to the value inside a successful Exit
+ * Use to apply a transformation to the value inside a successful Exit
  *
  * **Details**
  *
@@ -913,7 +954,7 @@ export const map: {
    *
    * **When to use**
    *
-   * - Use to apply a transformation to the value inside a successful Exit
+   * Use to apply a transformation to the value inside a successful Exit
    *
    * **Details**
    *
@@ -944,7 +985,7 @@ export const map: {
    *
    * **When to use**
    *
-   * - Use to apply a transformation to the value inside a successful Exit
+   * Use to apply a transformation to the value inside a successful Exit
    *
    * **Details**
    *
@@ -977,7 +1018,7 @@ export const map: {
  *
  * **When to use**
  *
- * - Use to remap typed errors while preserving the Exit structure
+ * Use to remap typed errors while preserving the Exit structure
  *
  * **Details**
  *
@@ -1015,7 +1056,7 @@ export const mapError: {
    *
    * **When to use**
    *
-   * - Use to remap typed errors while preserving the Exit structure
+   * Use to remap typed errors while preserving the Exit structure
    *
    * **Details**
    *
@@ -1053,7 +1094,7 @@ export const mapError: {
    *
    * **When to use**
    *
-   * - Use to remap typed errors while preserving the Exit structure
+   * Use to remap typed errors while preserving the Exit structure
    *
    * **Details**
    *
@@ -1093,7 +1134,7 @@ export const mapError: {
  *
  * **When to use**
  *
- * - Use when you need to remap both channels in one step
+ * Use when you need to remap both channels in one step
  *
  * **Details**
  *
@@ -1135,7 +1176,7 @@ export const mapBoth: {
    *
    * **When to use**
    *
-   * - Use when you need to remap both channels in one step
+   * Use when you need to remap both channels in one step
    *
    * **Details**
    *
@@ -1179,7 +1220,7 @@ export const mapBoth: {
    *
    * **When to use**
    *
-   * - Use when you need to remap both channels in one step
+   * Use when you need to remap both channels in one step
    *
    * **Details**
    *
@@ -1226,7 +1267,7 @@ export const mapBoth: {
  *
  * **When to use**
  *
- * - Use when you only care about whether the computation succeeded or failed, not the value
+ * Use when you only care about whether the computation succeeded or failed, not the value
  *
  * **Details**
  *
@@ -1244,7 +1285,7 @@ export const mapBoth: {
  * console.log(Exit.isSuccess(voided)) // true
  * ```
  *
- * @see {@link void} for a pre-allocated void success
+ * @see {@link void_ void} for a pre-allocated void success
  * @see {@link asVoidAll} to combine multiple exits into a single void Exit
  *
  * @category combinators
@@ -1257,7 +1298,7 @@ export const asVoid: <A, E>(self: Exit<A, E>) => Exit<void, E> = effect.exitAsVo
  *
  * **When to use**
  *
- * - Use to validate that all exits in a collection succeeded
+ * Use to validate that all exits in a collection succeeded
  *
  * **Details**
  *
@@ -1293,7 +1334,7 @@ export const asVoidAll: <I extends Iterable<Exit<any, any>>>(
  *
  * **When to use**
  *
- * - Use when you want to optionally extract the value without pattern matching
+ * Use when you want to optionally extract the value without pattern matching
  *
  * **Details**
  *
@@ -1311,7 +1352,7 @@ export const asVoidAll: <I extends Iterable<Exit<any, any>>>(
  * @see {@link getCause} to extract the Cause of a failure
  * @see {@link filterValue} for filter-pipeline usage
  *
- * @category Accessors
+ * @category accessors
  * @since 4.0.0
  */
 export const getSuccess: <A, E>(self: Exit<A, E>) => Option<A> = effect.exitGetSuccess
@@ -1321,7 +1362,7 @@ export const getSuccess: <A, E>(self: Exit<A, E>) => Option<A> = effect.exitGetS
  *
  * **When to use**
  *
- * - Use when you want to optionally inspect the failure cause
+ * Use when you want to optionally inspect the failure cause
  *
  * **Details**
  *
@@ -1339,7 +1380,7 @@ export const getSuccess: <A, E>(self: Exit<A, E>) => Option<A> = effect.exitGetS
  * @see {@link getSuccess} to extract the success value
  * @see {@link filterCause} for filter-pipeline usage
  *
- * @category Accessors
+ * @category accessors
  * @since 4.0.0
  */
 export const getCause: <A, E>(self: Exit<A, E>) => Option<Cause.Cause<E>> = effect.exitGetCause
@@ -1349,13 +1390,18 @@ export const getCause: <A, E>(self: Exit<A, E>) => Option<Cause.Cause<E>> = effe
  *
  * **When to use**
  *
- * - Use when you want to optionally extract a typed error without dealing with the full Cause
+ * Use when you want to optionally extract a typed error without dealing with the full Cause
  *
  * **Details**
  *
  * - Returns `Option.some(error)` if the Cause contains a Fail reason, `Option.none()` otherwise
  * - Returns `Option.none()` for successes, defect-only failures, and interrupt-only failures
  *
+ * **Gotchas**
+ *
+ * Only finds the first Fail reason. If the Cause has multiple typed errors,
+ * the rest are ignored.
+ *
  * **Example** (Getting the first error)
  *
  * ```ts
@@ -1369,7 +1415,7 @@ export const getCause: <A, E>(self: Exit<A, E>) => Option<Cause.Cause<E>> = effe
  * @see {@link findError} for filter-pipeline usage
  * @see {@link getCause} to get the full Cause as an Option
  *
- * @category Accessors
+ * @category accessors
  * @since 4.0.0
  */
 export const findErrorOption: <A, E>(self: Exit<A, E>) => Option<E> = effect.exitFindErrorOption