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

package/dist/Result.d.ts

@@ -159,7 +159,14 @@ export interface Failure<out A, out E> extends Pipeable, Inspectable {
  * Iterator protocol used to yield a `Result` inside {@link gen}, returning the
  * success value type back to the generator.
  *
- * @category Generators
+ * **When to use**
+ *
+ * Use when defining or typing `[Symbol.iterator]()` for `Result` values so
+ * `yield*` can pass the success value type back into `Result.gen`.
+ *
+ * @see {@link gen} for writing generator-based `Result` code that consumes this iterator protocol
+ *
+ * @category generators
  * @since 4.0.0
  */
 export interface ResultIterator<T extends Result<any, any>> {
@@ -308,7 +315,7 @@ export declare namespace Result {
  * ```
  *
  * @see {@link fail} to create a Failure
- * @see {@link void} for a pre-built `Success<void>`
+ * @see {@link void_ void} for a pre-built `Success<void>`
  *
  * @category constructors
  * @since 4.0.0
@@ -317,9 +324,12 @@ export declare const succeed: <A>(right: A) => Result<A>;
 /**
  * Creates a `Result` holding a `Failure` value.
  *
+ * **When to use**
+ *
+ * Use to represent a failed computation with a typed failure value.
+ *
  * **Details**
  *
- * - Use when you want to represent a failed computation
  * - The success type `A` defaults to `never`
  * - Does not mutate input; allocates a new `Failure` wrapper
  *
@@ -385,6 +395,12 @@ export declare const failVoid: Result<never, void>;
 /**
  * Converts a possibly `null` or `undefined` value into a `Result`.
  *
+ * **When to use**
+ *
+ * Use when an input may be `null` or `undefined` and absence should be
+ * represented as a `Failure` while present values should remain available as
+ * `Success`.
+ *
  * **Details**
  *
  * - Non-nullish values become `Success<NonNullable<A>>`
@@ -414,6 +430,12 @@ export declare const fromNullishOr: {
     /**
      * Converts a possibly `null` or `undefined` value into a `Result`.
      *
+     * **When to use**
+     *
+     * Use when an input may be `null` or `undefined` and absence should be
+     * represented as a `Failure` while present values should remain available as
+     * `Success`.
+     *
      * **Details**
      *
      * - Non-nullish values become `Success<NonNullable<A>>`
@@ -443,6 +465,12 @@ export declare const fromNullishOr: {
     /**
      * Converts a possibly `null` or `undefined` value into a `Result`.
      *
+     * **When to use**
+     *
+     * Use when an input may be `null` or `undefined` and absence should be
+     * represented as a `Failure` while present values should remain available as
+     * `Success`.
+     *
      * **Details**
      *
      * - Non-nullish values become `Success<NonNullable<A>>`
@@ -473,6 +501,11 @@ export declare const fromNullishOr: {
 /**
  * Converts an `Option<A>` into a `Result<A, E>`.
  *
+ * **When to use**
+ *
+ * Use when an existing `Option` should become a `Result`, preserving `Some` as
+ * success and turning `None` into a caller-provided failure.
+ *
  * **Details**
  *
  * - `Some<A>` becomes `Success<A>`
@@ -493,8 +526,9 @@ export declare const fromNullishOr: {
  * // Output: { _tag: "Failure", failure: "missing", ... }
  * ```
  *
- * @see {@link getSuccess} / {@link getFailure} to convert back to Option
- * @see {@link fromNullishOr} to convert from nullable values
+ * @see {@link getSuccess} to extract the success value as an Option
+ * @see {@link getFailure} to extract the failure value as an Option
+ * @see {@link fromNullishOr} to build a Result from nullable values
  *
  * @category constructors
  * @since 2.0.0
@@ -503,6 +537,11 @@ export declare const fromOption: {
     /**
      * Converts an `Option<A>` into a `Result<A, E>`.
      *
+     * **When to use**
+     *
+     * Use when an existing `Option` should become a `Result`, preserving `Some` as
+     * success and turning `None` into a caller-provided failure.
+     *
      * **Details**
      *
      * - `Some<A>` becomes `Success<A>`
@@ -523,8 +562,9 @@ export declare const fromOption: {
      * // Output: { _tag: "Failure", failure: "missing", ... }
      * ```
      *
-     * @see {@link getSuccess} / {@link getFailure} to convert back to Option
-     * @see {@link fromNullishOr} to convert from nullable values
+     * @see {@link getSuccess} to extract the success value as an Option
+     * @see {@link getFailure} to extract the failure value as an Option
+     * @see {@link fromNullishOr} to build a Result from nullable values
      *
      * @category constructors
      * @since 2.0.0
@@ -533,6 +573,11 @@ export declare const fromOption: {
     /**
      * Converts an `Option<A>` into a `Result<A, E>`.
      *
+     * **When to use**
+     *
+     * Use when an existing `Option` should become a `Result`, preserving `Some` as
+     * success and turning `None` into a caller-provided failure.
+     *
      * **Details**
      *
      * - `Some<A>` becomes `Success<A>`
@@ -553,8 +598,9 @@ export declare const fromOption: {
      * // Output: { _tag: "Failure", failure: "missing", ... }
      * ```
      *
-     * @see {@link getSuccess} / {@link getFailure} to convert back to Option
-     * @see {@link fromNullishOr} to convert from nullable values
+     * @see {@link getSuccess} to extract the success value as an Option
+     * @see {@link getFailure} to extract the failure value as an Option
+     * @see {@link fromNullishOr} to build a Result from nullable values
      *
      * @category constructors
      * @since 2.0.0
@@ -606,9 +652,12 @@ try_ as try };
 /**
  * Tests whether a value is a `Result` (either `Success` or `Failure`).
  *
+ * **When to use**
+ *
+ * Use to validate unknown input before operating on it as a `Result`.
+ *
  * **Details**
  *
- * - Use to validate unknown input before operating on it as a `Result`
  * - Returns `true` for both `Success` and `Failure` variants
  * - Acts as a TypeScript type guard, narrowing to `Result<unknown, unknown>`
  *
@@ -633,6 +682,10 @@ export declare const isResult: (input: unknown) => input is Result<unknown, unkn
 /**
  * Checks whether a `Result` is a `Failure`.
  *
+ * **When to use**
+ *
+ * Use to narrow a known `Result` to the `Failure` variant.
+ *
  * **Details**
  *
  * - Acts as a TypeScript type guard, narrowing to `Failure<A, E>`
@@ -661,6 +714,10 @@ export declare const isFailure: <A, E>(self: Result<A, E>) => self is Failure<A,
 /**
  * Checks whether a `Result` is a `Success`.
  *
+ * **When to use**
+ *
+ * Use to narrow a known `Result` to the `Success` variant.
+ *
  * **Details**
  *
  * - Acts as a TypeScript type guard, narrowing to `Success<A, E>`
@@ -689,11 +746,14 @@ export declare const isSuccess: <A, E>(self: Result<A, E>) => self is Success<A,
 /**
  * Extracts the success value as an `Option`, discarding the failure.
  *
+ * **When to use**
+ *
+ * Use to extract only the success value and discard failure information.
+ *
  * **Details**
  *
  * - `Success<A>` becomes `Some<A>`
  * - `Failure<E>` becomes `None`
- * - Use when you only care about the success case and want to discard error info
  *
  * **Example** (Extracting the success as an Option)
  *
@@ -717,11 +777,14 @@ export declare const getSuccess: <A, E>(self: Result<A, E>) => Option<A>;
 /**
  * Extracts the failure value as an `Option`, discarding the success.
  *
+ * **When to use**
+ *
+ * Use to extract only the failure value and discard successful values.
+ *
  * **Details**
  *
  * - `Failure<E>` becomes `Some<E>`
  * - `Success<A>` becomes `None`
- * - Use when you only care about the error case
  *
  * **Example** (Extracting the failure as an Option)
  *
@@ -775,12 +838,16 @@ export declare const makeEquivalence: <A, E>(success: Equivalence.Equivalence<A>
 /**
  * Transforms both the success and failure channels of a `Result`.
  *
+ * **When to use**
+ *
+ * Use to transform both success and failure values without changing whether the
+ * result succeeds or fails.
+ *
  * **Details**
  *
  * - Applies `onSuccess` if the result is a `Success`
  * - Applies `onFailure` if the result is a `Failure`
  * - Returns a new `Result`; does not mutate the input
- * - Use when you need to transform both channels in a single operation
  *
  * **Example** (Mapping both channels)
  *
@@ -809,12 +876,16 @@ export declare const mapBoth: {
     /**
      * Transforms both the success and failure channels of a `Result`.
      *
+     * **When to use**
+     *
+     * Use to transform both success and failure values without changing whether the
+     * result succeeds or fails.
+     *
      * **Details**
      *
      * - Applies `onSuccess` if the result is a `Success`
      * - Applies `onFailure` if the result is a `Failure`
      * - Returns a new `Result`; does not mutate the input
-     * - Use when you need to transform both channels in a single operation
      *
      * **Example** (Mapping both channels)
      *
@@ -846,12 +917,16 @@ export declare const mapBoth: {
     /**
      * Transforms both the success and failure channels of a `Result`.
      *
+     * **When to use**
+     *
+     * Use to transform both success and failure values without changing whether the
+     * result succeeds or fails.
+     *
      * **Details**
      *
      * - Applies `onSuccess` if the result is a `Success`
      * - Applies `onFailure` if the result is a `Failure`
      * - Returns a new `Result`; does not mutate the input
-     * - Use when you need to transform both channels in a single operation
      *
      * **Example** (Mapping both channels)
      *
@@ -884,6 +959,10 @@ export declare const mapBoth: {
 /**
  * Transforms the failure channel of a `Result`, leaving the success channel unchanged.
  *
+ * **When to use**
+ *
+ * Use to transform only the failure channel while preserving success values.
+ *
  * **Details**
  *
  * - If the result is a `Failure`, applies `f` to the error and returns a new `Failure`
@@ -913,6 +992,10 @@ export declare const mapError: {
     /**
      * Transforms the failure channel of a `Result`, leaving the success channel unchanged.
      *
+     * **When to use**
+     *
+     * Use to transform only the failure channel while preserving success values.
+     *
      * **Details**
      *
      * - If the result is a `Failure`, applies `f` to the error and returns a new `Failure`
@@ -942,6 +1025,10 @@ export declare const mapError: {
     /**
      * Transforms the failure channel of a `Result`, leaving the success channel unchanged.
      *
+     * **When to use**
+     *
+     * Use to transform only the failure channel while preserving success values.
+     *
      * **Details**
      *
      * - If the result is a `Failure`, applies `f` to the error and returns a new `Failure`
@@ -972,6 +1059,11 @@ export declare const mapError: {
 /**
  * Transforms the success channel of a `Result`, leaving the failure channel unchanged.
  *
+ * **When to use**
+ *
+ * Use to apply a transformation to the success value of a `Result` while
+ * preserving any existing failure.
+ *
  * **Details**
  *
  * - If the result is a `Success`, applies `f` to the value and returns a new `Success`
@@ -1003,6 +1095,11 @@ export declare const map: {
     /**
      * Transforms the success channel of a `Result`, leaving the failure channel unchanged.
      *
+     * **When to use**
+     *
+     * Use to apply a transformation to the success value of a `Result` while
+     * preserving any existing failure.
+     *
      * **Details**
      *
      * - If the result is a `Success`, applies `f` to the value and returns a new `Success`
@@ -1034,6 +1131,11 @@ export declare const map: {
     /**
      * Transforms the success channel of a `Result`, leaving the failure channel unchanged.
      *
+     * **When to use**
+     *
+     * Use to apply a transformation to the success value of a `Result` while
+     * preserving any existing failure.
+     *
      * **Details**
      *
      * - If the result is a `Success`, applies `f` to the value and returns a new `Success`
@@ -1175,6 +1277,11 @@ export declare const match: {
 /**
  * Lifts a value into a `Result` based on a predicate or refinement.
  *
+ * **When to use**
+ *
+ * Use to construct a `Result` from a raw value guarded by a predicate or
+ * refinement.
+ *
  * **Details**
  *
  * - If the predicate returns `true`, the value becomes `Success<A>`
@@ -1208,6 +1315,11 @@ export declare const liftPredicate: {
     /**
      * Lifts a value into a `Result` based on a predicate or refinement.
      *
+     * **When to use**
+     *
+     * Use to construct a `Result` from a raw value guarded by a predicate or
+     * refinement.
+     *
      * **Details**
      *
      * - If the predicate returns `true`, the value becomes `Success<A>`
@@ -1241,6 +1353,11 @@ export declare const liftPredicate: {
     /**
      * Lifts a value into a `Result` based on a predicate or refinement.
      *
+     * **When to use**
+     *
+     * Use to construct a `Result` from a raw value guarded by a predicate or
+     * refinement.
+     *
      * **Details**
      *
      * - If the predicate returns `true`, the value becomes `Success<A>`
@@ -1274,6 +1391,11 @@ export declare const liftPredicate: {
     /**
      * Lifts a value into a `Result` based on a predicate or refinement.
      *
+     * **When to use**
+     *
+     * Use to construct a `Result` from a raw value guarded by a predicate or
+     * refinement.
+     *
      * **Details**
      *
      * - If the predicate returns `true`, the value becomes `Success<A>`
@@ -1307,6 +1429,11 @@ export declare const liftPredicate: {
     /**
      * Lifts a value into a `Result` based on a predicate or refinement.
      *
+     * **When to use**
+     *
+     * Use to construct a `Result` from a raw value guarded by a predicate or
+     * refinement.
+     *
      * **Details**
      *
      * - If the predicate returns `true`, the value becomes `Success<A>`
@@ -1342,6 +1469,11 @@ export declare const liftPredicate: {
  * Validates the success value of a `Result` using a predicate, failing with a
  * custom error if the predicate returns `false`.
  *
+ * **When to use**
+ *
+ * Use to validate an already-successful `Result` value with a predicate or
+ * refinement.
+ *
  * **Details**
  *
  * - If the result is already a `Failure`, it is returned as-is
@@ -1377,6 +1509,11 @@ export declare const filterOrFail: {
      * Validates the success value of a `Result` using a predicate, failing with a
      * custom error if the predicate returns `false`.
      *
+     * **When to use**
+     *
+     * Use to validate an already-successful `Result` value with a predicate or
+     * refinement.
+     *
      * **Details**
      *
      * - If the result is already a `Failure`, it is returned as-is
@@ -1412,6 +1549,11 @@ export declare const filterOrFail: {
      * Validates the success value of a `Result` using a predicate, failing with a
      * custom error if the predicate returns `false`.
      *
+     * **When to use**
+     *
+     * Use to validate an already-successful `Result` value with a predicate or
+     * refinement.
+     *
      * **Details**
      *
      * - If the result is already a `Failure`, it is returned as-is
@@ -1447,6 +1589,11 @@ export declare const filterOrFail: {
      * Validates the success value of a `Result` using a predicate, failing with a
      * custom error if the predicate returns `false`.
      *
+     * **When to use**
+     *
+     * Use to validate an already-successful `Result` value with a predicate or
+     * refinement.
+     *
      * **Details**
      *
      * - If the result is already a `Failure`, it is returned as-is
@@ -1482,6 +1629,11 @@ export declare const filterOrFail: {
      * Validates the success value of a `Result` using a predicate, failing with a
      * custom error if the predicate returns `false`.
      *
+     * **When to use**
+     *
+     * Use to validate an already-successful `Result` value with a predicate or
+     * refinement.
+     *
      * **Details**
      *
      * - If the result is already a `Failure`, it is returned as-is
@@ -1546,6 +1698,11 @@ export declare const merge: <A, E>(self: Result<A, E>) => E | A;
 /**
  * Extracts the success value, or computes a fallback from the error.
  *
+ * **When to use**
+ *
+ * Use when you need the success value from a `Result`, with a fallback computed
+ * from the failure value.
+ *
  * **Details**
  *
  * - `Success<A>` returns the inner value
@@ -1567,6 +1724,7 @@ export declare const merge: <A, E>(self: Result<A, E>) => E | A;
  * @see {@link getOrNull} / {@link getOrUndefined} for simpler fallbacks
  * @see {@link getOrThrow} to throw on failure
  * @see {@link match} to map both branches
+ * @see {@link orElse} to recover with another Result instead of unwrapping
  *
  * @category getters
  * @since 2.0.0
@@ -1575,6 +1733,11 @@ export declare const getOrElse: {
     /**
      * Extracts the success value, or computes a fallback from the error.
      *
+     * **When to use**
+     *
+     * Use when you need the success value from a `Result`, with a fallback computed
+     * from the failure value.
+     *
      * **Details**
      *
      * - `Success<A>` returns the inner value
@@ -1596,6 +1759,7 @@ export declare const getOrElse: {
      * @see {@link getOrNull} / {@link getOrUndefined} for simpler fallbacks
      * @see {@link getOrThrow} to throw on failure
      * @see {@link match} to map both branches
+     * @see {@link orElse} to recover with another Result instead of unwrapping
      *
      * @category getters
      * @since 2.0.0
@@ -1604,6 +1768,11 @@ export declare const getOrElse: {
     /**
      * Extracts the success value, or computes a fallback from the error.
      *
+     * **When to use**
+     *
+     * Use when you need the success value from a `Result`, with a fallback computed
+     * from the failure value.
+     *
      * **Details**
      *
      * - `Success<A>` returns the inner value
@@ -1625,6 +1794,7 @@ export declare const getOrElse: {
      * @see {@link getOrNull} / {@link getOrUndefined} for simpler fallbacks
      * @see {@link getOrThrow} to throw on failure
      * @see {@link match} to map both branches
+     * @see {@link orElse} to recover with another Result instead of unwrapping
      *
      * @category getters
      * @since 2.0.0
@@ -1634,11 +1804,14 @@ export declare const getOrElse: {
 /**
  * Extracts the success value, or returns `null` on failure.
  *
+ * **When to use**
+ *
+ * Use with APIs that represent absence as `null`.
+ *
  * **Details**
  *
  * - `Success<A>` returns `A`
  * - `Failure<E>` returns `null`
- * - Convenient for interop with APIs that use `null` to represent absence
  *
  * **Example** (Unwrapping to nullable)
  *
@@ -1662,11 +1835,14 @@ export declare const getOrNull: <A, E>(self: Result<A, E>) => A | null;
 /**
  * Extracts the success value, or returns `undefined` on failure.
  *
+ * **When to use**
+ *
+ * Use with APIs that represent absence as `undefined`.
+ *
  * **Details**
  *
  * - `Success<A>` returns `A`
  * - `Failure<E>` returns `undefined`
- * - Convenient for interop with APIs that use `undefined` to represent absence
  *
  * **Example** (Unwrapping to optional)
  *
@@ -1690,12 +1866,15 @@ export declare const getOrUndefined: <A, E>(self: Result<A, E>) => A | undefined
 /**
  * Extracts the success value or throws a custom error derived from the failure.
  *
+ * **When to use**
+ *
+ * Use when converting a `Result` into a thrown exception with a custom error
+ * message or error type.
+ *
  * **Details**
  *
  * - `Success<A>` returns `A`
  * - `Failure<E>` throws the value returned by `onFailure(e)`
- * - Use when you want to convert a `Result` into a thrown exception with a
- *   custom error message or error type
  *
  * **Example** (Throwing a custom error)
  *
@@ -1724,12 +1903,15 @@ export declare const getOrThrowWith: {
     /**
      * Extracts the success value or throws a custom error derived from the failure.
      *
+     * **When to use**
+     *
+     * Use when converting a `Result` into a thrown exception with a custom error
+     * message or error type.
+     *
      * **Details**
      *
      * - `Success<A>` returns `A`
      * - `Failure<E>` throws the value returned by `onFailure(e)`
-     * - Use when you want to convert a `Result` into a thrown exception with a
-     *   custom error message or error type
      *
      * **Example** (Throwing a custom error)
      *
@@ -1758,12 +1940,15 @@ export declare const getOrThrowWith: {
     /**
      * Extracts the success value or throws a custom error derived from the failure.
      *
+     * **When to use**
+     *
+     * Use when converting a `Result` into a thrown exception with a custom error
+     * message or error type.
+     *
      * **Details**
      *
      * - `Success<A>` returns `A`
      * - `Failure<E>` throws the value returned by `onFailure(e)`
-     * - Use when you want to convert a `Result` into a thrown exception with a
-     *   custom error message or error type
      *
      * **Example** (Throwing a custom error)
      *
@@ -1793,6 +1978,10 @@ export declare const getOrThrowWith: {
 /**
  * Extracts the success value or throws the raw failure value `E`.
  *
+ * **When to use**
+ *
+ * Use when unchecked boundaries should turn failures into thrown exceptions.
+ *
  * **Details**
  *
  * - `Success<A>` returns `A`
@@ -1912,6 +2101,11 @@ export declare const orElse: {
 /**
  * Chains a function that returns a `Result` onto a successful value.
  *
+ * **When to use**
+ *
+ * Use to sequence `Result`-returning computations that should short-circuit on
+ * failure.
+ *
  * **Details**
  *
  * - If `self` is a `Success`, applies `f` to the value and returns the resulting `Result`
@@ -1944,6 +2138,11 @@ export declare const flatMap: {
     /**
      * Chains a function that returns a `Result` onto a successful value.
      *
+     * **When to use**
+     *
+     * Use to sequence `Result`-returning computations that should short-circuit on
+     * failure.
+     *
      * **Details**
      *
      * - If `self` is a `Success`, applies `f` to the value and returns the resulting `Result`
@@ -1976,6 +2175,11 @@ export declare const flatMap: {
     /**
      * Chains a function that returns a `Result` onto a successful value.
      *
+     * **When to use**
+     *
+     * Use to sequence `Result`-returning computations that should short-circuit on
+     * failure.
+     *
      * **Details**
      *
      * - If `self` is a `Success`, applies `f` to the value and returns the resulting `Result`
@@ -2009,6 +2213,11 @@ export declare const flatMap: {
 /**
  * A flexible variant of {@link flatMap} that accepts multiple input shapes.
  *
+ * **When to use**
+ *
+ * Use to sequence a next step that may be a `Result`, a function, or a plain
+ * value.
+ *
  * **Details**
  *
  * The second argument can be:
@@ -2052,6 +2261,11 @@ export declare const andThen: {
     /**
      * A flexible variant of {@link flatMap} that accepts multiple input shapes.
      *
+     * **When to use**
+     *
+     * Use to sequence a next step that may be a `Result`, a function, or a plain
+     * value.
+     *
      * **Details**
      *
      * The second argument can be:
@@ -2095,6 +2309,11 @@ export declare const andThen: {
     /**
      * A flexible variant of {@link flatMap} that accepts multiple input shapes.
      *
+     * **When to use**
+     *
+     * Use to sequence a next step that may be a `Result`, a function, or a plain
+     * value.
+     *
      * **Details**
      *
      * The second argument can be:
@@ -2138,6 +2357,11 @@ export declare const andThen: {
     /**
      * A flexible variant of {@link flatMap} that accepts multiple input shapes.
      *
+     * **When to use**
+     *
+     * Use to sequence a next step that may be a `Result`, a function, or a plain
+     * value.
+     *
      * **Details**
      *
      * The second argument can be:
@@ -2181,6 +2405,11 @@ export declare const andThen: {
     /**
      * A flexible variant of {@link flatMap} that accepts multiple input shapes.
      *
+     * **When to use**
+     *
+     * Use to sequence a next step that may be a `Result`, a function, or a plain
+     * value.
+     *
      * **Details**
      *
      * The second argument can be:
@@ -2224,6 +2453,11 @@ export declare const andThen: {
     /**
      * A flexible variant of {@link flatMap} that accepts multiple input shapes.
      *
+     * **When to use**
+     *
+     * Use to sequence a next step that may be a `Result`, a function, or a plain
+     * value.
+     *
      * **Details**
      *
      * The second argument can be:
@@ -2267,6 +2501,11 @@ export declare const andThen: {
     /**
      * A flexible variant of {@link flatMap} that accepts multiple input shapes.
      *
+     * **When to use**
+     *
+     * Use to sequence a next step that may be a `Result`, a function, or a plain
+     * value.
+     *
      * **Details**
      *
      * The second argument can be:
@@ -2310,6 +2549,11 @@ export declare const andThen: {
     /**
      * A flexible variant of {@link flatMap} that accepts multiple input shapes.
      *
+     * **When to use**
+     *
+     * Use to sequence a next step that may be a `Result`, a function, or a plain
+     * value.
+     *
      * **Details**
      *
      * The second argument can be:
@@ -2353,6 +2597,11 @@ export declare const andThen: {
     /**
      * A flexible variant of {@link flatMap} that accepts multiple input shapes.
      *
+     * **When to use**
+     *
+     * Use to sequence a next step that may be a `Result`, a function, or a plain
+     * value.
+     *
      * **Details**
      *
      * The second argument can be:
@@ -2397,6 +2646,11 @@ export declare const andThen: {
 /**
  * Collects a structure of `Result`s into a single `Result` of collected values.
  *
+ * **When to use**
+ *
+ * Use to collect independent `Result` values into one `Result` while preserving
+ * the original structure.
+ *
  * **Details**
  *
  * Accepts:
@@ -2436,6 +2690,11 @@ export declare const all: <const I extends Iterable<Result<any, any>> | Record<s
 /**
  * Swaps the success and failure channels of a `Result`.
  *
+ * **When to use**
+ *
+ * Use to swap channels when failure-focused operations are easier through
+ * success-oriented combinators.
+ *
  * **Details**
  *
  * - `Success<A>` becomes `Failure<A>` (i.e., `Result<E, A>`)
@@ -2464,6 +2723,11 @@ export declare const flip: <A, E>(self: Result<A, E>) => Result<E, A>;
 /**
  * Generator-based syntax for composing `Result` values sequentially.
  *
+ * **When to use**
+ *
+ * Use when sequential `Result` composition is clearer with generator syntax
+ * than nested `flatMap` calls.
+ *
  * **Details**
  *
  * - Use `yield*` to unwrap a `Result` inside the generator; if any yielded
@@ -2496,6 +2760,12 @@ export declare const gen: Gen.Gen<ResultTypeLambda>;
 /**
  * Starting point for the "do notation" simulation with `Result`.
  *
+ * **When to use**
+ *
+ * Use to start a `Result` do-notation pipeline from an empty successful record
+ * before adding named fields from `Result`-producing computations and pure
+ * computed values.
+ *
  * **Details**
  *
  * Creates a `Result<{}>` (success with an empty object). Use with
@@ -2520,6 +2790,7 @@ export declare const gen: Gen.Gen<ResultTypeLambda>;
  * @see {@link bind} to add Result-producing fields
  * @see {@link let_ let} to add pure computed fields
  * @see {@link gen} for an alternative generator-based syntax
+ * @see {@link bindTo} for starting a do-notation chain from an existing Result
  *
  * @category Do Notation
  * @since 2.0.0
@@ -2529,6 +2800,11 @@ export declare const Do: Result<{}>;
  * Adds a named field to the do-notation accumulator by running a `Result`-producing
  * function that receives the current accumulated object.
  *
+ * **When to use**
+ *
+ * Use when adding a `Result`-producing step to a do-notation pipeline and
+ * storing its successful value under a named field in the accumulated object.
+ *
  * **Details**
  *
  * - Short-circuits on the first `Failure`
@@ -2561,6 +2837,11 @@ export declare const bind: {
      * Adds a named field to the do-notation accumulator by running a `Result`-producing
      * function that receives the current accumulated object.
      *
+     * **When to use**
+     *
+     * Use when adding a `Result`-producing step to a do-notation pipeline and
+     * storing its successful value under a named field in the accumulated object.
+     *
      * **Details**
      *
      * - Short-circuits on the first `Failure`
@@ -2595,6 +2876,11 @@ export declare const bind: {
      * Adds a named field to the do-notation accumulator by running a `Result`-producing
      * function that receives the current accumulated object.
      *
+     * **When to use**
+     *
+     * Use when adding a `Result`-producing step to a do-notation pipeline and
+     * storing its successful value under a named field in the accumulated object.
+     *
      * **Details**
      *
      * - Short-circuits on the first `Failure`
@@ -2630,6 +2916,11 @@ export declare const bind: {
  * Wraps the success value of a `Result` into a named field, producing a
  * `Result<Record<N, A>>`.
  *
+ * **When to use**
+ *
+ * Use to name the success value of an existing `Result` before continuing a
+ * do-notation pipeline.
+ *
  * **Details**
  *
  * This is typically used to start a do-notation chain from an existing
@@ -2659,6 +2950,11 @@ export declare const bindTo: {
      * Wraps the success value of a `Result` into a named field, producing a
      * `Result<Record<N, A>>`.
      *
+     * **When to use**
+     *
+     * Use to name the success value of an existing `Result` before continuing a
+     * do-notation pipeline.
+     *
      * **Details**
      *
      * This is typically used to start a do-notation chain from an existing
@@ -2688,6 +2984,11 @@ export declare const bindTo: {
      * Wraps the success value of a `Result` into a named field, producing a
      * `Result<Record<N, A>>`.
      *
+     * **When to use**
+     *
+     * Use to name the success value of an existing `Result` before continuing a
+     * do-notation pipeline.
+     *
      * **Details**
      *
      * This is typically used to start a do-notation chain from an existing
@@ -2727,6 +3028,10 @@ export {
  * Adds a named field to the do-notation accumulator by computing a pure
  * (non-Result) value from the current accumulated object.
  *
+ * **When to use**
+ *
+ * Use to add a pure computed field to a do-notation accumulator.
+ *
  * **Details**
  *
  * - Use {@link bind} when the computation returns a `Result`