@wormss/genstack

Because I like Iterators and Generators, and I'm lazy
I think the technique is also called Lazy Evaluation.
I would recommend people use Streamjs or it's successor Sequency as more 'complete' packages,
I mostly concentrated on modifying iterators than generating or terminating them
and everything is chainable.

GenStack and AsyncGenStack are themselves iterable and iterators, to give the most interoperability with other packages and libraries.

``bash
npm i @wormss/genstack
`

Example

`js
const gen = AsyncGenStack.range({ start: 1 })
.map((pageNumber) => fetch(api/results/${pageNumber})) // call your paginated api
.runWhile((response) => response.ok) // quit if the response has an error code
.map((response) => response.json()) // download the body as json
.runUntil((body) => body.results.length === 0) // quit if the results are zero
.flatMap((body) => body.results) // turn array of results into individual results
.filter((value) => value.id === '') // throw some results away, because why not
.distinctBy((value) => value.date) // only take the first value per unique date
.merge([fakeItem]); // merge in more items at the end

for await (const message of gen) {
console.log(message.id, message.date, message.text);
}
`

API

- Static
- GenStack.from(input)
- GenStack.generator(func)
- GenStack.range(options)
- GenStack.merge(...inputs)
- GenStack.interlace(...inputs)
- GenStack.walker(node, children)
- GenStack.reg(reg, content)
- Limit (chainable)
- .limit(num)
- .runWhile(cb)
- .runUntil(cb)
- Filtering (chainable)
- .filter(cb)
- .filterUndefined()
- .filterNull()
- .filterNullUndefined()
- .distinct
- .distinctBy(cb)
- .skip(num)
- .skipWhile(cb)
- .skipUntil(cb)
- Mapping (chainable)
- .map(cb)
- .mapAsync(cb)
- Expand (chainable)
- .flatMap(cb)
- .flatMapAsync(cb)
- .walker(children)
- Merge (chainable)
- .merge(...inputs)
- .interlace(...inputs)
- Utility (chainable)
- .peek(cb)
- Terminators (insert Skynet joke)
- .toArray()
- .toMap()

#### GenStack.from(input)

Simplist way to make a GenStack from anything that is an Iterator or Iterable. Arrays, Maps, Sets, Strings, Generators are all forms of iterables.

If you have async generator or async iterator, you will need to use AsyncGenStack, but the API is identical

On a happier note, if you pass a synchronous generator or synchronous iterator to AsyncGenStack, it will internally wrap

`ts
const { GenStack, AsyncGenStack } = require('@wormss/genstack');

