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

package/dist/Array.d.ts

@@ -9,12 +9,12 @@ import * as Reducer from "./Reducer.ts";
 import * as Result from "./Result.ts";
 import type { NoInfer, TupleOf } from "./Types.ts";
 /**
- * Reference to the global `Array` constructor.
+ * Exposes the global array constructor.
  *
  * **When to use**
  *
- * Use this when you need the native `Array` constructor while the `Array`
- * namespace is in scope (e.g. `Array.Array.isArray`, `Array.Array.from`).
+ * Use to access native JavaScript array constructor methods such as `isArray`
+ * or `from` from the Effect module namespace.
  *
  * **Example** (Using the Array constructor)
  *
@@ -43,7 +43,7 @@ export interface ReadonlyArrayTypeLambda extends TypeLambda {
  *
  * **When to use**
  *
- * Use this type when you need to ensure non-emptiness at the type level while
+ * Use when you use this type when you need to ensure non-emptiness at the type level while
  * preventing mutation. Many Array module functions accept or return this type.
  *
  * **Example** (Typing a non-empty array)
@@ -65,6 +65,11 @@ export type NonEmptyReadonlyArray<A> = readonly [A, ...Array<A>];
 /**
  * A mutable array guaranteed to have at least one element.
  *
+ * **When to use**
+ *
+ * Use when mutation is acceptable and non-emptiness must be tracked at the type
+ * level.
+ *
  * **Details**
  *
  * This is the mutable counterpart of {@link NonEmptyReadonlyArray}. Most Array
@@ -92,7 +97,7 @@ export type NonEmptyArray<A> = [A, ...Array<A>];
  *
  * **When to use**
  *
- * - Use when you have literal values and want a typed non-empty array.
+ * Use when you have literal values and want a typed non-empty array.
  * - The element type is inferred as the union of all arguments.
  * - Always returns a `NonEmptyArray` since at least one argument is required.
  *
@@ -117,7 +122,7 @@ export declare const make: <Elements extends NonEmptyArray<unknown>>(...elements
  *
  * **When to use**
  *
- * - Use when you need a pre-sized array and will fill it imperatively.
+ * Use when you need a pre-sized array and will fill it imperatively.
  * - Elements are typed as `A | undefined` since slots are empty.
  * - Prefer {@link makeBy} when you can compute each element from its index.
  *
@@ -141,7 +146,7 @@ export declare const allocate: <A = never>(n: number) => Array<A | undefined>;
  *
  * **When to use**
  *
- * - Use when you need an array whose values depend on the index.
+ * Use when you need an array whose values depend on the index.
  * - `n` is normalized to an integer >= 1 — always returns at least one element.
  * - Dual: `Array.makeBy(5, f)` or `pipe(5, Array.makeBy(f))`.
  *
@@ -166,7 +171,7 @@ export declare const makeBy: {
      *
      * **When to use**
      *
-     * - Use when you need an array whose values depend on the index.
+     * Use when you need an array whose values depend on the index.
      * - `n` is normalized to an integer >= 1 — always returns at least one element.
      * - Dual: `Array.makeBy(5, f)` or `pipe(5, Array.makeBy(f))`.
      *
@@ -191,7 +196,7 @@ export declare const makeBy: {
      *
      * **When to use**
      *
-     * - Use when you need an array whose values depend on the index.
+     * Use when you need an array whose values depend on the index.
      * - `n` is normalized to an integer >= 1 — always returns at least one element.
      * - Dual: `Array.makeBy(5, f)` or `pipe(5, Array.makeBy(f))`.
      *
@@ -218,7 +223,7 @@ export declare const makeBy: {
  *
  * **When to use**
  *
- * - Use when you need a sequence of consecutive integers.
+ * Use when you need a sequence of consecutive integers.
  * - If `start > end`, returns `[start]`.
  * - Always returns a `NonEmptyArray`.
  *
@@ -242,7 +247,7 @@ export declare const range: (start: number, end: number) => NonEmptyArray<number
  *
  * **When to use**
  *
- * - Use when you need multiple copies of the same value.
+ * Use when you need multiple copies of the same value.
  * - `n` is normalized to an integer >= 1 — always returns at least one element.
  * - Dual: `Array.replicate("a", 3)` or `pipe("a", Array.replicate(3))`.
  *
@@ -266,7 +271,7 @@ export declare const replicate: {
      *
      * **When to use**
      *
-     * - Use when you need multiple copies of the same value.
+     * Use when you need multiple copies of the same value.
      * - `n` is normalized to an integer >= 1 — always returns at least one element.
      * - Dual: `Array.replicate("a", 3)` or `pipe("a", Array.replicate(3))`.
      *
@@ -290,7 +295,7 @@ export declare const replicate: {
      *
      * **When to use**
      *
-     * - Use when you need multiple copies of the same value.
+     * Use when you need multiple copies of the same value.
      * - `n` is normalized to an integer >= 1 — always returns at least one element.
      * - Dual: `Array.replicate("a", 3)` or `pipe("a", Array.replicate(3))`.
      *
@@ -313,6 +318,10 @@ export declare const replicate: {
 /**
  * Converts an `Iterable` to an `Array`.
  *
+ * **When to use**
+ *
+ * Use to convert any `Iterable` (Set, Generator, etc.) into an array.
+ *
  * **Details**
  *
  * - If the input is already an array, returns it **by reference** (no copy).
@@ -339,6 +348,11 @@ export declare const fromIterable: <A>(collection: Iterable<A>) => Array<A>;
 /**
  * Normalizes a value that is either a single element or an array into an array.
  *
+ * **When to use**
+ *
+ * Use to normalize input that may be a single value or an array into a consistent
+ * array.
+ *
  * **Details**
  *
  * - If the input is already an array, returns it by reference.
@@ -364,6 +378,11 @@ export declare const ensure: <A>(self: ReadonlyArray<A> | A) => Array<A>;
 /**
  * Converts a record into an array of `[key, value]` tuples.
  *
+ * **When to use**
+ *
+ * Use to convert a record into an array of key-value tuples for iteration or
+ * transformation.
+ *
  * **Details**
  *
  * - Key order follows `Object.entries` semantics.
@@ -378,6 +397,9 @@ export declare const ensure: <A>(self: ReadonlyArray<A> | A) => Array<A>;
  * console.log(result) // [["a", 1], ["b", 2], ["c", 3]]
  * ```
  *
+ * @see {@link Record.toEntries} the equivalent function from the Record module
+ * @see {@link Record.fromEntries} to build a record from an array of tuples
+ *
  * @category converting
  * @since 2.0.0
  */
