obliterator
Advanced tools
The 'obliterator' npm package provides a set of utilities for working with iterables and iterators in JavaScript. It offers a variety of functions to manipulate, transform, and handle iterables efficiently.
Iterate
The 'iterate' function allows you to create an iterator from an iterable object like an array. This example demonstrates how to iterate over an array using the iterator's next() method.
const iterate = require('obliterator/iterate');
const array = [1, 2, 3, 4];
const iterator = iterate(array);
let result = iterator.next();
while (!result.done) {
console.log(result.value);
result = iterator.next();
}Range
The 'range' function generates an iterator that produces numbers within a specified range. This example shows how to create an iterator that yields numbers from 1 to 4.
const range = require('obliterator/range');
const iterator = range(1, 5);
let result = iterator.next();
while (!result.done) {
console.log(result.value);
result = iterator.next();
}Take
The 'take' function allows you to take a specified number of elements from an iterable. This example demonstrates how to take the first 3 elements from an array.
const take = require('obliterator/take');
const array = [1, 2, 3, 4, 5];
const result = take(array, 3);
console.log(result); // [1, 2, 3]Filter
The 'filter' function creates an iterator that yields only the elements that satisfy a given predicate. This example shows how to filter out odd numbers from an array.
const filter = require('obliterator/filter');
const array = [1, 2, 3, 4, 5];
const iterator = filter(array, x => x % 2 === 0);
let result = iterator.next();
while (!result.done) {
console.log(result.value);
result = iterator.next();
}The 'iter-tools' package provides a comprehensive set of utilities for working with iterables and iterators. It offers a wide range of functions for transforming, filtering, and combining iterables, similar to 'obliterator'. However, 'iter-tools' has a larger set of features and more extensive documentation.
The 'lazy.js' package is a utility library for working with lazy sequences. It allows you to create and manipulate sequences in a lazy manner, meaning computations are deferred until necessary. While 'lazy.js' offers similar functionalities to 'obliterator', it focuses more on lazy evaluation and chaining operations.
The 'lodash' package is a popular utility library that provides a wide range of functions for manipulating arrays, objects, and other data structures. Although 'lodash' is not specifically focused on iterables and iterators, it offers many similar functions for transforming and filtering data.
Obliterator is a dead simple JavaScript/TypeScript library providing miscellaneous higher-order iterator/iterable functions such as combining two or more iterators into a single one.
Note that when possible, obliterator also consider sequences such as arrays, strings etc. as valid iterables (although they are not proper ES6 iterables values), for convenience.
npm install --save obliterator
Note that obliterator comes along with its TypeScript declarations.
Classes
Functions
A handy Iterator class easily usable with ES2015's for ... of loop constructs & spread operator.
import Iterator from 'obliterator/iterator';
// Or
import {Iterator} from 'obliterator';
const iterator = new Iterator(function () {
// Define what the `next` function does
return {done: false, value: 34};
});
// Checking that the given value is an iterator (native or else)
Iterator.is(value);
// Creating an empty iterator
const emptyIterator = Iterator.empty();
// Creating a simple iterator from a single value
const simpleIterator = Iterator.of(34);
// Creating a simple iterator from multiple values
const multipleIterator = Iterator.of(1, 2, 3);
Variadic function chaining all the given iterable-like values.
import chain from 'obliterator/chain';
// Or
import {chain} from 'obliterator';
const set1 = new Set('a');
const set2 = new Set('bc');
const chained = chain(set1.values(), set2);
chained.next();
>>> {done: false, value: 'a'}
chained.next();
>>> {done: false, value: 'b'}
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';
// Or
import {combinations} from 'obliterator';
const iterator = combinations(['A', 'B', 'C', 'D'], 2);
iterator.next().value;
>>> ['A', 'B']
iterator.next().value;
>>> ['A', 'C']
Function consuming the given iterator fully or for n steps.
import consume from 'obliterator/consume';
// Or
import {consume} from 'obliterator';
const set = new Set([1, 2, 3]);
// Consuming the whole iterator
let iterator = set.values();
consume(iterator);
iterator.next().done >>> true;
// Consuming n steps
let iterator = set.values();
consume(iterator, 2);
iterator.next().value >>> 3;
Function returning whether all items of an iterable-like match the given predicate function.
import every from 'obliterator/every';
// Or
import {every} from 'obliterator';
every([2, 4, 6], n => n % 2 === 0);
>>> true
every([1, 2, 3], n => n % 2 === 0);
>>> false
Function returning an iterator filtering another one's values using the given predicate function.
import filter from 'obliterator/filter';
// Or
import {filter} from 'obliterator';
const set = new Set([1, 2, 3, 4, 5]);
const even = x => x % 2 === 0;
const iterator = filter(set.values(), even);
iterator.next().value >>> 2;
iterator.next().value >>> 4;
Function returning the next item matching given predicate function in an iterable-like.
import find from 'obliterator/find';
// Or
import {find} from 'obliterator';
const set = new Set([1, 2, 3, 4, 5]);
const even = x => x % 2 === 0;
const values = set.values();
find(values, even);
>>> 2
find(values, even);
>>> 4
find(values, even);
>>> undefined
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';
// Or
import {forEach} from 'obliterator';
const set = new Set(['apple', 'banana']);
forEach(set.values(), (value, i) => {
console.log(i, value);
});
// Iterating over a string
forEach('abc', (char, i) => ...);
// Iterating over a map
forEach(map, (value, key) => ...);
Variant of forEach one can use to iterate over mixed values but with the twist that iterables without proper keys (lists, sets etc.), will yield null instead of an index key.
Supported values range from arrays, typed arrays, sets, maps, objects, strings, arguments, iterators, arbitrary iterables etc.
import {forEachWithNullKeys} from 'obliterator/foreach';
const set = new Set(['apple', 'banana']);
forEach(set, (value, key) => {
console.log(key, value);
});
>>> null, 'apple'
>>> null, 'banana'
Function returning whether the given value can be found in given iterable-like.
import {includes} from 'obliterator';
// Or
import includes from 'obliterator/includes';
includes([1, 2, 3], 3);
>>> true;
includes('test', 'a');
>>> false;
Function casting any iterable-like value to a proper iterator. Will throw an error if the given value cannot be cast as an iterator.
import {iter} from 'obliterator';
// Or
import iter from 'obliterator/iter';
iter('test');
iter(new Set([1, 2, 3]));
// This will throw:
iter(null);
Function returning an iterator mapping another one's values using the given function.
import map from 'obliterator/map';
// Or
import {map} from 'obliterator';
const set = new Set([1, 2, 3, 4, 5]);
const triple = x => x * 3;
const iterator = map(set.values(), triple);
iterator.next().value >>> 3;
iterator.next().value >>> 6;
Function returning an iterator over the matches of a given regex applied to the target string.
import match from 'obliterator/match';
// Or
import {match} from 'obliterator';
const iterator = match(/t/, 'test');
iterator.next().value.index >>> 0;
iterator.next().value.index >>> 3;
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';
// Or
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']
Returns an iterator of sets composing the power set of the given array.
import powerSet from 'obliterator/power-set';
// Or
import {powerSet} from 'obliterator';
const iterator = powerSet(['A', 'B', 'C']);
iterator.next().value;
>>> []
iterator.next().value;
>>> ['A']
Returns whether the given iterable-like has some item matching the given predicate function.
import some from 'obliterator/some';
// Or
import {some} from 'obliterator';
some(new Set([1, 2, 3]), n => n % 2 === 0);
>>> true
some('test', c => c === 'a');
>>> false
Returns an iterator over the splits of the target string, according to the given RegExp pattern.
import split from 'obliterator/split';
// Or
import {split} from 'obliterator';
const iterator = split(/;/g, 'hello;world;super');
iterator.next().value;
>>> 'hello'
iterator.next().value;
>>> 'world'
Function taking values from given iterator and returning them in an array.
import take from 'obliterator/take';
// Or
import {take} from 'obliterator';
const set = new Set([1, 2, 3]);
// To take n values from the iterator
take(set.values(), 2);
>>> [1, 2]
// To convert the full iterator into an array
take(set.values());
>>> [1, 2, 3]
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
FAQs
Higher order iterator library for JavaScript/TypeScript.
We found that obliterator demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
License exceptions modify the terms of open source licenses, impacting how software can be used, modified, and distributed. Developers should be aware of the legal implications of these exceptions.
Security News
A developer is accusing Tencent of violating the GPL by modifying a Python utility and changing its license to BSD, highlighting the importance of copyleft compliance.
Security News
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.