Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

Iterable

This module provides utility functions for working with Iterables in TypeScript.

48 exports Since v2.0.0 Source

Concatenating

append

Since v2.0.0

Append an element to the end of an Iterable, creating a new Iterable.

Signature

declare const append: {
  <B>(last: B): <A>(self: Iterable<A>) => Iterable<B | A>;
  <A, B>(self: Iterable<A>, last: B): Iterable<A | B>;
}

appendAll

Since v2.0.0

Concatenates two iterables, combining their elements.

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>;
}

prepend

Since v2.0.0

Prepend 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

Since v2.0.0

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>;
}

Example 

import * as assert from "node:assert"
import { Iterable } from "effect"


assert.deepStrictEqual(
  Array.from(Iterable.prependAll([1, 2], ["a", "b"])),
  ["a", "b", 1, 2]
)

Constructors

empty

Since v2.0.0

Signature

declare function empty<A = never>(): Iterable<A>

makeBy

Since v2.0.0

Return a Iterable with element i initialized with f(i).

If the length is not specified, the Iterable will be infinite.

Note. length is normalized to an integer >= 1.

Signature

declare function makeBy<A>(f: (i: number) => A, options?: {
  readonly length?: number;
}): Iterable<A>

Example 

import * as assert from "node:assert"
import { makeBy } from "effect/Iterable"


assert.deepStrictEqual(Array.from(makeBy(n => n * 2, { length: 5 })), [0, 2, 4, 6, 8])

of

Since v2.0.0

Constructs a new Iterable<A> from the specified value.

Signature

declare function of<A>(a: A): Iterable<A>

range

Since v2.0.0

Return a Iterable containing a range of integers, including both endpoints.

If end is omitted, the range will not have an upper bound.

Signature

declare function range(start: number, end?: number): Iterable<number>

Example 

import * as assert from "node:assert"
import { range } from "effect/Iterable"


assert.deepStrictEqual(Array.from(range(1, 3)), [1, 2, 3])

replicate

Since v2.0.0

Return a Iterable containing a value repeated the specified number of times.

Note. n is normalized to an integer >= 1.

Signature

declare const replicate: {
  (n: number): <A>(a: A) => Iterable<A>;
  <A>(a: A, n: number): Iterable<A>;
}

Example 

import * as assert from "node:assert"
import { replicate } from "effect/Iterable"


assert.deepStrictEqual(Array.from(replicate("a", 3)), ["a", "a", "a"])

unfold

Since v2.0.0

Signature

declare function unfold<B, A>(b: B, f: (b: B) => Option<readonly [A, B]>): Iterable<A>

Conversions

fromRecord

Since v2.0.0

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]>

Example 

import * as assert from "node:assert"
import { fromRecord } from "effect/Iterable"


const x = { a: 1, b: 2, c: 3 }
assert.deepStrictEqual(Array.from(fromRecord(x)), [["a", 1], ["b", 2], ["c", 3]])

Elements

cartesian

Since v2.0.0

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

Since v2.0.0

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>;
}

contains

Since v2.0.0

Returns a function that checks if a Iterable contains a given value using the default Equivalence.

Signature

declare const contains: {
  <A>(a: A): (self: Iterable<A>) => boolean;
  <A>(self: Iterable<A>, a: A): boolean;
}

containsWith

Since v2.0.0

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;
}

findFirst

Since v2.0.0

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>;
}

findLast

Since v2.0.0

Find 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>;
}

some

Since v2.0.0

Check if 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;
}

Filtering

filter

Since v2.0.0

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>;
}

filterMap

Since v2.0.0

Signature

declare const filterMap: {
  <A, B>(f: (a: A, i: number) => Option<B>): (self: Iterable<A>) => Iterable<B>;
  <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Iterable<B>;
}

filterMapWhile

Since v2.0.0

Transforms all elements of the Iterable for as long as the specified function returns some value

Signature

declare const filterMapWhile: {
  <A, B>(f: (a: A, i: number) => Option<B>): (self: Iterable<A>) => Iterable<B>;
  <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Iterable<B>;
}

getLefts

Since v2.0.0

Retrieves the Left values from an Iterable of Eithers.

Signature

declare function getLefts<R, L>(self: Iterable<Either<R, L>>): Iterable<L>

Example 

import * as assert from "node:assert"
import { Iterable, Either } from "effect"


