effect 4.0.0-beta.73 → 4.0.0-beta.75

package/dist/Option.d.ts

@@ -145,7 +145,7 @@ export interface None<out A> extends Pipeable, Inspectable {
  *
  * @see {@link gen} for writing generator-based `Option` code that consumes this iterator protocol
  *
- * @category Generators
+ * @category generators
  * @since 4.0.0
  */
 export interface OptionIterator<T extends Option<any>> {
@@ -261,9 +261,10 @@ 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
+ * @category type lambdas
  * @since 2.0.0
  */
 export interface OptionTypeLambda extends TypeLambda {
@@ -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**
  *
@@ -456,7 +457,7 @@ export declare const isSome: <A>(self: Option<A>) => self is Some<A>;
  *
  * @see {@link getOrElse} for unwrapping with a default
  *
- * @category Pattern matching
+ * @category pattern matching
  * @since 2.0.0
  */
 export declare const match: {
@@ -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**
      *
@@ -490,7 +491,7 @@ export declare const match: {
      *
      * @see {@link getOrElse} for unwrapping with a default
      *
-     * @category Pattern matching
+     * @category pattern matching
      * @since 2.0.0
      */
     <B, A, C = B>(options: {
@@ -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**
      *
@@ -527,7 +528,7 @@ export declare const match: {
      *
      * @see {@link getOrElse} for unwrapping with a default
      *
-     * @category Pattern matching
+     * @category pattern matching
      * @since 2.0.0
      */
     <A, B, C = B>(self: Option<A>, options: {
@@ -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**
  *
@@ -2823,7 +2824,7 @@ export declare const tap: {
  * @see {@link zipWith} to combine with a function instead of a tuple
  * @see {@link all} to combine many `Option`s
  *
- * @category Combining
+ * @category combining
  * @since 2.0.0
  */
 export declare const product: <A, B>(self: Option<A>, that: Option<B>) => Option<[A, B]>;
@@ -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**
  *
@@ -2858,7 +2860,7 @@ export declare const product: <A, B>(self: Option<A>, that: Option<B>) => Option
  * @see {@link product} for combining exactly two
  * @see {@link all} for tuples, structs, and iterables
  *
- * @category Combining
+ * @category combining
  * @since 2.0.0
  */
 export declare const productMany: <A>(self: Option<A>, collection: Iterable<Option<A>>) => Option<[A, ...Array<A>]>;
@@ -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**
  *
@@ -2904,7 +2906,7 @@ export declare const productMany: <A>(self: Option<A>, collection: Iterable<Opti
  * @see {@link product} for combining exactly two
  * @see {@link productMany} for a homogeneous collection
  *
- * @category Combining
+ * @category combining
  * @since 2.0.0
  */
 export declare const all: <const I extends Iterable<Option<any>> | Record<string, Option<any>>>(input: I) => [I] extends [ReadonlyArray<Option<any>>] ? Option<{
@@ -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**
  *
@@ -3042,7 +3048,7 @@ export declare const zipWith: {
  * // Output: 3
  * ```
  *
- * @category Reducing
+ * @category reducing
  * @since 2.0.0
  */
 export declare const reduceCompact: {
@@ -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**
      *
@@ -3070,7 +3077,7 @@ export declare const reduceCompact: {
      * // Output: 3
      * ```
      *
-     * @category Reducing
+     * @category reducing
      * @since 2.0.0
      */
     <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<Option<A>>) => B;
@@ -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**
      *
@@ -3098,7 +3106,7 @@ export declare const reduceCompact: {
      * // Output: 3
      * ```
      *
-     * @category Reducing
+     * @category reducing
      * @since 2.0.0
      */
     <A, B>(self: Iterable<Option<A>>, b: B, f: (b: B, a: A) => B): B;
@@ -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**
  *
@@ -3579,7 +3594,7 @@ export declare const filter: {
  * // Output: true
  * ```
  *
- * @category Equivalence
+ * @category instances
  * @since 4.0.0
  */
 export declare const makeEquivalence: <A>(isEquivalent: Equivalence.Equivalence<A>) => Equivalence.Equivalence<Option<A>>;
@@ -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**
  *
@@ -3613,7 +3630,7 @@ export declare const makeEquivalence: <A>(isEquivalent: Equivalence.Equivalence<
  * // Output: -1
  * ```
  *
- * @category Sorting
+ * @category sorting
  * @since 4.0.0
  */
 export declare const makeOrder: <A>(O: Order<A>) => Order<Option<A>>;
@@ -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**
  *
@@ -3645,7 +3663,7 @@ export declare const makeOrder: <A>(O: Order<A>) => Order<Option<A>>;
  *
  * @see {@link zipWith} for a non-lifted variant
  *
- * @category Lifting
+ * @category lifting
  * @since 2.0.0
  */
 export declare const lift2: <A, B, C>(f: (a: A, b: B) => C) => {
@@ -3684,7 +3702,7 @@ export declare const lift2: <A, B, C>(f: (a: A, b: B) => C) => {
  * @see {@link filter} to apply a predicate to an existing `Option`
  * @see {@link toRefinement} for the inverse direction
  *
- * @category Lifting
+ * @category lifting
  * @since 2.0.0
  */
 export declare const liftPredicate: {
@@ -3721,7 +3739,7 @@ export declare const liftPredicate: {
      * @see {@link filter} to apply a predicate to an existing `Option`
      * @see {@link toRefinement} for the inverse direction
      *
-     * @category Lifting
+     * @category lifting
      * @since 2.0.0
      */
     <B extends A, A = B>(predicate: Predicate<A>): (b: B) => Option<B>;
@@ -3757,7 +3775,7 @@ export declare const liftPredicate: {
      * @see {@link filter} to apply a predicate to an existing `Option`
      * @see {@link toRefinement} for the inverse direction
      *
-     * @category Lifting
+     * @category lifting
      * @since 2.0.0
      */
     <A, B extends A>(self: A, refinement: Refinement<A, B>): Option<B>;
@@ -3793,7 +3811,7 @@ export declare const liftPredicate: {
      * @see {@link filter} to apply a predicate to an existing `Option`
      * @see {@link toRefinement} for the inverse direction
      *
-     * @category Lifting
+     * @category lifting
      * @since 2.0.0
      */
     <B extends A, A = B>(self: B, predicate: Predicate<A>): Option<B>;
@@ -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**
  *
@@ -3830,7 +3849,7 @@ export declare const liftPredicate: {
  *
  * @see {@link contains} for a version using default equality
  *
- * @category Elements
+ * @category elements
  * @since 2.0.0
  */
 export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boolean) => {
@@ -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**
  *
@@ -3868,7 +3888,7 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
  * @see {@link containsWith} for custom equality
  * @see {@link exists} to test with a predicate
  *
- * @category Elements
+ * @category elements
  * @since 2.0.0
  */
 export declare const contains: {
@@ -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**
      *
@@ -3903,7 +3924,7 @@ export declare const contains: {
      * @see {@link containsWith} for custom equality
      * @see {@link exists} to test with a predicate
      *
-     * @category Elements
+     * @category elements
      * @since 2.0.0
      */
     <A>(a: A): (self: Option<A>) => boolean;
@@ -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**
      *
@@ -3938,7 +3960,7 @@ export declare const contains: {
      * @see {@link containsWith} for custom equality
      * @see {@link exists} to test with a predicate
      *
-     * @category Elements
+     * @category elements
      * @since 2.0.0
      */
     <A>(self: Option<A>, a: A): boolean;
@@ -3977,7 +3999,7 @@ export declare const contains: {
  * @see {@link filter} to keep or discard based on a predicate
  * @see {@link contains} to test for a specific value
  *
- * @category Elements
+ * @category elements
  * @since 2.0.0
  */
 export declare const exists: {
@@ -4015,7 +4037,7 @@ export declare const exists: {
      * @see {@link filter} to keep or discard based on a predicate
      * @see {@link contains} to test for a specific value
      *
-     * @category Elements
+     * @category elements
      * @since 2.0.0
      */
     <A, B extends A>(refinement: Refinement<NoInfer<A>, B>): (self: Option<A>) => self is Option<B>;
@@ -4053,7 +4075,7 @@ export declare const exists: {
      * @see {@link filter} to keep or discard based on a predicate
      * @see {@link contains} to test for a specific value
      *
-     * @category Elements
+     * @category elements
      * @since 2.0.0
      */
     <A>(predicate: Predicate<NoInfer<A>>): (self: Option<A>) => boolean;
@@ -4091,7 +4113,7 @@ export declare const exists: {
      * @see {@link filter} to keep or discard based on a predicate
      * @see {@link contains} to test for a specific value
      *
-     * @category Elements
+     * @category elements
      * @since 2.0.0
      */
     <A, B extends A>(self: Option<A>, refinement: Refinement<A, B>): self is Option<B>;
@@ -4129,7 +4151,7 @@ export declare const exists: {
      * @see {@link filter} to keep or discard based on a predicate
      * @see {@link contains} to test for a specific value
      *
-     * @category Elements
+     * @category elements
      * @since 2.0.0
      */
     <A>(self: Option<A>, predicate: Predicate<A>): boolean;
@@ -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)
  *
@@ -4161,7 +4184,7 @@ export declare const exists: {
  * @see {@link bind} to add `Option` values
  * @see {@link let_ let} to add plain values
  *
- * @category Do notation
+ * @category do notation
  * @since 2.0.0
  */
 export declare const bindTo: {
@@ -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)
      *
@@ -4192,7 +4216,7 @@ export declare const bindTo: {
      * @see {@link bind} to add `Option` values
      * @see {@link let_ let} to add plain values
      *
-     * @category Do notation
+     * @category do notation
      * @since 2.0.0
      */
     <N extends string>(name: N): <A>(self: Option<A>) => Option<{
@@ -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)
      *
@@ -4225,7 +4250,7 @@ export declare const bindTo: {
      * @see {@link bind} to add `Option` values
      * @see {@link let_ let} to add plain values
      *
-     * @category Do notation
+     * @category do notation
      * @since 2.0.0
      */
     <A, N extends string>(self: Option<A>, name: N): Option<{
@@ -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)
  *
@@ -4267,7 +4293,7 @@ export {
  * @see {@link bind} to add `Option` values
  * @see {@link bindTo} to start by naming an existing `Option`
  *
- * @category Do notation
+ * @category do notation
  * @since 2.0.0
  */
 let_ as let };
@@ -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)
  *
@@ -4299,7 +4325,7 @@ let_ as let };
  * @see {@link let_ let} to add plain values
  * @see {@link bindTo} to start by naming an existing `Option`
  *
- * @category Do notation
+ * @category do notation
  * @since 2.0.0
  */
 export declare const bind: {
@@ -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)
      *
@@ -4331,7 +4357,7 @@ export declare const bind: {
      * @see {@link let_ let} to add plain values
      * @see {@link bindTo} to start by naming an existing `Option`
      *
-     * @category Do notation
+     * @category do notation
      * @since 2.0.0
      */
     <N extends string, A extends object, B>(name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => Option<B>): (self: Option<A>) => Option<{
@@ -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)
      *
@@ -4365,7 +4391,7 @@ export declare const bind: {
      * @see {@link let_ let} to add plain values
      * @see {@link bindTo} to start by naming an existing `Option`
      *
-     * @category Do notation
+     * @category do notation
      * @since 2.0.0
      */
     <A extends object, N extends string, B>(self: Option<A>, name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => Option<B>): Option<{
@@ -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)
  *
@@ -4400,7 +4427,7 @@ export declare const bind: {
  * @see {@link let_ let} to add plain values
  * @see {@link bindTo} to start by naming an existing `Option`
  *
- * @category Do notation
+ * @category do notation
  * @since 2.0.0
  */
 export declare const Do: Option<{}>;
@@ -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**
  *
@@ -4440,7 +4467,7 @@ export declare const Do: Option<{}>;
  *
  * @see {@link Do} / {@link bind} for the do notation alternative
  *
- * @category Generators
+ * @category generators
  * @since 2.0.0
  */
 export declare const gen: Gen.Gen<OptionTypeLambda>;
@@ -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**
  *