iterama !npm

Composable functional (async) iterable helpers.

Install

``sh
yarn add iterama
`

API

- iterama !npm
- Install
- API
- concat
- concatAsync
- distinct
- distinctAsync
- filter
- filterAsync
- forEach
- forEachAsync
- iterate
- iterateAsync
- length
- lengthAsync
- map
- mapAsync
- range
- rangeAsync
- reduce
- reduceAsync
- scan
- scanAsync
- skip
- skipAsync
- slice
- sliceAsync
- startWith
- startWithAsync
- take
- takeAsync
- unique
- uniqueAsync
- zip
- zipAsync
- toArray
- toArrayAsync
- toSet
- toSetAsync
- toObject
- toObjectAsync
- toMap
- toMapAsync
- toIterator
- toIteratorAsync
- toValue
- toValueAsync

In the examples below we use range() and rangeAsync() helpers whenever possible just to save space and reading time.

range(5) is the same as [0, 1, 2, 3, 4] array (because arrays are iterables too), or, in a more low-level manner:

`ts
{
*[Symbol.iterator]() {
for (let i = 0; i < 5; i++) {
yield i
}
}
}
`

and rangeAsync(5) is:

`ts
{
async *[Symbol.asyncIterator]() {
for (let i = 0; i < 5; i++) {
yield await Promise.resolve(i)
}
}
}
`

$3

Concatenates multiple iterables.

`ts
const concat: (iterables: Iterable>) => Iterable
`

`ts
import { concat } from 'iterama'

const iterable1 = [1, 2, 3]
const iterable2 = [4, 5, 6]
const result = concat([iterable1, iterable2])

for (const value of result)
console.log(value)
}
// 1
// 2
// 3
// 4
// 5
// 6
`

$3

Concatenates multiple async iterables.

`ts
const concatAsync: (iterables: Iterable>) => AsyncIterable
`

`ts
import { concatAsync } from 'iterama'

const iterable1 = {
async *[Symbol.asyncIterable]() {
for (let i = 1; i <= 3; i++) {
yield await Promise.resolve(i)
}
}
}
const iterable2 = {
async *[Symbol.asyncIterable]() {
for (let i = 4; i <= 6; i++) {
yield await Promise.resolve(i)
}
}
}
const result = concatAsync([iterable1, iterable2])

for await (const value of result)
console.log(value)
}
// 1
// 2
// 3
// 4
// 5
// 6
`

$3

Distincts (squashes repeatable) iterable values.

`ts
const distinct: (iterable: Iterable) => Iterable
`

`ts
import { distinct } from 'iterama'

const result = distinct([1, 1, 3, 3, 4, 3])

for (const value of result) {
console.log(value)
}
// 1
// 3
// 4
// 3

`


$3

Distincts (squashes repeatable) async iterable values.

`ts
const distinctAsync: (iterable: AsyncIterable) => AsyncIterable
`

`ts
import { distinctAsync } from 'iterama'

const iterable = {
async *[Symbol.asyncIterable]() {
yield await Promise.resolve(1)
yield await Promise.resolve(1)
yield await Promise.resolve(3)
yield await Promise.resolve(3)
yield await Promise.resolve(4)
yield await Promise.resolve(3)
}
}
const result = distinctAsync(iterable)

for await (const value of result) {
console.log(value)
}
// 1
// 3
// 4
// 3
`

$3

Filters iterable values.

`ts
type TFilterFn = (arg: T, index: number) => boolean

const filter: (filterFn: TFilterFn) => (iterable: Iterable) => Iterable
`

`ts
import { filter, range } from 'iterama'

const iterable = range(5)
const isEven = (x: number) => x % 2 === 0
const result = filter(isEven)(iterable)

for (const value of result) {
console.log(value)
}
// 0
// 2
// 4
`

$3

Filters async iterable values.

`ts
type TFilterFnAsync = (arg: T, index: number) => Promise | boolean

const filterAsync: (filterFn: TFilterFnAsync) => (iterable: AsyncIterable | Iterable) => AsyncIterable
`

`ts
import { filterAsync, rangeAsync } from 'iterama'

