effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Option.ts

@@ -101,7 +101,7 @@ 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
  *
@@ -119,7 +119,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**
  *
@@ -149,6 +149,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
  */
@@ -163,7 +170,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**
@@ -195,6 +202,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
@@ -211,12 +222,20 @@ export interface OptionUnify<A extends { [Unify.typeSymbol]?: any }> {
 /**
  * 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
@@ -238,6 +257,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
@@ -251,6 +274,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
  */
@@ -263,8 +290,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**
  *
@@ -296,7 +323,7 @@ export const none = <A = never>(): Option<A> => option.none
  *
  * **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**
@@ -329,8 +356,8 @@ export const some: <A>(value: A) => Option<A> = option.some
  *
  * **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**
  *
@@ -365,7 +392,7 @@ export const isOption: (input: unknown) => input is Option<unknown> = option.isO
  *
  * **When to use**
  *
- * - Branching on absence before accessing `.value`
+ * Use when branching on absence before accessing `.value`
  *
  * **Details**
  *
@@ -395,7 +422,7 @@ export const isNone: <A>(self: Option<A>) => self is None<A> = option.isNone
  *
  * **When to use**
  *
- * - Branching on presence before accessing `.value`
+ * Use when branching on presence before accessing `.value`
  *
  * **Details**
  *
@@ -425,7 +452,7 @@ export const isSome: <A>(self: Option<A>) => self is Some<A> = option.isSome
  *
  * **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**
@@ -459,7 +486,7 @@ export 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**
@@ -498,7 +525,7 @@ export 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**
@@ -546,7 +573,7 @@ export 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**
@@ -589,7 +616,7 @@ export const toRefinement = <A, B extends A>(f: (a: A) => Option<B>): (a: A) =>
  *
  * **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**
@@ -626,7 +653,7 @@ export 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**
  *
@@ -657,7 +684,7 @@ export const getSuccess: <A, E>(self: Result<A, E>) => Option<A> = result.getSuc
  *
  * **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**
  *
@@ -688,7 +715,7 @@ export const getFailure: <A, E>(self: Result<A, E>) => Option<E> = result.getFai
  *
  * **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**
@@ -722,7 +749,7 @@ export 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**
@@ -756,7 +783,7 @@ export 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**
@@ -795,7 +822,7 @@ export const getOrElse: {
  *
  * **When to use**
  *
- * - Chaining fallback `Option` computations
+ * Use when chaining fallback `Option` computations
  * - Building priority chains of optional values
  *
  * **Details**
@@ -828,7 +855,7 @@ export const orElse: {
    *
    * **When to use**
    *
-   * - Chaining fallback `Option` computations
+   * Use when chaining fallback `Option` computations
    * - Building priority chains of optional values
    *
    * **Details**
@@ -861,7 +888,7 @@ export const orElse: {
    *
    * **When to use**
    *
-   * - Chaining fallback `Option` computations
+   * Use when chaining fallback `Option` computations
    * - Building priority chains of optional values
    *
    * **Details**
@@ -900,7 +927,7 @@ export 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**
  *
@@ -931,7 +958,7 @@ export 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**
    *
@@ -962,7 +989,7 @@ export 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**
    *
@@ -998,7 +1025,7 @@ export const orElseSome: {
  *
  * **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**
  *
@@ -1030,7 +1057,7 @@ export const orElseResult: {
    *
    * **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**
    *
@@ -1062,7 +1089,7 @@ export const orElseResult: {
    *
    * **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**
    *
@@ -1100,7 +1127,7 @@ export 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**
  *
@@ -1142,7 +1169,7 @@ export const firstSomeOf = <T, C extends Iterable<Option<T>> = Iterable<Option<T
  *
  * **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**
@@ -1182,7 +1209,7 @@ export const fromNullishOr = <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**
  *
@@ -1220,7 +1247,7 @@ export const fromUndefinedOr = <A>(
  *
  * **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**
  *
@@ -1258,7 +1285,7 @@ export const fromNullOr = <A>(
  *
  * **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**
  *
@@ -1300,7 +1327,7 @@ export const liftNullishOr = <A extends ReadonlyArray<unknown>, B>(
  *
  * **When to use**
  *
- * - Interoping with APIs that use `null` for missing values
+ * Use when interoping with APIs that use `null` for missing values
  *
  * **Details**
  *
@@ -1332,7 +1359,7 @@ export const getOrNull: <A>(self: Option<A>) => A | null = getOrElse(constNull)
  *
  * **When to use**
  *
- * - Interoping with APIs that use `undefined` for missing values
+ * Use when interoping with APIs that use `undefined` for missing values
  *
  * **Details**
  *
@@ -1364,7 +1391,7 @@ export const getOrUndefined: <A>(self: Option<A>) => A | undefined = getOrElse(c
  *
  * **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**
  *
@@ -1406,7 +1433,7 @@ export const liftThrowable = <A extends ReadonlyArray<unknown>, B>(
  *
  * **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**
@@ -1438,7 +1465,7 @@ export 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**
@@ -1470,7 +1497,7 @@ export 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**
@@ -1509,7 +1536,7 @@ export 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**
  *
@@ -1542,8 +1569,8 @@ export const getOrThrow: <A>(self: Option<A>) => A = getOrThrowWith(() => new Er
  *
  * **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**
  *
@@ -1576,8 +1603,8 @@ export 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**
    *
@@ -1610,8 +1637,8 @@ export 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**
    *
@@ -1648,7 +1675,7 @@ export const map: {
  *
  * **When to use**
  *
- * - Preserving presence/absence while discarding the original value
+ * Use when preserving presence/absence while discarding the original value
  *
  * **Details**
  *
@@ -1679,7 +1706,7 @@ export const as: {
    *
    * **When to use**
    *
-   * - Preserving presence/absence while discarding the original value
+   * Use when preserving presence/absence while discarding the original value
    *
    * **Details**
    *
@@ -1710,7 +1737,7 @@ export const as: {
    *
    * **When to use**
    *
-   * - Preserving presence/absence while discarding the original value
+   * Use when preserving presence/absence while discarding the original value
    *
    * **Details**
    *
@@ -1744,7 +1771,7 @@ export const as: {
  *
  * **When to use**
  *
- * - Discarding the value while preserving presence/absence
+ * Use when discarding the value while preserving presence/absence
  *
  * **Details**
  *
@@ -1777,7 +1804,7 @@ export {
    *
    * **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)
    *
@@ -1802,8 +1829,8 @@ export {
  *
  * **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**
  *
@@ -1848,8 +1875,8 @@ export 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**
    *
@@ -1894,8 +1921,8 @@ export 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**
    *
@@ -1945,7 +1972,7 @@ export 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**
@@ -1986,7 +2013,7 @@ export 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**
@@ -2027,7 +2054,7 @@ export 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**
@@ -2068,7 +2095,7 @@ export 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**
@@ -2109,7 +2136,7 @@ export 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**
@@ -2150,7 +2177,7 @@ export 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**
@@ -2191,7 +2218,7 @@ export 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**
@@ -2232,7 +2259,7 @@ export 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**
@@ -2273,7 +2300,7 @@ export 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**
@@ -2323,7 +2350,7 @@ export 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**
@@ -2365,7 +2392,7 @@ export 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**
@@ -2407,7 +2434,7 @@ export 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**
@@ -2454,7 +2481,7 @@ export const flatMapNullishOr: {
  *
  * **When to use**
  *
- * - Removing one layer of `Option` nesting
+ * Use when removing one layer of `Option` nesting
  *
  * **Details**
  *
@@ -2486,7 +2513,7 @@ export const flatten: <A>(self: Option<Option<A>>) => Option<A> = flatMap(identi
  *
  * **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**
  *
@@ -2517,7 +2544,7 @@ export 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**
    *
@@ -2548,7 +2575,7 @@ export 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**
    *
@@ -2581,7 +2608,7 @@ export 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**
  *
@@ -2612,7 +2639,7 @@ export 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**
    *
@@ -2643,7 +2670,7 @@ export 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**
    *
@@ -2677,7 +2704,7 @@ export const zipLeft: {
  *
  * **When to use**
  *
- * - Building pipelines of partial functions (Kleisli composition)
+ * Use to build pipelines of partial functions (Kleisli composition)
  *
  * **Details**
  *
@@ -2716,7 +2743,7 @@ export const composeK: {
    *
    * **When to use**
    *
-   * - Building pipelines of partial functions (Kleisli composition)
+   * Use to build pipelines of partial functions (Kleisli composition)
    *
    * **Details**
    *
@@ -2755,7 +2782,7 @@ export const composeK: {
    *
    * **When to use**
    *
-   * - Building pipelines of partial functions (Kleisli composition)
+   * Use to build pipelines of partial functions (Kleisli composition)
    *
    * **Details**
    *
@@ -2797,7 +2824,7 @@ export 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**
@@ -2834,7 +2861,7 @@ export 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**
@@ -2871,7 +2898,7 @@ export 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**
@@ -2909,7 +2936,7 @@ export const tap: {
  *
  * **When to use**
  *
- * - Pairing two optional values together
+ * Use when pairing two optional values together
  *
  * **Details**
  *
@@ -2943,7 +2970,7 @@ export const product = <A, B>(self: Option<A>, that: Option<B>): Option<[A, B]>
  *
  * **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**
  *
@@ -2994,7 +3021,7 @@ export const productMany = <A>(
  *
  * **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**
@@ -3070,7 +3097,7 @@ export const all: <const I extends Iterable<Option<any>> | Record<string, Option
  *
  * **When to use**
  *
- * - Merging two optional values into a computed result
+ * Use when merging two optional values into a computed result
  *
  * **Details**
  *
@@ -3105,7 +3132,7 @@ export const zipWith: {
    *
    * **When to use**
    *
-   * - Merging two optional values into a computed result
+   * Use when merging two optional values into a computed result
    *
    * **Details**
    *
@@ -3140,7 +3167,7 @@ export const zipWith: {
    *
    * **When to use**
    *
-   * - Merging two optional values into a computed result
+   * Use when merging two optional values into a computed result
    *
    * **Details**
    *
@@ -3181,7 +3208,7 @@ export 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**
  *
@@ -3209,7 +3236,7 @@ export 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**
    *
@@ -3237,7 +3264,7 @@ export 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**
    *
@@ -3278,7 +3305,7 @@ export const reduceCompact: {
  *
  * **When to use**
  *
- * - Interfacing with array-based APIs
+ * Use when interfacing with array-based APIs
  * - Spreading optional values into collections
  *
  * **Details**
@@ -3310,7 +3337,7 @@ export const toArray = <A>(self: Option<A>): Array<A> => isNone(self) ? [] : [se
  *
  * **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**
  *
@@ -3349,7 +3376,7 @@ export 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**
    *
@@ -3388,7 +3415,7 @@ export 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**
    *
@@ -3436,6 +3463,10 @@ export 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
@@ -3462,6 +3493,10 @@ export 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
@@ -3488,6 +3523,10 @@ export 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
@@ -3525,7 +3564,7 @@ export 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**
@@ -3566,7 +3605,7 @@ export 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**
@@ -3607,7 +3646,7 @@ export 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**
@@ -3648,7 +3687,7 @@ export 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**
@@ -3689,7 +3728,7 @@ export 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**
@@ -3735,7 +3774,7 @@ export const filter: {
  *
  * **When to use**
  *
- * - Comparing two `Option` values for structural equality
+ * Use to compare two `Option` values for structural equality
  *
  * **Details**
  *
@@ -3771,7 +3810,7 @@ export const makeEquivalence = <A>(isEquivalent: Equivalence.Equivalence<A>): Eq
  *
  * **When to use**
  *
- * - Sorting collections of `Option` values
+ * Use to sort collections of `Option` values
  *
  * **Details**
  *
@@ -3807,7 +3846,7 @@ export 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**
  *
@@ -3844,7 +3883,7 @@ export 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**
@@ -3881,7 +3920,7 @@ export const liftPredicate: { // Note: I intentionally avoid using the NoInfer p
    *
    * **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**
@@ -3917,7 +3956,7 @@ export const liftPredicate: { // Note: I intentionally avoid using the NoInfer p
    *
    * **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**
@@ -3953,7 +3992,7 @@ export const liftPredicate: { // Note: I intentionally avoid using the NoInfer p
    *
    * **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**
@@ -3994,7 +4033,7 @@ export const liftPredicate: { // Note: I intentionally avoid using the NoInfer p
  *
  * **When to use**
  *
- * - Testing membership with a custom equality check
+ * Use when testing membership with a custom equality check
  *
  * **Details**
  *
@@ -4034,7 +4073,7 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
  *
  * **When to use**
  *
- * - Quick membership test with standard equality
+ * Use when quick membership test with standard equality
  *
  * **Details**
  *
@@ -4069,7 +4108,7 @@ export const contains: {
    *
    * **When to use**
    *
-   * - Quick membership test with standard equality
+   * Use when quick membership test with standard equality
    *
    * **Details**
    *
@@ -4104,7 +4143,7 @@ export const contains: {
    *
    * **When to use**
    *
-   * - Quick membership test with standard equality
+   * Use when quick membership test with standard equality
    *
    * **Details**
    *
@@ -4140,7 +4179,7 @@ export const contains: {
  *
  * **When to use**
  *
- * - Checking a condition on an optional value without unwrapping
+ * Use to check a condition on an optional value without unwrapping
  *
  * **Details**
  *
@@ -4178,7 +4217,7 @@ export const exists: {
    *
    * **When to use**
    *
-   * - Checking a condition on an optional value without unwrapping
+   * Use to check a condition on an optional value without unwrapping
    *
    * **Details**
    *
@@ -4216,7 +4255,7 @@ export const exists: {
    *
    * **When to use**
    *
-   * - Checking a condition on an optional value without unwrapping
+   * Use to check a condition on an optional value without unwrapping
    *
    * **Details**
    *
@@ -4254,7 +4293,7 @@ export const exists: {
    *
    * **When to use**
    *
-   * - Checking a condition on an optional value without unwrapping
+   * Use to check a condition on an optional value without unwrapping
    *
    * **Details**
    *
@@ -4292,7 +4331,7 @@ export const exists: {
    *
    * **When to use**
    *
-   * - Checking a condition on an optional value without unwrapping
+   * Use to check a condition on an optional value without unwrapping
    *
    * **Details**
    *
@@ -4341,7 +4380,7 @@ export 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)
  *
@@ -4376,7 +4415,7 @@ export 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)
    *
@@ -4411,7 +4450,7 @@ export 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)
    *
@@ -4456,7 +4495,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)
    *
@@ -4489,7 +4528,7 @@ export {
  *
  * **When to use**
  *
- * - Sequencing `Option` computations in do notation
+ * Use when sequencing `Option` computations in do notation
  *
  * **Example** (Binding Option values)
  *
@@ -4521,7 +4560,7 @@ export const bind: {
    *
    * **When to use**
    *
-   * - Sequencing `Option` computations in do notation
+   * Use when sequencing `Option` computations in do notation
    *
    * **Example** (Binding Option values)
    *
@@ -4553,7 +4592,7 @@ export const bind: {
    *
    * **When to use**
    *
-   * - Sequencing `Option` computations in do notation
+   * Use when sequencing `Option` computations in do notation
    *
    * **Example** (Binding Option values)
    *
@@ -4591,7 +4630,7 @@ export const bind: {
  *
  * **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)
  *
@@ -4624,7 +4663,7 @@ export const Do: Option<{}> = some({})
  *
  * **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**
@@ -4677,7 +4716,7 @@ export const gen: Gen.Gen<OptionTypeLambda> = (...args) => {
  *
  * **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**
@@ -4717,7 +4756,7 @@ export function makeReducer<A>(combiner: Combiner.Combiner<A>): Reducer.Reducer<
  *
  * **When to use**
  *
- * - Operations that require both values to be present
+ * Use when operations that require both values to be present
  *
  * **Details**
  *
@@ -4756,7 +4795,7 @@ export function makeCombinerFailFast<A>(combiner: Combiner.Combiner<A>): Combine
  *
  * **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**