effect 4.0.0-beta.74 → 4.0.0-beta.75

package/dist/Option.d.ts

@@ -261,7 +261,8 @@ export interface OptionUnifyIgnore {
  *
  * **When to use**
  *
- * Use to represent `Option` in higher-kinded type operations.
+ * Use when defining higher-kinded abstractions that must accept optional-value
+ * types as one of their type-lambda inputs.
  *
  * @category type lambdas
  * @since 2.0.0
@@ -306,7 +307,7 @@ export declare const none: <A = never>() => Option<A>;
  *
  * **When to use**
  *
- * Use to wrap a known-present value as `Option`
+ * Use to wrap a known present value as `Option`
  * - Returning a successful result from a partial function
  *
  * **Details**
@@ -373,7 +374,7 @@ export declare const isOption: (input: unknown) => input is Option<unknown>;
  *
  * **When to use**
  *
- * Use when branching on absence before accessing `.value`
+ * Use when you need to branch on an absent `Option` before accessing `.value`.
  *
  * **Details**
  *
@@ -402,7 +403,7 @@ export declare const isNone: <A>(self: Option<A>) => self is None<A>;
  *
  * **When to use**
  *
- * Use when branching on presence before accessing `.value`
+ * Use when you need to branch on a present `Option` before accessing `.value`.
  *
  * **Details**
  *
@@ -431,8 +432,8 @@ export declare const isSome: <A>(self: Option<A>) => self is Some<A>;
  *
  * **When to use**
  *
- * Use when exhaustively handling both branches in one expression
- * - Transforming an `Option` into a plain value
+ * Use when you need to handle both `Some` and `None` in one expression and
+ * transform an `Option` into a plain value.
  *
  * **Details**
  *
@@ -465,8 +466,8 @@ export declare const match: {
      *
      * **When to use**
      *
-     * Use when exhaustively handling both branches in one expression
-     * - Transforming an `Option` into a plain value
+     * Use when you need to handle both `Some` and `None` in one expression and
+     * transform an `Option` into a plain value.
      *
      * **Details**
      *
@@ -502,8 +503,8 @@ export declare const match: {
      *
      * **When to use**
      *
-     * Use when exhaustively handling both branches in one expression
-     * - Transforming an `Option` into a plain value
+     * Use when you need to handle both `Some` and `None` in one expression and
+     * transform an `Option` into a plain value.
      *
      * **Details**
      *
@@ -540,8 +541,8 @@ export declare const match: {
  *
  * **When to use**
  *
- * Use when turning a parsing function into a type-narrowing predicate
- * - Filtering arrays with `Array.prototype.filter`
+ * Use when you need to turn an `Option`-returning parser into a type-narrowing
+ * predicate, such as for `Array.prototype.filter`.
  *
  * **Details**
  *
@@ -582,8 +583,8 @@ export declare const toRefinement: <A, B extends A>(f: (a: A) => Option<B>) => (
  *
  * **When to use**
  *
- * Use when safely extracting the head of a collection
- * - Working with generators or lazy iterables
+ * Use when you need to safely extract the head of a collection, including
+ * generators or lazy iterables.
  *
  * **Details**
  *
@@ -613,7 +614,8 @@ export declare const fromIterable: <A>(collection: Iterable<A>) => Option<A>;
  *
  * **When to use**
  *
- * Use when discarding the failure channel when you only care about success
+ * Use when you need to discard a `Result` failure and keep only the success
+ * value as an `Option`.
  *
  * **Details**
  *
@@ -643,7 +645,8 @@ export declare const getSuccess: <A, E>(self: Result<A, E>) => Option<A>;
  *
  * **When to use**
  *
- * Use to extract the failure when you do not need the success value
+ * Use when you need to discard a `Result` success and keep only the failure
+ * value as an `Option`.
  *
  * **Details**
  *
@@ -776,8 +779,8 @@ export declare const getOrElse: {
  *
  * **When to use**
  *
- * Use when chaining fallback `Option` computations
- * - Building priority chains of optional values
+ * Use when you need a lazy fallback `Option`, such as when building priority
+ * chains of optional values.
  *
  * **Details**
  *
@@ -809,8 +812,8 @@ export declare const orElse: {
      *
      * **When to use**
      *
-     * Use when chaining fallback `Option` computations
-     * - Building priority chains of optional values
+     * Use when you need a lazy fallback `Option`, such as when building priority
+     * chains of optional values.
      *
      * **Details**
      *
@@ -842,8 +845,8 @@ export declare const orElse: {
      *
      * **When to use**
      *
-     * Use when chaining fallback `Option` computations
-     * - Building priority chains of optional values
+     * Use when you need a lazy fallback `Option`, such as when building priority
+     * chains of optional values.
      *
      * **Details**
      *
@@ -970,8 +973,8 @@ export declare const orElseSome: {
  *
  * **When to use**
  *
- * Use when distinguishing whether a value came from the primary or fallback
- * `Option`.
+ * Use when you need to know whether a present value came from the primary or
+ * fallback `Option`.
  *
  * **Details**
  *
@@ -1002,8 +1005,8 @@ export declare const orElseResult: {
      *
      * **When to use**
      *
-     * Use when distinguishing whether a value came from the primary or fallback
-     * `Option`.
+     * Use when you need to know whether a present value came from the primary or
+     * fallback `Option`.
      *
      * **Details**
      *
@@ -1034,8 +1037,8 @@ export declare const orElseResult: {
      *
      * **When to use**
      *
-     * Use when distinguishing whether a value came from the primary or fallback
-     * `Option`.
+     * Use when you need to know whether a present value came from the primary or
+     * fallback `Option`.
      *
      * **Details**
      *
@@ -1068,7 +1071,7 @@ export declare const orElseResult: {
  *
  * **When to use**
  *
- * Use when searching for the first available value in a priority list
+ * Use when you need the first available `Some` value from a priority list.
  *
  * **Details**
  *
@@ -1099,8 +1102,8 @@ export declare const firstSomeOf: <T, C extends Iterable<Option<T>> = Iterable<O
  *
  * **When to use**
  *
- * Use when bridging from nullable APIs to `Option`
- * - Wrapping values that may be `null` or `undefined`
+ * Use when you need JavaScript nullish values to become absence at an API
+ * boundary while all other values, including falsy ones, remain present.
  *
  * **Details**
  *
@@ -1136,7 +1139,8 @@ export declare const fromNullishOr: <A>(a: A) => Option<NonNullable<A>>;
  *
  * **When to use**
  *
- * Use when when `null` is a meaningful value but `undefined` means absent
+ * Use when you want to treat only `undefined` as absent while preserving `null`
+ * as a meaningful value.
  *
  * **Details**
  *
@@ -1171,7 +1175,8 @@ export declare const fromUndefinedOr: <A>(a: A) => Option<Exclude<A, undefined>>
  *
  * **When to use**
  *
- * Use when when `undefined` is a meaningful value but `null` means absent
+ * Use when you want to treat only `null` as absent while preserving
+ * `undefined` as a meaningful value.
  *
  * **Details**
  *
@@ -1244,7 +1249,7 @@ export declare const liftNullishOr: <A extends ReadonlyArray<unknown>, B>(f: (..
  *
  * **When to use**
  *
- * Use when interoping with APIs that use `null` for missing values
+ * Use when you need to pass absent `Option` values to APIs that expect `null`.
  *
  * **Details**
  *
@@ -1275,7 +1280,8 @@ export declare const getOrNull: <A>(self: Option<A>) => A | null;
  *
  * **When to use**
  *
- * Use when interoping with APIs that use `undefined` for missing values
+ * Use when you need to pass absent `Option` values to APIs that expect
+ * `undefined`.
  *
  * **Details**
  *
@@ -1338,8 +1344,8 @@ export declare const liftThrowable: <A extends ReadonlyArray<unknown>, B>(f: (..
  *
  * **When to use**
  *
- * Use when fail-fast unwrapping when absence is unexpected
- * - Providing a descriptive error for debugging
+ * Use when you need fail-fast unwrapping of an `Option` for unexpected absence
+ * and want to provide a descriptive debugging error.
  *
  * **Details**
  *
@@ -1370,8 +1376,8 @@ export declare const getOrThrowWith: {
      *
      * **When to use**
      *
-     * Use when fail-fast unwrapping when absence is unexpected
-     * - Providing a descriptive error for debugging
+     * Use when you need fail-fast unwrapping of an `Option` for unexpected absence
+     * and want to provide a descriptive debugging error.
      *
      * **Details**
      *
@@ -1402,8 +1408,8 @@ export declare const getOrThrowWith: {
      *
      * **When to use**
      *
-     * Use when fail-fast unwrapping when absence is unexpected
-     * - Providing a descriptive error for debugging
+     * Use when you need fail-fast unwrapping of an `Option` for unexpected absence
+     * and want to provide a descriptive debugging error.
      *
      * **Details**
      *
@@ -1435,7 +1441,8 @@ export declare const getOrThrowWith: {
  *
  * **When to use**
  *
- * Use when quick fail-fast unwrapping when a generic error is acceptable
+ * Use when you need quick fail-fast unwrapping of an `Option` and a generic
+ * error is acceptable.
  *
  * **Details**
  *
@@ -1467,8 +1474,8 @@ export declare const getOrThrow: <A>(self: Option<A>) => A;
  *
  * **When to use**
  *
- * Use to apply a pure transformation to an optional value, especially when
- * chaining transformations in a pipeline.
+ * Use to apply a pure transformation to an `Option`'s present value, especially
+ * when chaining transformations in a pipeline.
  *
  * **Details**
  *
@@ -1500,8 +1507,8 @@ export declare const map: {
      *
      * **When to use**
      *
-     * Use to apply a pure transformation to an optional value, especially when
-     * chaining transformations in a pipeline.
+     * Use to apply a pure transformation to an `Option`'s present value, especially
+     * when chaining transformations in a pipeline.
      *
      * **Details**
      *
@@ -1533,8 +1540,8 @@ export declare const map: {
      *
      * **When to use**
      *
-     * Use to apply a pure transformation to an optional value, especially when
-     * chaining transformations in a pipeline.
+     * Use to apply a pure transformation to an `Option`'s present value, especially
+     * when chaining transformations in a pipeline.
      *
      * **Details**
      *
@@ -1566,12 +1573,8 @@ export declare const map: {
  *
  * **When to use**
  *
- * Use when preserving presence/absence while discarding the original value
- *
- * **Details**
- *
- * - `Some` → `Some(b)`
- * - `None` → `None`
+ * Use when you need to replace a present `Option` value while preserving
+ * whether it was `Some` or `None`.
  *
  * **Example** (Replacing a value)
  *
@@ -1597,12 +1600,8 @@ export declare const as: {
      *
      * **When to use**
      *
-     * Use when preserving presence/absence while discarding the original value
-     *
-     * **Details**
-     *
-     * - `Some` → `Some(b)`
-     * - `None` → `None`
+     * Use when you need to replace a present `Option` value while preserving
+     * whether it was `Some` or `None`.
      *
      * **Example** (Replacing a value)
      *
@@ -1628,12 +1627,8 @@ export declare const as: {
      *
      * **When to use**
      *
-     * Use when preserving presence/absence while discarding the original value
-     *
-     * **Details**
-     *
-     * - `Some` → `Some(b)`
-     * - `None` → `None`
+     * Use when you need to replace a present `Option` value while preserving
+     * whether it was `Some` or `None`.
      *
      * **Example** (Replacing a value)
      *
@@ -1661,12 +1656,8 @@ export declare const as: {
  *
  * **When to use**
  *
- * Use when discarding the value while preserving presence/absence
- *
- * **Details**
- *
- * - `Some` → `Some(undefined)`
- * - `None` → `None`
+ * Use when you need to discard a present `Option` value while preserving
+ * whether it was `Some` or `None`.
  *
  * **Example** (Voiding the value)
  *
@@ -1716,8 +1707,8 @@ void_ as void };
  *
  * **When to use**
  *
- * Use when chaining dependent optional computations where each step may return
- * `None`.
+ * Use when you need to chain dependent `Option` computations where each step
+ * may return `None`.
  *
  * **Details**
  *
@@ -1762,8 +1753,8 @@ export declare const flatMap: {
      *
      * **When to use**
      *
-     * Use when chaining dependent optional computations where each step may return
-     * `None`.
+     * Use when you need to chain dependent `Option` computations where each step
+     * may return `None`.
      *
      * **Details**
      *
@@ -1808,8 +1799,8 @@ export declare const flatMap: {
      *
      * **When to use**
      *
-     * Use when chaining dependent optional computations where each step may return
-     * `None`.
+     * Use when you need to chain dependent `Option` computations where each step
+     * may return `None`.
      *
      * **Details**
      *
@@ -1855,8 +1846,8 @@ export declare const flatMap: {
  *
  * **When to use**
  *
- * Use when flexible chaining where the next step may return `Option`, a plain value,
- *   or a function
+ * Use when you need to chain an `Option` with a next step that may be another
+ * `Option`, a plain value, or a function.
  *
  * **Details**
  *
@@ -1896,8 +1887,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when flexible chaining where the next step may return `Option`, a plain value,
-     *   or a function
+     * Use when you need to chain an `Option` with a next step that may be another
+     * `Option`, a plain value, or a function.
      *
      * **Details**
      *
@@ -1937,8 +1928,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when flexible chaining where the next step may return `Option`, a plain value,
-     *   or a function
+     * Use when you need to chain an `Option` with a next step that may be another
+     * `Option`, a plain value, or a function.
      *
      * **Details**
      *
@@ -1978,8 +1969,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when flexible chaining where the next step may return `Option`, a plain value,
-     *   or a function
+     * Use when you need to chain an `Option` with a next step that may be another
+     * `Option`, a plain value, or a function.
      *
      * **Details**
      *
@@ -2019,8 +2010,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when flexible chaining where the next step may return `Option`, a plain value,
-     *   or a function
+     * Use when you need to chain an `Option` with a next step that may be another
+     * `Option`, a plain value, or a function.
      *
      * **Details**
      *
@@ -2060,8 +2051,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when flexible chaining where the next step may return `Option`, a plain value,
-     *   or a function
+     * Use when you need to chain an `Option` with a next step that may be another
+     * `Option`, a plain value, or a function.
      *
      * **Details**
      *
@@ -2101,8 +2092,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when flexible chaining where the next step may return `Option`, a plain value,
-     *   or a function
+     * Use when you need to chain an `Option` with a next step that may be another
+     * `Option`, a plain value, or a function.
      *
      * **Details**
      *
@@ -2142,8 +2133,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when flexible chaining where the next step may return `Option`, a plain value,
-     *   or a function
+     * Use when you need to chain an `Option` with a next step that may be another
+     * `Option`, a plain value, or a function.
      *
      * **Details**
      *
@@ -2183,8 +2174,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when flexible chaining where the next step may return `Option`, a plain value,
-     *   or a function
+     * Use when you need to chain an `Option` with a next step that may be another
+     * `Option`, a plain value, or a function.
      *
      * **Details**
      *
@@ -2225,8 +2216,8 @@ export declare const andThen: {
  *
  * **When to use**
  *
- * Use when chaining with functions that use `null`/`undefined` instead of `Option`
- * - Navigating deeply nested optional properties
+ * Use when you need to chain optional computations that use `null` or
+ * `undefined` instead of `Option`, such as nested property access.
  *
  * **Details**
  *
@@ -2267,8 +2258,8 @@ export declare const flatMapNullishOr: {
      *
      * **When to use**
      *
-     * Use when chaining with functions that use `null`/`undefined` instead of `Option`
-     * - Navigating deeply nested optional properties
+     * Use when you need to chain optional computations that use `null` or
+     * `undefined` instead of `Option`, such as nested property access.
      *
      * **Details**
      *
@@ -2309,8 +2300,8 @@ export declare const flatMapNullishOr: {
      *
      * **When to use**
      *
-     * Use when chaining with functions that use `null`/`undefined` instead of `Option`
-     * - Navigating deeply nested optional properties
+     * Use when you need to chain optional computations that use `null` or
+     * `undefined` instead of `Option`, such as nested property access.
      *
      * **Details**
      *
@@ -2351,7 +2342,7 @@ export declare const flatMapNullishOr: {
  *
  * **When to use**
  *
- * Use when removing one layer of `Option` nesting
+ * Use when you need to remove one layer of nested `Option`.
  *
  * **Details**
  *
@@ -2382,7 +2373,8 @@ export declare const flatten: <A>(self: Option<Option<A>>) => Option<A>;
  *
  * **When to use**
  *
- * Use to run a side-condition that must succeed, then using the second value
+ * Use when you need two `Option` values to both be `Some`, then keep only the
+ * second value.
  *
  * **Details**
  *
@@ -2413,7 +2405,8 @@ export declare const zipRight: {
      *
      * **When to use**
      *
-     * Use to run a side-condition that must succeed, then using the second value
+     * Use when you need two `Option` values to both be `Some`, then keep only the
+     * second value.
      *
      * **Details**
      *
@@ -2444,7 +2437,8 @@ export declare const zipRight: {
      *
      * **When to use**
      *
-     * Use to run a side-condition that must succeed, then using the second value
+     * Use when you need two `Option` values to both be `Some`, then keep only the
+     * second value.
      *
      * **Details**
      *
@@ -2476,7 +2470,8 @@ export declare const zipRight: {
  *
  * **When to use**
  *
- * Use to run a validation that must succeed, but keeping the original value
+ * Use when you need two `Option` values to both be `Some`, then keep only the
+ * first value.
  *
  * **Details**
  *
@@ -2507,7 +2502,8 @@ export declare const zipLeft: {
      *
      * **When to use**
      *
-     * Use to run a validation that must succeed, but keeping the original value
+     * Use when you need two `Option` values to both be `Some`, then keep only the
+     * first value.
      *
      * **Details**
      *
@@ -2538,7 +2534,8 @@ export declare const zipLeft: {
      *
      * **When to use**
      *
-     * Use to run a validation that must succeed, but keeping the original value
+     * Use when you need two `Option` values to both be `Some`, then keep only the
+     * first value.
      *
      * **Details**
      *
@@ -2571,7 +2568,8 @@ export declare const zipLeft: {
  *
  * **When to use**
  *
- * Use to build pipelines of partial functions (Kleisli composition)
+ * Use when you need to compose two functions that each return an `Option`, so
+ * `None` short-circuits without calling the next function.
  *
  * **Details**
  *
@@ -2610,7 +2608,8 @@ export declare const composeK: {
      *
      * **When to use**
      *
-     * Use to build pipelines of partial functions (Kleisli composition)
+     * Use when you need to compose two functions that each return an `Option`, so
+     * `None` short-circuits without calling the next function.
      *
      * **Details**
      *
@@ -2649,7 +2648,8 @@ export declare const composeK: {
      *
      * **When to use**
      *
-     * Use to build pipelines of partial functions (Kleisli composition)
+     * Use when you need to compose two functions that each return an `Option`, so
+     * `None` short-circuits without calling the next function.
      *
      * **Details**
      *
@@ -2690,8 +2690,8 @@ export declare const composeK: {
  *
  * **When to use**
  *
- * Use to validate a value without transforming it
- * - Adding a side-condition check in a pipeline
+ * Use to validate an `Option`'s present value without transforming it, such as
+ * adding a side-condition check in a pipeline.
  *
  * **Details**
  *
@@ -2727,8 +2727,8 @@ export declare const tap: {
      *
      * **When to use**
      *
-     * Use to validate a value without transforming it
-     * - Adding a side-condition check in a pipeline
+     * Use to validate an `Option`'s present value without transforming it, such as
+     * adding a side-condition check in a pipeline.
      *
      * **Details**
      *
@@ -2764,8 +2764,8 @@ export declare const tap: {
      *
      * **When to use**
      *
-     * Use to validate a value without transforming it
-     * - Adding a side-condition check in a pipeline
+     * Use to validate an `Option`'s present value without transforming it, such as
+     * adding a side-condition check in a pipeline.
      *
      * **Details**
      *
@@ -2801,7 +2801,8 @@ export declare const tap: {
  *
  * **When to use**
  *
- * Use when pairing two optional values together
+ * Use when you need to require two `Option` values to both be `Some` and keep
+ * both values as a tuple.
  *
  * **Details**
  *
@@ -2833,7 +2834,8 @@ export declare const product: <A, B>(self: Option<A>, that: Option<B>) => Option
  *
  * **When to use**
  *
- * Use when collecting several `Option`s of the same type into a non-empty tuple
+ * Use when you need several `Option` values of the same type to all be `Some`
+ * and return them as a non-empty tuple.
  *
  * **Details**
  *
@@ -2868,8 +2870,8 @@ export declare const productMany: <A>(self: Option<A>, collection: Iterable<Opti
  *
  * **When to use**
  *
- * Use when collecting multiple `Option`s into one, preserving the input shape
- * - "All or nothing" combination — any `None` makes the result `None`
+ * Use when you need to combine multiple `Option` values into one while
+ * preserving the input shape, with any `None` making the result `None`.
  *
  * **Details**
  *
@@ -2917,7 +2919,8 @@ export declare const all: <const I extends Iterable<Option<any>> | Record<string
  *
  * **When to use**
  *
- * Use when merging two optional values into a computed result
+ * Use when you need to combine two present `Option` values into a computed
+ * result.
  *
  * **Details**
  *
@@ -2952,7 +2955,8 @@ export declare const zipWith: {
      *
      * **When to use**
      *
-     * Use when merging two optional values into a computed result
+     * Use when you need to combine two present `Option` values into a computed
+     * result.
      *
      * **Details**
      *
@@ -2987,7 +2991,8 @@ export declare const zipWith: {
      *
      * **When to use**
      *
-     * Use when merging two optional values into a computed result
+     * Use when you need to combine two present `Option` values into a computed
+     * result.
      *
      * **Details**
      *
@@ -3023,7 +3028,8 @@ export declare const zipWith: {
  *
  * **When to use**
  *
- * Use when aggregating values from a collection where some may be absent
+ * Use when you need to aggregate values from a collection where some may be
+ * absent.
  *
  * **Details**
  *
@@ -3051,7 +3057,8 @@ export declare const reduceCompact: {
      *
      * **When to use**
      *
-     * Use when aggregating values from a collection where some may be absent
+     * Use when you need to aggregate values from a collection where some may be
+     * absent.
      *
      * **Details**
      *
@@ -3079,7 +3086,8 @@ export declare const reduceCompact: {
      *
      * **When to use**
      *
-     * Use when aggregating values from a collection where some may be absent
+     * Use when you need to aggregate values from a collection where some may be
+     * absent.
      *
      * **Details**
      *
@@ -3108,8 +3116,8 @@ export declare const reduceCompact: {
  *
  * **When to use**
  *
- * Use when interfacing with array-based APIs
- * - Spreading optional values into collections
+ * Use when you need to pass an `Option` to array-based APIs or spread optional
+ * values into collections.
  *
  * **Details**
  *
@@ -3139,7 +3147,8 @@ export declare const toArray: <A>(self: Option<A>) => Array<A>;
  *
  * **When to use**
  *
- * Use when categorizing an optional value into "left" (failure) and "right" (success) channels
+ * Use when you need to split an optional value into "left" and "right"
+ * channels using a `Result`-returning function.
  *
  * **Details**
  *
@@ -3178,7 +3187,8 @@ export declare const partitionMap: {
      *
      * **When to use**
      *
-     * Use when categorizing an optional value into "left" (failure) and "right" (success) channels
+     * Use when you need to split an optional value into "left" and "right"
+     * channels using a `Result`-returning function.
      *
      * **Details**
      *
@@ -3217,7 +3227,8 @@ export declare const partitionMap: {
      *
      * **When to use**
      *
-     * Use when categorizing an optional value into "left" (failure) and "right" (success) channels
+     * Use when you need to split an optional value into "left" and "right"
+     * channels using a `Result`-returning function.
      *
      * **Details**
      *
@@ -3257,7 +3268,8 @@ export declare const partitionMap: {
  *
  * **When to use**
  *
- * Use to transform a present value and discard it when the `Filter` fails.
+ * Use to transform an `Option`'s present value and discard it when the `Filter`
+ * fails.
  *
  * **Details**
  *
@@ -3287,7 +3299,8 @@ export declare const filterMap: {
      *
      * **When to use**
      *
-     * Use to transform a present value and discard it when the `Filter` fails.
+     * Use to transform an `Option`'s present value and discard it when the `Filter`
+     * fails.
      *
      * **Details**
      *
@@ -3317,7 +3330,8 @@ export declare const filterMap: {
      *
      * **When to use**
      *
-     * Use to transform a present value and discard it when the `Filter` fails.
+     * Use to transform an `Option`'s present value and discard it when the `Filter`
+     * fails.
      *
      * **Details**
      *
@@ -3349,8 +3363,8 @@ export declare const filterMap: {
  *
  * **When to use**
  *
- * Use when discarding values that don't meet a condition
- * - Narrowing the type via a refinement predicate
+ * Use when you need to discard an `Option`'s present value when it does not
+ * meet a condition, while narrowing the type via a refinement predicate.
  *
  * **Details**
  *
@@ -3390,8 +3404,8 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * Use when discarding values that don't meet a condition
-     * - Narrowing the type via a refinement predicate
+     * Use when you need to discard an `Option`'s present value when it does not
+     * meet a condition, while narrowing the type via a refinement predicate.
      *
      * **Details**
      *
@@ -3431,8 +3445,8 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * Use when discarding values that don't meet a condition
-     * - Narrowing the type via a refinement predicate
+     * Use when you need to discard an `Option`'s present value when it does not
+     * meet a condition, while narrowing the type via a refinement predicate.
      *
      * **Details**
      *
@@ -3472,8 +3486,8 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * Use when discarding values that don't meet a condition
-     * - Narrowing the type via a refinement predicate
+     * Use when you need to discard an `Option`'s present value when it does not
+     * meet a condition, while narrowing the type via a refinement predicate.
      *
      * **Details**
      *
@@ -3513,8 +3527,8 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * Use when discarding values that don't meet a condition
-     * - Narrowing the type via a refinement predicate
+     * Use when you need to discard an `Option`'s present value when it does not
+     * meet a condition, while narrowing the type via a refinement predicate.
      *
      * **Details**
      *
@@ -3554,7 +3568,8 @@ export declare const filter: {
  *
  * **When to use**
  *
- * Use to compare two `Option` values for structural equality
+ * Use when you need equality to treat two `None` values as equal and compare
+ * two `Some` values with a supplied equality rule.
  *
  * **Details**
  *
@@ -3588,7 +3603,9 @@ export declare const makeEquivalence: <A>(isEquivalent: Equivalence.Equivalence<
  *
  * **When to use**
  *
- * Use to sort collections of `Option` values
+ * Use when you need to sort `Some` and `None` values, with `None` ordered
+ * before present values and present values compared by a supplied ordering
+ * rule.
  *
  * **Details**
  *
@@ -3622,7 +3639,8 @@ export declare const makeOrder: <A>(O: Order<A>) => Order<Option<A>>;
  *
  * **When to use**
  *
- * Use when reusing an existing binary function in an `Option` context
+ * Use when you need to reuse an existing binary function with two `Option`
+ * values.
  *
  * **Details**
  *
@@ -3804,7 +3822,8 @@ export declare const liftPredicate: {
  *
  * **When to use**
  *
- * Use when testing membership with a custom equality check
+ * Use when you need to test whether an `Option` contains a value using a
+ * custom equality check.
  *
  * **Details**
  *
@@ -3843,7 +3862,8 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
  *
  * **When to use**
  *
- * Use when quick membership test with standard equality
+ * Use when you need a quick membership test for an `Option` value using
+ * standard equality.
  *
  * **Details**
  *
@@ -3878,7 +3898,8 @@ export declare const contains: {
      *
      * **When to use**
      *
-     * Use when quick membership test with standard equality
+     * Use when you need a quick membership test for an `Option` value using
+     * standard equality.
      *
      * **Details**
      *
@@ -3913,7 +3934,8 @@ export declare const contains: {
      *
      * **When to use**
      *
-     * Use when quick membership test with standard equality
+     * Use when you need a quick membership test for an `Option` value using
+     * standard equality.
      *
      * **Details**
      *
@@ -4140,7 +4162,8 @@ export declare const exists: {
  *
  * **When to use**
  *
- * Use when beginning a do notation chain by naming the first value
+ * Use when you need to start an `Option` do notation chain by naming the first
+ * value.
  *
  * **Example** (Starting do notation)
  *
@@ -4171,7 +4194,8 @@ export declare const bindTo: {
      *
      * **When to use**
      *
-     * Use when beginning a do notation chain by naming the first value
+     * Use when you need to start an `Option` do notation chain by naming the first
+     * value.
      *
      * **Example** (Starting do notation)
      *
@@ -4204,7 +4228,8 @@ export declare const bindTo: {
      *
      * **When to use**
      *
-     * Use when beginning a do notation chain by naming the first value
+     * Use when you need to start an `Option` do notation chain by naming the first
+     * value.
      *
      * **Example** (Starting do notation)
      *
@@ -4246,7 +4271,8 @@ export {
  *
  * **When to use**
  *
- * Use when binding a derived (non-`Option`) value in a do notation pipeline
+ * Use when you need to bind a derived non-`Option` value in an `Option` do
+ * notation pipeline.
  *
  * **Example** (Adding a computed value)
  *
@@ -4277,7 +4303,7 @@ let_ as let };
  *
  * **When to use**
  *
- * Use when sequencing `Option` computations in do notation
+ * Use when you need to sequence `Option` computations in do notation.
  *
  * **Example** (Binding Option values)
  *
@@ -4309,7 +4335,7 @@ export declare const bind: {
      *
      * **When to use**
      *
-     * Use when sequencing `Option` computations in do notation
+     * Use when you need to sequence `Option` computations in do notation.
      *
      * **Example** (Binding Option values)
      *
@@ -4343,7 +4369,7 @@ export declare const bind: {
      *
      * **When to use**
      *
-     * Use when sequencing `Option` computations in do notation
+     * Use when you need to sequence `Option` computations in do notation.
      *
      * **Example** (Binding Option values)
      *
@@ -4378,7 +4404,8 @@ export declare const bind: {
  *
  * **When to use**
  *
- * Use when starting a do notation pipeline before adding bindings
+ * Use when you need to start an `Option` do notation pipeline before adding
+ * bindings.
  *
  * **Example** (Do notation pipeline)
  *
@@ -4410,8 +4437,8 @@ export declare const Do: Option<{}>;
  *
  * **When to use**
  *
- * Use when writing imperative-style code that chains multiple `Option`s
- * - Readability when many sequential optional steps are involved
+ * Use when you need generator syntax for a sequence of `Option` steps that
+ * should short-circuit on `None`.
  *
  * **Details**
  *
@@ -4450,8 +4477,8 @@ export declare const gen: Gen.Gen<OptionTypeLambda>;
  *
  * **When to use**
  *
- * Use to build a reducer that falls back to the first available value
- * - Combining optional values where either side may be absent
+ * Use to build an `Option` reducer that falls back to the first available value
+ * when either side may be absent.
  *
  * **Details**
  *
@@ -4483,7 +4510,8 @@ export declare function makeReducer<A>(combiner: Combiner.Combiner<A>): Reducer.
  *
  * **When to use**
  *
- * Use when operations that require both values to be present
+ * Use when you need an `Option` combiner that returns `None` unless both
+ * operands are `Some`.
  *
  * **Details**
  *
@@ -4516,8 +4544,8 @@ export declare function makeCombinerFailFast<A>(combiner: Combiner.Combiner<A>):
  *
  * **When to use**
  *
- * Use to wrap an existing `Reducer` to work with `Option` values
- * - Reductions where any `None` should abort the entire result
+ * Use when you need to reduce `Option` values with fail-fast semantics, where
+ * any `None` aborts the entire result instead of being skipped.
  *
  * **Details**
  *