zilt is a TypeScript lazy iterator library. It lets you create iterators with useful utility methods for declarative-style data processing. The library uses ES6 generators under the hood and has no dependencies.
Some great iterator libraries already exist, why create another one?
- To learn about ES6 generators
- To learn about creating, publishing and maintaining open-source libraries
- For fun
npm install zilt// ESM
import * as zilt from "zilt";
// CommonJS
const zilt = require("zilt");Let's consider the following exercise: given a non-empty height * width matrix full of .'s, draw a zigzag pattern of O's inside the matrix and return it. This is a contrived example, but it helps demonstrate the capabilities of zilt iterators.
const input = [
[".", ".", ".", ".", ".", ".", ".", ".", "."],
[".", ".", ".", ".", ".", ".", ".", ".", "."],
[".", ".", ".", ".", ".", ".", ".", ".", "."],
[".", ".", ".", ".", ".", ".", ".", ".", "."],
];
const output = [
["O", ".", ".", "O", ".", ".", "O", ".", "."],
["O", ".", "O", "O", ".", "O", "O", ".", "O"],
["O", "O", ".", "O", "O", ".", "O", "O", "."],
["O", ".", ".", "O", ".", ".", "O", ".", "."],
];To visit the cells that need to be replaced with an O, we want to iterate over matrix positions starting from [0, 0] moving either down or to the top right at each iteration.
With [ystep, xstep] denoting a vertical ystep move + a horizontal xstep move, the step algorithm can be described as follows:
height - 1vertical steps down ([ystep, xstep] = [1, 0]) are taken to reach the bottom of the matrixheight - 1diagonal steps to the top right ([ystep, xstep] = [-1, 1]) are taken to reach the top again- Repeat
We can create a zilt iterator over the infinite step sequence from above using the .stretch() and .cycle() methods.
function draw(matrix, height, width) {
const down = [1, 0];
const up = [-1, 1];
const steps = zilt.iter([down, up]) // [down, up]
.stretch(height - 1) // [down * (height - 1), up * (height - 1)]
.cycle(); // repeat the above to infinity
...
}From there, we just need to initialize some matrix coordinates to [0, 0] and apply each directional step to it in order to loop over the relevant cells and overwrite their content with O's. Since the iterator loops indefinitely, we need to make sure to stop the drawing loop once the current coordinate is out of the matrix bounds.
function draw(matrix, height, width) {
const down = [1, 0];
const up = [-1, 1];
const steps = zilt
.iter([down, up])
.stretch(height - 1)
.cycle();
let [y, x] = [0, 0];
for (const [ystep, xstep] of steps) {
if (x >= width) break;
matrix[y][x] = "O";
[y, x] = [y + ystep, x + xstep];
}
return matrix;
}I would advise against writing code in this style, but here's another way of solving this problem using zilt exclusively.
function draw(matrix, height, width) {
const down = [1, 0];
const up = [-1, 1];
const steps = zilt
.iter([down, up])
.stretch(height - 1)
.cycle();
zilt.once([0, 0])
.chain(steps)
.accumulate(([y, x], [ys, xs]) => [y + ys, x + xs])
.takeWhile(([_, x]) => x < width)
.forEach(([y, x]) => (matrix[y][x] = "O"));
return matrix;
}Creates an iterator from an iterable.
// [0, 1, 2]
zilt.iter([0, 1, 2]).collect();Creates an iterator over a single value.
// [['hello']]
zilt.once(["hello"]).collect();Creates an iterator over a range of numbers (end excluded).
zilt.range().collect(); // [0, 1, ...] (infinite)
zilt.range(1, 4).collect(); // [1, 2, 3]
zilt.range(3, 0).collect(); // [3, 2, 1]
zilt.range(4).collect(); // [0, 1, 2, 3]
zilt.range(-4).collect(); // [0, -1, -2, -3]Creates an iterator that yields the values of each passed iterable in sequence.
// [0, 1, 'foo']
zilt.chain([0, 1], ["foo"]).collect();Creates an iterator over n-tuples from "merging" n iterators together.
// [[0, 6, "foo"], [1, 7, "bar"]]
zilt.zip([0, 1], [6, 7], ["foo", "bar"]).collect();Consumes the iterator to collect its values in an array and returns it.
// [0, 1, 2]
zilt.range(0, 3).collect();Consumes the iterator, invoking the provided function for each element.
// prints 0, 1, 2
zilt.range(0, 3).forEach((n, i) => console.log(n));Partially consumes the iterator and returns the first element for which the predicate is true. Returns undefined if none was found.
// 6
zilt.iter([7, 11, 3, 6, 5]).find((n) => n % 2 === 0);Partially consumes the iterator and returns the index of the first element for which the predicate is true. Returns undefined if none was found.
// 3
zilt.iter([7, 11, 3, 6, 5]).position((n) => n % 2 === 0);Consumes the iterator to produce a single value using a given function.
// 6
zilt.range(0, 4).reduce((acc, n) => acc + n);
// 7
zilt.range(0, 4).reduce((acc, n) => acc + n, 1);
// '0123'
zilt.range(0, 4).reduce((acc, n) => acc + n.toString(), "");Consumes the iterator and returns the number of elements that match a predicate.
// 3
const arr = [10, 15, 15, 20];
zilt.iter(arr).count(); // 4
zilt.iter(arr).count((n) => n === 15); // 2Partially consumes the iterator and returns its nth element (0-indexed).
zilt.iter([1, 2, 3]).nth(2); // 3Partially consumes the iterator and returns its first element.
zilt.iter([1, 2, 3]).first(); // 1Consumes the iterator and returns its last element.
zilt.iter([1, 2, 3]).last(); // 3Consumes the iterator and returns the element for which the getKey function result is the minimum.
zilt.iter([3, 6, 4, 1, 8]).min((n) => n); // 1
zilt.iter([3, 6, 4, 1, 8]).min((n) => -n); // 8Consumes the iterator and returns the element for which the getKey function result is the maximum.
zilt.iter([3, 6, 4, 1, 8]).max((n) => n); // 8
zilt.iter([3, 6, 4, 1, 8]).max((n) => -n); // 1Consumes the iterator and returns true if any element satisfies the predicate.
zilt.iter([1, 1, 2]).some((n) => n === 2); // true
zilt.iter([1, 1, 1]).some((n) => n === 2); // falseConsumes the iterator and returns true if every element satisfies the predicate.
zilt.iter([1, 2, 2]).every((n) => n === 2); // false
zilt.iter([2, 2, 2]).every((n) => n === 2); // trueConsumes an iterator over n-tuples and returns n arrays.
// [[0, 1, 2], [3, 4, 5]]
zilt.iter([
[0, 3],
[1, 4],
[2, 5],
]).unzip();Consumes the iterator and returns a pair of arrays.
- the first array contains all elements for which the predicate is true
- the second array contains all elements for which the predicate is false
// [[2, 4], [1, 3]]
zilt.iter([1, 2, 3, 4]).partition((n) => n % 2 === 0);Consumes the iterator.
// void
zilt.range(0, 3).consume();Creates an iterator yielding values with an index counter starting from 0.
// [[4, 0], [5, 1], [6, 2]]
zilt.iter([4, 5, 6]).enumerate().collect();Creates an iterator which uses a callback to determine if an element should be yielded.
// [1, 3]
zilt.range(0, 4)
.filter((n) => n % 2 === 1)
.collect();Creates an iterator that transforms each value in the original iterator using the passed function parameter.
// [0, 2, 4, 6]
zilt.range(0, 4)
.map((n) => n * 2)
.collect();Creates an iterator which flattens nested array elements up to a certain depth (maxDepth).
NOTE: this method only accepts number literals for the
maxDepthparameter in order to correctly infer the output iterator element type.
const array = [
[0, 1],
[2, [3]],
];
// [0, 1, 2, [3]]
zilt.iter(arr).flat(1).collect();
// [0, 1, 2, 3]
zilt.iter(arr).flat(2).collect();Creates an iterator which is equivalent to .map().flat(1)
// [1, -1, 2, -2]
zilt.iter([1, 2])
.flatMap((n) => [n, -n])
.collect();Creates an iterator which only keeps the first num values.
// [0, 1, 2]
zilt.range(0, 6).take(3).collect();Creates an iterator which yields values until a predicate is false.
// [0, 1, 2]
zilt.range(0, 6)
.takeWhile((n) => n < 3)
.collect();Creates an iterator which skips the first num values.
// [3, 4, 5]
zilt.range(0, 6).skip(3).collect();Creates an iterator which skips values while a predicate is true.
// [3, 4, 5]
zilt.range(0, 6)
.skipWhile((n) => n < 3)
.collect();Creates an iterator which only yields elements from start to end (excluded). It is equivalent to .skip(start).take(end - start).
// [1, 2]
zilt.iter([0, 1, 1, 2, 3]).slice(2, 4).collect();Creates an iterator that yields values by steps of step starting from the first element.
// [1, 4, 7]
zilt.range(1, 10).step(3).collect();Creates an iterator that extends the current iterator with the values of each passed iterable in sequence.
// [0, 'foo', 'bar']
zilt.iter([0]).chain(["foo"], ["bar"]).collect();Creates an iterator that repeats the current iterator count times. count defaults to Infinity.
// [1, 2, 3, 1, 2, 3]
zilt.range(1, 4).cycle(2).collect();
// [1, 2, 3, 1, 2, 3, 1, 2]
zilt.range(1, 4).cycle().take(8).collect();Creates an iterator that repeats each value of the current iterator count times.
// [1, 1, 2, 2, 3, 3]
zilt.iter([1, 2, 3]).stretch(2).collect();Creates an iterator which repeats the provided iterable for each element in the current iterator. Elements are yielded as pairs.
NOTE: prefer using
.nest(start, end)instead of.nest(range(start, end))to avoid the unnecessary buffering of iterable values.
// [[0, 'a'], [0, 'b'], [1, 'a'], [1, 'b']]
zilt.range(2).nest(["a", "b"]).collect();
// [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2]]
zilt.range(2).nest(3).collect();
// [[0, 0], [0, -1], [1, 0], [1, -1]]
zilt.range(2).nest(0, -2).collect();Creates an iterator over n-tuples from "merging" n iterators together.
// [[0, 6, "foo"], [1, 7, "bar"]]
zilt.iter([0, 1]).zip([6, 7], ["foo", "bar"]).collect();Creates an iterator which yields elements by chunks of k.
// [[0, 1], [2, 3], [4]]
zilt.iter([0, 1, 2, 3, 4]).chunks(2).collect();Creates an iterator which yields every consecutive k-element window.
// [[0, 1], [1, 2], [2, 3], [3, 4]]
zilt.iter([0, 1, 2, 3, 4]).windows(2).collect();Creates an iterator which updates and yields an accumulator using the provided function (similar to reduce, but yields the accumulator at every step instead of returning the final accumulator value).
// [0, 1, 3, 6, 10]
zilt.range(0, 5)
.accumulate((acc, n) => acc + n)
.collect();Creates an iterator which filters out duplicate values.
// [0, 1, 2, 3, 4]
zilt.iter([0, 1, 1, 2, 3, 2, 4]).unique().collect();Creates an iterator which filters out duplicate values using a getKey function.
// [0, 1, 2, 3, 4]
zilt.iter([0, 1, 1, 2, 3, 2, 4])
.uniqueBy((n) => n)
.collect();Creates an iterator that invokes a callback on each element before yielding.
// [1, 10, 2, 20, 3, 30]
const out: number[] = [];
zilt.range(1, 4)
.inspect((n) => out.push(n))
.map((n) => n * 10)
.inspect((n) => out.push(n))
.consume();Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!