const iterable = rangeAsync(5)
const isEven = (x: number) => x % 2 === 0
const result = filterAsync(isEven)(iterable)

for await (const value of result) {
console.log(value)
}
// 0
// 2
// 4
`

$3

Invokes callback with iterable values.

`ts
type TForEachFn = (value: T, i: number) => void

const forEach: (forEachFn: TForEachFn) => (iterable: Iterable) => Iterable
`

`ts
import { forEach, range } from 'iterama'

const iterable = range(5)
const result = forEach(console.log)(iterable)

for (const value of result) {
console.log(value)
}
// 0 0
// 0
// 1 1
// 1
// 2 2
// 2
// 3 3
// 3
// 4 4
// 4
`

$3

Invokes callback with async iterable values.

`ts
type TForEachFnAsync = (value: T, i: number) => Promise | void

const forEachAsync: (forEachFn: TForEachFnAsync) => (iterable: AsyncIterable | Iterable) => AsyncIterable
`

`ts
import { forEachAsync, rangeAsync } from 'iterama'

const iterable = rangeAsync(5)
const result = forEachAsync(async (value, i) => {
await Promise.resolve()

console.log(value, i)
})(iterable)

for await (const value of result) {
console.log(value)
}
// 0 0
// 0
// 1 1
// 1
// 2 2
// 2
// 3 3
// 3
// 4 4
// 4
`

$3

Provides iterable iterator out of iterable.

`ts
const iterate: (iterable: Iterable): IterableIterator
`

`ts
import { iterate, range } from 'iterama'

const iterable = range(5)
const iterator = iterate(iterable)

console.log(iterator.next().value)
// 0
console.log(iterator.next().value)
// 1

for (const value of iterator) {
console.log(value)
}
// 2
// 3
// 4
`

$3

Provides async iterable iterator out of async iterable.

`ts
const iterateAsync: (iterable: AsyncIterable): AsyncIterableIterator
`

`ts
import { iterateAsync, rangeAsync } from 'iterama'

const iterable = rangeAsync(5)
const iterator = iterateAsync(iterable)

console.log((await iterator.next()).value)
// 0
console.log((await iterator.next()).value)
// 1

for await (const value of iterator) {
console.log(value)
}
// 2
// 3
// 4
`

$3

Returns length of iterable, limited to Number.MAX_SAFE_INTEGER.

`ts
const length: (iterable: Iterable) => number
`

`ts
import { length, range } from 'iterama'

const iterable = range(5)
const result = length(iterable)

console.log(result)
// 5
`

$3

Returns length of async iterable, limited to Number.MAX_SAFE_INTEGER.

`ts
const lengthAsync: (iterable: AsyncIterable) => Promise
`

`ts
import { lengthAsync, rangeAsync } from 'iterama'

const iterable = rangeAsync(5)
const result = await lengthAsync(iterable)

console.log(result)
// 5
`

$3

Maps over iterable.

`ts
type TMapFn = (value: T, i: number) => R

const map: (mapFn: TMapFn) => (iterable: Iterable) => Iterable
`

`ts
import { map } from 'iterama'

const iterable = range(5)
const mult2 = (x: number) => x * 2
const result = map(mult2)(iterable)

for (const value of result) {
console.log(value)
}
// 0
// 2
// 4
// 6
// 8
`

$3

Maps over async iterable.

`ts
type TMapFnAsync = (value: T, i: number) => Promise | R

const mapAsync: (mapFn: TMapFnAsync) => (iterable: AsyncIterable | Iterable) => AsyncIterable
`

`ts
import { mapAsync, rangeAsync } from 'iterama'

const iterable = rangeAsync(5)
const mult2 = (x: number) => Promise.resolve(x * 2)
const result = mapAsync(mult2)(iterable)

for await (const value of result) {
console.log(value)
}
// 0
// 2
// 4
// 6
// 8
`

$3

Provides iterable filled with numbers from zero to given length.

`ts
const range: (length: number) => Iterable
`

`ts
import { range } from 'iterama'

const result = range(5)

for (const value of result) {
console.log(value)
}
// 0
// 1
// 2
// 3
// 4
`

$3

Provides async iterable filled with numbers from zero to given length.

`ts
const rangeAsync: (length: number) => AsyncIterable
`

`ts
import { rangeAsync } from 'iterama'

