pragmatic-streams

Set of pragmatic operations on iterables.

• full documentation can be found on https://andres-kovalev.github.io/pragmatic-streams/
• few demo examples can be found in playground

Description

pragmatic-streams provides utility functions to operate with iterable structures (like arrays and iterators). There operators are similar to native array functions (like filter, map, reduce etc). There are just two differences:

• stream operators are lazy, which means all calculations performed only when needed.
• stream operators supports are curried (support partial application), so they can be combined to get more complex operators.

Installation

As any other npm package pragmatic-streams can be added to your project by following command:

npm i -S pragmatic-streams

API

There are several stream operators provided by this package:

• create
• distinct
• distinctUntilChanged
• distinctUntilChangedShallow
• distinctUntilChangedStrict
• every
• filter
• last
• map
• reduce
• reduceWith
• scan
• scanWith
• skip
• some
• take
• takeWhile

Most stream operators consumes at least 1 argument - iterable value. For instance, filter operator lets us to filter out some values, when map operator transforms each item of input iterable. Both returns new iterable:

import { filter, map } from 'pragmatic-streams';

const source = [ 1, 2, 3, 4, 5, 6 ];

const isOdd = item => (item & 1);
const add2 = item => item + 2;

const filtered = filter(isOdd, source); // [ 1, 3, 5 ]
const transformed = map(add2, source); // [ 3, 4, 5, 6, 7, 8 ];

const filteredAndTransformed = map(add2, filter(isOdd, source)); // [ 3, 5, 7 ]

As we mentioned before, all operators supports partial application:

const filterOdd = filter(item => (item & 1));
const add2 = map(item => item + 2);

const filtered = filterOdd(source); // [ 1, 3, 5 ]
const transformed = add2(source); // [ 3, 4, 5, 6, 7, 8 ];

const filteredAndTransformed = add2(filterOdd(source)); // [ 3, 5, 7 ]

As you can see, behavior is similar to native Array.prototype.filter() and Array.prototype.map(), so why we need this operators? Since stream operators supports partial application, they can be combined:

import { filter, map, pipe } from 'pragmatic-streams';

...

const filterAndTransform = pipe(
    filter(isOdd),
    map(add2),
);

const filteredAndTransformed = filterAndTransform(source);

Also stream operators are lazy, which means they can improve performance when combined. Each operator pulls data from previous one, so if last one need only certain amount of items, it will call previous operator accordingly:

const source = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ];

// native example
...
const first3 = (_, index) => index < 3;

const result = source
    .filter(isOdd) // will call isOdd() function 10 times (for each item)
    .map(add2) // will call add2() function 5 times (for each filtered item)
    .filter(first3); // will call first3() function 5 times (for each filtered item)

// stream example
import { filter, map, take, pipe } from 'pragmatic-streams';

...

const complexOperator(
    filter(isOdd), // will call isOdd() function only until we get 3 items (5 times)
                   // because of take(3)
    map(add2),     // will call add2() function only 3 times
    take(3)        // tooks only 3 first items, so filter
);

const result = complexOperator(source);

All operators returns iterators, so we can use result only once:

...
const result = complexOperator(source);

for(let item of result) {
    console.log(item); // will print 3, 5 and 7
}

for(let item of result) {
    console.log(item); // won't print anything
}

So, if we need to re-use result, we should store data by, for instance, converting iterator into an array:

const result = [ ...complexOperator(source) ];

for(let item of result) {
    console.log(item); // will print 3, 5 and 7
}

for(let item of result) {
    console.log(item); // will print 3, 5 and 7 again
}

There are several helpful functions provided to make work with partially applied operators easier:

• curry
• pipe