Skip to content

Iterable

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

48 exports Added in v2.0.0 Source

Concatenating

append

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Signature

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

makeBy

Added in v2.0.0 Source

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

of

Added in v2.0.0 Source

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

Signature

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

range

Added in v2.0.0 Source

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

replicate

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Signature

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

Conversions

fromRecord

Added in v2.0.0 Source

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

Elements

cartesian

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Retrieves the Left values from an Iterable of Eithers.

Signature

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

getRights

Added in v2.0.0 Source

Retrieves the Right values from an Iterable of Eithers.

Signature

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

getSomes

Added in v2.0.0 Source

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

Added in v3.16.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Return the number of elements in a Iterable.

Signature

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

take

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v3.3.0 Source

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

Added in v2.0.0 Source

Group equal, consecutive elements of an Iterable into NonEmptyArrays.

Signature

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

groupBy

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Determine if an Iterable is empty

Signature

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

Mapping

map

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Deduplicates adjacent elements that are identical.

Signature

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

dedupeAdjacentWith

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Flattens an Iterable of Iterables into a single Iterable

Signature

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

Splitting

chunksOf

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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