#<Sawyer::Resource:0x00007fbac98da410>

Basic operations on iterables

Description

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).

We also do not use ES6 generators internally, because their current implementation in V8 is relatively slow.

Programming language: TypeScript

License: MIT License

Tags: Editors     TypeScript     JavaScript     Iterable     Iterator    

README

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).

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

• API List below, plus Full API
• Recipes, for additional operations
• [Benchmarks], for performance comparison

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.
• split - splits values into separate lists - see Split.
• spread - spreads iterable values.
• start - starts emitting, once the predicate returns a truthy value.
• stop - stops emitting, once the predicate returns a truthy value.
• take - emits up to certain number of values.
• takeLast - emits up to certain number of the last values.
• 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.

See also:

• Full API - generated from code
• [Asynchronous Operators](./src/ops/async) - specific for asynchronous iterables
• Recipes - for more operations.