const result = rangeAsync(5)

for await (const value of result) {
console.log(value)
}
// 0
// 1
// 2
// 3
// 4
`

$3

Reduces over iterable.

`ts
type TReduceFn = (acc: R, value: T, index: number) => R

const reduce: (reduceFn: TReduceFn, initial: R) => (iterable: Iterable) => Iterable
`

`ts
import { reduce, range } from 'iterama'

const iterable = range(5)
const reducer = (acc: number, value: number) => acc + value
const result = reduce(reducer, 0)(iterable)

for (const value of result) {
console.log(value)
}
// 10
`

$3

Reduces over async iterable.

`ts
type TReduceFnAsync = (acc: R, value: T, index: number) => Promise | R

const reduceAsync: (reduceFn: TReduceFnAsync, initial: Promise | R) => (iterable: AsyncIterable | Iterable) => AsyncIterable
`

`ts
import { reduceAsync, rangeAsync } from 'iterama'

const iterable = rangeAsync(5)
const reducer = (acc: number, value: number) => Promise.resolve(acc + value)
const result = reduceAsync(reducer, Promise.resolve(0))(iterable)

for await (const value of result) {
console.log(value)
}
// 10
`

$3

Scans over iterable. Like reduce but returns iterable with values from every step.

`ts
type TScanFn = (acc: R, value: T, index: number) => R

const scan: (scanFn: TScanFn, initial: R) => (iterable: Iterable) => Iterable
`

`ts
import { scan } from 'iterama'

const iterable = range(5)
const scanner = (acc: number, value: number) => Promise.resolve(acc + value)
const result = scan(scanner, 0)(iterable)

for (const value of result) {
console.log(value)
}
// 0
// 1
// 3
// 6
// 10
`

$3

Scans over async iterable. Like reduce but returns async iterable with values from every step.

`ts
type TScanFnAsync = (acc: R, value: T, index: number) => Promise | R

const scanAsync: (scanFn: TScanFnAsync, initial: Promise | R) => (iterable: AsyncIterable | Iterable) => AsyncIterable
`

`ts
import { scanAsync, rangeAsync } from 'iterama'

const iterable = rangeAsync(5)
const scanner = (acc: number, value: number) => Promise.resolve(acc + value)
const result = scanAsync(scanner, 0)(iterable)

for await (const value of result) {
console.log(value)
}
// 0
// 1
// 3
// 6
// 10
`

$3

Skips n first/last iterable values.

`ts
const skip: (n: number) => (iterable: Iterable) => Iterable
`

`ts
import { skip, range } from 'iterama'

const iterable1 = range(5)
const result1 = skip(2)(iterable1)

for (const value of result1) {
console.log(value)
}
// 2
// 3
// 4

const iterable2 = range(5)
const result2 = skip(-2)(iterable2)

for (const value of result2) {
console.log(value)
}
// 0
// 1
// 2

`


$3

Skips n first/last async iterable values.

`ts
const skipAsync: (n: number) => (iterable: AsyncIterable) => AsyncIterable
`

`ts
import { skipAsync, rangeAsync } from 'iterama'

const iterable1 = rangeAsync(5)
const result1 = skipAsync(2)(iterable1)

for await (const value of result1) {
console.log(value)
}
// 2
// 3
// 4

const iterable2 = rangeAsync(5)
const result2 = skipAsync(-2)(iterable2)

for await (const value of result2) {
console.log(value)
}
// 0
// 1
// 2
`

$3

Slices iterable.

`ts
const slice: (from?: number, to?: number) => (iterable: Iterable) => Iterable
`

`ts
import { slice, range } from 'iterama'

const iterable1 = range(5)
// skip 1, take 2
const result1 = slice(1, 2)(iterable1)

for (const value of result1) {
console.log(value)
}
// 1
// 2

const iterable2 = range(5)
// skip until 2 from end, take 1
const result2 = slice(-2, 1)(iterable2)

for (const value of result2) {
console.log(value)
}
// 3

