@ricokahler/lazy Β· 
A small (~600B gzip*), useful set of methods for lazy iteration of iterables.
Why this lazy lib?
- Small size (~600B gzipped)
- Simple, modern
for...of-only implementations. (Read the source here) - Only ships useful* methods
*Useful is a keyword here because this library only ships with iterable methods that can take advantage of chained lazy iteration.
What that boils down to is shipping methods that never have to exhaust the iterable in order to yield the next item.
An example of this would be a reverse() method. If this lib implemented a reverse() method, it would have to buffer the items received from the iterable into an array to be able to yield the items in reverse.
Since we have to buffer the items into an array anyway, there's not all that much difference between:
Lazy.from(iterable).reverse(); // not implemented!
and
Lazy.from(iterable).to(Array).reverse();
This constraint has some mental model benefits too. If you find yourself frequently needing to convert your iterable to an array, then there's a good chance lazy evaluation is not giving you much benefit.
Do I even need a lazy lib?
In order to take full advantage of the short-circuiting nature of call-by-need/lazy-evaluation, your Lazy expression should either:
- terminate in short-circuiting method
- take (via
takeortakeWhile) a subset of the iterable
Installation
npm i @ricokahler/lazy
Usage
Both ESM and CJS are supported in this package.
// esm
import Lazy from '@ricokahler/lazy';
// common-js
const Lazy = require('@ricokahler/lazy');
You can then:
- chain the methods like arrays:
const result = Lazy.from([1, 2, 3])
.map((x) => x + 1)
.filter((x) => x >= 3)
.first();
console.log(result); // 3
- Or use the static method counterparts:
let iterable = Lazy.from([1, 2, 3]);
iterable = Lazy.map(iterable, (x) => x + 1);
iterable = Lazy.filter(iterable, (x) => x >= 3);
const result = Lazy.first(iterable);
console.log(result); // 3
Method Reference
Short-circuiting, terminating methods
Conversion methods
Lazy.from |
π
Takes in any iterable and returns it wrapped in a Lazy with chainable Lazy methods.
// static method only
Lazy.from<T>(iterable: Iterable<T>): Lazy<T>
Note: this is equivalent to calling new Lazy(iterable)
to |
π
Writes the iterable into another data structure. Accepts an object with a from method that accepts an iterable (e.g. Array.from) or a constructor that accepts an iterable.
The implementation is as follows:
function to(iterable, constructorOrFromable) {
if (typeof constructorOrFromable.from === 'function') {
return constructorOrFromable.from(iterable);
}
return new constructorOrFromable(iterable);
}
Lazy<T>.to<TInstance>(fromable: {from: (iterable: Iterable<T>) => TInstance}): TInstance
Lazy<T>.to<TInstance>(constructor: {new (iterable: Iterable<T>) => TInstance}): TInstance
Chainable methods
map |
π
Takes in an iterable and returns an iterable generator that yields the result of the callback function on each item from the input iterable.
Lazy<T>.map<R>(mapper: (t: T) => R): Lazy<R>
filter |
π
Takes in an iterable and returns an iterable generator that yields the accepted elements of the given callback function.
Lazy<T>.filter<R extends T>(accept: (t: T) => t is R): Lazy<R>
Lazy<T>.filter<R extends T>(accept: (t: T) => t is R): Lazy<R>
flat |
π
Returns a new iterable with all sub-iterable items yielded into it recursively up to the specified depth.
Lazy<T>.flat<TDepth extends number>(depth?: TDepth): Lazy<Flattened<T, TDepth>>
flatMap |
π
Calls the result of the given callback function on each item of the parent iterable. Then, yields the result of each into a flatted iterable. This is identical to a map followed by flat with depth 1.
Lazy<T>.flatMap<R>(mapper: (value: T) => R | Iterable<R>): Lazy<R>
take |
π
Yields the first n items of the given iterable and stops further iteration.
const result = Lazy.from([1, 2, 3, 4, 5]).take(3).to(Array);
console.log(result); // [1, 2, 3]
Lazy<T>.take(n: number): Lazy<T>
takeWhile |
π
Yields while the callback function accepts the current item from the given iterable. Iteration finishes as soon as an item is rejected by the callback.
const result = Lazy.from([1, 2, 3, 4, 5, 0, 1])
.takeWhile((n) => n <= 2)
.to(Array);
console.log(result); // [1, 2]
Lazy<T>.takeWhile<R extends T>(accept: (t: T) => t is R): Lazy<R>
Lazy<T>.takeWhile(accept: (t: T) => unknown): Lazy<T>
skip |
π
Skips over the first n items of the given iterable then yields the rest.
const result = Lazy.from([1, 2, 3, 4, 5]).skip(2).to(Array);
console.log(result); // [3, 4, 5]
Lazy<T>.skip(n: number): Lazy<T>
skipWhile |
π
Skips over the items while the given callback accepts the current item from the given iterable, then yields the rest.
const result = Lazy.from([1, 2, 3, 4, 5, 0, 1])
.skipWhile((n) => n <= 2)
.to(Array);
console.log(result); // [3, 4, 5, 0, 1]
Lazy<T>.skip(n: number): Lazy<T>
Short-circuiting, terminating methods
includes |
π
Determines whether an iterable includes a certain value using === comparison. Short-circuits iteration once the value is found.
Lazy<T>.includes(t: T): boolean
first |
π
Returns the first item of an iterable or undefined if the iterable is done/exhausted.
Lazy<T>.first(): T | undefined
find |
π
Returns the first item accepted by the given callback. Short-circuits iteration once an item is found.
Lazy<T>.find<R extends T>(accept: (t: T) => t is R): R | undefined
Lazy<T>.find(accept: (t: T) => unknown): T | undefined
some |
π
Returns true if at least one item accepted by the given callback. Short-circuits iteration once an item is accepted.
Lazy<T>.some(accept: (t: T) => unknown): boolean
every |
π
Returns true only if all items are accepted by the given callback. Short-circuits iteration once an item is rejected.
Lazy<T>.every(accept: (t: T) => unknown): boolean
571 Dec 30, 2022
96 Dec 20, 2022
3 May 18, 2022
4 May 3, 2022
14 Jan 3, 2023
11 Aug 15, 2022
3 Oct 15, 2022
3 May 20, 2022
66 Jan 1, 2023
170 Dec 19, 2022
5 Jul 25, 2022
2 Oct 3, 2022
22.7k Jan 9, 2023
7 Aug 16, 2022
7 Jul 31, 2022
2 Mar 10, 2022
2.6k Jan 9, 2023
7.1k Jan 2, 2023
1 Feb 10, 2022