effect 4.0.0-beta.69 → 4.0.0-beta.70

package/dist/Array.js

@@ -98,6 +98,8 @@ import * as Tuple from "./Tuple.js";
 /**
  * Reference to 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`).
  *
@@ -117,6 +119,8 @@ export const Array = globalThis.Array;
 /**
  * Creates a `NonEmptyArray` from one or more elements.
  *
+ * **When to use**
+ *
  * - 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.
@@ -140,6 +144,8 @@ export const make = (...elements) => elements;
 /**
  * Creates a new `Array` of the specified length with all slots uninitialized.
  *
+ * **When to use**
+ *
  * - 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.
@@ -162,6 +168,8 @@ export const allocate = n => new Array(n);
 /**
  * Creates a `NonEmptyArray` of length `n` where element `i` is computed by `f(i)`.
  *
+ * **When to use**
+ *
  * - 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))`.
@@ -193,6 +201,8 @@ export const makeBy = /*#__PURE__*/dual(2, (n, f) => {
  * Creates a `NonEmptyArray` containing a range of integers, inclusive on both
  * ends.
  *
+ * **When to use**
+ *
  * - Use when you need a sequence of consecutive integers.
  * - If `start > end`, returns `[start]`.
  * - Always returns a `NonEmptyArray`.
@@ -215,6 +225,8 @@ export const range = (start, end) => start <= end ? makeBy(end - start + 1, i =>
 /**
  * Creates a `NonEmptyArray` containing a value repeated `n` times.
  *
+ * **When to use**
+ *
  * - 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))`.
@@ -237,6 +249,8 @@ export const replicate = /*#__PURE__*/dual(2, (a, n) => makeBy(n, () => a));
 /**
  * Converts an `Iterable` to an `Array`.
  *
+ * **Details**
+ *
  * - If the input is already an array, returns it **by reference** (no copy).
  * - Otherwise, creates a new array from the iterable.
  * - Use {@link copy} if you need a fresh array even when the input is already
@@ -261,6 +275,8 @@ export const fromIterable = collection => Array.isArray(collection) ? collection
 /**
  * Normalizes a value that is either a single element or an array into an array.
  *
+ * **Details**
+ *
  * - If the input is already an array, returns it by reference.
  * - If the input is a single value, wraps it in a one-element array.
  * - Useful for APIs that accept `A | Array<A>`.
@@ -284,6 +300,8 @@ export const ensure = self => Array.isArray(self) ? self : [self];
 /**
  * Converts a record into an array of `[key, value]` tuples.
  *
+ * **Details**
+ *
  * - Key order follows `Object.entries` semantics.
  * - Returns an empty array for an empty record.
  *
@@ -321,6 +339,8 @@ export const fromOption = Option.toArray;
 /**
  * Pattern-matches on an array, handling empty and non-empty cases separately.
  *
+ * **When to use**
+ *
  * - Use when you need to branch on whether an array has elements.
  * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
  * - Dual: data-first or data-last.
@@ -352,6 +372,8 @@ export const match = /*#__PURE__*/dual(2, (self, {
  * Pattern-matches on an array from the left, providing the first element and
  * the remaining elements separately.
  *
+ * **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.
  *
@@ -382,6 +404,8 @@ 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.
  *
+ * **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.
  *
@@ -411,6 +435,8 @@ export const matchRight = /*#__PURE__*/dual(2, (self, {
 /**
  * Adds a single element to the front of an iterable, returning a `NonEmptyArray`.
  *
+ * **Details**
+ *
  * - Always returns a non-empty array.
  * - Does not mutate the input.
  *
@@ -433,6 +459,8 @@ export const prepend = /*#__PURE__*/dual(2, (self, head) => [head, ...self]);
 /**
  * Prepends all elements from a prefix iterable to the front of an array.
  *
+ * **Details**
+ *
  * - If either input is non-empty, the result is a `NonEmptyArray`.
  * - Does not mutate the input.
  *
@@ -455,6 +483,8 @@ export const prependAll = /*#__PURE__*/dual(2, (self, that) => fromIterable(that
 /**
  * Adds a single element to the end of an iterable, returning a `NonEmptyArray`.
  *
+ * **Details**
+ *
  * - Always returns a non-empty array.
  * - Does not mutate the input.
  *
@@ -477,6 +507,8 @@ export const append = /*#__PURE__*/dual(2, (self, last) => [...self, last]);
 /**
  * Concatenates two iterables into a single array.
  *
+ * **Details**
+ *
  * - If either input is non-empty, the result is a `NonEmptyArray`.
  * - Does not mutate the inputs.
  *
@@ -499,6 +531,8 @@ export const appendAll = /*#__PURE__*/dual(2, (self, that) => fromIterable(self)
 /**
  * Left-to-right fold that keeps every intermediate accumulator value.
  *
+ * **Details**
+ *
  * - The output length is `input.length + 1` (starts with the initial value).
  * - Always returns a `NonEmptyArray` because the initial value is included.
  * - Use {@link reduce} if you only need the final accumulated value.
@@ -530,6 +564,8 @@ export const scan = /*#__PURE__*/dual(3, (self, b, f) => {
 /**
  * Right-to-left fold that keeps every intermediate accumulator value.
  *
+ * **Details**
+ *
  * - The output length is `input.length + 1` (ends with the initial value).
  * - Always returns a `NonEmptyArray`.
  *
@@ -560,6 +596,8 @@ export const scanRight = /*#__PURE__*/dual(3, (self, b, f) => {
 /**
  * Tests whether a value is an `Array`.
  *
+ * **Details**
+ *
  * - Acts as a type guard narrowing the input to `Array<unknown>`.
  * - Delegates to `globalThis.Array.isArray`.
  *
@@ -681,6 +719,8 @@ 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
  * `Option.none` if the index is out of bounds.
  *
+ * **Details**
+ *
  * - The index is floored to an integer.
  * - Never throws.
  *
@@ -707,6 +747,8 @@ export const get = /*#__PURE__*/dual(2, (self, index) => {
 /**
  * Reads an element at the given index, throwing if the index is out of bounds.
  *
+ * **Details**
+ *
  * - Throws an `Error` with the message `"Index out of bounds: <i>"`.
  * - Prefer {@link get} for safe access.
  *
@@ -734,6 +776,8 @@ export const getUnsafe = /*#__PURE__*/dual(2, (self, index) => {
 /**
  * Splits a non-empty array into its first element and the remaining elements.
  *
+ * **Details**
+ *
  * - Returns a tuple `[head, tail]`.
  * - Requires a `NonEmptyReadonlyArray`.
  *
@@ -758,6 +802,8 @@ export const unprepend = self => [headNonEmpty(self), tailNonEmpty(self)];
  * Splits a non-empty array into all elements except the last, and the last
  * element.
  *
+ * **Details**
+ *
  * - Returns a tuple `[init, last]`.
  * - Requires a `NonEmptyReadonlyArray`.
  *
@@ -857,6 +903,8 @@ export const lastNonEmpty = self => self[self.length - 1];
 /**
  * Returns all elements except the first, wrapped in an `Option`.
  *
+ * **Details**
+ *
  * - Allocates a new array via `slice(1)`.
  * - Returns `Option.none()` for empty inputs.
  *
@@ -900,6 +948,8 @@ export const tailNonEmpty = self => self.slice(1);
 /**
  * Returns all elements except the last, wrapped in an `Option`.
  *
+ * **Details**
+ *
  * - Allocates a new array via `slice(0, -1)`.
  * - Returns `Option.none()` for empty inputs.
  *
@@ -943,6 +993,8 @@ export const initNonEmpty = self => self.slice(0, -1);
 /**
  * Keeps the first `n` elements, creating a new array.
  *
+ * **Details**
+ *
  * - `n` is clamped to `[0, length]`.
  * - Returns an empty array when `n <= 0`.
  *
@@ -968,6 +1020,8 @@ export const take = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * Keeps the last `n` elements, creating a new array.
  *
+ * **Details**
+ *
  * - `n` is clamped to `[0, length]`.
  * - Returns an empty array when `n <= 0`.
  *
@@ -994,6 +1048,8 @@ export const takeRight = /*#__PURE__*/dual(2, (self, n) => {
  * Takes elements from the start while the predicate holds, stopping at the
  * first element that fails.
  *
+ * **Details**
+ *
  * - Supports refinements for type narrowing.
  * - The predicate receives `(element, index)`.
  *
@@ -1027,6 +1083,8 @@ export const takeWhile = /*#__PURE__*/dual(2, (self, predicate) => {
 /**
  * Takes elements from the start while a `Filter` succeeds, collecting transformed values.
  *
+ * **Details**
+ *
  * - The filter receives `(element, index)`.
  * - Stops at the first filter failure.
  *
@@ -1060,6 +1118,8 @@ const spanIndex = (self, predicate) => {
  * Splits an iterable into two arrays: the longest prefix where the predicate
  * holds, and the remaining elements.
  *
+ * **Details**
+ *
  * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
  *   (single pass).
  * - Supports refinements for type narrowing of the prefix.
@@ -1086,6 +1146,8 @@ export const span = /*#__PURE__*/dual(2, (self, predicate) => {
 /**
  * Removes the first `n` elements, creating a new array.
  *
+ * **Details**
+ *
  * - `n` is clamped to `[0, length]`.
  * - Returns a copy of the full array when `n <= 0`.
  *
@@ -1111,6 +1173,8 @@ export const drop = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * Removes the last `n` elements, creating a new array.
  *
+ * **Details**
+ *
  * - `n` is clamped to `[0, length]`.
  *
  * **Example** (Dropping from the end)
@@ -1134,6 +1198,8 @@ export const dropRight = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * Drops elements from the start while the predicate holds, returning the rest.
  *
+ * **Details**
+ *
  * - The predicate receives `(element, index)`.
  *
  * **Example** (Dropping while condition holds)
@@ -1164,6 +1230,8 @@ export const dropWhile = /*#__PURE__*/dual(2, (self, predicate) => {
 /**
  * Drops elements from the start while a `Filter` succeeds.
  *
+ * **Details**
+ *
  * - The filter receives `(element, index)`.
  * - Returns the remaining original elements after the first filter failure.
  *
@@ -1240,6 +1308,8 @@ export const findLastIndex = /*#__PURE__*/dual(2, (self, predicate) => {
  * Returns the first element matching a predicate, refinement, or mapping
  * function, wrapped in `Option`.
  *
+ * **Details**
+ *
  * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
  *   `(a, i) => Option<B>` for simultaneous find-and-transform.
  * - Returns `Option.none()` if no element matches.
@@ -1264,6 +1334,8 @@ export const findFirst = moduleIterable.findFirst;
  * Returns the first selected value together with its index, wrapped in an
  * `Option`.
  *
+ * **Details**
+ *
  * Accepts a predicate, a refinement, or a function returning `Option`. For an
  * `Option`-returning function, returns `[mappedValue, index]` for the first
  * `Some`, or `Option.none()` if no element is selected.
@@ -1303,6 +1375,8 @@ export const findFirstWithIndex = /*#__PURE__*/dual(2, (self, f) => {
  * Returns the last element matching a predicate, refinement, or mapping
  * function, wrapped in `Option`.
  *
+ * **Details**
+ *
  * - Searches from the end of the array.
  * - Returns `Option.none()` if no element matches.
  *
@@ -1341,6 +1415,8 @@ export const findLast = /*#__PURE__*/dual(2, (self, f) => {
  * Inserts an element at the specified index, returning a new `NonEmptyArray`
  * wrapped in an `Option`.
  *
+ * **Details**
+ *
  * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
  * - Does not mutate the input.
  *
@@ -1370,6 +1446,8 @@ export const insertAt = /*#__PURE__*/dual(3, (self, i, b) => {
  * Replaces the element at the specified index with a new value, returning the
  * updated array in `Option.some`.
  *
+ * **Details**
+ *
  * - Returns `Option.none()` when the index is out of bounds.
  * - Does not mutate the input.
  *
@@ -1392,6 +1470,8 @@ export const replace = /*#__PURE__*/dual(3, (self, i, b) => modify(self, i, () =
  * Applies a function to the element at the specified index, returning the
  * updated array in `Option.some`.
  *
+ * **Details**
+ *
  * - Returns `Option.none()` when the index is out of bounds.
  * - Does not mutate the input.
  *
@@ -1425,6 +1505,8 @@ 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**
+ *
  * - Does not mutate the input.
  *
  * **Example** (Removing an element)
@@ -1453,6 +1535,8 @@ export const remove = /*#__PURE__*/dual(2, (self, i) => {
 /**
  * Reverses an iterable into a new array.
  *
+ * **Details**
+ *
  * - Does not mutate the input.
  * - Preserves `NonEmptyArray` in the return type.
  *
@@ -1471,6 +1555,8 @@ export const reverse = self => Array.from(self).reverse();
 /**
  * Sorts an array by the given `Order`, returning a new array.
  *
+ * **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
@@ -1499,6 +1585,8 @@ 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.
  *
+ * **Details**
+ *
  * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
  * - Does not mutate the input.
  *
@@ -1522,6 +1610,8 @@ 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.
  *
+ * **Details**
+ *
  * - Data-last only (returns a function).
  * - Preserves `NonEmptyArray` in the return type.
  *
@@ -1567,6 +1657,8 @@ 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.
  *
+ * **Details**
+ *
  * - Returns `NonEmptyArray` when both inputs are non-empty.
  *
  * **Example** (Zipping two arrays)
@@ -1646,6 +1738,8 @@ export const unzip = self => {
 /**
  * Places a separator element between every pair of elements.
  *
+ * **Details**
+ *
  * - Preserves `NonEmptyArray` in the return type.
  * - An empty input produces an empty result.
  *
@@ -1755,6 +1849,8 @@ export const setLastNonEmpty = /*#__PURE__*/dual(2, (self, b) => modifyLastNonEm
  * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
  * rotates left.
  *
+ * **Details**
+ *
  * - `n` is rounded to the nearest integer before rotating.
  * - Preserves `NonEmptyArray` in the return type.
  * - Returns a copy for empty arrays or when the normalized rotation is `0`.
@@ -1834,6 +1930,8 @@ export const contains = /*#__PURE__*/containsWith(/*#__PURE__*/Equal.asEquivalen
  * Repeatedly applies a function that consumes a prefix of the array and
  * produces a value plus the remaining elements, collecting the values.
  *
+ * **Details**
+ *
  * - The function receives a `NonEmptyReadonlyArray` and returns
  *   `[value, rest]`.
  * - Continues until the remaining array is empty.
@@ -1875,6 +1973,8 @@ export const chop = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * Splits an iterable into two arrays at the given index.
  *
+ * **Details**
+ *
  * - `n` can be `0` (all elements in the second array).
  * - `n` is floored to an integer.
  *
@@ -1928,6 +2028,8 @@ export const splitAtNonEmpty = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * Splits an iterable into `n` roughly equal-sized chunks.
  *
+ * **Details**
+ *
  * - Uses `chunksOf(ceil(length / n))` internally.
  * - The last chunk may be shorter.
  *
@@ -1970,6 +2072,8 @@ export const splitWhere = /*#__PURE__*/dual(2, (self, predicate) => span(self, (
 /**
  * Creates a shallow copy of an array.
  *
+ * **Details**
+ *
  * - Preserves `NonEmptyArray` in the return type.
  * - Useful when you need a distinct reference (e.g. before mutating).
  *
@@ -1994,6 +2098,8 @@ 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.
  *
+ * **Details**
+ *
  * - Returns an empty array when `n <= 0`.
  *
  * **Example** (Padding an array)
@@ -2020,6 +2126,8 @@ 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.
  *
+ * **Details**
+ *
  * - `chunksOf(n)([])` is `[]`, not `[[]]`.
  * - Each chunk is a `NonEmptyArray`.
  * - Preserves `NonEmptyArray` in the outer return type.
@@ -2048,6 +2156,8 @@ export const chunksOf = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * Creates overlapping sliding windows of size `n`.
  *
+ * **Details**
+ *
  * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
  * - Each window is a tuple of exactly `n` elements.
  *
@@ -2077,6 +2187,8 @@ export const window = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * Groups consecutive equal elements using a custom equivalence function.
  *
+ * **Details**
+ *
  * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
  * - Requires a `NonEmptyReadonlyArray`.
  *
@@ -2112,6 +2224,8 @@ export const groupWith = /*#__PURE__*/dual(2, (self, isEquivalent) => chop(self,
 /**
  * Groups consecutive equal elements using `Equal.equivalence()`.
  *
+ * **Details**
+ *
  * - Only groups **adjacent** elements.
  *
  * **Example** (Grouping adjacent equal elements)
@@ -2133,6 +2247,8 @@ 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.
  *
+ * **Details**
+ *
  * - Unlike {@link group}/{@link groupWith}, elements do not need to be
  *   adjacent to be grouped together.
  * - Key function must return a `string` or `symbol`.
@@ -2358,6 +2474,8 @@ export const of = a => [a];
 /**
  * Transforms each element using a function, returning a new array.
  *
+ * **Details**
+ *
  * - The function receives `(element, index)`.
  * - Preserves `NonEmptyArray` in the return type.
  *
@@ -2378,6 +2496,8 @@ 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.
  *
+ * **Details**
+ *
  * - The function receives `(element, index)`.
  * - Returns `NonEmptyArray` when both input and mapped arrays are non-empty.
  *
@@ -2510,6 +2630,8 @@ export const getSuccesses = self => {
 /**
  * Keeps transformed values for elements where a `Filter` succeeds.
  *
+ * **Details**
+ *
  * - The filter receives `(element, index)`.
  * - Failures are discarded.
  *
@@ -2541,6 +2663,8 @@ export const filterMap = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * Keeps only elements satisfying a predicate (or refinement).
  *
+ * **Details**
+ *
  * - The predicate receives `(element, index)`.
  * - Supports refinements for type narrowing.
  *
@@ -2570,6 +2694,8 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => {
 /**
  * Splits an iterable using a `Filter` into failures and successes.
  *
+ * **Details**
+ *
  * - Returns `[excluded, satisfying]`.
  * - The filter receives `(element, index)`.
  *
@@ -2607,6 +2733,8 @@ export const partition = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * Separates an iterable of `Result`s into failure values and success values.
  *
+ * **Details**
+ *
  * - Returns `[failures, successes]`.
  * - Equivalent to `partition(identity)`.
  *
@@ -2632,6 +2760,8 @@ export const separate = /*#__PURE__*/partition(identity);
 /**
  * Folds an iterable from left to right into a single value.
  *
+ * **Details**
+ *
  * - The function receives `(accumulator, element, index)`.
  *
  * **Example** (Summing an array)
@@ -2652,6 +2782,8 @@ export const reduce = /*#__PURE__*/dual(3, (self, b, f) => fromIterable(self).re
 /**
  * Folds an iterable from right to left into a single value.
  *
+ * **Details**
+ *
  * - The function receives `(accumulator, element, index)`.
  *
  * **Example** (Right-to-left fold)
@@ -2848,6 +2980,8 @@ 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.
  *
+ * **Details**
+ *
  * - For index `i`, the function receives `self.slice(i)`.
  *
  * **Example** (Suffix lengths)
@@ -3043,6 +3177,8 @@ export const dedupe = self => dedupeWith(self, Equal.asEquivalence());
 /**
  * Removes consecutive duplicate elements using a custom equivalence.
  *
+ * **Details**
+ *
  * - Non-adjacent duplicates are preserved.
  *
  * **Example** (Deduplicating adjacent elements)
@@ -3109,6 +3245,8 @@ 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.
  *
+ * **Details**
+ *
  * - Combines `map` and `reduce` in a single pass.
  * - The callback receives the current state, element, and index, and returns `[nextState, mappedValue]`.
  * - Returns `[finalState, mappedArray]`.
@@ -3144,6 +3282,8 @@ export const mapAccum = /*#__PURE__*/dual(3, (self, s, f) => {
 /**
  * Computes the cartesian product of two arrays, applying a combiner to each pair.
  *
+ * **Details**
+ *
  * - Produces every combination of an element from `self` with an element from `that`.
  * - Result length is `self.length * that.length`.
  * - Order: iterates `that` for each element of `self`.
@@ -3166,6 +3306,8 @@ export const cartesianWith = /*#__PURE__*/dual(3, (self, that, f) => flatMap(sel
 /**
  * Computes the cartesian product of two arrays, returning all pairs as tuples.
  *
+ * **Details**
+ *
  * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
  * - Result length is `self.length * that.length`.
  *
@@ -3190,6 +3332,8 @@ export const cartesian = /*#__PURE__*/dual(2, (self, that) => cartesianWith(self
 /**
  * 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.
  * - 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.
@@ -3220,6 +3364,8 @@ export const Do = /*#__PURE__*/of({});
 /**
  * Introduces a new array variable into a do-notation scope, producing the cartesian product with all previous bindings.
  *
+ * **Details**
+ *
  * - Each `bind` call adds a named property to the accumulated object.
  * - The callback receives the current scope and must return an array.
  * - Equivalent to `flatMap` + merging the new value into the scope object.
@@ -3249,6 +3395,8 @@ 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.
  *
+ * **Details**
+ *
  * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
  * - Alternative to starting with `Do` + `bind`; useful when you already have an array.
  *
@@ -3276,6 +3424,8 @@ export {
 /**
  * Adds a computed plain value to the do-notation scope without introducing a new array dimension.
  *
+ * **Details**
+ *
  * - Unlike {@link bind}, the callback returns a single value (not an array), so no cartesian product occurs.
  * - Useful for derived or intermediate values that depend on previously bound variables.
  *
@@ -3326,6 +3476,8 @@ export function makeReducerConcat() {
 /**
  * Counts the elements in an iterable that satisfy a predicate.
  *
+ * **Details**
+ *
  * - The predicate receives both the element and its index.
  * - Returns `0` for an empty iterable.
  *