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

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>> {
@@ -294,7 +301,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)
  *
@@ -308,7 +314,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,11 +323,13 @@ 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
  *
  * **Example** (Creating a failure)
  *
@@ -344,12 +352,17 @@ export declare const fail: <E>(left: E) => Result<never, E>;
 declare const void_: Result<void>;
 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)
  *
@@ -362,21 +375,38 @@ export {
  * // Output: true
  * ```
  *
- * @see {@link succeed}
+ * @see {@link succeed} to create a Success with a specific value
  *
  * @category constructors
  * @since 3.13.0
  */
 void_ as void };
 /**
- * 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
@@ -385,6 +415,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 +450,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 +485,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 +521,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 +546,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 +557,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 +582,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 +593,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 +618,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
@@ -570,7 +636,7 @@ declare 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**
  *
@@ -604,11 +670,14 @@ export {
  */
 try_ as try };
 /**
- * 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>`
  *
@@ -633,6 +702,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 +734,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 +766,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 +797,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 +858,15 @@ 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 +895,15 @@ 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 +935,15 @@ 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,11 +976,14 @@ 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`
  * - If the result is a `Success`, returns it as-is
- * - Does not mutate the input
  *
  * **Example** (Adding context to an error)
  *
@@ -913,11 +1008,14 @@ 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`
      * - If the result is a `Success`, returns it as-is
-     * - Does not mutate the input
      *
      * **Example** (Adding context to an error)
      *
@@ -942,11 +1040,14 @@ 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`
      * - If the result is a `Success`, returns it as-is
-     * - Does not mutate the input
      *
      * **Example** (Adding context to an error)
      *
@@ -972,11 +1073,15 @@ 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`
  * - 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)
@@ -1003,11 +1108,15 @@ 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`
      * - 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)
@@ -1034,11 +1143,15 @@ 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`
      * - 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)
@@ -1175,6 +1288,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 +1326,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 +1364,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 +1402,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 +1440,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 +1480,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 +1520,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 +1560,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 +1600,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 +1640,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 +1709,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 +1735,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 +1744,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 +1770,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 +1779,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 +1805,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 +1815,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 +1846,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 +1877,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 +1914,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 +1951,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 +1989,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 +2112,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 +2149,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 +2186,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`
@@ -2007,7 +2222,12 @@ export declare const flatMap: {
     <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**
  *
@@ -2050,7 +2270,12 @@ export declare const flatMap: {
  */
 export declare 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**
      *
@@ -2093,7 +2318,12 @@ export declare 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**
      *
@@ -2136,7 +2366,12 @@ export declare 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**
      *
@@ -2179,7 +2414,12 @@ export declare 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**
      *
@@ -2222,7 +2462,12 @@ export declare 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**
      *
@@ -2265,7 +2510,12 @@ export declare 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**
      *
@@ -2308,7 +2558,12 @@ export declare 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**
      *
@@ -2351,7 +2606,12 @@ export declare 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**
      *
@@ -2397,6 +2657,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 +2701,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>`)
@@ -2462,7 +2732,12 @@ export declare const all: <const I extends Iterable<Result<any, any>> | Record<s
  */
 export declare const flip: <A, E>(self: Result<A, E>) => Result<E, A>;
 /**
- * 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**
  *
@@ -2494,7 +2769,13 @@ export declare const flip: <A, E>(self: Result<A, E>) => Result<E, A>;
  */
 export declare const gen: Gen.Gen<ResultTypeLambda>;
 /**
- * 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**
  *
@@ -2520,6 +2801,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 +2811,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 +2848,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 +2887,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 +2927,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 +2961,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 +2995,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 +3039,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`
@@ -2817,12 +3133,17 @@ export declare const transposeOption: <A = never, E = never>(self: Option<Result
  */
 export declare const transposeMapOption: (<A, B, E = never>(f: (self: A) => Result<B, E>) => (self: Option<A>) => Result<Option<B>, E>) & (<A, B, E = never>(self: Option<A>, f: (self: A) => Result<B, E>) => Result<Option<B>, E>);
 /**
- * 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)
  *
@@ -2834,6 +3155,8 @@ export declare const transposeMapOption: (<A, B, E = never>(f: (self: A) => Resu
  * ```
  *
  * @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