const iterable3 = range(5)
// don't skip, take last 2
const result3 = slice(0, -2)(iterable3)

for (const value of result3) {
console.log(value)
}
// 0
// 1
// 2

const iterable4 = range(5)
// skip 2, take the rest
const result4 = slice(2)(iterable4)

for (const value of result4) {
console.log(value)
}
// 2
// 3
// 4

const iterable5 = range(5)
// skip until 2 from end, take the rest
const result5 = slice(-2)(iterable5)

for (const value of result4) {
console.log(value)
}
// 3
// 4

const iterable6 = range(5)
// don't skip, take all
const result6 = slice()(iterable6)

for (const value of result6) {
console.log(value)
}
// 0
// 1
// 2
// 3
// 4
`

$3

Slices async iterable.

`ts
const sliceAsync: (from?: number, to?: number) => (iterable: AsyncIterable) => AsyncIterable
`

`ts
import { sliceAsync, rangeAsync } from 'iterama'

const iterable1 = rangeAsync(5)
// skip 1, take 2
const result1 = sliceAsync(1, 2)(iterable1)

for await (const value of result1) {
console.log(value)
}
// 1
// 2

const iterable2 = rangeAsync(5)
// skip until 2 from end, take 1
const result2 = sliceAsync(-2, 1)(iterable2)

for await (const value of result2) {
console.log(value)
}
// 3

const iterable3 = rangeAsync(5)
// don't skip, take last 2
const result3 = sliceAsync(0, -2)(iterable3)

for await (const value of result3) {
console.log(value)
}
// 0
// 1
// 2

const iterable4 = rangeAsync(5)
// skip 2, take the rest
const result4 = sliceAsync(2)(iterable4)

for await (const value of result4) {
console.log(value)
}
// 2
// 3
// 4

const iterable5 = rangeAsync(5)
// skip until 2 from end, take the rest
const result5 = sliceAsync(-2)(iterable5)

for await (const value of result4) {
console.log(value)
}
// 3
// 4

const iterable6 = rangeAsync(5)
// don't skip, take all
const result6 = sliceAsync()(iterable6)

for await (const value of result6) {
console.log(value)
}
// 0
// 1
// 2
// 3
// 4
`

$3

Starts iterable with additional value.

`ts
const startWith: (value: T) => (iterable: Iterable) => Iterable
`

`ts
import { startWith, range } from 'iterama'

const iterable = range(5)
const result = startWith(-1)(iterable)

for (const value of result) {
console.log(value)
}
// -1
// 0
// 1
// 2
// 3
// 4
`

$3

Starts async iterable with additional value.

`ts
const startWithAsync: (value: T) => (iterable: AsyncIterable) => AsyncIterable
`

`ts
import { startWithAsync, rangeAsync } from 'iterama'

const iterable = rangeAsync(5)
const result = startWithAsync(-1)(iterable)

for await (const value of result) {
console.log(value)
}
// -1
// 0
// 1
// 2
// 3
// 4
`

$3

Takes n first/last iterable values.

`ts
const take: (n: number) => (iterable: Iterable) => Iterable
`

`ts
import { take, range } from 'iterama'

const iterable1 = range(5)
// take 2 first, skip the rest
const result1 = take(2)(iterable1)

for (const value of result1) {
console.log(value)
}
// 0
// 1

const iterable2 = range(5)
// take 2 last
const result2 = take(-2)(iterable2)

for (const value of result1) {
console.log(value)
}
// 3
// 4
`

$3

Takes n first/last async iterable values.

`ts
const takeAsync: (n: number) => (iterable: AsyncIterable) => AsyncIterable
`

`ts
import { takeAsync, rangeAsync } from 'iterama'

const iterable1 = rangeAsync(5)
// take 2 first, skip the rest
const result1 = takeAsync(2)(iterable1)

for await (const value of result1) {
console.log(value)
}
// 0
// 1

const iterable2 = rangeAsync(5)
// take 2 last
const result2 = takeAsync(-2)(iterable2)

for await (const value of result1) {
console.log(value)
}
// 3
// 4
`

$3

Takes unique iterable values.

`ts
const unique: (iterable: Iterable) => Iterable
`

`ts
import { unique } from 'iterama'

