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

package/src/Result.ts

@@ -169,7 +169,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>> {
@@ -323,7 +330,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
@@ -333,9 +340,12 @@ export const succeed: <A>(right: A) => Result<A> = result.succeed
 /**
  * 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
  *
@@ -405,6 +415,12 @@ export const failVoid: Result<never, void> = fail(void 0)
 /**
  * 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>>`
@@ -434,6 +450,12 @@ export 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>>`
@@ -463,6 +485,12 @@ export 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>>`
@@ -498,6 +526,11 @@ export 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>`
@@ -518,8 +551,9 @@ export 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
@@ -528,6 +562,11 @@ export 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>`
@@ -548,8 +587,9 @@ export 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
@@ -558,6 +598,11 @@ export 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>`
@@ -578,8 +623,9 @@ export 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
@@ -656,9 +702,12 @@ export {
 /**
  * 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>`
  *
@@ -684,6 +733,10 @@ export const isResult: (input: unknown) => input is Result<unknown, unknown> = r
 /**
  * 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>`
@@ -713,6 +766,10 @@ export const isFailure: <A, E>(self: Result<A, E>) => self is Failure<A, E> = re
 /**
  * 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>`
@@ -742,11 +799,14 @@ export const isSuccess: <A, E>(self: Result<A, E>) => self is Success<A, E> = re
 /**
  * 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)
  *
@@ -771,11 +831,14 @@ export const getSuccess: <A, E>(self: Result<A, E>) => Option<A> = result.getSuc
 /**
  * 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)
  *
@@ -839,12 +902,16 @@ export const makeEquivalence = <A, E>(
 /**
  * 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)
  *
@@ -873,12 +940,16 @@ export 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)
    *
@@ -912,12 +983,16 @@ export 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)
    *
@@ -960,6 +1035,10 @@ export 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`
@@ -989,6 +1068,10 @@ export 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`
@@ -1018,6 +1101,10 @@ export 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`
@@ -1053,6 +1140,11 @@ export 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`
@@ -1084,6 +1176,11 @@ export 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`
@@ -1115,6 +1212,11 @@ export 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`
@@ -1273,6 +1375,11 @@ export 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>`
@@ -1306,6 +1413,11 @@ export 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>`
@@ -1339,6 +1451,11 @@ export 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>`
@@ -1372,6 +1489,11 @@ export 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>`
@@ -1405,6 +1527,11 @@ export 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>`
@@ -1445,6 +1572,11 @@ export 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
@@ -1480,6 +1612,11 @@ export 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
@@ -1518,6 +1655,11 @@ export 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
@@ -1553,6 +1695,11 @@ export 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
@@ -1592,6 +1739,11 @@ export 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
@@ -1662,6 +1814,11 @@ export const merge: <A, E>(self: Result<A, E>) => E | A = match({ onFailure: ide
 /**
  * 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
@@ -1683,6 +1840,7 @@ export const merge: <A, E>(self: Result<A, E>) => E | A = match({ onFailure: ide
  * @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
@@ -1691,6 +1849,11 @@ export 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
@@ -1712,6 +1875,7 @@ export 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
@@ -1720,6 +1884,11 @@ export 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
@@ -1741,6 +1910,7 @@ export 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
@@ -1755,11 +1925,14 @@ export 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)
  *
@@ -1784,11 +1957,14 @@ export const getOrNull: <A, E>(self: Result<A, E>) => A | null = getOrElse(const
 /**
  * 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)
  *
@@ -1813,12 +1989,15 @@ export const getOrUndefined: <A, E>(self: Result<A, E>) => A | undefined = getOr
 /**
  * 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)
  *
@@ -1847,12 +2026,15 @@ export 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)
    *
@@ -1881,12 +2063,15 @@ export 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)
    *
@@ -1922,6 +2107,10 @@ export 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`
@@ -2047,6 +2236,11 @@ export 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`
@@ -2079,6 +2273,11 @@ export 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`
@@ -2111,6 +2310,11 @@ export 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`
@@ -2149,6 +2353,11 @@ export 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:
@@ -2192,6 +2401,11 @@ export 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:
@@ -2235,6 +2449,11 @@ export 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:
@@ -2278,6 +2497,11 @@ export 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:
@@ -2321,6 +2545,11 @@ export 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:
@@ -2364,6 +2593,11 @@ export 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:
@@ -2407,6 +2641,11 @@ export 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:
@@ -2450,6 +2689,11 @@ export 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:
@@ -2493,6 +2737,11 @@ export 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:
@@ -2548,6 +2797,11 @@ export 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:
@@ -2618,6 +2872,11 @@ export const all: <const I extends Iterable<Result<any, any>> | Record<string, R
 /**
  * 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>`)
@@ -2648,6 +2907,11 @@ export 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
@@ -2697,6 +2961,12 @@ export const gen: Gen.Gen<ResultTypeLambda> = (...args) => {
 /**
  * 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
@@ -2721,6 +2991,7 @@ export const gen: Gen.Gen<ResultTypeLambda> = (...args) => {
  * @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
@@ -2731,6 +3002,11 @@ export const Do: Result<{}> = succeed({})
  * 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`
@@ -2763,6 +3039,11 @@ export 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`
@@ -2795,6 +3076,11 @@ export 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`
@@ -2833,6 +3119,11 @@ export 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
@@ -2862,6 +3153,11 @@ export 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
@@ -2891,6 +3187,11 @@ export 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
@@ -2935,6 +3236,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`