Projektstart
This commit is contained in:
415
backend/node_modules/obliterator/README.md
generated
vendored
Normal file
415
backend/node_modules/obliterator/README.md
generated
vendored
Normal file
@@ -0,0 +1,415 @@
|
||||
[](https://github.com/Yomguithereal/obliterator/actions)
|
||||
|
||||
# Obliterator
|
||||
|
||||
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.
|
||||
|
||||
# Installation
|
||||
|
||||
```
|
||||
npm install --save obliterator
|
||||
```
|
||||
|
||||
Note that `obliterator` comes along with its TypeScript declarations.
|
||||
|
||||
# Usage
|
||||
|
||||
## Summary
|
||||
|
||||
_Classes_
|
||||
|
||||
- [Iterator](#iterator)
|
||||
|
||||
_Functions_
|
||||
|
||||
- [chain](#chain)
|
||||
- [combinations](#combinations)
|
||||
- [consume](#consume)
|
||||
- [every](#every)
|
||||
- [filter](#filter)
|
||||
- [find](#find)
|
||||
- [forEach](#foreach)
|
||||
- [forEachWithNullKeys](#foreachwithnullkeys)
|
||||
- [includes](#includes)
|
||||
- [iter](#iter)
|
||||
- [map](#map)
|
||||
- [match](#match)
|
||||
- [permutations](#permutations)
|
||||
- [powerSet](#powerSet)
|
||||
- [some](#some)
|
||||
- [split](#split)
|
||||
- [take](#take)
|
||||
|
||||
## Iterator
|
||||
|
||||
A handy Iterator class easily usable with ES2015's `for ... of` loop constructs & spread operator.
|
||||
|
||||
```js
|
||||
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);
|
||||
```
|
||||
|
||||
## chain
|
||||
|
||||
Variadic function chaining all the given iterable-like values.
|
||||
|
||||
```js
|
||||
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'}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
```js
|
||||
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']
|
||||
```
|
||||
|
||||
## consume
|
||||
|
||||
Function consuming the given iterator fully or for n steps.
|
||||
|
||||
```js
|
||||
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;
|
||||
```
|
||||
|
||||
## every
|
||||
|
||||
Function returning whether all items of an iterable-like match the given predicate function.
|
||||
|
||||
```js
|
||||
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
|
||||
```
|
||||
|
||||
## filter
|
||||
|
||||
Function returning an iterator filtering another one's values using the given predicate function.
|
||||
|
||||
```js
|
||||
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;
|
||||
```
|
||||
|
||||
## find
|
||||
|
||||
Function returning the next item matching given predicate function in an iterable-like.
|
||||
|
||||
```js
|
||||
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
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
```js
|
||||
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) => ...);
|
||||
```
|
||||
|
||||
## forEachWithNullKeys
|
||||
|
||||
Variant of [forEach](#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.
|
||||
|
||||
```js
|
||||
import {forEachWithNullKeys} from 'obliterator/foreach';
|
||||
|
||||
const set = new Set(['apple', 'banana']);
|
||||
|
||||
forEach(set, (value, key) => {
|
||||
console.log(key, value);
|
||||
});
|
||||
>>> null, 'apple'
|
||||
>>> null, 'banana'
|
||||
```
|
||||
|
||||
## includes
|
||||
|
||||
Function returning whether the given value can be found in given iterable-like.
|
||||
|
||||
```js
|
||||
import {includes} from 'obliterator';
|
||||
// Or
|
||||
import includes from 'obliterator/includes';
|
||||
|
||||
includes([1, 2, 3], 3);
|
||||
>>> true;
|
||||
|
||||
includes('test', 'a');
|
||||
>>> false;
|
||||
```
|
||||
|
||||
## iter
|
||||
|
||||
Function casting any iterable-like value to a proper iterator. Will throw an error if the given value cannot be cast as an iterator.
|
||||
|
||||
```js
|
||||
import {iter} from 'obliterator';
|
||||
// Or
|
||||
import iter from 'obliterator/iter';
|
||||
|
||||
iter('test');
|
||||
iter(new Set([1, 2, 3]));
|
||||
|
||||
// This will throw:
|
||||
iter(null);
|
||||
```
|
||||
|
||||
## map
|
||||
|
||||
Function returning an iterator mapping another one's values using the given function.
|
||||
|
||||
```js
|
||||
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;
|
||||
```
|
||||
|
||||
## match
|
||||
|
||||
Function returning an iterator over the matches of a given regex applied to the target string.
|
||||
|
||||
```js
|
||||
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;
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
```js
|
||||
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']
|
||||
```
|
||||
|
||||
## powerSet
|
||||
|
||||
Returns an iterator of sets composing the power set of the given array.
|
||||
|
||||
```js
|
||||
import powerSet from 'obliterator/power-set';
|
||||
// Or
|
||||
import {powerSet} from 'obliterator';
|
||||
|
||||
const iterator = powerSet(['A', 'B', 'C']);
|
||||
|
||||
iterator.next().value;
|
||||
>>> []
|
||||
iterator.next().value;
|
||||
>>> ['A']
|
||||
```
|
||||
|
||||
## some
|
||||
|
||||
Returns whether the given iterable-like has some item matching the given predicate function.
|
||||
|
||||
```js
|
||||
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
|
||||
```
|
||||
|
||||
## split
|
||||
|
||||
Returns an iterator over the splits of the target string, according to the given RegExp pattern.
|
||||
|
||||
```js
|
||||
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'
|
||||
```
|
||||
|
||||
## take
|
||||
|
||||
Function taking values from given iterator and returning them in an array.
|
||||
|
||||
```js
|
||||
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]
|
||||
```
|
||||
|
||||
# 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](LICENSE.txt)
|
||||
Reference in New Issue
Block a user