effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/Iterable.ts

@@ -10,7 +10,8 @@
  * for stream processing and memory-efficient data manipulation. All functions in this
  * module preserve the lazy nature of iterables where possible.
  *
- * @example
+ * **Example** (Working with iterables)
+ *
  * ```ts
  * import { Iterable, Option } from "effect"
  *
@@ -52,7 +53,8 @@ import type { NoInfer } from "./Types.ts"
  * @param f - Function that receives the index and returns the element
  * @param options - Configuration object with optional length
  *
- * @example
+ * **Example** (Generating values by index)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -93,11 +95,14 @@ export const makeBy = <A>(f: (i: number) => A, options?: {
 }
 
 /**
- * Return a `Iterable` containing a range of integers, including both endpoints.
+ * Returns an iterable of integers starting at `start` and increasing by `1`.
+ *
+ * When `end` is provided and `start <= end`, both endpoints are included. When
+ * `end` is omitted, the iterable is unbounded. When `start > end`, the
+ * iterable contains only `start`.
  *
- * If `end` is omitted, the range will not have an upper bound.
+ * **Example** (Creating a range)
  *
- * @example
  * ```ts
  * import { range } from "effect/Iterable"
  * import * as assert from "node:assert"
@@ -122,7 +127,8 @@ export const range = (start: number, end?: number): Iterable<number> => {
  *
  * **Note**. `n` is normalized to an integer >= 1.
  *
- * @example
+ * **Example** (Repeating a value)
+ *
  * ```ts
  * import { replicate } from "effect/Iterable"
  * import * as assert from "node:assert"
@@ -139,7 +145,8 @@ export const replicate: {
    *
    * **Note**. `n` is normalized to an integer >= 1.
    *
-   * @example
+   * **Example** (Repeating a value)
+   *
    * ```ts
    * import { replicate } from "effect/Iterable"
    * import * as assert from "node:assert"
@@ -156,7 +163,8 @@ export const replicate: {
    *
    * **Note**. `n` is normalized to an integer >= 1.
    *
-   * @example
+   * **Example** (Repeating a value)
+   *
    * ```ts
    * import { replicate } from "effect/Iterable"
    * import * as assert from "node:assert"
@@ -171,16 +179,31 @@ export const replicate: {
 } = dual(2, <A>(a: A, n: number): Iterable<A> => makeBy(() => a, { length: n }))
 
 /**
+ * Repeats an iterable `n` times, yielding the full contents of `self` for each
+ * repetition.
+ *
+ * The result is lazy. Each repetition obtains a new iterator from `self`.
+ *
  * @category constructors
  * @since 4.0.0
  */
 export const repeat: {
   /**
+   * Repeats an iterable `n` times, yielding the full contents of `self` for each
+   * repetition.
+   *
+   * The result is lazy. Each repetition obtains a new iterator from `self`.
+   *
    * @category constructors
    * @since 4.0.0
    */
   (n: number): <A>(self: Iterable<A>) => Iterable<A>
   /**
+   * Repeats an iterable `n` times, yielding the full contents of `self` for each
+   * repetition.
+   *
+   * The result is lazy. Each repetition obtains a new iterator from `self`.
+   *
    * @category constructors
    * @since 4.0.0
    */
@@ -188,6 +211,11 @@ export const repeat: {
 } = dual(2, <A>(self: Iterable<A>, n: number): Iterable<A> => flatten(makeBy(() => self, { length: n })))
 
 /**
+ * Repeats an iterable without an upper bound.
+ *
+ * The returned iterable is lazy and should usually be bounded with `take` or
+ * another terminating consumer before materializing it.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -196,7 +224,8 @@ export const forever = <A>(self: Iterable<A>): Iterable<A> => repeat(self, Infin
 /**
  * Takes a record and returns an Iterable of tuples containing its keys and values.
  *
- * @example
+ * **Example** (Converting a record to entries)
+ *
  * ```ts
  * import { fromRecord } from "effect/Iterable"
  * import * as assert from "node:assert"
@@ -224,7 +253,8 @@ 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`.
  *
- * @example
+ * **Example** (Prepending an element)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -245,7 +275,8 @@ export const prepend: {
   /**
    * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
    *
-   * @example
+   * **Example** (Prepending an element)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -266,7 +297,8 @@ export const prepend: {
   /**
    * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
    *
-   * @example
+   * **Example** (Prepending an element)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -289,7 +321,8 @@ export const prepend: {
 /**
  * Prepends the specified prefix iterable to the beginning of the specified iterable.
  *
- * @example
+ * **Example** (Prepending another iterable)
+ *
  * ```ts
  * import { Iterable } from "effect"
  * import * as assert from "node:assert"
@@ -307,7 +340,8 @@ export const prependAll: {
   /**
    * Prepends the specified prefix iterable to the beginning of the specified iterable.
    *
-   * @example
+   * **Example** (Prepending another iterable)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as assert from "node:assert"
@@ -325,7 +359,8 @@ export const prependAll: {
   /**
    * Prepends the specified prefix iterable to the beginning of the specified iterable.
    *
-   * @example
+   * **Example** (Prepending another iterable)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as assert from "node:assert"
@@ -348,7 +383,8 @@ export const prependAll: {
 /**
  * Append an element to the end of an `Iterable`, creating a new `Iterable`.
  *
- * @example
+ * **Example** (Appending an element)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -371,7 +407,8 @@ export const append: {
   /**
    * Append an element to the end of an `Iterable`, creating a new `Iterable`.
    *
-   * @example
+   * **Example** (Appending an element)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -394,7 +431,8 @@ export const append: {
   /**
    * Append an element to the end of an `Iterable`, creating a new `Iterable`.
    *
-   * @example
+   * **Example** (Appending an element)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -419,7 +457,8 @@ export const append: {
 /**
  * Concatenates two iterables, combining their elements.
  *
- * @example
+ * **Example** (Concatenating iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -448,7 +487,8 @@ export const appendAll: {
   /**
    * Concatenates two iterables, combining their elements.
    *
-   * @example
+   * **Example** (Concatenating iterables)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -477,7 +517,8 @@ export const appendAll: {
   /**
    * Concatenates two iterables, combining their elements.
    *
-   * @example
+   * **Example** (Concatenating iterables)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -531,7 +572,8 @@ export const appendAll: {
 /**
  * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
  *
- * @example
+ * **Example** (Tracking running results)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -558,7 +600,8 @@ export const scan: {
   /**
    * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
    *
-   * @example
+   * **Example** (Tracking running results)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -585,7 +628,8 @@ export const scan: {
   /**
    * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
    *
-   * @example
+   * **Example** (Tracking running results)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -632,7 +676,8 @@ export const scan: {
 /**
  * Determine if an `Iterable` is empty
  *
- * @example
+ * **Example** (Checking for emptiness)
+ *
  * ```ts
  * import { isEmpty } from "effect/Iterable"
  * import * as assert from "node:assert"
@@ -652,7 +697,8 @@ export const isEmpty = <A>(self: Iterable<A>): self is Iterable<never> => {
 /**
  * Return the number of elements in a `Iterable`.
  *
- * @example
+ * **Example** (Counting iterable elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -686,7 +732,8 @@ export const size = <A>(self: Iterable<A>): number => {
 /**
  * Get the first element of a `Iterable`, or `None` if the `Iterable` is empty.
  *
- * @example
+ * **Example** (Getting the first element)
+ *
  * ```ts
  * import { Iterable } from "effect"
  * import * as Option from "effect/Option"
@@ -720,7 +767,8 @@ 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.
  *
- * @example
+ * **Example** (Getting the first element unsafely)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -730,13 +778,8 @@ export const head = <A>(self: Iterable<A>): Option<A> => {
  * const letters = "hello"
  * console.log(Iterable.headUnsafe(letters)) // "h"
  *
- * // This will throw an error!
- * try {
- *   const empty = Iterable.empty<number>()
- *   Iterable.headUnsafe(empty) // throws Error: "headUnsafe: empty iterable"
- * } catch (error) {
- *   console.log((error as Error).message) // "headUnsafe: empty iterable"
- * }
+ * // Iterable.headUnsafe(Iterable.empty<number>())
+ * // throws Error: "headUnsafe: empty iterable"
  *
  * // Use only when you're certain the iterable is non-empty
  * const nonEmpty = Iterable.range(1, 10)
@@ -758,7 +801,8 @@ export const headUnsafe = <A>(self: Iterable<A>): A => {
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
- * @example
+ * **Example** (Taking from the start)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -789,7 +833,8 @@ export const take: {
    *
    * **Note**. `n` is normalized to a non negative integer.
    *
-   * @example
+   * **Example** (Taking from the start)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -820,7 +865,8 @@ export const take: {
    *
    * **Note**. `n` is normalized to a non negative integer.
    *
-   * @example
+   * **Example** (Taking from the start)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -865,7 +911,8 @@ export const take: {
 /**
  * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
  *
- * @example
+ * **Example** (Taking while a predicate holds)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -899,7 +946,8 @@ export const takeWhile: {
   /**
    * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
    *
-   * @example
+   * **Example** (Taking while a predicate holds)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -933,7 +981,8 @@ export const takeWhile: {
   /**
    * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
    *
-   * @example
+   * **Example** (Taking while a predicate holds)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -967,7 +1016,8 @@ export const takeWhile: {
   /**
    * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
    *
-   * @example
+   * **Example** (Taking while a predicate holds)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1001,7 +1051,8 @@ export const takeWhile: {
   /**
    * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
    *
-   * @example
+   * **Example** (Taking while a predicate holds)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1053,7 +1104,8 @@ export const takeWhile: {
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
- * @example
+ * **Example** (Dropping from the start)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1083,7 +1135,8 @@ export const drop: {
    *
    * **Note**. `n` is normalized to a non negative integer.
    *
-   * @example
+   * **Example** (Dropping from the start)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1113,7 +1166,8 @@ export const drop: {
    *
    * **Note**. `n` is normalized to a non negative integer.
    *
-   * @example
+   * **Example** (Dropping from the start)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1161,7 +1215,8 @@ export const drop: {
  * Returns the first element that satisfies the specified
  * predicate, or `None` if no such element exists.
  *
- * @example
+ * **Example** (Finding the first match)
+ *
  * ```ts
  * import { Iterable } from "effect"
  * import * as Option from "effect/Option"
@@ -1202,7 +1257,8 @@ export const findFirst: {
    * Returns the first element that satisfies the specified
    * predicate, or `None` if no such element exists.
    *
-   * @example
+   * **Example** (Finding the first match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as Option from "effect/Option"
@@ -1243,7 +1299,8 @@ export const findFirst: {
    * Returns the first element that satisfies the specified
    * predicate, or `None` if no such element exists.
    *
-   * @example
+   * **Example** (Finding the first match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as Option from "effect/Option"
@@ -1284,7 +1341,8 @@ export const findFirst: {
    * Returns the first element that satisfies the specified
    * predicate, or `None` if no such element exists.
    *
-   * @example
+   * **Example** (Finding the first match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as Option from "effect/Option"
@@ -1325,7 +1383,8 @@ export const findFirst: {
    * Returns the first element that satisfies the specified
    * predicate, or `None` if no such element exists.
    *
-   * @example
+   * **Example** (Finding the first match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as Option from "effect/Option"
@@ -1366,7 +1425,8 @@ export const findFirst: {
    * Returns the first element that satisfies the specified
    * predicate, or `None` if no such element exists.
    *
-   * @example
+   * **Example** (Finding the first match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as Option from "effect/Option"
@@ -1407,7 +1467,8 @@ export const findFirst: {
    * Returns the first element that satisfies the specified
    * predicate, or `None` if no such element exists.
    *
-   * @example
+   * **Example** (Finding the first match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as Option from "effect/Option"
@@ -1468,7 +1529,8 @@ export const findFirst: {
 /**
  * Find the last element for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the last match)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1500,7 +1562,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1532,7 +1595,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1564,7 +1628,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1596,7 +1661,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1628,7 +1694,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1660,7 +1727,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1714,7 +1782,8 @@ export const findLast: {
 /**
  * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
  *
- * @example
+ * **Example** (Zipping iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1749,7 +1818,8 @@ export const zip: {
   /**
    * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
    *
-   * @example
+   * **Example** (Zipping iterables)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1784,7 +1854,8 @@ export const zip: {
   /**
    * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
    *
-   * @example
+   * **Example** (Zipping iterables)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1825,7 +1896,8 @@ export const zip: {
  * Apply 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
+ * **Example** (Zipping with a combining function)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1872,7 +1944,8 @@ export const zipWith: {
    * Apply 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
+   * **Example** (Zipping with a combining function)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1919,7 +1992,8 @@ export const zipWith: {
    * Apply 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
+   * **Example** (Zipping with a combining function)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1983,7 +2057,8 @@ export const zipWith: {
  * Places an element in between members of an `Iterable`.
  * If the input is a non-empty array, the result is also a non-empty array.
  *
- * @example
+ * **Example** (Interspersing separators)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2021,7 +2096,8 @@ export const intersperse: {
    * Places an element in between members of an `Iterable`.
    * If the input is a non-empty array, the result is also a non-empty array.
    *
-   * @example
+   * **Example** (Interspersing separators)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2059,7 +2135,8 @@ export const intersperse: {
    * Places an element in between members of an `Iterable`.
    * If the input is a non-empty array, the result is also a non-empty array.
    *
-   * @example
+   * **Example** (Interspersing separators)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2118,7 +2195,8 @@ export const intersperse: {
 /**
  * Returns a function that checks if an `Iterable` contains a given value using a provided `isEquivalent` function.
  *
- * @example
+ * **Example** (Checking membership with custom equivalence)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2165,9 +2243,14 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
   })
 
 /**
- * Returns a function that checks if a `Iterable` contains a given value using the default `Equivalence`.
+ * Checks whether an iterable contains a value using Effect's default `Equal`
+ * equivalence.
+ *
+ * Can be called as `contains(self, value)` or curried as
+ * `contains(value)(self)`.
+ *
+ * **Example** (Checking membership)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2195,9 +2278,14 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
  */
 export const contains: {
   /**
-   * Returns a function that checks if a `Iterable` contains a given value using the default `Equivalence`.
+   * Checks whether an iterable contains a value using Effect's default `Equal`
+   * equivalence.
+   *
+   * Can be called as `contains(self, value)` or curried as
+   * `contains(value)(self)`.
+   *
+   * **Example** (Checking membership)
    *
-   * @example
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2225,9 +2313,14 @@ export const contains: {
    */
   <A>(a: A): (self: Iterable<A>) => boolean
   /**
-   * Returns a function that checks if a `Iterable` contains a given value using the default `Equivalence`.
+   * Checks whether an iterable contains a value using Effect's default `Equal`
+   * equivalence.
+   *
+   * Can be called as `contains(self, value)` or curried as
+   * `contains(value)(self)`.
+   *
+   * **Example** (Checking membership)
    *
-   * @example
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2260,7 +2353,8 @@ export const contains: {
  * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
  * the `Iterable`.
  *
- * @example
+ * **Example** (Chunking an iterable)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2299,7 +2393,8 @@ export const chunksOf: {
    * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
    * the `Iterable`.
    *
-   * @example
+   * **Example** (Chunking an iterable)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2338,7 +2433,8 @@ export const chunksOf: {
    * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
    * the `Iterable`.
    *
-   * @example
+   * **Example** (Chunking an iterable)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2404,7 +2500,8 @@ export const chunksOf: {
 /**
  * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
  *
- * @example
+ * **Example** (Grouping consecutive elements with custom equivalence)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2443,7 +2540,8 @@ export const groupWith: {
   /**
    * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
    *
-   * @example
+   * **Example** (Grouping consecutive elements with custom equivalence)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2482,7 +2580,8 @@ export const groupWith: {
   /**
    * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
    *
-   * @example
+   * **Example** (Grouping consecutive elements with custom equivalence)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2558,7 +2657,8 @@ export const groupWith: {
 /**
  * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s.
  *
- * @example
+ * **Example** (Grouping consecutive elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2592,10 +2692,14 @@ export const group: <A>(self: Iterable<A>) => Iterable<NonEmptyArray<A>> = group
 )
 
 /**
- * Splits an `Iterable` into sub-non-empty-arrays stored in an object, based on the result of calling a `string`-returning
- * function on each element, and grouping the results according to values returned
+ * Groups all elements by the string or symbol key returned by `f`.
+ *
+ * Each property in the returned record contains a non-empty array of elements
+ * that produced that key. Unlike `group`, matching elements do not need to be
+ * consecutive.
+ *
+ * **Example** (Grouping by a key)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2637,10 +2741,14 @@ export const group: <A>(self: Iterable<A>) => Iterable<NonEmptyArray<A>> = group
  */
 export const groupBy: {
   /**
-   * Splits an `Iterable` into sub-non-empty-arrays stored in an object, based on the result of calling a `string`-returning
-   * function on each element, and grouping the results according to values returned
+   * Groups all elements by the string or symbol key returned by `f`.
+   *
+   * Each property in the returned record contains a non-empty array of elements
+   * that produced that key. Unlike `group`, matching elements do not need to be
+   * consecutive.
+   *
+   * **Example** (Grouping by a key)
    *
-   * @example
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2682,10 +2790,14 @@ export const groupBy: {
    */
   <A, K extends string | symbol>(f: (a: A) => K): (self: Iterable<A>) => Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>>
   /**
-   * Splits an `Iterable` into sub-non-empty-arrays stored in an object, based on the result of calling a `string`-returning
-   * function on each element, and grouping the results according to values returned
+   * Groups all elements by the string or symbol key returned by `f`.
+   *
+   * Each property in the returned record contains a non-empty array of elements
+   * that produced that key. Unlike `group`, matching elements do not need to be
+   * consecutive.
+   *
+   * **Example** (Grouping by a key)
    *
-   * @example
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2759,7 +2871,8 @@ const constEmptyIterator: Iterator<never> = {
  * This function returns a reusable empty iterable that can be used as a base case
  * for operations or when you need to represent "no data" in a type-safe way.
  *
- * @example
+ * **Example** (Creating an empty iterable)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2787,7 +2900,8 @@ export const empty = <A = never>(): Iterable<A> => constEmpty
  *
  * @param a - The single element to wrap in an iterable
  *
- * @example
+ * **Example** (Wrapping a single value)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2826,7 +2940,8 @@ export const of = <A>(a: A): Iterable<A> => [a]
  * @param self - The source iterable to transform
  * @param f - Function that transforms each element (receives value and index)
  *
- * @example
+ * **Example** (Mapping elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2862,7 +2977,8 @@ export const map: {
    * @param self - The source iterable to transform
    * @param f - Function that transforms each element (receives value and index)
    *
-   * @example
+   * **Example** (Mapping elements)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2898,7 +3014,8 @@ export const map: {
    * @param self - The source iterable to transform
    * @param f - Function that transforms each element (receives value and index)
    *
-   * @example
+   * **Example** (Mapping elements)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -2942,7 +3059,8 @@ export const map: {
 /**
  * Applies a function to each element in an Iterable and returns a new Iterable containing the concatenated mapped elements.
  *
- * @example
+ * **Example** (FlatMapping iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2980,7 +3098,8 @@ export const flatMap: {
   /**
    * Applies a function to each element in an Iterable and returns a new Iterable containing the concatenated mapped elements.
    *
-   * @example
+   * **Example** (FlatMapping iterables)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -3018,7 +3137,8 @@ export const flatMap: {
   /**
    * Applies a function to each element in an Iterable and returns a new Iterable containing the concatenated mapped elements.
    *
-   * @example
+   * **Example** (FlatMapping iterables)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -3061,7 +3181,8 @@ export const flatMap: {
 /**
  * Flattens an Iterable of Iterables into a single Iterable
  *
- * @example
+ * **Example** (Flattening nested iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3119,7 +3240,8 @@ export const flatten = <A>(self: Iterable<Iterable<A>>): Iterable<A> => ({
  * This combines mapping and filtering in a single operation - the function is applied to each element,
  * and only elements that result in `Result.succeed` are included in the result.
  *
- * @example
+ * **Example** (Filtering and transforming Result values)
+ *
  * ```ts
  * import { Iterable } from "effect"
  * import * as Result from "effect/Result"
@@ -3165,7 +3287,8 @@ export const filterMap: {
    * This combines mapping and filtering in a single operation - the function is applied to each element,
    * and only elements that result in `Result.succeed` are included in the result.
    *
-   * @example
+   * **Example** (Filtering and transforming Result values)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as Result from "effect/Result"
@@ -3211,7 +3334,8 @@ export const filterMap: {
    * This combines mapping and filtering in a single operation - the function is applied to each element,
    * and only elements that result in `Result.succeed` are included in the result.
    *
-   * @example
+   * **Example** (Filtering and transforming Result values)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as Result from "effect/Result"
@@ -3277,7 +3401,8 @@ export const filterMap: {
 /**
  * Transforms all elements of the `Iterable` for as long as the specified function succeeds.
  *
- * @example
+ * **Example** (Filtering and transforming until failure)
+ *
  * ```ts
  * import { Iterable } from "effect"
  * import * as Result from "effect/Result"
@@ -3314,7 +3439,8 @@ export const filterMapWhile: {
   /**
    * Transforms all elements of the `Iterable` for as long as the specified function succeeds.
    *
-   * @example
+   * **Example** (Filtering and transforming until failure)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as Result from "effect/Result"
@@ -3351,7 +3477,8 @@ export const filterMapWhile: {
   /**
    * Transforms all elements of the `Iterable` for as long as the specified function succeeds.
    *
-   * @example
+   * **Example** (Filtering and transforming until failure)
+   *
    * ```ts
    * import { Iterable } from "effect"
    * import * as Result from "effect/Result"
@@ -3408,7 +3535,8 @@ export const filterMapWhile: {
 /**
  * Retrieves the `Some` values from an `Iterable` of `Option`s.
  *
- * @example
+ * **Example** (Extracting Some values)
+ *
  * ```ts
  * import { Iterable } from "effect"
  * import * as Option from "effect/Option"
@@ -3446,9 +3574,11 @@ export const getSomes = <A>(self: Iterable<Option<A>>): Iterable<A> => {
 }
 
 /**
- * Retrieves the `Err` values from an `Iterable` of `Result`s.
+ * Returns a lazy iterable containing the failure values from an iterable of
+ * `Result`s, skipping successful results.
+ *
+ * **Example** (Extracting failures)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  * import * as Result from "effect/Result"
@@ -3490,9 +3620,11 @@ export const getFailures = <R0, L>(self: Iterable<Result<R0, L>>): Iterable<L> =
 }
 
 /**
- * Retrieves the `Ok` values from an `Iterable` of `Result`s.
+ * Returns a lazy iterable containing the success values from an iterable of
+ * `Result`s, skipping failed results.
+ *
+ * **Example** (Extracting successes)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  * import * as Result from "effect/Result"
@@ -3543,7 +3675,8 @@ export const getSuccesses = <R0, L>(self: Iterable<Result<R0, L>>): Iterable<R0>
  * @param self - The source iterable to filter
  * @param predicate - Function that tests each element (receives value and index)
  *
- * @example
+ * **Example** (Filtering elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3587,7 +3720,8 @@ export const filter: {
    * @param self - The source iterable to filter
    * @param predicate - Function that tests each element (receives value and index)
    *
-   * @example
+   * **Example** (Filtering elements)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -3631,7 +3765,8 @@ export const filter: {
    * @param self - The source iterable to filter
    * @param predicate - Function that tests each element (receives value and index)
    *
-   * @example
+   * **Example** (Filtering elements)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -3675,7 +3810,8 @@ export const filter: {
    * @param self - The source iterable to filter
    * @param predicate - Function that tests each element (receives value and index)
    *
-   * @example
+   * **Example** (Filtering elements)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -3719,7 +3855,8 @@ export const filter: {
    * @param self - The source iterable to filter
    * @param predicate - Function that tests each element (receives value and index)
    *
-   * @example
+   * **Example** (Filtering elements)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -3781,7 +3918,8 @@ export const filter: {
  * This is useful when working with APIs or functions that return nullable values,
  * providing a clean way to filter out null/undefined while transforming.
  *
- * @example
+ * **Example** (FlatMapping nullable results)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3824,7 +3962,8 @@ export const flatMapNullishOr: {
    * This is useful when working with APIs or functions that return nullable values,
    * providing a clean way to filter out null/undefined while transforming.
    *
-   * @example
+   * **Example** (FlatMapping nullable results)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -3867,7 +4006,8 @@ export const flatMapNullishOr: {
    * This is useful when working with APIs or functions that return nullable values,
    * providing a clean way to filter out null/undefined while transforming.
    *
-   * @example
+   * **Example** (FlatMapping nullable results)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -3916,7 +4056,8 @@ export const flatMapNullishOr: {
 /**
  * Check if a predicate holds true for some `Iterable` element.
  *
- * @example
+ * **Example** (Checking whether some element matches)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3957,7 +4098,8 @@ export const some: {
   /**
    * Check if a predicate holds true for some `Iterable` element.
    *
-   * @example
+   * **Example** (Checking whether some element matches)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -3998,7 +4140,8 @@ export const some: {
   /**
    * Check if a predicate holds true for some `Iterable` element.
    *
-   * @example
+   * **Example** (Checking whether some element matches)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4057,7 +4200,8 @@ export const some: {
  * maintains state. The function should return `Option.some([value, nextState])`
  * to continue or `Option.none()` to stop.
  *
- * @example
+ * **Example** (Unfolding state into values)
+ *
  * ```ts
  * import { Iterable, Option } from "effect"
  *
@@ -4106,7 +4250,8 @@ export const unfold = <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>): Iterab
 /**
  * Iterate over the `Iterable` applying `f`.
  *
- * @example
+ * **Example** (Iterating with side effects)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4144,7 +4289,8 @@ export const forEach: {
   /**
    * Iterate over the `Iterable` applying `f`.
    *
-   * @example
+   * **Example** (Iterating with side effects)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4182,7 +4328,8 @@ export const forEach: {
   /**
    * Iterate over the `Iterable` applying `f`.
    *
-   * @example
+   * **Example** (Iterating with side effects)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4230,7 +4377,8 @@ export const forEach: {
  * This function applies a reducing function against an accumulator and each element
  * of the iterable (from left to right) to reduce it to a single value.
  *
- * @example
+ * **Example** (Reducing an iterable)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4279,7 +4427,8 @@ export const reduce: {
    * This function applies a reducing function against an accumulator and each element
    * of the iterable (from left to right) to reduce it to a single value.
    *
-   * @example
+   * **Example** (Reducing an iterable)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4328,7 +4477,8 @@ export const reduce: {
    * This function applies a reducing function against an accumulator and each element
    * of the iterable (from left to right) to reduce it to a single value.
    *
-   * @example
+   * **Example** (Reducing an iterable)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4386,7 +4536,8 @@ export const reduce: {
 /**
  * Deduplicates adjacent elements that are identical using the provided `isEquivalent` function.
  *
- * @example
+ * **Example** (Deduplicating adjacent elements with custom equivalence)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4428,7 +4579,8 @@ export const dedupeAdjacentWith: {
   /**
    * Deduplicates adjacent elements that are identical using the provided `isEquivalent` function.
    *
-   * @example
+   * **Example** (Deduplicating adjacent elements with custom equivalence)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4470,7 +4622,8 @@ export const dedupeAdjacentWith: {
   /**
    * Deduplicates adjacent elements that are identical using the provided `isEquivalent` function.
    *
-   * @example
+   * **Example** (Deduplicating adjacent elements with custom equivalence)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4538,7 +4691,8 @@ export const dedupeAdjacentWith: {
 /**
  * Deduplicates adjacent elements that are identical.
  *
- * @example
+ * **Example** (Deduplicating adjacent elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4577,7 +4731,8 @@ export const dedupeAdjacent: <A>(self: Iterable<A>) => Iterable<A> = dedupeAdjac
 /**
  * Zips this Iterable crosswise with the specified Iterable using the specified combiner.
  *
- * @example
+ * **Example** (Combining cartesian products)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4620,14 +4775,15 @@ export const dedupeAdjacent: <A>(self: Iterable<A>) => Iterable<A> = dedupeAdjac
  * // ["admin_can_read", "admin_can_write", "admin_can_delete", "user_can_read", "user_can_write", "user_can_delete"]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const cartesianWith: {
   /**
    * Zips this Iterable crosswise with the specified Iterable using the specified combiner.
    *
-   * @example
+   * **Example** (Combining cartesian products)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4670,14 +4826,15 @@ export const cartesianWith: {
    * // ["admin_can_read", "admin_can_write", "admin_can_delete", "user_can_read", "user_can_write", "user_can_delete"]
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <A, B, C>(that: Iterable<B>, f: (a: A, b: B) => C): (self: Iterable<A>) => Iterable<C>
   /**
    * Zips this Iterable crosswise with the specified Iterable using the specified combiner.
    *
-   * @example
+   * **Example** (Combining cartesian products)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4720,8 +4877,8 @@ export const cartesianWith: {
    * // ["admin_can_read", "admin_can_write", "admin_can_delete", "user_can_read", "user_can_write", "user_can_delete"]
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <A, B, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): Iterable<C>
 } = dual(
@@ -4733,7 +4890,8 @@ export const cartesianWith: {
 /**
  * Zips this Iterable crosswise with the specified Iterable.
  *
- * @example
+ * **Example** (Generating cartesian pairs)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4767,14 +4925,15 @@ export const cartesianWith: {
  * console.log(Array.from(withEmpty)) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const cartesian: {
   /**
    * Zips this Iterable crosswise with the specified Iterable.
    *
-   * @example
+   * **Example** (Generating cartesian pairs)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4808,14 +4967,15 @@ export const cartesian: {
    * console.log(Array.from(withEmpty)) // []
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Iterable<[A, B]>
   /**
    * Zips this Iterable crosswise with the specified Iterable.
    *
-   * @example
+   * **Example** (Generating cartesian pairs)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4849,8 +5009,8 @@ export const cartesian: {
    * console.log(Array.from(withEmpty)) // []
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<[A, B]>
 } = dual(
@@ -4861,7 +5021,7 @@ export const cartesian: {
 /**
  * Counts all the element of the given iterable that pass the given predicate
  *
- * **Example**
+ * **Example** (Counting matching elements)
  *
  * ```ts
  * import { Iterable } from "effect"
@@ -4877,7 +5037,7 @@ export const countBy: {
   /**
    * Counts all the element of the given iterable that pass the given predicate
    *
-   * **Example**
+   * **Example** (Counting matching elements)
    *
    * ```ts
    * import { Iterable } from "effect"
@@ -4893,7 +5053,7 @@ export const countBy: {
   /**
    * Counts all the element of the given iterable that pass the given predicate
    *
-   * **Example**
+   * **Example** (Counting matching elements)
    *
    * ```ts
    * import { Iterable } from "effect"