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.

$3

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

$3

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

$3

`html


`

`html

`

API

$3

`javascript
import { cancelable } from 'cancelable-promise';

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

$3

`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_

$3

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

$3

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

$3

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

$3

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
`

$3

#### 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
`

Scripts

$3

Run babel

`
npm run build
`

$3

Run eslint and jest

`shell
npm test
`

$3

Run cypress tests

`shell
npm run test:e2e
``

Contributing

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

$3

This project exists thanks to all the people who contribute.

Code of conduct

Contributor Covenant Code of Conduct.

License

MIT License © Alkemics