const gen = GenStack.from([1, 2, 3, 4, 5, 6]); // Sync GenStack from Array
const gen = GenStack.from('Hello'); // Sync GenStack, will result in each letter being split, since string is an iterable
const gen = GenStack.from(myGenerator()); // Sync GenStack from async Generator or async iterator
const gen = AsyncGenStack.from([1, 2, 3, 4, 5, 6]); // Async GenStack from synchrous Array
const gen = AsyncGenStack.from('Hello'); // Async Generator will result in each letter being split, since string is an iterable, but asynchronously
const gen = AsyncGenStack.from(myAsyncGenerator()); // Async GenStack from async Generator or async iterator
const gen = AsyncGenStack.from(GenStack.from([1, 2, 3])); // Because why not.
`

#### GenStack.generator(func)

Infinitly call a supplied function for values.

`ts
const gen = GenStack.generate(Math.random);
const gen = AsyncGenStack.generate(() => fetch('https://something.com/randomStuff'));
`

$3

Standard Number range, start/end/step can all be configured

Start is optional, inclusive. The default is zero.\
End is optional, exclusive. There is no default, it is effectively Infinity or -Infinity depending on step\
Step is optional. The default is one.

This will produce 0, 2, 4, 6, 8, 10, 12, 14, 16, 18

`ts
const options = {
start: 0,
end: 20,
step: 2,
};
const gen = GenStack.range(options);
const gen = AsyncGenStack.range(options);
`

These are effectively the same. Start at zero and increases by 1 forever

`ts
const gen = GenStack.range();
const gen = AsyncGenStack.range();
const gen = GenStack.range({});
const gen = AsyncGenStack.range({});
`

$3

_// TODO add more info_

Merge (or concatinate) multiple iterators or iterables together

`ts
// 0...many number of iterable_or_iterators
GenStack.merge(iterable1, iterable2, ...iterables);
`

$3

_// TODO add more info_

Interlace multiple iterators or iterables together. Taking 1 from each at a time

`ts
// 0...many number of iterable_or_iterators
GenStack.interlace(iterable1, iterable2, ...iterables);
`

$3

_// TODO add more info_

`ts
GenStack.walker({ children: [] }, (n) => n.children);
`

$3

_// TODO add more info_

`ts
GenStack.reg('a.', 'aaabacad');
`

$3

_// TODO add more info_

`ts
// only run until x number of values before stopping
GenStack.from(myList).limit(num);
`

$3

_// TODO add more info_

`ts
// lets everything through until cb returns false.
GenStack.from(myList).runWhile(cb);
`

$3

_// TODO add more info_

`ts
// lets everything through until cb returns true
GenStack.from(myList).runUntil(cb);
`

$3

_// TODO add more info_

`ts
// throw away the values when cb returns false
GenStack.from(myList).filter(cb);
`

$3

_// TODO add more info_

`ts
// throw away values when they strictly match previous values
GenStack.from(myList).distinct();
`

$3

_// TODO add more info_

`ts
// throw away values when cb returned values match previous cb values.
GenStack.from(myList).distinctBy(cb);
`

$3

_// TODO add more info_

`ts
// throw away the first x number of values
GenStack.from(myList).skip(num);
`

$3

_// TODO add more info_

`ts
// skips all values until cb returns false, then lets everything else through
GenStack.from(myList).skipWhile(cb);
`

$3

_// TODO add more info_

`ts
// skips all values until cb returns true, then lets everything else through
GenStack.from(myList).skipUntil(cb);
`

$3

_// TODO add more info_

`ts
// change value into another value
GenStack.from(myList).map(cb);\
`

$3

_// TODO add more info_

`ts
// use the value to do some asynchrous call. Remember this is nice lazy evaluation, so will only run 1 at a time
GenStack.from(myList).mapAsync(cb);
`

#### .flatmap(cb)

`ts
// flatterns a list of lists into a single list. By list, I mean anythign that is iterable or an iterator. Be mindful of strings
GenStack.from(myList).flatMap(cb);

// flatterns into a single list after making an async call
GenStack.from(myList).flatMapAsync(cb);

// map and mapAsync are the same function on AsyncGenStack
// flatMap and flatMapAsync are the same function on AsyngGenStack
`

$3

#### .merge(...inputs)

`ts
// See GenStack.merge, only difference is they are concatinated after the 'this' has ran out of values
GenStack.from(myList).merge(iterable2, ...iterables);
`

#### .interlace(...inputs)

`ts
// See GenStack.interlace, only difference is 'this' is the first iterator to interlace
GenStack.from(myList).interlace(iterable2, ...iterables);
`

$3

#### .peek(cb)

`ts
// cb will be called with the value, but the value itself will continue down the stack.
GenStack.from(myList).peek(cb);
`

$3

#### .toArray()

I've listed both here.... Just because, you know.. reasons..

`ts
// because I found out there is no simple way of spreading an asynchrous iterator into an array. And I am too lazy to write the same logic everywhere.
await AsyncGenStack.from(myList).toArray();

