README
iter-ops
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
);
(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 an iterable, applies all specified operators to it, and returns an extended iterable.
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.
- 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.
- 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 - specific for asynchronous iterables
- Recipes - for more operations.