Extended iterable class, providing lazy array-like methods with automatic async and return/throw forwarding
npm install @harperfast/extended-iterable
The extended-iterable package provides a class that implements the Iterable/Iterator protocol and provides array-like methods
with lazy evaluation, similar to iterators helpers. However,
extended-iterable provides additional methods, the ability to handle both sync and async iteration, automatic handling of
asynchronous callbacks, and return/throw forwarding which can be critical for proper cleanup when used with
database transactions.
The package exports a single ExtendedIterable class, which can be constructed with a basic iterable or can be constructed
with no arguments and assigned (or overridden with) an iterate method that returns an iterator.
For example, we can create an ExtendedIterable:
``javascript
import { ExtendedIterable } from '@harperdb/extended-iterable';
function performQuery() {
let results = new ExtendedIterable();
results.iterate = function() {
let txn = startTxn(); // we can start a transaction in some database, and be notified of when the iterable is completed below
let cursor = txn.doQuery();
return {
// implement an iterator
next() {
// iterate through a query or table
let entry = cursor.getNext();
if (entry)
return { value: entry };
else
return { done: true };
},
return () { // called when the iterator is done
txn.commit();
},
throw () {
txn.abort();
}
}
};
return results;
}
`
The returned ExtendedIterable is fully iterable:
`js`
let extendedIterable = performQuery();
for (let value of extendedIterable) {
// for each value
}
Or we can use the provided iterative methods on the returned results:
`js`
extendedIterable
.filter((value) => test(value))
.forEach((value) => {
// for each value that matched the filter
})
Note that map and filter are also lazy, they will only be executed once their returned iterable is iterated or forEach is called on it. The map and filter functions also support async/promise-based functions, and you can create an async iterable if the callback functions execute asynchronously (return a promise).
We can also query with offset to skip a certain number of entries, and limit the number of entries to iterate through:
`js`
let sliced = extendedIterable.slice(10, 20); // skip first 10 and get next 10
If you want to get a true array from the results, the asArray property will return the results as an array.
and filter callbacks are immediately executed, but wit iterators, they are executed during iteration, so if an error occurs during iteration, the error will be thrown when the iteration is attempted. It is also critical that when an iteration is finished, the cursor is closed, so by default, if an error occurs during iteration, the cursor will immediately be closed. However, if you want to catch errors that occur in map (and flatMap) callbacks during iteration, you can use the mapError method to catch errors that occur during iteration, and allow iteration to continue (without closing the cursor). For example:`js
let mapped = extendedIterable.map(({ key, value }) => {
return thisMightThrowError(value);
}).mapError((error) => {
// rather than letting the error terminate the iteration, we can catch it here and return a value to continue iterating:
return 'error occurred';
})
for (let entry of mapped) {
...
}
`
A This library is licensed under the terms of the MIT license.