Obliterator
Obliterator is a dead simple JavaScript library providing miscellaneous higher-order iterator functions such as combining two or more iterators into a single one.
Installation
npm install --save obliterator
Usage
Summary
Classes
Functions
Iterator
A handy Iterator class with safeguards and usable with ES2015's for ... of
loop constructs & spread operator.
import Iterator from 'obliterator/iterator';
import {Iterator} from 'obliterator';
const iterator = new Iterator(function() {
});
Iterator.is(value);
const emptyIterator = Iterator.empty();
const simpleIterator = Iterator.of(34);
const multipleIterator = Iterator.of(1, 2, 3);
chain
Variadic function chaining all the given iterators.
import chain from 'obliterator/chain';
import {chain} from 'obliterator';
const set1 = new Set('a');
const set2 = new Set('bc');
const chained = chain(set1.values(), set2.values());
chained.next();
>>> {done: false, value: 'a'}
chained.next();
>>> {done: false, value: 'b'}
combinations
Returns an iterator of combinations of the given array and of the given size.
Note that for performance reasons, the yielded combination is always the same object.
import combinations from 'obliterator/combinations';
import {combinations} from 'obliterator';
const iterator = combinations(['A', 'B', 'C', 'D'], 2);
iterator.next().value;
>>> ['A', 'B']
iterator.next().value;
>>> ['A', 'C']
consume
Function consuming the given iterator fully or for n steps.
import consume from 'obliterator/consume';
import {consume} from 'obliterator';
const set = new Set([1, 2, 3]);
let iterator = set.values();
consume(iterator);
iterator.next().done
>>> true
let iterator = set.values();
consume(iterator, 2);
iterator.next().value
>>> 3
filter
Function returning an iterator filtering another one's values using the given predicate.
import filter from 'obliterator/filter';
import {filter} from 'obliterator';
const set = new Set([1, 2, 3, 4, 5]);
const even = x => x % 2 === 0;
const iterator = filter(even, set.values());
iterator.next().value
>>> 2
iterator.next().value
>>> 4
forEach
Function able to iterate over almost any JavaScript iterable value using a callback.
Supported values range from arrays, typed arrays, sets, maps, objects, strings, arguments, iterators, arbitrary iterables etc.
import forEach from 'obliterator/foreach';
import {forEach} from 'obliterator';
const set = new Set(['apple', 'banana']);
forEach(set.values(), (value, i) => {
console.log(i, value);
});
forEach('abc', (char, i) => ...);
forEach(map, (value, key) => ...);
map
Function returning an iterator mapping another one's values using the given function.
import map from 'obliterator/map';
import {map} from 'obliterator';
const set = new Set([1, 2, 3, 4, 5]);
const triple = x => x * 3;
const iterator = map(triple, set.values());
iterator.next().value
>>> 3
iterator.next().value
>>> 6
match
Function returning an iterator over the matches of a given regex applied to the target string.
import match from 'obliterator/match';
import {match} from 'obliterator';
const iterator = match(/t/, 'test');
iterator.next().value.index
>>> 0
iterator.next().value.index
>>> 3
permutations
Returns an iterator of permutations of the given array and of the given size.
Note that for performance reasons, the yielded permutation is always the same object.
import permutations from 'obliterator/permutations';
import {permutations} from 'obliterator';
let iterator = permutations([1, 2, 3]);
iterator.next().value
>>> [1, 2, 3]
iterator.next().value
>>> [1, 3, 2]
iterator = permutations(['A', 'B', 'C', 'D'], 2);
iterator.next().value;
>>> ['A', 'B']
iterator.next().value;
>>> ['A', 'C']
powerSet
Returns an iterator of sets composing the power set of the given array.
import powerSet from 'obliterator/power-set';
import {powerSet} from 'obliterator';
const iterator = powerSet(['A', 'B', 'C']);
iterator.next().value;
>>> []
iterator.next().value;
>>> ['A']
split
Returns an iterator over the splits of the target string, according to the given RegExp pattern.
import split from 'obliterator/split';
import {split} from 'obliterator';
const iterator = split(/;/g, 'hello;world;super');
iterator.next().value;
>>> 'hello'
iterator.next().value;
>>> 'world'
take
Function taking values from given iterator and returning them in an array.
import take from 'obliterator/take';
import {take} from 'obliterator';
const set = new Set([1, 2, 3]);
take(set.values(), 2);
>>> [1, 2]
take(set.values());
>>> [1, 2, 3]
Contribution
Contributions are obviously welcome. Please be sure to lint the code & add the relevant unit tests before submitting any PR.
git clone git@github.com:Yomguithereal/obliterator.git
cd obliterator
npm install
# To lint the code
npm run lint
# To run the unit tests
npm test
License
MIT