effect 4.0.0-beta.70 → 4.0.0-beta.72

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>> {
@@ -309,7 +316,6 @@ export declare namespace Result {
  *
  * - Use when you have a value and want to lift it into the `Result` type
  * - The error type `E` defaults to `never`
- * - Does not mutate input; allocates a new `Success` wrapper
  *
  * **Example** (Wrapping a value)
  *
@@ -323,7 +329,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,11 +339,13 @@ 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
  *
  * **Example** (Creating a failure)
  *
@@ -361,12 +369,17 @@ export const fail: <E>(left: E) => Result<never, E> = result.fail
 const void_: Result<void> = succeed(void 0)
 export {
   /**
-   * A pre-built `Result<void>` holding `undefined` as its success value.
+   * Provides a pre-built successful `Result` that carries `undefined`.
+   *
+   * **When to use**
+   *
+   * Use when a success should signal completion without carrying a meaningful
+   * value.
    *
    * **Details**
    *
-   * - Use when you need a `Result` that represents "completed with no meaningful value"
-   * - Equivalent to `Result.succeed(undefined)` but avoids an extra allocation
+   * This is equivalent to `Result.succeed(undefined)`, but reuses a shared
+   * `Success` wrapper instead of allocating one each time.
    *
    * **Example** (Using void result)
    *
@@ -379,7 +392,7 @@ export {
    * // Output: true
    * ```
    *
-   * @see {@link succeed}
+   * @see {@link succeed} to create a Success with a specific value
    *
    * @category constructors
    * @since 3.13.0
@@ -388,14 +401,31 @@ export {
 }
 
 /**
- * A pre-built failed `Result` whose failure value is `undefined`.
+ * Provides a pre-built failed `Result` whose failure value is `undefined`.
+ *
+ * **When to use**
+ *
+ * Use when a failure should act only as a control signal and no failure value
+ * is needed.
  *
  * **Details**
  *
  * This is equivalent to `Result.fail(undefined)` with type
- * `Result<never, void>`, but avoids allocating a new `Failure` wrapper.
+ * `Result<never, void>`, but reuses a shared `Failure` wrapper instead of
+ * allocating one each time.
+ *
+ * **Example** (Using a failure without a payload)
+ *
+ * ```ts
+ * import { Result } from "effect"
+ *
+ * const result = Result.failVoid
+ *
+ * console.log(Result.isFailure(result))
+ * // Output: true
+ * ```
  *
- * @see {@link fail}
+ * @see {@link fail} to create a Failure with a specific value
  *
  * @category constructors
  * @since 4.0.0
@@ -405,6 +435,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 +470,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 +505,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 +546,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 +571,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 +582,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 +607,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 +618,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 +643,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
@@ -618,7 +684,7 @@ const try_: {
 
 export {
   /**
-   * Wraps a synchronous computation that may throw into a `Result`.
+   * Wraps a synchronous computation that may throw into a `Result` safely.
    *
    * **Details**
    *
@@ -654,11 +720,14 @@ export {
 }
 
 /**
- * Tests whether a value is a `Result` (either `Success` or `Failure`).
+ * Checks 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 +753,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 +786,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 +819,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 +851,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 +922,15 @@ 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 +959,15 @@ 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 +1001,15 @@ 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,11 +1052,14 @@ 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`
  * - If the result is a `Success`, returns it as-is
- * - Does not mutate the input
  *
  * **Example** (Adding context to an error)
  *
@@ -989,11 +1084,14 @@ 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`
    * - If the result is a `Success`, returns it as-is
-   * - Does not mutate the input
    *
    * **Example** (Adding context to an error)
    *
@@ -1018,11 +1116,14 @@ 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`
    * - If the result is a `Success`, returns it as-is
-   * - Does not mutate the input
    *
    * **Example** (Adding context to an error)
    *
@@ -1053,11 +1154,15 @@ 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`
  * - If the result is a `Failure`, returns it as-is
- * - Does not mutate the input
  * - Use {@link flatMap} if `f` returns a `Result` (to avoid nested Results)
  *
  * **Example** (Doubling the success value)
@@ -1084,11 +1189,15 @@ 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`
    * - If the result is a `Failure`, returns it as-is
-   * - Does not mutate the input
    * - Use {@link flatMap} if `f` returns a `Result` (to avoid nested Results)
    *
    * **Example** (Doubling the success value)
@@ -1115,11 +1224,15 @@ 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`
    * - If the result is a `Failure`, returns it as-is
-   * - Does not mutate the input
    * - Use {@link flatMap} if `f` returns a `Result` (to avoid nested Results)
    *
    * **Example** (Doubling the success value)
@@ -1273,6 +1386,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 +1424,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 +1462,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 +1500,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 +1538,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 +1583,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 +1623,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 +1666,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 +1706,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 +1750,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 +1825,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 +1851,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 +1860,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 +1886,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 +1895,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 +1921,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 +1936,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 +1968,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 +2000,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 +2037,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 +2074,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 +2118,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 +2247,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 +2284,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 +2321,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`
@@ -2147,7 +2362,12 @@ export const flatMap: {
 )
 
 /**
- * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+ * Provides 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**
  *
@@ -2190,7 +2410,12 @@ export const flatMap: {
  */
 export const andThen: {
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides 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**
    *
@@ -2233,7 +2458,12 @@ export const andThen: {
    */
   <A, A2, E2>(f: (a: A) => Result<A2, E2>): <E>(self: Result<A, E>) => Result<A2, E | E2>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides 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**
    *
@@ -2276,7 +2506,12 @@ export const andThen: {
    */
   <A2, E2>(f: Result<A2, E2>): <A, E>(self: Result<A, E>) => Result<A2, E | E2>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides 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**
    *
@@ -2319,7 +2554,12 @@ export const andThen: {
    */
   <A, A2>(f: (a: A) => A2): <E>(self: Result<A, E>) => Result<A2, E>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides 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**
    *
@@ -2362,7 +2602,12 @@ export const andThen: {
    */
   <A2>(right: NotFunction<A2>): <A, E>(self: Result<A, E>) => Result<A2, E>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides 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**
    *
@@ -2405,7 +2650,12 @@ export const andThen: {
    */
   <A, E, A2, E2>(self: Result<A, E>, f: (a: A) => Result<A2, E2>): Result<A2, E | E2>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides 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**
    *
@@ -2448,7 +2698,12 @@ export const andThen: {
    */
   <A, E, A2, E2>(self: Result<A, E>, f: Result<A2, E2>): Result<A2, E | E2>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides 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**
    *
@@ -2491,7 +2746,12 @@ export const andThen: {
    */
   <A, E, A2>(self: Result<A, E>, f: (a: A) => A2): Result<A2, E>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides 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**
    *
@@ -2548,6 +2808,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 +2883,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>`)
@@ -2646,7 +2916,12 @@ export const flip = <A, E>(self: Result<A, E>): Result<E, A> =>
   isFailure(self) ? succeed(self.failure) : fail(self.success)
 
 /**
- * Generator-based syntax for composing `Result` values sequentially.
+ * Provides 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**
  *
@@ -2695,7 +2970,13 @@ export const gen: Gen.Gen<ResultTypeLambda> = (...args) => {
 // -------------------------------------------------------------------------------------
 
 /**
- * Starting point for the "do notation" simulation with `Result`.
+ * Provides the 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**
  *
@@ -2721,6 +3002,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 +3013,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 +3050,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 +3087,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 +3130,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 +3164,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 +3198,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 +3247,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`
@@ -3100,12 +3416,17 @@ export const transposeMapOption = dual<
 >(2, (self, f) => option_.isNone(self) ? succeedNone : map(f(self.value), option_.some))
 
 /**
- * A pre-built `Result<Option<never>>` that succeeds with `None`.
+ * Provides a pre-built `Result<Option<never>>` that succeeds with `None`.
+ *
+ * **When to use**
+ *
+ * Use when an optional success should be absent, such as the `None` branch of
+ * `transposeOption` or `transposeMapOption`.
  *
  * **Details**
  *
- * - Equivalent to `Result.succeed(Option.none())` but avoids an extra allocation
- * - Useful with {@link transposeOption} patterns
+ * This is equivalent to `Result.succeed(Option.none())`, but reuses a shared
+ * `Success` wrapper instead of allocating one each time.
  *
  * **Example** (Using succeedNone)
  *
@@ -3117,6 +3438,8 @@ export const transposeMapOption = dual<
  * ```
  *
  * @see {@link succeedSome} for the `Some` counterpart
+ * @see {@link transposeOption} to transpose an Option that already contains a Result
+ * @see {@link transposeMapOption} to map and transpose an Option in one step
  *
  * @category constructors
  * @since 4.0.0