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

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

4.3.1 (2022-10-14)

Noticeable changes:

• fix(type): add toStringTag symbol to class fields to be compatible with Promise type

Other changes:

• chore(release): update preparation commit message
• chore(deps-dev): bump @babel/preset-env from 7.19.3 to 7.19.4
• chore(deps-dev): bump terser from 5.15.0 to 5.15.1
• chore(deps-dev): bump core-js from 3.25.3 to 3.25.5
• chore(deps-dev): bump @babel/cli from 7.18.10 to 7.19.3
• chore(deps-dev): bump @babel/core from 7.19.1 to 7.19.3
• chore(deps-dev): bump @babel/preset-typescript from 7.17.12 to 7.18.6
• fix(cypress): migrate cypress config file for v10
• fix(tests): fix tests for jest v28

4.3.0 (2022-03-14)

• chore(deps-dev): bump @typescript-eslint/eslint-plugin
• chore(deps-dev): bump @typescript-eslint/parser from 5.13.0 to 5.14.0
• chore(deps-dev): bump lint-staged from 12.3.4 to 12.3.5
• feat(any): support Promise.any

4.2.1 (2021-07-09)

• add browser entrypoint in package.json
• upgrade dev dependencies

4.2.0 (2021-06-17)

• Fix finally usecase always been called
• Merge onCancelList and finallyList
• Add isCancelablePromise util
• Migrate to Typescript and improve umd/esm outputs

4.1.0 (2021-06-16)

• Prepare release without commit
• Cancel cancelable promise returned by a then/catch callback

Consider this example:

const { CancelablePromise } = require('cancelable-promise');

const promise1 = new CancelablePromise((resolve, reject, onCancel) => {
  const timer = setTimeout(() => {
    console.log('resolve promise1');
    resolve();
  }, 1000);
  const abort = () => {
    clearTimeout(timer);
  };
  onCancel(abort);
});

const promise2 = promise1.then(() => {
  const promise3 = new CancelablePromise((resolve, reject, onCancel) => {
    const timer = setTimeout(() => {
      console.log('resolve promise 3');
      resolve();
    }, 1000);
    const abort = () => {
      clearTimeout(timer);
    };
    onCancel(abort);
  });
  return promise3;
});

setTimeout(() => {
  console.log('cancel promise 2');
  promise2.cancel();
}, 1500);

Before this release, output was:

resolve promise1
cancel promise 2
resolve promise 3

Now if you return a cancelable promise in a then/catch callback, it will cancel it too when you are canceling the parent promise. Output will be:

resolve promise1
cancel promise 2

4.0.0 (2021-05-27)

• Update dependencies and add esm module

[Breaking change]

No more dist folder, you will find releases in umd and esm folders.

- https://unpkg.com/cancelable-promise@3.0.0/dist/CancelablePromise.min.js
+ https://unpkg.com/cancelable-promise@4.0.0/umd/CancelablePromise.min.js
+ https://unpkg.com/cancelable-promise@4.0.0/esm/CancelablePromise.min.js

[Feature] ESM module

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

3.2.3 (2021-01-13)

• add types in package.json

3.2.0 (2020-10-10)

• feature: execute onCancel or finally callback when promise is canceled

import CancelablePromise from 'cancelable-promise';

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

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();

3.1.3 (2020-08-31)

• upgrade dev dependencies
• add node v14 to nodejs workflows

3.1.2 (2020-07-20)

• upgrade dev dependencies

3.1.1 (2020-05-01)

• export CancelablePromiseType and CancelablePromiseConstructor types
• upgrade dev dependencies

3.1.0 (2020-04-28)

• upgrade dev dependencies
• add isCanceled method to cancelable promises

3.0.0 (2020-04-07)

• Complete rewrite of CancelablePromise. Now promises returned from Promise API such as then or catch can cancel the root promise and all promises created from this root promise:

// CancelablePromise v2
import CancelablePromise from 'cancelable-promise';

const promise = new CancelablePromise((resolve) => setTimeout(resolve, 1))
  .then(() => console.log('callback2 executed'))
  .then(() => console.log('callback3 executed'));
promise.cancel();
// logs:
// callback2 executed
// callback3 executed

// CancelablePromise v3
import CancelablePromise from 'cancelable-promise';

const promise = new CancelablePromise((resolve) => setTimeout(resolve, 1))
  .then(() => console.log('callback2 executed'))
  .then(() => console.log('callback3 executed'));
promise.cancel();
// no logs

• a functionnal util has been added:

import { cancelable } from 'cancelable-promise';

cancelable(new Promise((resolve) => setTimeout(resolve, 1)));

• UMD module, CancelablePromise can be loaded in browser