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

package/dist/Array.js

@@ -1,79 +1,80 @@
 /**
- * Utilities for working with immutable arrays (and non-empty arrays) in a
- * functional style. All functions treat arrays as immutable — they return new
- * arrays rather than mutating the input.
- *
- * ## Mental model
- *
- * - **`Array<A>`** is a standard JS array. All functions in this module return
- *   new arrays; the input is never mutated.
- * - **`NonEmptyReadonlyArray<A>`** (`readonly [A, ...Array<A>]`) is a readonly
- *   array guaranteed to have at least one element. Many functions preserve or
- *   require this guarantee at the type level.
- * - **`NonEmptyArray<A>`** is the mutable counterpart: `[A, ...Array<A>]`.
- * - Most functions are **dual** — they can be called either as
- *   `Array.fn(array, arg)` (data-first) or piped as
- *   `pipe(array, Array.fn(arg))` (data-last).
- * - Functions that access elements by index return `Option<A>` for safety; use
- *   the `*NonEmpty` variants (e.g. {@link headNonEmpty}) when you already know
- *   the array is non-empty.
- * - Set-like operations ({@link union}, {@link intersection},
- *   {@link difference}) use `Equal.equivalence()` by default; use the `*With`
- *   variants for custom equality.
- *
- * ## Common tasks
- *
- * - **Create** an array: {@link make}, {@link of}, {@link empty},
- *   {@link fromIterable}, {@link range}, {@link makeBy}, {@link replicate},
- *   {@link unfold}
- * - **Access** elements: {@link head}, {@link last}, {@link get}, {@link tail},
- *   {@link init}
- * - **Transform**: {@link map}, {@link flatMap}, {@link flatten}
- * - **Filter**: {@link filter}, {@link partition}, {@link dedupe}
- * - **Combine**: {@link append}, {@link prepend}, {@link appendAll},
- *   {@link prependAll}, {@link zip}, {@link cartesian}
- * - **Split**: {@link splitAt}, {@link chunksOf}, {@link span}, {@link window}
- * - **Search**: {@link findFirst}, {@link findLast}, {@link contains}
- * - **Sort**: {@link sort}, {@link sortBy}, {@link sortWith}
- * - **Fold**: {@link reduce}, {@link scan}, {@link join}
- * - **Group**: {@link groupBy}, {@link group}, {@link groupWith}
- * - **Set operations**: {@link union}, {@link intersection},
- *   {@link difference}
- * - **Match** on empty vs non-empty: {@link match}, {@link matchLeft},
- *   {@link matchRight}
- * - **Check** properties: {@link isArray}, {@link isArrayNonEmpty},
- *   {@link every}, {@link some}
- *
- * ## Gotchas
- *
- * - {@link fromIterable} returns the original array reference when given an
- *   array; if you need a copy, use {@link copy}.
- * - `sort`, `reverse`, etc. always allocate a new array — the input is never
- *   mutated.
- * - {@link makeBy} and {@link replicate} normalize `n` to an integer >= 1 —
- *   they never produce an empty array.
- * - {@link range}`(start, end)` is inclusive on both ends. If `start > end` it
- *   returns `[start]`.
- * - Functions returning `Option` (e.g. {@link head}, {@link findFirst}) return
- *   `Option.none()` for empty inputs — they never throw.
- *
- * ## Quickstart
- *
- * **Example** (Basic array operations)
- *
- * ```ts
- * import { Array } from "effect"
- *
- * const numbers = Array.make(1, 2, 3, 4, 5)
- *
- * const doubled = Array.map(numbers, (n) => n * 2)
- * console.log(doubled) // [2, 4, 6, 8, 10]
- *
- * const evens = Array.filter(numbers, (n) => n % 2 === 0)
- * console.log(evens) // [2, 4]
- *
- * const sum = Array.reduce(numbers, 0, (acc, n) => acc + n)
- * console.log(sum) // 15
+ * The `Array` module provides functional operations for JavaScript arrays,
+ * readonly arrays, and arrays that are known to contain at least one element.
+ * Operations that transform, reorder, or update collections allocate new arrays
+ * instead of mutating their inputs, while preserving useful type information
+ * such as non-emptiness when the operation can prove it.
+ *
+ * **Mental model**
+ *
+ * - A regular `Array<A>` is still the built-in JavaScript array type; this
+ *   module supplies functional constructors, combinators, searches, folds,
+ *   grouping, sorting, and set-like operations around it.
+ * - {@link NonEmptyReadonlyArray} and {@link NonEmptyArray} encode
+ *   non-emptiness at the type level. APIs with `NonEmpty` in the name can avoid
+ *   `Option` because an element is guaranteed to exist.
+ * - Most functions are dual. You can call them data-first, such as
+ *   `Array.map(values, f)`, or data-last in a pipeline, such as
+ *   `pipe(values, Array.map(f))`.
+ * - Safe element access returns {@link Option}; unsafe or `NonEmpty` variants
+ *   are for code that already has a proof an index or element exists.
+ * - Set-like operations such as {@link union}, {@link intersection}, and
+ *   {@link difference} use the {@link Equal} protocol by default. Use the
+ *   `*With` variants when equality is domain-specific.
+ *
+ * **Common tasks**
+ *
+ * - Create arrays with {@link make}, {@link of}, {@link empty},
+ *   {@link fromIterable}, {@link range}, {@link makeBy}, {@link replicate}, and
+ *   {@link unfold}.
+ * - Access edges or indexes with {@link head}, {@link last}, {@link get},
+ *   {@link tail}, and {@link init}.
+ * - Transform and flatten with {@link map}, {@link flatMap}, and
+ *   {@link flatten}.
+ * - Keep, split, or deduplicate values with {@link filter}, {@link partition},
+ *   {@link dedupe}, and {@link dedupeAdjacent}.
+ * - Combine collections with {@link append}, {@link prepend}, {@link appendAll},
+ *   {@link prependAll}, {@link zip}, and {@link cartesian}.
+ * - Chunk, window, and slice with {@link splitAt}, {@link chunksOf},
+ *   {@link span}, and {@link window}.
+ * - Sort with {@link sort}, {@link sortWith}, and {@link sortBy}.
+ * - Fold or aggregate with {@link reduce}, {@link scan}, {@link join}, and
+ *   {@link countBy}.
+ * - Match empty and non-empty cases with {@link match}, {@link matchLeft}, and
+ *   {@link matchRight}.
+ *
+ * **Gotchas**
+ *
+ * - {@link fromIterable} returns the original array reference when the input is
+ *   already an array. Use {@link copy} when you need a fresh shallow copy.
+ * - {@link makeBy}, {@link range}, and {@link replicate} always return
+ *   non-empty arrays. `range(start, end)` is inclusive and returns `[start]`
+ *   when `start > end`.
+ * - Functions returning {@link Option}, such as {@link head} and
+ *   {@link findFirst}, return `Option.none()` for empty inputs instead of
+ *   throwing.
+ * - `NonEmpty` return types describe what the function can prove, not what may
+ *   happen for a particular runtime value after filtering.
+ *
+ * **Example** (Filtering and transforming)
+ *
+ * ```ts
+ * import { Array, Option, pipe } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ *
+ * const doubledEvens = pipe(
+ *   numbers,
+ *   Array.filter((n) => n % 2 === 0),
+ *   Array.map((n) => n * 2)
+ * )
+ *
+ * console.log(doubledEvens)
+ * // [4, 8]
+ *
+ * const first = Array.head(doubledEvens)
+ * console.log(Option.getOrElse(first, () => 0))
+ * // 4
  * ```
  *
  * @see {@link make} — create a non-empty array from elements
@@ -96,12 +97,12 @@ import * as Reducer from "./Reducer.js";
 import * as Result from "./Result.js";
 import * as Tuple from "./Tuple.js";
 /**
- * Reference to the global `Array` constructor.
+ * Exposes the global array constructor.
  *
  * **When to use**
  *
- * Use this when you need the native `Array` constructor while the `Array`
- * namespace is in scope (e.g. `Array.Array.isArray`, `Array.Array.from`).
+ * Use to access native JavaScript array constructor methods such as `isArray`
+ * or `from` from the Effect module namespace.
  *
  * **Example** (Using the Array constructor)
  *
@@ -121,7 +122,7 @@ export const Array = globalThis.Array;
  *
  * **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.
  *
@@ -146,7 +147,7 @@ export const make = (...elements) => 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.
  *
@@ -170,7 +171,7 @@ export const allocate = n => new Array(n);
  *
  * **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))`.
  *
@@ -203,7 +204,7 @@ export const makeBy = /*#__PURE__*/dual(2, (n, f) => {
  *
  * **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`.
  *
@@ -227,7 +228,7 @@ export const range = (start, end) => start <= end ? makeBy(end - start + 1, i =>
  *
  * **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))`.
  *
@@ -249,6 +250,10 @@ export const replicate = /*#__PURE__*/dual(2, (a, n) => makeBy(n, () => a));
 /**
  * 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).
@@ -275,6 +280,11 @@ export const fromIterable = collection => Array.isArray(collection) ? collection
 /**
  * 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.
@@ -300,6 +310,11 @@ export const ensure = self => Array.isArray(self) ? self : [self];
 /**
  * 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.
@@ -314,6 +329,9 @@ export const ensure = self => Array.isArray(self) ? self : [self];
  * 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
  */
@@ -321,6 +339,10 @@ export const fromRecord = Record.toEntries;
 /**
  * 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
@@ -341,7 +363,7 @@ export const fromOption = Option.toArray;
  *
  * **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.
  *
@@ -372,10 +394,14 @@ export const match = /*#__PURE__*/dual(2, (self, {
  * 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)
  *
@@ -404,10 +430,14 @@ export const matchLeft = /*#__PURE__*/dual(2, (self, {
  * 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)
  *
@@ -435,10 +465,13 @@ export const matchRight = /*#__PURE__*/dual(2, (self, {
 /**
  * Adds a single element to the front of an iterable, returning a `NonEmptyArray`.
  *
+ * **When to use**
+ *
+ * Use to add a single element at the start of an iterable and get a `NonEmptyArray`.
+ *
  * **Details**
  *
  * - Always returns a non-empty array.
- * - Does not mutate the input.
  *
  * **Example** (Prepending an element)
  *
@@ -459,10 +492,13 @@ export const prepend = /*#__PURE__*/dual(2, (self, head) => [head, ...self]);
 /**
  * Prepends all elements from a prefix iterable to the front of an array.
  *
+ * **When to use**
+ *
+ * Use to prepend multiple elements from an iterable to the front of an array.
+ *
  * **Details**
  *
  * - If either input is non-empty, the result is a `NonEmptyArray`.
- * - Does not mutate the input.
  *
  * **Example** (Prepending multiple elements)
  *
@@ -483,10 +519,14 @@ export const prependAll = /*#__PURE__*/dual(2, (self, that) => fromIterable(that
 /**
  * Adds a single element to the end of an iterable, returning a `NonEmptyArray`.
  *
+ * **When to use**
+ *
+ * Use to add one element to the end of an iterable and get a new
+ * `NonEmptyArray`.
+ *
  * **Details**
  *
  * - Always returns a non-empty array.
- * - Does not mutate the input.
  *
  * **Example** (Appending an element)
  *
@@ -507,10 +547,14 @@ export const append = /*#__PURE__*/dual(2, (self, last) => [...self, last]);
 /**
  * Concatenates two iterables into a single array.
  *
+ * **When to use**
+ *
+ * Use to combine two iterable inputs into a new array with the second input's
+ * elements after the first.
+ *
  * **Details**
  *
  * - If either input is non-empty, the result is a `NonEmptyArray`.
- * - Does not mutate the inputs.
  *
  * **Example** (Concatenating arrays)
  *
@@ -529,7 +573,11 @@ export const append = /*#__PURE__*/dual(2, (self, last) => [...self, last]);
  */
 export const appendAll = /*#__PURE__*/dual(2, (self, that) => fromIterable(self).concat(fromIterable(that)));
 /**
- * Left-to-right fold that keeps every intermediate accumulator value.
+ * Folds left-to-right while keeping every intermediate accumulator value.
+ *
+ * **When to use**
+ *
+ * Use to compute a running accumulator where each intermediate value is needed.
  *
  * **Details**
  *
@@ -562,7 +610,12 @@ export const scan = /*#__PURE__*/dual(3, (self, b, f) => {
   return out;
 });
 /**
- * Right-to-left fold that keeps every intermediate accumulator value.
+ * Folds right-to-left while keeping every intermediate accumulator value.
+ *
+ * **When to use**
+ *
+ * Use to compute a running accumulator from right to left where each intermediate
+ * value is needed.
  *
  * **Details**
  *
@@ -594,7 +647,11 @@ export const scanRight = /*#__PURE__*/dual(3, (self, b, f) => {
   return out;
 });
 /**
- * Tests whether a value is an `Array`.
+ * Checks whether a value is an `Array`.
+ *
+ * **When to use**
+ *
+ * Use to verify a value is a mutable array, narrowing its type to `Array<unknown>`.
  *
  * **Details**
  *
@@ -618,7 +675,7 @@ export const scanRight = /*#__PURE__*/dual(3, (self, b, f) => {
  */
 export const isArray = Array.isArray;
 /**
- * Tests whether a mutable `Array` is empty, narrowing the type to `[]`.
+ * Checks whether a mutable `Array` is empty, narrowing the type to `[]`.
  *
  * **Example** (Checking for an empty array)
  *
@@ -637,7 +694,7 @@ export const isArray = Array.isArray;
  */
 export const isArrayEmpty = self => self.length === 0;
 /**
- * Tests whether a `ReadonlyArray` is empty, narrowing the type to `readonly []`.
+ * Checks whether a `ReadonlyArray` is empty, narrowing the type to `readonly []`.
  *
  * **Example** (Checking for an empty readonly array)
  *
@@ -656,7 +713,7 @@ export const isArrayEmpty = self => self.length === 0;
  */
 export const isReadonlyArrayEmpty = isArrayEmpty;
 /**
- * Tests whether a mutable `Array` is non-empty, narrowing the type to
+ * Checks whether a mutable `Array` is non-empty, narrowing the type to
  * `NonEmptyArray`.
  *
  * **Example** (Checking for a non-empty array)
@@ -676,7 +733,7 @@ export const isReadonlyArrayEmpty = isArrayEmpty;
  */
 export const isArrayNonEmpty = internalArray.isArrayNonEmpty;
 /**
- * Tests whether a `ReadonlyArray` is non-empty, narrowing the type to
+ * Checks whether a `ReadonlyArray` is non-empty, narrowing the type to
  * `NonEmptyReadonlyArray`.
  *
  * **Example** (Checking for a non-empty readonly array)
@@ -698,6 +755,10 @@ export const isReadonlyArrayNonEmpty = internalArray.isArrayNonEmpty;
 /**
  * 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
@@ -716,9 +777,14 @@ export function isOutOfBounds(i, as) {
 }
 const clamp = (i, as) => Math.floor(Math.min(Math.max(0, i), as.length));
 /**
- * Safely reads an element at the given index, returning `Option.some` or
+ * Reads an element at the given index safely, returning `Option.some` or
  * `Option.none` if the index is out of bounds.
  *
+ * **When to use**
+ *
+ * Use when you need to read an array element by index and handle an
+ * out-of-bounds index as `Option.none`.
+ *
  * **Details**
  *
  * - The index is floored to an integer.
@@ -733,9 +799,9 @@ const clamp = (i, as) => Math.floor(Math.min(Math.max(0, i), as.length));
  * 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
@@ -747,6 +813,11 @@ export const get = /*#__PURE__*/dual(2, (self, index) => {
 /**
  * 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>"`.
@@ -776,6 +847,11 @@ export const getUnsafe = /*#__PURE__*/dual(2, (self, index) => {
 /**
  * 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]`.
@@ -790,9 +866,9 @@ export const getUnsafe = /*#__PURE__*/dual(2, (self, index) => {
  * 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
@@ -802,6 +878,11 @@ export const unprepend = self => [headNonEmpty(self), tailNonEmpty(self)];
  * 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]`.
@@ -816,18 +897,22 @@ export const unprepend = self => [headNonEmpty(self), tailNonEmpty(self)];
  * console.log(result) // [[1, 2, 3], 4]
  * ```
  *
- * @see {@link unprepend} — split into head + tail
- * @see {@link initNonEmpty} — get only the init
- * @see {@link lastNonEmpty} — get only the last
+ * @see {@link unprepend} for splitting a non-empty array into head and tail
+ * @see {@link initNonEmpty} for getting only the elements before the last
+ * @see {@link lastNonEmpty} for getting only the last element
  *
  * @category splitting
  * @since 2.0.0
  */
 export const unappend = self => [initNonEmpty(self), lastNonEmpty(self)];
 /**
- * Returns the first element of an array wrapped in `Option.some`, or
+ * Returns the first element of an array safely wrapped in `Option.some`, or
  * `Option.none` if the array is empty.
  *
+ * **When to use**
+ *
+ * Use to safely get the first element of an array that may be empty.
+ *
  * **Example** (Getting the first element)
  *
  * ```ts
@@ -848,6 +933,11 @@ export const head = /*#__PURE__*/get(0);
  * 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
@@ -863,9 +953,13 @@ export const head = /*#__PURE__*/get(0);
  */
 export const headNonEmpty = /*#__PURE__*/getUnsafe(0);
 /**
- * Returns the last element of an array wrapped in `Option.some`, or
+ * Returns the last element of an array safely wrapped in `Option.some`, or
  * `Option.none` if the array is empty.
  *
+ * **When to use**
+ *
+ * Use to safely get the last element of an array that may be empty.
+ *
  * **Example** (Getting the last element)
  *
  * ```ts
@@ -886,6 +980,11 @@ export const last = self => isReadonlyArrayNonEmpty(self) ? Option.some(lastNonE
  * 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
@@ -901,7 +1000,11 @@ export const last = self => isReadonlyArrayNonEmpty(self) ? Option.some(lastNonE
  */
 export const lastNonEmpty = self => self[self.length - 1];
 /**
- * Returns all elements except the first, wrapped in an `Option`.
+ * Returns all elements except the first safely, wrapped in an `Option`.
+ *
+ * **When to use**
+ *
+ * Use to safely get all elements after the first when the iterable may be empty.
  *
  * **Details**
  *
@@ -930,6 +1033,10 @@ export function tail(self) {
 /**
  * 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
@@ -946,7 +1053,11 @@ export function tail(self) {
  */
 export const tailNonEmpty = self => self.slice(1);
 /**
- * Returns all elements except the last, wrapped in an `Option`.
+ * Returns all elements except the last safely, wrapped in an `Option`.
+ *
+ * **When to use**
+ *
+ * Use to safely get all elements before the last when the iterable may be empty.
  *
  * **Details**
  *
@@ -975,6 +1086,10 @@ export function init(self) {
 /**
  * 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
@@ -993,6 +1108,10 @@ export const initNonEmpty = self => self.slice(0, -1);
 /**
  * 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]`.
@@ -1006,9 +1125,9 @@ export const initNonEmpty = self => self.slice(0, -1);
  * 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
@@ -1020,6 +1139,10 @@ export const take = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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]`.
@@ -1048,6 +1171,11 @@ export const takeRight = /*#__PURE__*/dual(2, (self, n) => {
  * 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.
@@ -1061,9 +1189,9 @@ export const takeRight = /*#__PURE__*/dual(2, (self, n) => {
  * 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
@@ -1083,11 +1211,19 @@ export const takeWhile = /*#__PURE__*/dual(2, (self, predicate) => {
 /**
  * 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
  */
@@ -1118,6 +1254,11 @@ const spanIndex = (self, predicate) => {
  * 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
@@ -1132,9 +1273,9 @@ const spanIndex = (self, predicate) => {
  * 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
@@ -1146,6 +1287,11 @@ export const span = /*#__PURE__*/dual(2, (self, predicate) => {
 /**
  * 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]`.
@@ -1159,9 +1305,9 @@ export const span = /*#__PURE__*/dual(2, (self, predicate) => {
  * 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
@@ -1173,9 +1319,13 @@ export const drop = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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)
  *
@@ -1198,9 +1348,13 @@ export const dropRight = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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)
  *
@@ -1230,11 +1384,19 @@ export const dropWhile = /*#__PURE__*/dual(2, (self, predicate) => {
 /**
  * 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
  */
@@ -1253,6 +1415,11 @@ export const dropWhileFilter = /*#__PURE__*/dual(2, (self, f) => {
  * 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
@@ -1281,6 +1448,10 @@ export const findFirstIndex = /*#__PURE__*/dual(2, (self, predicate) => {
  * 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
@@ -1308,6 +1479,11 @@ export const findLastIndex = /*#__PURE__*/dual(2, (self, predicate) => {
  * 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
@@ -1334,6 +1510,10 @@ export const findFirst = moduleIterable.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
@@ -1375,6 +1555,10 @@ export const findFirstWithIndex = /*#__PURE__*/dual(2, (self, f) => {
  * 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.
@@ -1412,13 +1596,16 @@ export const findLast = /*#__PURE__*/dual(2, (self, f) => {
   return Option.none();
 });
 /**
- * Inserts an element at the specified index, returning a new `NonEmptyArray`
+ * Inserts an element at the specified index safely, returning a new `NonEmptyArray`
  * wrapped in an `Option`.
  *
+ * **When to use**
+ *
+ * Use to insert a single element at a specific position in an array.
+ *
  * **Details**
  *
  * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
- * - Does not mutate the input.
  *
  * **Example** (Inserting at an index)
  *
@@ -1443,13 +1630,16 @@ export const insertAt = /*#__PURE__*/dual(3, (self, i, b) => {
   return Option.some(out);
 });
 /**
- * Replaces the element at the specified index with a new value, returning the
+ * Replaces the element at the specified index safely with a new value, returning the
  * updated array in `Option.some`.
  *
+ * **When to use**
+ *
+ * Use to set a fixed replacement value at a specific index.
+ *
  * **Details**
  *
  * - Returns `Option.none()` when the index is out of bounds.
- * - Does not mutate the input.
  *
  * **Example** (Replacing an element)
  *
@@ -1467,13 +1657,17 @@ export const insertAt = /*#__PURE__*/dual(3, (self, i, b) => {
  */
 export const replace = /*#__PURE__*/dual(3, (self, i, b) => modify(self, i, () => b));
 /**
- * Applies a function to the element at the specified index, returning the
+ * Applies a function to the element at the specified index safely, returning the
  * updated array in `Option.some`.
  *
+ * **When to use**
+ *
+ * Use to derive a replacement value from the current element at a specific
+ * index while leaving the other elements unchanged.
+ *
  * **Details**
  *
  * - Returns `Option.none()` when the index is out of bounds.
- * - Does not mutate the input.
  *
  * **Example** (Modifying an element)
  *
@@ -1505,9 +1699,9 @@ export const modify = /*#__PURE__*/dual(3, (self, i, f) => {
  * Removes the element at the specified index, returning a new array. If the
  * index is out of bounds, returns a copy of the original.
  *
- * **Details**
+ * **When to use**
  *
- * - Does not mutate the input.
+ * Use to remove a single element at a known index.
  *
  * **Example** (Removing an element)
  *
@@ -1535,9 +1729,12 @@ export const remove = /*#__PURE__*/dual(2, (self, i) => {
 /**
  * Reverses an iterable into a new array.
  *
+ * **When to use**
+ *
+ * Use to reverse the order of elements without mutating the original input.
+ *
  * **Details**
  *
- * - Does not mutate the input.
  * - Preserves `NonEmptyArray` in the return type.
  *
  * **Example** (Reversing an array)
@@ -1555,9 +1752,12 @@ export const reverse = self => Array.from(self).reverse();
 /**
  * Sorts an array by the given `Order`, returning a new array.
  *
+ * **When to use**
+ *
+ * Use to sort an array using a single `Order` comparator.
+ *
  * **Details**
  *
- * - Does not mutate the input.
  * - Preserves `NonEmptyArray` in the return type.
  * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
  *   multi-key sorting.
@@ -1585,10 +1785,14 @@ export const sort = /*#__PURE__*/dual(2, (self, O) => {
  * Sorts an array by a derived key using a mapping function and an `Order` for
  * that key.
  *
+ * **When to use**
+ *
+ * Use when values need to be sorted by a derived key, such as a string length
+ * or object field, while the output should keep the original values.
+ *
  * **Details**
  *
  * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
- * - Does not mutate the input.
  *
  * **Example** (Sorting strings by length)
  *
@@ -1599,8 +1803,8 @@ export const sort = /*#__PURE__*/dual(2, (self, O) => {
  * // ["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
@@ -1610,6 +1814,11 @@ export const sortWith = /*#__PURE__*/dual(3, (self, f, order) => Array.from(self
  * 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).
@@ -1657,6 +1866,10 @@ export const sortBy = (...orders) => {
  * 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.
@@ -1738,6 +1951,10 @@ export const unzip = self => {
 /**
  * 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.
@@ -1775,6 +1992,10 @@ export const intersperse = /*#__PURE__*/dual(2, (self, middle) => {
  * 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
@@ -1846,9 +2067,14 @@ export const modifyLastNonEmpty = /*#__PURE__*/dual(2, (self, f) => append(initN
  */
 export const setLastNonEmpty = /*#__PURE__*/dual(2, (self, b) => modifyLastNonEmpty(self, () => b));
 /**
- * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+ * Transforms an array by rotating it `n` steps. Positive `n` rotates right; negative `n`
  * rotates left.
  *
+ * **When to use**
+ *
+ * Use when elements should wrap around the end of the array rather than being
+ * dropped.
+ *
  * **Details**
  *
  * - `n` is rounded to the nearest integer before rotating.
@@ -1863,6 +2089,9 @@ export const setLastNonEmpty = /*#__PURE__*/dual(2, (self, b) => modifyLastNonEm
  * 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
  */
@@ -1886,6 +2115,11 @@ export const rotate = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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
@@ -1895,7 +2129,7 @@ export const rotate = /*#__PURE__*/dual(2, (self, n) => {
  * 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
@@ -1909,9 +2143,14 @@ export const containsWith = isEquivalent => dual(2, (self, a) => {
   return false;
 });
 /**
- * Tests whether an array contains a value, using `Equal.equivalence()` for
+ * Checks whether an array contains a value, using `Equal.equivalence()` for
  * comparison.
  *
+ * **When to use**
+ *
+ * Use to check membership with Effect's default equality instead of providing a
+ * comparison function.
+ *
  * **Example** (Checking membership)
  *
  * ```ts
@@ -1927,8 +2166,13 @@ export const containsWith = isEquivalent => dual(2, (self, a) => {
  */
 export const contains = /*#__PURE__*/containsWith(/*#__PURE__*/Equal.asEquivalence());
 /**
- * Repeatedly applies a function that consumes a prefix of the array and
- * produces a value plus the remaining elements, collecting the values.
+ * Applies a function repeatedly to consume prefixes of the array and collect
+ * the values it produces.
+ *
+ * **When to use**
+ *
+ * Use when the grouping logic is custom and each step needs to return both a
+ * value and the remaining input.
  *
  * **Details**
  *
@@ -1973,6 +2217,10 @@ export const chop = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * 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).
@@ -2028,6 +2276,10 @@ export const splitAtNonEmpty = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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.
@@ -2054,6 +2306,10 @@ export const split = /*#__PURE__*/dual(2, (self, n) => {
  * 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
@@ -2072,6 +2328,11 @@ export const splitWhere = /*#__PURE__*/dual(2, (self, predicate) => span(self, (
 /**
  * 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.
@@ -2098,6 +2359,10 @@ export const copy = self => self.slice();
  * 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`.
@@ -2126,6 +2391,11 @@ export const pad = /*#__PURE__*/dual(3, (self, n, fill) => {
  * 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 `[[]]`.
@@ -2156,6 +2426,10 @@ export const chunksOf = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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.
@@ -2187,6 +2461,11 @@ export const window = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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.
@@ -2201,8 +2480,8 @@ export const window = /*#__PURE__*/dual(2, (self, n) => {
  * // [["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
@@ -2224,6 +2503,11 @@ export const groupWith = /*#__PURE__*/dual(2, (self, isEquivalent) => chop(self,
 /**
  * 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.
@@ -2247,6 +2531,10 @@ export const group = /*#__PURE__*/groupWith(/*#__PURE__*/Equal.asEquivalence());
  * 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
@@ -2291,6 +2579,11 @@ export const groupBy = /*#__PURE__*/dual(2, (self, f) => {
  * 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
@@ -2299,9 +2592,9 @@ export const groupBy = /*#__PURE__*/dual(2, (self, f) => {
  * 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
@@ -2342,6 +2635,11 @@ export const union = /*#__PURE__*/dual(2, (self, that) => unionWith(self, that,
  * 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
@@ -2353,9 +2651,9 @@ export const union = /*#__PURE__*/dual(2, (self, that) => unionWith(self, that,
  * 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
@@ -2391,6 +2689,11 @@ export const intersection = /*#__PURE__*/intersectionWith(/*#__PURE__*/Equal.asE
  * 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
@@ -2400,9 +2703,9 @@ export const intersection = /*#__PURE__*/intersectionWith(/*#__PURE__*/Equal.asE
  * 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
@@ -2418,6 +2721,11 @@ export const differenceWith = isEquivalent => {
  * 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
@@ -2437,6 +2745,10 @@ export const difference = /*#__PURE__*/differenceWith(/*#__PURE__*/Equal.asEquiv
 /**
  * Creates an empty array.
  *
+ * **When to use**
+ *
+ * Use to create a typed empty array without allocating placeholder elements.
+ *
  * **Example** (Creating an empty array)
  *
  * ```ts
@@ -2474,6 +2786,10 @@ export const of = a => [a];
 /**
  * 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)`.
@@ -2496,6 +2812,11 @@ export const map = /*#__PURE__*/dual(2, (self, f) => self.map(f));
 /**
  * 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)`.
@@ -2531,6 +2852,11 @@ export const flatMap = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * 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
@@ -2548,6 +2874,11 @@ export const flatten = /*#__PURE__*/flatMap(identity);
 /**
  * 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
@@ -2575,6 +2906,11 @@ export const getSomes = self => {
  * 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
@@ -2603,6 +2939,11 @@ export const getFailures = self => {
  * 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
@@ -2630,6 +2971,11 @@ export const getSuccesses = self => {
 /**
  * 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)`.
@@ -2645,6 +2991,7 @@ export const getSuccesses = self => {
  * ```
  *
  * @see {@link filter} — keep original elements matching a predicate
+ * @see {@link partition} for keeping both failures and successes
  *
  * @category filtering
  * @since 2.0.0
@@ -2663,6 +3010,10 @@ export const filterMap = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * 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)`.
@@ -2677,6 +3028,7 @@ export const filterMap = /*#__PURE__*/dual(2, (self, f) => {
  * ```
  *
  * @see {@link partition} — split into matching and non-matching
+ * @see {@link filterMap} for transforming while filtering
  *
  * @category filtering
  * @since 2.0.0
@@ -2694,6 +3046,11 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => {
 /**
  * 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]`.
@@ -2711,6 +3068,7 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => {
  * ```
  *
  * @see {@link filter} — keep only matching elements
+ * @see {@link filterMap} for discarding failures
  * @see {@link separate} — split an iterable of `Result` values
  *
  * @category filtering
@@ -2733,6 +3091,10 @@ export const partition = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * 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]`.
@@ -2752,6 +3114,7 @@ export const partition = /*#__PURE__*/dual(2, (self, f) => {
  *
  * @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
@@ -2760,6 +3123,10 @@ export const separate = /*#__PURE__*/partition(identity);
 /**
  * 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)`.
@@ -2782,6 +3149,11 @@ export const reduce = /*#__PURE__*/dual(3, (self, b, f) => fromIterable(self).re
 /**
  * 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)`.
@@ -2850,6 +3222,10 @@ export const liftOption = f => (...a) => fromOption(f(...a));
  * 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
@@ -2895,6 +3271,11 @@ export const liftNullishOr = f => (...a) => fromNullishOr(f(...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
@@ -2904,6 +3285,9 @@ export const liftNullishOr = f => (...a) => fromNullishOr(f(...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
  */
@@ -2938,9 +3322,14 @@ export const liftResult = f => (...a) => {
   return Result.isFailure(e) ? [] : [e.success];
 };
 /**
- * Tests whether all elements satisfy the predicate. Supports refinements for
+ * Checks whether all elements satisfy the predicate. Supports refinements for
  * type narrowing.
  *
+ * **When to use**
+ *
+ * Use to check that all elements satisfy a predicate, including
+ * refinement-based type narrowing.
+ *
  * **Example** (Testing all elements)
  *
  * ```ts
@@ -2957,7 +3346,7 @@ export const liftResult = f => (...a) => {
  */
 export const every = /*#__PURE__*/dual(2, (self, refinement) => self.every(refinement));
 /**
- * Tests whether at least one element satisfies the predicate. Narrows the type
+ * Checks whether at least one element satisfies the predicate. Narrows the type
  * to `NonEmptyReadonlyArray` on success.
  *
  * **Example** (Testing for any match)
@@ -2980,6 +3369,11 @@ export const some = /*#__PURE__*/dual(2, (self, predicate) => self.some(predicat
  * 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)`.
@@ -2992,6 +3386,8 @@ export const some = /*#__PURE__*/dual(2, (self, predicate) => self.some(predicat
  * 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
  */
@@ -3111,6 +3507,11 @@ export const makeEquivalence = Equivalence.Array;
 /**
  * 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
@@ -3119,6 +3520,8 @@ export const makeEquivalence = Equivalence.Array;
  * 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
  */
@@ -3127,6 +3530,11 @@ export const forEach = /*#__PURE__*/dual(2, (self, f) => fromIterable(self).forE
  * 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
@@ -3159,6 +3567,11 @@ export const dedupeWith = /*#__PURE__*/dual(2, (self, isEquivalent) => {
  * 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
@@ -3177,6 +3590,12 @@ export const dedupe = self => dedupeWith(self, Equal.asEquivalence());
 /**
  * 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.
@@ -3210,6 +3629,11 @@ export const dedupeAdjacentWith = /*#__PURE__*/dual(2, (self, isEquivalent) => {
 /**
  * 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
@@ -3245,6 +3669,11 @@ export const join = /*#__PURE__*/dual(2, (self, sep) => fromIterable(self).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.
@@ -3282,6 +3711,11 @@ export const mapAccum = /*#__PURE__*/dual(3, (self, s, f) => {
 /**
  * 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`.
@@ -3297,7 +3731,7 @@ export const mapAccum = /*#__PURE__*/dual(3, (self, s, f) => {
  * 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
@@ -3306,6 +3740,10 @@ export const cartesianWith = /*#__PURE__*/dual(3, (self, that, f) => flatMap(sel
 /**
  * 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`.
@@ -3330,11 +3768,11 @@ export const cartesian = /*#__PURE__*/dual(2, (self, that) => cartesianWith(self
 // do notation
 // -------------------------------------------------------------------------------------
 /**
- * Starting point for the "do simulation" — an array comprehension pattern.
+ * Provides the starting point for the "do simulation" — an array comprehension pattern.
  *
  * **When to use**
  *
- * - Begin a pipeline with `Do`, then use {@link bind} to introduce array variables and {@link let_ let} for plain values.
+ * Use when begin a pipeline with `Do`, then use {@link bind} to introduce array variables and {@link let_ let} for plain values.
  * - Each `bind` produces the cartesian product of all bound variables (like nested loops).
  * - Use `filter` and `map` in the pipeline to add conditions and transformations.
  *
@@ -3362,7 +3800,12 @@ export const cartesian = /*#__PURE__*/dual(2, (self, that) => cartesianWith(self
  */
 export const Do = /*#__PURE__*/of({});
 /**
- * Introduces a new array variable into a do-notation scope, producing the cartesian product with all previous bindings.
+ * Adds a new array variable to a do-notation scope, producing the cartesian product with all previous bindings.
+ *
+ * **When to use**
+ *
+ * Use to add another array-producing binding to an `Array.Do` pipeline, pairing
+ * each existing scope with every value returned by the callback.
  *
  * **Details**
  *
@@ -3393,7 +3836,12 @@ export const Do = /*#__PURE__*/of({});
  */
 export const bind = /*#__PURE__*/internalDoNotation.bind(map, flatMap);
 /**
- * Names the elements of an array by wrapping each in an object with the given key, starting a do-notation scope.
+ * Wraps each array element in an object with the given key, starting a do-notation scope.
+ *
+ * **When to use**
+ *
+ * Use when you already have an array and want to start a do-notation pipeline
+ * by naming each element.
  *
  * **Details**
  *
@@ -3474,7 +3922,12 @@ export function makeReducerConcat() {
   return reducer;
 }
 /**
- * Counts the elements in an iterable that satisfy a predicate.
+ * Computes the number of elements in an iterable that satisfy a predicate.
+ *
+ * **When to use**
+ *
+ * Use to count how many elements satisfy a predicate when you only need the
+ * number of matches instead of the matching elements.
  *
  * **Details**
  *