// nothing more than a spread operator. You can be lazy and call .toArray or do [...gen] Only here to match the Async's function
GenStack.from(myList).toArray();
`

#### .toMap()

`ts
toMap(options?: ToMapOptions): Map;
toMap(key?: (i: T) => K, value?: (i: T) => V): Map;
`

`ts
GenStack.from(myList).toMap(); // Default
GenStack.from(myList).toMap((i) => i); // Same Default
GenStack.from(myList).toMap(
(i) => i,
(i) => i,
); // Same Default
GenStack.from(myList).toMap((i) => i.index); // custom key but default value
GenStack.from(myList).toMap(
(i) => i.index,
(i) => i.value,
); // custom key and custom value
GenStack.from(myList).toMap({}); // Default
GenStack.from(myList).toMap({ key: (i) => i.index, value: (i) => i.value }); // custom key and custom value
`

Usage Examples

There are two main exports GenStack and AsyncGenStack classes
No points are given for guessing when to use which over the other
Though, AsyncGenStack.from() will gladly accept any sync Iterator | Iterable and wrap it to be async

`ts
const { GenStack } = require('@wormss/genstack');

const gen = new GenStack(someUnlimitedIterator)
.filter((someItem) => someItem.someProperty === 'someValue') // filter to only get some values
.limit(100) // take the first 100
.map((someItem) => someItem.someDifferentValue * 2); // map those items into a different form

// At this point, you can do anything you would normally do with any iterator.
const array1 = [1, 2, 3, ...gen]; // put all the items in an array with spread
for (const value of gen) {
// receive the values in a for...of loop
}
// or choose one of the super lazy terminator
const array2 = gen.toArray();
`

The contructor is limited to iterators (purely for limiting complexity) there is GenStack.from() for greater compatibility

$3

`ts
// Split a string into individual letters
const gen1 = GenStack.from('string'); // values will be "s", "t", "r", "i", "n", "g"

// An array
const gen2 = GenStack.from(['string', 'another string']); // values will be "string", "another string"

// Set
const mySet = new Set();
mySet.add(1);
mySet.add(2);
mySet.add(3);
const gen3 = GenStack.from(mySet); // values will be 1, 2, 3

// Map
const myMap = new Map();
myMap.set('a', 1);
myMap.set('b', 2);
myMap.set('c', 3);
const gen4 = GenStack.from(myMap); // values will be an ['a', 1], ['b', 2] ,['c', 3]

// Custom iterable
let i = 0;
const myIterable = {
[Symbol.iterator]() {
return { next() { return { value: this.i++; done: false } }, };
},
};
const gen5 = GenStack.from(myIterable); // values will be 0, 1, 2, 3, 4.....Infinity
`

$3

You will guess from the code below, it's easier to deal with iterables, but just incase you have an iterator

`ts
// Get an iterator
const array = ['a', 'b', 'c'];
const iterator = array[Symbol.iterator]();
const gen6 = GenStack.from(iterator); // values will be 'a', 'b', 'c'

// Since you have the iterator directly, you can use the constructure if you really wanted
const array = [1, 2, 3];
const iterator = array[Symbol.iterator]();
const gen7 = new GenStack(iterator); // values will be 1, 2, 3 (as long as gen6 hasn't run)

// Make your own iterator
let i = 0;
const iterator = { next() { return { i++; done: false }; } };
const gen8 = new GenStack(iterator);
// or
const gen9 = GenStack.from(iterator);
`

$3

Range, go from start

`ts
// Blank, from 0 to infinity and beyond.
const gen10 = GenStack.range(); // values will be 0, 1, 2, 3....Infinate

// Start, end, step supplied to truely customise
const gen11 = GenStack.range({
start: 10, // default 0
end: 20, // end is exclusive, default undefined, eg, Infinite
step: 3, // default 1 or -1 depending on start and end values
}); // values will be 10, 13, 16, 19

// And don't try to outsmart it, it knows..
const gen12 = GenStack.range({
start: 10,
end: 21,
step: -5, // it wont try to step downwards if start/end are ascending
}); // values will be 10, 15, 20

// decend to the very bottom
const gen13 = GenStack.range({
start: 4
step: -2, // not supplying an end, is the only time negative step will do anything backwards
}); // values will be 4, 2, 0, -2, -4...-Infinity
``