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

package/src/Iterable.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
@@ -124,7 +147,7 @@ export 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**
  *
@@ -144,7 +167,7 @@ export const range = (start: number, end?: number): Iterable<number> => {
  */
 export 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**
    *
@@ -164,7 +187,7 @@ export 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**
    *
@@ -189,10 +212,16 @@ export 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
  */
@@ -201,10 +230,16 @@ export 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
    */
@@ -213,10 +248,16 @@ export 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
    */
@@ -226,11 +267,19 @@ export 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
  */
@@ -266,7 +315,7 @@ export const fromRecord = <K extends string, A>(self: Readonly<Record<K, A>>): I
 })
 
 /**
- * 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)
  *
@@ -288,7 +337,7 @@ export const fromRecord = <K extends string, A>(self: Readonly<Record<K, A>>): I
  */
 export 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)
    *
@@ -310,7 +359,7 @@ export 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)
    *
@@ -396,7 +445,22 @@ export const prependAll: {
 )
 
 /**
- * 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)
  *
@@ -415,12 +479,30 @@ export 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 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)
    *
@@ -439,12 +521,30 @@ export 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)
    *
@@ -463,6 +563,9 @@ export 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
    */
@@ -472,6 +575,20 @@ export 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
@@ -495,6 +612,9 @@ export 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
  */
@@ -502,6 +622,20 @@ export 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
@@ -525,6 +659,9 @@ export 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
    */
@@ -532,6 +669,20 @@ export 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
@@ -555,6 +706,9 @@ export 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
    */
@@ -585,7 +739,7 @@ export const appendAll: {
 )
 
 /**
- * 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)
  *
@@ -613,7 +767,7 @@ export const appendAll: {
  */
 export 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)
    *
@@ -641,7 +795,7 @@ export 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)
    *
@@ -689,7 +843,7 @@ export const scan: {
 }))
 
 /**
- * Determine if an `Iterable` is empty
+ * Checks whether an `Iterable` is empty.
  *
  * **Example** (Checking for emptiness)
  *
@@ -710,7 +864,7 @@ export 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)
  *
@@ -745,7 +899,7 @@ export 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)
  *
@@ -779,7 +933,7 @@ export 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)
  *
@@ -811,7 +965,7 @@ export 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**
  *
@@ -845,7 +999,7 @@ export const headUnsafe = <A>(self: Iterable<A>): A => {
  */
 export 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**
    *
@@ -879,7 +1033,7 @@ export 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**
    *
@@ -929,7 +1083,8 @@ export const take: {
 }))
 
 /**
- * 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)
  *
@@ -964,7 +1119,8 @@ export const take: {
  */
 export 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)
    *
@@ -999,7 +1155,8 @@ export 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)
    *
@@ -1034,7 +1191,8 @@ export 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)
    *
@@ -1069,7 +1227,8 @@ export 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)
    *
@@ -1120,7 +1279,7 @@ export const takeWhile: {
 }))
 
 /**
- * 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**
  *
@@ -1153,7 +1312,7 @@ export const takeWhile: {
  */
 export 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**
    *
@@ -1186,7 +1345,7 @@ export 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**
    *
@@ -1546,7 +1705,7 @@ export const findFirst: {
 )
 
 /**
- * Find the last element for which a predicate holds.
+ * Finds the last element for which a predicate holds.
  *
  * **Example** (Finding the last match)
  *
@@ -1579,7 +1738,7 @@ export const findFirst: {
  */
 export 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)
    *
@@ -1612,7 +1771,7 @@ export 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)
    *
@@ -1645,7 +1804,7 @@ export 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)
    *
@@ -1678,7 +1837,7 @@ export 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)
    *
@@ -1711,7 +1870,7 @@ export 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)
    *
@@ -1744,7 +1903,7 @@ export 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)
    *
@@ -1912,7 +2071,7 @@ export const zip: {
 )
 
 /**
- * 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)
@@ -1960,7 +2119,7 @@ export const zip: {
  */
 export 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)
@@ -2008,7 +2167,7 @@ export 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)
@@ -2073,7 +2232,14 @@ export const zipWith: {
 }))
 
 /**
- * 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)
@@ -2112,7 +2278,14 @@ export const zipWith: {
  */
 export 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)
@@ -2151,7 +2324,14 @@ export 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)
@@ -2523,7 +2703,7 @@ export const chunksOf: {
 })
 
 /**
- * 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)
  *
@@ -2563,7 +2743,7 @@ export const chunksOf: {
  */
 export 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)
    *
@@ -2603,7 +2783,7 @@ export 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)
    *
@@ -2680,7 +2860,7 @@ export const groupWith: {
 )
 
 /**
- * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s.
+ * Groups equal, consecutive elements of an `Iterable` into `NonEmptyArray`s.
  *
  * **Example** (Grouping consecutive elements)
  *
@@ -2901,7 +3081,7 @@ const constEmptyIterator: Iterator<never> = {
  *
  * **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)
@@ -2930,7 +3110,7 @@ export const empty = <A = never>(): Iterable<A> => constEmpty
  *
  * **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)
@@ -3939,7 +4119,7 @@ export 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)
@@ -3985,7 +4165,7 @@ export 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)
@@ -4031,7 +4211,7 @@ export 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)
@@ -4082,7 +4262,7 @@ export const flatMapNullishOr: {
 )
 
 /**
- * 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)
  *
@@ -4124,7 +4304,7 @@ export const flatMapNullishOr: {
  */
 export 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)
    *
@@ -4166,7 +4346,7 @@ export 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)
    *
@@ -4278,7 +4458,7 @@ export const unfold = <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>): Iterab
 })
 
 /**
- * Iterate over the `Iterable` applying `f`.
+ * Iterates over the `Iterable`, applying `f` to each element.
  *
  * **Example** (Iterating with side effects)
  *
@@ -4317,7 +4497,7 @@ export const unfold = <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>): Iterab
  */
 export const forEach: {
   /**
-   * Iterate over the `Iterable` applying `f`.
+   * Iterates over the `Iterable`, applying `f` to each element.
    *
    * **Example** (Iterating with side effects)
    *
@@ -4356,7 +4536,7 @@ export 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)
    *
@@ -4402,7 +4582,7 @@ export const forEach: {
 })
 
 /**
- * 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**
  *
@@ -4454,7 +4634,7 @@ export const forEach: {
  */
 export 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**
    *
@@ -4506,7 +4686,7 @@ export 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**
    *
@@ -5055,7 +5235,7 @@ export const cartesian: {
 )
 
 /**
- * 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)
  *
@@ -5071,7 +5251,7 @@ export const cartesian: {
  */
 export 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)
    *
@@ -5087,7 +5267,7 @@ export 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)
    *