const iterable = {
*[Symbol.iterator]() {
yield 1
yield 1
yield 3
yield 4
yield 3
}
}
const result = unique(iterable)

for (const value of result) {
console.log(value)
}
// 1
// 3
// 4
`

$3

Takes unique async iterable values.

`ts
const uniqueAsync: (iterable: AsyncIterable) => AsyncIterable
`

`ts
import { uniqueAsync } from 'iterama'

const iterable = {
async *[Symbol.asyncIterator]() {
yield await Promise.resolve(1)
yield await Promise.resolve(1)
yield await Promise.resolve(3)
yield await Promise.resolve(4)
yield await Promise.resolve(4)
}
}
const result = uniqueAsync(iterable)

for await (const value of result) {
console.log(value)
}
// 1
// 3
// 4
`

$3

Zips (combines) multiple iterables.

`ts
const zip: (iterable0: Iterable, iterable1: Iterable) => Iterable<[A, B]>
const zip: (iterable0: Iterable, iterable1: Iterable, iterable2: Iterable) => Iterable<[A, B, C]>
const zip: (iterable0: Iterable, iterable1: Iterable, iterable2: Iterable, iterable3: Iterable) => Iterable<[A, B, C, D]>
`

`ts
import { zip, range } from 'iterama'

const iterable1 = range(5)
const iterable2 = {
*[Symbol.iteratior]() {
yield 'a'
yield 'b'
yield 'c'
yield 'd'
}
}
const result = zip(iterable1, iterable2)

for (const value of result) {
console.log(value)
}

// [0, 'a'],
// [1, 'b'],
// [2, 'c'],
// [3, 'd']
`

$3

Zips (combines) multiple async iterables.

`ts
const zipAsync: (iterable0: AsyncIterable, iterable1: AsyncIterable) => AsyncIterable<[A, B]>
const zipAsync: (iterable0: AsyncIterable, iterable1: AsyncIterable, iterable2: AsyncIterable) => AsyncIterable<[A, B, C]>
const zipAsync: (iterable0: AsyncIterable, iterable1: AsyncIterable, iterable2: AsyncIterable, iterable3: AsyncIterable) => AsyncIterable<[A, B, C, D]>
`

`ts
import { zipAsync, rangeAsync } from 'iterama'

const iterable1 = rangeAsync(5)
const iterable2 = {
async *[Symbol.asyncIteratior]() {
yield await Promise.resolve('a')
yield await Promise.resolve('b')
yield await Promise.resolve('c')
yield await Promise.resolve('d')
}
}
const result = zipAsync(iterable1, iterable2)

for await (const value of result) {
console.log(value)
}

// [0, 'a'],
// [1, 'b'],
// [2, 'c'],
// [3, 'd']
`

$3

Converts iterable into array.

`ts
const toArray: (iterable: Iterable) => T[]
`

`ts
import { toArray, range } from 'iterama'

const iterable = range(5)
const result = toArray(iterable)

console.log(result)
// [0, 1, 2, 3, 4]
`

$3

Converts async iterable into array.

`ts
const toArrayAsync: (iterable: AsyncIterable) => Promise
`

`ts
import { toArrayAsync, rangeAsync } from 'iterama'

const iterable = rangeAsync(5)
const result = await toArrayAsync(iterable)

console.log(result)
// [0, 1, 2, 3, 4]
`

$3

Converts iterable into Set.

`ts
const toSet: (iterable: Iterable) => Set
`

`ts
import { toSet, range } from 'iterama'

const iterable = range(5)
const result = toSet(iterable)

console.log(result)
// Set(5) [ 0, 1, 2, 3, 4 ]
`

$3

Converts async iterable into Set.

`ts
const toSetAsync: (iterable: AsyncIterable) => Promise>
`

`ts
import { toSetAsync, rangeAsync } from 'iterama'

const iterable = rangeAsync(5)
const result = await toSetAsync(iterable)

console.log(result)
// Set(5) [ 0, 1, 2, 3, 4 ]
`

$3

Converts iterable filled with entries into object.

`ts
const toObject: (iterable: Iterable) => { [key in K]: V }
`

`ts
import { toObject } from 'iterama'

