A simple cancelable promise
npm install 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.
- 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
```
npm install --save cancelable-promise
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.
`javascript
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
`
`javascript`
const { cancelable } = require('cancelable-promise');
cancelable(new Promise((resolve) => resolve('ok')));
`html`
`html`
`javascript
import { cancelable } from 'cancelable-promise';
/**
* @param {Promise} arg - a native Promise
* @returns {CancelablePromise}
*/
cancelable(
new Promise((resolve) => {
resolve('ok');
})
);
`
`javascript
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_
`javascript`
/**
* @returns {void}
*/
cancelablePromise.cancel();
`javascript`
/**
* @returns {boolean}
*/
cancelablePromise.isCanceled();
`javascript
/**
* @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();
`
Same as Promise static methods.
`javascript
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:
`javascript
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.
`javascript
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
`
#### isCancelablePromise
Same as CancelablePromise.isCancelable, it returns true if parameter is a cancelable promise.
`javascript
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
`
Run babel
``
npm run build
Run eslint and jest
`shell`
npm test
Run cypress tests
`shell``
npm run test:e2e
Feel free to dive in! Open an issue or submit PRs.
This project exists thanks to all the people who contribute.
Contributor Covenant Code of Conduct.
MIT License © Alkemics