Make any iterator or iterable abortable via an AbortSignal
npm install abortable-iterator

> Make any iterator or iterable abortable via an AbortSignal
``js
import { abortableSource } from 'abortable-iterator'
async function main () {
// An example function that creates an async iterator that yields an increasing
// number every x milliseconds and NEVER ENDS!
const asyncCounter = async function * (start, delay) {
let i = start
while (true) {
yield new Promise(resolve => setTimeout(() => resolve(i++), delay))
}
}
// Create a counter that'll yield numbers from 0 upwards every second
const everySecond = asyncCounter(0, 1000)
// Make everySecond abortable!
const controller = new AbortController()
const abortableEverySecond = abortableSource(everySecond, controller.signal)
// Abort after 5 seconds
setTimeout(() => controller.abort(), 5000)
try {
// Start the iteration, which will throw after 5 seconds when it is aborted
for await (const n of abortableEverySecond) {
console.log(n)
}
} catch (err) {
if (err.code === 'ERR_ABORTED') {
// Expected - all ok :D
} else {
throw err
}
}
}
main()
`
`console`
$ npm i abortable-iterator
API
`js
import {
abortableSource,
abortableSink,
abortableTransform,
abortableDuplex
} from 'abortable-iterator'
`- [
abortableSource(source, signal, [options])](#abortablesource-signal-options)
- [abortableSink(sink, signal, [options])](#abortablesinksink-signal-options)
- [abortableTransform(transform, signal, [options])](#abortabletransformtransform-signal-options)
- [abortableDuplex(duplex, signal, [options])](#abortableduplexduplex-signal-options)$3
(alias for
abortable.source(source, signal, [options]))Make any iterator or iterable abortable via an
AbortSignal.#### Parameters
| Name | Type | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| source |
Iterable\|Iterator | The iterator or iterable object to make abortable |
| signal | AbortSignal | Signal obtained from AbortController.signal which is used to abort the iterator. |
| options | Object | (optional) options |
| options.onAbort | Function | An (async) function called when the iterator is being aborted, before the abort error is thrown. Default null |
| options.abortMessage | String | The message that the error will have if the iterator is aborted. Default "The operation was aborted" |
| options.abortCode | String\|Number | The value assigned to the code property of the error that is thrown if the iterator is aborted. Default "ABORT\_ERR" |
| options.returnOnAbort | Boolean | Instead of throwing the abort error, just return from iterating over the source stream. |
| options.onReturnError | Function | When a generator is aborted, we call .return on it - if this function errors the error value will be passed to the .onReturnError callback if passed. Default null |#### Returns
| Type | Description |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
Iterable | An iterator that wraps the passed source parameter that makes it abortable via the passed signal parameter. |The returned iterator will
throw an AbortError when it is aborted that has a type with the value aborted and code property with the value ABORT_ERR by default.$3
abortable.source except this makes the passed sink abortable. Returns a new sink that wraps the passed sink and makes it abortable via the passed signal parameter.$3
abortable.source except this makes the passed transform abortable. Returns a new transform that wraps the passed transform and makes it abortable via the passed signal parameter.$3
abortable.source except this makes the passed duplex abortable. Returns a new duplex that wraps the passed duplex and makes it abortable via the passed signal parameter.Note that this will abort both sides of the duplex. Use
duplex.sink = abortable.sink(duplex.sink) or duplex.source = abortable.source(duplex.source) to abort just the sink or the source.Related
it-pipe` Utility to "pipe" async iterables together-
Licensed under either of
- Apache 2.0, (LICENSE-APACHE /
- MIT (LICENSE-MIT /
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.