const iterable = {
*[Symbol.iterator]() {
yield ['a', 0]
yield ['b', 1]
yield ['c', 2]
yield ['d', 3]
yield ['e', 4]
}
}
const result = toObject(iterable)

console.log(result)
// {
// a: 0,
// b: 1,
// c: 2,
// d: 3,
// e: 4,
// }
`

$3

Converts async iterable filled with entries into object.

`ts
const toObject: (iterable: AsyncIterable) => Promise<{ [key in K]: V }>
`

`ts
import { toObjectAsync } from 'iterama'

const iterable = {
async *[Symbol.asyncIterator]() {
yield await Promise.resolve(['a', 0])
yield await Promise.resolve(['b', 1])
yield await Promise.resolve(['c', 2])
yield await Promise.resolve(['d', 3])
yield await Promise.resolve(['e', 4])
}
}
const result = await toObjectAsync(iterable)

console.log(result)
// {
// a: 0,
// b: 1,
// c: 2,
// d: 3,
// e: 4,
// }
`

$3

Converts iterable filled with entries into Map.

`ts
const toMap: (iterable: Iterable) => Map
`

`ts
import { toMap } from 'iterama'

const iterable = {
*[Symbol.iterator]() {
yield ['a', 0]
yield ['b', 1]
yield ['c', 2]
yield ['d', 3]
yield ['e', 4]
}
}
const result = toMap(iterable)

console.log(result)
// Map {
// a → 0,
// b → 1,
// c → 2,
// d → 3,
// e → 4
// }
`

$3

Converts async iterable filled with entries into Map.

`ts
const toMapAsync: (iterable: AsyncIterable) => Promise>
`

`ts
import { toMapAsync } from 'iterama'

const iterable = {
async *[Symbol.asyncIterator]() {
yield await Promise.resolve(['a', 0])
yield await Promise.resolve(['b', 1])
yield await Promise.resolve(['c', 2])
yield await Promise.resolve(['d', 3])
yield await Promise.resolve(['e', 4])
}
}
const result = await toMapAsync(iterable)

console.log(result)
// Map {
// a → 0,
// b → 1,
// c → 2,
// d → 3,
// e → 4
// }
`

$3

Extracts iterator from iterable.

`ts
const toIterator: (iterable: Iterable) => Iterator
`

`ts
import { toIterator } from 'iterama'

const iterable = {
*[Symbol.iterator]() {
yield 1
yield 2
yield 3
}
}
const iterator = toIterator(iterable)
const result = [
iterator.next(),
iterator.next(),
iterator.next(),
iterator.next(),
]

console.log(result)
// [
// { value: 1, done: false },
// { value: 2, done: false },
// { value: 3, done: false },
// { value: undefined, done: true },
// ]
`

$3

Extracts async iterator from async iterable.

`ts
const toAsyncIterator: (iterable: AsyncIterable) => AsyncIterator
`

`ts
import { toIteratorAsync } from 'iterama'

const iterable = {
*[Symbol.asyncIterator]() {
yield Promise.resolve(1)
yield Promise.resolve(2)
yield Promise.resolve(3)
}
}
const iterator = toIteratorAsync(iterable)
const result = [
await iterator.next(),
await iterator.next(),
await iterator.next(),
await iterator.next(),
]

console.log(result)
// [
// { value: 1, done: false },
// { value: 2, done: false },
// { value: 3, done: false },
// { value: undefined, done: true },
// ]
`

$3

Extracts first value from iterable.

`ts
const toValue: (iterable: Iterable) => T | undefined
`

`ts
import { toValue } from 'iterama'

const iterable = {
*[Symbol.iterator]() {
yield 1
yield 2
}
}
const value = toValue(iterable)

console.log(result)
// 1
`

$3

Extracts first value from async iterable.

`ts
const toAsyncIterator: (iterable: AsyncIterable) => Promise
`

`ts
import { toValueAsync } from 'iterama'

const iterable = {
*[Symbol.asyncIterator]() {
yield Promise.resolve(1)
yield Promise.resolve(2)
}
}
const value = await toValueAsync(iterable)

console.log(value)
// 1
``