Nine Pedestrians Mesmerized
    Wondering what’s next for npm?Check out our public roadmap! »

    cancelable-promise
    TypeScript icon, indicating that this package has built-in type declarations

    3.2.3 • Public • Published

    cancelable-promise

    GitHub license npm version Node.js CI End-to-end tests PRs Welcome

    A simple Cancelable Promise.

    This package is based on ES Promise.

    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/cancelable-promise@3.0.0/dist/CancelablePromise.min.js"></script>
    <script>
      const { cancelable } = window.CancelablePromise;
      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]));

    Scripts

    Build

    Run babel

    npm run build
    

    Tests

    Run eslint and jest

    npm test

    End-to-end tests

    Run cypress

    npm run cypress

    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

    Keywords

    none

    Install

    npm i cancelable-promise

    DownloadsWeekly Downloads

    46,179

    Version

    3.2.3

    License

    MIT

    Unpacked Size

    44.7 kB

    Total Files

    10

    Last publish

    Collaborators

    • avatar
    • avatar