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

package/src/Exit.ts

@@ -69,9 +69,13 @@ const TypeId = core.ExitTypeId
 /**
  * Represents the result of an Effect computation.
  *
+ * **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
  *
+ * **Details**
+ *
  * An `Exit<A, E>` is either:
  * - `Success<A, E>` containing a value of type `A`
  * - `Failure<A, E>` containing a `Cause<E>` describing why the computation failed
@@ -110,6 +114,8 @@ export declare namespace Exit {
   /**
    * Base interface shared by both Success and Failure.
    *
+   * **Details**
+   *
    * Every Exit is also an Effect, so you can yield it in `Effect.gen`.
    *
    * @category models
@@ -123,6 +129,8 @@ export declare namespace Exit {
 /**
  * A successful Exit containing a value.
  *
+ * **When to use**
+ *
  * - Use {@link isSuccess} to narrow an `Exit` to `Success`
  * - Access the value via the `value` property after narrowing
  *
@@ -153,8 +161,13 @@ export interface Success<out A, out E = never> extends Exit.Proto<A, E> {
 /**
  * A failed Exit containing a Cause.
  *
+ * **When to use**
+ *
  * - Use {@link isFailure} to narrow an `Exit` to `Failure`
  * - Access the cause via the `cause` property after narrowing
+ *
+ * **Details**
+ *
  * - The `Cause<E>` may contain typed errors, defects, or interruptions
  *
  * **Example** (Accessing the failure cause)
@@ -184,9 +197,13 @@ export interface Failure<out A, out E> extends Exit.Proto<A, E> {
 /**
  * Tests whether an unknown value is an Exit.
  *
+ * **When to use**
+ *
  * - Use to validate unknown values at system boundaries
  * - Works as a type guard, narrowing to `Exit<unknown, unknown>`
  *
+ * **Details**
+ *
  * Does not inspect the contents of the Exit. Returns `true` for both Success
  * and Failure exits.
  *
@@ -211,9 +228,13 @@ export const isExit: (u: unknown) => u is Exit<unknown, unknown> = core.isExit
 /**
  * Creates a successful Exit containing the given value.
  *
+ * **When to use**
+ *
  * - Use to wrap a known success value into an Exit
  * - Use when constructing test data or returning explicit results
  *
+ * **Details**
+ *
  * Returns a `Success<A>` with the provided value. Does not perform any
  * computation.
  *
@@ -237,9 +258,13 @@ export const succeed: <A>(a: A) => Exit<A> = core.exitSucceed
 /**
  * Creates a failed Exit from a Cause.
  *
+ * **When to use**
+ *
  * - 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**
+ *
  * Returns a `Failure<never, E>`. If you only have an error value, use
  * {@link fail} instead.
  *
@@ -264,7 +289,12 @@ export const failCause: <E>(cause: Cause.Cause<E>) => Exit<never, E> = core.exit
 /**
  * Creates a failed Exit from a typed error value.
  *
+ * **When to use**
+ *
  * - Use for expected, recoverable failures
+ *
+ * **Details**
+ *
  * - The error is wrapped in a `Cause.Fail` internally
  *
  * Returns a `Failure<never, E>`.
@@ -290,7 +320,12 @@ export const fail: <E>(e: E) => Exit<never, E> = core.exitFail
 /**
  * Creates a failed Exit from a defect (unexpected error).
  *
+ * **When to use**
+ *
  * - Use for unexpected, unrecoverable errors that should not appear in the typed error channel
+ *
+ * **Details**
+ *
  * - The defect is wrapped in a `Cause.Die` internally
  *
  * Returns a `Failure<never>` with `E = never`, since defects do not appear in
@@ -316,7 +351,12 @@ export const die: (defect: unknown) => Exit<never> = core.exitDie
 /**
  * Creates a failed Exit representing fiber interruption.
  *
+ * **When to use**
+ *
  * - Use to signal that a fiber was interrupted
+ *
+ * **Details**
+ *
  * - Optionally pass a fiber ID to identify which fiber was interrupted
  *
  * Returns a `Failure<never>` with an `Interrupt` cause.
@@ -343,9 +383,13 @@ export {
   /**
    * A pre-allocated successful Exit with a `void` value.
    *
+   * **When to use**
+   *
    * - Use when you need a success Exit but do not care about the value
    * - Avoids allocating a new Exit for a common case
    *
+   * **Details**
+   *
    * Equivalent to `Exit.succeed(undefined)` but shared as a single instance.
    *
    * **Example** (Using the void Exit)
@@ -369,6 +413,8 @@ export {
 /**
  * Tests whether an Exit is a Success.
  *
+ * **When to use**
+ *
  * - Use as a type guard to narrow `Exit<A, E>` to `Success<A, E>`
  * - After narrowing, the `value` property becomes accessible
  *
@@ -395,6 +441,8 @@ export const isSuccess: <A, E>(self: Exit<A, E>) => self is Success<A, E> = effe
 /**
  * Tests whether an Exit is a Failure.
  *
+ * **When to use**
+ *
  * - Use as a type guard to narrow `Exit<A, E>` to `Failure<A, E>`
  * - After narrowing, the `cause` property becomes accessible
  *
@@ -421,7 +469,12 @@ export const isFailure: <A, E>(self: Exit<A, E>) => self is Failure<A, E> = effe
 /**
  * Tests whether a failed Exit contains typed errors (Fail reasons).
  *
+ * **When to use**
+ *
  * - Use to distinguish typed failures from defects or interruptions
+ *
+ * **Details**
+ *
  * - Returns `false` for successful exits
  *
  * Only checks for `Fail` reasons in the Cause. A Cause with only `Die` or
@@ -448,7 +501,12 @@ export const hasFails: <A, E>(self: Exit<A, E>) => self is Failure<A, E> = effec
 /**
  * Tests whether a failed Exit contains defects (Die reasons).
  *
+ * **When to use**
+ *
  * - Use to check for unexpected errors
+ *
+ * **Details**
+ *
  * - Returns `false` for successful exits
  *
  * Only checks for `Die` reasons in the Cause. A Cause with only `Fail` or
@@ -475,7 +533,12 @@ export const hasDies: <A, E>(self: Exit<A, E>) => self is Failure<A, E> = effect
 /**
  * Tests whether a failed Exit contains interruptions (Interrupt reasons).
  *
+ * **When to use**
+ *
  * - Use to check if a fiber was interrupted
+ *
+ * **Details**
+ *
  * - Returns `false` for successful exits
  *
  * Only checks for `Interrupt` reasons in the Cause. A Cause with only `Fail`
@@ -502,7 +565,12 @@ export const hasInterrupts: <A, E>(self: Exit<A, E>) => self is Failure<A, E> =
 /**
  * Extracts the Success variant from an Exit for use in filter pipelines.
  *
+ * **When to use**
+ *
  * - Use with Filter-based composition
+ *
+ * **Details**
+ *
  * - Returns the `Success<A>` if the Exit succeeded, or a `Filter.fail` wrapping the Failure otherwise
  *
  * **Example** (Filtering for success)
@@ -529,7 +597,12 @@ export const filterSuccess: <A, E>(
 /**
  * Extracts the success value from an Exit for use in filter pipelines.
  *
+ * **When to use**
+ *
  * - Use with Filter-based composition when you want the raw value, not the Success wrapper
+ *
+ * **Details**
+ *
  * - Returns the value `A` if the Exit succeeded, or a `Filter.fail` wrapping the Failure otherwise
  *
  * **Example** (Filtering for the value)
@@ -554,7 +627,12 @@ export const filterValue: <A, E>(self: Exit<A, E>) => Result.Result<A, Failure<n
 /**
  * Extracts the Failure variant from an Exit for use in filter pipelines.
  *
+ * **When to use**
+ *
  * - Use with Filter-based composition
+ *
+ * **Details**
+ *
  * - Returns the `Failure<never, E>` if the Exit failed, or a `Filter.fail` wrapping the Success otherwise
  *
  * **Example** (Filtering for failure)
@@ -580,7 +658,12 @@ export const filterFailure: <A, E>(self: Exit<A, E>) => Result.Result<Failure<ne
 /**
  * Extracts the Cause from a failed Exit for use in filter pipelines.
  *
+ * **When to use**
+ *
  * - Use with Filter-based composition when you want the raw Cause, not the Failure wrapper
+ *
+ * **Details**
+ *
  * - Returns the `Cause<E>` if the Exit failed, or a `Filter.fail` wrapping the Success otherwise
  *
  * **Example** (Filtering for the cause)
@@ -606,9 +689,16 @@ export const filterCause: <A, E>(self: Exit<A, E>) => Result.Result<Cause.Cause<
  * Extracts the first typed error value from a failed Exit for use in filter
  * pipelines.
  *
+ * **When to use**
+ *
  * - Use when you need just the first `E` from the Cause
+ *
+ * **Details**
+ *
  * - Returns the error `E` if one exists, or `Filter.fail` wrapping the original Exit if the Exit has no typed errors
  *
+ * **Gotchas**
+ *
  * Only finds the first Fail reason. If the Cause has multiple errors, the rest
  * are ignored.
  *
@@ -637,9 +727,16 @@ export const findError: <A, E>(input: Exit<A, E>) => Result.Result<E, Exit<A, E>
 /**
  * Extracts the first defect from a failed Exit for use in filter pipelines.
  *
+ * **When to use**
+ *
  * - Use when you need to inspect unexpected errors
+ *
+ * **Details**
+ *
  * - Returns the defect value if one exists, or `Filter.fail` wrapping the original Exit if the Exit has no defects
  *
+ * **Gotchas**
+ *
  * Only finds the first Die reason. If the Cause has multiple defects, the rest
  * are ignored.
  *
@@ -668,7 +765,12 @@ export const findDefect: <A, E>(input: Exit<A, E>) => Result.Result<unknown, Exi
 /**
  * Pattern matches on an Exit, handling both success and failure cases.
  *
+ * **When to use**
+ *
  * - Use for exhaustive handling of both outcomes
+ *
+ * **Details**
+ *
  * - Calls `onSuccess` with the value if the Exit is a Success
  * - Calls `onFailure` with the Cause if the Exit is a Failure
  *
@@ -697,7 +799,12 @@ export const match: {
   /**
    * Pattern matches on an Exit, handling both success and failure cases.
    *
+   * **When to use**
+   *
    * - Use for exhaustive handling of both outcomes
+   *
+   * **Details**
+   *
    * - Calls `onSuccess` with the value if the Exit is a Success
    * - Calls `onFailure` with the Cause if the Exit is a Failure
    *
@@ -731,7 +838,12 @@ export const match: {
   /**
    * Pattern matches on an Exit, handling both success and failure cases.
    *
+   * **When to use**
+   *
    * - Use for exhaustive handling of both outcomes
+   *
+   * **Details**
+   *
    * - Calls `onSuccess` with the value if the Exit is a Success
    * - Calls `onFailure` with the Cause if the Exit is a Failure
    *
@@ -768,7 +880,12 @@ export const match: {
 /**
  * Transforms the success value of an Exit using the given function.
  *
+ * **When to use**
+ *
  * - Use to apply a transformation to the value inside a successful Exit
+ *
+ * **Details**
+ *
  * - Has no effect on failures, which pass through unchanged
  *
  * Allocates a new Exit if successful. Does not mutate the input.
@@ -794,7 +911,12 @@ export const map: {
   /**
    * Transforms the success value of an Exit using the given function.
    *
+   * **When to use**
+   *
    * - Use to apply a transformation to the value inside a successful Exit
+   *
+   * **Details**
+   *
    * - Has no effect on failures, which pass through unchanged
    *
    * Allocates a new Exit if successful. Does not mutate the input.
@@ -820,7 +942,12 @@ export const map: {
   /**
    * Transforms the success value of an Exit using the given function.
    *
+   * **When to use**
+   *
    * - Use to apply a transformation to the value inside a successful Exit
+   *
+   * **Details**
+   *
    * - Has no effect on failures, which pass through unchanged
    *
    * Allocates a new Exit if successful. Does not mutate the input.
@@ -848,13 +975,22 @@ export const map: {
 /**
  * Transforms the typed error of a failed Exit using the given function.
  *
+ * **When to use**
+ *
  * - Use to remap typed errors while preserving the Exit structure
+ *
+ * **Details**
+ *
  * - Has no effect on successes, which pass through unchanged
- * - Only transforms typed errors (Fail reasons). If the Cause contains only defects or interruptions, the failure passes through unchanged.
  *
  * Allocates a new Exit if the error is transformed. Does not mutate the input.
  * Supports both curried and direct call styles.
  *
+ * **Gotchas**
+ *
+ * Only transforms typed errors (Fail reasons). If the Cause contains only
+ * defects or interruptions, the failure passes through unchanged.
+ *
  * **Example** (Mapping over an error)
  *
  * ```ts
@@ -877,13 +1013,22 @@ export const mapError: {
   /**
    * Transforms the typed error of a failed Exit using the given function.
    *
+   * **When to use**
+   *
    * - Use to remap typed errors while preserving the Exit structure
+   *
+   * **Details**
+   *
    * - Has no effect on successes, which pass through unchanged
-   * - Only transforms typed errors (Fail reasons). If the Cause contains only defects or interruptions, the failure passes through unchanged.
    *
    * Allocates a new Exit if the error is transformed. Does not mutate the input.
    * Supports both curried and direct call styles.
    *
+   * **Gotchas**
+   *
+   * Only transforms typed errors (Fail reasons). If the Cause contains only
+   * defects or interruptions, the failure passes through unchanged.
+   *
    * **Example** (Mapping over an error)
    *
    * ```ts
@@ -906,13 +1051,22 @@ export const mapError: {
   /**
    * Transforms the typed error of a failed Exit using the given function.
    *
+   * **When to use**
+   *
    * - Use to remap typed errors while preserving the Exit structure
+   *
+   * **Details**
+   *
    * - Has no effect on successes, which pass through unchanged
-   * - Only transforms typed errors (Fail reasons). If the Cause contains only defects or interruptions, the failure passes through unchanged.
    *
    * Allocates a new Exit if the error is transformed. Does not mutate the input.
    * Supports both curried and direct call styles.
    *
+   * **Gotchas**
+   *
+   * Only transforms typed errors (Fail reasons). If the Cause contains only
+   * defects or interruptions, the failure passes through unchanged.
+   *
    * **Example** (Mapping over an error)
    *
    * ```ts
@@ -937,14 +1091,23 @@ export const mapError: {
 /**
  * Transforms both the success value and typed error of an Exit.
  *
+ * **When to use**
+ *
  * - Use when you need to remap both channels in one step
+ *
+ * **Details**
+ *
  * - `onSuccess` transforms the value if the Exit is a Success
  * - `onFailure` transforms the typed error if the Exit is a Failure with a Fail reason
- * - If the Cause contains only defects or interruptions, the failure passes through unchanged
  *
  * Allocates a new Exit. Does not mutate the input.
  * Supports both curried and direct call styles.
  *
+ * **Gotchas**
+ *
+ * If the Cause contains only defects or interruptions, the failure passes
+ * through unchanged.
+ *
  * **Example** (Mapping both channels)
  *
  * ```ts
@@ -970,14 +1133,23 @@ export const mapBoth: {
   /**
    * Transforms both the success value and typed error of an Exit.
    *
+   * **When to use**
+   *
    * - Use when you need to remap both channels in one step
+   *
+   * **Details**
+   *
    * - `onSuccess` transforms the value if the Exit is a Success
    * - `onFailure` transforms the typed error if the Exit is a Failure with a Fail reason
-   * - If the Cause contains only defects or interruptions, the failure passes through unchanged
    *
    * Allocates a new Exit. Does not mutate the input.
    * Supports both curried and direct call styles.
    *
+   * **Gotchas**
+   *
+   * If the Cause contains only defects or interruptions, the failure passes
+   * through unchanged.
+   *
    * **Example** (Mapping both channels)
    *
    * ```ts
@@ -1005,14 +1177,23 @@ export const mapBoth: {
   /**
    * Transforms both the success value and typed error of an Exit.
    *
+   * **When to use**
+   *
    * - Use when you need to remap both channels in one step
+   *
+   * **Details**
+   *
    * - `onSuccess` transforms the value if the Exit is a Success
    * - `onFailure` transforms the typed error if the Exit is a Failure with a Fail reason
-   * - If the Cause contains only defects or interruptions, the failure passes through unchanged
    *
    * Allocates a new Exit. Does not mutate the input.
    * Supports both curried and direct call styles.
    *
+   * **Gotchas**
+   *
+   * If the Cause contains only defects or interruptions, the failure passes
+   * through unchanged.
+   *
    * **Example** (Mapping both channels)
    *
    * ```ts
@@ -1043,7 +1224,12 @@ export const mapBoth: {
 /**
  * Discards the success value of an Exit, replacing it with `void`.
  *
+ * **When to use**
+ *
  * - Use when you only care about whether the computation succeeded or failed, not the value
+ *
+ * **Details**
+ *
  * - Failures pass through unchanged
  *
  * Allocates a new Exit if successful. Does not mutate the input.
@@ -1069,7 +1255,12 @@ export const asVoid: <A, E>(self: Exit<A, E>) => Exit<void, E> = effect.exitAsVo
 /**
  * Combines multiple Exit values into a single `Exit<void, E>`.
  *
+ * **When to use**
+ *
  * - Use to validate that all exits in a collection succeeded
+ *
+ * **Details**
+ *
  * - If all exits are successful, returns a void success
  * - If any exit is a failure, returns a single failure with all error causes combined
  *
@@ -1100,7 +1291,12 @@ export const asVoidAll: <I extends Iterable<Exit<any, any>>>(
 /**
  * Returns the success value of an Exit as an Option.
  *
+ * **When to use**
+ *
  * - Use when you want to optionally extract the value without pattern matching
+ *
+ * **Details**
+ *
  * - Returns `Option.some(value)` for a Success, `Option.none()` for a Failure
  *
  * **Example** (Getting the success value)
@@ -1123,7 +1319,12 @@ export const getSuccess: <A, E>(self: Exit<A, E>) => Option<A> = effect.exitGetS
 /**
  * Returns the Cause of a failed Exit as an Option.
  *
+ * **When to use**
+ *
  * - Use when you want to optionally inspect the failure cause
+ *
+ * **Details**
+ *
  * - Returns `Option.some(cause)` for a Failure, `Option.none()` for a Success
  *
  * **Example** (Getting the failure cause)
@@ -1146,7 +1347,12 @@ export const getCause: <A, E>(self: Exit<A, E>) => Option<Cause.Cause<E>> = effe
 /**
  * Returns the first typed error from a failed Exit as an Option.
  *
+ * **When to use**
+ *
  * - 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
  *

package/src/Fiber.ts

@@ -268,6 +268,8 @@ export const join: <A, E>(self: Fiber<A, E>) => Effect<A, E> = effect.fiberJoin
 /**
  * Waits for all fibers to succeed and returns their values in input order.
  *
+ * **Details**
+ *
  * If any fiber fails, the returned `Effect` fails with that fiber's cause and
  * stops waiting for additional results. This does not interrupt the remaining
  * fibers.
@@ -630,6 +632,8 @@ export const getCurrent: () => Fiber<any, any> | undefined = effect.getCurrentFi
 /**
  * Links a fiber to a `Scope` and returns the same fiber.
  *
+ * **Details**
+ *
  * When the scope is closed, the fiber is interrupted. If the scope is already
  * closed, the fiber is interrupted immediately.
  *
@@ -640,6 +644,8 @@ export const runIn: {
   /**
    * Links a fiber to a `Scope` and returns the same fiber.
    *
+   * **Details**
+   *
    * When the scope is closed, the fiber is interrupted. If the scope is already
    * closed, the fiber is interrupted immediately.
    *
@@ -650,6 +656,8 @@ export const runIn: {
   /**
    * Links a fiber to a `Scope` and returns the same fiber.
    *
+   * **Details**
+   *
    * When the scope is closed, the fiber is interrupted. If the scope is already
    * closed, the fiber is interrupted immediately.
    *