Iterable.ts overview
This module provides utility functions for working with Iterables in TypeScript.
Since v2.0.0
Exports Grouped by Category
- concatenating
- constructors
- conversions
- elements
- filtering
- folding
- getters
- grouping
- guards
- mapping
- sequencing
- splitting
- utils
- zipping
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>
}
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>
}
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>
}
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>
}
Since v2.0.0
constructors
empty
Signature
declare const empty: <A = never>() => Iterable<A>
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>
Since v2.0.0
of
Constructs a new Iterable<A>
from the specified value.
Signature
declare const of: <A>(a: A) => Iterable<A>
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>
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> }
Since v2.0.0
unfold
Signature
declare const unfold: <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>) => Iterable<A>
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]>
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]>
}
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>
}
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 }
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
}
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>
}
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>
}
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
}
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>
}
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>
}
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>
}
Since v2.0.0
getLefts
Retrieves the Left
values from an Iterable
of Either
s.
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>
Since v2.0.0
getRights
Retrieves the Right
values from an Iterable
of Either
s.
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>
Since v2.0.0
getSomes
Retrieves the Some
values from an Iterable
of Option
s.
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>
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
}
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
}
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>
}
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>
}
Since v2.0.0
head
Get the first element of a Iterable
, or None
if the Iterable
is empty.
Signature
declare const head: <A>(self: Iterable<A>) => Option<A>
Since v2.0.0
size
Return the number of elements in a Iterable
.
Signature
declare const size: <A>(self: Iterable<A>) => number
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>
}
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>
}
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
Since v3.3.0
grouping
group
Group equal, consecutive elements of an Iterable
into NonEmptyArray
s.
Signature
declare const group: <A>(self: Iterable<A>) => Iterable<NonEmptyArray<A>>
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>>
}
Since v2.0.0
groupWith
Group equal, consecutive elements of an Iterable
into NonEmptyArray
s 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>>
}
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>
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>
}
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>
}
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>>
}
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>
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>>
}
Since v2.0.0
utils
dedupeAdjacent
Deduplicates adjacent elements that are identical.
Signature
declare const dedupeAdjacent: <A>(self: Iterable<A>) => Iterable<A>
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>
}
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
}
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>
}
Since v2.0.0
zipping
zip
Takes two Iterable
s 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]>
}
Since v2.0.0
zipWith
Apply a function to pairs of elements at the same index in two Iterable
s, 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>
}
Since v2.0.0