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

Iterable overview

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

Added in v2.0.0

Table of contents

concatenating

append

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

Signature

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

Added in v2.0.0

appendAll

Concatenates two iterables, combining their elements.

Signature

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

Added in v2.0.0

prepend

Prepend an element to the front of an Iterable, creating a new Iterable.

Signature

export declare const prepend: {
  <B>(head: B): <A>(self: Iterable<A>) => Iterable<A | B>
  <A, B>(self: Iterable<A>, head: B): Iterable<A | B>
}

Added in v2.0.0

prependAll

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

Signature

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

Example

import { Iterable } from "effect"

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

Added in v2.0.0

constructors

empty

Signature

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

Added in 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.

Signature

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

Example

import { makeBy } from "effect/Iterable"

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

Added in v2.0.0

of

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

Signature

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

Added in 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.

Signature

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

Example

import { range } from "effect/Iterable"

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

Added in v2.0.0

replicate

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

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

Signature

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

Example

import { replicate } from "effect/Iterable"

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

Added in v2.0.0

unfold

Signature

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

Added in v2.0.0

conversions

fromRecord

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

Signature

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

Example

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

Added in v2.0.0

elements

cartesian

Zips this Iterable crosswise with the specified Iterable.

Signature

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

Added in v2.0.0

cartesianWith

Zips this Iterable crosswise with the specified Iterable using the specified combiner.

Signature

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

Added in v2.0.0

contains

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

Signature

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

Added in v2.0.0

containsWith

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

Signature

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

Added in v2.0.0

findFirst

Returns the first element that satisfies the specified predicate, or None if no such element exists.

Signature

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

Added in v2.0.0

findLast

Find the last element for which a predicate holds.

Signature

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

Added in v2.0.0

some

Check if a predicate holds true for some Iterable element.

Signature

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

Added in v2.0.0

filtering

filter

Signature

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

Added in v2.0.0

filterMap

Signature

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

Added in v2.0.0

filterMapWhile

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

Signature

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

Added in v2.0.0

getLefts

Retrieves the Left values from an Iterable of Eithers.

Signature

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

Example

import { Iterable, Either } from "effect"

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

Added in v2.0.0

getRights

Retrieves the Right values from an Iterable of Eithers.

Signature

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

Example

import { Iterable, Either } from "effect"

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

Added in v2.0.0

getSomes

Retrieves the Some values from an Iterable of Options.

Signature

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

Example

import { Iterable, Option } from "effect"

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

Added in v2.0.0

folding

reduce

Signature

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

Added in v2.0.0

scan

Reduce an Iterable from the left, keeping all intermediate results instead of only the final result.

Signature

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

Added in 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

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

Added in v2.0.0

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

Signature

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

Added in v2.0.0

size

Return the number of elements in a Iterable.

Signature

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

Added in 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

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

Added in v2.0.0

takeWhile

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

Signature

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

Added in v2.0.0

unsafeHead

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

Signature

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

Added in v3.3.0

grouping

group

Group equal, consecutive elements of an Iterable into NonEmptyArrays.

Signature

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

Added in 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

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

Added in v2.0.0

groupWith

Group equal, consecutive elements of an Iterable into NonEmptyArrays using the provided isEquivalent function.

Signature

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

Added in v2.0.0

guards

isEmpty

Determine if an Iterable is empty

Signature

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

Example

import { isEmpty } from "effect/Iterable"

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

Added in v2.0.0

mapping

map

Signature

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

Added in 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

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

Added in v2.0.0

flatMapNullable

Signature

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

Added in v2.0.0

flatten

Flattens an Iterable of Iterables into a single Iterable

Signature

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

Added in 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

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

Added in v2.0.0

utils

dedupeAdjacent

Deduplicates adjacent elements that are identical.

Signature

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

Added in v2.0.0

dedupeAdjacentWith

Deduplicates adjacent elements that are identical using the provided isEquivalent function.

Signature

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

Added in v2.0.0

forEach

Iterate over the Iterable applying f.

Signature

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

Added in 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

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

Added in v2.0.0

zipping

zip

Takes two Iterables and returns an Iterable of corresponding pairs.

Signature

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

Added in 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

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

Added in v2.0.0