Basic operations on iterables
npm install iter-ops- About
- Installation
- Usage
- [API]
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.
``
$ npm i iter-ops
- Synchronous pipeline:
`ts
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:
`ts
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
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
[api]: #api
[short api]: #api
[full api]: https://vitaly-t.github.io/iter-ops
[error handling]: https://github.com/vitaly-t/iter-ops/wiki/Error-Handling
[iterable]: https://javascript.info/iterable
[iterables]: https://javascript.info/iterable
[array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
[wiki]: https://github.com/vitaly-t/iter-ops/wiki
[pipe]: http://vitaly-t.github.io/iter-ops/functions/pipe
[recipes]: https://github.com/vitaly-t/iter-ops/wiki/Recipes
[state]: https://github.com/vitaly-t/iter-ops/wiki/Iteration-State
[aggregates]: https://github.com/vitaly-t/iter-ops/wiki/Aggregates
[split]: https://github.com/vitaly-t/iter-ops/wiki/Split
[benchmarks]: ./benchmarks
[asynchronous iterables]: https://github.com/vitaly-t/iter-ops/wiki/Asynchronous-Iterables
[synchronous]: https://javascript.info/iterable
[asynchronous]: https://javascript.info/async-iterators-generators#async-iterables
[rationale]: https://github.com/vitaly-t/iter-ops/wiki/Rationale
[pipesync]: https://vitaly-t.github.io/iter-ops/functions/pipeSync
[pipeasync]: https://vitaly-t.github.io/iter-ops/functions/pipeAsync
[wiki pages]: https://github.com/vitaly-t/iter-ops/wiki
[iter-ops-extras]: https://github.com/vitaly-t/iter-ops-extras