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

package/dist/Iterable.d.ts

@@ -1,31 +1,54 @@
 /**
- * This module provides utility functions for working with Iterables in TypeScript.
+ * The `Iterable` module works with any JavaScript value that implements
+ * `[Symbol.iterator]`, including arrays, strings, generators, sets, and custom
+ * lazy sequences. It provides constructors, transformations, searches, grouping,
+ * and folding helpers that can be used without converting to an array first.
+ *
+ * **Mental model**
+ *
+ * - An `Iterable<A>` creates an `Iterator<A>` when it is consumed.
+ * - Transformations such as {@link map}, {@link filter}, {@link flatMap},
+ *   {@link take}, and {@link drop} return new iterables and usually do no work
+ *   until the result is iterated.
+ * - Consumers such as {@link reduce}, {@link size}, {@link head},
+ *   {@link findFirst}, and `Array.from` pull values from an iterator.
+ * - Constructors such as {@link range}, {@link makeBy}, {@link repeat},
+ *   {@link forever}, and {@link unfold} can represent unbounded sequences.
+ *
+ * **Common tasks**
+ *
+ * - Create sequences: {@link empty}, {@link of}, {@link range}, {@link makeBy},
+ *   {@link replicate}, {@link unfold}
+ * - Transform values: {@link map}, {@link flatMap}, {@link flatten},
+ *   {@link filter}, {@link filterMap}
+ * - Slice and search: {@link take}, {@link drop}, {@link takeWhile},
+ *   {@link findFirst}, {@link findLast}, {@link contains}
+ * - Combine and group: {@link appendAll}, {@link zipWith}, {@link chunksOf},
+ *   {@link groupBy}, {@link cartesian}
+ * - Fold or collect: {@link reduce}, {@link scan}, {@link countBy},
+ *   `Array.from`
  *
- * Iterables are objects that implement the iterator protocol, allowing them to be
- * consumed with `for...of` loops, spread syntax, and other iteration constructs.
- * This module provides a comprehensive set of functions for creating, transforming,
- * and working with iterables in a functional programming style.
+ * **Gotchas**
  *
- * Unlike arrays, iterables can be lazy and potentially infinite, making them suitable
- * for stream processing and memory-efficient data manipulation. All functions in this
- * module preserve the lazy nature of iterables where possible.
+ * - Laziness depends on the operation. Functions such as {@link size} and
+ *   {@link reduce} consume the iterable immediately.
+ * - Some JavaScript iterables are single-use iterators. Reusing the same value
+ *   after it has been consumed may produce no elements.
+ * - Unbounded iterables must be limited before full collection, for example
+ *   with {@link take}.
  *
- * **Example** (Working with iterables)
+ * **Example** (Building a lazy pipeline)
  *
  * ```ts
- * import { Iterable, Option } from "effect"
- *
- * // Create iterables
- * const numbers = Iterable.range(1, 5)
- * const doubled = Iterable.map(numbers, (x) => x * 2)
- * const filtered = Iterable.filter(doubled, (x) => x > 5)
+ * import { Iterable } from "effect"
  *
- * console.log(Array.from(filtered)) // [6, 8, 10]
+ * const naturals = Iterable.range(1)
+ * const squares = Iterable.map(naturals, (n) => n * n)
+ * const evenSquares = Iterable.filter(squares, (n) => n % 2 === 0)
+ * const firstFive = Iterable.take(evenSquares, 5)
  *
- * // Infinite iterables
- * const fibonacci = Iterable.unfold([0, 1], ([a, b]) => Option.some([a, [b, a + b]]))
- * const first10 = Iterable.take(fibonacci, 10)
- * console.log(Array.from(first10)) // [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
+ * console.log(Array.from(firstFive))
+ * // [4, 16, 36, 64, 100]
  * ```
  *
  * @since 2.0.0
@@ -92,7 +115,7 @@ export declare const makeBy: <A>(f: (i: number) => A, options?: {
  */
 export declare const range: (start: number, end?: number) => Iterable<number>;
 /**
- * Return a `Iterable` containing a value repeated the specified number of times.
+ * Returns a `Iterable` containing a value repeated the specified number of times.
  *
  * **Details**
  *
@@ -112,7 +135,7 @@ export declare const range: (start: number, end?: number) => Iterable<number>;
  */
 export declare const replicate: {
     /**
-     * Return a `Iterable` containing a value repeated the specified number of times.
+     * Returns a `Iterable` containing a value repeated the specified number of times.
      *
      * **Details**
      *
@@ -132,7 +155,7 @@ export declare const replicate: {
      */
     (n: number): <A>(a: A) => Iterable<A>;
     /**
-     * Return a `Iterable` containing a value repeated the specified number of times.
+     * Returns a `Iterable` containing a value repeated the specified number of times.
      *
      * **Details**
      *
@@ -156,10 +179,16 @@ export declare const replicate: {
  * Repeats an iterable `n` times, yielding the full contents of `self` for each
  * repetition.
  *
+ * **When to use**
+ *
+ * Use to repeat an iterable's contents a specific number of times.
+ *
  * **Details**
  *
  * The result is lazy. Each repetition obtains a new iterator from `self`.
  *
+ * @see {@link forever} for repeating without an upper bound
+ * @see {@link replicate} for repeating a single value
  * @category constructors
  * @since 4.0.0
  */
@@ -168,10 +197,16 @@ export declare const repeat: {
      * Repeats an iterable `n` times, yielding the full contents of `self` for each
      * repetition.
      *
+     * **When to use**
+     *
+     * Use to repeat an iterable's contents a specific number of times.
+     *
      * **Details**
      *
      * The result is lazy. Each repetition obtains a new iterator from `self`.
      *
+     * @see {@link forever} for repeating without an upper bound
+     * @see {@link replicate} for repeating a single value
      * @category constructors
      * @since 4.0.0
      */
@@ -180,10 +215,16 @@ export declare const repeat: {
      * Repeats an iterable `n` times, yielding the full contents of `self` for each
      * repetition.
      *
+     * **When to use**
+     *
+     * Use to repeat an iterable's contents a specific number of times.
+     *
      * **Details**
      *
      * The result is lazy. Each repetition obtains a new iterator from `self`.
      *
+     * @see {@link forever} for repeating without an upper bound
+     * @see {@link replicate} for repeating a single value
      * @category constructors
      * @since 4.0.0
      */
@@ -192,11 +233,19 @@ export declare const repeat: {
 /**
  * Repeats an iterable without an upper bound.
  *
+ * **When to use**
+ *
+ * Use to cycle a reusable iterable without an upper bound when a downstream
+ * consumer controls how many values are taken.
+ *
  * **Gotchas**
  *
  * The returned iterable is lazy and should usually be bounded with `take` or
  * another terminating consumer before materializing it.
  *
+ * @see {@link repeat} for repeating an iterable a specific number of times
+ * @see {@link take} for bounding the unbounded result before materializing it
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -222,7 +271,7 @@ export declare const forever: <A>(self: Iterable<A>) => Iterable<A>;
  */
 export declare const fromRecord: <K extends string, A>(self: Readonly<Record<K, A>>) => Iterable<[K, A]>;
 /**
- * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
+ * Prepends an element to the front of an `Iterable`, creating a new `Iterable`.
  *
  * **Example** (Prepending an element)
  *
@@ -244,7 +293,7 @@ export declare const fromRecord: <K extends string, A>(self: Readonly<Record<K,
  */
 export declare const prepend: {
     /**
-     * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
+     * Prepends an element to the front of an `Iterable`, creating a new `Iterable`.
      *
      * **Example** (Prepending an element)
      *
@@ -266,7 +315,7 @@ export declare const prepend: {
      */
     <B>(head: B): <A>(self: Iterable<A>) => Iterable<A | B>;
     /**
-     * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
+     * Prepends an element to the front of an `Iterable`, creating a new `Iterable`.
      *
      * **Example** (Prepending an element)
      *
@@ -347,7 +396,22 @@ export declare const prependAll: {
     <A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<A | B>;
 };
 /**
- * Append an element to the end of an `Iterable`, creating a new `Iterable`.
+ * Appends an element to the end of an `Iterable`, creating a new `Iterable`.
+ *
+ * **When to use**
+ *
+ * Use to add one element after all elements of an iterable while keeping the
+ * result as a lazy `Iterable`.
+ *
+ * **Details**
+ *
+ * The result yields every element from `self` first, then yields `last` after
+ * `self` is exhausted.
+ *
+ * **Gotchas**
+ *
+ * If `self` is infinite or never completes, the appended element is never
+ * reached.
  *
  * **Example** (Appending an element)
  *
@@ -366,12 +430,30 @@ export declare const prependAll: {
  * console.log(Array.from(result)) // [1, 2, 3, 4]
  * ```
  *
+ * @see {@link prepend} for adding one element before the existing elements
+ * @see {@link appendAll} for appending all elements from another iterable
+ *
  * @category concatenating
  * @since 2.0.0
  */
 export declare const append: {
     /**
-     * Append an element to the end of an `Iterable`, creating a new `Iterable`.
+     * Appends an element to the end of an `Iterable`, creating a new `Iterable`.
+     *
+     * **When to use**
+     *
+     * Use to add one element after all elements of an iterable while keeping the
+     * result as a lazy `Iterable`.
+     *
+     * **Details**
+     *
+     * The result yields every element from `self` first, then yields `last` after
+     * `self` is exhausted.
+     *
+     * **Gotchas**
+     *
+     * If `self` is infinite or never completes, the appended element is never
+     * reached.
      *
      * **Example** (Appending an element)
      *
@@ -390,12 +472,30 @@ export declare const append: {
      * console.log(Array.from(result)) // [1, 2, 3, 4]
      * ```
      *
+     * @see {@link prepend} for adding one element before the existing elements
+     * @see {@link appendAll} for appending all elements from another iterable
+     *
      * @category concatenating
      * @since 2.0.0
      */
     <B>(last: B): <A>(self: Iterable<A>) => Iterable<A | B>;
     /**
-     * Append an element to the end of an `Iterable`, creating a new `Iterable`.
+     * Appends an element to the end of an `Iterable`, creating a new `Iterable`.
+     *
+     * **When to use**
+     *
+     * Use to add one element after all elements of an iterable while keeping the
+     * result as a lazy `Iterable`.
+     *
+     * **Details**
+     *
+     * The result yields every element from `self` first, then yields `last` after
+     * `self` is exhausted.
+     *
+     * **Gotchas**
+     *
+     * If `self` is infinite or never completes, the appended element is never
+     * reached.
      *
      * **Example** (Appending an element)
      *
@@ -414,6 +514,9 @@ export declare const append: {
      * console.log(Array.from(result)) // [1, 2, 3, 4]
      * ```
      *
+     * @see {@link prepend} for adding one element before the existing elements
+     * @see {@link appendAll} for appending all elements from another iterable
+     *
      * @category concatenating
      * @since 2.0.0
      */
@@ -422,6 +525,20 @@ export declare const append: {
 /**
  * Concatenates two iterables, combining their elements.
  *
+ * **When to use**
+ *
+ * Use to lazily concatenate two iterables while preserving order, yielding all
+ * elements from `self` before `that`.
+ *
+ * **Details**
+ *
+ * The result is lazy. The iterator for `that` is not created or read until
+ * `self` is exhausted.
+ *
+ * **Gotchas**
+ *
+ * If `self` is infinite or never completes, `that` is never reached.
+ *
  * **Example** (Concatenating iterables)
  *
  * ```ts
@@ -445,6 +562,9 @@ export declare const append: {
  * console.log(Array.from(result)) // [0, -1, -2, 1, 2]
  * ```
  *
+ * @see {@link append} for appending one value instead of another iterable
+ * @see {@link prependAll} for yielding another iterable before `self`
+ *
  * @category concatenating
  * @since 2.0.0
  */
@@ -452,6 +572,20 @@ export declare const appendAll: {
     /**
      * Concatenates two iterables, combining their elements.
      *
+     * **When to use**
+     *
+     * Use to lazily concatenate two iterables while preserving order, yielding all
+     * elements from `self` before `that`.
+     *
+     * **Details**
+     *
+     * The result is lazy. The iterator for `that` is not created or read until
+     * `self` is exhausted.
+     *
+     * **Gotchas**
+     *
+     * If `self` is infinite or never completes, `that` is never reached.
+     *
      * **Example** (Concatenating iterables)
      *
      * ```ts
@@ -475,6 +609,9 @@ export declare const appendAll: {
      * console.log(Array.from(result)) // [0, -1, -2, 1, 2]
      * ```
      *
+     * @see {@link append} for appending one value instead of another iterable
+     * @see {@link prependAll} for yielding another iterable before `self`
+     *
      * @category concatenating
      * @since 2.0.0
      */
@@ -482,6 +619,20 @@ export declare const appendAll: {
     /**
      * Concatenates two iterables, combining their elements.
      *
+     * **When to use**
+     *
+     * Use to lazily concatenate two iterables while preserving order, yielding all
+     * elements from `self` before `that`.
+     *
+     * **Details**
+     *
+     * The result is lazy. The iterator for `that` is not created or read until
+     * `self` is exhausted.
+     *
+     * **Gotchas**
+     *
+     * If `self` is infinite or never completes, `that` is never reached.
+     *
      * **Example** (Concatenating iterables)
      *
      * ```ts
@@ -505,13 +656,16 @@ export declare const appendAll: {
      * console.log(Array.from(result)) // [0, -1, -2, 1, 2]
      * ```
      *
+     * @see {@link append} for appending one value instead of another iterable
+     * @see {@link prependAll} for yielding another iterable before `self`
+     *
      * @category concatenating
      * @since 2.0.0
      */
     <A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<A | B>;
 };
 /**
- * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
+ * Reduces an `Iterable` from the left, keeping all intermediate results instead of only the final result.
  *
  * **Example** (Tracking running results)
  *
@@ -539,7 +693,7 @@ export declare const appendAll: {
  */
 export declare const scan: {
     /**
-     * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
+     * Reduces an `Iterable` from the left, keeping all intermediate results instead of only the final result.
      *
      * **Example** (Tracking running results)
      *
@@ -567,7 +721,7 @@ export declare const scan: {
      */
     <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => Iterable<B>;
     /**
-     * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
+     * Reduces an `Iterable` from the left, keeping all intermediate results instead of only the final result.
      *
      * **Example** (Tracking running results)
      *
@@ -596,7 +750,7 @@ export declare const scan: {
     <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): Iterable<B>;
 };
 /**
- * Determine if an `Iterable` is empty
+ * Checks whether an `Iterable` is empty.
  *
  * **Example** (Checking for emptiness)
  *
@@ -613,7 +767,7 @@ export declare const scan: {
  */
 export declare const isEmpty: <A>(self: Iterable<A>) => self is Iterable<never>;
 /**
- * Return the number of elements in a `Iterable`.
+ * Returns the number of elements in a `Iterable`.
  *
  * **Example** (Counting iterable elements)
  *
@@ -640,7 +794,7 @@ export declare const isEmpty: <A>(self: Iterable<A>) => self is Iterable<never>;
  */
 export declare const size: <A>(self: Iterable<A>) => number;
 /**
- * Get the first element of a `Iterable`, or `None` if the `Iterable` is empty.
+ * Gets the first element of a `Iterable` safely, or `None` if the `Iterable` is empty.
  *
  * **Example** (Getting the first element)
  *
@@ -669,7 +823,7 @@ export declare const size: <A>(self: Iterable<A>) => number;
  */
 export declare const head: <A>(self: Iterable<A>) => Option<A>;
 /**
- * Get the first element of a `Iterable`, or throw an error if the `Iterable` is empty.
+ * Gets the first element of a `Iterable`, or throw an error if the `Iterable` is empty.
  *
  * **Example** (Getting the first element unsafely)
  *
@@ -695,7 +849,7 @@ export declare const head: <A>(self: Iterable<A>) => Option<A>;
  */
 export declare const headUnsafe: <A>(self: Iterable<A>) => A;
 /**
- * Keep only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
+ * Keeps only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
  *
  * **Details**
  *
@@ -729,7 +883,7 @@ export declare const headUnsafe: <A>(self: Iterable<A>) => A;
  */
 export declare const take: {
     /**
-     * Keep only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
+     * Keeps only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
      *
      * **Details**
      *
@@ -763,7 +917,7 @@ export declare const take: {
      */
     (n: number): <A>(self: Iterable<A>) => Iterable<A>;
     /**
-     * Keep only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
+     * Keeps only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
      *
      * **Details**
      *
@@ -798,7 +952,8 @@ export declare const take: {
     <A>(self: Iterable<A>, n: number): Iterable<A>;
 };
 /**
- * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
+ * Takes the longest initial `Iterable` prefix for which all elements satisfy the
+ * specified predicate.
  *
  * **Example** (Taking while a predicate holds)
  *
@@ -833,7 +988,8 @@ export declare const take: {
  */
 export declare const takeWhile: {
     /**
-     * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
+     * Takes the longest initial `Iterable` prefix for which all elements satisfy the
+     * specified predicate.
      *
      * **Example** (Taking while a predicate holds)
      *
@@ -868,7 +1024,8 @@ export declare const takeWhile: {
      */
     <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Iterable<B>;
     /**
-     * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
+     * Takes the longest initial `Iterable` prefix for which all elements satisfy the
+     * specified predicate.
      *
      * **Example** (Taking while a predicate holds)
      *
@@ -903,7 +1060,8 @@ export declare const takeWhile: {
      */
     <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Iterable<A>;
     /**
-     * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
+     * Takes the longest initial `Iterable` prefix for which all elements satisfy the
+     * specified predicate.
      *
      * **Example** (Taking while a predicate holds)
      *
@@ -938,7 +1096,8 @@ export declare const takeWhile: {
      */
     <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Iterable<B>;
     /**
-     * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
+     * Takes the longest initial `Iterable` prefix for which all elements satisfy the
+     * specified predicate.
      *
      * **Example** (Taking while a predicate holds)
      *
@@ -974,7 +1133,7 @@ export declare const takeWhile: {
     <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Iterable<A>;
 };
 /**
- * Drop a max number of elements from the start of an `Iterable`
+ * Drops a max number of elements from the start of an `Iterable`
  *
  * **Details**
  *
@@ -1007,7 +1166,7 @@ export declare const takeWhile: {
  */
 export declare const drop: {
     /**
-     * Drop a max number of elements from the start of an `Iterable`
+     * Drops a max number of elements from the start of an `Iterable`
      *
      * **Details**
      *
@@ -1040,7 +1199,7 @@ export declare const drop: {
      */
     (n: number): <A>(self: Iterable<A>) => Iterable<A>;
     /**
-     * Drop a max number of elements from the start of an `Iterable`
+     * Drops a max number of elements from the start of an `Iterable`
      *
      * **Details**
      *
@@ -1362,7 +1521,7 @@ export declare const findFirst: {
     <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option<A>;
 };
 /**
- * Find the last element for which a predicate holds.
+ * Finds the last element for which a predicate holds.
  *
  * **Example** (Finding the last match)
  *
@@ -1395,7 +1554,7 @@ export declare const findFirst: {
  */
 export declare const findLast: {
     /**
-     * Find the last element for which a predicate holds.
+     * Finds the last element for which a predicate holds.
      *
      * **Example** (Finding the last match)
      *
@@ -1428,7 +1587,7 @@ export declare const findLast: {
      */
     <A, B>(f: (a: NoInfer<A>, i: number) => Option<B>): (self: Iterable<A>) => Option<B>;
     /**
-     * Find the last element for which a predicate holds.
+     * Finds the last element for which a predicate holds.
      *
      * **Example** (Finding the last match)
      *
@@ -1461,7 +1620,7 @@ export declare const findLast: {
      */
     <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Option<B>;
     /**
-     * Find the last element for which a predicate holds.
+     * Finds the last element for which a predicate holds.
      *
      * **Example** (Finding the last match)
      *
@@ -1494,7 +1653,7 @@ export declare const findLast: {
      */
     <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option<A>;
     /**
-     * Find the last element for which a predicate holds.
+     * Finds the last element for which a predicate holds.
      *
      * **Example** (Finding the last match)
      *
@@ -1527,7 +1686,7 @@ export declare const findLast: {
      */
     <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Option<B>;
     /**
-     * Find the last element for which a predicate holds.
+     * Finds the last element for which a predicate holds.
      *
      * **Example** (Finding the last match)
      *
@@ -1560,7 +1719,7 @@ export declare const findLast: {
      */
     <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Option<B>;
     /**
-     * Find the last element for which a predicate holds.
+     * Finds the last element for which a predicate holds.
      *
      * **Example** (Finding the last match)
      *
@@ -1703,7 +1862,7 @@ export declare const zip: {
     <A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<[A, B]>;
 };
 /**
- * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
+ * Applies a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
  * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
  *
  * **Example** (Zipping with a combining function)
@@ -1751,7 +1910,7 @@ export declare const zip: {
  */
 export declare const zipWith: {
     /**
-     * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
+     * Applies a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
      * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
      *
      * **Example** (Zipping with a combining function)
@@ -1799,7 +1958,7 @@ export declare const zipWith: {
      */
     <B, A, C>(that: Iterable<B>, f: (a: A, b: B) => C): (self: Iterable<A>) => Iterable<C>;
     /**
-     * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
+     * Applies a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
      * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
      *
      * **Example** (Zipping with a combining function)
@@ -1848,7 +2007,14 @@ export declare const zipWith: {
     <A, B, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): Iterable<C>;
 };
 /**
- * Places an element in between members of an `Iterable`.
+ * Places a separator between members of an `Iterable`.
+ *
+ * **When to use**
+ *
+ * Use to lazily insert a separator between adjacent values.
+ *
+ * **Details**
+ *
  * If the input is a non-empty array, the result is also a non-empty array.
  *
  * **Example** (Interspersing separators)
@@ -1887,7 +2053,14 @@ export declare const zipWith: {
  */
 export declare const intersperse: {
     /**
-     * Places an element in between members of an `Iterable`.
+     * Places a separator between members of an `Iterable`.
+     *
+     * **When to use**
+     *
+     * Use to lazily insert a separator between adjacent values.
+     *
+     * **Details**
+     *
      * If the input is a non-empty array, the result is also a non-empty array.
      *
      * **Example** (Interspersing separators)
@@ -1926,7 +2099,14 @@ export declare const intersperse: {
      */
     <B>(middle: B): <A>(self: Iterable<A>) => Iterable<A | B>;
     /**
-     * Places an element in between members of an `Iterable`.
+     * Places a separator between members of an `Iterable`.
+     *
+     * **When to use**
+     *
+     * Use to lazily insert a separator between adjacent values.
+     *
+     * **Details**
+     *
      * If the input is a non-empty array, the result is also a non-empty array.
      *
      * **Example** (Interspersing separators)
@@ -2240,7 +2420,7 @@ export declare const chunksOf: {
     <A>(self: Iterable<A>, n: number): Iterable<Array<A>>;
 };
 /**
- * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
+ * Groups equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
  *
  * **Example** (Grouping consecutive elements with custom equivalence)
  *
@@ -2280,7 +2460,7 @@ export declare const chunksOf: {
  */
 export declare const groupWith: {
     /**
-     * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
+     * Groups equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
      *
      * **Example** (Grouping consecutive elements with custom equivalence)
      *
@@ -2320,7 +2500,7 @@ export declare const groupWith: {
      */
     <A>(isEquivalent: (self: A, that: A) => boolean): (self: Iterable<A>) => Iterable<NonEmptyArray<A>>;
     /**
-     * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
+     * Groups equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
      *
      * **Example** (Grouping consecutive elements with custom equivalence)
      *
@@ -2361,7 +2541,7 @@ export declare const groupWith: {
     <A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Iterable<NonEmptyArray<A>>;
 };
 /**
- * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s.
+ * Groups equal, consecutive elements of an `Iterable` into `NonEmptyArray`s.
  *
  * **Example** (Grouping consecutive elements)
  *
@@ -2553,7 +2733,7 @@ export declare const groupBy: {
  *
  * **When to use**
  *
- * Use this reusable empty iterable as a base case for operations or when you
+ * Use as a base case for operations or when you
  * need to represent "no data" in a type-safe way.
  *
  * **Example** (Creating an empty iterable)
@@ -2581,7 +2761,7 @@ export declare const empty: <A = never>() => Iterable<A>;
  *
  * **When to use**
  *
- * Use this to wrap a single value in an iterable context so it can be combined
+ * Use to wrap a single value in an iterable context so it can be combined
  * with other iterable operations.
  *
  * **Example** (Wrapping a single value)
@@ -3429,7 +3609,7 @@ export declare const filter: {
  *
  * **When to use**
  *
- * Use this when working with APIs or functions that return nullable values,
+ * Use when working with APIs or functions that return nullable values,
  * providing a clean way to filter out null or undefined while transforming.
  *
  * **Example** (FlatMapping nullable results)
@@ -3475,7 +3655,7 @@ export declare const flatMapNullishOr: {
      *
      * **When to use**
      *
-     * Use this when working with APIs or functions that return nullable values,
+     * Use when working with APIs or functions that return nullable values,
      * providing a clean way to filter out null or undefined while transforming.
      *
      * **Example** (FlatMapping nullable results)
@@ -3521,7 +3701,7 @@ export declare const flatMapNullishOr: {
      *
      * **When to use**
      *
-     * Use this when working with APIs or functions that return nullable values,
+     * Use when working with APIs or functions that return nullable values,
      * providing a clean way to filter out null or undefined while transforming.
      *
      * **Example** (FlatMapping nullable results)
@@ -3564,7 +3744,7 @@ export declare const flatMapNullishOr: {
     <A, B>(self: Iterable<A>, f: (a: A) => B): Iterable<NonNullable<B>>;
 };
 /**
- * Check if a predicate holds true for some `Iterable` element.
+ * Checks whether a predicate holds true for some `Iterable` element.
  *
  * **Example** (Checking whether some element matches)
  *
@@ -3606,7 +3786,7 @@ export declare const flatMapNullishOr: {
  */
 export declare const some: {
     /**
-     * Check if a predicate holds true for some `Iterable` element.
+     * Checks whether a predicate holds true for some `Iterable` element.
      *
      * **Example** (Checking whether some element matches)
      *
@@ -3648,7 +3828,7 @@ export declare const some: {
      */
     <A>(predicate: (a: A, i: number) => boolean): (self: Iterable<A>) => boolean;
     /**
-     * Check if a predicate holds true for some `Iterable` element.
+     * Checks whether a predicate holds true for some `Iterable` element.
      *
      * **Example** (Checking whether some element matches)
      *
@@ -3732,7 +3912,7 @@ export declare const some: {
  */
 export declare const unfold: <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>) => Iterable<A>;
 /**
- * Iterate over the `Iterable` applying `f`.
+ * Iterates over the `Iterable`, applying `f` to each element.
  *
  * **Example** (Iterating with side effects)
  *
@@ -3771,7 +3951,7 @@ export declare const unfold: <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>)
  */
 export declare const forEach: {
     /**
-     * Iterate over the `Iterable` applying `f`.
+     * Iterates over the `Iterable`, applying `f` to each element.
      *
      * **Example** (Iterating with side effects)
      *
@@ -3810,7 +3990,7 @@ export declare const forEach: {
      */
     <A>(f: (a: A, i: number) => void): (self: Iterable<A>) => void;
     /**
-     * Iterate over the `Iterable` applying `f`.
+     * Iterates over the `Iterable`, applying `f` to each element.
      *
      * **Example** (Iterating with side effects)
      *
@@ -3850,7 +4030,7 @@ export declare const forEach: {
     <A>(self: Iterable<A>, f: (a: A, i: number) => void): void;
 };
 /**
- * Reduce an iterable to a single value by applying a function to each element and accumulating the result.
+ * Reduces an iterable to a single value by applying a function to each element and accumulating the result.
  *
  * **Details**
  *
@@ -3902,7 +4082,7 @@ export declare const forEach: {
  */
 export declare const reduce: {
     /**
-     * Reduce an iterable to a single value by applying a function to each element and accumulating the result.
+     * Reduces an iterable to a single value by applying a function to each element and accumulating the result.
      *
      * **Details**
      *
@@ -3954,7 +4134,7 @@ export declare const reduce: {
      */
     <B, A>(b: B, f: (b: B, a: A, i: number) => B): (self: Iterable<A>) => B;
     /**
-     * Reduce an iterable to a single value by applying a function to each element and accumulating the result.
+     * Reduces an iterable to a single value by applying a function to each element and accumulating the result.
      *
      * **Details**
      *
@@ -4457,7 +4637,7 @@ export declare const cartesian: {
     <A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<[A, B]>;
 };
 /**
- * Counts all the element of the given iterable that pass the given predicate
+ * Computes how many elements of the iterable pass the given predicate.
  *
  * **Example** (Counting matching elements)
  *
@@ -4473,7 +4653,7 @@ export declare const cartesian: {
  */
 export declare const countBy: {
     /**
-     * Counts all the element of the given iterable that pass the given predicate
+     * Computes how many elements of the iterable pass the given predicate.
      *
      * **Example** (Counting matching elements)
      *
@@ -4489,7 +4669,7 @@ export declare const countBy: {
      */
     <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => number;
     /**
-     * Counts all the element of the given iterable that pass the given predicate
+     * Computes how many elements of the iterable pass the given predicate.
      *
      * **Example** (Counting matching elements)
      *