cancelable-promise
v4.3.1
Published
A simple cancelable promise
Downloads
141,811
Readme
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.
Table of Contents
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/[email protected]/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/[email protected]/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