Awesome

abortable-iterator

Make any iterator or iterable abortable via an AbortSignal

About

Example

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

$ npm i abortable-iterator

Browser `<script>` tag

Loading this module through a script tag will make its exports available as AbortableIterator in the global namespace.

<script src="https://unpkg.com/abortable-iterator/dist/index.min.js"></script>

API

import {
  abortableSource,
  abortableSink,
  abortableTransform,
  abortableDuplex
} from 'abortable-iterator'

abortableSource(source, signal, [options])
abortableSink(sink, signal, [options])
abortableTransform(transform, signal, [options])
abortableDuplex(duplex, 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`\|`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.

`abortableSink(sink, signal, [options])`

The same as 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.

`abortableTransform(transform, signal, [options])`

The same as 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.

`abortableDuplex(duplex, signal, [options])`

The same as 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.

it-pipe Utility to "pipe" async iterables together

API Docs

https://alanshaw.github.io/abortable-iterator

License

Licensed under either of

Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
MIT (LICENSE-MIT / http://opensource.org/licenses/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.