Cancelable-promise NPM

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

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.2.1/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.2.1/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