happy-ferret / abortable-iterator

Make any iterator or iterable abortable via an AbortSignal

abortable-iterator

Make any iterator or iterable abortable via an AbortSignal

The AbortController is used in the fetch API to abort in flight requests from, for example, a timeout or user action. The same concept is used here to halt iteration of an async iterator.

Install

npm install abortable-iterator

Usage

const abortable = require('abortable-iterator')
const AbortController = require('abort-controller')

// 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 = abortable(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
  }
}

API

const abortable = require('abortable-iterator')

abortable(iterator, signal, [options])

Make any iterator or iterable abortable via an AbortSignal.

Parameters

Name	Type	Description
iterator	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 "operation aborted"
options.abortCode	String|Number	The value assigned to the code property of the error that is thrown if the iterator is aborted. Default "ERR_ABORTED"

Returns

Type	Description
Iterator	An iterator that wraps the passed iterator parameter that makes it abortable via the passed signal parameter.

The returned iterator will throw an Error when it is aborted that has a code property with the value ERR_ABORTED by default.

Contribute

Feel free to dive in! Open an issue or submit PRs.

License

MIT © Alan Shaw