effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Iterable.js

@@ -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"
  *
@@ -42,10 +43,8 @@ import * as Tuple from "./Tuple.js";
  * with each index starting from 0. If no length is specified, the iterable will
  * be infinite. This is useful for generating sequences, patterns, or any indexed data.
  *
- * @param f - Function that receives the index and returns the element
- * @param options - Configuration object with optional length
+ * **Example** (Generating values by index)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -89,16 +88,19 @@ export const makeBy = (f, 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 { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Array.from(range(1, 3)), [1, 2, 3])
+ * assert.deepStrictEqual(Array.from(Iterable.range(1, 3)), [1, 2, 3])
  * ```
  *
  * @category constructors
@@ -117,12 +119,13 @@ export const range = (start, end) => {
  *
  * **Note**. `n` is normalized to an integer >= 1.
  *
- * @example
+ * **Example** (Repeating a value)
+ *
  * ```ts
- * import { replicate } from "effect/Iterable"
+ * import { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Array.from(replicate("a", 3)), ["a", "a", "a"])
+ * assert.deepStrictEqual(Array.from(Iterable.replicate("a", 3)), ["a", "a", "a"])
  * ```
  *
  * @category constructors
@@ -132,6 +135,11 @@ export const replicate = /*#__PURE__*/dual(2, (a, n) => 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
  */
@@ -139,6 +147,11 @@ export const repeat = /*#__PURE__*/dual(2, (self, n) => flatten(makeBy(() => sel
   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
  */
@@ -146,19 +159,20 @@ export const forever = self => repeat(self, Infinity);
 /**
  * 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 { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
  * const x = { a: 1, b: 2, c: 3 }
- * assert.deepStrictEqual(Array.from(fromRecord(x)), [["a", 1], ["b", 2], [
+ * assert.deepStrictEqual(Array.from(Iterable.fromRecord(x)), [["a", 1], ["b", 2], [
  *   "c",
  *   3
  * ]])
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export const fromRecord = self => ({
@@ -173,7 +187,8 @@ export const fromRecord = self => ({
 /**
  * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
  *
- * @example
+ * **Example** (Prepending an element)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -194,7 +209,8 @@ export const prepend = /*#__PURE__*/dual(2, (self, head) => prependAll(self, [he
 /**
  * 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"
@@ -212,7 +228,8 @@ export const prependAll = /*#__PURE__*/dual(2, (self, that) => appendAll(that, s
 /**
  * Append an element to the end of an `Iterable`, creating a new `Iterable`.
  *
- * @example
+ * **Example** (Appending an element)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -235,7 +252,8 @@ export const append = /*#__PURE__*/dual(2, (self, last) => appendAll(self, [last
 /**
  * Concatenates two iterables, combining their elements.
  *
- * @example
+ * **Example** (Concatenating iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -284,7 +302,8 @@ export const appendAll = /*#__PURE__*/dual(2, (self, that) => ({
 /**
  * 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"
  *
@@ -337,13 +356,14 @@ export const scan = /*#__PURE__*/dual(3, (self, b, f) => ({
 /**
  * Determine if an `Iterable` is empty
  *
- * @example
+ * **Example** (Checking for emptiness)
+ *
  * ```ts
- * import { isEmpty } from "effect/Iterable"
+ * import { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isEmpty([]), true)
- * assert.deepStrictEqual(isEmpty([1, 2, 3]), false)
+ * assert.deepStrictEqual(Iterable.isEmpty([]), true)
+ * assert.deepStrictEqual(Iterable.isEmpty([1, 2, 3]), false)
  * ```
  *
  * @category guards
@@ -356,7 +376,8 @@ export const isEmpty = self => {
 /**
  * Return the number of elements in a `Iterable`.
  *
- * @example
+ * **Example** (Counting iterable elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -389,10 +410,10 @@ export const size = self => {
 /**
  * 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"
+ * import { Iterable, Option } from "effect"
  *
  * const numbers = [1, 2, 3]
  * console.log(Iterable.head(numbers)) // Option.some(1)
@@ -422,7 +443,8 @@ export const head = self => {
 /**
  * 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"
  *
@@ -432,13 +454,8 @@ export const head = self => {
  * 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)
@@ -446,7 +463,7 @@ export const head = self => {
  * ```
  *
  * @category getters
- * @since 3.3.0
+ * @since 4.0.0
  */
 export const headUnsafe = self => {
   const iterator = self[Symbol.iterator]();
@@ -459,7 +476,8 @@ export const headUnsafe = self => {
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
- * @example
+ * **Example** (Taking from the start)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -505,7 +523,8 @@ export const take = /*#__PURE__*/dual(2, (self, n) => ({
 /**
  * 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"
  *
@@ -558,7 +577,8 @@ export const takeWhile = /*#__PURE__*/dual(2, (self, predicate) => ({
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
- * @example
+ * **Example** (Dropping from the start)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -607,10 +627,10 @@ export const drop = /*#__PURE__*/dual(2, (self, n) => ({
  * 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"
+ * import { Iterable, Option } from "effect"
  *
  * const numbers = [1, 3, 4, 6, 8]
  * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -663,7 +683,8 @@ export const findFirst = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * Find the last element for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the last match)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -712,7 +733,8 @@ export const findLast = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
  *
- * @example
+ * **Example** (Zipping iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -748,7 +770,8 @@ export const zip = /*#__PURE__*/dual(2, (self, that) => zipWith(self, that, Tupl
  * 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"
  *
@@ -816,7 +839,8 @@ export const zipWith = /*#__PURE__*/dual(3, (self, that, f) => ({
  * 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"
  *
@@ -876,7 +900,8 @@ export const intersperse = /*#__PURE__*/dual(2, (self, middle) => ({
 /**
  * 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"
  *
@@ -918,9 +943,14 @@ export const containsWith = isEquivalent => dual(2, (self, a) => {
   return false;
 });
 /**
- * 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"
  *
@@ -951,7 +981,8 @@ export const contains = /*#__PURE__*/containsWith(/*#__PURE__*/Equal.asEquivalen
  * 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"
  *
@@ -1025,7 +1056,8 @@ export const chunksOf = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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"
  *
@@ -1104,7 +1136,8 @@ export const groupWith = /*#__PURE__*/dual(2, (self, isEquivalent) => ({
 /**
  * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s.
  *
- * @example
+ * **Example** (Grouping consecutive elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1135,10 +1168,14 @@ export const groupWith = /*#__PURE__*/dual(2, (self, isEquivalent) => ({
  */
 export const group = /*#__PURE__*/groupWith(/*#__PURE__*/Equal.asEquivalence());
 /**
- * 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"
  *
@@ -1209,7 +1246,8 @@ const constEmptyIterator = {
  * 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"
  *
@@ -1234,9 +1272,8 @@ export const empty = () => constEmpty;
  * This is useful for wrapping a single value in an iterable context,
  * allowing it to be used with other iterable operations.
  *
- * @param a - The single element to wrap in an iterable
+ * **Example** (Wrapping a single value)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1271,10 +1308,8 @@ export const of = a => [a];
  * with the transformed values. The operation is lazy - elements are only
  * transformed when the iterable is consumed.
  *
- * @param self - The source iterable to transform
- * @param f - Function that transforms each element (receives value and index)
+ * **Example** (Mapping elements)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1322,7 +1357,8 @@ export const map = /*#__PURE__*/dual(2, (self, f) => ({
 /**
  * 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"
  *
@@ -1360,7 +1396,8 @@ export const flatMap = /*#__PURE__*/dual(2, (self, f) => flatten(map(self, f)));
 /**
  * Flattens an Iterable of Iterables into a single Iterable
  *
- * @example
+ * **Example** (Flattening nested iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1419,10 +1456,10 @@ export const flatten = self => ({
  * 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"
+ * import { Iterable, Result } from "effect"
  *
  * // Parse strings to numbers, keeping only valid ones
  * const strings = ["1", "2", "invalid", "4", "not-a-number"]
@@ -1486,10 +1523,10 @@ export const filterMap = /*#__PURE__*/dual(2, (self, f) => ({
 /**
  * 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"
+ * import { Iterable, Result } from "effect"
  *
  * // Parse numbers until we hit an invalid one
  * const strings = ["1", "2", "3", "invalid", "4", "5"]
@@ -1550,10 +1587,10 @@ export const filterMapWhile = /*#__PURE__*/dual(2, (self, f) => ({
 /**
  * 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"
+ * import { Iterable, Option } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
@@ -1593,12 +1630,13 @@ export const getSomes = self => {
   };
 };
 /**
- * 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"
+ * import { Iterable, Result } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
@@ -1614,7 +1652,7 @@ export const getSomes = self => {
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const getFailures = self => {
   return {
@@ -1642,12 +1680,13 @@ export const getFailures = self => {
   };
 };
 /**
- * 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"
+ * import { Iterable, Result } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
@@ -1663,7 +1702,7 @@ export const getFailures = self => {
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const getSuccesses = self => {
   return {
@@ -1697,10 +1736,8 @@ export const getSuccesses = self => {
  * the predicate function returns true. Like map, this operation is lazy and
  * elements are only tested when the iterable is consumed.
  *
- * @param self - The source iterable to filter
- * @param predicate - Function that tests each element (receives value and index)
+ * **Example** (Filtering elements)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1763,7 +1800,8 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => ({
  * 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"
  *
@@ -1797,7 +1835,7 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => ({
  * ```
  *
  * @category sequencing
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const flatMapNullishOr = /*#__PURE__*/dual(2, (self, f) => filterMap(self, a => {
   const b = f(a);
@@ -1806,7 +1844,8 @@ export const flatMapNullishOr = /*#__PURE__*/dual(2, (self, f) => filterMap(self
 /**
  * Check if a predicate holds true for some `Iterable` element.
  *
- * @example
+ * **Example** (Checking whether some element matches)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1860,7 +1899,8 @@ export const some = /*#__PURE__*/dual(2, (self, predicate) => {
  * 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"
  *
@@ -1914,7 +1954,8 @@ export const unfold = (b, f) => ({
 /**
  * Iterate over the `Iterable` applying `f`.
  *
- * @example
+ * **Example** (Iterating with side effects)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1960,7 +2001,8 @@ export const forEach = /*#__PURE__*/dual(2, (self, f) => {
  * 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"
  *
@@ -2016,7 +2058,8 @@ export const reduce = /*#__PURE__*/dual(3, (self, b, f) => {
 /**
  * Deduplicates adjacent elements that are identical using the provided `isEquivalent` function.
  *
- * @example
+ * **Example** (Deduplicating adjacent elements with custom equivalence)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2087,7 +2130,8 @@ export const dedupeAdjacentWith = /*#__PURE__*/dual(2, (self, isEquivalent) => (
 /**
  * Deduplicates adjacent elements that are identical.
  *
- * @example
+ * **Example** (Deduplicating adjacent elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2125,7 +2169,8 @@ export const dedupeAdjacent = /*#__PURE__*/dedupeAdjacentWith(/*#__PURE__*/Equal
 /**
  * Zips this Iterable crosswise with the specified Iterable using the specified combiner.
  *
- * @example
+ * **Example** (Combining cartesian products)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2168,14 +2213,15 @@ export const dedupeAdjacent = /*#__PURE__*/dedupeAdjacentWith(/*#__PURE__*/Equal
  * // ["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 = /*#__PURE__*/dual(3, (self, that, f) => flatMap(self, a => map(that, b => f(a, b))));
 /**
  * Zips this Iterable crosswise with the specified Iterable.
  *
- * @example
+ * **Example** (Generating cartesian pairs)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2209,14 +2255,14 @@ export const cartesianWith = /*#__PURE__*/dual(3, (self, that, f) => flatMap(sel
  * console.log(Array.from(withEmpty)) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const cartesian = /*#__PURE__*/dual(2, (self, that) => cartesianWith(self, that, (a, b) => [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"