README
js-xiterable
Make ES6 Iterators Functional Again
Synopsis
Suppose we have a generator like this.
function* count(n) {
for (let i = 0; i < n; i++) yield i;
};
We make it more functional like this.
import {Xiterable} from './xiterable.js';
const xcount = n => new Xiterable(() => count(n));
const tens = xcount(10);
const odds = tens.filter(v=>v%2).map(v=>v*v);
const zips = tens.zip(odds);
[...tens]; // [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
[...odds]; // [ 1, 9, 25, 49, 81]
[...zips]; // [[0, 1], [1, 9], [2, 25], [3, 49], [4, 81]]
In other words, this module make any iterables work like Array
, with .map
, .filter
and so on.
Install
npm install js-xiterable
Usage
locally
import {
Xiterable,
xiterable, zip, zipWith, xrange, repeat
} from './xiterable.js';
remotely
import {Xiterable} from 'https://cdn.jsdelivr.net/npm/js-xiterable@0.1.7/xiterable.min.js';
commonjs (node.js)
% node -r esm
Welcome to Node.js v14.5.0.
Type ".help" for more information.
> import * as $X from 'js-xiterable'
undefined
> $X
[Module] {
Xiterable: [Function: Xiterable],
isIterable: [Function: isIterable],
repeat: [Function: repeat],
version: '0.0.3',
xiterable: [Function: xiterable],
xrange: [Function: xrange],
zip: [Function: zip],
zipWith: [Function: zipWith]
}
> [...$X.xrange().take(10).filter(v=>v%2).map(v=>v*v)]
[ 1, 9, 25, 49, 81 ]
>
Description
This module makes any given iterables behave like an array with all functional methods like .map()
, .filter()
, .reduce()
and so on. But for methods that Array.prototype
returns an instance of Array
, an instace of Xiterable
is returned. An Xiterable
instance are:
like an instance of
Array
that has.map()
,.filter()
,.reduce()
…unlike an instance of
Array
that demands the storage for elements. Elements are generated on demand.
[...Array(1e9).keys()].slice(0,10) // gets stuck with a billion elements
[...xrange(1e9).slice(0,10)] // same expected result instantly.
All elements are lazily generated. They are not generated until needed.
That is why .filter marks the result infinite, even though it is finite. You cannot estimate the number of elements until you apply the predicate function.
constructor
from any built-in iterables...
new Xiterable([0,1,2,3]);
new Xiterable('0123');
new Xiterable(new Uint8Array([0,1,2,3]))
or your custom generator (with no argument)...
let it = new Xiterable(function *() {
for (let i = 0; true; i++) yield i;
});
[...it.take(8)]; // [ 0, 1, 2, 3, 4, 5, 6, 7]
[...it.take(8).reversed()] // throws TypeError;
Generators are treated as an infinite iterable. But you can override it by giving its length for the 2nd argument and the implentation of nth
for the 3rd argument. see .nth() and .map() for more example.
let it = new Xiterable(function *() {
for (let i = 0; true; i++) yield i;
}, Number.POSIVE_INFINITY, n => n);
it.nth(42); // 42
it.take(42).reversed().nth(0) // 41
A factory function is also exported as xiterable
.
import {xiterable as $X} from 'js-xiterable';
$X('01234567').zip('abcdefgh').map(v=>v.join('')).toArray(); /* [
'0a', '1b', '2c', '3d', '4e', '5f', '6g', '7h'
] */
Instance Methods and Properties
.toArray()
Returns [...this]
unless this
is infinite, in which case throws RangeError
. It is longer than [...this]
but slightly safer.
.nth()
.nth(n)
returns the nth element of this
if the original itertor has .nth
or Array-like (can access nth element via [n]
. In which case nth()
is auto-generated).
Unlike [n]
, .nth(n)
accepts BigInt
and negatives.
let it = xiterable('javascript');
it.nth(0); // 'j'
it.nth(0n); // 'j'
it.nth(9); // 't'
it.nth(-1); // 't'
it.nth(-1n); // 't'
it.nth(-10); // 'j'
It raises exceptions on infinite (and indefinite) iterables
it = xiterable(function*(){ for(;;) yield 42 }); // infinite
[...it.take(42)]; // Array(42).fill(42)
it.nth(0); // throws TypeError;
it = xiterable('javascript');
it = it.filter(v=>!new Set('aeiou').has(v)); // indefinite
[...it]; // ['j', 'v', 's', 'c', 'r', 'p', 't']
it.nth(0); // throws TypeError;
BigInt
is sometimes necessary when you deal with large -- combinatorially large -- iterables like js-combinatorics handles.
import * as $C from 'js-combinatorics';
let it = xiterable(new $C.Permutation('abcdefghijklmnopqrstuvwxyz'));
it = it.map(v=>v.join(''));
it.nth(0); // 'abcdefghijklmnopqrstuvwxyz'
it.nth(-1); // 'zyxwvutsrqponmlkjihgfedcba'
it.nth(403291461126605635583999999n) === it.nth(-1); // true
.length
The (maximum) number of elements in the iterable. For infinite (or indefinite iterables like the result of .filter()
) Number.POSITIVE_INFINITY
is set.
xrange().length; // Number.POSITIVE_INFINITY
xrange().take(42).length // 42
xrange().take(42).filter(v=>v%2).length; // Number.POSITIVE_INFINITY
The number can be BigInt
for very large iterable.
it = xiterable(new $C.Permutation('abcdefghijklmnopqrstuvwxyz'));
it.lenth; // 403291461126605635584000000n
You can tell if the iterable is infinite or indefinite via .isEndless
.
xrange().isEndless; // true
xrange().take(42).isEndless // false
xrange().take(42).filter(v=>v%2).isEndless; // true
.map()
.map(fn, thisArg?)
works just like Array.prototype.map
except:
.map
of this module works with infinite iterables.if
this
is finite with working.nth
, the resulting iterable is also reversible with.reversed
and random-accissible via.nth
.
it = xiterable(function*(){ let i = 0; for(;;) yield i++ });
[...it.map(v=>v*v).take(8)] // [0, 1, 4, 9, 16, 25, 36, 49]
it.nth(42); // throws TypeError
it = xiterable(it.seed, it.length, n=>n); // installs nth
it.nth(42); // 41
.filter()
.filter(fn, thisArg?)
works just like Array.prototype.filter
except:
.filter
of this module works with infinite iterables.unlike .map() the resulting iterable is always marked infinite because there is no way to know its length lazily, that is, prior to iteration. See .length for more examples.
it = xiterable('javascript');
it.length; // 10
it = it.filter(v=>!new Set('aeiou').has(v));
it.length; // Number.POSITIVE_INFINITY
[...it].length; // 7
[...it] // [ 'j', 'v', 's', 'c', 'r', 'p', 't' ]
.mapFilter()
.mapFilter(fn, thisArg?)
works just like .filter()
but instead of dropping elements, it is replaced with undefined
. That way the number of elements remains unchanged so you can use .nth()
and .reversed()
.
it = xiterable('javascript');
it.length; // 10
it = it.mapFilter(v=>!new Set('aeiou').has(v));
it.length; // 10
[...it].length; // 10
[...it]; /* [
'j', undefined, 'v', undefined,
's', 'c', 'r', undefined, 'p', 't'
] */
.take()
.take(n)
returns an iterable with the first n
elements from this
.
If n <= this.length
it is a no-op.
[...xrange().take(8)]; // [0, 1, 2, 3, 4, 5, 6, 7]
[...xrange().take(4).take(8)]; // [0, 1, 2, 3]
.drop()
.drop(n)
returns an iterable without the first n
elements from this
.
If n <= this.length
an empty iterable is returned.
[...xrange(8).drop(4)]; // [4, 5, 6, 7]
[...xrange(4).drop(8)]; // []
Note the infinite iterable remains infinite even after you .drop(n)
xrange().drop(8).length; // Number.POSITIVE_INFINITY
[...xrange().drop(8).take(4)]; // [ 8, 9, 10, 11 ]
.takeWhile()
.takeWhile(fn, thisArg?)
returns an iterable with which iterates till fn
is no longer true
. Similar to .filter but unlinke .filter()
the iterator terminates at the first element where fn()
returns false.
let it = xiterable('javascript');
let fn = v=>!new Set('aeiou').has(v);
[...it.filter(fn)]; // ['j', 'v', 's', 'c', 'r', 'p', 't']
[...it.takeWhile(fn)]; // ['j']
.filled()
.filled(value)
returns an iterator with all elements replaced with value
. See also Xiterable.repeat.
.reversed()
.reversed()
returns an iterator that returns elements in reverse order. this
must be finite and random-accesible via .nth()
or exception is thrown.
[...xrange().take(4).reversed()]; // [3, 2, 1, 0]
[...xrange().reversed()]; // throws RangeError
.zip()
.zip(...args)
zips iterators in the args
. Static version also available.
[...Xiterable.xrange().zip('abcd')] // [[0,"a"],[1,"b"],[2,"c"],[3,"d"]]
Array.prototype
Instance methods found in The following methods in Array.prototype
are supported as follows. For any method meth
, [...iter.meth(arg)]
deeply equals to [...iter].meth(arg)
.
method | available? | Comment |
---|---|---|
concat | ✔︎ | |
copyWithin | ❌ | mutating |
entries | ✔︎ | |
every | ✔︎ | |
fill | ❌ | mutating ; see .filled |
filter | ✔︎ | see filter |
find | ✔︎ | |
findIndex | ✔︎ | |
flat | ✔︎ | |
flatMap | ✔︎ | |
forEach | ✔︎ | |
includes | ✔︎* | * throws RangeError on infinite iterables if the 2nd arg is negative |
indexOf | ✔︎* | * throws RangeError on infinite iterables if the 2nd arg is negative |
join | ✔︎ | |
keys | ✔︎ | |
lastIndexOf | ✔︎* | * throws RangeError on infinite iterables if the 2nd arg is negative |
map | ✔︎ | see map |
pop | ❌ | mutating |
push | ❌ | mutating |
reduce | ✔︎* | * throws RangeError on infinite iterables |
reduceRight | ✔︎* | * throws RangeError on infinite iterables |
reverse | ❌ | mutating. See reversed |
shift | ❌ | mutating |
slice | ✔︎* | * throws RangeError on infinite iterables if any of the args is negative |
some | ✔︎ | |
sort | ❌ | mutating |
splice | ❌ | mutating |
unshift | ❌ | mutating |
filter | ✔︎ |
Mutating functions (functions that change
this
) are deliberately made unavailable. e.g.pop
,push
…Functions that need toiterate backwards do not work on infinite iterables. e.g.
lastIndexOf()
,reduceRight()
…
Static methods
They are also exported so you can:
import {repeat,xrange,zip,zipWith} from 'js-xiterable'
Examples below assumes
import {Xiterable} from 'js-xiterable'.
Examples below assumes
Xiterable.zip
Zips iterators in the argument.
[...Xiterable.zip('0123', 'abcd')] // [[0,"a"],[1,"b"],[2,"c"],[3,"d"]]
Xiterable.zipWith
Zips iterators and then feed it to the function.
[...Xiterable.zipWith((a,b)=>a+b, 'bcdfg', 'aeiou')] // ["ba","ce","di","fo","gu"]
Xiterable.xrange
xrange()
as Python 2 (or range()
of Python 3).
for (const i of Xiterable.xrange()){ // infinite stream of 0, 1, ...
console.log(i)
}
[...Xiterable.xrange(4)] // [0, 1, 2, 3]
[...Xiterable.xrange(1,5)] // [1, 2, 3, 4]
[...Xiterable.xrange(1,5,2)] // [1, 3]
Xiterable.repeat
Returns an iterator with all elements are the same.
for (const i of Xiterable.repeat('spam')) { // infinite stream of 'spam'
console.log(i)
}
[...Xiterable.repeat('spam', 4)] // ['spam', 'spam', 'spam', 'spam']