vitaly-t/iter-ops

iter-ops

• About
• Installation
• Usage
• API

About

Basic operations on synchronous + asynchronous iterables, strictly for JavaScript native types.

We do not use any synthetic types / wrappers here, like Observable in RXJS, etc. It is strictly an iterable on the input, and an iterable on the output, for maximum performance, simplicity and compatibility (see Rationale).

Related repo: iter-ops-extras - addition to the main API.

Installation

$ npm i iter-ops

Usage

• Synchronous pipeline:

import {pipe, filter, map} from 'iter-ops';

const input = [1, 2, 3, 4, 5];

const i = pipe(
    input,
    filter((a) => a % 2 === 0), // find even numbers
    map((value) => ({value})) // remap into objects
);

console.log(...i); //=> {value: 2}, {value: 4}

• Asynchronous pipeline:

import {pipe, toAsync, distinct, delay} from 'iter-ops';

const input = [1, 2, 2, 3, 3, 4];

const i = pipe(
    toAsync(input), // make asynchronous
    distinct(), // emit unique numbers
    delay(1000) // delay each value by 1s
);
// or you can replace `pipe` + `toAsync` with just `pipeAsync`

(async function () {
    for await (const a of i) {
        console.log(a); //=> 1, 2, 3, 4 (with 1s delay)
    }
})();

See also...

• Short API list below, plus Full API
• Benchmarks, for performance comparison
• WiKi Pages, for additional resources

API

Function pipe takes any iterable, applies all specified operators to it, and returns an extended iterable. For strict type of iterables, there are also pipeSync and pipeAsync.

Standard Operators:

All standard operators implement the same logic as Array does:

• concat - merges current iterable with multiple values, iterators or iterables.
• every - checks if all elements pass the predicate test.
• filter - standard filter processor, filtering by predicate.
• flat - flattens/expands sub-iterable elements.
• flatMap - remaps + flattens sub-iterable elements.
• map - standard mapping processor, remapping by predicate.
• reduce - standard reduce processor.
• some - checks if any element passes the predicate test.

Extended Operators:

• aggregate - executes an aggregate on accumulated values - see Aggregates.
• catchError - catches iteration errors - see Error Handling.
• count - counts values, and produces a one-value iterable.
• defaultEmpty - adds default to an empty iterable.
• distinct - emits unique values, with optional key selector.
• drain - drains the iterable, and then ends it.
• empty - produces an empty iterable.
• first - produces a one-value iterable, with the first emitted value.
• indexBy - emits indexed values that pass the predicate test.
• isEmpty - produces a one-value iterable, indicating if the source is empty.
• last - produces a one-value iterable, with the last emitted value.
• onEnd - notifies of the end of a successful iteration.
• page - splits values into pages of fixed size (last page can be smaller).
• repeat - repeats iterable values.
• skip - starts emitting values after certain count.
• skipUntil - skips until the predicate returns a truthy value.
• skipWhile - skips while the predicate returns a truthy value.
• split - splits values into separate lists - see Split.
• spread - spreads iterable values.
• take - emits up to certain number of values.
• takeLast - emits up to certain number of the last values.
• takeUntil - emits until the predicate returns a truthy value.
• takeWhile - emits while the predicate returns a truthy value.
• tap - taps into each value, without changing the output.
• timeout - ends iteration after N milliseconds.
• timing - measures timings for each value.
• toArray - accumulates values into an array.
• zip - zips values together, into an array.

Custom Operators:

See iter-ops-extras - a collection of custom operators (ones based on existing operators).

Resources:

• Short API list below, plus Full API
• Benchmarks, for performance comparison
• WiKi Pages, for additional resources