{"id":13457736,"url":"https://github.com/alkemics/CancelablePromise","last_synced_at":"2025-03-24T14:32:15.445Z","repository":{"id":1877285,"uuid":"44961319","full_name":"alkemics/CancelablePromise","owner":"alkemics","description":"A simple Cancelable Promise","archived":false,"fork":false,"pushed_at":"2025-03-18T09:40:28.000Z","size":7482,"stargazers_count":157,"open_issues_count":6,"forks_count":25,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-03-21T19:49:50.519Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alkemics.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-26T10:25:15.000Z","updated_at":"2025-03-18T09:39:13.000Z","dependencies_parsed_at":"2023-01-14T10:55:17.095Z","dependency_job_id":"fc710f85-badc-4745-950c-7e4476cd684c","html_url":"https://github.com/alkemics/CancelablePromise","commit_stats":{"total_commits":977,"total_committers":20,"mean_commits":48.85,"dds":"0.10542476970317294","last_synced_commit":"906b922d2280d50e1602854855884c36a6eb2abd"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alkemics%2FCancelablePromise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alkemics%2FCancelablePromise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alkemics%2FCancelablePromise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alkemics%2FCancelablePromise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alkemics","download_url":"https://codeload.github.com/alkemics/CancelablePromise/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245289625,"owners_count":20591106,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T09:00:34.995Z","updated_at":"2025-03-24T14:32:15.063Z","avatar_url":"https://github.com/alkemics.png","language":"TypeScript","readme":"# cancelable-promise\n\n[![GitHub license](https://img.shields.io/github/license/alkemics/CancelablePromise)](https://github.com/alkemics/CancelablePromise/blob/master/LICENSE) [![npm version](https://img.shields.io/npm/v/cancelable-promise)](https://www.npmjs.com/package/cancelable-promise) [![Unit tests](https://github.com/alkemics/CancelablePromise/workflows/Unit%20tests/badge.svg?branch=master)](https://github.com/alkemics/CancelablePromise/actions?query=workflow%3A%22Unit+20tests%22) [![Cypress tests](https://github.com/alkemics/CancelablePromise/workflows/Cypress%20tests/badge.svg?branch=master)](https://github.com/alkemics/CancelablePromise/actions?query=workflow%3A%22Cypress+tests%22) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/alkemics/CancelablePromise/pulls)\n\nA simple Cancelable Promise.\n\nThis package is based on ES Promise.\n\n- See [caniuse](https://caniuse.com/#search=Promise) for browser support\n- See [core-js](https://github.com/zloirock/core-js#ecmascript-promise) for polyfills\n- For example, you can use https://polyfill.io/v3/polyfill.min.js?features=Promise%2CPromise.prototype.finally for Internet Explorer 11\n\nFYI, you can cancel a fetch request with AbortController \u0026 AbortSignal.\n\n- See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/AbortController)\n- See [caniuse](https://caniuse.com/#feat=abortcontroller)\n\n## Table of Contents\n\n- [Install](#install)\n- [Usage](#usage)\n  - [Basic example](#basic-example)\n  - [NodeJS](#nodejs)\n  - [Browser](#browser)\n- [API](#api)\n  - [cancelable](#cancelable)\n  - [CancelablePromise](#cancelablepromise)\n  - [CancelablePromise.cancel](#cancelablepromisecancel)\n  - [CancelablePromise.isCanceled](#cancelablepromiseiscanceled)\n  - [Static methods](#static-methods)\n- [Scripts](#scripts)\n  - [Build](#build)\n  - [Tests](#tests)\n  - [End-to-end tests](#end-to-end-tests)\n- [Contributing](#contributing)\n  - [Contributors](#contributors)\n- [Code of conduct](#code-of-conduct)\n- [License](#license)\n\n## Install\n\n```\nnpm install --save cancelable-promise\n```\n\n## Usage\n\nCancelablePromise 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`.\n\n### Basic example\n\n```javascript\nimport { cancelable, CancelablePromise } from 'cancelable-promise';\n\nconst promises = [\n  cancelable(new Promise((resolve) =\u003e setTimeout(resolve, 1))),\n  new CancelablePromise((resolve) =\u003e setTimeout(resolve, 1)),\n];\n\nfor (const promise of promises) {\n  promise.then(() =\u003e console.log('not logged'));\n  promise.cancel();\n}\n// Nothing will be logged\n```\n\n### NodeJS\n\n```javascript\nconst { cancelable } = require('cancelable-promise');\ncancelable(new Promise((resolve) =\u003e resolve('ok')));\n```\n\n### Browser\n\n```html\n\u003cscript src=\"https://unpkg.com/cancelable-promise@4.2.1/umd/CancelablePromise.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const { cancelable } = window.CancelablePromise;\n  cancelable(new Promise((resolve) =\u003e resolve('ok')));\n\u003c/script\u003e\n```\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { cancelable } from 'https://unpkg.com/cancelable-promise@4.2.1/esm/CancelablePromise.min.mjs';\n  cancelable(new Promise((resolve) =\u003e resolve('ok')));\n\u003c/script\u003e\n```\n\n## API\n\n### cancelable\n\n```javascript\nimport { cancelable } from 'cancelable-promise';\n\n/**\n * @param {Promise} arg - a native Promise\n * @returns {CancelablePromise}\n */\ncancelable(\n  new Promise((resolve) =\u003e {\n    resolve('ok');\n  })\n);\n```\n\n### CancelablePromise\n\n```javascript\nimport CancelablePromise from 'cancelable-promise';\n\n/**\n * @param {(resolve, reject, onCancel) =\u003e void} arg - an augmented promise executor\n * @returns {CancelablePromise}\n */\nconst promise = new CancelablePromise((resolve, reject, onCancel) =\u003e {\n  const worker = new Worker('some-script.js');\n\n  onCancel(() =\u003e {\n    worker.terminate();\n  });\n\n  worker.onmessage = (event) =\u003e resolve(event.data);\n  worker.onerror = (error) =\u003e reject(error);\n});\n\npromise.cancel(); // It will execute the callback passed to onCancel\n```\n\n_`onCancel` callback is working as in [p-cancelable](https://github.com/sindresorhus/p-cancelable)_\n\n### cancelablePromise.cancel\n\n```javascript\n/**\n * @returns {void}\n */\ncancelablePromise.cancel();\n```\n\n### cancelablePromise.isCanceled\n\n```javascript\n/**\n * @returns {boolean}\n */\ncancelablePromise.isCanceled();\n```\n\n### cancelablePromise.finally\n\n```javascript\n/**\n * @param {() =\u003e void} onFinally callback\n * @param {boolean} runWhenCanceled force finally execution on cancel\n * @returns {void}\n */\ncancelablePromise.finally(() =\u003e {});\n\n// You can release prematurely resources for a long running task\n// by forcing finnaly callback execution when cancelling a promise\nlet worker;\nconst promise = cancelable(\n  new Promise((resolve, reject) =\u003e {\n    worker = new Worker('some-script.js');\n    worker.onmessage = (event) =\u003e {\n      resolve(event.data); // never executed\n    };\n    worker.onerror = (error) =\u003e {\n      reject(error); // never executed\n    };\n  })\n)\n  .then(() =\u003e {\n    console.log('never logged');\n  })\n  .finally(\n    () =\u003e {\n      console.log('executed');\n      if (worker) {\n        worker.terminate();\n        worker = null;\n      }\n    },\n    // runWhenCanceled boolean\n    true\n  );\n\npromise.cancel();\n```\n\n### Static methods\n\nSame as Promise static methods.\n\n```javascript\nimport CancelablePromise from 'cancelable-promise';\n\nCancelablePromise.resolve();\nCancelablePromise.reject();\nCancelablePromise.all([promise1, promise2]);\nCancelablePromise.race([promise1, promise2]);\nCancelablePromise.allSettled([promise1, promise2]);\n```\n\nYou can still use the native Promise API and wrap your promise:\n\n```javascript\nimport { cancelable } from 'cancelable-promise';\n\ncancelable(Promise.all([promise1, promise2]));\ncancelable(Promise.race([promise1, promise2]));\ncancelable(Promise.allSettled([promise1, promise2]));\n```\n\n#### CancelablePromise.isCancelable\n\nReturns `true` if parameter is a cancelable promise.\n\n```javascript\nimport { cancelable, CancelablePromise } from 'cancelable-promise';\n\nCancelablePromise.isCancelable(cancelable(new Promise(() =\u003e {}))); // true\nCancelablePromise.isCancelable(new CancelablePromise(() =\u003e {})); // true\nCancelablePromise.isCancelable(new Promise(() =\u003e {})); // false\nCancelablePromise.isCancelable(undefined); // false\nCancelablePromise.isCancelable({ cancel() {} }); // false\n```\n\n### Utils\n\n#### isCancelablePromise\n\nSame as `CancelablePromise.isCancelable`, it returns `true` if parameter is a cancelable promise.\n\n```javascript\nimport {\n  cancelable,\n  CancelablePromise,\n  isCancelablePromise,\n} from 'cancelable-promise';\n\nisCancelablePromise(cancelable(new Promise(() =\u003e {}))); // true\nisCancelablePromise(new CancelablePromise(() =\u003e {})); // true\nisCancelablePromise(new Promise(() =\u003e {})); // false\nisCancelablePromise(undefined); // false\nisCancelablePromise({ cancel() {} }); // false\n```\n\n## Scripts\n\n### Build\n\nRun babel\n\n```\nnpm run build\n```\n\n### Tests\n\nRun `eslint` and `jest`\n\n```shell\nnpm test\n```\n\n### End-to-end tests\n\nRun `cypress` tests\n\n```shell\nnpm run test:e2e\n```\n\n## Contributing\n\nFeel free to dive in! [Open an issue](https://github.com/alkemics/CancelablePromise/issues) or [submit PRs](https://github.com/alkemics/CancelablePromise/compare).\n\n### Contributors\n\nThis project exists thanks to all [the people who contribute](https://github.com/alkemics/CancelablePromise/graphs/contributors).\n\n## Code of conduct\n\n[Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).\n\n## License\n\n[MIT License](LICENSE) © Alkemics\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falkemics%2FCancelablePromise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falkemics%2FCancelablePromise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falkemics%2FCancelablePromise/lists"}