https://github.com/alanshaw/abortable-iterator
Make any iterator or iterable abortable via an AbortSignal
https://github.com/alanshaw/abortable-iterator
abort abortable abortcontroller abortsignal async cancel iterator stop
Last synced: 4 months ago
JSON representation
Make any iterator or iterable abortable via an AbortSignal
- Host: GitHub
- URL: https://github.com/alanshaw/abortable-iterator
- Owner: alanshaw
- License: other
- Created: 2018-10-31T10:22:10.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-12-06T10:57:09.000Z (about 1 year ago)
- Last Synced: 2025-04-02T11:49:53.459Z (10 months ago)
- Topics: abort, abortable, abortcontroller, abortsignal, async, cancel, iterator, stop
- Language: TypeScript
- Size: 468 KB
- Stars: 14
- Watchers: 2
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# abortable-iterator
[](https://codecov.io/gh/alanshaw/abortable-iterator)
[](https://github.com/alanshaw/abortable-iterator/actions/workflows/js-test-and-release.yml?query=branch%3Amaster)
> Make any iterator or iterable abortable via an AbortSignal
# About
## Example
```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()
```
# Install
```console
$ npm i abortable-iterator
```
## Browser `` tag
Loading this module through a script tag will make its exports available as `AbortableIterator` in the global namespace.
```html
<script src="https://unpkg.com/abortable-iterator/dist/index.min.js">
```
## 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)
### `abortableSource(source, signal, [options])`
**(alias for `abortable.source(source, signal, [options])`)**
Make any iterator or iterable abortable via an `AbortSignal`.
#### Parameters
| Name | Type | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| source | [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol)\|[`Iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol) | The iterator or iterable object to make abortable |
| signal | [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol) | 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.
### `abortableSink(sink, signal, [options])`
The same as [`abortable.source`](#abortablesource-signal-options) except this makes the passed [`sink`](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#sink-it) abortable. Returns a new sink that wraps the passed `sink` and makes it abortable via the passed `signal` parameter.
### `abortableTransform(transform, signal, [options])`
The same as [`abortable.source`](#abortablesource-signal-options) except this makes the passed [`transform`](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#transform-it) abortable. Returns a new transform that wraps the passed `transform` and makes it abortable via the passed `signal` parameter.
### `abortableDuplex(duplex, signal, [options])`
The same as [`abortable.source`](#abortablesource-signal-options) except this makes the passed [`duplex`](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#duplex-it) 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`](https://www.npmjs.com/package/it-pipe) Utility to "pipe" async iterables together
# API Docs
-
# License
Licensed under either of
- Apache 2.0, ([LICENSE-APACHE](https://github.com/alanshaw/abortable-iterator/LICENSE-APACHE) / )
- MIT ([LICENSE-MIT](https://github.com/alanshaw/abortable-iterator/LICENSE-MIT) / )
# Contribution
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.