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

package/dist/Option.d.ts

@@ -92,7 +92,7 @@ declare const TypeId = "~effect/data/Option";
  *
  * **When to use**
  *
- * - Representing initial values that may not yet exist
+ * Use to represent initial values that may not yet exist
  * - Returning from partial functions (not defined for all inputs)
  * - Managing optional fields in data structures
  *
@@ -109,7 +109,7 @@ export type Option<A> = None<A> | Some<A>;
  *
  * **When to use**
  *
- * - Use as a type guard target when narrowing via {@link isNone}
+ * Use as a type guard target when narrowing via {@link isNone}
  *
  * **Details**
  *
@@ -138,6 +138,13 @@ export interface None<out A> extends Pipeable, Inspectable {
  * Iterator protocol used to yield an `Option` inside {@link gen}, returning the
  * contained value type back to the generator.
  *
+ * **When to use**
+ *
+ * Use when defining or typing `[Symbol.iterator]()` for `Option` values so
+ * `yield*` can pass the contained value type back into `Option.gen`.
+ *
+ * @see {@link gen} for writing generator-based `Option` code that consumes this iterator protocol
+ *
  * @category Generators
  * @since 4.0.0
  */
@@ -149,7 +156,7 @@ export interface OptionIterator<T extends Option<any>> {
  *
  * **When to use**
  *
- * - Use as a type guard target when narrowing via {@link isSome}
+ * Use as a type guard target when narrowing via {@link isSome}
  * - Access the inner value via `.value`
  *
  * **Details**
@@ -180,6 +187,10 @@ export interface Some<out A> extends Pipeable, Inspectable {
 /**
  * Type-level unification support for `Option` values.
  *
+ * **When to use**
+ *
+ * Use when extending Effect's type-level unification support for `Option`.
+ *
  * **Details**
  *
  * This is used by Effect's `Unify` machinery to preserve the contained value
@@ -197,12 +208,20 @@ export interface OptionUnify<A extends {
 /**
  * Namespace containing utility types for `Option`.
  *
+ * **When to use**
+ *
+ * Use to access type-level helpers associated with `Option`.
+ *
  * @since 2.0.0
  */
 export declare namespace Option {
     /**
      * Extracts the type of the value contained in an `Option`.
      *
+     * **When to use**
+     *
+     * Use to infer the inner value type from an existing `Option` type.
+     *
      * **Example** (Extracting the value type)
      *
      * ```ts
@@ -223,6 +242,10 @@ export declare namespace Option {
 /**
  * Marker interface used by Effect's `Unify` machinery for `Option` values.
  *
+ * **When to use**
+ *
+ * Use when marking generic code so `Option` unification should be ignored.
+ *
  * **Details**
  *
  * This supports type-level unification behavior for `Option`. Users normally
@@ -236,6 +259,10 @@ export interface OptionUnifyIgnore {
 /**
  * Type lambda interface for higher-kinded type encodings with `Option`.
  *
+ * **When to use**
+ *
+ * Use to represent `Option` in higher-kinded type operations.
+ *
  * @category Type Lambdas
  * @since 2.0.0
  */
@@ -247,8 +274,8 @@ export interface OptionTypeLambda extends TypeLambda {
  *
  * **When to use**
  *
- * - Representing a missing or uninitialized value
- * - Returning "no result" from a function
+ * Use to represent a missing or uninitialized value, such as returning "no
+ * result" from a function.
  *
  * **Details**
  *
@@ -279,7 +306,7 @@ export declare const none: <A = never>() => Option<A>;
  *
  * **When to use**
  *
- * - Wrapping a known-present value as `Option`
+ * Use to wrap a known-present value as `Option`
  * - Returning a successful result from a partial function
  *
  * **Details**
@@ -311,8 +338,8 @@ export declare const some: <A>(value: A) => Option<A>;
  *
  * **When to use**
  *
- * - Validating unknown values at runtime boundaries
- * - Type-narrowing in union types
+ * Use to validate unknown values at runtime boundaries, such as type-narrowing
+ * in union types.
  *
  * **Details**
  *
@@ -346,7 +373,7 @@ export declare const isOption: (input: unknown) => input is Option<unknown>;
  *
  * **When to use**
  *
- * - Branching on absence before accessing `.value`
+ * Use when branching on absence before accessing `.value`
  *
  * **Details**
  *
@@ -375,7 +402,7 @@ export declare const isNone: <A>(self: Option<A>) => self is None<A>;
  *
  * **When to use**
  *
- * - Branching on presence before accessing `.value`
+ * Use when branching on presence before accessing `.value`
  *
  * **Details**
  *
@@ -404,7 +431,7 @@ export declare const isSome: <A>(self: Option<A>) => self is Some<A>;
  *
  * **When to use**
  *
- * - Exhaustively handling both branches in one expression
+ * Use when exhaustively handling both branches in one expression
  * - Transforming an `Option` into a plain value
  *
  * **Details**
@@ -438,7 +465,7 @@ export declare const match: {
      *
      * **When to use**
      *
-     * - Exhaustively handling both branches in one expression
+     * Use when exhaustively handling both branches in one expression
      * - Transforming an `Option` into a plain value
      *
      * **Details**
@@ -475,7 +502,7 @@ export declare const match: {
      *
      * **When to use**
      *
-     * - Exhaustively handling both branches in one expression
+     * Use when exhaustively handling both branches in one expression
      * - Transforming an `Option` into a plain value
      *
      * **Details**
@@ -513,7 +540,7 @@ export declare const match: {
  *
  * **When to use**
  *
- * - Turning a parsing function into a type-narrowing predicate
+ * Use when turning a parsing function into a type-narrowing predicate
  * - Filtering arrays with `Array.prototype.filter`
  *
  * **Details**
@@ -555,7 +582,7 @@ export declare const toRefinement: <A, B extends A>(f: (a: A) => Option<B>) => (
  *
  * **When to use**
  *
- * - Safely extracting the head of a collection
+ * Use when safely extracting the head of a collection
  * - Working with generators or lazy iterables
  *
  * **Details**
@@ -586,7 +613,7 @@ export declare const fromIterable: <A>(collection: Iterable<A>) => Option<A>;
  *
  * **When to use**
  *
- * - Discarding the failure channel when you only care about success
+ * Use when discarding the failure channel when you only care about success
  *
  * **Details**
  *
@@ -616,7 +643,7 @@ export declare const getSuccess: <A, E>(self: Result<A, E>) => Option<A>;
  *
  * **When to use**
  *
- * - Extracting the failure when you do not need the success value
+ * Use to extract the failure when you do not need the success value
  *
  * **Details**
  *
@@ -646,7 +673,7 @@ export declare const getFailure: <A, E>(self: Result<A, E>) => Option<E>;
  *
  * **When to use**
  *
- * - Providing a default value for an absent `Option`
+ * Use when providing a default value for an absent `Option`
  * - Unwrapping with lazy evaluation of the fallback
  *
  * **Details**
@@ -680,7 +707,7 @@ export declare const getOrElse: {
      *
      * **When to use**
      *
-     * - Providing a default value for an absent `Option`
+     * Use when providing a default value for an absent `Option`
      * - Unwrapping with lazy evaluation of the fallback
      *
      * **Details**
@@ -714,7 +741,7 @@ export declare const getOrElse: {
      *
      * **When to use**
      *
-     * - Providing a default value for an absent `Option`
+     * Use when providing a default value for an absent `Option`
      * - Unwrapping with lazy evaluation of the fallback
      *
      * **Details**
@@ -749,7 +776,7 @@ export declare const getOrElse: {
  *
  * **When to use**
  *
- * - Chaining fallback `Option` computations
+ * Use when chaining fallback `Option` computations
  * - Building priority chains of optional values
  *
  * **Details**
@@ -782,7 +809,7 @@ export declare const orElse: {
      *
      * **When to use**
      *
-     * - Chaining fallback `Option` computations
+     * Use when chaining fallback `Option` computations
      * - Building priority chains of optional values
      *
      * **Details**
@@ -815,7 +842,7 @@ export declare const orElse: {
      *
      * **When to use**
      *
-     * - Chaining fallback `Option` computations
+     * Use when chaining fallback `Option` computations
      * - Building priority chains of optional values
      *
      * **Details**
@@ -850,7 +877,7 @@ export declare const orElse: {
  *
  * **When to use**
  *
- * - Providing a default plain value (not an `Option`) as fallback
+ * Use when providing a default plain value (not an `Option`) as fallback
  *
  * **Details**
  *
@@ -881,7 +908,7 @@ export declare const orElseSome: {
      *
      * **When to use**
      *
-     * - Providing a default plain value (not an `Option`) as fallback
+     * Use when providing a default plain value (not an `Option`) as fallback
      *
      * **Details**
      *
@@ -912,7 +939,7 @@ export declare const orElseSome: {
      *
      * **When to use**
      *
-     * - Providing a default plain value (not an `Option`) as fallback
+     * Use when providing a default plain value (not an `Option`) as fallback
      *
      * **Details**
      *
@@ -939,12 +966,12 @@ export declare const orElseSome: {
     <A, B>(self: Option<A>, onNone: LazyArg<B>): Option<A | B>;
 };
 /**
- * Like {@link orElse}, but wraps the result in a `Result` to indicate the
- * source of the value.
+ * Returns the first available value and marks whether it came from the fallback.
  *
  * **When to use**
  *
- * - Distinguishing whether a value came from the primary or fallback `Option`
+ * Use when distinguishing whether a value came from the primary or fallback
+ * `Option`.
  *
  * **Details**
  *
@@ -971,12 +998,12 @@ export declare const orElseSome: {
  */
 export declare const orElseResult: {
     /**
-     * Like {@link orElse}, but wraps the result in a `Result` to indicate the
-     * source of the value.
+     * Returns the first available value and marks whether it came from the fallback.
      *
      * **When to use**
      *
-     * - Distinguishing whether a value came from the primary or fallback `Option`
+     * Use when distinguishing whether a value came from the primary or fallback
+     * `Option`.
      *
      * **Details**
      *
@@ -1003,12 +1030,12 @@ export declare const orElseResult: {
      */
     <B>(that: LazyArg<Option<B>>): <A>(self: Option<A>) => Option<Result<B, A>>;
     /**
-     * Like {@link orElse}, but wraps the result in a `Result` to indicate the
-     * source of the value.
+     * Returns the first available value and marks whether it came from the fallback.
      *
      * **When to use**
      *
-     * - Distinguishing whether a value came from the primary or fallback `Option`
+     * Use when distinguishing whether a value came from the primary or fallback
+     * `Option`.
      *
      * **Details**
      *
@@ -1041,7 +1068,7 @@ export declare const orElseResult: {
  *
  * **When to use**
  *
- * - Searching for the first available value in a priority list
+ * Use when searching for the first available value in a priority list
  *
  * **Details**
  *
@@ -1072,7 +1099,7 @@ export declare const firstSomeOf: <T, C extends Iterable<Option<T>> = Iterable<O
  *
  * **When to use**
  *
- * - Bridging from nullable APIs to `Option`
+ * Use when bridging from nullable APIs to `Option`
  * - Wrapping values that may be `null` or `undefined`
  *
  * **Details**
@@ -1109,7 +1136,7 @@ export declare const fromNullishOr: <A>(a: A) => Option<NonNullable<A>>;
  *
  * **When to use**
  *
- * - When `null` is a meaningful value but `undefined` means absent
+ * Use when when `null` is a meaningful value but `undefined` means absent
  *
  * **Details**
  *
@@ -1144,7 +1171,7 @@ export declare const fromUndefinedOr: <A>(a: A) => Option<Exclude<A, undefined>>
  *
  * **When to use**
  *
- * - When `undefined` is a meaningful value but `null` means absent
+ * Use when when `undefined` is a meaningful value but `null` means absent
  *
  * **Details**
  *
@@ -1179,7 +1206,7 @@ export declare const fromNullOr: <A>(a: A) => Option<Exclude<A, null>>;
  *
  * **When to use**
  *
- * - Wrapping existing nullable-returning functions for use in `Option` pipelines
+ * Use to wrap existing nullable-returning functions for use in `Option` pipelines
  *
  * **Details**
  *
@@ -1217,7 +1244,7 @@ export declare const liftNullishOr: <A extends ReadonlyArray<unknown>, B>(f: (..
  *
  * **When to use**
  *
- * - Interoping with APIs that use `null` for missing values
+ * Use when interoping with APIs that use `null` for missing values
  *
  * **Details**
  *
@@ -1248,7 +1275,7 @@ export declare const getOrNull: <A>(self: Option<A>) => A | null;
  *
  * **When to use**
  *
- * - Interoping with APIs that use `undefined` for missing values
+ * Use when interoping with APIs that use `undefined` for missing values
  *
  * **Details**
  *
@@ -1279,7 +1306,7 @@ export declare const getOrUndefined: <A>(self: Option<A>) => A | undefined;
  *
  * **When to use**
  *
- * - Wrapping exception-throwing APIs (e.g. `JSON.parse`) for safe usage
+ * Use to wrap exception-throwing APIs (e.g. `JSON.parse`) for safe usage
  *
  * **Details**
  *
@@ -1311,7 +1338,7 @@ export declare const liftThrowable: <A extends ReadonlyArray<unknown>, B>(f: (..
  *
  * **When to use**
  *
- * - Fail-fast unwrapping when absence is unexpected
+ * Use when fail-fast unwrapping when absence is unexpected
  * - Providing a descriptive error for debugging
  *
  * **Details**
@@ -1343,7 +1370,7 @@ export declare const getOrThrowWith: {
      *
      * **When to use**
      *
-     * - Fail-fast unwrapping when absence is unexpected
+     * Use when fail-fast unwrapping when absence is unexpected
      * - Providing a descriptive error for debugging
      *
      * **Details**
@@ -1375,7 +1402,7 @@ export declare const getOrThrowWith: {
      *
      * **When to use**
      *
-     * - Fail-fast unwrapping when absence is unexpected
+     * Use when fail-fast unwrapping when absence is unexpected
      * - Providing a descriptive error for debugging
      *
      * **Details**
@@ -1408,7 +1435,7 @@ export declare const getOrThrowWith: {
  *
  * **When to use**
  *
- * - Quick fail-fast unwrapping when a generic error is acceptable
+ * Use when quick fail-fast unwrapping when a generic error is acceptable
  *
  * **Details**
  *
@@ -1440,14 +1467,13 @@ export declare const getOrThrow: <A>(self: Option<A>) => A;
  *
  * **When to use**
  *
- * - Applying a pure transformation to an optional value
- * - Chaining transformations in a pipeline
+ * Use to apply a pure transformation to an optional value, especially when
+ * chaining transformations in a pipeline.
  *
  * **Details**
  *
  * - `Some` → applies `f` and wraps the result in a new `Some`
  * - `None` → returns `None` unchanged
- * - Does not mutate the input
  *
  * **Example** (Mapping over an Option)
  *
@@ -1474,14 +1500,13 @@ export declare const map: {
      *
      * **When to use**
      *
-     * - Applying a pure transformation to an optional value
-     * - Chaining transformations in a pipeline
+     * Use to apply a pure transformation to an optional value, especially when
+     * chaining transformations in a pipeline.
      *
      * **Details**
      *
      * - `Some` → applies `f` and wraps the result in a new `Some`
      * - `None` → returns `None` unchanged
-     * - Does not mutate the input
      *
      * **Example** (Mapping over an Option)
      *
@@ -1508,14 +1533,13 @@ export declare const map: {
      *
      * **When to use**
      *
-     * - Applying a pure transformation to an optional value
-     * - Chaining transformations in a pipeline
+     * Use to apply a pure transformation to an optional value, especially when
+     * chaining transformations in a pipeline.
      *
      * **Details**
      *
      * - `Some` → applies `f` and wraps the result in a new `Some`
      * - `None` → returns `None` unchanged
-     * - Does not mutate the input
      *
      * **Example** (Mapping over an Option)
      *
@@ -1542,7 +1566,7 @@ export declare const map: {
  *
  * **When to use**
  *
- * - Preserving presence/absence while discarding the original value
+ * Use when preserving presence/absence while discarding the original value
  *
  * **Details**
  *
@@ -1573,7 +1597,7 @@ export declare const as: {
      *
      * **When to use**
      *
-     * - Preserving presence/absence while discarding the original value
+     * Use when preserving presence/absence while discarding the original value
      *
      * **Details**
      *
@@ -1604,7 +1628,7 @@ export declare const as: {
      *
      * **When to use**
      *
-     * - Preserving presence/absence while discarding the original value
+     * Use when preserving presence/absence while discarding the original value
      *
      * **Details**
      *
@@ -1637,7 +1661,7 @@ export declare const as: {
  *
  * **When to use**
  *
- * - Discarding the value while preserving presence/absence
+ * Use when discarding the value while preserving presence/absence
  *
  * **Details**
  *
@@ -1665,11 +1689,11 @@ export declare const asVoid: <_>(self: Option<_>) => Option<void>;
 declare const void_: Option<void>;
 export { 
 /**
- * A pre-built `Some(undefined)` constant.
+ * Provides a pre-built `Some(undefined)` constant.
  *
  * **When to use**
  *
- * - Returning a "success with no meaningful value" from an `Option`-returning function
+ * Use to return a "success with no meaningful value" from an `Option`-returning function
  *
  * **Example** (Using Option.void)
  *
@@ -1692,8 +1716,8 @@ void_ as void };
  *
  * **When to use**
  *
- * - Chaining computations that each may fail (return `None`)
- * - Sequencing dependent optional operations
+ * Use when chaining dependent optional computations where each step may return
+ * `None`.
  *
  * **Details**
  *
@@ -1738,8 +1762,8 @@ export declare const flatMap: {
      *
      * **When to use**
      *
-     * - Chaining computations that each may fail (return `None`)
-     * - Sequencing dependent optional operations
+     * Use when chaining dependent optional computations where each step may return
+     * `None`.
      *
      * **Details**
      *
@@ -1784,8 +1808,8 @@ export declare const flatMap: {
      *
      * **When to use**
      *
-     * - Chaining computations that each may fail (return `None`)
-     * - Sequencing dependent optional operations
+     * Use when chaining dependent optional computations where each step may return
+     * `None`.
      *
      * **Details**
      *
@@ -1831,7 +1855,7 @@ export declare const flatMap: {
  *
  * **When to use**
  *
- * - Flexible chaining where the next step may return `Option`, a plain value,
+ * Use when flexible chaining where the next step may return `Option`, a plain value,
  *   or a function
  *
  * **Details**
@@ -1872,7 +1896,7 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * - Flexible chaining where the next step may return `Option`, a plain value,
+     * Use when flexible chaining where the next step may return `Option`, a plain value,
      *   or a function
      *
      * **Details**
@@ -1913,7 +1937,7 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * - Flexible chaining where the next step may return `Option`, a plain value,
+     * Use when flexible chaining where the next step may return `Option`, a plain value,
      *   or a function
      *
      * **Details**
@@ -1954,7 +1978,7 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * - Flexible chaining where the next step may return `Option`, a plain value,
+     * Use when flexible chaining where the next step may return `Option`, a plain value,
      *   or a function
      *
      * **Details**
@@ -1995,7 +2019,7 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * - Flexible chaining where the next step may return `Option`, a plain value,
+     * Use when flexible chaining where the next step may return `Option`, a plain value,
      *   or a function
      *
      * **Details**
@@ -2036,7 +2060,7 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * - Flexible chaining where the next step may return `Option`, a plain value,
+     * Use when flexible chaining where the next step may return `Option`, a plain value,
      *   or a function
      *
      * **Details**
@@ -2077,7 +2101,7 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * - Flexible chaining where the next step may return `Option`, a plain value,
+     * Use when flexible chaining where the next step may return `Option`, a plain value,
      *   or a function
      *
      * **Details**
@@ -2118,7 +2142,7 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * - Flexible chaining where the next step may return `Option`, a plain value,
+     * Use when flexible chaining where the next step may return `Option`, a plain value,
      *   or a function
      *
      * **Details**
@@ -2159,7 +2183,7 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * - Flexible chaining where the next step may return `Option`, a plain value,
+     * Use when flexible chaining where the next step may return `Option`, a plain value,
      *   or a function
      *
      * **Details**
@@ -2201,7 +2225,7 @@ export declare const andThen: {
  *
  * **When to use**
  *
- * - Chaining with functions that use `null`/`undefined` instead of `Option`
+ * Use when chaining with functions that use `null`/`undefined` instead of `Option`
  * - Navigating deeply nested optional properties
  *
  * **Details**
@@ -2243,7 +2267,7 @@ export declare const flatMapNullishOr: {
      *
      * **When to use**
      *
-     * - Chaining with functions that use `null`/`undefined` instead of `Option`
+     * Use when chaining with functions that use `null`/`undefined` instead of `Option`
      * - Navigating deeply nested optional properties
      *
      * **Details**
@@ -2285,7 +2309,7 @@ export declare const flatMapNullishOr: {
      *
      * **When to use**
      *
-     * - Chaining with functions that use `null`/`undefined` instead of `Option`
+     * Use when chaining with functions that use `null`/`undefined` instead of `Option`
      * - Navigating deeply nested optional properties
      *
      * **Details**
@@ -2327,7 +2351,7 @@ export declare const flatMapNullishOr: {
  *
  * **When to use**
  *
- * - Removing one layer of `Option` nesting
+ * Use when removing one layer of `Option` nesting
  *
  * **Details**
  *
@@ -2358,7 +2382,7 @@ export declare const flatten: <A>(self: Option<Option<A>>) => Option<A>;
  *
  * **When to use**
  *
- * - Running a side-condition that must succeed, then using the second value
+ * Use to run a side-condition that must succeed, then using the second value
  *
  * **Details**
  *
@@ -2389,7 +2413,7 @@ export declare const zipRight: {
      *
      * **When to use**
      *
-     * - Running a side-condition that must succeed, then using the second value
+     * Use to run a side-condition that must succeed, then using the second value
      *
      * **Details**
      *
@@ -2420,7 +2444,7 @@ export declare const zipRight: {
      *
      * **When to use**
      *
-     * - Running a side-condition that must succeed, then using the second value
+     * Use to run a side-condition that must succeed, then using the second value
      *
      * **Details**
      *
@@ -2452,7 +2476,7 @@ export declare const zipRight: {
  *
  * **When to use**
  *
- * - Running a validation that must succeed, but keeping the original value
+ * Use to run a validation that must succeed, but keeping the original value
  *
  * **Details**
  *
@@ -2483,7 +2507,7 @@ export declare const zipLeft: {
      *
      * **When to use**
      *
-     * - Running a validation that must succeed, but keeping the original value
+     * Use to run a validation that must succeed, but keeping the original value
      *
      * **Details**
      *
@@ -2514,7 +2538,7 @@ export declare const zipLeft: {
      *
      * **When to use**
      *
-     * - Running a validation that must succeed, but keeping the original value
+     * Use to run a validation that must succeed, but keeping the original value
      *
      * **Details**
      *
@@ -2547,7 +2571,7 @@ export declare const zipLeft: {
  *
  * **When to use**
  *
- * - Building pipelines of partial functions (Kleisli composition)
+ * Use to build pipelines of partial functions (Kleisli composition)
  *
  * **Details**
  *
@@ -2586,7 +2610,7 @@ export declare const composeK: {
      *
      * **When to use**
      *
-     * - Building pipelines of partial functions (Kleisli composition)
+     * Use to build pipelines of partial functions (Kleisli composition)
      *
      * **Details**
      *
@@ -2625,7 +2649,7 @@ export declare const composeK: {
      *
      * **When to use**
      *
-     * - Building pipelines of partial functions (Kleisli composition)
+     * Use to build pipelines of partial functions (Kleisli composition)
      *
      * **Details**
      *
@@ -2666,7 +2690,7 @@ export declare const composeK: {
  *
  * **When to use**
  *
- * - Validating a value without transforming it
+ * Use to validate a value without transforming it
  * - Adding a side-condition check in a pipeline
  *
  * **Details**
@@ -2703,7 +2727,7 @@ export declare const tap: {
      *
      * **When to use**
      *
-     * - Validating a value without transforming it
+     * Use to validate a value without transforming it
      * - Adding a side-condition check in a pipeline
      *
      * **Details**
@@ -2740,7 +2764,7 @@ export declare const tap: {
      *
      * **When to use**
      *
-     * - Validating a value without transforming it
+     * Use to validate a value without transforming it
      * - Adding a side-condition check in a pipeline
      *
      * **Details**
@@ -2777,7 +2801,7 @@ export declare const tap: {
  *
  * **When to use**
  *
- * - Pairing two optional values together
+ * Use when pairing two optional values together
  *
  * **Details**
  *
@@ -2809,7 +2833,7 @@ export declare const product: <A, B>(self: Option<A>, that: Option<B>) => Option
  *
  * **When to use**
  *
- * - Collecting several `Option`s of the same type into a non-empty tuple
+ * Use when collecting several `Option`s of the same type into a non-empty tuple
  *
  * **Details**
  *
@@ -2844,7 +2868,7 @@ export declare const productMany: <A>(self: Option<A>, collection: Iterable<Opti
  *
  * **When to use**
  *
- * - Collecting multiple `Option`s into one, preserving the input shape
+ * Use when collecting multiple `Option`s into one, preserving the input shape
  * - "All or nothing" combination — any `None` makes the result `None`
  *
  * **Details**
@@ -2893,7 +2917,7 @@ export declare const all: <const I extends Iterable<Option<any>> | Record<string
  *
  * **When to use**
  *
- * - Merging two optional values into a computed result
+ * Use when merging two optional values into a computed result
  *
  * **Details**
  *
@@ -2928,7 +2952,7 @@ export declare const zipWith: {
      *
      * **When to use**
      *
-     * - Merging two optional values into a computed result
+     * Use when merging two optional values into a computed result
      *
      * **Details**
      *
@@ -2963,7 +2987,7 @@ export declare const zipWith: {
      *
      * **When to use**
      *
-     * - Merging two optional values into a computed result
+     * Use when merging two optional values into a computed result
      *
      * **Details**
      *
@@ -2999,7 +3023,7 @@ export declare const zipWith: {
  *
  * **When to use**
  *
- * - Aggregating values from a collection where some may be absent
+ * Use when aggregating values from a collection where some may be absent
  *
  * **Details**
  *
@@ -3027,7 +3051,7 @@ export declare const reduceCompact: {
      *
      * **When to use**
      *
-     * - Aggregating values from a collection where some may be absent
+     * Use when aggregating values from a collection where some may be absent
      *
      * **Details**
      *
@@ -3055,7 +3079,7 @@ export declare const reduceCompact: {
      *
      * **When to use**
      *
-     * - Aggregating values from a collection where some may be absent
+     * Use when aggregating values from a collection where some may be absent
      *
      * **Details**
      *
@@ -3084,7 +3108,7 @@ export declare const reduceCompact: {
  *
  * **When to use**
  *
- * - Interfacing with array-based APIs
+ * Use when interfacing with array-based APIs
  * - Spreading optional values into collections
  *
  * **Details**
@@ -3115,7 +3139,7 @@ export declare const toArray: <A>(self: Option<A>) => Array<A>;
  *
  * **When to use**
  *
- * - Categorizing an optional value into "left" (failure) and "right" (success) channels
+ * Use when categorizing an optional value into "left" (failure) and "right" (success) channels
  *
  * **Details**
  *
@@ -3154,7 +3178,7 @@ export declare const partitionMap: {
      *
      * **When to use**
      *
-     * - Categorizing an optional value into "left" (failure) and "right" (success) channels
+     * Use when categorizing an optional value into "left" (failure) and "right" (success) channels
      *
      * **Details**
      *
@@ -3193,7 +3217,7 @@ export declare const partitionMap: {
      *
      * **When to use**
      *
-     * - Categorizing an optional value into "left" (failure) and "right" (success) channels
+     * Use when categorizing an optional value into "left" (failure) and "right" (success) channels
      *
      * **Details**
      *
@@ -3231,6 +3255,10 @@ export declare const partitionMap: {
 /**
  * Transforms and filters an `Option` using a `Filter` callback.
  *
+ * **When to use**
+ *
+ * Use to transform a present value and discard it when the `Filter` fails.
+ *
  * **Details**
  *
  * The callback returns a `Result`: `Result.succeed` keeps and transforms the
@@ -3257,6 +3285,10 @@ export declare const filterMap: {
     /**
      * Transforms and filters an `Option` using a `Filter` callback.
      *
+     * **When to use**
+     *
+     * Use to transform a present value and discard it when the `Filter` fails.
+     *
      * **Details**
      *
      * The callback returns a `Result`: `Result.succeed` keeps and transforms the
@@ -3283,6 +3315,10 @@ export declare const filterMap: {
     /**
      * Transforms and filters an `Option` using a `Filter` callback.
      *
+     * **When to use**
+     *
+     * Use to transform a present value and discard it when the `Filter` fails.
+     *
      * **Details**
      *
      * The callback returns a `Result`: `Result.succeed` keeps and transforms the
@@ -3313,7 +3349,7 @@ export declare const filterMap: {
  *
  * **When to use**
  *
- * - Discarding values that don't meet a condition
+ * Use when discarding values that don't meet a condition
  * - Narrowing the type via a refinement predicate
  *
  * **Details**
@@ -3354,7 +3390,7 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * - Discarding values that don't meet a condition
+     * Use when discarding values that don't meet a condition
      * - Narrowing the type via a refinement predicate
      *
      * **Details**
@@ -3395,7 +3431,7 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * - Discarding values that don't meet a condition
+     * Use when discarding values that don't meet a condition
      * - Narrowing the type via a refinement predicate
      *
      * **Details**
@@ -3436,7 +3472,7 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * - Discarding values that don't meet a condition
+     * Use when discarding values that don't meet a condition
      * - Narrowing the type via a refinement predicate
      *
      * **Details**
@@ -3477,7 +3513,7 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * - Discarding values that don't meet a condition
+     * Use when discarding values that don't meet a condition
      * - Narrowing the type via a refinement predicate
      *
      * **Details**
@@ -3518,7 +3554,7 @@ export declare const filter: {
  *
  * **When to use**
  *
- * - Comparing two `Option` values for structural equality
+ * Use to compare two `Option` values for structural equality
  *
  * **Details**
  *
@@ -3552,7 +3588,7 @@ export declare const makeEquivalence: <A>(isEquivalent: Equivalence.Equivalence<
  *
  * **When to use**
  *
- * - Sorting collections of `Option` values
+ * Use to sort collections of `Option` values
  *
  * **Details**
  *
@@ -3586,7 +3622,7 @@ export declare const makeOrder: <A>(O: Order<A>) => Order<Option<A>>;
  *
  * **When to use**
  *
- * - Reusing an existing binary function in an `Option` context
+ * Use when reusing an existing binary function in an `Option` context
  *
  * **Details**
  *
@@ -3622,7 +3658,7 @@ export declare const lift2: <A, B, C>(f: (a: A, b: B) => C) => {
  *
  * **When to use**
  *
- * - Converting a boolean check into an `Option`-returning function
+ * Use to convert a boolean check into an `Option`-returning function
  * - Validating input and wrapping it in `Option`
  *
  * **Details**
@@ -3659,7 +3695,7 @@ export declare const liftPredicate: {
      *
      * **When to use**
      *
-     * - Converting a boolean check into an `Option`-returning function
+     * Use to convert a boolean check into an `Option`-returning function
      * - Validating input and wrapping it in `Option`
      *
      * **Details**
@@ -3695,7 +3731,7 @@ export declare const liftPredicate: {
      *
      * **When to use**
      *
-     * - Converting a boolean check into an `Option`-returning function
+     * Use to convert a boolean check into an `Option`-returning function
      * - Validating input and wrapping it in `Option`
      *
      * **Details**
@@ -3731,7 +3767,7 @@ export declare const liftPredicate: {
      *
      * **When to use**
      *
-     * - Converting a boolean check into an `Option`-returning function
+     * Use to convert a boolean check into an `Option`-returning function
      * - Validating input and wrapping it in `Option`
      *
      * **Details**
@@ -3763,12 +3799,12 @@ export declare const liftPredicate: {
     <B extends A, A = B>(self: B, predicate: Predicate<A>): Option<B>;
 };
 /**
- * Checks if an `Option` contains a value equivalent to the given one, using a
+ * Checks whether an `Option` contains a value equivalent to the given one, using a
  * custom `Equivalence`.
  *
  * **When to use**
  *
- * - Testing membership with a custom equality check
+ * Use when testing membership with a custom equality check
  *
  * **Details**
  *
@@ -3802,12 +3838,12 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
     (self: Option<A>, a: A): boolean;
 };
 /**
- * Checks if an `Option` contains a value equal to the given one, using default
+ * Checks whether an `Option` contains a value equal to the given one, using default
  * structural equality.
  *
  * **When to use**
  *
- * - Quick membership test with standard equality
+ * Use when quick membership test with standard equality
  *
  * **Details**
  *
@@ -3837,12 +3873,12 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
  */
 export declare const contains: {
     /**
-     * Checks if an `Option` contains a value equal to the given one, using default
+     * Checks whether an `Option` contains a value equal to the given one, using default
      * structural equality.
      *
      * **When to use**
      *
-     * - Quick membership test with standard equality
+     * Use when quick membership test with standard equality
      *
      * **Details**
      *
@@ -3872,12 +3908,12 @@ export declare const contains: {
      */
     <A>(a: A): (self: Option<A>) => boolean;
     /**
-     * Checks if an `Option` contains a value equal to the given one, using default
+     * Checks whether an `Option` contains a value equal to the given one, using default
      * structural equality.
      *
      * **When to use**
      *
-     * - Quick membership test with standard equality
+     * Use when quick membership test with standard equality
      *
      * **Details**
      *
@@ -3908,11 +3944,11 @@ export declare const contains: {
     <A>(self: Option<A>, a: A): boolean;
 };
 /**
- * Tests if the value in a `Some` satisfies a predicate or refinement.
+ * Checks whether the value in a `Some` satisfies a predicate or refinement.
  *
  * **When to use**
  *
- * - Checking a condition on an optional value without unwrapping
+ * Use to check a condition on an optional value without unwrapping
  *
  * **Details**
  *
@@ -3946,11 +3982,11 @@ export declare const contains: {
  */
 export declare const exists: {
     /**
-     * Tests if the value in a `Some` satisfies a predicate or refinement.
+     * Checks whether the value in a `Some` satisfies a predicate or refinement.
      *
      * **When to use**
      *
-     * - Checking a condition on an optional value without unwrapping
+     * Use to check a condition on an optional value without unwrapping
      *
      * **Details**
      *
@@ -3984,11 +4020,11 @@ export declare const exists: {
      */
     <A, B extends A>(refinement: Refinement<NoInfer<A>, B>): (self: Option<A>) => self is Option<B>;
     /**
-     * Tests if the value in a `Some` satisfies a predicate or refinement.
+     * Checks whether the value in a `Some` satisfies a predicate or refinement.
      *
      * **When to use**
      *
-     * - Checking a condition on an optional value without unwrapping
+     * Use to check a condition on an optional value without unwrapping
      *
      * **Details**
      *
@@ -4022,11 +4058,11 @@ export declare const exists: {
      */
     <A>(predicate: Predicate<NoInfer<A>>): (self: Option<A>) => boolean;
     /**
-     * Tests if the value in a `Some` satisfies a predicate or refinement.
+     * Checks whether the value in a `Some` satisfies a predicate or refinement.
      *
      * **When to use**
      *
-     * - Checking a condition on an optional value without unwrapping
+     * Use to check a condition on an optional value without unwrapping
      *
      * **Details**
      *
@@ -4060,11 +4096,11 @@ export declare const exists: {
      */
     <A, B extends A>(self: Option<A>, refinement: Refinement<A, B>): self is Option<B>;
     /**
-     * Tests if the value in a `Some` satisfies a predicate or refinement.
+     * Checks whether the value in a `Some` satisfies a predicate or refinement.
      *
      * **When to use**
      *
-     * - Checking a condition on an optional value without unwrapping
+     * Use to check a condition on an optional value without unwrapping
      *
      * **Details**
      *
@@ -4104,7 +4140,7 @@ export declare const exists: {
  *
  * **When to use**
  *
- * - Beginning a do notation chain by naming the first value
+ * Use when beginning a do notation chain by naming the first value
  *
  * **Example** (Starting do notation)
  *
@@ -4135,7 +4171,7 @@ export declare const bindTo: {
      *
      * **When to use**
      *
-     * - Beginning a do notation chain by naming the first value
+     * Use when beginning a do notation chain by naming the first value
      *
      * **Example** (Starting do notation)
      *
@@ -4168,7 +4204,7 @@ export declare const bindTo: {
      *
      * **When to use**
      *
-     * - Beginning a do notation chain by naming the first value
+     * Use when beginning a do notation chain by naming the first value
      *
      * **Example** (Starting do notation)
      *
@@ -4210,7 +4246,7 @@ export {
  *
  * **When to use**
  *
- * - Binding a derived (non-`Option`) value in a do notation pipeline
+ * Use when binding a derived (non-`Option`) value in a do notation pipeline
  *
  * **Example** (Adding a computed value)
  *
@@ -4241,7 +4277,7 @@ let_ as let };
  *
  * **When to use**
  *
- * - Sequencing `Option` computations in do notation
+ * Use when sequencing `Option` computations in do notation
  *
  * **Example** (Binding Option values)
  *
@@ -4273,7 +4309,7 @@ export declare const bind: {
      *
      * **When to use**
      *
-     * - Sequencing `Option` computations in do notation
+     * Use when sequencing `Option` computations in do notation
      *
      * **Example** (Binding Option values)
      *
@@ -4307,7 +4343,7 @@ export declare const bind: {
      *
      * **When to use**
      *
-     * - Sequencing `Option` computations in do notation
+     * Use when sequencing `Option` computations in do notation
      *
      * **Example** (Binding Option values)
      *
@@ -4337,12 +4373,12 @@ export declare const bind: {
     }>;
 };
 /**
- * An `Option` containing an empty record `{}`, used as the starting point for
+ * Provides an `Option` containing an empty record `{}`, used as the starting point for
  * do notation chains.
  *
  * **When to use**
  *
- * - Starting a do notation pipeline before adding bindings
+ * Use when starting a do notation pipeline before adding bindings
  *
  * **Example** (Do notation pipeline)
  *
@@ -4369,12 +4405,12 @@ export declare const bind: {
  */
 export declare const Do: Option<{}>;
 /**
- * Generator-based syntax for `Option`, similar to `async`/`await` but for
+ * Provides generator-based syntax for `Option`, similar to `async`/`await` but for
  * optional values. Yielding a `None` short-circuits the generator to `None`.
  *
  * **When to use**
  *
- * - Writing imperative-style code that chains multiple `Option`s
+ * Use when writing imperative-style code that chains multiple `Option`s
  * - Readability when many sequential optional steps are involved
  *
  * **Details**
@@ -4414,7 +4450,7 @@ export declare const gen: Gen.Gen<OptionTypeLambda>;
  *
  * **When to use**
  *
- * - Building a reducer that falls back to the first available value
+ * Use to build a reducer that falls back to the first available value
  * - Combining optional values where either side may be absent
  *
  * **Details**
@@ -4447,7 +4483,7 @@ export declare function makeReducer<A>(combiner: Combiner.Combiner<A>): Reducer.
  *
  * **When to use**
  *
- * - Operations that require both values to be present
+ * Use when operations that require both values to be present
  *
  * **Details**
  *
@@ -4480,7 +4516,7 @@ export declare function makeCombinerFailFast<A>(combiner: Combiner.Combiner<A>):
  *
  * **When to use**
  *
- * - Wrapping an existing `Reducer` to work with `Option` values
+ * Use to wrap an existing `Reducer` to work with `Option` values
  * - Reductions where any `None` should abort the entire result
  *
  * **Details**