@@ -385,6 +407,10 @@ export declare const fromRecord: <K extends string, A>(self: Readonly<Record<K,
 /**
  * Converts an `Option` to an array: `Some(a)` becomes `[a]`, `None` becomes `[]`.
  *
+ * **When to use**
+ *
+ * Use to convert a single `Option` into an array for downstream array operations.
+ *
  * **Example** (Option to array)
  *
  * ```ts
@@ -405,7 +431,7 @@ export declare const fromOption: <A>(self: Option.Option<A>) => Array<A>;
  *
  * **When to use**
  *
- * - Use when you need to branch on whether an array has elements.
+ * Use when you need to branch on whether an array has elements.
  * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
  * - Dual: data-first or data-last.
  *
@@ -434,7 +460,7 @@ export declare const match: {
      *
      * **When to use**
      *
-     * - Use when you need to branch on whether an array has elements.
+     * Use when you need to branch on whether an array has elements.
      * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
      * - Dual: data-first or data-last.
      *
@@ -466,7 +492,7 @@ export declare const match: {
      *
      * **When to use**
      *
-     * - Use when you need to branch on whether an array has elements.
+     * Use when you need to branch on whether an array has elements.
      * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
      * - Dual: data-first or data-last.
      *
@@ -498,10 +524,14 @@ export declare const match: {
  * Pattern-matches on an array from the left, providing the first element and
  * the remaining elements separately.
  *
+ * **When to use**
+ *
+ * Use to pattern-match when you need the first element and remaining elements as
+ * separate values.
+ *
  * **Details**
  *
- * - `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
- * - Use when you want to process the first element differently from the rest.
+ * `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
  *
  * **Example** (Head and tail destructuring)
  *
@@ -527,10 +557,14 @@ export declare const matchLeft: {
      * Pattern-matches on an array from the left, providing the first element and
      * the remaining elements separately.
      *
+     * **When to use**
+     *
+     * Use to pattern-match when you need the first element and remaining elements as
+     * separate values.
+     *
      * **Details**
      *
-     * - `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
-     * - Use when you want to process the first element differently from the rest.
+     * `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
      *
      * **Example** (Head and tail destructuring)
      *
@@ -559,10 +593,14 @@ export declare const matchLeft: {
      * Pattern-matches on an array from the left, providing the first element and
      * the remaining elements separately.
      *
+     * **When to use**
+     *
+     * Use to pattern-match when you need the first element and remaining elements as
+     * separate values.
+     *
      * **Details**
      *
-     * - `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
-     * - Use when you want to process the first element differently from the rest.
+     * `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
      *
      * **Example** (Head and tail destructuring)
      *
@@ -592,10 +630,14 @@ export declare const matchLeft: {
  * Pattern-matches on an array from the right, providing all elements except the
  * last and the last element separately.
  *
+ * **When to use**
+ *
+ * Use to pattern-match when you need all but the last element and the last element
+ * as separate values.
+ *
  * **Details**
  *
- * - `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
- * - Use when you want to process the last element differently from the rest.
+ * `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
  *
  * **Example** (Init and last destructuring)
  *
@@ -621,10 +663,14 @@ export declare const matchRight: {
      * Pattern-matches on an array from the right, providing all elements except the
      * last and the last element separately.
      *
+     * **When to use**
+     *
+     * Use to pattern-match when you need all but the last element and the last element
+     * as separate values.
+     *
      * **Details**
      *
-     * - `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
-     * - Use when you want to process the last element differently from the rest.
+     * `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
      *
      * **Example** (Init and last destructuring)
      *
@@ -653,10 +699,14 @@ export declare const matchRight: {
      * Pattern-matches on an array from the right, providing all elements except the
      * last and the last element separately.
      *
+     * **When to use**
+     *
+     * Use to pattern-match when you need all but the last element and the last element
+     * as separate values.
+     *
      * **Details**
      *
-     * - `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
-     * - Use when you want to process the last element differently from the rest.
+     * `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
      *
      * **Example** (Init and last destructuring)
      *
@@ -685,10 +735,13 @@ export declare const matchRight: {
 /**
  * Adds a single element to the front of an iterable, returning a `NonEmptyArray`.
  *
+ * **When to use**
+ *
+ * Use to add a single element at the start of an iterable and get a `NonEmptyArray`.
+ *
  * **Details**
  *
  * - Always returns a non-empty array.
- * - Does not mutate the input.
  *
  * **Example** (Prepending an element)
  *
@@ -709,10 +762,13 @@ export declare const prepend: {
     /**
      * Adds a single element to the front of an iterable, returning a `NonEmptyArray`.
      *
+     * **When to use**
+     *
+     * Use to add a single element at the start of an iterable and get a `NonEmptyArray`.
+     *
      * **Details**
      *
      * - Always returns a non-empty array.
-     * - Does not mutate the input.
      *
      * **Example** (Prepending an element)
      *
@@ -733,10 +789,13 @@ export declare const prepend: {
     /**
      * Adds a single element to the front of an iterable, returning a `NonEmptyArray`.
      *
+     * **When to use**
+     *
+     * Use to add a single element at the start of an iterable and get a `NonEmptyArray`.
+     *
      * **Details**
      *
      * - Always returns a non-empty array.
-     * - Does not mutate the input.
      *
      * **Example** (Prepending an element)
      *
@@ -758,10 +817,13 @@ export declare const prepend: {
 /**
  * Prepends all elements from a prefix iterable to the front of an array.
  *
+ * **When to use**
+ *
+ * Use to prepend multiple elements from an iterable to the front of an array.
+ *
  * **Details**
  *
  * - If either input is non-empty, the result is a `NonEmptyArray`.
- * - Does not mutate the input.
  *
  * **Example** (Prepending multiple elements)
  *
@@ -782,10 +844,13 @@ export declare const prependAll: {
     /**
      * Prepends all elements from a prefix iterable to the front of an array.
      *
+     * **When to use**
+     *
+     * Use to prepend multiple elements from an iterable to the front of an array.
+     *
      * **Details**
      *
      * - If either input is non-empty, the result is a `NonEmptyArray`.
-     * - Does not mutate the input.
      *
      * **Example** (Prepending multiple elements)
      *
@@ -806,10 +871,13 @@ export declare const prependAll: {
     /**
      * Prepends all elements from a prefix iterable to the front of an array.
      *
+     * **When to use**
+     *
+     * Use to prepend multiple elements from an iterable to the front of an array.
+     *
      * **Details**
      *
      * - If either input is non-empty, the result is a `NonEmptyArray`.
-     * - Does not mutate the input.
      *
      * **Example** (Prepending multiple elements)
      *
@@ -830,10 +898,13 @@ export declare const prependAll: {
     /**
      * Prepends all elements from a prefix iterable to the front of an array.
      *
+     * **When to use**
+     *
+     * Use to prepend multiple elements from an iterable to the front of an array.
+     *
      * **Details**
      *
      * - If either input is non-empty, the result is a `NonEmptyArray`.
-     * - Does not mutate the input.
      *
      * **Example** (Prepending multiple elements)
      *
@@ -854,10 +925,13 @@ export declare const prependAll: {
     /**
      * Prepends all elements from a prefix iterable to the front of an array.
      *
+     * **When to use**
+     *
+     * Use to prepend multiple elements from an iterable to the front of an array.
+     *
      * **Details**
      *
      * - If either input is non-empty, the result is a `NonEmptyArray`.
-     * - Does not mutate the input.
      *
      * **Example** (Prepending multiple elements)
      *
@@ -879,10 +953,14 @@ export declare const prependAll: {
 /**
  * Adds a single element to the end of an iterable, returning a `NonEmptyArray`.
  *
+ * **When to use**
+ *
+ * Use to add one element to the end of an iterable and get a new
+ * `NonEmptyArray`.
+ *
  * **Details**
  *
  * - Always returns a non-empty array.
- * - Does not mutate the input.
  *
  * **Example** (Appending an element)
  *
@@ -903,10 +981,14 @@ export declare const append: {
     /**
      * Adds a single element to the end of an iterable, returning a `NonEmptyArray`.
      *
+     * **When to use**
+     *
+     * Use to add one element to the end of an iterable and get a new
+     * `NonEmptyArray`.
+     *
      * **Details**
      *
      * - Always returns a non-empty array.
-     * - Does not mutate the input.
      *
      * **Example** (Appending an element)
      *
@@ -927,10 +1009,14 @@ export declare const append: {
     /**
      * Adds a single element to the end of an iterable, returning a `NonEmptyArray`.
      *
+     * **When to use**
+     *
+     * Use to add one element to the end of an iterable and get a new
+     * `NonEmptyArray`.
+     *
      * **Details**
      *
      * - Always returns a non-empty array.
-     * - Does not mutate the input.
      *
      * **Example** (Appending an element)
      *
@@ -952,10 +1038,14 @@ export declare const append: {
 /**
  * Concatenates two iterables into a single array.
  *
+ * **When to use**
+ *
+ * Use to combine two iterable inputs into a new array with the second input's
+ * elements after the first.
+ *
  * **Details**
  *
  * - If either input is non-empty, the result is a `NonEmptyArray`.
- * - Does not mutate the inputs.
  *
  * **Example** (Concatenating arrays)
  *
@@ -976,10 +1066,14 @@ export declare const appendAll: {
     /**
      * Concatenates two iterables into a single array.
      *
+     * **When to use**
+     *
+     * Use to combine two iterable inputs into a new array with the second input's
+     * elements after the first.
+     *
      * **Details**
      *
      * - If either input is non-empty, the result is a `NonEmptyArray`.
-     * - Does not mutate the inputs.
      *
      * **Example** (Concatenating arrays)
      *
@@ -1000,10 +1094,14 @@ export declare const appendAll: {
     /**
      * Concatenates two iterables into a single array.
      *
+     * **When to use**
+     *
+     * Use to combine two iterable inputs into a new array with the second input's
+     * elements after the first.
+     *
      * **Details**
      *
      * - If either input is non-empty, the result is a `NonEmptyArray`.
-     * - Does not mutate the inputs.
      *
      * **Example** (Concatenating arrays)
      *
@@ -1024,10 +1122,14 @@ export declare const appendAll: {
     /**
      * Concatenates two iterables into a single array.
      *
+     * **When to use**
+     *
+     * Use to combine two iterable inputs into a new array with the second input's
+     * elements after the first.
+     *
      * **Details**
      *
      * - If either input is non-empty, the result is a `NonEmptyArray`.
-     * - Does not mutate the inputs.
      *
      * **Example** (Concatenating arrays)
      *
@@ -1048,10 +1150,14 @@ export declare const appendAll: {
     /**
      * Concatenates two iterables into a single array.
      *
+     * **When to use**
+     *
+     * Use to combine two iterable inputs into a new array with the second input's
+     * elements after the first.
+     *
      * **Details**
      *
      * - If either input is non-empty, the result is a `NonEmptyArray`.
-     * - Does not mutate the inputs.
      *
      * **Example** (Concatenating arrays)
      *
@@ -1071,7 +1177,11 @@ export declare const appendAll: {
     <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A | B>;
 };
 /**
- * Left-to-right fold that keeps every intermediate accumulator value.
+ * Folds left-to-right while keeping every intermediate accumulator value.
+ *
+ * **When to use**
+ *
+ * Use to compute a running accumulator where each intermediate value is needed.
  *
  * **Details**
  *
@@ -1096,7 +1206,11 @@ export declare const appendAll: {
  */
 export declare const scan: {
     /**
-     * Left-to-right fold that keeps every intermediate accumulator value.
+     * Folds left-to-right while keeping every intermediate accumulator value.
+     *
+     * **When to use**
+     *
+     * Use to compute a running accumulator where each intermediate value is needed.
      *
      * **Details**
      *
@@ -1121,7 +1235,11 @@ export declare const scan: {
      */
     <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => NonEmptyArray<B>;
     /**
-     * Left-to-right fold that keeps every intermediate accumulator value.
+     * Folds left-to-right while keeping every intermediate accumulator value.
+     *
+     * **When to use**
+     *
+     * Use to compute a running accumulator where each intermediate value is needed.
      *
      * **Details**
      *
@@ -1147,7 +1265,12 @@ export declare const scan: {
     <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): NonEmptyArray<B>;
 };
 /**
- * Right-to-left fold that keeps every intermediate accumulator value.
+ * Folds right-to-left while keeping every intermediate accumulator value.
+ *
+ * **When to use**
+ *
+ * Use to compute a running accumulator from right to left where each intermediate
+ * value is needed.
  *
  * **Details**
  *
@@ -1171,7 +1294,12 @@ export declare const scan: {
  */
 export declare const scanRight: {
     /**
-     * Right-to-left fold that keeps every intermediate accumulator value.
+     * Folds right-to-left while keeping every intermediate accumulator value.
+     *
+     * **When to use**
+     *
+     * Use to compute a running accumulator from right to left where each intermediate
+     * value is needed.
      *
      * **Details**
      *
@@ -1195,7 +1323,12 @@ export declare const scanRight: {
      */
     <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => NonEmptyArray<B>;
     /**
-     * Right-to-left fold that keeps every intermediate accumulator value.
+     * Folds right-to-left while keeping every intermediate accumulator value.
+     *
+     * **When to use**
+     *
+     * Use to compute a running accumulator from right to left where each intermediate
+     * value is needed.
      *
      * **Details**
      *
@@ -1220,7 +1353,11 @@ export declare const scanRight: {
     <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): NonEmptyArray<B>;
 };
 /**
- * Tests whether a value is an `Array`.
+ * Checks whether a value is an `Array`.
+ *
+ * **When to use**
+ *
+ * Use to verify a value is a mutable array, narrowing its type to `Array<unknown>`.
  *
  * **Details**
  *
@@ -1244,7 +1381,11 @@ export declare const scanRight: {
  */
 export declare const isArray: {
     /**
-     * Tests whether a value is an `Array`.
+     * Checks whether a value is an `Array`.
+     *
+     * **When to use**
+     *
+     * Use to verify a value is a mutable array, narrowing its type to `Array<unknown>`.
      *
      * **Details**
      *
@@ -1268,7 +1409,11 @@ export declare const isArray: {
      */
     (self: unknown): self is Array<unknown>;
     /**
-     * Tests whether a value is an `Array`.
+     * Checks whether a value is an `Array`.
+     *
+     * **When to use**
+     *
+     * Use to verify a value is a mutable array, narrowing its type to `Array<unknown>`.
      *
      * **Details**
      *
@@ -1293,7 +1438,7 @@ export declare const isArray: {
     <T>(self: T): self is Extract<T, ReadonlyArray<any>>;
 };
 /**
- * Tests whether a mutable `Array` is empty, narrowing the type to `[]`.
+ * Checks whether a mutable `Array` is empty, narrowing the type to `[]`.
  *
  * **Example** (Checking for an empty array)
  *
@@ -1312,7 +1457,7 @@ export declare const isArray: {
  */
 export declare const isArrayEmpty: <A>(self: Array<A>) => self is [];
 /**
- * Tests whether a `ReadonlyArray` is empty, narrowing the type to `readonly []`.
+ * Checks whether a `ReadonlyArray` is empty, narrowing the type to `readonly []`.
  *
  * **Example** (Checking for an empty readonly array)
  *
@@ -1331,7 +1476,7 @@ export declare const isArrayEmpty: <A>(self: Array<A>) => self is [];
  */
 export declare const isReadonlyArrayEmpty: <A>(self: ReadonlyArray<A>) => self is readonly [];
 /**
- * Tests whether a mutable `Array` is non-empty, narrowing the type to
+ * Checks whether a mutable `Array` is non-empty, narrowing the type to
  * `NonEmptyArray`.
  *
  * **Example** (Checking for a non-empty array)
@@ -1351,7 +1496,7 @@ export declare const isReadonlyArrayEmpty: <A>(self: ReadonlyArray<A>) => self i
  */
 export declare const isArrayNonEmpty: <A>(self: Array<A>) => self is NonEmptyArray<A>;
 /**
- * Tests whether a `ReadonlyArray` is non-empty, narrowing the type to
+ * Checks whether a `ReadonlyArray` is non-empty, narrowing the type to
  * `NonEmptyReadonlyArray`.
  *
  * **Example** (Checking for a non-empty readonly array)
@@ -1373,6 +1518,10 @@ export declare const isReadonlyArrayNonEmpty: <A>(self: ReadonlyArray<A>) => sel
 /**
  * Returns the number of elements in a `ReadonlyArray`.
  *
+ * **When to use**
+ *
+ * Use when you need length as a composable function rather than a property access.
+ *
  * **Example** (Getting the length)
  *
  * ```ts
@@ -1386,9 +1535,14 @@ export declare const isReadonlyArrayNonEmpty: <A>(self: ReadonlyArray<A>) => sel
  */
 export declare const length: <A>(self: ReadonlyArray<A>) => number;
 /**
- * Safely reads an element at the given index, returning `Option.some` or
+ * Reads an element at the given index safely, returning `Option.some` or
  * `Option.none` if the index is out of bounds.
  *
+ * **When to use**
+ *
+ * Use when you need to read an array element by index and handle an
+ * out-of-bounds index as `Option.none`.
+ *
  * **Details**
  *
  * - The index is floored to an integer.
@@ -1403,18 +1557,23 @@ export declare const length: <A>(self: ReadonlyArray<A>) => number;
  * console.log(Array.get([1, 2, 3], 10)) // None
  * ```
  *
- * @see {@link getUnsafe} — throws on out of bounds
- * @see {@link head} — get the first element
- * @see {@link last} — get the last element
+ * @see {@link getUnsafe} for indexed access that throws when the index is out of bounds
+ * @see {@link head} for reading the first element as an `Option`
+ * @see {@link last} for reading the last element as an `Option`
  *
  * @category getters
  * @since 2.0.0
  */
 export declare const get: {
     /**
-     * Safely reads an element at the given index, returning `Option.some` or
+     * Reads an element at the given index safely, returning `Option.some` or
      * `Option.none` if the index is out of bounds.
      *
+     * **When to use**
+     *
+     * Use when you need to read an array element by index and handle an
+     * out-of-bounds index as `Option.none`.
+     *
      * **Details**
      *
      * - The index is floored to an integer.
@@ -1429,18 +1588,23 @@ export declare const get: {
      * console.log(Array.get([1, 2, 3], 10)) // None
      * ```
      *
-     * @see {@link getUnsafe} — throws on out of bounds
-     * @see {@link head} — get the first element
-     * @see {@link last} — get the last element
+     * @see {@link getUnsafe} for indexed access that throws when the index is out of bounds
+     * @see {@link head} for reading the first element as an `Option`
+     * @see {@link last} for reading the last element as an `Option`
      *
      * @category getters
      * @since 2.0.0
      */
     (index: number): <A>(self: ReadonlyArray<A>) => Option.Option<A>;
     /**
-     * Safely reads an element at the given index, returning `Option.some` or
+     * Reads an element at the given index safely, returning `Option.some` or
      * `Option.none` if the index is out of bounds.
      *
+     * **When to use**
+     *
+     * Use when you need to read an array element by index and handle an
+     * out-of-bounds index as `Option.none`.
+     *
      * **Details**
      *
      * - The index is floored to an integer.
@@ -1455,9 +1619,9 @@ export declare const get: {
      * console.log(Array.get([1, 2, 3], 10)) // None
      * ```
      *
-     * @see {@link getUnsafe} — throws on out of bounds
-     * @see {@link head} — get the first element
-     * @see {@link last} — get the last element
+     * @see {@link getUnsafe} for indexed access that throws when the index is out of bounds
+     * @see {@link head} for reading the first element as an `Option`
+     * @see {@link last} for reading the last element as an `Option`
      *
      * @category getters
      * @since 2.0.0
@@ -1467,6 +1631,11 @@ export declare const get: {
 /**
  * Reads an element at the given index, throwing if the index is out of bounds.
  *
+ * **When to use**
+ *
+ * Use to read an element at a known valid index when out-of-bounds would be a
+ * programming error.
+ *
  * **Details**
  *
  * - Throws an `Error` with the message `"Index out of bounds: <i>"`.
@@ -1490,6 +1659,11 @@ export declare const getUnsafe: {
     /**
      * Reads an element at the given index, throwing if the index is out of bounds.
      *
+     * **When to use**
+     *
+     * Use to read an element at a known valid index when out-of-bounds would be a
+     * programming error.
+     *
      * **Details**
      *
      * - Throws an `Error` with the message `"Index out of bounds: <i>"`.
@@ -1513,6 +1687,11 @@ export declare const getUnsafe: {
     /**
      * Reads an element at the given index, throwing if the index is out of bounds.
      *
+     * **When to use**
+     *
+     * Use to read an element at a known valid index when out-of-bounds would be a
+     * programming error.
+     *
      * **Details**
      *
      * - Throws an `Error` with the message `"Index out of bounds: <i>"`.
@@ -1537,6 +1716,11 @@ export declare const getUnsafe: {
 /**
  * Splits a non-empty array into its first element and the remaining elements.
  *
+ * **When to use**
+ *
+ * Use when you have a `NonEmptyReadonlyArray` and need both its first element
+ * and the remaining elements as separate values.
+ *
  * **Details**
  *
  * - Returns a tuple `[head, tail]`.
@@ -1551,9 +1735,9 @@ export declare const getUnsafe: {
  * console.log(result) // [1, [2, 3, 4]]
  * ```
  *
- * @see {@link unappend} — split into init + last
- * @see {@link headNonEmpty} — get only the head
- * @see {@link tailNonEmpty} — get only the tail
+ * @see {@link unappend} for splitting a non-empty array into init and last
+ * @see {@link headNonEmpty} for getting only the first element
+ * @see {@link tailNonEmpty} for getting only the elements after the first
  *
  * @category splitting
  * @since 2.0.0
@@ -1563,6 +1747,11 @@ export declare const unprepend: <A>(self: NonEmptyReadonlyArray<A>) => [firstEle
  * Splits a non-empty array into all elements except the last, and the last
  * element.
  *
+ * **When to use**
+ *
+ * Use to split a non-empty array from the end when you need both the elements
+ * before the last element and the last element.
+ *
  * **Details**
  *
  * - Returns a tuple `[init, last]`.
@@ -1577,18 +1766,22 @@ export declare const unprepend: <A>(self: NonEmptyReadonlyArray<A>) => [firstEle
  * console.log(result) // [[1, 2, 3], 4]
  * ```
  *
- * @see {@link unprepend} — split into head + tail
- * @see {@link initNonEmpty} — get only the init
- * @see {@link lastNonEmpty} — get only the last
+ * @see {@link unprepend} for splitting a non-empty array into head and tail
+ * @see {@link initNonEmpty} for getting only the elements before the last
+ * @see {@link lastNonEmpty} for getting only the last element
  *
  * @category splitting
  * @since 2.0.0
  */
 export declare const unappend: <A>(self: NonEmptyReadonlyArray<A>) => [arrayWithoutLastElement: Array<A>, lastElement: A];
 /**
- * Returns the first element of an array wrapped in `Option.some`, or
+ * Returns the first element of an array safely wrapped in `Option.some`, or
  * `Option.none` if the array is empty.
  *
+ * **When to use**
+ *
+ * Use to safely get the first element of an array that may be empty.
+ *
  * **Example** (Getting the first element)
  *
  * ```ts
@@ -1609,6 +1802,11 @@ export declare const head: <A>(self: ReadonlyArray<A>) => Option.Option<A>;
  * Returns the first element of a `NonEmptyReadonlyArray` directly (no `Option`
  * wrapper).
  *
+ * **When to use**
+ *
+ * Use to get the first element without `Option` wrapping when the array is known
+ * to be non-empty.
+ *
  * **Example** (Getting the head of a non-empty array)
  *
  * ```ts
@@ -1624,9 +1822,13 @@ export declare const head: <A>(self: ReadonlyArray<A>) => Option.Option<A>;
  */
 export declare const headNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => A;
 /**
- * Returns the last element of an array wrapped in `Option.some`, or
+ * Returns the last element of an array safely wrapped in `Option.some`, or
  * `Option.none` if the array is empty.
  *
+ * **When to use**
+ *
+ * Use to safely get the last element of an array that may be empty.
+ *
  * **Example** (Getting the last element)
  *
  * ```ts
@@ -1647,6 +1849,11 @@ export declare const last: <A>(self: ReadonlyArray<A>) => Option.Option<A>;
  * Returns the last element of a `NonEmptyReadonlyArray` directly (no `Option`
  * wrapper).
  *
+ * **When to use**
+ *
+ * Use to get the last element without `Option` wrapping when the array is known
+ * to be non-empty.
+ *
  * **Example** (Getting the last of a non-empty array)
  *
  * ```ts
@@ -1662,7 +1869,11 @@ export declare const last: <A>(self: ReadonlyArray<A>) => Option.Option<A>;
  */
 export declare const lastNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => A;
 /**
- * Returns all elements except the first, wrapped in an `Option`.
+ * Returns all elements except the first safely, wrapped in an `Option`.
+ *
+ * **When to use**
+ *
+ * Use to safely get all elements after the first when the iterable may be empty.
  *
  * **Details**
  *
@@ -1688,6 +1899,10 @@ export declare function tail<A>(self: Iterable<A>): Option.Option<Array<A>>;
 /**
  * Returns all elements except the first of a `NonEmptyReadonlyArray`.
  *
+ * **When to use**
+ *
+ * Use to get all elements after the first when the array is known to be non-empty.
+ *
  * **Example** (Getting the tail of a non-empty array)
  *
  * ```ts
@@ -1704,7 +1919,11 @@ export declare function tail<A>(self: Iterable<A>): Option.Option<Array<A>>;
  */
 export declare const tailNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => Array<A>;
 /**
- * Returns all elements except the last, wrapped in an `Option`.
+ * Returns all elements except the last safely, wrapped in an `Option`.
+ *
+ * **When to use**
+ *
+ * Use to safely get all elements before the last when the iterable may be empty.
  *
  * **Details**
  *
@@ -1730,6 +1949,10 @@ export declare function init<A>(self: Iterable<A>): Option.Option<Array<A>>;
 /**
  * Returns all elements except the last of a `NonEmptyReadonlyArray`.
  *
+ * **When to use**
+ *
+ * Use to get all elements before the last when the array is known to be non-empty.
+ *
  * **Example** (Getting init of a non-empty array)
  *
  * ```ts
@@ -1748,6 +1971,10 @@ export declare const initNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => Array<
 /**
  * Keeps the first `n` elements, creating a new array.
  *
+ * **When to use**
+ *
+ * Use to keep up to the first `n` elements from an iterable as a new array.
+ *
  * **Details**
  *
  * - `n` is clamped to `[0, length]`.
@@ -1761,9 +1988,9 @@ export declare const initNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => Array<
  * console.log(Array.take([1, 2, 3, 4, 5], 3)) // [1, 2, 3]
  * ```
  *
- * @see {@link takeRight} — keep from the end
- * @see {@link takeWhile} — keep while predicate holds
- * @see {@link drop} — remove from the start
+ * @see {@link takeRight} for keeping elements from the end
+ * @see {@link takeWhile} for keeping an initial prefix while a predicate holds
+ * @see {@link drop} for removing elements from the start
  *
  * @category getters
  * @since 2.0.0
@@ -1772,6 +1999,10 @@ export declare const take: {
     /**
      * Keeps the first `n` elements, creating a new array.
      *
+     * **When to use**
+     *
+     * Use to keep up to the first `n` elements from an iterable as a new array.
+     *
      * **Details**
      *
      * - `n` is clamped to `[0, length]`.
@@ -1785,9 +2016,9 @@ export declare const take: {
      * console.log(Array.take([1, 2, 3, 4, 5], 3)) // [1, 2, 3]
      * ```
      *
-     * @see {@link takeRight} — keep from the end
-     * @see {@link takeWhile} — keep while predicate holds
-     * @see {@link drop} — remove from the start
+     * @see {@link takeRight} for keeping elements from the end
+     * @see {@link takeWhile} for keeping an initial prefix while a predicate holds
+     * @see {@link drop} for removing elements from the start
      *
      * @category getters
      * @since 2.0.0
@@ -1796,6 +2027,10 @@ export declare const take: {
     /**
      * Keeps the first `n` elements, creating a new array.
      *
+     * **When to use**
+     *
+     * Use to keep up to the first `n` elements from an iterable as a new array.
+     *
      * **Details**
      *
      * - `n` is clamped to `[0, length]`.
@@ -1809,9 +2044,9 @@ export declare const take: {
      * console.log(Array.take([1, 2, 3, 4, 5], 3)) // [1, 2, 3]
      * ```
      *
-     * @see {@link takeRight} — keep from the end
-     * @see {@link takeWhile} — keep while predicate holds
-     * @see {@link drop} — remove from the start
+     * @see {@link takeRight} for keeping elements from the end
+     * @see {@link takeWhile} for keeping an initial prefix while a predicate holds
+     * @see {@link drop} for removing elements from the start
      *
      * @category getters
      * @since 2.0.0
@@ -1821,6 +2056,10 @@ export declare const take: {
 /**
  * Keeps the last `n` elements, creating a new array.
  *
+ * **When to use**
+ *
+ * Use to keep the last `n` elements of an iterable.
+ *
  * **Details**
  *
  * - `n` is clamped to `[0, length]`.
@@ -1844,6 +2083,10 @@ export declare const takeRight: {
     /**
      * Keeps the last `n` elements, creating a new array.
      *
+     * **When to use**
+     *
+     * Use to keep the last `n` elements of an iterable.
+     *
      * **Details**
      *
      * - `n` is clamped to `[0, length]`.
@@ -1867,6 +2110,10 @@ export declare const takeRight: {
     /**
      * Keeps the last `n` elements, creating a new array.
      *
+     * **When to use**
+     *
+     * Use to keep the last `n` elements of an iterable.
+     *
      * **Details**
      *
      * - `n` is clamped to `[0, length]`.
@@ -1892,6 +2139,11 @@ export declare const takeRight: {
  * Takes elements from the start while the predicate holds, stopping at the
  * first element that fails.
  *
+ * **When to use**
+ *
+ * Use to keep the leading elements of an iterable while each element satisfies
+ * a predicate, returning the retained prefix as an array.
+ *
  * **Details**
  *
  * - Supports refinements for type narrowing.
@@ -1905,9 +2157,9 @@ export declare const takeRight: {
  * console.log(Array.takeWhile([1, 3, 2, 4, 1, 2], (x) => x < 4)) // [1, 3, 2]
  * ```
  *
- * @see {@link take} — take a fixed count
- * @see {@link dropWhile} — drop while predicate holds
- * @see {@link span} — split into matching prefix + rest
+ * @see {@link take} for keeping a fixed number of leading elements
+ * @see {@link dropWhile} for removing the matching prefix and keeping the rest
+ * @see {@link span} for splitting the matching prefix from the remaining elements
  *
  * @category getters
  * @since 2.0.0
@@ -1917,6 +2169,11 @@ export declare const takeWhile: {
      * Takes elements from the start while the predicate holds, stopping at the
      * first element that fails.
      *
+     * **When to use**
+     *
+     * Use to keep the leading elements of an iterable while each element satisfies
+     * a predicate, returning the retained prefix as an array.
+     *
      * **Details**
      *
      * - Supports refinements for type narrowing.
@@ -1930,9 +2187,9 @@ export declare const takeWhile: {
      * console.log(Array.takeWhile([1, 3, 2, 4, 1, 2], (x) => x < 4)) // [1, 3, 2]
      * ```
      *
-     * @see {@link take} — take a fixed count
-     * @see {@link dropWhile} — drop while predicate holds
-     * @see {@link span} — split into matching prefix + rest
+     * @see {@link take} for keeping a fixed number of leading elements
+     * @see {@link dropWhile} for removing the matching prefix and keeping the rest
+     * @see {@link span} for splitting the matching prefix from the remaining elements
      *
      * @category getters
      * @since 2.0.0
@@ -1942,6 +2199,11 @@ export declare const takeWhile: {
      * Takes elements from the start while the predicate holds, stopping at the
      * first element that fails.
      *
+     * **When to use**
+     *
+     * Use to keep the leading elements of an iterable while each element satisfies
+     * a predicate, returning the retained prefix as an array.
+     *
      * **Details**
      *
      * - Supports refinements for type narrowing.
@@ -1955,9 +2217,9 @@ export declare const takeWhile: {
      * console.log(Array.takeWhile([1, 3, 2, 4, 1, 2], (x) => x < 4)) // [1, 3, 2]
      * ```
      *
-     * @see {@link take} — take a fixed count
-     * @see {@link dropWhile} — drop while predicate holds
-     * @see {@link span} — split into matching prefix + rest
+     * @see {@link take} for keeping a fixed number of leading elements
+     * @see {@link dropWhile} for removing the matching prefix and keeping the rest
+     * @see {@link span} for splitting the matching prefix from the remaining elements
      *
      * @category getters
      * @since 2.0.0
@@ -1967,6 +2229,11 @@ export declare const takeWhile: {
      * Takes elements from the start while the predicate holds, stopping at the
      * first element that fails.
      *
+     * **When to use**
+     *
+     * Use to keep the leading elements of an iterable while each element satisfies
+     * a predicate, returning the retained prefix as an array.
+     *
      * **Details**
      *
      * - Supports refinements for type narrowing.
@@ -1980,9 +2247,9 @@ export declare const takeWhile: {
      * console.log(Array.takeWhile([1, 3, 2, 4, 1, 2], (x) => x < 4)) // [1, 3, 2]
      * ```
      *
-     * @see {@link take} — take a fixed count
-     * @see {@link dropWhile} — drop while predicate holds
-     * @see {@link span} — split into matching prefix + rest
+     * @see {@link take} for keeping a fixed number of leading elements
+     * @see {@link dropWhile} for removing the matching prefix and keeping the rest
+     * @see {@link span} for splitting the matching prefix from the remaining elements
      *
      * @category getters
      * @since 2.0.0
@@ -1992,6 +2259,11 @@ export declare const takeWhile: {
      * Takes elements from the start while the predicate holds, stopping at the
      * first element that fails.
      *
+     * **When to use**
+     *
+     * Use to keep the leading elements of an iterable while each element satisfies
+     * a predicate, returning the retained prefix as an array.
+     *
      * **Details**
      *
      * - Supports refinements for type narrowing.
@@ -2005,9 +2277,9 @@ export declare const takeWhile: {
      * console.log(Array.takeWhile([1, 3, 2, 4, 1, 2], (x) => x < 4)) // [1, 3, 2]
      * ```
      *
-     * @see {@link take} — take a fixed count
-     * @see {@link dropWhile} — drop while predicate holds
-     * @see {@link span} — split into matching prefix + rest
+     * @see {@link take} for keeping a fixed number of leading elements
+     * @see {@link dropWhile} for removing the matching prefix and keeping the rest
+     * @see {@link span} for splitting the matching prefix from the remaining elements
      *
      * @category getters
      * @since 2.0.0
@@ -2017,11 +2289,19 @@ export declare const takeWhile: {
 /**
  * Takes elements from the start while a `Filter` succeeds, collecting transformed values.
  *
+ * **When to use**
+ *
+ * Use when you need to take a prefix of elements while a function can
+ * successfully extract or transform them, stopping at the first element
+ * that produces a failure result.
+ *
  * **Details**
  *
  * - The filter receives `(element, index)`.
  * - Stops at the first filter failure.
  *
+ * @see {@link takeWhile} for taking a prefix based on a boolean predicate
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -2029,11 +2309,19 @@ export declare const takeWhileFilter: {
     /**
      * Takes elements from the start while a `Filter` succeeds, collecting transformed values.
      *
+     * **When to use**
+     *
+     * Use when you need to take a prefix of elements while a function can
+     * successfully extract or transform them, stopping at the first element
+     * that produces a failure result.
+     *
      * **Details**
      *
      * - The filter receives `(element, index)`.
      * - Stops at the first filter failure.
      *
+     * @see {@link takeWhile} for taking a prefix based on a boolean predicate
+     *
      * @category getters
      * @since 4.0.0
      */
@@ -2041,11 +2329,19 @@ export declare const takeWhileFilter: {
     /**
      * Takes elements from the start while a `Filter` succeeds, collecting transformed values.
      *
+     * **When to use**
+     *
+     * Use when you need to take a prefix of elements while a function can
+     * successfully extract or transform them, stopping at the first element
+     * that produces a failure result.
+     *
      * **Details**
      *
      * - The filter receives `(element, index)`.
      * - Stops at the first filter failure.
      *
+     * @see {@link takeWhile} for taking a prefix based on a boolean predicate
+     *
      * @category getters
      * @since 4.0.0
      */
@@ -2055,6 +2351,11 @@ export declare const takeWhileFilter: {
  * Splits an iterable into two arrays: the longest prefix where the predicate
  * holds, and the remaining elements.
  *
+ * **When to use**
+ *
+ * Use to split an iterable into the longest prefix that satisfies a predicate
+ * and the elements after that prefix when you need both parts.
+ *
  * **Details**
  *
  * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
@@ -2069,9 +2370,9 @@ export declare const takeWhileFilter: {
  * console.log(Array.span([1, 3, 2, 4, 5], (x) => x % 2 === 1)) // [[1, 3], [2, 4, 5]]
  * ```
  *
- * @see {@link takeWhile} — keep only the matching prefix
- * @see {@link dropWhile} — keep only the rest
- * @see {@link splitWhere} — split at the first element matching a predicate
+ * @see {@link takeWhile} for keeping only the matching prefix
+ * @see {@link dropWhile} for keeping only the elements after the matching prefix
+ * @see {@link splitWhere} for splitting at the first element that satisfies a predicate
  *
  * @category splitting
  * @since 2.0.0
@@ -2081,6 +2382,11 @@ export declare const span: {
      * Splits an iterable into two arrays: the longest prefix where the predicate
      * holds, and the remaining elements.
      *
+     * **When to use**
+     *
+     * Use to split an iterable into the longest prefix that satisfies a predicate
+     * and the elements after that prefix when you need both parts.
+     *
      * **Details**
      *
      * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
@@ -2095,9 +2401,9 @@ export declare const span: {
      * console.log(Array.span([1, 3, 2, 4, 5], (x) => x % 2 === 1)) // [[1, 3], [2, 4, 5]]
      * ```
      *
-     * @see {@link takeWhile} — keep only the matching prefix
-     * @see {@link dropWhile} — keep only the rest
-     * @see {@link splitWhere} — split at the first element matching a predicate
+     * @see {@link takeWhile} for keeping only the matching prefix
+     * @see {@link dropWhile} for keeping only the elements after the matching prefix
+     * @see {@link splitWhere} for splitting at the first element that satisfies a predicate
      *
      * @category splitting
      * @since 2.0.0
@@ -2107,6 +2413,11 @@ export declare const span: {
      * Splits an iterable into two arrays: the longest prefix where the predicate
      * holds, and the remaining elements.
      *
+     * **When to use**
+     *
+     * Use to split an iterable into the longest prefix that satisfies a predicate
+     * and the elements after that prefix when you need both parts.
+     *
      * **Details**
      *
      * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
@@ -2121,9 +2432,9 @@ export declare const span: {
      * console.log(Array.span([1, 3, 2, 4, 5], (x) => x % 2 === 1)) // [[1, 3], [2, 4, 5]]
      * ```
      *
-     * @see {@link takeWhile} — keep only the matching prefix
-     * @see {@link dropWhile} — keep only the rest
-     * @see {@link splitWhere} — split at the first element matching a predicate
+     * @see {@link takeWhile} for keeping only the matching prefix
+     * @see {@link dropWhile} for keeping only the elements after the matching prefix
+     * @see {@link splitWhere} for splitting at the first element that satisfies a predicate
      *
      * @category splitting
      * @since 2.0.0
@@ -2133,6 +2444,11 @@ export declare const span: {
      * Splits an iterable into two arrays: the longest prefix where the predicate
      * holds, and the remaining elements.
      *
+     * **When to use**
+     *
+     * Use to split an iterable into the longest prefix that satisfies a predicate
+     * and the elements after that prefix when you need both parts.
+     *
      * **Details**
      *
      * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
@@ -2147,9 +2463,9 @@ export declare const span: {
      * console.log(Array.span([1, 3, 2, 4, 5], (x) => x % 2 === 1)) // [[1, 3], [2, 4, 5]]
      * ```
      *
-     * @see {@link takeWhile} — keep only the matching prefix
-     * @see {@link dropWhile} — keep only the rest
-     * @see {@link splitWhere} — split at the first element matching a predicate
+     * @see {@link takeWhile} for keeping only the matching prefix
+     * @see {@link dropWhile} for keeping only the elements after the matching prefix
+     * @see {@link splitWhere} for splitting at the first element that satisfies a predicate
      *
      * @category splitting
      * @since 2.0.0
@@ -2159,6 +2475,11 @@ export declare const span: {
      * Splits an iterable into two arrays: the longest prefix where the predicate
      * holds, and the remaining elements.
      *
+     * **When to use**
+     *
+     * Use to split an iterable into the longest prefix that satisfies a predicate
+     * and the elements after that prefix when you need both parts.
+     *
      * **Details**
      *
      * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
@@ -2173,9 +2494,9 @@ export declare const span: {
      * console.log(Array.span([1, 3, 2, 4, 5], (x) => x % 2 === 1)) // [[1, 3], [2, 4, 5]]
      * ```
      *
-     * @see {@link takeWhile} — keep only the matching prefix
-     * @see {@link dropWhile} — keep only the rest
-     * @see {@link splitWhere} — split at the first element matching a predicate
+     * @see {@link takeWhile} for keeping only the matching prefix
+     * @see {@link dropWhile} for keeping only the elements after the matching prefix
+     * @see {@link splitWhere} for splitting at the first element that satisfies a predicate
      *
      * @category splitting
      * @since 2.0.0
@@ -2185,6 +2506,11 @@ export declare const span: {
 /**
  * Removes the first `n` elements, creating a new array.
  *
+ * **When to use**
+ *
+ * Use to keep the suffix of an iterable after skipping a fixed number of
+ * leading elements.
+ *
  * **Details**
  *
  * - `n` is clamped to `[0, length]`.
@@ -2198,9 +2524,9 @@ export declare const span: {
  * console.log(Array.drop([1, 2, 3, 4, 5], 2)) // [3, 4, 5]
  * ```
  *
- * @see {@link dropRight} — remove from the end
- * @see {@link dropWhile} — remove while predicate holds
- * @see {@link take} — keep from the start
+ * @see {@link dropRight} for removing a fixed number of elements from the end
+ * @see {@link dropWhile} for removing a prefix based on a predicate instead of a fixed count
+ * @see {@link take} for keeping a fixed number of elements from the start
  *
  * @category getters
  * @since 2.0.0
@@ -2209,6 +2535,11 @@ export declare const drop: {
     /**
      * Removes the first `n` elements, creating a new array.
      *
+     * **When to use**
+     *
+     * Use to keep the suffix of an iterable after skipping a fixed number of
+     * leading elements.
+     *
      * **Details**
      *
      * - `n` is clamped to `[0, length]`.
@@ -2222,9 +2553,9 @@ export declare const drop: {
      * console.log(Array.drop([1, 2, 3, 4, 5], 2)) // [3, 4, 5]
      * ```
      *
-     * @see {@link dropRight} — remove from the end
-     * @see {@link dropWhile} — remove while predicate holds
-     * @see {@link take} — keep from the start
+     * @see {@link dropRight} for removing a fixed number of elements from the end
+     * @see {@link dropWhile} for removing a prefix based on a predicate instead of a fixed count
+     * @see {@link take} for keeping a fixed number of elements from the start
      *
      * @category getters
      * @since 2.0.0
@@ -2233,6 +2564,11 @@ export declare const drop: {
     /**
      * Removes the first `n` elements, creating a new array.
      *
+     * **When to use**
+     *
+     * Use to keep the suffix of an iterable after skipping a fixed number of
+     * leading elements.
+     *
      * **Details**
      *
      * - `n` is clamped to `[0, length]`.
@@ -2246,9 +2582,9 @@ export declare const drop: {
      * console.log(Array.drop([1, 2, 3, 4, 5], 2)) // [3, 4, 5]
      * ```
      *
-     * @see {@link dropRight} — remove from the end
-     * @see {@link dropWhile} — remove while predicate holds
-     * @see {@link take} — keep from the start
+     * @see {@link dropRight} for removing a fixed number of elements from the end
+     * @see {@link dropWhile} for removing a prefix based on a predicate instead of a fixed count
+     * @see {@link take} for keeping a fixed number of elements from the start
      *
      * @category getters
      * @since 2.0.0
@@ -2258,9 +2594,13 @@ export declare const drop: {
 /**
  * Removes the last `n` elements, creating a new array.
  *
+ * **When to use**
+ *
+ * Use to remove the last `n` elements from an iterable.
+ *
  * **Details**
  *
- * - `n` is clamped to `[0, length]`.
+ * `n` is clamped to `[0, length]`.
  *
  * **Example** (Dropping from the end)
  *
@@ -2280,9 +2620,13 @@ export declare const dropRight: {
     /**
      * Removes the last `n` elements, creating a new array.
      *
+     * **When to use**
+     *
+     * Use to remove the last `n` elements from an iterable.
+     *
      * **Details**
      *
-     * - `n` is clamped to `[0, length]`.
+     * `n` is clamped to `[0, length]`.
      *
      * **Example** (Dropping from the end)
      *
@@ -2302,9 +2646,13 @@ export declare const dropRight: {
     /**
      * Removes the last `n` elements, creating a new array.
      *
+     * **When to use**
+     *
+     * Use to remove the last `n` elements from an iterable.
+     *
      * **Details**
      *
-     * - `n` is clamped to `[0, length]`.
+     * `n` is clamped to `[0, length]`.
      *
      * **Example** (Dropping from the end)
      *
@@ -2325,9 +2673,13 @@ export declare const dropRight: {
 /**
  * Drops elements from the start while the predicate holds, returning the rest.
  *
+ * **When to use**
+ *
+ * Use to remove a leading prefix of elements that satisfy a predicate.
+ *
  * **Details**
  *
- * - The predicate receives `(element, index)`.
+ * The predicate receives `(element, index)`.
  *
  * **Example** (Dropping while condition holds)
  *
@@ -2347,9 +2699,13 @@ export declare const dropWhile: {
     /**
      * Drops elements from the start while the predicate holds, returning the rest.
      *
+     * **When to use**
+     *
+     * Use to remove a leading prefix of elements that satisfy a predicate.
+     *
      * **Details**
      *
-     * - The predicate receives `(element, index)`.
+     * The predicate receives `(element, index)`.
      *
      * **Example** (Dropping while condition holds)
      *
@@ -2369,9 +2725,13 @@ export declare const dropWhile: {
     /**
      * Drops elements from the start while the predicate holds, returning the rest.
      *
+     * **When to use**
+     *
+     * Use to remove a leading prefix of elements that satisfy a predicate.
+     *
      * **Details**
      *
-     * - The predicate receives `(element, index)`.
+     * The predicate receives `(element, index)`.
      *
      * **Example** (Dropping while condition holds)
      *
@@ -2392,11 +2752,19 @@ export declare const dropWhile: {
 /**
  * Drops elements from the start while a `Filter` succeeds.
  *
+ * **When to use**
+ *
+ * Use when dropping a prefix requires computing a `Result` per element instead
+ * of a simple boolean predicate.
+ *
  * **Details**
  *
  * - The filter receives `(element, index)`.
  * - Returns the remaining original elements after the first filter failure.
  *
+ * @see {@link dropWhile} for dropping a prefix with a simple boolean predicate
+ * @see {@link takeWhileFilter} for keeping only the matching prefix
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -2404,11 +2772,19 @@ export declare const dropWhileFilter: {
     /**
      * Drops elements from the start while a `Filter` succeeds.
      *
+     * **When to use**
+     *
+     * Use when dropping a prefix requires computing a `Result` per element instead
+     * of a simple boolean predicate.
+     *
      * **Details**
      *
      * - The filter receives `(element, index)`.
      * - Returns the remaining original elements after the first filter failure.
      *
+     * @see {@link dropWhile} for dropping a prefix with a simple boolean predicate
+     * @see {@link takeWhileFilter} for keeping only the matching prefix
+     *
      * @category getters
      * @since 4.0.0
      */
@@ -2416,11 +2792,19 @@ export declare const dropWhileFilter: {
     /**
      * Drops elements from the start while a `Filter` succeeds.
      *
+     * **When to use**
+     *
+     * Use when dropping a prefix requires computing a `Result` per element instead
+     * of a simple boolean predicate.
+     *
      * **Details**
      *
      * - The filter receives `(element, index)`.
      * - Returns the remaining original elements after the first filter failure.
      *
+     * @see {@link dropWhile} for dropping a prefix with a simple boolean predicate
+     * @see {@link takeWhileFilter} for keeping only the matching prefix
+     *
      * @category getters
      * @since 4.0.0
      */
@@ -2430,6 +2814,11 @@ export declare const dropWhileFilter: {
  * Returns the index of the first element matching the predicate, wrapped in an
  * `Option`.
  *
+ * **When to use**
+ *
+ * Use to find the index of the first matching element from the start of an
+ * iterable.
+ *
  * **Example** (Finding an index)
  *
  * ```ts
@@ -2449,6 +2838,11 @@ export declare const findFirstIndex: {
      * Returns the index of the first element matching the predicate, wrapped in an
      * `Option`.
      *
+     * **When to use**
+     *
+     * Use to find the index of the first matching element from the start of an
+     * iterable.
+     *
      * **Example** (Finding an index)
      *
      * ```ts
@@ -2468,6 +2862,11 @@ export declare const findFirstIndex: {
      * Returns the index of the first element matching the predicate, wrapped in an
      * `Option`.
      *
+     * **When to use**
+     *
+     * Use to find the index of the first matching element from the start of an
+     * iterable.
+     *
      * **Example** (Finding an index)
      *
      * ```ts
@@ -2488,6 +2887,10 @@ export declare const findFirstIndex: {
  * Returns the index of the last element matching the predicate, wrapped in an
  * `Option`.
  *
+ * **When to use**
+ *
+ * Use to find the index of the last matching element from the end of an array.
+ *
  * **Example** (Finding the last matching index)
  *
  * ```ts
@@ -2507,6 +2910,10 @@ export declare const findLastIndex: {
      * Returns the index of the last element matching the predicate, wrapped in an
      * `Option`.
      *
+     * **When to use**
+     *
+     * Use to find the index of the last matching element from the end of an array.
+     *
      * **Example** (Finding the last matching index)
      *
      * ```ts
@@ -2526,6 +2933,10 @@ export declare const findLastIndex: {
      * Returns the index of the last element matching the predicate, wrapped in an
      * `Option`.
      *
+     * **When to use**
+     *
+     * Use to find the index of the last matching element from the end of an array.
+     *
      * **Example** (Finding the last matching index)
      *
      * ```ts
@@ -2546,6 +2957,11 @@ export declare const findLastIndex: {
  * Returns the first element matching a predicate, refinement, or mapping
  * function, wrapped in `Option`.
  *
+ * **When to use**
+ *
+ * Use to scan an iterable in iteration order and return the first selected
+ * element or mapped value as an `Option`.
+ *
  * **Details**
  *
  * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -2572,6 +2988,11 @@ export declare const findFirst: {
      * Returns the first element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to scan an iterable in iteration order and return the first selected
+     * element or mapped value as an `Option`.
+     *
      * **Details**
      *
      * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -2598,6 +3019,11 @@ export declare const findFirst: {
      * Returns the first element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to scan an iterable in iteration order and return the first selected
+     * element or mapped value as an `Option`.
+     *
      * **Details**
      *
      * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -2624,6 +3050,11 @@ export declare const findFirst: {
      * Returns the first element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to scan an iterable in iteration order and return the first selected
+     * element or mapped value as an `Option`.
+     *
      * **Details**
      *
      * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -2650,6 +3081,11 @@ export declare const findFirst: {
      * Returns the first element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to scan an iterable in iteration order and return the first selected
+     * element or mapped value as an `Option`.
+     *
      * **Details**
      *
      * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -2676,6 +3112,11 @@ export declare const findFirst: {
      * Returns the first element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to scan an iterable in iteration order and return the first selected
+     * element or mapped value as an `Option`.
+     *
      * **Details**
      *
      * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -2702,6 +3143,11 @@ export declare const findFirst: {
      * Returns the first element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to scan an iterable in iteration order and return the first selected
+     * element or mapped value as an `Option`.
+     *
      * **Details**
      *
      * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -2729,6 +3175,10 @@ export declare const findFirst: {
  * Returns the first selected value together with its index, wrapped in an
  * `Option`.
  *
+ * **When to use**
+ *
+ * Use to find both the first matching element and its index in one pass.
+ *
  * **Details**
  *
  * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -2754,6 +3204,10 @@ export declare const findFirstWithIndex: {
      * Returns the first selected value together with its index, wrapped in an
      * `Option`.
      *
+     * **When to use**
+     *
+     * Use to find both the first matching element and its index in one pass.
+     *
      * **Details**
      *
      * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -2779,6 +3233,10 @@ export declare const findFirstWithIndex: {
      * Returns the first selected value together with its index, wrapped in an
      * `Option`.
      *
+     * **When to use**
+     *
+     * Use to find both the first matching element and its index in one pass.
+     *
      * **Details**
      *
      * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -2804,6 +3262,10 @@ export declare const findFirstWithIndex: {
      * Returns the first selected value together with its index, wrapped in an
      * `Option`.
      *
+     * **When to use**
+     *
+     * Use to find both the first matching element and its index in one pass.
+     *
      * **Details**
      *
      * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -2829,6 +3291,10 @@ export declare const findFirstWithIndex: {
      * Returns the first selected value together with its index, wrapped in an
      * `Option`.
      *
+     * **When to use**
+     *
+     * Use to find both the first matching element and its index in one pass.
+     *
      * **Details**
      *
      * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -2854,6 +3320,10 @@ export declare const findFirstWithIndex: {
      * Returns the first selected value together with its index, wrapped in an
      * `Option`.
      *
+     * **When to use**
+     *
+     * Use to find both the first matching element and its index in one pass.
+     *
      * **Details**
      *
      * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -2879,6 +3349,10 @@ export declare const findFirstWithIndex: {
      * Returns the first selected value together with its index, wrapped in an
      * `Option`.
      *
+     * **When to use**
+     *
+     * Use to find both the first matching element and its index in one pass.
+     *
      * **Details**
      *
      * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -2905,6 +3379,10 @@ export declare const findFirstWithIndex: {
  * Returns the last element matching a predicate, refinement, or mapping
  * function, wrapped in `Option`.
  *
+ * **When to use**
+ *
+ * Use to find the last matching element from the end of an array.
+ *
  * **Details**
  *
  * - Searches from the end of the array.
@@ -2929,6 +3407,10 @@ export declare const findLast: {
      * Returns the last element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to find the last matching element from the end of an array.
+     *
      * **Details**
      *
      * - Searches from the end of the array.
@@ -2953,6 +3435,10 @@ export declare const findLast: {
      * Returns the last element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to find the last matching element from the end of an array.
+     *
      * **Details**
      *
      * - Searches from the end of the array.
@@ -2977,6 +3463,10 @@ export declare const findLast: {
      * Returns the last element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to find the last matching element from the end of an array.
+     *
      * **Details**
      *
      * - Searches from the end of the array.
@@ -3001,6 +3491,10 @@ export declare const findLast: {
      * Returns the last element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to find the last matching element from the end of an array.
+     *
      * **Details**
      *
      * - Searches from the end of the array.
@@ -3025,6 +3519,10 @@ export declare const findLast: {
      * Returns the last element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to find the last matching element from the end of an array.
+     *
      * **Details**
      *
      * - Searches from the end of the array.
@@ -3049,6 +3547,10 @@ export declare const findLast: {
      * Returns the last element matching a predicate, refinement, or mapping
      * function, wrapped in `Option`.
      *
+     * **When to use**
+     *
+     * Use to find the last matching element from the end of an array.
+     *
      * **Details**
      *
      * - Searches from the end of the array.
@@ -3071,13 +3573,16 @@ export declare const findLast: {
     <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option.Option<A>;
 };
 /**
- * Inserts an element at the specified index, returning a new `NonEmptyArray`
+ * Inserts an element at the specified index safely, returning a new `NonEmptyArray`
  * wrapped in an `Option`.
  *
+ * **When to use**
+ *
+ * Use to insert a single element at a specific position in an array.
+ *
  * **Details**
  *
  * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
- * - Does not mutate the input.
  *
  * **Example** (Inserting at an index)
  *
@@ -3095,13 +3600,16 @@ export declare const findLast: {
  */
 export declare const insertAt: {
     /**
-     * Inserts an element at the specified index, returning a new `NonEmptyArray`
+     * Inserts an element at the specified index safely, returning a new `NonEmptyArray`
      * wrapped in an `Option`.
      *
+     * **When to use**
+     *
+     * Use to insert a single element at a specific position in an array.
+     *
      * **Details**
      *
      * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
-     * - Does not mutate the input.
      *
      * **Example** (Inserting at an index)
      *
@@ -3119,13 +3627,16 @@ export declare const insertAt: {
      */
     <B>(i: number, b: B): <A>(self: Iterable<A>) => Option.Option<NonEmptyArray<A | B>>;
     /**
-     * Inserts an element at the specified index, returning a new `NonEmptyArray`
+     * Inserts an element at the specified index safely, returning a new `NonEmptyArray`
      * wrapped in an `Option`.
      *
+     * **When to use**
+     *
+     * Use to insert a single element at a specific position in an array.
+     *
      * **Details**
      *
      * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
-     * - Does not mutate the input.
      *
      * **Example** (Inserting at an index)
      *
@@ -3144,13 +3655,16 @@ export declare const insertAt: {
     <A, B>(self: Iterable<A>, i: number, b: B): Option.Option<NonEmptyArray<A | B>>;
 };
 /**
- * Replaces the element at the specified index with a new value, returning the
+ * Replaces the element at the specified index safely with a new value, returning the
  * updated array in `Option.some`.
  *
+ * **When to use**
+ *
+ * Use to set a fixed replacement value at a specific index.
+ *
  * **Details**
  *
  * - Returns `Option.none()` when the index is out of bounds.
- * - Does not mutate the input.
  *
  * **Example** (Replacing an element)
  *
@@ -3168,13 +3682,16 @@ export declare const insertAt: {
  */
 export declare const replace: {
     /**
-     * Replaces the element at the specified index with a new value, returning the
+     * Replaces the element at the specified index safely with a new value, returning the
      * updated array in `Option.some`.
      *
+     * **When to use**
+     *
+     * Use to set a fixed replacement value at a specific index.
+     *
      * **Details**
      *
      * - Returns `Option.none()` when the index is out of bounds.
-     * - Does not mutate the input.
      *
      * **Example** (Replacing an element)
      *
@@ -3192,13 +3709,16 @@ export declare const replace: {
      */
     <B>(i: number, b: B): <A, S extends Iterable<A> = Iterable<A>>(self: S) => Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>;
     /**
-     * Replaces the element at the specified index with a new value, returning the
+     * Replaces the element at the specified index safely with a new value, returning the
      * updated array in `Option.some`.
      *
+     * **When to use**
+     *
+     * Use to set a fixed replacement value at a specific index.
+     *
      * **Details**
      *
      * - Returns `Option.none()` when the index is out of bounds.
-     * - Does not mutate the input.
      *
      * **Example** (Replacing an element)
      *
@@ -3217,13 +3737,17 @@ export declare const replace: {
     <A, B, S extends Iterable<A> = Iterable<A>>(self: S, i: number, b: B): Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>;
 };
 /**
- * Applies a function to the element at the specified index, returning the
+ * Applies a function to the element at the specified index safely, returning the
  * updated array in `Option.some`.
  *
+ * **When to use**
+ *
+ * Use to derive a replacement value from the current element at a specific
+ * index while leaving the other elements unchanged.
+ *
  * **Details**
  *
  * - Returns `Option.none()` when the index is out of bounds.
- * - Does not mutate the input.
  *
  * **Example** (Modifying an element)
  *
@@ -3243,13 +3767,17 @@ export declare const replace: {
  */
 export declare const modify: {
     /**
-     * Applies a function to the element at the specified index, returning the
+     * Applies a function to the element at the specified index safely, returning the
      * updated array in `Option.some`.
      *
+     * **When to use**
+     *
+     * Use to derive a replacement value from the current element at a specific
+     * index while leaving the other elements unchanged.
+     *
      * **Details**
      *
      * - Returns `Option.none()` when the index is out of bounds.
-     * - Does not mutate the input.
      *
      * **Example** (Modifying an element)
      *
@@ -3269,13 +3797,17 @@ export declare const modify: {
      */
     <A, B, S extends Iterable<A> = Iterable<A>>(i: number, f: (a: ReadonlyArray.Infer<S>) => B): (self: S) => Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>;
     /**
-     * Applies a function to the element at the specified index, returning the
+     * Applies a function to the element at the specified index safely, returning the
      * updated array in `Option.some`.
      *
+     * **When to use**
+     *
+     * Use to derive a replacement value from the current element at a specific
+     * index while leaving the other elements unchanged.
+     *
      * **Details**
      *
      * - Returns `Option.none()` when the index is out of bounds.
-     * - Does not mutate the input.
      *
      * **Example** (Modifying an element)
      *
@@ -3299,9 +3831,9 @@ export declare const modify: {
  * Removes the element at the specified index, returning a new array. If the
  * index is out of bounds, returns a copy of the original.
  *
- * **Details**
+ * **When to use**
  *
- * - Does not mutate the input.
+ * Use to remove a single element at a known index.
  *
  * **Example** (Removing an element)
  *
@@ -3323,9 +3855,9 @@ export declare const remove: {
      * Removes the element at the specified index, returning a new array. If the
      * index is out of bounds, returns a copy of the original.
      *
-     * **Details**
+     * **When to use**
      *
-     * - Does not mutate the input.
+     * Use to remove a single element at a known index.
      *
      * **Example** (Removing an element)
      *
@@ -3347,9 +3879,9 @@ export declare const remove: {
      * Removes the element at the specified index, returning a new array. If the
      * index is out of bounds, returns a copy of the original.
      *
-     * **Details**
+     * **When to use**
      *
-     * - Does not mutate the input.
+     * Use to remove a single element at a known index.
      *
      * **Example** (Removing an element)
      *
@@ -3371,9 +3903,12 @@ export declare const remove: {
 /**
  * Reverses an iterable into a new array.
  *
+ * **When to use**
+ *
+ * Use to reverse the order of elements without mutating the original input.
+ *
  * **Details**
  *
- * - Does not mutate the input.
  * - Preserves `NonEmptyArray` in the return type.
  *
  * **Example** (Reversing an array)
@@ -3391,9 +3926,12 @@ export declare const reverse: <S extends Iterable<any>>(self: S) => S extends No
 /**
  * Sorts an array by the given `Order`, returning a new array.
  *
+ * **When to use**
+ *
+ * Use to sort an array using a single `Order` comparator.
+ *
  * **Details**
  *
- * - Does not mutate the input.
  * - Preserves `NonEmptyArray` in the return type.
  * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
  *   multi-key sorting.
@@ -3416,9 +3954,12 @@ export declare const sort: {
     /**
      * Sorts an array by the given `Order`, returning a new array.
      *
+     * **When to use**
+     *
+     * Use to sort an array using a single `Order` comparator.
+     *
      * **Details**
      *
-     * - Does not mutate the input.
      * - Preserves `NonEmptyArray` in the return type.
      * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
      *   multi-key sorting.
@@ -3441,9 +3982,12 @@ export declare const sort: {
     /**
      * Sorts an array by the given `Order`, returning a new array.
      *
+     * **When to use**
+     *
+     * Use to sort an array using a single `Order` comparator.
+     *
      * **Details**
      *
-     * - Does not mutate the input.
      * - Preserves `NonEmptyArray` in the return type.
      * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
      *   multi-key sorting.
@@ -3466,9 +4010,12 @@ export declare const sort: {
     /**
      * Sorts an array by the given `Order`, returning a new array.
      *
+     * **When to use**
+     *
+     * Use to sort an array using a single `Order` comparator.
+     *
      * **Details**
      *
-     * - Does not mutate the input.
      * - Preserves `NonEmptyArray` in the return type.
      * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
      *   multi-key sorting.
@@ -3493,10 +4040,14 @@ export declare const sort: {
  * Sorts an array by a derived key using a mapping function and an `Order` for
  * that key.
  *
+ * **When to use**
+ *
+ * Use when values need to be sorted by a derived key, such as a string length
+ * or object field, while the output should keep the original values.
+ *
  * **Details**
  *
  * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
- * - Does not mutate the input.
  *
  * **Example** (Sorting strings by length)
  *
@@ -3507,8 +4058,8 @@ export declare const sort: {
  * // ["b", "cc", "aaa"]
  * ```
  *
- * @see {@link sort} — sort by a direct `Order`
- * @see {@link sortBy} — sort by multiple orders
+ * @see {@link sort} for sorting with an `Order` that compares the elements directly
+ * @see {@link sortBy} for sorting with multiple `Order`s applied in sequence
  *
  * @category elements
  * @since 2.0.0
@@ -3518,10 +4069,14 @@ export declare const sortWith: {
      * Sorts an array by a derived key using a mapping function and an `Order` for
      * that key.
      *
+     * **When to use**
+     *
+     * Use when values need to be sorted by a derived key, such as a string length
+     * or object field, while the output should keep the original values.
+     *
      * **Details**
      *
      * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
-     * - Does not mutate the input.
      *
      * **Example** (Sorting strings by length)
      *
@@ -3532,8 +4087,8 @@ export declare const sortWith: {
      * // ["b", "cc", "aaa"]
      * ```
      *
-     * @see {@link sort} — sort by a direct `Order`
-     * @see {@link sortBy} — sort by multiple orders
+     * @see {@link sort} for sorting with an `Order` that compares the elements directly
+     * @see {@link sortBy} for sorting with multiple `Order`s applied in sequence
      *
      * @category elements
      * @since 2.0.0
@@ -3543,10 +4098,14 @@ export declare const sortWith: {
      * Sorts an array by a derived key using a mapping function and an `Order` for
      * that key.
      *
+     * **When to use**
+     *
+     * Use when values need to be sorted by a derived key, such as a string length
+     * or object field, while the output should keep the original values.
+     *
      * **Details**
      *
      * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
-     * - Does not mutate the input.
      *
      * **Example** (Sorting strings by length)
      *
@@ -3557,8 +4116,8 @@ export declare const sortWith: {
      * // ["b", "cc", "aaa"]
      * ```
      *
-     * @see {@link sort} — sort by a direct `Order`
-     * @see {@link sortBy} — sort by multiple orders
+     * @see {@link sort} for sorting with an `Order` that compares the elements directly
+     * @see {@link sortBy} for sorting with multiple `Order`s applied in sequence
      *
      * @category elements
      * @since 2.0.0
@@ -3568,10 +4127,14 @@ export declare const sortWith: {
      * Sorts an array by a derived key using a mapping function and an `Order` for
      * that key.
      *
+     * **When to use**
+     *
+     * Use when values need to be sorted by a derived key, such as a string length
+     * or object field, while the output should keep the original values.
+     *
      * **Details**
      *
      * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
-     * - Does not mutate the input.
      *
      * **Example** (Sorting strings by length)
      *
@@ -3582,8 +4145,8 @@ export declare const sortWith: {
      * // ["b", "cc", "aaa"]
      * ```
      *
-     * @see {@link sort} — sort by a direct `Order`
-     * @see {@link sortBy} — sort by multiple orders
+     * @see {@link sort} for sorting with an `Order` that compares the elements directly
+     * @see {@link sortBy} for sorting with multiple `Order`s applied in sequence
      *
      * @category elements
      * @since 2.0.0
@@ -3594,6 +4157,11 @@ export declare const sortWith: {
  * Sorts an array by multiple `Order`s applied in sequence: the first order is
  * used first; ties are broken by the second order, and so on.
  *
+ * **When to use**
+ *
+ * Use to sort by multiple criteria where later orders break ties from earlier
+ * ones.
+ *
  * **Details**
  *
  * - Data-last only (returns a function).
@@ -3632,6 +4200,10 @@ export declare const sortBy: <S extends Iterable<any>>(...orders: ReadonlyArray<
  * Pairs elements from two iterables by position. If the iterables differ in
  * length, the extra elements from the longer one are discarded.
  *
+ * **When to use**
+ *
+ * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+ *
  * **Details**
  *
  * - Returns `NonEmptyArray` when both inputs are non-empty.
@@ -3655,6 +4227,10 @@ export declare const zip: {
      * Pairs elements from two iterables by position. If the iterables differ in
      * length, the extra elements from the longer one are discarded.
      *
+     * **When to use**
+     *
+     * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+     *
      * **Details**
      *
      * - Returns `NonEmptyArray` when both inputs are non-empty.
@@ -3678,6 +4254,10 @@ export declare const zip: {
      * Pairs elements from two iterables by position. If the iterables differ in
      * length, the extra elements from the longer one are discarded.
      *
+     * **When to use**
+     *
+     * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+     *
      * **Details**
      *
      * - Returns `NonEmptyArray` when both inputs are non-empty.
@@ -3701,6 +4281,10 @@ export declare const zip: {
      * Pairs elements from two iterables by position. If the iterables differ in
      * length, the extra elements from the longer one are discarded.
      *
+     * **When to use**
+     *
+     * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+     *
      * **Details**
      *
      * - Returns `NonEmptyArray` when both inputs are non-empty.
@@ -3724,6 +4308,10 @@ export declare const zip: {
      * Pairs elements from two iterables by position. If the iterables differ in
      * length, the extra elements from the longer one are discarded.
      *
+     * **When to use**
+     *
+     * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+     *
      * **Details**
      *
      * - Returns `NonEmptyArray` when both inputs are non-empty.
@@ -3855,6 +4443,10 @@ export declare const unzip: <S extends Iterable<readonly [any, any]>>(self: S) =
 /**
  * Places a separator element between every pair of elements.
  *
+ * **When to use**
+ *
+ * Use to insert a separator between elements, for example when preparing data for display or concatenation.
+ *
  * **Details**
  *
  * - Preserves `NonEmptyArray` in the return type.
@@ -3877,6 +4469,10 @@ export declare const intersperse: {
     /**
      * Places a separator element between every pair of elements.
      *
+     * **When to use**
+     *
+     * Use to insert a separator between elements, for example when preparing data for display or concatenation.
+     *
      * **Details**
      *
      * - Preserves `NonEmptyArray` in the return type.
@@ -3899,6 +4495,10 @@ export declare const intersperse: {
     /**
      * Places a separator element between every pair of elements.
      *
+     * **When to use**
+     *
+     * Use to insert a separator between elements, for example when preparing data for display or concatenation.
+     *
      * **Details**
      *
      * - Preserves `NonEmptyArray` in the return type.
@@ -3921,6 +4521,10 @@ export declare const intersperse: {
     /**
      * Places a separator element between every pair of elements.
      *
+     * **When to use**
+     *
+     * Use to insert a separator between elements, for example when preparing data for display or concatenation.
+     *
      * **Details**
      *
      * - Preserves `NonEmptyArray` in the return type.
@@ -3945,6 +4549,10 @@ export declare const intersperse: {
  * Applies a function to the first element of a non-empty array, returning a
  * new array.
  *
+ * **When to use**
+ *
+ * Use to transform the first element of a non-empty array while preserving the rest.
+ *
  * **Example** (Modifying the head)
  *
  * ```ts
@@ -3964,6 +4572,10 @@ export declare const modifyHeadNonEmpty: {
      * Applies a function to the first element of a non-empty array, returning a
      * new array.
      *
+     * **When to use**
+     *
+     * Use to transform the first element of a non-empty array while preserving the rest.
+     *
      * **Example** (Modifying the head)
      *
      * ```ts
@@ -3983,6 +4595,10 @@ export declare const modifyHeadNonEmpty: {
      * Applies a function to the first element of a non-empty array, returning a
      * new array.
      *
+     * **When to use**
+     *
+     * Use to transform the first element of a non-empty array while preserving the rest.
+     *
      * **Example** (Modifying the head)
      *
      * ```ts
@@ -4168,9 +4784,14 @@ export declare const setLastNonEmpty: {
     <A, B>(self: NonEmptyReadonlyArray<A>, b: B): NonEmptyArray<A | B>;
 };
 /**
- * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+ * Transforms an array by rotating it `n` steps. Positive `n` rotates right; negative `n`
  * rotates left.
  *
+ * **When to use**
+ *
+ * Use when elements should wrap around the end of the array rather than being
+ * dropped.
+ *
  * **Details**
  *
  * - `n` is rounded to the nearest integer before rotating.
@@ -4185,14 +4806,22 @@ export declare const setLastNonEmpty: {
  * console.log(Array.rotate(["a", "b", "c", "d"], 2)) // ["c", "d", "a", "b"]
  * ```
  *
+ * @see {@link take} for taking a fixed number of elements from the start
+ * @see {@link drop} for dropping a fixed number of elements from the start
+ *
  * @category elements
  * @since 2.0.0
  */
 export declare const rotate: {
     /**
-     * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+     * Transforms an array by rotating it `n` steps. Positive `n` rotates right; negative `n`
      * rotates left.
      *
+     * **When to use**
+     *
+     * Use when elements should wrap around the end of the array rather than being
+     * dropped.
+     *
      * **Details**
      *
      * - `n` is rounded to the nearest integer before rotating.
@@ -4207,14 +4836,22 @@ export declare const rotate: {
      * console.log(Array.rotate(["a", "b", "c", "d"], 2)) // ["c", "d", "a", "b"]
      * ```
      *
+     * @see {@link take} for taking a fixed number of elements from the start
+     * @see {@link drop} for dropping a fixed number of elements from the start
+     *
      * @category elements
      * @since 2.0.0
      */
     (n: number): <S extends Iterable<any>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>;
     /**
-     * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+     * Transforms an array by rotating it `n` steps. Positive `n` rotates right; negative `n`
      * rotates left.
      *
+     * **When to use**
+     *
+     * Use when elements should wrap around the end of the array rather than being
+     * dropped.
+     *
      * **Details**
      *
      * - `n` is rounded to the nearest integer before rotating.
@@ -4229,14 +4866,22 @@ export declare const rotate: {
      * console.log(Array.rotate(["a", "b", "c", "d"], 2)) // ["c", "d", "a", "b"]
      * ```
      *
+     * @see {@link take} for taking a fixed number of elements from the start
+     * @see {@link drop} for dropping a fixed number of elements from the start
+     *
      * @category elements
      * @since 2.0.0
      */
     <A>(self: NonEmptyReadonlyArray<A>, n: number): NonEmptyArray<A>;
     /**
-     * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+     * Transforms an array by rotating it `n` steps. Positive `n` rotates right; negative `n`
      * rotates left.
      *
+     * **When to use**
+     *
+     * Use when elements should wrap around the end of the array rather than being
+     * dropped.
+     *
      * **Details**
      *
      * - `n` is rounded to the nearest integer before rotating.
@@ -4251,6 +4896,9 @@ export declare const rotate: {
      * console.log(Array.rotate(["a", "b", "c", "d"], 2)) // ["c", "d", "a", "b"]
      * ```
      *
+     * @see {@link take} for taking a fixed number of elements from the start
+     * @see {@link drop} for dropping a fixed number of elements from the start
+     *
      * @category elements
      * @since 2.0.0
      */
@@ -4259,6 +4907,11 @@ export declare const rotate: {
 /**
  * Returns a membership-test function using a custom equivalence.
  *
+ * **When to use**
+ *
+ * Use when checking membership with caller-provided equality instead of
+ * `Equal.equivalence()`.
+ *
  * **Example** (Custom equality check)
  *
  * ```ts
@@ -4268,7 +4921,7 @@ export declare const rotate: {
  * console.log(pipe([1, 2, 3, 4], containsNumber(3))) // true
  * ```
  *
- * @see {@link contains} — uses default `Equal.equivalence()`
+ * @see {@link contains} for the `Equal.equivalence()` variant
  *
  * @category elements
  * @since 2.0.0
@@ -4278,9 +4931,14 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
     (self: Iterable<A>, a: A): boolean;
 };
 /**
- * Tests whether an array contains a value, using `Equal.equivalence()` for
+ * Checks whether an array contains a value, using `Equal.equivalence()` for
  * comparison.
  *
+ * **When to use**
+ *
+ * Use to check membership with Effect's default equality instead of providing a
+ * comparison function.
+ *
  * **Example** (Checking membership)
  *
  * ```ts
@@ -4296,9 +4954,14 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
  */
 export declare const contains: {
     /**
-     * Tests whether an array contains a value, using `Equal.equivalence()` for
+     * Checks whether an array contains a value, using `Equal.equivalence()` for
      * comparison.
      *
+     * **When to use**
+     *
+     * Use to check membership with Effect's default equality instead of providing a
+     * comparison function.
+     *
      * **Example** (Checking membership)
      *
      * ```ts
@@ -4314,9 +4977,14 @@ export declare const contains: {
      */
     <A>(a: A): (self: Iterable<A>) => boolean;
     /**
-     * Tests whether an array contains a value, using `Equal.equivalence()` for
+     * Checks whether an array contains a value, using `Equal.equivalence()` for
      * comparison.
      *
+     * **When to use**
+     *
+     * Use to check membership with Effect's default equality instead of providing a
+     * comparison function.
+     *
      * **Example** (Checking membership)
      *
      * ```ts
@@ -4333,8 +5001,13 @@ export declare const contains: {
     <A>(self: Iterable<A>, a: A): boolean;
 };
 /**
- * Repeatedly applies a function that consumes a prefix of the array and
- * produces a value plus the remaining elements, collecting the values.
+ * Applies a function repeatedly to consume prefixes of the array and collect
+ * the values it produces.
+ *
+ * **When to use**
+ *
+ * Use when the grouping logic is custom and each step needs to return both a
+ * value and the remaining input.
  *
  * **Details**
  *
@@ -4363,8 +5036,13 @@ export declare const contains: {
  */
 export declare const chop: {
     /**
-     * Repeatedly applies a function that consumes a prefix of the array and
-     * produces a value plus the remaining elements, collecting the values.
+     * Applies a function repeatedly to consume prefixes of the array and collect
+     * the values it produces.
+     *
+     * **When to use**
+     *
+     * Use when the grouping logic is custom and each step needs to return both a
+     * value and the remaining input.
      *
      * **Details**
      *
@@ -4393,8 +5071,13 @@ export declare const chop: {
      */
     <S extends Iterable<any>, B>(f: (as: NonEmptyReadonlyArray<ReadonlyArray.Infer<S>>) => readonly [B, ReadonlyArray<ReadonlyArray.Infer<S>>]): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>;
     /**
-     * Repeatedly applies a function that consumes a prefix of the array and
-     * produces a value plus the remaining elements, collecting the values.
+     * Applies a function repeatedly to consume prefixes of the array and collect
+     * the values it produces.
+     *
+     * **When to use**
+     *
+     * Use when the grouping logic is custom and each step needs to return both a
+     * value and the remaining input.
      *
      * **Details**
      *
@@ -4423,8 +5106,13 @@ export declare const chop: {
      */
     <A, B>(self: NonEmptyReadonlyArray<A>, f: (as: NonEmptyReadonlyArray<A>) => readonly [B, ReadonlyArray<A>]): NonEmptyArray<B>;
     /**
-     * Repeatedly applies a function that consumes a prefix of the array and
-     * produces a value plus the remaining elements, collecting the values.
+     * Applies a function repeatedly to consume prefixes of the array and collect
+     * the values it produces.
+     *
+     * **When to use**
+     *
+     * Use when the grouping logic is custom and each step needs to return both a
+     * value and the remaining input.
      *
      * **Details**
      *
@@ -4456,6 +5144,10 @@ export declare const chop: {
 /**
  * Splits an iterable into two arrays at the given index.
  *
+ * **When to use**
+ *
+ * Use to divide an array into a prefix and suffix at a specific position.
+ *
  * **Details**
  *
  * - `n` can be `0` (all elements in the second array).
@@ -4479,6 +5171,10 @@ export declare const splitAt: {
     /**
      * Splits an iterable into two arrays at the given index.
      *
+     * **When to use**
+     *
+     * Use to divide an array into a prefix and suffix at a specific position.
+     *
      * **Details**
      *
      * - `n` can be `0` (all elements in the second array).
@@ -4502,6 +5198,10 @@ export declare const splitAt: {
     /**
      * Splits an iterable into two arrays at the given index.
      *
+     * **When to use**
+     *
+     * Use to divide an array into a prefix and suffix at a specific position.
+     *
      * **Details**
      *
      * - `n` can be `0` (all elements in the second array).
@@ -4584,6 +5284,10 @@ export declare const splitAtNonEmpty: {
 /**
  * Splits an iterable into `n` roughly equal-sized chunks.
  *
+ * **When to use**
+ *
+ * Use to distribute elements across a fixed number of groups, such as when splitting work across threads.
+ *
  * **Details**
  *
  * - Uses `chunksOf(ceil(length / n))` internally.
@@ -4606,6 +5310,10 @@ export declare const split: {
     /**
      * Splits an iterable into `n` roughly equal-sized chunks.
      *
+     * **When to use**
+     *
+     * Use to distribute elements across a fixed number of groups, such as when splitting work across threads.
+     *
      * **Details**
      *
      * - Uses `chunksOf(ceil(length / n))` internally.
@@ -4628,6 +5336,10 @@ export declare const split: {
     /**
      * Splits an iterable into `n` roughly equal-sized chunks.
      *
+     * **When to use**
+     *
+     * Use to distribute elements across a fixed number of groups, such as when splitting work across threads.
+     *
      * **Details**
      *
      * - Uses `chunksOf(ceil(length / n))` internally.
@@ -4652,6 +5364,10 @@ export declare const split: {
  * Splits an iterable at the first element matching the predicate. The matching
  * element is included in the second array.
  *
+ * **When to use**
+ *
+ * Use to split an array at a condition boundary when you know which element marks the transition point.
+ *
  * **Example** (Splitting at a condition)
  *
  * ```ts
@@ -4671,6 +5387,10 @@ export declare const splitWhere: {
      * Splits an iterable at the first element matching the predicate. The matching
      * element is included in the second array.
      *
+     * **When to use**
+     *
+     * Use to split an array at a condition boundary when you know which element marks the transition point.
+     *
      * **Example** (Splitting at a condition)
      *
      * ```ts
@@ -4690,6 +5410,10 @@ export declare const splitWhere: {
      * Splits an iterable at the first element matching the predicate. The matching
      * element is included in the second array.
      *
+     * **When to use**
+     *
+     * Use to split an array at a condition boundary when you know which element marks the transition point.
+     *
      * **Example** (Splitting at a condition)
      *
      * ```ts
@@ -4709,6 +5433,11 @@ export declare const splitWhere: {
 /**
  * Creates a shallow copy of an array.
  *
+ * **When to use**
+ *
+ * Use to create a distinct array reference for an existing array, for example
+ * before mutating the returned array.
+ *
  * **Details**
  *
  * - Preserves `NonEmptyArray` in the return type.
@@ -4734,6 +5463,11 @@ export declare const copy: {
     /**
      * Creates a shallow copy of an array.
      *
+     * **When to use**
+     *
+     * Use to create a distinct array reference for an existing array, for example
+     * before mutating the returned array.
+     *
      * **Details**
      *
      * - Preserves `NonEmptyArray` in the return type.
@@ -4759,6 +5493,11 @@ export declare const copy: {
     /**
      * Creates a shallow copy of an array.
      *
+     * **When to use**
+     *
+     * Use to create a distinct array reference for an existing array, for example
+     * before mutating the returned array.
+     *
      * **Details**
      *
      * - Preserves `NonEmptyArray` in the return type.
@@ -4786,6 +5525,10 @@ export declare const copy: {
  * Pads or truncates an array to exactly `n` elements, filling with `fill`
  * if the array is shorter, or slicing if longer.
  *
+ * **When to use**
+ *
+ * Use to ensure an array has a specific length, padding with a fill value or truncating as needed.
+ *
  * **Details**
  *
  * - Returns an empty array when `n <= 0`.
@@ -4809,6 +5552,10 @@ export declare const pad: {
      * Pads or truncates an array to exactly `n` elements, filling with `fill`
      * if the array is shorter, or slicing if longer.
      *
+     * **When to use**
+     *
+     * Use to ensure an array has a specific length, padding with a fill value or truncating as needed.
+     *
      * **Details**
      *
      * - Returns an empty array when `n <= 0`.
@@ -4832,6 +5579,10 @@ export declare const pad: {
      * Pads or truncates an array to exactly `n` elements, filling with `fill`
      * if the array is shorter, or slicing if longer.
      *
+     * **When to use**
+     *
+     * Use to ensure an array has a specific length, padding with a fill value or truncating as needed.
+     *
      * **Details**
      *
      * - Returns an empty array when `n <= 0`.
@@ -4856,6 +5607,11 @@ export declare const pad: {
  * Splits an iterable into chunks of length `n`. The last chunk may be shorter
  * if `n` does not evenly divide the length.
  *
+ * **When to use**
+ *
+ * Use to divide an iterable into non-overlapping chunks with a maximum chunk
+ * size.
+ *
  * **Details**
  *
  * - `chunksOf(n)([])` is `[]`, not `[[]]`.
@@ -4881,6 +5637,11 @@ export declare const chunksOf: {
      * Splits an iterable into chunks of length `n`. The last chunk may be shorter
      * if `n` does not evenly divide the length.
      *
+     * **When to use**
+     *
+     * Use to divide an iterable into non-overlapping chunks with a maximum chunk
+     * size.
+     *
      * **Details**
      *
      * - `chunksOf(n)([])` is `[]`, not `[[]]`.
@@ -4906,6 +5667,11 @@ export declare const chunksOf: {
      * Splits an iterable into chunks of length `n`. The last chunk may be shorter
      * if `n` does not evenly divide the length.
      *
+     * **When to use**
+     *
+     * Use to divide an iterable into non-overlapping chunks with a maximum chunk
+     * size.
+     *
      * **Details**
      *
      * - `chunksOf(n)([])` is `[]`, not `[[]]`.
@@ -4931,6 +5697,11 @@ export declare const chunksOf: {
      * Splits an iterable into chunks of length `n`. The last chunk may be shorter
      * if `n` does not evenly divide the length.
      *
+     * **When to use**
+     *
+     * Use to divide an iterable into non-overlapping chunks with a maximum chunk
+     * size.
+     *
      * **Details**
      *
      * - `chunksOf(n)([])` is `[]`, not `[[]]`.
@@ -4956,6 +5727,10 @@ export declare const chunksOf: {
 /**
  * Creates overlapping sliding windows of size `n`.
  *
+ * **When to use**
+ *
+ * Use to process sequences with a moving window, such as for computing running averages or detecting patterns.
+ *
  * **Details**
  *
  * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
@@ -4979,6 +5754,10 @@ export declare const window: {
     /**
      * Creates overlapping sliding windows of size `n`.
      *
+     * **When to use**
+     *
+     * Use to process sequences with a moving window, such as for computing running averages or detecting patterns.
+     *
      * **Details**
      *
      * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
@@ -5002,6 +5781,10 @@ export declare const window: {
     /**
      * Creates overlapping sliding windows of size `n`.
      *
+     * **When to use**
+     *
+     * Use to process sequences with a moving window, such as for computing running averages or detecting patterns.
+     *
      * **Details**
      *
      * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
@@ -5026,6 +5809,11 @@ export declare const window: {
 /**
  * Groups consecutive equal elements using a custom equivalence function.
  *
+ * **When to use**
+ *
+ * Use when a non-empty array is already arranged so matching elements are
+ * adjacent and you need a custom equivalence function.
+ *
  * **Details**
  *
  * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
@@ -5040,8 +5828,8 @@ export declare const window: {
  * // [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
  * ```
  *
- * @see {@link group} — uses default equality
- * @see {@link groupBy} — group by a key function into a record
+ * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+ * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
  *
  * @category grouping
  * @since 2.0.0
@@ -5050,6 +5838,11 @@ export declare const groupWith: {
     /**
      * Groups consecutive equal elements using a custom equivalence function.
      *
+     * **When to use**
+     *
+     * Use when a non-empty array is already arranged so matching elements are
+     * adjacent and you need a custom equivalence function.
+     *
      * **Details**
      *
      * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
@@ -5064,8 +5857,8 @@ export declare const groupWith: {
      * // [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
      * ```
      *
-     * @see {@link group} — uses default equality
-     * @see {@link groupBy} — group by a key function into a record
+     * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+     * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
      *
      * @category grouping
      * @since 2.0.0
@@ -5074,6 +5867,11 @@ export declare const groupWith: {
     /**
      * Groups consecutive equal elements using a custom equivalence function.
      *
+     * **When to use**
+     *
+     * Use when a non-empty array is already arranged so matching elements are
+     * adjacent and you need a custom equivalence function.
+     *
      * **Details**
      *
      * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
@@ -5088,8 +5886,8 @@ export declare const groupWith: {
      * // [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
      * ```
      *
-     * @see {@link group} — uses default equality
-     * @see {@link groupBy} — group by a key function into a record
+     * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+     * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
      *
      * @category grouping
      * @since 2.0.0
@@ -5099,6 +5897,11 @@ export declare const groupWith: {
 /**
  * Groups consecutive equal elements using `Equal.equivalence()`.
  *
+ * **When to use**
+ *
+ * Use when equal values are already adjacent and Effect's default equality is
+ * the right comparison.
+ *
  * **Details**
  *
  * - Only groups **adjacent** elements.
@@ -5122,6 +5925,10 @@ export declare const group: <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray
  * Groups elements into a record by a key-returning function. Each key maps
  * to a `NonEmptyArray` of elements that produced that key.
  *
+ * **When to use**
+ *
+ * Use to build buckets of elements indexed by a computed string or symbol key.
+ *
  * **Details**
  *
  * - Unlike {@link group}/{@link groupWith}, elements do not need to be
@@ -5155,6 +5962,10 @@ export declare const groupBy: {
      * Groups elements into a record by a key-returning function. Each key maps
      * to a `NonEmptyArray` of elements that produced that key.
      *
+     * **When to use**
+     *
+     * Use to build buckets of elements indexed by a computed string or symbol key.
+     *
      * **Details**
      *
      * - Unlike {@link group}/{@link groupWith}, elements do not need to be
@@ -5188,6 +5999,10 @@ export declare const groupBy: {
      * Groups elements into a record by a key-returning function. Each key maps
      * to a `NonEmptyArray` of elements that produced that key.
      *
+     * **When to use**
+     *
+     * Use to build buckets of elements indexed by a computed string or symbol key.
+     *
      * **Details**
      *
      * - Unlike {@link group}/{@link groupWith}, elements do not need to be
@@ -5222,6 +6037,11 @@ export declare const groupBy: {
  * Computes the union of two arrays using a custom equivalence, removing
  * duplicates.
  *
+ * **When to use**
+ *
+ * Use when you need the union of two arrays but duplicate detection must use a
+ * custom equivalence instead of the default `Equal.equivalence()`.
+ *
  * **Example** (Union with custom equality)
  *
  * ```ts
@@ -5230,9 +6050,9 @@ export declare const groupBy: {
  * console.log(Array.unionWith([1, 2], [2, 3], (a, b) => a === b)) // [1, 2, 3]
  * ```
  *
- * @see {@link union} — uses default equality
- * @see {@link intersection} — elements in both arrays
- * @see {@link difference} — elements only in the first array
+ * @see {@link union} for the `Equal.equivalence()` variant
+ * @see {@link intersectionWith} for keeping elements present in both arrays
+ * @see {@link differenceWith} for keeping elements present only in the first array
  *
  * @category elements
  * @since 2.0.0
@@ -5242,6 +6062,11 @@ export declare const unionWith: {
      * Computes the union of two arrays using a custom equivalence, removing
      * duplicates.
      *
+     * **When to use**
+     *
+     * Use when you need the union of two arrays but duplicate detection must use a
+     * custom equivalence instead of the default `Equal.equivalence()`.
+     *
      * **Example** (Union with custom equality)
      *
      * ```ts
@@ -5250,9 +6075,9 @@ export declare const unionWith: {
      * console.log(Array.unionWith([1, 2], [2, 3], (a, b) => a === b)) // [1, 2, 3]
      * ```
      *
-     * @see {@link union} — uses default equality
-     * @see {@link intersection} — elements in both arrays
-     * @see {@link difference} — elements only in the first array
+     * @see {@link union} for the `Equal.equivalence()` variant
+     * @see {@link intersectionWith} for keeping elements present in both arrays
+     * @see {@link differenceWith} for keeping elements present only in the first array
      *
      * @category elements
      * @since 2.0.0
@@ -5262,6 +6087,11 @@ export declare const unionWith: {
      * Computes the union of two arrays using a custom equivalence, removing
      * duplicates.
      *
+     * **When to use**
+     *
+     * Use when you need the union of two arrays but duplicate detection must use a
+     * custom equivalence instead of the default `Equal.equivalence()`.
+     *
      * **Example** (Union with custom equality)
      *
      * ```ts
@@ -5270,9 +6100,9 @@ export declare const unionWith: {
      * console.log(Array.unionWith([1, 2], [2, 3], (a, b) => a === b)) // [1, 2, 3]
      * ```
      *
-     * @see {@link union} — uses default equality
-     * @see {@link intersection} — elements in both arrays
-     * @see {@link difference} — elements only in the first array
+     * @see {@link union} for the `Equal.equivalence()` variant
+     * @see {@link intersectionWith} for keeping elements present in both arrays
+     * @see {@link differenceWith} for keeping elements present only in the first array
      *
      * @category elements
      * @since 2.0.0
@@ -5282,6 +6112,11 @@ export declare const unionWith: {
      * Computes the union of two arrays using a custom equivalence, removing
      * duplicates.
      *
+     * **When to use**
+     *
+     * Use when you need the union of two arrays but duplicate detection must use a
+     * custom equivalence instead of the default `Equal.equivalence()`.
+     *
      * **Example** (Union with custom equality)
      *
      * ```ts
@@ -5290,9 +6125,9 @@ export declare const unionWith: {
      * console.log(Array.unionWith([1, 2], [2, 3], (a, b) => a === b)) // [1, 2, 3]
      * ```
      *
-     * @see {@link union} — uses default equality
-     * @see {@link intersection} — elements in both arrays
-     * @see {@link difference} — elements only in the first array
+     * @see {@link union} for the `Equal.equivalence()` variant
+     * @see {@link intersectionWith} for keeping elements present in both arrays
+     * @see {@link differenceWith} for keeping elements present only in the first array
      *
      * @category elements
      * @since 2.0.0
@@ -5302,6 +6137,11 @@ export declare const unionWith: {
      * Computes the union of two arrays using a custom equivalence, removing
      * duplicates.
      *
+     * **When to use**
+     *
+     * Use when you need the union of two arrays but duplicate detection must use a
+     * custom equivalence instead of the default `Equal.equivalence()`.
+     *
      * **Example** (Union with custom equality)
      *
      * ```ts
@@ -5310,9 +6150,9 @@ export declare const unionWith: {
      * console.log(Array.unionWith([1, 2], [2, 3], (a, b) => a === b)) // [1, 2, 3]
      * ```
      *
-     * @see {@link union} — uses default equality
-     * @see {@link intersection} — elements in both arrays
-     * @see {@link difference} — elements only in the first array
+     * @see {@link union} for the `Equal.equivalence()` variant
+     * @see {@link intersectionWith} for keeping elements present in both arrays
+     * @see {@link differenceWith} for keeping elements present only in the first array
      *
      * @category elements
      * @since 2.0.0
@@ -5424,6 +6264,11 @@ export declare const union: {
  * Computes the intersection of two arrays using a custom equivalence. Order is
  * determined by the first array.
  *
+ * **When to use**
+ *
+ * Use when keeping only values present in both arrays and equality must be
+ * defined by a custom comparator, such as matching objects by id.
+ *
  * **Example** (Intersection with custom equality)
  *
  * ```ts
@@ -5435,9 +6280,9 @@ export declare const union: {
  * console.log(Array.intersectionWith(isEquivalent)(array2)(array1)) // [{ id: 1 }, { id: 3 }]
  * ```
  *
- * @see {@link intersection} — uses default equality
- * @see {@link union} — elements in either array
- * @see {@link difference} — elements only in the first array
+ * @see {@link intersection} for the `Equal.equivalence()` variant
+ * @see {@link unionWith} for keeping values from either array with custom equality
+ * @see {@link differenceWith} for keeping values only from the first array with custom equality
  *
  * @category elements
  * @since 2.0.0
@@ -5511,6 +6356,11 @@ export declare const intersection: {
  * Computes elements in the first array that are not in the second, using a
  * custom equivalence.
  *
+ * **When to use**
+ *
+ * Use when keeping only values from the first array and equality must be
+ * defined by a custom comparator, such as matching objects by id.
+ *
  * **Example** (Difference with custom equality)
  *
  * ```ts
@@ -5520,9 +6370,9 @@ export declare const intersection: {
  * console.log(diff) // [1]
  * ```
  *
- * @see {@link difference} — uses default equality
- * @see {@link union} — elements in either array
- * @see {@link intersection} — elements in both arrays
+ * @see {@link difference} for the `Equal.equivalence()` variant
+ * @see {@link unionWith} for keeping values from either array with custom equality
+ * @see {@link intersectionWith} for keeping values present in both arrays with custom equality
  *
  * @category elements
  * @since 2.0.0
@@ -5535,6 +6385,11 @@ export declare const differenceWith: <A>(isEquivalent: (self: A, that: A) => boo
  * Computes elements in the first array that are not in the second, using
  * `Equal.equivalence()`.
  *
+ * **When to use**
+ *
+ * Use when you need to keep values from the first array that are absent from
+ * the second and the default `Equal.equivalence()` comparison is appropriate.
+ *
  * **Example** (Array difference)
  *
  * ```ts
@@ -5555,6 +6410,11 @@ export declare const difference: {
      * Computes elements in the first array that are not in the second, using
      * `Equal.equivalence()`.
      *
+     * **When to use**
+     *
+     * Use when you need to keep values from the first array that are absent from
+     * the second and the default `Equal.equivalence()` comparison is appropriate.
+     *
      * **Example** (Array difference)
      *
      * ```ts
@@ -5575,6 +6435,11 @@ export declare const difference: {
      * Computes elements in the first array that are not in the second, using
      * `Equal.equivalence()`.
      *
+     * **When to use**
+     *
+     * Use when you need to keep values from the first array that are absent from
+     * the second and the default `Equal.equivalence()` comparison is appropriate.
+     *
      * **Example** (Array difference)
      *
      * ```ts
@@ -5595,6 +6460,10 @@ export declare const difference: {
 /**
  * Creates an empty array.
  *
+ * **When to use**
+ *
+ * Use to create a typed empty array without allocating placeholder elements.
+ *
  * **Example** (Creating an empty array)
  *
  * ```ts
@@ -5729,6 +6598,10 @@ export declare namespace ReadonlyArray {
 /**
  * Transforms each element using a function, returning a new array.
  *
+ * **When to use**
+ *
+ * Use to transform each element independently while preserving the array shape.
+ *
  * **Details**
  *
  * - The function receives `(element, index)`.
@@ -5751,6 +6624,10 @@ export declare const map: {
     /**
      * Transforms each element using a function, returning a new array.
      *
+     * **When to use**
+     *
+     * Use to transform each element independently while preserving the array shape.
+     *
      * **Details**
      *
      * - The function receives `(element, index)`.
@@ -5773,6 +6650,10 @@ export declare const map: {
     /**
      * Transforms each element using a function, returning a new array.
      *
+     * **When to use**
+     *
+     * Use to transform each element independently while preserving the array shape.
+     *
      * **Details**
      *
      * - The function receives `(element, index)`.
@@ -5796,6 +6677,11 @@ export declare const map: {
 /**
  * Maps each element to an array and flattens the results into a single array.
  *
+ * **When to use**
+ *
+ * Use to map each element to zero or more values and concatenate the results in
+ * one pass.
+ *
  * **Details**
  *
  * - The function receives `(element, index)`.
@@ -5819,6 +6705,11 @@ export declare const flatMap: {
     /**
      * Maps each element to an array and flattens the results into a single array.
      *
+     * **When to use**
+     *
+     * Use to map each element to zero or more values and concatenate the results in
+     * one pass.
+     *
      * **Details**
      *
      * - The function receives `(element, index)`.
@@ -5842,6 +6733,11 @@ export declare const flatMap: {
     /**
      * Maps each element to an array and flattens the results into a single array.
      *
+     * **When to use**
+     *
+     * Use to map each element to zero or more values and concatenate the results in
+     * one pass.
+     *
      * **Details**
      *
      * - The function receives `(element, index)`.
@@ -5865,6 +6761,11 @@ export declare const flatMap: {
     /**
      * Maps each element to an array and flattens the results into a single array.
      *
+     * **When to use**
+     *
+     * Use to map each element to zero or more values and concatenate the results in
+     * one pass.
+     *
      * **Details**
      *
      * - The function receives `(element, index)`.
@@ -5889,6 +6790,11 @@ export declare const flatMap: {
 /**
  * Flattens a nested array of arrays into a single array.
  *
+ * **When to use**
+ *
+ * Use to collapse one level of nested arrays when no per-element mapping is
+ * needed.
+ *
  * **Example** (Flattening nested arrays)
  *
  * ```ts
@@ -5906,6 +6812,11 @@ export declare const flatten: <const S extends ReadonlyArray<ReadonlyArray<any>>
 /**
  * Extracts all `Some` values from an iterable of `Option`s, discarding `None`s.
  *
+ * **When to use**
+ *
+ * Use to collect only present values from `Option` values while discarding
+ * `None` values.
+ *
  * **Example** (Extracting Some values)
  *
  * ```ts
@@ -5925,6 +6836,11 @@ export declare const getSomes: <T extends Iterable<Option.Option<X>>, X = any>(s
  * Extracts all failure values from an iterable of `Result`s, discarding
  * successes.
  *
+ * **When to use**
+ *
+ * Use to collect only failure values from `Result` values while discarding
+ * successes.
+ *
  * **Example** (Extracting failures)
  *
  * ```ts
@@ -5945,6 +6861,11 @@ export declare const getFailures: <T extends Iterable<Result.Result<any, any>>>(
  * Extracts all success values from an iterable of `Result`s, discarding
  * failures.
  *
+ * **When to use**
+ *
+ * Use to collect only success values from `Result` values while discarding
+ * failures.
+ *
  * **Example** (Extracting successes)
  *
  * ```ts
@@ -5964,6 +6885,11 @@ export declare const getSuccesses: <T extends Iterable<Result.Result<any, any>>>
 /**
  * Keeps transformed values for elements where a `Filter` succeeds.
  *
+ * **When to use**
+ *
+ * Use to transform elements with a `Result`-returning filter while discarding
+ * failures.
+ *
  * **Details**
  *
  * - The filter receives `(element, index)`.
@@ -5979,6 +6905,7 @@ export declare const getSuccesses: <T extends Iterable<Result.Result<any, any>>>
  * ```
  *
  * @see {@link filter} — keep original elements matching a predicate
+ * @see {@link partition} for keeping both failures and successes
  *
  * @category filtering
  * @since 2.0.0
@@ -5987,6 +6914,11 @@ export declare const filterMap: {
     /**
      * Keeps transformed values for elements where a `Filter` succeeds.
      *
+     * **When to use**
+     *
+     * Use to transform elements with a `Result`-returning filter while discarding
+     * failures.
+     *
      * **Details**
      *
      * - The filter receives `(element, index)`.
@@ -6002,6 +6934,7 @@ export declare const filterMap: {
      * ```
      *
      * @see {@link filter} — keep original elements matching a predicate
+     * @see {@link partition} for keeping both failures and successes
      *
      * @category filtering
      * @since 2.0.0
@@ -6010,6 +6943,11 @@ export declare const filterMap: {
     /**
      * Keeps transformed values for elements where a `Filter` succeeds.
      *
+     * **When to use**
+     *
+     * Use to transform elements with a `Result`-returning filter while discarding
+     * failures.
+     *
      * **Details**
      *
      * - The filter receives `(element, index)`.
@@ -6025,6 +6963,7 @@ export declare const filterMap: {
      * ```
      *
      * @see {@link filter} — keep original elements matching a predicate
+     * @see {@link partition} for keeping both failures and successes
      *
      * @category filtering
      * @since 2.0.0
@@ -6034,6 +6973,10 @@ export declare const filterMap: {
 /**
  * Keeps only elements satisfying a predicate (or refinement).
  *
+ * **When to use**
+ *
+ * Use to keep original elements that satisfy a boolean predicate or refinement.
+ *
  * **Details**
  *
  * - The predicate receives `(element, index)`.
@@ -6048,6 +6991,7 @@ export declare const filterMap: {
  * ```
  *
  * @see {@link partition} — split into matching and non-matching
+ * @see {@link filterMap} for transforming while filtering
  *
  * @category filtering
  * @since 2.0.0
@@ -6056,6 +7000,10 @@ export declare const filter: {
     /**
      * Keeps only elements satisfying a predicate (or refinement).
      *
+     * **When to use**
+     *
+     * Use to keep original elements that satisfy a boolean predicate or refinement.
+     *
      * **Details**
      *
      * - The predicate receives `(element, index)`.
@@ -6070,6 +7018,7 @@ export declare const filter: {
      * ```
      *
      * @see {@link partition} — split into matching and non-matching
+     * @see {@link filterMap} for transforming while filtering
      *
      * @category filtering
      * @since 2.0.0
@@ -6078,6 +7027,10 @@ export declare const filter: {
     /**
      * Keeps only elements satisfying a predicate (or refinement).
      *
+     * **When to use**
+     *
+     * Use to keep original elements that satisfy a boolean predicate or refinement.
+     *
      * **Details**
      *
      * - The predicate receives `(element, index)`.
@@ -6092,6 +7045,7 @@ export declare const filter: {
      * ```
      *
      * @see {@link partition} — split into matching and non-matching
+     * @see {@link filterMap} for transforming while filtering
      *
      * @category filtering
      * @since 2.0.0
@@ -6100,6 +7054,10 @@ export declare const filter: {
     /**
      * Keeps only elements satisfying a predicate (or refinement).
      *
+     * **When to use**
+     *
+     * Use to keep original elements that satisfy a boolean predicate or refinement.
+     *
      * **Details**
      *
      * - The predicate receives `(element, index)`.
@@ -6114,6 +7072,7 @@ export declare const filter: {
      * ```
      *
      * @see {@link partition} — split into matching and non-matching
+     * @see {@link filterMap} for transforming while filtering
      *
      * @category filtering
      * @since 2.0.0
@@ -6122,6 +7081,10 @@ export declare const filter: {
     /**
      * Keeps only elements satisfying a predicate (or refinement).
      *
+     * **When to use**
+     *
+     * Use to keep original elements that satisfy a boolean predicate or refinement.
+     *
      * **Details**
      *
      * - The predicate receives `(element, index)`.
@@ -6136,6 +7099,7 @@ export declare const filter: {
      * ```
      *
      * @see {@link partition} — split into matching and non-matching
+     * @see {@link filterMap} for transforming while filtering
      *
      * @category filtering
      * @since 2.0.0
@@ -6145,6 +7109,11 @@ export declare const filter: {
 /**
  * Splits an iterable using a `Filter` into failures and successes.
  *
+ * **When to use**
+ *
+ * Use to evaluate each element with a `Result`-returning filter and keep both
+ * failure and success values.
+ *
  * **Details**
  *
  * - Returns `[excluded, satisfying]`.
@@ -6162,6 +7131,7 @@ export declare const filter: {
  * ```
  *
  * @see {@link filter} — keep only matching elements
+ * @see {@link filterMap} for discarding failures
  * @see {@link separate} — split an iterable of `Result` values
  *
  * @category filtering
@@ -6171,6 +7141,11 @@ export declare const partition: {
     /**
      * Splits an iterable using a `Filter` into failures and successes.
      *
+     * **When to use**
+     *
+     * Use to evaluate each element with a `Result`-returning filter and keep both
+     * failure and success values.
+     *
      * **Details**
      *
      * - Returns `[excluded, satisfying]`.
@@ -6188,6 +7163,7 @@ export declare const partition: {
      * ```
      *
      * @see {@link filter} — keep only matching elements
+     * @see {@link filterMap} for discarding failures
      * @see {@link separate} — split an iterable of `Result` values
      *
      * @category filtering
@@ -6197,6 +7173,11 @@ export declare const partition: {
     /**
      * Splits an iterable using a `Filter` into failures and successes.
      *
+     * **When to use**
+     *
+     * Use to evaluate each element with a `Result`-returning filter and keep both
+     * failure and success values.
+     *
      * **Details**
      *
      * - Returns `[excluded, satisfying]`.
@@ -6214,6 +7195,7 @@ export declare const partition: {
      * ```
      *
      * @see {@link filter} — keep only matching elements
+     * @see {@link filterMap} for discarding failures
      * @see {@link separate} — split an iterable of `Result` values
      *
      * @category filtering
@@ -6224,6 +7206,10 @@ export declare const partition: {
 /**
  * Separates an iterable of `Result`s into failure values and success values.
  *
+ * **When to use**
+ *
+ * Use to split existing `Result` values into failure and success arrays.
+ *
  * **Details**
  *
  * - Returns `[failures, successes]`.
@@ -6243,6 +7229,7 @@ export declare const partition: {
  *
  * @see {@link getFailures} — extract only failures
  * @see {@link getSuccesses} — extract only successes
+ * @see {@link partition} for computing `Result` values while splitting
  *
  * @category filtering
  * @since 2.0.0
@@ -6254,6 +7241,10 @@ export declare const separate: <T extends Iterable<Result.Result<any, any>>>(sel
 /**
  * Folds an iterable from left to right into a single value.
  *
+ * **When to use**
+ *
+ * Use to combine all elements into one accumulated value from left to right.
+ *
  * **Details**
  *
  * - The function receives `(accumulator, element, index)`.
@@ -6276,6 +7267,10 @@ export declare const reduce: {
     /**
      * Folds an iterable from left to right into a single value.
      *
+     * **When to use**
+     *
+     * Use to combine all elements into one accumulated value from left to right.
+     *
      * **Details**
      *
      * - The function receives `(accumulator, element, index)`.
@@ -6298,6 +7293,10 @@ export declare const reduce: {
     /**
      * Folds an iterable from left to right into a single value.
      *
+     * **When to use**
+     *
+     * Use to combine all elements into one accumulated value from left to right.
+     *
      * **Details**
      *
      * - The function receives `(accumulator, element, index)`.
@@ -6321,6 +7320,11 @@ export declare const reduce: {
 /**
  * Folds an iterable from right to left into a single value.
  *
+ * **When to use**
+ *
+ * Use when folding order matters and values must be combined from right to
+ * left.
+ *
  * **Details**
  *
  * - The function receives `(accumulator, element, index)`.
@@ -6343,6 +7347,11 @@ export declare const reduceRight: {
     /**
      * Folds an iterable from right to left into a single value.
      *
+     * **When to use**
+     *
+     * Use when folding order matters and values must be combined from right to
+     * left.
+     *
      * **Details**
      *
      * - The function receives `(accumulator, element, index)`.
@@ -6365,6 +7374,11 @@ export declare const reduceRight: {
     /**
      * Folds an iterable from right to left into a single value.
      *
+     * **When to use**
+     *
+     * Use when folding order matters and values must be combined from right to
+     * left.
+     *
      * **Details**
      *
      * - The function receives `(accumulator, element, index)`.
@@ -6457,6 +7471,10 @@ export declare const liftOption: <A extends Array<unknown>, B>(f: (...a: A) => O
  * Converts a nullable value to an array: `null`/`undefined` becomes `[]`,
  * anything else becomes `[value]`.
  *
+ * **When to use**
+ *
+ * Use to treat a nullable single value as zero or one array element.
+ *
  * **Example** (Nullable to array)
  *
  * ```ts
@@ -6502,6 +7520,11 @@ export declare const liftNullishOr: <A extends Array<unknown>, B>(f: (...a: A) =
  * Maps each element with a nullable-returning function, keeping only non-null /
  * non-undefined results.
  *
+ * **When to use**
+ *
+ * Use when mapping and filtering in one step, where the mapper can return
+ * `null` or `undefined` to skip elements.
+ *
  * **Example** (FlatMapping with nullable)
  *
  * ```ts
@@ -6511,6 +7534,9 @@ export declare const liftNullishOr: <A extends Array<unknown>, B>(f: (...a: A) =
  * // [1, 3]
  * ```
  *
+ * @see {@link flatMap} for mapping each element to an array and flattening
+ * @see {@link fromNullishOr} for converting a single nullable value to an array
+ *
  * @category sequencing
  * @since 4.0.0
  */
@@ -6519,6 +7545,11 @@ export declare const flatMapNullishOr: {
      * Maps each element with a nullable-returning function, keeping only non-null /
      * non-undefined results.
      *
+     * **When to use**
+     *
+     * Use when mapping and filtering in one step, where the mapper can return
+     * `null` or `undefined` to skip elements.
+     *
      * **Example** (FlatMapping with nullable)
      *
      * ```ts
@@ -6528,6 +7559,9 @@ export declare const flatMapNullishOr: {
      * // [1, 3]
      * ```
      *
+     * @see {@link flatMap} for mapping each element to an array and flattening
+     * @see {@link fromNullishOr} for converting a single nullable value to an array
+     *
      * @category sequencing
      * @since 4.0.0
      */
@@ -6536,6 +7570,11 @@ export declare const flatMapNullishOr: {
      * Maps each element with a nullable-returning function, keeping only non-null /
      * non-undefined results.
      *
+     * **When to use**
+     *
+     * Use when mapping and filtering in one step, where the mapper can return
+     * `null` or `undefined` to skip elements.
+     *
      * **Example** (FlatMapping with nullable)
      *
      * ```ts
@@ -6545,6 +7584,9 @@ export declare const flatMapNullishOr: {
      * // [1, 3]
      * ```
      *
+     * @see {@link flatMap} for mapping each element to an array and flattening
+     * @see {@link fromNullishOr} for converting a single nullable value to an array
+     *
      * @category sequencing
      * @since 4.0.0
      */
@@ -6577,9 +7619,14 @@ export declare const flatMapNullishOr: {
  */
 export declare const liftResult: <A extends Array<unknown>, E, B>(f: (...a: A) => Result.Result<B, E>) => (...a: A) => Array<B>;
 /**
- * Tests whether all elements satisfy the predicate. Supports refinements for
+ * Checks whether all elements satisfy the predicate. Supports refinements for
  * type narrowing.
  *
+ * **When to use**
+ *
+ * Use to check that all elements satisfy a predicate, including
+ * refinement-based type narrowing.
+ *
  * **Example** (Testing all elements)
  *
  * ```ts
@@ -6596,9 +7643,14 @@ export declare const liftResult: <A extends Array<unknown>, E, B>(f: (...a: A) =
  */
 export declare const every: {
     /**
-     * Tests whether all elements satisfy the predicate. Supports refinements for
+     * Checks whether all elements satisfy the predicate. Supports refinements for
      * type narrowing.
      *
+     * **When to use**
+     *
+     * Use to check that all elements satisfy a predicate, including
+     * refinement-based type narrowing.
+     *
      * **Example** (Testing all elements)
      *
      * ```ts
@@ -6615,9 +7667,14 @@ export declare const every: {
      */
     <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: ReadonlyArray<A>) => self is ReadonlyArray<B>;
     /**
-     * Tests whether all elements satisfy the predicate. Supports refinements for
+     * Checks whether all elements satisfy the predicate. Supports refinements for
      * type narrowing.
      *
+     * **When to use**
+     *
+     * Use to check that all elements satisfy a predicate, including
+     * refinement-based type narrowing.
+     *
      * **Example** (Testing all elements)
      *
      * ```ts
@@ -6634,9 +7691,14 @@ export declare const every: {
      */
     <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: ReadonlyArray<A>) => boolean;
     /**
-     * Tests whether all elements satisfy the predicate. Supports refinements for
+     * Checks whether all elements satisfy the predicate. Supports refinements for
      * type narrowing.
      *
+     * **When to use**
+     *
+     * Use to check that all elements satisfy a predicate, including
+     * refinement-based type narrowing.
+     *
      * **Example** (Testing all elements)
      *
      * ```ts
@@ -6653,9 +7715,14 @@ export declare const every: {
      */
     <A, B extends A>(self: ReadonlyArray<A>, refinement: (a: A, i: number) => a is B): self is ReadonlyArray<B>;
     /**
-     * Tests whether all elements satisfy the predicate. Supports refinements for
+     * Checks whether all elements satisfy the predicate. Supports refinements for
      * type narrowing.
      *
+     * **When to use**
+     *
+     * Use to check that all elements satisfy a predicate, including
+     * refinement-based type narrowing.
+     *
      * **Example** (Testing all elements)
      *
      * ```ts
@@ -6673,7 +7740,7 @@ export declare const every: {
     <A>(self: ReadonlyArray<A>, predicate: (a: A, i: number) => boolean): boolean;
 };
 /**
- * Tests whether at least one element satisfies the predicate. Narrows the type
+ * Checks whether at least one element satisfies the predicate. Narrows the type
  * to `NonEmptyReadonlyArray` on success.
  *
  * **Example** (Testing for any match)
@@ -6693,7 +7760,7 @@ export declare const every: {
  */
 export declare const some: {
     /**
-     * Tests whether at least one element satisfies the predicate. Narrows the type
+     * Checks whether at least one element satisfies the predicate. Narrows the type
      * to `NonEmptyReadonlyArray` on success.
      *
      * **Example** (Testing for any match)
@@ -6713,7 +7780,7 @@ export declare const some: {
      */
     <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: ReadonlyArray<A>) => self is NonEmptyReadonlyArray<A>;
     /**
-     * Tests whether at least one element satisfies the predicate. Narrows the type
+     * Checks whether at least one element satisfies the predicate. Narrows the type
      * to `NonEmptyReadonlyArray` on success.
      *
      * **Example** (Testing for any match)
@@ -6737,6 +7804,11 @@ export declare const some: {
  * Applies a function to each suffix of the array (starting from each index),
  * collecting the results.
  *
+ * **When to use**
+ *
+ * Use when a computation depends on every suffix of an array, such as
+ * cumulative aggregations from each position.
+ *
  * **Details**
  *
  * - For index `i`, the function receives `self.slice(i)`.
@@ -6749,6 +7821,8 @@ export declare const some: {
  * console.log(Array.extend([1, 2, 3], (as) => as.length)) // [3, 2, 1]
  * ```
  *
+ * @see {@link scan} for keeping intermediate accumulator values during a fold
+ *
  * @category mapping
  * @since 2.0.0
  */
@@ -6757,6 +7831,11 @@ export declare const extend: {
      * Applies a function to each suffix of the array (starting from each index),
      * collecting the results.
      *
+     * **When to use**
+     *
+     * Use when a computation depends on every suffix of an array, such as
+     * cumulative aggregations from each position.
+     *
      * **Details**
      *
      * - For index `i`, the function receives `self.slice(i)`.
@@ -6769,6 +7848,8 @@ export declare const extend: {
      * console.log(Array.extend([1, 2, 3], (as) => as.length)) // [3, 2, 1]
      * ```
      *
+     * @see {@link scan} for keeping intermediate accumulator values during a fold
+     *
      * @category mapping
      * @since 2.0.0
      */
@@ -6777,6 +7858,11 @@ export declare const extend: {
      * Applies a function to each suffix of the array (starting from each index),
      * collecting the results.
      *
+     * **When to use**
+     *
+     * Use when a computation depends on every suffix of an array, such as
+     * cumulative aggregations from each position.
+     *
      * **Details**
      *
      * - For index `i`, the function receives `self.slice(i)`.
@@ -6789,6 +7875,8 @@ export declare const extend: {
      * console.log(Array.extend([1, 2, 3], (as) => as.length)) // [3, 2, 1]
      * ```
      *
+     * @see {@link scan} for keeping intermediate accumulator values during a fold
+     *
      * @category mapping
      * @since 2.0.0
      */
@@ -6974,6 +8062,11 @@ export declare const makeEquivalence: <A>(isEquivalent: Equivalence.Equivalence<
 /**
  * Runs a side-effect for each element. The callback receives `(element, index)`.
  *
+ * **When to use**
+ *
+ * Use to iterate over an array for side-effects only, when no transformed
+ * result is needed.
+ *
  * **Example** (Iterating with side-effects)
  *
  * ```ts
@@ -6982,6 +8075,8 @@ export declare const makeEquivalence: <A>(isEquivalent: Equivalence.Equivalence<
  * Array.forEach([1, 2, 3], (n) => console.log(n)) // 1, 2, 3
  * ```
  *
+ * @see {@link map} for transforming each element into a new array
+ *
  * @category elements
  * @since 2.0.0
  */
@@ -6989,6 +8084,11 @@ export declare const forEach: {
     /**
      * Runs a side-effect for each element. The callback receives `(element, index)`.
      *
+     * **When to use**
+     *
+     * Use to iterate over an array for side-effects only, when no transformed
+     * result is needed.
+     *
      * **Example** (Iterating with side-effects)
      *
      * ```ts
@@ -6997,6 +8097,8 @@ export declare const forEach: {
      * Array.forEach([1, 2, 3], (n) => console.log(n)) // 1, 2, 3
      * ```
      *
+     * @see {@link map} for transforming each element into a new array
+     *
      * @category elements
      * @since 2.0.0
      */
@@ -7004,6 +8106,11 @@ export declare const forEach: {
     /**
      * Runs a side-effect for each element. The callback receives `(element, index)`.
      *
+     * **When to use**
+     *
+     * Use to iterate over an array for side-effects only, when no transformed
+     * result is needed.
+     *
      * **Example** (Iterating with side-effects)
      *
      * ```ts
@@ -7012,6 +8119,8 @@ export declare const forEach: {
      * Array.forEach([1, 2, 3], (n) => console.log(n)) // 1, 2, 3
      * ```
      *
+     * @see {@link map} for transforming each element into a new array
+     *
      * @category elements
      * @since 2.0.0
      */
@@ -7021,6 +8130,11 @@ export declare const forEach: {
  * Removes duplicates using a custom equivalence, preserving the order of the
  * first occurrence.
  *
+ * **When to use**
+ *
+ * Use to remove all duplicate elements with a custom equivalence when default
+ * equality is not appropriate.
+ *
  * **Example** (Deduplicating with custom equality)
  *
  * ```ts
@@ -7040,6 +8154,11 @@ export declare const dedupeWith: {
      * Removes duplicates using a custom equivalence, preserving the order of the
      * first occurrence.
      *
+     * **When to use**
+     *
+     * Use to remove all duplicate elements with a custom equivalence when default
+     * equality is not appropriate.
+     *
      * **Example** (Deduplicating with custom equality)
      *
      * ```ts
@@ -7059,6 +8178,11 @@ export declare const dedupeWith: {
      * Removes duplicates using a custom equivalence, preserving the order of the
      * first occurrence.
      *
+     * **When to use**
+     *
+     * Use to remove all duplicate elements with a custom equivalence when default
+     * equality is not appropriate.
+     *
      * **Example** (Deduplicating with custom equality)
      *
      * ```ts
@@ -7078,6 +8202,11 @@ export declare const dedupeWith: {
      * Removes duplicates using a custom equivalence, preserving the order of the
      * first occurrence.
      *
+     * **When to use**
+     *
+     * Use to remove all duplicate elements with a custom equivalence when default
+     * equality is not appropriate.
+     *
      * **Example** (Deduplicating with custom equality)
      *
      * ```ts
@@ -7098,6 +8227,11 @@ export declare const dedupeWith: {
  * Removes duplicates using `Equal.equivalence()`, preserving the order of the
  * first occurrence.
  *
+ * **When to use**
+ *
+ * Use to remove repeated values from an iterable when Effect's default equality
+ * is the right comparison, preserving the first occurrence.
+ *
  * **Example** (Removing duplicates)
  *
  * ```ts
@@ -7116,6 +8250,12 @@ export declare const dedupe: <S extends Iterable<any>>(self: S) => S extends Non
 /**
  * Removes consecutive duplicate elements using a custom equivalence.
  *
+ * **When to use**
+ *
+ * Use when consecutive duplicates should be collapsed using a custom
+ * equivalence, while equivalent values that appear later should remain in the
+ * result.
+ *
  * **Details**
  *
  * - Non-adjacent duplicates are preserved.
@@ -7139,6 +8279,12 @@ export declare const dedupeAdjacentWith: {
     /**
      * Removes consecutive duplicate elements using a custom equivalence.
      *
+     * **When to use**
+     *
+     * Use when consecutive duplicates should be collapsed using a custom
+     * equivalence, while equivalent values that appear later should remain in the
+     * result.
+     *
      * **Details**
      *
      * - Non-adjacent duplicates are preserved.
@@ -7162,6 +8308,12 @@ export declare const dedupeAdjacentWith: {
     /**
      * Removes consecutive duplicate elements using a custom equivalence.
      *
+     * **When to use**
+     *
+     * Use when consecutive duplicates should be collapsed using a custom
+     * equivalence, while equivalent values that appear later should remain in the
+     * result.
+     *
      * **Details**
      *
      * - Non-adjacent duplicates are preserved.
@@ -7186,6 +8338,11 @@ export declare const dedupeAdjacentWith: {
 /**
  * Removes consecutive duplicate elements using `Equal.equivalence()`.
  *
+ * **When to use**
+ *
+ * Use when you need to collapse consecutive duplicates while preserving later
+ * non-consecutive repeats, and the default equality is sufficient.
+ *
  * **Example** (Removing adjacent duplicates)
  *
  * ```ts
@@ -7256,6 +8413,11 @@ export declare const join: {
 /**
  * Maps over an array while threading an accumulator through each step, returning both the final state and the mapped array.
  *
+ * **When to use**
+ *
+ * Use when mapping needs state threaded through each element and the final state
+ * is also needed.
+ *
  * **Details**
  *
  * - Combines `map` and `reduce` in a single pass.
@@ -7282,6 +8444,11 @@ export declare const mapAccum: {
     /**
      * Maps over an array while threading an accumulator through each step, returning both the final state and the mapped array.
      *
+     * **When to use**
+     *
+     * Use when mapping needs state threaded through each element and the final state
+     * is also needed.
+     *
      * **Details**
      *
      * - Combines `map` and `reduce` in a single pass.
@@ -7308,6 +8475,11 @@ export declare const mapAccum: {
     /**
      * Maps over an array while threading an accumulator through each step, returning both the final state and the mapped array.
      *
+     * **When to use**
+     *
+     * Use when mapping needs state threaded through each element and the final state
+     * is also needed.
+     *
      * **Details**
      *
      * - Combines `map` and `reduce` in a single pass.
@@ -7335,6 +8507,11 @@ export declare const mapAccum: {
 /**
  * Computes the cartesian product of two arrays, applying a combiner to each pair.
  *
+ * **When to use**
+ *
+ * Use to compute every combination from two arrays and immediately transform
+ * each pair into a custom result.
+ *
  * **Details**
  *
  * - Produces every combination of an element from `self` with an element from `that`.
@@ -7350,7 +8527,7 @@ export declare const mapAccum: {
  * console.log(result) // ["1-a", "1-b", "2-a", "2-b"]
  * ```
  *
- * @see {@link cartesian} — returns tuples instead of applying a combiner
+ * @see {@link cartesian} for returning tuples instead of applying a combiner
  *
  * @category elements
  * @since 2.0.0
@@ -7359,6 +8536,11 @@ export declare const cartesianWith: {
     /**
      * Computes the cartesian product of two arrays, applying a combiner to each pair.
      *
+     * **When to use**
+     *
+     * Use to compute every combination from two arrays and immediately transform
+     * each pair into a custom result.
+     *
      * **Details**
      *
      * - Produces every combination of an element from `self` with an element from `that`.
@@ -7374,7 +8556,7 @@ export declare const cartesianWith: {
      * console.log(result) // ["1-a", "1-b", "2-a", "2-b"]
      * ```
      *
-     * @see {@link cartesian} — returns tuples instead of applying a combiner
+     * @see {@link cartesian} for returning tuples instead of applying a combiner
      *
      * @category elements
      * @since 2.0.0
@@ -7383,6 +8565,11 @@ export declare const cartesianWith: {
     /**
      * Computes the cartesian product of two arrays, applying a combiner to each pair.
      *
+     * **When to use**
+     *
+     * Use to compute every combination from two arrays and immediately transform
+     * each pair into a custom result.
+     *
      * **Details**
      *
      * - Produces every combination of an element from `self` with an element from `that`.
@@ -7398,7 +8585,7 @@ export declare const cartesianWith: {
      * console.log(result) // ["1-a", "1-b", "2-a", "2-b"]
      * ```
      *
-     * @see {@link cartesian} — returns tuples instead of applying a combiner
+     * @see {@link cartesian} for returning tuples instead of applying a combiner
      *
      * @category elements
      * @since 2.0.0
@@ -7408,6 +8595,10 @@ export declare const cartesianWith: {
 /**
  * Computes the cartesian product of two arrays, returning all pairs as tuples.
  *
+ * **When to use**
+ *
+ * Use when you need every `[a, b]` pair from two arrays as tuples.
+ *
  * **Details**
  *
  * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
@@ -7431,6 +8622,10 @@ export declare const cartesian: {
     /**
      * Computes the cartesian product of two arrays, returning all pairs as tuples.
      *
+     * **When to use**
+     *
+     * Use when you need every `[a, b]` pair from two arrays as tuples.
+     *
      * **Details**
      *
      * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
@@ -7454,6 +8649,10 @@ export declare const cartesian: {
     /**
      * Computes the cartesian product of two arrays, returning all pairs as tuples.
      *
+     * **When to use**
+     *
+     * Use when you need every `[a, b]` pair from two arrays as tuples.
+     *
      * **Details**
      *
      * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
@@ -7476,11 +8675,11 @@ export declare const cartesian: {
     <A, B>(self: ReadonlyArray<A>, that: ReadonlyArray<B>): Array<[A, B]>;
 };
 /**
- * Starting point for the "do simulation" — an array comprehension pattern.
+ * Provides the starting point for the "do simulation" — an array comprehension pattern.
  *
  * **When to use**
  *
- * - Begin a pipeline with `Do`, then use {@link bind} to introduce array variables and {@link let_ let} for plain values.
+ * Use when begin a pipeline with `Do`, then use {@link bind} to introduce array variables and {@link let_ let} for plain values.
  * - Each `bind` produces the cartesian product of all bound variables (like nested loops).
  * - Use `filter` and `map` in the pipeline to add conditions and transformations.
  *
@@ -7508,7 +8707,12 @@ export declare const cartesian: {
  */
 export declare const Do: ReadonlyArray<{}>;
 /**
- * Introduces a new array variable into a do-notation scope, producing the cartesian product with all previous bindings.
+ * Adds a new array variable to a do-notation scope, producing the cartesian product with all previous bindings.
+ *
+ * **When to use**
+ *
+ * Use to add another array-producing binding to an `Array.Do` pipeline, pairing
+ * each existing scope with every value returned by the callback.
  *
  * **Details**
  *
@@ -7539,7 +8743,12 @@ export declare const Do: ReadonlyArray<{}>;
  */
 export declare const bind: {
     /**
-     * Introduces a new array variable into a do-notation scope, producing the cartesian product with all previous bindings.
+     * Adds a new array variable to a do-notation scope, producing the cartesian product with all previous bindings.
+     *
+     * **When to use**
+     *
+     * Use to add another array-producing binding to an `Array.Do` pipeline, pairing
+     * each existing scope with every value returned by the callback.
      *
      * **Details**
      *
@@ -7572,7 +8781,12 @@ export declare const bind: {
         [K in N | keyof A]: K extends keyof A ? A[K] : B;
     }>;
     /**
-     * Introduces a new array variable into a do-notation scope, producing the cartesian product with all previous bindings.
+     * Adds a new array variable to a do-notation scope, producing the cartesian product with all previous bindings.
+     *
+     * **When to use**
+     *
+     * Use to add another array-producing binding to an `Array.Do` pipeline, pairing
+     * each existing scope with every value returned by the callback.
      *
      * **Details**
      *
@@ -7606,7 +8820,12 @@ export declare const bind: {
     }>;
 };
 /**
- * Names the elements of an array by wrapping each in an object with the given key, starting a do-notation scope.
+ * Wraps each array element in an object with the given key, starting a do-notation scope.
+ *
+ * **When to use**
+ *
+ * Use when you already have an array and want to start a do-notation pipeline
+ * by naming each element.
  *
  * **Details**
  *
@@ -7633,7 +8852,12 @@ export declare const bind: {
  */
 export declare const bindTo: {
     /**
-     * Names the elements of an array by wrapping each in an object with the given key, starting a do-notation scope.
+     * Wraps each array element in an object with the given key, starting a do-notation scope.
+     *
+     * **When to use**
+     *
+     * Use when you already have an array and want to start a do-notation pipeline
+     * by naming each element.
      *
      * **Details**
      *
@@ -7662,7 +8886,12 @@ export declare const bindTo: {
         [K in N]: A;
     }>;
     /**
-     * Names the elements of an array by wrapping each in an object with the given key, starting a do-notation scope.
+     * Wraps each array element in an object with the given key, starting a do-notation scope.
+     *
+     * **When to use**
+     *
+     * Use when you already have an array and want to start a do-notation pipeline
+     * by naming each element.
      *
      * **Details**
      *
@@ -7748,7 +8977,12 @@ export declare function getReadonlyReducerConcat<A>(): Reducer.Reducer<ReadonlyA
  */
 export declare function makeReducerConcat<A>(): Reducer.Reducer<Array<A>>;
 /**
- * Counts the elements in an iterable that satisfy a predicate.
+ * Computes the number of elements in an iterable that satisfy a predicate.
+ *
+ * **When to use**
+ *
+ * Use to count how many elements satisfy a predicate when you only need the
+ * number of matches instead of the matching elements.
  *
  * **Details**
  *
@@ -7771,7 +9005,12 @@ export declare function makeReducerConcat<A>(): Reducer.Reducer<Array<A>>;
  */
 export declare const countBy: {
     /**
-     * Counts the elements in an iterable that satisfy a predicate.
+     * Computes the number of elements in an iterable that satisfy a predicate.
+     *
+     * **When to use**
+     *
+     * Use to count how many elements satisfy a predicate when you only need the
+     * number of matches instead of the matching elements.
      *
      * **Details**
      *
@@ -7794,7 +9033,12 @@ export declare const countBy: {
      */
     <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => number;
     /**
-     * Counts the elements in an iterable that satisfy a predicate.
+     * Computes the number of elements in an iterable that satisfy a predicate.
+     *
+     * **When to use**
+     *
+     * Use to count how many elements satisfy a predicate when you only need the
+     * number of matches instead of the matching elements.
      *
      * **Details**
      *