Skip to main content Link Search Menu Expand Document (external link)
effect

Iterable.ts overview

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

Since v2.0.0

Exports Grouped by Category

concatenating

append

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<A | B>
  <A, B>(self: Iterable<A>, last: B): Iterable<A | B>
}

Source

Since v2.0.0

appendAll

Concatenates two iterables, combining their elements.

Signature

declare const appendAll: {
  <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Iterable<A | B>
  <A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<A | B>
}

Source

Since v2.0.0

prepend

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<A | B>
  <A, B>(self: Iterable<A>, head: B): Iterable<A | B>
}

Source

Since v2.0.0

prependAll

Prepends the specified prefix iterable to the beginning of the specified iterable.

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

Signature

declare const prependAll: {
  <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Iterable<A | B>
  <A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<A | B>
}

Source

Since v2.0.0

constructors

empty

Signature

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

Source

Since v2.0.0

makeBy

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.

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

Signature

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

Source

Since v2.0.0

of

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

Signature

declare const of: <A>(a: A) => Iterable<A>

Source

Since v2.0.0

range

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

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

Example

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

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

Signature

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

Source

Since v2.0.0

replicate

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

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

Example

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

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

Signature

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

Source

Since v2.0.0

unfold

Signature

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

Source

Since v2.0.0

conversions

fromRecord

Takes a record and returns an Iterable of tuples containing its keys and values.

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

Signature

declare const fromRecord: <K extends string, A>(self: Readonly<Record<K, A>>) => Iterable<[K, A]>

Source

Since v2.0.0

elements

cartesian

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

Source

Since v2.0.0

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

Source

Since v2.0.0

contains

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 }

Source

Since v2.0.0

containsWith

Returns a function that checks if an Iterable contains a given value using a provided isEquivalent function.

Signature

declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boolean) => {
  (a: A): (self: Iterable<A>) => boolean
  (self: Iterable<A>, a: A): boolean
}

Source

Since v2.0.0

findFirst

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 extends A>(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 extends A>(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>
}

Source

Since v2.0.0

findLast

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 extends A>(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 extends A>(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>
}

Source

Since v2.0.0

some

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
}

Source

Since v2.0.0

filtering

filter

Signature

declare const filter: {
  <A, B extends A>(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 extends A>(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>
}

Source

Since v2.0.0

filterMap

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

Source

Since v2.0.0

filterMapWhile

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

Source

Since v2.0.0

getLefts

Retrieves the Left values from an Iterable of Eithers.

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

Signature

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

Source

Since v2.0.0

getRights

Retrieves the Right values from an Iterable of Eithers.

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

Signature

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

Source

Since v2.0.0

getSomes

Retrieves the Some values from an Iterable of Options.

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

Signature

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

Source

Since v2.0.0

folding

countBy

Counts all the element of the given iterable that pass the given predicate

Example

import { Iterable } from "effect"

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

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
}

Source

Since v3.16.0

reduce

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
}

Source

Since v2.0.0

scan

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

Source

Since v2.0.0

getters

drop

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

Source

Since v2.0.0

Get the first element of a Iterable, or None if the Iterable is empty.

Signature

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

Source

Since v2.0.0

size

Return the number of elements in a Iterable.

Signature

declare const size: <A>(self: Iterable<A>) => number

Source

Since v2.0.0

take

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

Source

Since v2.0.0

takeWhile

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

Signature

declare const takeWhile: {
  <A, B extends A>(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 extends A>(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>
}

Source

Since v2.0.0

unsafeHead

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

Signature

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

Source

Since v3.3.0

grouping

group

Group equal, consecutive elements of an Iterable into NonEmptyArrays.

Signature

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

Source

Since v2.0.0

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

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

Source

Since v2.0.0

groupWith

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<NonEmptyArray<A>>
  <A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Iterable<NonEmptyArray<A>>
}

Source

Since v2.0.0

guards

isEmpty

Determine if an Iterable is empty

Example

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

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

Signature

declare const isEmpty: <A>(self: Iterable<A>) => self is Iterable<never>

Source

Since v2.0.0

mapping

map

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

Source

Since v2.0.0

sequencing

flatMap

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

Source

Since v2.0.0

flatMapNullable

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

Source

Since v2.0.0

flatten

Flattens an Iterable of Iterables into a single Iterable

Signature

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

Source

Since v2.0.0

splitting

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.

Signature

declare const chunksOf: {
  (n: number): <A>(self: Iterable<A>) => Iterable<Array<A>>
  <A>(self: Iterable<A>, n: number): Iterable<Array<A>>
}

Source

Since v2.0.0

utils

dedupeAdjacent

Deduplicates adjacent elements that are identical.

Signature

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

Source

Since v2.0.0

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

Source

Since v2.0.0

forEach

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
}

Source

Since v2.0.0

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.

Signature

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

Source

Since v2.0.0

zipping

zip

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

Source

Since v2.0.0

zipWith

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

Source

Since v2.0.0