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

package/dist/Iterable.d.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"
  *
@@ -44,7 +45,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"
  *
@@ -69,11 +71,14 @@ export declare const makeBy: <A>(f: (i: number) => A, options?: {
     readonly length?: number;
 }) => Iterable<A>;
 /**
- * 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"
@@ -90,7 +95,8 @@ export declare 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"
@@ -107,7 +113,8 @@ export declare 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"
@@ -124,7 +131,8 @@ export declare 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"
@@ -138,22 +146,42 @@ export declare const replicate: {
     <A>(a: A, n: number): 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
  */
 export declare 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
      */
     <A>(self: Iterable<A>, n: number): Iterable<A>;
 };
 /**
+ * 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
  */
@@ -161,7 +189,8 @@ export declare const forever: <A>(self: Iterable<A>) => Iterable<A>;
 /**
  * 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"
@@ -180,7 +209,8 @@ export declare const fromRecord: <K extends string, A>(self: Readonly<Record<K,
 /**
  * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
  *
- * @example
+ * **Example** (Prepending an element)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -201,7 +231,8 @@ export declare 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"
      *
@@ -222,7 +253,8 @@ export declare 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"
      *
@@ -244,7 +276,8 @@ export declare 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"
@@ -262,7 +295,8 @@ export declare 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"
@@ -280,7 +314,8 @@ export declare 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"
@@ -299,7 +334,8 @@ export declare 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"
  *
@@ -322,7 +358,8 @@ export declare 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"
      *
@@ -345,7 +382,8 @@ export declare 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"
      *
@@ -369,7 +407,8 @@ export declare const append: {
 /**
  * Concatenates two iterables, combining their elements.
  *
- * @example
+ * **Example** (Concatenating iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -398,7 +437,8 @@ export declare const appendAll: {
     /**
      * Concatenates two iterables, combining their elements.
      *
-     * @example
+     * **Example** (Concatenating iterables)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -427,7 +467,8 @@ export declare const appendAll: {
     /**
      * Concatenates two iterables, combining their elements.
      *
-     * @example
+     * **Example** (Concatenating iterables)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -457,7 +498,8 @@ export declare 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"
  *
@@ -484,7 +526,8 @@ export declare 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"
      *
@@ -511,7 +554,8 @@ export declare 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"
      *
@@ -539,7 +583,8 @@ export declare 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"
@@ -555,7 +600,8 @@ export declare 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"
  *
@@ -581,7 +627,8 @@ export declare 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"
@@ -610,7 +657,8 @@ 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.
  *
- * @example
+ * **Example** (Getting the first element unsafely)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -620,13 +668,8 @@ export declare 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)
@@ -642,7 +685,8 @@ export declare 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"
  *
@@ -673,7 +717,8 @@ export declare const take: {
      *
      * **Note**. `n` is normalized to a non negative integer.
      *
-     * @example
+     * **Example** (Taking from the start)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -704,7 +749,8 @@ export declare const take: {
      *
      * **Note**. `n` is normalized to a non negative integer.
      *
-     * @example
+     * **Example** (Taking from the start)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -734,7 +780,8 @@ export declare 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"
  *
@@ -768,7 +815,8 @@ export declare 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"
      *
@@ -802,7 +850,8 @@ export declare 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"
      *
@@ -836,7 +885,8 @@ export declare 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"
      *
@@ -870,7 +920,8 @@ export declare 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"
      *
@@ -907,7 +958,8 @@ export declare const takeWhile: {
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
- * @example
+ * **Example** (Dropping from the start)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -937,7 +989,8 @@ export declare const drop: {
      *
      * **Note**. `n` is normalized to a non negative integer.
      *
-     * @example
+     * **Example** (Dropping from the start)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -967,7 +1020,8 @@ export declare const drop: {
      *
      * **Note**. `n` is normalized to a non negative integer.
      *
-     * @example
+     * **Example** (Dropping from the start)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -997,7 +1051,8 @@ export declare 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"
@@ -1038,7 +1093,8 @@ export declare 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"
@@ -1079,7 +1135,8 @@ export declare 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"
@@ -1120,7 +1177,8 @@ export declare 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"
@@ -1161,7 +1219,8 @@ export declare 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"
@@ -1202,7 +1261,8 @@ export declare 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 +1303,8 @@ export declare 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 +1345,8 @@ export declare const findFirst: {
 /**
  * Find the last element for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the last match)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1316,7 +1378,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1348,7 +1411,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1380,7 +1444,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1412,7 +1477,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1444,7 +1510,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1476,7 +1543,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1509,7 +1577,8 @@ export declare const findLast: {
 /**
  * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
  *
- * @example
+ * **Example** (Zipping iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1544,7 +1613,8 @@ export declare const zip: {
     /**
      * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
      *
-     * @example
+     * **Example** (Zipping iterables)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1579,7 +1649,8 @@ export declare const zip: {
     /**
      * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
      *
-     * @example
+     * **Example** (Zipping iterables)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1616,7 +1687,8 @@ export declare 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"
  *
@@ -1663,7 +1735,8 @@ export declare 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"
      *
@@ -1710,7 +1783,8 @@ export declare 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"
      *
@@ -1758,7 +1832,8 @@ export declare 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"
  *
@@ -1796,7 +1871,8 @@ export declare 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"
      *
@@ -1834,7 +1910,8 @@ export declare 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"
      *
@@ -1872,7 +1949,8 @@ export declare 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"
  *
@@ -1910,9 +1988,14 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
     (self: Iterable<A>, a: 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"
  *
@@ -1940,9 +2023,14 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
  */
 export declare 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"
      *