assert.deepStrictEqual(
  Array.from(Iterable.getLefts([Either.right(1), Either.left("err"), Either.right(2)])),
  ["err"]
)

getRights

Since v2.0.0

Retrieves the Right values from an Iterable of Eithers.

Signature

declare function getRights<R, L>(self: Iterable<Either<R, L>>): Iterable<R>

Example 

import * as assert from "node:assert"
import { Iterable, Either } from "effect"


assert.deepStrictEqual(
  Array.from(Iterable.getRights([Either.right(1), Either.left("err"), Either.right(2)])),
  [1, 2]
)

getSomes

Since v2.0.0

Retrieves the Some values from an Iterable of Options.

Signature

declare const getSomes: <A>(self: Iterable<Option<A>>) => Iterable<A>

Example 

import * as assert from "node:assert"
import { Iterable, Option } from "effect"


assert.deepStrictEqual(
  Array.from(Iterable.getSomes([Option.some(1), Option.none(), Option.some(2)])),
  [1, 2]
)

Folding

countBy

Since v3.16.0

Counts all the element of the given iterable that 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;
}

Example 

import { Iterable } from "effect"


const result = Iterable.countBy([1, 2, 3, 4, 5], n => n % 2 === 0)
console.log(result) // 2

reduce

Since v2.0.0

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;
}

scan

Since v2.0.0

Reduce 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

drop

Since v2.0.0

Drop a max number of elements from the start of an Iterable

Note. 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>;
}

size

Since v2.0.0

Return the number of elements in a Iterable.

Signature

declare function size<A>(self: Iterable<A>): number

take

Since v2.0.0

Keep only a max number of elements from the start of an Iterable, creating a new Iterable.

Note. 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>;
}

takeWhile

Since v2.0.0

Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new Iterable.

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>;
}

unsafeHead

Since v3.3.0

Get the first element of a Iterable, or throw an error if the Iterable is empty.

Signature

declare function unsafeHead<A>(self: Iterable<A>): A

Grouping

group

Since v2.0.0

Group equal, consecutive elements of an Iterable into NonEmptyArrays.

Signature

declare const group: <A>(self: Iterable<A>) => Iterable<NonEmptyArray<A>>

groupBy

Since v2.0.0

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

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>>;
}

groupWith

Since v2.0.0

Group 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

isEmpty

Since v2.0.0

Determine if an Iterable is empty

Signature

declare function isEmpty<A>(self: Iterable<A>): self is Iterable<never, any, any>

Example 

import * as assert from "node:assert"
import { isEmpty } from "effect/Iterable"


assert.deepStrictEqual(isEmpty([]), true);
assert.deepStrictEqual(isEmpty([1, 2, 3]), false);

Mapping

map

Since v2.0.0

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>;
}

Other

dedupeAdjacent

Since v2.0.0

Deduplicates adjacent elements that are identical.

Signature

declare const dedupeAdjacent: <A>(self: Iterable<A>) => Iterable<A>

dedupeAdjacentWith

Since v2.0.0

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>;
}

forEach

Since v2.0.0

Iterate over the Iterable applying f.

Signature

declare const forEach: {
  <A>(f: (a: A, i: number) => void): (self: Iterable<A>) => void;
  <A>(self: Iterable<A>, f: (a: A, i: number) => void): void;
}

intersperse

Since v2.0.0

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.

Signature

declare const intersperse: {
  <B>(middle: B): <A>(self: Iterable<A>) => Iterable<B | A>;
  <A, B>(self: Iterable<A>, middle: B): Iterable<A | B>;
}

Sequencing

flatMap

Since v2.0.0

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>;
}

flatMapNullable

Since v2.0.0

Signature

declare const flatMapNullable: {
  <A, B>(f: (a: A) => B | null | undefined): (self: Iterable<A>) => Iterable<NonNullable<B>>;
  <A, B>(self: Iterable<A>, f: (a: A) => B | null | undefined): Iterable<NonNullable<B>>;
}

flatten

Since v2.0.0

Flattens an Iterable of Iterables into a single Iterable

Signature

declare function flatten<A>(self: Iterable<Iterable<A, any, any>>): Iterable<A>

Splitting

chunksOf

Since v2.0.0

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>>;
}

Zipping

zip

Since v2.0.0

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]>;
}

zipWith

Since v2.0.0

Apply 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>;
}