cancelable-promise

A simple Cancelable Promise.

This package is based on ES Promise.

• See caniuse for browser support
• See core-js for polyfills
• For example, you can use https://polyfill.io/v3/polyfill.min.js?features=Promise%2CPromise.prototype.finally for Internet Explorer 11

FYI, you can cancel a fetch request with AbortController & AbortSignal.

• See MDN
• See caniuse

Table of Contents

• Install
• Usage
  • Basic example
  • NodeJS
  • Browser
• API
  • cancelable
  • CancelablePromise
  • CancelablePromise.cancel
  • CancelablePromise.isCanceled
  • Static methods
• Scripts
  • Build
  • Tests
  • End-to-end tests
• Contributing
  • Contributors
• Code of conduct
• License

Install

npm install --save cancelable-promise

Usage

CancelablePromise acts like an ES Promise: you can use Promise.all, Promise.race with your CancelablePromise for example. The only difference is you'll have a cancel method on your promise to cancel future execution of then or catch functions. CancelablePromise will also cancel all callbacks attached to new promises returned by then/catch.

Basic example

import { cancelable, CancelablePromise } from 'cancelable-promise';

const promises = [
  cancelable(new Promise((resolve) => setTimeout(resolve, 1))),
  new CancelablePromise((resolve) => setTimeout(resolve, 1)),
];

for (const promise of promises) {
  promise.then(() => console.log('not logged'));
  promise.cancel();
}
// Nothing will be logged

NodeJS

const { cancelable } = require('cancelable-promise');
cancelable(new Promise((resolve) => resolve('ok')));

Browser

<script src="https://unpkg.com/cancelable-promise@4.0.0/umd/CancelablePromise.min.js"></script>
<script>
  const { cancelable } = window.CancelablePromise;
  cancelable(new Promise((resolve) => resolve('ok')));
</script>

<script type="module">
  import { cancelable } from 'https://unpkg.com/cancelable-promise@4.0.0/esm/CancelablePromise.min.mjs';
  cancelable(new Promise((resolve) => resolve('ok')));
</script>

API

cancelable

import { cancelable } from 'cancelable-promise';

/**
 * @param {Promise} arg - a native Promise
 * @returns {CancelablePromise}
 */
cancelable(
  new Promise((resolve) => {
    resolve('ok');
  })
);

CancelablePromise

import CancelablePromise from 'cancelable-promise';

/**
 * @param {(resolve, reject, onCancel) => void} arg - an augmented promise executor
 * @returns {CancelablePromise}
 */
const promise = new CancelablePromise((resolve, reject, onCancel) => {
  const worker = new Worker('some-script.js');

  onCancel(() => {
    worker.terminate();
  });

  worker.onmessage = (event) => resolve(event.data);
  worker.onerror = (error) => reject(error);
});

promise.cancel(); // It will execute the callback passed to onCancel

onCancel callback is working as in p-cancelable

cancelablePromise.cancel

/**
 * @returns {void}
 */
cancelablePromise.cancel();

cancelablePromise.isCanceled

/**
 * @returns {boolean}
 */
cancelablePromise.isCanceled();

cancelablePromise.finally

/**
 * @param {() => void} onFinally callback
 * @param {boolean} runWhenCanceled force finally execution on cancel
 * @returns {void}
 */
cancelablePromise.finally(() => {});

// You can release prematurely resources for a long running task
// by forcing finnaly callback execution when cancelling a promise
let worker;
const promise = cancelable(
  new Promise((resolve, reject) => {
    worker = new Worker('some-script.js');
    worker.onmessage = (event) => {
      resolve(event.data); // never executed
    };
    worker.onerror = (error) => {
      reject(error); // never executed
    };
  })
)
  .then(() => {
    console.log('never logged');
  })
  .finally(
    () => {
      console.log('executed');
      if (worker) {
        worker.terminate();
        worker = null;
      }
    },
    // runWhenCanceled boolean
    true
  );

promise.cancel();

Static methods

Same as Promise static methods.

import CancelablePromise from 'cancelable-promise';

CancelablePromise.resolve();
CancelablePromise.reject();
CancelablePromise.all([promise1, promise2]);
CancelablePromise.race([promise1, promise2]);
CancelablePromise.allSettled([promise1, promise2]);

You can still use the native Promise API and wrap your promise:

import { cancelable } from 'cancelable-promise';

cancelable(Promise.all([promise1, promise2]));
cancelable(Promise.race([promise1, promise2]));
cancelable(Promise.allSettled([promise1, promise2]));

CancelablePromise.isCancelable

Returns true if parameter is a cancelable promise.

import { cancelable, CancelablePromise } from 'cancelable-promise';

CancelablePromise.isCancelable(cancelable(new Promise(() => {}))); // true
CancelablePromise.isCancelable(new CancelablePromise(() => {})); // true
CancelablePromise.isCancelable(new Promise(() => {})); // false
CancelablePromise.isCancelable(undefined); // false
CancelablePromise.isCancelable({ cancel() {} }); // false

Utils

isCancelablePromise

Same as CancelablePromise.isCancelable, it returns true if parameter is a cancelable promise.

import {
  cancelable,
  CancelablePromise,
  isCancelablePromise,
} from 'cancelable-promise';

isCancelablePromise(cancelable(new Promise(() => {}))); // true
isCancelablePromise(new CancelablePromise(() => {})); // true
isCancelablePromise(new Promise(() => {})); // false
isCancelablePromise(undefined); // false
isCancelablePromise({ cancel() {} }); // false

Scripts

Build

Run babel

npm run build

Tests

Run eslint and jest

npm test

End-to-end tests

Run cypress tests

npm run test:e2e

Contributing

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

Contributors

This project exists thanks to all the people who contribute.

Code of conduct

Contributor Covenant Code of Conduct.

License

MIT License © Alkemics