@@ -1970,9 +2058,14 @@ export declare 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"
      *
@@ -2004,7 +2097,8 @@ export declare 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"
  *
@@ -2043,7 +2137,8 @@ export declare 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"
      *
@@ -2082,7 +2177,8 @@ export declare 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"
      *
@@ -2121,7 +2217,8 @@ export declare 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"
  *
@@ -2160,7 +2257,8 @@ export declare 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"
      *
@@ -2199,7 +2297,8 @@ export declare 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"
      *
@@ -2239,7 +2338,8 @@ export declare const groupWith: {
 /**
  * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s.
  *
- * @example
+ * **Example** (Grouping consecutive elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2270,10 +2370,14 @@ export declare const groupWith: {
  */
 export declare const group: <A>(self: Iterable<A>) => Iterable<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"
  *
@@ -2315,10 +2419,14 @@ export declare const group: <A>(self: Iterable<A>) => Iterable<NonEmptyArray<A>>
  */
 export declare 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"
      *
@@ -2360,10 +2468,14 @@ export declare 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"
      *
@@ -2411,7 +2523,8 @@ export declare const groupBy: {
  * 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"
  *
@@ -2438,7 +2551,8 @@ export declare const empty: <A = never>() => Iterable<A>;
  *
  * @param a - The single element to wrap in an iterable
  *
- * @example
+ * **Example** (Wrapping a single value)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2476,7 +2590,8 @@ export declare const of: <A>(a: A) => Iterable<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"
  *
@@ -2512,7 +2627,8 @@ export declare 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"
      *
@@ -2548,7 +2664,8 @@ export declare 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"
      *
@@ -2577,7 +2694,8 @@ export declare 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"
  *
@@ -2615,7 +2733,8 @@ export declare 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"
      *
@@ -2653,7 +2772,8 @@ export declare 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"
      *
@@ -2692,7 +2812,8 @@ export declare const flatMap: {
 /**
  * Flattens an Iterable of Iterables into a single Iterable
  *
- * @example
+ * **Example** (Flattening nested iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2728,7 +2849,8 @@ export declare 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"
@@ -2774,7 +2896,8 @@ export declare 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"
@@ -2820,7 +2943,8 @@ export declare 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"
@@ -2864,7 +2988,8 @@ export declare 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"
@@ -2901,7 +3026,8 @@ export declare 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"
@@ -2938,7 +3064,8 @@ export declare 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"
@@ -2976,7 +3103,8 @@ export declare 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"
@@ -2995,9 +3123,11 @@ export declare const filterMapWhile: {
  */
 export declare 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"
@@ -3020,9 +3150,11 @@ export declare const getSomes: <A>(self: Iterable<Option<A>>) => Iterable<A>;
  */
 export declare 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"
@@ -3054,7 +3186,8 @@ export declare const getSuccesses: <R0, L>(self: Iterable<Result<R0, L>>) => Ite
  * @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"
  *
@@ -3098,7 +3231,8 @@ export declare 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"
      *
@@ -3142,7 +3276,8 @@ export declare 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"
      *
@@ -3186,7 +3321,8 @@ export declare 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"
      *
@@ -3230,7 +3366,8 @@ export declare 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"
      *
@@ -3271,7 +3408,8 @@ export declare 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"
  *
@@ -3314,7 +3452,8 @@ export declare 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"
      *
@@ -3357,7 +3496,8 @@ export declare 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"
      *
@@ -3398,7 +3538,8 @@ export declare const flatMapNullishOr: {
 /**
  * Check if a predicate holds true for some `Iterable` element.
  *
- * @example
+ * **Example** (Checking whether some element matches)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3439,7 +3580,8 @@ export declare const some: {
     /**
      * Check if a predicate holds true for some `Iterable` element.
      *
-     * @example
+     * **Example** (Checking whether some element matches)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3480,7 +3622,8 @@ export declare const some: {
     /**
      * Check if a predicate holds true for some `Iterable` element.
      *
-     * @example
+     * **Example** (Checking whether some element matches)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3527,7 +3670,8 @@ export declare 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"
  *
@@ -3560,7 +3704,8 @@ export declare const unfold: <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>)
 /**
  * Iterate over the `Iterable` applying `f`.
  *
- * @example
+ * **Example** (Iterating with side effects)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3598,7 +3743,8 @@ export declare const forEach: {
     /**
      * Iterate over the `Iterable` applying `f`.
      *
-     * @example
+     * **Example** (Iterating with side effects)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3636,7 +3782,8 @@ export declare const forEach: {
     /**
      * Iterate over the `Iterable` applying `f`.
      *
-     * @example
+     * **Example** (Iterating with side effects)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3678,7 +3825,8 @@ export declare 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"
  *
@@ -3727,7 +3875,8 @@ export declare 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"
      *
@@ -3776,7 +3925,8 @@ export declare 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"
      *
@@ -3823,7 +3973,8 @@ export declare 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"
  *
@@ -3865,7 +4016,8 @@ export declare 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"
      *
@@ -3907,7 +4059,8 @@ export declare 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"
      *
@@ -3950,7 +4103,8 @@ export declare const dedupeAdjacentWith: {
 /**
  * Deduplicates adjacent elements that are identical.
  *
- * @example
+ * **Example** (Deduplicating adjacent elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3988,7 +4142,8 @@ export declare const dedupeAdjacent: <A>(self: Iterable<A>) => Iterable<A>;
 /**
  * Zips this Iterable crosswise with the specified Iterable using the specified combiner.
  *
- * @example
+ * **Example** (Combining cartesian products)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4031,14 +4186,15 @@ export declare const dedupeAdjacent: <A>(self: Iterable<A>) => Iterable<A>;
  * // ["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 declare const cartesianWith: {
     /**
      * Zips this Iterable crosswise with the specified Iterable using the specified combiner.
      *
-     * @example
+     * **Example** (Combining cartesian products)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -4081,14 +4237,15 @@ export declare 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"
      *
@@ -4131,15 +4288,16 @@ export declare 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>;
 };
 /**
  * Zips this Iterable crosswise with the specified Iterable.
  *
- * @example
+ * **Example** (Generating cartesian pairs)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4173,14 +4331,15 @@ export declare const cartesianWith: {
  * console.log(Array.from(withEmpty)) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const cartesian: {
     /**
      * Zips this Iterable crosswise with the specified Iterable.
      *
-     * @example
+     * **Example** (Generating cartesian pairs)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -4214,14 +4373,15 @@ export declare 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"
      *
@@ -4255,15 +4415,15 @@ export declare 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]>;
 };
 /**
  * Counts all the element of the given iterable that pass the given predicate
  *
- * **Example**
+ * **Example** (Counting matching elements)
  *
  * ```ts
  * import { Iterable } from "effect"
@@ -4279,7 +4439,7 @@ export declare 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"
@@ -4295,7 +4455,7 @@ export declare 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"