Iterable
Works with JavaScript values that implement [Symbol.iterator].
Iterables include arrays, strings, generators, sets, and custom lazy sequences. The helpers in this module let code transform, search, group, and fold iterable values while preserving the input as an iterable instead of forcing an array first.
Combining
Signature
declare const append: {
<B>(last: B): <A>(self: Iterable<A>) => Iterable<B | A>;
<A, B>(self: Iterable<A>, last: B): Iterable<A | B>;
};Concatenates two iterables, combining their elements.
When to use
Use to lazily concatenate two iterables while preserving order, yielding all elements from self before that.
Details
The result is lazy. The iterator for that is not created or read until self is exhausted.
Gotchas
If self is infinite or never completes, that is never reached.
See
appendfor appending one value instead of another iterableprependAllfor yielding another iterable beforeself
Signature
declare const appendAll: {
<B>(that: Iterable<B>): <A>(self: Iterable<A>) => Iterable<B | A>;
<A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<A | B>;
};Zips this Iterable crosswise with the specified Iterable.
Signature
declare const cartesian: {
<B>(that: Iterable<B>): <A>(self: Iterable<A>) => Iterable<[A, B]>;
<A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<[A, B]>;
};cartesianWith
Zips this Iterable crosswise with the specified Iterable using the specified combiner.
Signature
declare const cartesianWith: {
<A, B, C>(that: Iterable<B>, f: (a: A, b: B) => C): (self: Iterable<A>) => Iterable<C>;
<A, B, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): Iterable<C>;
};intersperse
Places a separator between members of an Iterable.
When to use
Use to lazily insert a separator between adjacent values.
Details
If the input is a non-empty array, the result is also a non-empty array.
Signature
declare const intersperse: {
<B>(middle: B): <A>(self: Iterable<A>) => Iterable<B | A>;
<A, B>(self: Iterable<A>, middle: B): Iterable<A | B>;
};Prepends an element to the front of an Iterable, creating a new Iterable.
Signature
declare const prepend: {
<B>(head: B): <A>(self: Iterable<A>) => Iterable<B | A>;
<A, B>(self: Iterable<A>, head: B): Iterable<A | B>;
};prependAll
Prepends the specified prefix iterable to the beginning of the specified iterable.
Signature
declare const prependAll: {
<B>(that: Iterable<B>): <A>(self: Iterable<A>) => Iterable<B | A>;
<A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<A | B>;
};Constructors
Creates an empty iterable that yields no elements.
When to use
Use when you need an empty iterable as a typed "no data" value or a base case for iterable operations.
Signature
declare function empty<A = never>(): Iterable<A>;Repeats an iterable without an upper bound.
When to use
Use to cycle a reusable iterable without an upper bound when a downstream consumer controls how many values are taken.
Gotchas
The returned iterable is lazy and should usually be bounded with take or another terminating consumer before materializing it.
See
Signature
declare function forever<A>(self: Iterable<A>): Iterable<A>;Creates an iterable by applying a function to consecutive integers.
Details
The function is called with each index starting from 0. If no length is specified, the iterable is infinite. This is useful for generating sequences, patterns, or any indexed data.
Signature
declare function makeBy<A>(
f: (i: number) => A,
options?: {
readonly length?: number;
},
): Iterable<A>;Creates an iterable containing a single element.
When to use
Use to wrap a single value in an iterable context so it can be combined with other iterable operations.
Signature
declare function of<A>(a: A): Iterable<A>;Returns an iterable of integers starting at start and increasing by 1.
Details
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.
Signature
declare function range(start: number, end?: number): Iterable<number>;Repeats an iterable n times, yielding the full contents of self for each repetition.
When to use
Use to repeat an iterable's contents a specific number of times.
Details
The result is lazy. Each repetition obtains a new iterator from self.
See
Signature
declare const repeat: {
(n: number): <A>(self: Iterable<A>) => Iterable<A>;
<A>(self: Iterable<A>, n: number): Iterable<A>;
};Returns a Iterable containing a value repeated the specified number of times.
Details
n is normalized to an integer greater than or equal to 1.
Signature
declare const replicate: {
(n: number): <A>(a: A) => Iterable<A>;
<A>(a: A, n: number): Iterable<A>;
};Generates an iterable by repeatedly applying a function that produces the next element and state.
Details
This is useful for creating iterables from a generating function that maintains state. The function should return Option.some([value, nextState]) to continue or Option.none() to stop.
Signature
declare function unfold<B, A>(b: B, f: (b: B) => Option<readonly [A, B]>): Iterable<A>;Converting
fromRecord
Takes a record and returns an Iterable of tuples containing its keys and values.
Signature
declare function fromRecord<K extends string, A>(self: Readonly<Record<K, A>>): Iterable<[K, A]>;Filtering
dedupeAdjacent
Deduplicates adjacent elements that are identical.
Signature
declare const dedupeAdjacent: <A>(self: Iterable<A>) => Iterable<A>;dedupeAdjacentWith
Deduplicates adjacent elements that are identical using the provided isEquivalent function.
Signature
declare const dedupeAdjacentWith: {
<A>(isEquivalent: (self: A, that: A) => boolean): (self: Iterable<A>) => Iterable<A>;
<A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Iterable<A>;
};Filters an iterable to only include elements that match a predicate.
Details
This function creates a new iterable containing only the elements for which the predicate function returns true. Like map, this operation is lazy and elements are only tested when the iterable is consumed.
Signature
declare const filter: {
<A, B>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Iterable<B>;
<A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Iterable<A>;
<A, B>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Iterable<B>;
<A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Iterable<A>;
};Transforms elements of an iterable using a function that returns a Result, keeping only successful values.
Details
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.
Signature
declare const filterMap: {
<A, B, X>(f: (input: A, i: number) => Result<B, X>): (self: Iterable<A>) => Iterable<B>;
<A, B, X>(self: Iterable<A>, f: (input: A, i: number) => Result<B, X>): Iterable<B>;
};filterMapWhile
Transforms all elements of the Iterable for as long as the specified function succeeds.
Signature
declare const filterMapWhile: {
<A, B, X>(f: (input: A, i: number) => Result<B, X>): (self: Iterable<A>) => Iterable<B>;
<A, B, X>(self: Iterable<A>, f: (input: A, i: number) => Result<B, X>): Iterable<B>;
};getFailures
Returns a lazy iterable containing the failure values from an iterable of Results, skipping successful results.
Signature
declare function getFailures<R0, L>(self: Iterable<Result<R0, L>>): Iterable<L>;Retrieves the Some values from an Iterable of Options.
Signature
declare function getSomes<A>(self: Iterable<Option<A>>): Iterable<A>;getSuccesses
Returns a lazy iterable containing the success values from an iterable of Results, skipping failed results.
Signature
declare function getSuccesses<R0, L>(self: Iterable<Result<R0, L>>): Iterable<R0>;Folding
Computes how many elements of the iterable pass the given predicate.
Signature
declare const countBy: {
<A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => number;
<A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): number;
};Reduces an iterable to a single value by applying a function to each element and accumulating the result.
Details
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.
Signature
declare const reduce: {
<B, A>(b: B, f: (b: B, a: A, i: number) => B): (self: Iterable<A>) => B;
<A, B>(self: Iterable<A>, b: B, f: (b: B, a: A, i: number) => B): B;
};Reduces an Iterable from the left, keeping all intermediate results instead of only the final result.
Signature
declare const scan: {
<B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => Iterable<B>;
<A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): Iterable<B>;
};Getters
Drops a max number of elements from the start of an Iterable
Details
n is normalized to a non-negative integer.
Signature
declare const drop: {
(n: number): <A>(self: Iterable<A>) => Iterable<A>;
<A>(self: Iterable<A>, n: number): Iterable<A>;
};Gets the first element of a Iterable safely, or None if the Iterable is empty.
Signature
declare function head<A>(self: Iterable<A>): Option<A>;headUnsafe
Gets the first element of an Iterable without returning an Option.
When to use
Use when the Iterable is known to be non-empty and direct access to the first element is preferred over handling Option.none.
Gotchas
Throws if the Iterable is empty.
Signature
declare function headUnsafe<A>(self: Iterable<A>): A;Returns the number of elements in a Iterable.
Signature
declare function size<A>(self: Iterable<A>): number;Keeps only a max number of elements from the start of an Iterable, creating a new Iterable.
Details
n is normalized to a non-negative integer.
Signature
declare const take: {
(n: number): <A>(self: Iterable<A>) => Iterable<A>;
<A>(self: Iterable<A>, n: number): Iterable<A>;
};Takes the longest initial Iterable prefix for which all elements satisfy the specified predicate.
Signature
declare const takeWhile: {
<A, B>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Iterable<B>;
<A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Iterable<A>;
<A, B>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Iterable<B>;
<A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Iterable<A>;
};Grouping
Groups equal, consecutive elements of an Iterable into NonEmptyArrays.
Signature
declare const group: <A>(self: Iterable<A>) => Iterable<NonEmptyArray<A>>;Groups all elements by the string or symbol key returned by f.
Details
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.
Signature
declare const groupBy: {
<A, K extends string | symbol>(
f: (a: A) => K,
): (self: Iterable<A>) => Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>>;
<A, K extends string | symbol>(
self: Iterable<A>,
f: (a: A) => K,
): Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>>;
};Groups equal, consecutive elements of an Iterable into NonEmptyArrays using the provided isEquivalent function.
Signature
declare const groupWith: {
<A>(
isEquivalent: (self: A, that: A) => boolean,
): (self: Iterable<A>) => Iterable<[A, ...Array<A>]>;
<A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Iterable<[A, ...Array<A>]>;
};Guards
Mapping
Transforms each element of an iterable using a function.
Details
This is one of the most fundamental operations for working with iterables. It applies a transformation function to each element, creating a new iterable with the transformed values. The operation is lazy, so elements are only transformed when the iterable is consumed.
Signature
declare const map: {
<A, B>(f: (a: NoInfer<A>, i: number) => B): (self: Iterable<A>) => Iterable<B>;
<A, B>(self: Iterable<A>, f: (a: NoInfer<A>, i: number) => B): Iterable<B>;
};Predicates
Checks whether an iterable contains a value using Effect's default Equal equivalence.
Details
Can be called as contains(self, value) or curried as contains(value)(self).
Signature
declare const contains: {
<A>(a: A): (self: Iterable<A>) => boolean;
<A>(self: Iterable<A>, a: A): boolean;
};containsWith
Returns a function that checks if an Iterable contains a given value using a provided isEquivalent function.
Signature
declare function containsWith<A>(isEquivalent: (self: A, that: A) => boolean): {
(a: A): (self: Iterable<A>) => boolean;
(self: Iterable<A>, a: A): boolean;
};Checks whether a predicate holds true for some Iterable element.
Signature
declare const some: {
<A>(predicate: (a: A, i: number) => boolean): (self: Iterable<A>) => boolean;
<A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): boolean;
};Searching
Returns the first element that satisfies the specified predicate, or None if no such element exists.
Signature
declare const findFirst: {
<A, B>(f: (a: NoInfer<A>, i: number) => Option<B>): (self: Iterable<A>) => Option<B>;
<A, B>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Option<B>;
<A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option<A>;
<A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Option<B>;
<A, B>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Option<B>;
<A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option<A>;
};Finds the last element for which a predicate holds.
Signature
declare const findLast: {
<A, B>(f: (a: NoInfer<A>, i: number) => Option<B>): (self: Iterable<A>) => Option<B>;
<A, B>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Option<B>;
<A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option<A>;
<A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Option<B>;
<A, B>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Option<B>;
<A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option<A>;
};Sequencing
Applies a function to each element in an Iterable and returns a new Iterable containing the concatenated mapped elements.
Signature
declare const flatMap: {
<A, B>(f: (a: NoInfer<A>, i: number) => Iterable<B>): (self: Iterable<A>) => Iterable<B>;
<A, B>(self: Iterable<A>, f: (a: NoInfer<A>, i: number) => Iterable<B>): Iterable<B>;
};flatMapNullishOr
Transforms elements using a function that may return null or undefined, filtering out the null/undefined results.
When to use
Use when working with APIs or functions that return nullable values, providing a clean way to filter out null or undefined while transforming.
Signature
declare const flatMapNullishOr: {
<A, B>(f: (a: A) => B): (self: Iterable<A>) => Iterable<NonNullable<B>>;
<A, B>(self: Iterable<A>, f: (a: A) => B): Iterable<NonNullable<B>>;
};Flattens an Iterable of Iterables into a single Iterable
Signature
declare function flatten<A>(self: Iterable<Iterable<A, any, any>>): Iterable<A>;Splitting
Splits an Iterable into length-n pieces. The last piece will be shorter if n does not evenly divide the length of the Iterable.
Signature
declare const chunksOf: {
(n: number): <A>(self: Iterable<A>) => Iterable<Array<A>>;
<A>(self: Iterable<A>, n: number): Iterable<Array<A>>;
};Traversing
Zipping
Takes two Iterables and returns an Iterable of corresponding pairs.
Signature
declare const zip: {
<B>(that: Iterable<B>): <A>(self: Iterable<A>) => Iterable<[A, B]>;
<A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<[A, B]>;
};Applies a function to pairs of elements at the same index in two Iterables, collecting the results. If one input Iterable is short, excess elements of the longer Iterable are discarded.
Signature
declare const zipWith: {
<B, A, C>(that: Iterable<B>, f: (a: A, b: B) => C): (self: Iterable<A>) => Iterable<C>;
<A, B, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): Iterable<C>;
};
Appends an element to the end of an
Iterable, creating a newIterable.When to use
Use to add one element after all elements of an iterable while keeping the result as a lazy
Iterable.Details
The result yields every element from
selffirst, then yieldslastafterselfis exhausted.Gotchas
If
selfis infinite or never completes, the appended element is never reached.See
prependfor adding one element before the existing elementsappendAllfor appending all elements from another iterable