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

package/dist/Array.d.ts

@@ -13,7 +13,7 @@ import type { NoInfer, TupleOf } from "./Types.ts";
  *
  * **When to use**
  *
- * Use this when you need the native `Array` constructor while the `Array`
+ * Use when you need the native `Array` constructor while the `Array`
  * namespace is in scope (e.g. `Array.Array.isArray`, `Array.Array.from`).
  *
  * **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,6 +735,10 @@ 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.
@@ -709,6 +763,10 @@ 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.
@@ -733,6 +791,10 @@ 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.
@@ -758,6 +820,10 @@ 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`.
@@ -782,6 +848,10 @@ 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`.
@@ -806,6 +876,10 @@ 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`.
@@ -830,6 +904,10 @@ 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`.
@@ -854,6 +932,10 @@ 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`.
@@ -879,6 +961,11 @@ 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.
@@ -903,6 +990,11 @@ 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.
@@ -927,6 +1019,11 @@ 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.
@@ -952,6 +1049,11 @@ 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`.
@@ -976,6 +1078,11 @@ 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`.
@@ -1000,6 +1107,11 @@ 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`.
@@ -1024,6 +1136,11 @@ 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`.
@@ -1048,6 +1165,11 @@ 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`.
@@ -1073,6 +1195,10 @@ export declare const appendAll: {
 /**
  * Left-to-right fold that keeps every intermediate accumulator value.
  *
+ * **When to use**
+ *
+ * Use to compute a running accumulator where each intermediate value is needed.
+ *
  * **Details**
  *
  * - The output length is `input.length + 1` (starts with the initial value).
@@ -1098,6 +1224,10 @@ export declare const scan: {
     /**
      * Left-to-right fold that keeps every intermediate accumulator value.
      *
+     * **When to use**
+     *
+     * Use to compute a running accumulator where each intermediate value is needed.
+     *
      * **Details**
      *
      * - The output length is `input.length + 1` (starts with the initial value).
@@ -1123,6 +1253,10 @@ export declare const scan: {
     /**
      * Left-to-right fold that keeps every intermediate accumulator value.
      *
+     * **When to use**
+     *
+     * Use to compute a running accumulator where each intermediate value is needed.
+     *
      * **Details**
      *
      * - The output length is `input.length + 1` (starts with the initial value).
@@ -1149,6 +1283,11 @@ export declare const scan: {
 /**
  * Right-to-left fold that keeps every intermediate accumulator value.
  *
+ * **When to use**
+ *
+ * Use to compute a running accumulator from right to left where each intermediate
+ * value is needed.
+ *
  * **Details**
  *
  * - The output length is `input.length + 1` (ends with the initial value).
@@ -1173,6 +1312,11 @@ export declare const scanRight: {
     /**
      * Right-to-left fold that keeps every intermediate accumulator value.
      *
+     * **When to use**
+     *
+     * Use to compute a running accumulator from right to left where each intermediate
+     * value is needed.
+     *
      * **Details**
      *
      * - The output length is `input.length + 1` (ends with the initial value).
@@ -1197,6 +1341,11 @@ export declare const scanRight: {
     /**
      * Right-to-left fold that keeps every intermediate accumulator value.
      *
+     * **When to use**
+     *
+     * Use to compute a running accumulator from right to left where each intermediate
+     * value is needed.
+     *
      * **Details**
      *
      * - The output length is `input.length + 1` (ends with the initial value).
@@ -1222,6 +1371,10 @@ export declare const scanRight: {
 /**
  * Tests 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**
  *
  * - Acts as a type guard narrowing the input to `Array<unknown>`.
@@ -1246,6 +1399,10 @@ export declare const isArray: {
     /**
      * Tests 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**
      *
      * - Acts as a type guard narrowing the input to `Array<unknown>`.
@@ -1270,6 +1427,10 @@ export declare const isArray: {
     /**
      * Tests 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**
      *
      * - Acts as a type guard narrowing the input to `Array<unknown>`.
@@ -1373,6 +1534,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
@@ -1389,6 +1554,11 @@ export declare const length: <A>(self: ReadonlyArray<A>) => number;
  * Safely reads an element at the given index, 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,9 +1573,9 @@ 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
@@ -1415,6 +1585,11 @@ export declare const get: {
      * Safely reads an element at the given index, 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,9 +1604,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
@@ -1441,6 +1616,11 @@ export declare const get: {
      * Safely reads an element at the given index, 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 +1635,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 +1647,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 +1675,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 +1703,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 +1732,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 +1751,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 +1763,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,9 +1782,9 @@ 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
@@ -1589,6 +1794,10 @@ export declare const unappend: <A>(self: NonEmptyReadonlyArray<A>) => [arrayWith
  * Returns the first element of an array 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 +1818,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
@@ -1627,6 +1841,10 @@ export declare const headNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => A;
  * Returns the last element of an array 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 +1865,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
@@ -1664,6 +1887,10 @@ export declare const lastNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => A;
 /**
  * Returns all elements except the first, wrapped in an `Option`.
  *
+ * **When to use**
+ *
+ * Use to safely get all elements after the first when the iterable may be empty.
+ *
  * **Details**
  *
  * - Allocates a new array via `slice(1)`.
@@ -1688,6 +1915,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
@@ -1706,6 +1937,10 @@ export declare const tailNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => Array<
 /**
  * Returns all elements except the last, wrapped in an `Option`.
  *
+ * **When to use**
+ *
+ * Use to safely get all elements before the last when the iterable may be empty.
+ *
  * **Details**
  *
  * - Allocates a new array via `slice(0, -1)`.
@@ -1730,6 +1965,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 +1987,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 +2004,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 +2015,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 +2032,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 +2043,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 +2060,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 +2072,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 +2099,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 +2126,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 +2155,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 +2173,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 +2185,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 +2203,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 +2215,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 +2233,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 +2245,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 +2263,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 +2275,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 +2293,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 +2305,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 +2325,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 +2345,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 +2367,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 +2386,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 +2398,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 +2417,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 +2429,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 +2448,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 +2460,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 +2479,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 +2491,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 +2510,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 +2522,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 +2540,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 +2551,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 +2569,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 +2580,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 +2598,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 +2610,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 +2636,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 +2662,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 +2689,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 +2715,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 +2741,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 +2768,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 +2788,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 +2808,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 +2830,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 +2854,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 +2878,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 +2903,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 +2926,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 +2949,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 +2973,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 +3004,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 +3035,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 +3066,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 +3097,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 +3128,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 +3159,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 +3191,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 +3220,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 +3249,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 +3278,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 +3307,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 +3336,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 +3365,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 +3395,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 +3423,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 +3451,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 +3479,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 +3507,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 +3535,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 +3563,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.
@@ -3074,6 +3592,10 @@ export declare const findLast: {
  * Inserts an element at the specified index, 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).
@@ -3098,6 +3620,10 @@ export declare const insertAt: {
      * Inserts an element at the specified index, 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).
@@ -3122,6 +3648,10 @@ export declare const insertAt: {
      * Inserts an element at the specified index, 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).
@@ -3147,6 +3677,10 @@ export declare const insertAt: {
  * Replaces the element at the specified index 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.
@@ -3171,6 +3705,10 @@ export declare const replace: {
      * Replaces the element at the specified index 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.
@@ -3195,6 +3733,10 @@ export declare const replace: {
      * Replaces the element at the specified index 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.
@@ -3220,6 +3762,11 @@ export declare const replace: {
  * Applies a function to the element at the specified index, 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.
@@ -3246,6 +3793,11 @@ export declare const modify: {
      * Applies a function to the element at the specified index, 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.
@@ -3272,6 +3824,11 @@ export declare const modify: {
      * Applies a function to the element at the specified index, 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.
@@ -3299,9 +3856,13 @@ 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.
  *
+ * **When to use**
+ *
+ * Use to remove a single element at a known index.
+ *
  * **Details**
  *
- * - Does not mutate the input.
+ * Does not mutate the input.
  *
  * **Example** (Removing an element)
  *
@@ -3323,9 +3884,13 @@ 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.
      *
+     * **When to use**
+     *
+     * Use to remove a single element at a known index.
+     *
      * **Details**
      *
-     * - Does not mutate the input.
+     * Does not mutate the input.
      *
      * **Example** (Removing an element)
      *
@@ -3347,9 +3912,13 @@ 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.
      *
+     * **When to use**
+     *
+     * Use to remove a single element at a known index.
+     *
      * **Details**
      *
-     * - Does not mutate the input.
+     * Does not mutate the input.
      *
      * **Example** (Removing an element)
      *
@@ -3371,6 +3940,10 @@ 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.
@@ -3391,6 +3964,10 @@ 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.
@@ -3416,6 +3993,10 @@ 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.
@@ -3441,6 +4022,10 @@ 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.
@@ -3466,6 +4051,10 @@ 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.
@@ -3493,6 +4082,11 @@ 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.
@@ -3507,8 +4101,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,6 +4112,11 @@ 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.
@@ -3532,8 +4131,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,6 +4142,11 @@ 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.
@@ -3557,8 +4161,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,6 +4172,11 @@ 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.
@@ -3582,8 +4191,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 +4203,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 +4246,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 +4273,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 +4300,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 +4327,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 +4354,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 +4489,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 +4515,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 +4541,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 +4567,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 +4595,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 +4618,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 +4641,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
@@ -4171,6 +4833,11 @@ export declare const setLastNonEmpty: {
  * Rotates an array by `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,6 +4852,9 @@ 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
  */
@@ -4193,6 +4863,11 @@ export declare const rotate: {
      * Rotates an array by `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,6 +4882,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
      */
@@ -4215,6 +4893,11 @@ export declare const rotate: {
      * Rotates an array by `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,6 +4912,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
      */
@@ -4237,6 +4923,11 @@ export declare const rotate: {
      * Rotates an array by `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 +4942,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 +4953,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 +4967,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
@@ -4281,6 +4980,11 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
  * Tests 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
@@ -4299,6 +5003,11 @@ export declare const contains: {
      * Tests 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
@@ -4317,6 +5026,11 @@ export declare const contains: {
      * Tests 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
@@ -4336,6 +5050,11 @@ export declare const contains: {
  * Repeatedly applies a function that consumes a prefix of the array and
  * produces a value plus the remaining elements, collecting the values.
  *
+ * **When to use**
+ *
+ * Use when the grouping logic is custom and each step needs to return both a
+ * value and the remaining input.
+ *
  * **Details**
  *
  * - The function receives a `NonEmptyReadonlyArray` and returns
@@ -4366,6 +5085,11 @@ 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.
      *
+     * **When to use**
+     *
+     * Use when the grouping logic is custom and each step needs to return both a
+     * value and the remaining input.
+     *
      * **Details**
      *
      * - The function receives a `NonEmptyReadonlyArray` and returns
@@ -4396,6 +5120,11 @@ 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.
      *
+     * **When to use**
+     *
+     * Use when the grouping logic is custom and each step needs to return both a
+     * value and the remaining input.
+     *
      * **Details**
      *
      * - The function receives a `NonEmptyReadonlyArray` and returns
@@ -4426,6 +5155,11 @@ 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.
      *
+     * **When to use**
+     *
+     * Use when the grouping logic is custom and each step needs to return both a
+     * value and the remaining input.
+     *
      * **Details**
      *
      * - The function receives a `NonEmptyReadonlyArray` and returns
@@ -4456,6 +5190,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 +5217,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 +5244,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 +5330,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 +5356,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 +5382,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 +5410,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 +5433,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 +5456,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 +5479,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 +5509,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 +5539,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 +5571,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 +5598,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 +5625,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 +5653,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 +5683,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 +5713,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 +5743,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 +5773,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 +5800,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 +5827,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 +5855,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 +5874,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 +5884,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 +5903,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 +5913,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 +5932,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 +5943,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 +5971,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 +6008,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 +6045,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 +6083,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 +6096,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 +6108,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 +6121,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 +6133,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 +6146,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 +6158,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 +6171,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 +6183,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 +6196,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 +6310,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 +6326,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 +6402,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 +6416,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 +6431,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 +6456,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 +6481,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 +6506,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 +6644,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 +6670,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 +6696,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 +6723,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 +6751,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 +6779,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 +6807,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 +6836,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 +6858,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 +6882,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 +6907,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 +6931,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 +6951,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 +6960,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 +6980,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 +6989,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 +7009,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 +7019,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 +7037,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 +7046,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 +7064,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 +7073,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 +7091,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 +7100,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 +7118,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 +7127,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 +7145,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 +7155,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 +7177,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 +7187,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 +7209,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 +7219,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 +7241,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 +7252,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 +7275,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 +7287,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 +7313,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 +7339,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 +7366,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 +7393,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 +7420,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 +7517,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 +7566,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 +7580,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 +7591,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 +7605,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 +7616,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 +7630,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
      */
@@ -6580,6 +7668,11 @@ export declare const liftResult: <A extends Array<unknown>, E, B>(f: (...a: A) =
  * Tests 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
@@ -6599,6 +7692,11 @@ export declare const every: {
      * Tests 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
@@ -6618,6 +7716,11 @@ export declare const every: {
      * Tests 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
@@ -6637,6 +7740,11 @@ export declare const every: {
      * Tests 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
@@ -6656,6 +7764,11 @@ export declare const every: {
      * Tests 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
@@ -6737,6 +7850,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 +7867,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 +7877,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 +7894,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 +7904,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 +7921,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 +8108,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 +8121,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 +8130,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 +8143,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 +8152,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 +8165,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 +8176,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 +8200,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 +8224,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 +8248,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 +8273,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 +8296,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 +8325,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 +8354,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 +8384,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 +8459,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 +8490,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 +8521,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 +8553,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 +8573,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 +8582,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 +8602,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 +8611,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 +8631,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 +8641,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 +8668,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 +8695,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`.
@@ -7480,7 +8725,7 @@ export declare const cartesian: {
  *
  * **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.
  *
@@ -7510,6 +8755,11 @@ export declare const Do: ReadonlyArray<{}>;
 /**
  * Introduces a new array variable into 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**
  *
  * - Each `bind` call adds a named property to the accumulated object.
@@ -7541,6 +8791,11 @@ export declare const bind: {
     /**
      * Introduces a new array variable into 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**
      *
      * - Each `bind` call adds a named property to the accumulated object.
@@ -7574,6 +8829,11 @@ export declare const bind: {
     /**
      * Introduces a new array variable into 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**
      *
      * - Each `bind` call adds a named property to the accumulated object.
@@ -7608,6 +8868,11 @@ 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.
  *
+ * **When to use**
+ *
+ * Use when you already have an array and want to start a do-notation pipeline
+ * by naming each element.
+ *
  * **Details**
  *
  * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
@@ -7635,6 +8900,11 @@ 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.
      *
+     * **When to use**
+     *
+     * Use when you already have an array and want to start a do-notation pipeline
+     * by naming each element.
+     *
      * **Details**
      *
      * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
@@ -7664,6 +8934,11 @@ 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.
      *
+     * **When to use**
+     *
+     * Use when you already have an array and want to start a do-notation pipeline
+     * by naming each element.
+     *
      * **Details**
      *
      * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
@@ -7750,6 +9025,11 @@ export declare function makeReducerConcat<A>(): Reducer.Reducer<Array<A>>;
 /**
  * Counts the 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**
  *
  * - The predicate receives both the element and its index.
@@ -7773,6 +9053,11 @@ export declare const countBy: {
     /**
      * Counts the 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**
      *
      * - The predicate receives both the element and its index.
@@ -7796,6 +9081,11 @@ export declare const countBy: {
     /**
      * Counts the 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**
      *
      * - The predicate receives both the element and its index.