Iterama is a utility library for working with iterables in JavaScript. It provides a variety of functions to create, transform, and consume iterables, making it easier to work with sequences of data in a functional programming style.
Creating Iterables
The `range` function creates an iterable that generates numbers within a specified range. In this example, it generates numbers from 1 to 4.
const { range } = require('iterama');
const iterable = range(1, 5);
console.log([...iterable]); // Output: [1, 2, 3, 4]Transforming Iterables
The `map` function transforms each element of an iterable using a provided function. In this example, it doubles each number in the iterable.
const { map } = require('iterama');
const iterable = [1, 2, 3, 4];
const doubled = map(x => x * 2, iterable);
console.log([...doubled]); // Output: [2, 4, 6, 8]Consuming Iterables
The `reduce` function consumes an iterable to produce a single value by applying a reducer function. In this example, it calculates the sum of the numbers in the iterable.
const { reduce } = require('iterama');
const iterable = [1, 2, 3, 4];
const sum = reduce((acc, x) => acc + x, 0, iterable);
console.log(sum); // Output: 10iter-tools is a comprehensive library for working with iterables in JavaScript. It offers a wide range of functions for creating, transforming, and consuming iterables, similar to iterama. However, iter-tools has a larger set of utilities and is more feature-rich.
Lodash is a popular utility library that provides a wide range of functions for working with arrays, objects, and other data types. While it is not focused solely on iterables, it includes many functions that can be used to manipulate sequences of data, making it a versatile alternative to iterama.
RxJS is a library for reactive programming using Observables, which can be thought of as a more powerful and flexible form of iterables. It provides a rich set of operators for creating, transforming, and consuming data streams, making it suitable for complex asynchronous data flows.
Composable functional (async) iterable helpers.
yarn add iterama
concatconcatAsyncdistinctdistinctAsyncfilterfilterAsyncforEachforEachAsynciterateiterateAsynclengthlengthAsyncmapmapAsyncrangerangeAsyncreducereduceAsyncscanscanAsyncskipskipAsyncslicesliceAsyncstartWithstartWithAsynctaketakeAsyncuniqueuniqueAsynczipzipAsynctoArraytoArrayAsynctoSettoSetAsynctoObjecttoObjectAsynctoMaptoMapAsyncIn 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:
{
*[Symbol.iterator]() {
for (let i = 0; i < 5; i++) {
yield i
}
}
}
and rangeAsync(5) is:
{
async *[Symbol.asyncIterator]() {
for (let i = 0; i < 5; i++) {
yield await Promise.resolve(i)
}
}
}
concatConcatenates multiple iterables.
const concat: <T>(...iterables: Iterable<T>[]) => Iterable<T>
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
concatAsyncConcatenates multiple async iterables.
const concatAsync: <T>(...iterables: AsyncIterable<T>[]) => AsyncIterable<T>
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
distinctDistincts (squashes repeatable) iterable values.
const distinct: <T>(iterable: Iterable<T>) => Iterable<T>
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
distinctAsyncDistincts (squashes repeatable) async iterable values.
const distinctAsync: <T>(iterable: AsyncIterable<T>) => AsyncIterable<T>
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
filterFilters iterable values.
type TFilterFn<T> = (arg: T, index: number) => boolean
const filter: <T>(filterFn: TFilterFn<T>) => (iterable: Iterable<T>) => Iterable<T>
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
filterAsyncFilters async iterable values.
type TFilterFnAsync<T> = (arg: T, index: number) => Promise<boolean> | boolean
const filterAsync: <T>(filterFn: TFilterFnAsync<T>) => (iterable: AsyncIterable<T>) => AsyncIterable<T>
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
forEachInvokes callback with iterable values.
type TForEachFn<T> = (value: T, i: number) => void
const forEach: <T>(forEachFn: TForEachFn<T>) => (iterable: Iterable<T>) => Iterable<T>
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
forEachAsyncInvokes callback with async iterable values.
type TForEachFnAsync<T> = (value: T, i: number) => Promise<void> | void
const forEachAsync: <T>(forEachFn: TForEachFnAsync<T>) => (iterable: AsyncIterable<T>) => AsyncIterable<T>
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
iterateProvides iterable iterator out of iterable.
const iterate: <T>(iterable: Iterable<T>): IterableIterator<T>
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
iterateAsyncProvides async iterable iterator out of async iterable.
const iterateAsync: <T>(iterable: AsyncIterable<T>): AsyncIterableIterator<T>
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
lengthReturns length of iterable, limited to Number.MAX_SAFE_INTEGER.
const length: <T>(iterable: Iterable<T>) => number
import { length, range } from 'iterama'
const iterable = range(5)
const result = length(iterable)
console.log(result)
// 5
lengthAsyncReturns length of async iterable, limited to Number.MAX_SAFE_INTEGER.
const lengthAsync: <T>(iterable: AsyncIterable<T>) => Promise<number>
import { lengthAsync, rangeAsync } from 'iterama'
const iterable = rangeAsync(5)
const result = await lengthAsync(iterable)
console.log(result)
// 5
mapMaps over iterable.
type TMapFn<T, R> = (value: T, i: number) => R
const map: <T, R>(mapFn: TMapFn<T, R>) => (iterable: Iterable<T>) => Iterable<R>
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
mapAsyncMaps over async iterable.
type TMapFnAsync<T, R> = (value: T, i: number) => Promise<R> | R
const mapAsync: <T, R>(mapFn: TMapFnAsync<T, R>) => (iterable: AsyncIterable<T>) => AsyncIterable<R>
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
rangeProvides iterable filled with numbers from zero to given length.
const range: (length: number) => Iterable<number>
import { range } from 'iterama'
const result = range(5)
for (const value of result) {
console.log(value)
}
// 0
// 1
// 2
// 3
// 4
rangeAsyncProvides async iterable filled with numbers from zero to given length.
const rangeAsync: (length: number) => AsyncIterable<number>
import { rangeAsync } from 'iterama'
const result = rangeAsync(5)
for await (const value of result) {
console.log(value)
}
// 0
// 1
// 2
// 3
// 4
reduceReduces over iterable.
type TReduceFn<T, R> = (acc: R, value: T, index: number) => R
const reduce: <T, R>(reduceFn: TReduceFn<T, R>, initial: R) => (iterable: Iterable<T>) => Iterable<R>
import { reduce, range } from 'iterama'
const iterable = range(5)
const reducer = (acc: number, value: number) => acc + value
const result = reduce(reducer, 0)(iterable)
console.log(result)
// 10
reduceAsyncReduces over async iterable.
type TReduceFnAsync<T, R> = (acc: R, value: T, index: number) => Promise<R> | R
const reduceAsync: <T, R>(reduceFn: TReduceFnAsync<T, R>, initial: Promise<R> | R) => (iterable: AsyncIterable<T>) => Promise<R>
import { reduceAsync, rangeAsync } from 'iterama'
const iterable = rangeAsync(5)
const reducer = (acc: number, value: number) => Promise.resolve(acc + value)
const result = await reduceAsync(reducer, Promise.resolve(0))(iterable)
console.log(result)
// 10
scanScans over iterable. Like reduce but returns iterable with values from every step.
type TScanFn<T, R> = (acc: R, value: T, index: number) => R
const scan: <T, R>(scanFn: TScanFn<T, R>, initial: R) => (iterable: Iterable<T>) => Iterable<R>
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
scanAsyncScans over async iterable. Like reduce but returns async iterable with values from every step.
type TScanFnAsync<T, R> = (acc: R, value: T, index: number) => Promise<R> | R
const scanAsync: <T, R>(scanFn: TScanFnAsync<T, R>, initial: Promise<R> | R) => (iterable: AsyncIterable<T>) => AsyncIterable<R>
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
skipSkips n first/last iterable values.
const skip: (n: number) => <T>(iterable: Iterable<T>) => Iterable<T>
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
skipAsyncSkips n first/last async iterable values.
const skipAsync: (n: number) => <T>(iterable: AsyncIterable<T>) => AsyncIterable<T>
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
sliceSlices iterable.
const slice: (from?: number, to?: number) => <T>(iterable: Iterable<T>) => Iterable<T>
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
sliceAsyncSlices async iterable.
const sliceAsync: (from?: number, to?: number) => <T>(iterable: AsyncIterable<T>) => AsyncIterable<T>
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
startWithStarts iterable with additional value.
const startWith: <T>(value: T) => (iterable: Iterable<T>) => Iterable<T>
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
startWithAsyncStarts async iterable with additional value.
const startWithAsync: <T>(value: T) => (iterable: AsyncIterable<T>) => AsyncIterable<T>
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
takeTakes n first/last iterable values.
const take: (n: number) => <T>(iterable: Iterable<T>) => Iterable<T>
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
takeAsyncTakes n first/last async iterable values.
const takeAsync: (n: number) => <T>(iterable: AsyncIterable<T>) => AsyncIterable<T>
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
uniqueTakes unique iterable values.
const unique: <T>(iterable: Iterable<T>) => Iterable<T>
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
uniqueAsyncTakes unique async iterable values.
const uniqueAsync: <T>(iterable: AsyncIterable<T>) => AsyncIterable<T>
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
zipZips (combines) multiple iterables.
const zip: <A, B>(iterable0: Iterable<A>, iterable1: Iterable<B>) => Iterable<[A, B]>
const zip: <A, B, C>(iterable0: Iterable<A>, iterable1: Iterable<B>, iterable2: Iterable<C>) => Iterable<[A, B, C]>
const zip: <A, B, C, D>(iterable0: Iterable<A>, iterable1: Iterable<B>, iterable2: Iterable<C>, iterable3: Iterable<D>) => Iterable<[A, B, C, D]>
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']
zipAsyncZips (combines) multiple async iterables.
const zipAsync: <A, B>(iterable0: AsyncIterable<A>, iterable1: AsyncIterable<B>) => AsyncIterable<[A, B]>
const zipAsync: <A, B, C>(iterable0: AsyncIterable<A>, iterable1: AsyncIterable<B>, iterable2: AsyncIterable<C>) => AsyncIterable<[A, B, C]>
const zipAsync: <A, B, C, D>(iterable0: AsyncIterable<A>, iterable1: AsyncIterable<B>, iterable2: AsyncIterable<C>, iterable3: AsyncIterable<D>) => AsyncIterable<[A, B, C, D]>
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']
toArrayConvert iterable into array.
const toArray: <T>(iterable: Iterable<T>) => T[]
import { toArray, range } from 'iterama'
const iterable = range(5)
const result = toArray(iterable)
console.log(result)
// [0, 1, 2, 3, 4]
toArrayAsyncConvert async iterable into array.
const toArrayAsync: <T>(iterable: AsyncIterable<T>) => Promise<T[]>
import { toArrayAsync, rangeAsync } from 'iterama'
const iterable = rangeAsync(5)
const result = await toArrayAsync(iterable)
console.log(result)
// [0, 1, 2, 3, 4]
toSetConvert iterable into Set.
const toSet: <T>(iterable: Iterable<T>) => Set<T>
import { toSet, range } from 'iterama'
const iterable = range(5)
const result = toSet(iterable)
console.log(result)
// Set(5) [ 0, 1, 2, 3, 4 ]
toSetAsyncConvert async iterable into Set.
const toSetAsync: <T>(iterable: AsyncIterable<T>) => Promise<Set<T>>
import { toSetAsync, rangeAsync } from 'iterama'
const iterable = rangeAsync(5)
const result = await toSetAsync(iterable)
console.log(result)
// Set(5) [ 0, 1, 2, 3, 4 ]
toObjectConvert iterable filled with entries into object.
const toObject: <K extends PropertyKey, V>(iterable: Iterable<readonly [K, V]>) => { [key in K]: V }
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,
// }
toObjectAsyncConvert async iterable filled with entries into object.
const toObject: <K extends PropertyKey, V>(iterable: AsyncIterable<readonly [K, V]>) => Promise<{ [key in K]: V }>
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,
// }
toMapConvert iterable filled with entries into Map.
const toMap: <K, V>(iterable: Iterable<readonly [K, V]>) => Map<K, V>
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
// }
toMapAsyncConvert async iterable filled with entries into Map.
const toMapAsync: <K, V>(iterable: AsyncIterable<readonly [K, V]>) => Promise<Map<K, V>>
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
// }
FAQs
Composable functional (async) iterable helpers
The npm package iterama receives a total of 28,474 weekly downloads. As such, iterama popularity was classified as popular.
We found that iterama demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.