Helper for creating cancellable promise-returning functions.

Example:

import cancellable from 'cancellable'

const promise = cancellable((cancellation, cancelled) => new Promise((resolve, reject) => {
  const xhr = new XMLHttpRequest()
  xhr.open('GET', '/ajax')
  xhr.addEventListener('error', () => reject(new Error('Something went wrong')))
  xhr.addEventListener('load', () => resolve(xhr.response))
  xhr.send()
  cancellation.catch((reason) => {
    xhr.abort()
    reject(reason)
  })
}))

// later

promise.cancel()

Takes a promise-returning function that will be passed two arguments:

• cancellation: Promise

  A promise that will be rejected with a CancellationError if the cancel method was invoked or otherwise resolves to the fulfilled/rejected value of the promise returned by the function.

• cancelled: () => boolean

  A function that returns true if the cancel method was invoked or false otherwise. This function will return true even if the cancel method was invoked after the promise was fulfilled/rejected normally.

Returns the promise returned by the function but adds a cancel method that takes an optional argument:

• message: string

  A message that will be used to create a CancellationError. Rejects the promise if it hasn't already been fulfilled/rejected.

A subclass of Error that is used to reject cancelled promises.

As of 1.1.0 it also has a cancelled property (set to true) to easily distinguish it from other errors.

The MIT/Expat license. For more information, see http://foss-haas.mit-license.org/ or the accompanying LICENSE file.