{"id":19639585,"url":"https://github.com/mkloubert/js-promises","last_synced_at":"2026-04-21T09:31:31.072Z","repository":{"id":62354977,"uuid":"486831419","full_name":"mkloubert/js-promises","owner":"mkloubert","description":"Helpers for promises, which work in Node and the browser.","archived":false,"fork":false,"pushed_at":"2022-05-02T02:22:14.000Z","size":185,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-20T01:28:58.435Z","etag":null,"topics":["browser","function","helper","javascript","nodejs","promise"],"latest_commit_sha":null,"homepage":"https://mkloubert.github.io/js-promises/","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/mkloubert.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"patreon":"mkloubert","custom":["https://marcel.coffee/"]}},"created_at":"2022-04-29T04:00:02.000Z","updated_at":"2022-04-30T10:36:56.000Z","dependencies_parsed_at":"2022-10-31T10:30:33.254Z","dependency_job_id":null,"html_url":"https://github.com/mkloubert/js-promises","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mkloubert/js-promises","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkloubert%2Fjs-promises","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkloubert%2Fjs-promises/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkloubert%2Fjs-promises/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkloubert%2Fjs-promises/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkloubert","download_url":"https://codeload.github.com/mkloubert/js-promises/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkloubert%2Fjs-promises/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32085409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T06:27:27.065Z","status":"ssl_error","status_checked_at":"2026-04-21T06:27:21.250Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["browser","function","helper","javascript","nodejs","promise"],"created_at":"2024-11-11T13:02:20.724Z","updated_at":"2026-04-21T09:31:30.455Z","avatar_url":"https://github.com/mkloubert.png","language":"TypeScript","funding_links":["https://patreon.com/mkloubert","https://marcel.coffee/","https://paypal.me/MarcelKloubert","https://buymeacoffee.com/mkloubert"],"categories":[],"sub_categories":[],"readme":"[![npm](https://img.shields.io/npm/v/@marcelkloubert/promises.svg)](https://www.npmjs.com/package/@marcelkloubert/promises)\n[![last build](https://img.shields.io/github/workflow/status/mkloubert/js-promises/Publish)](https://github.com/mkloubert/js-promises/actions?query=workflow%3APublish)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/mkloubert/js-promises/pulls)\n\n# @marcelkloubert/promises\n\n\u003e Helpers for promises, which work in Node and the browser.\n\n## Install\n\nExecute the following command from your project folder, where your `package.json` file is stored:\n\n```bash\nnpm i @marcelkloubert/promises\n```\n\n## Usage\n\n### doRepeat(action: DoRepeatAction, countOrCondition: number | DoRepeatCondition, ...args: any[]): Promise\n\n\u003e Repeats an action or promise.\n\n```typescript\nimport assert from \"assert\";\nimport { doRepeat, DoRepeatActionContext } from \"@marcelkloubert/promises\";\n\nconst repeatCount = 5979;\nconst counter = 0;\n\nconst results = await doRepeat(async (context: DoRepeatActionContext) =\u003e {\n  console.log(\"context.state\", String(context.state));\n  context.state = context.index * 2;\n\n  ++counter;\n\n  // do some work here\n}, repeatCount);\n\nassert.strictEqual(results.length, repeatCount);\nassert.strictEqual(counter, results.length);\n```\n\n### isPromise(value: any): boolean\n\n\u003e Checks if a value is a Promise.\n\n```typescript\nimport { isPromise } from \"@marcelkloubert/promises\";\nimport Bluebird from \"bluebird\";\n\n// all are (true)\nisPromise(Promise.resolve(\"Foo\"));\nisPromise(Bluebird.resolve(\"Foo\"));\nisPromise({\n  then: (onfulfilled?: Function, onrejected?: Function): any =\u003e {},\n  catch: (onrejected?: Function) =\u003e {},\n});\n\n// all are (false)\nisPromise(\"Foo\");\nisPromise({\n  then: (onfulfilled?: Function, onrejected?: Function): any =\u003e {},\n});\nisPromise(null);\n```\n\n### isPromiseLike(value: any): boolean\n\n\u003e Checks if a value is a PromiseLike.\n\n```typescript\nimport { isPromiseLike } from \"@marcelkloubert/promises\";\nimport Bluebird from \"bluebird\";\n\n// all are (true)\nisPromiseLike(Promise.resolve(\"Foo\"));\nisPromiseLike(Bluebird.resolve(\"Foo\"));\nisPromiseLike({\n  then: (onfulfilled?: Function, onrejected?: Function): any =\u003e {},\n});\n\n// all are (false)\nisPromiseLike(\"Foo\");\nisPromiseLike({});\nisPromiseLike(null);\n```\n\n### PromiseQueue\n\n\u003e A promise queue.\n\n```typescript\nimport assert from \"assert\";\nimport { PromiseQueue } from \"@marcelkloubert/promises\";\n\n// create and start the queue\nconst queue = new PromiseQueue({\n  autoStart: true,\n  concurrency: 10, // maximum 10 actions at the same time\n});\n\nconst promises: Promise\u003cany\u003e[] = [];\nlet counter = 0;\n\n// lets create 100 actions and\n// add them to queue\nconst actionCount = 100;\nfor (let i = 0; i \u003c actionCount; i++) {\n  promises.push(\n    queue.enqueue(async () =\u003e {\n      // do some (long) work here ...\n\n      ++counter;\n    })\n  );\n}\n\n// wait until all actions have been executed\nawait Promise.all(promises);\n\n// stop the queue\nqueue.stop();\n\n// counter should now be the number of\n// enqueued actions\nassert.strictEqual(counter, promises.length);\n```\n\n### waitFor(action: WaitForAction, condition: WaitForCondition, ...args: any[]): Promise\n\n\u003e Invokes an action or promise, but waits for a condition.\n\n```typescript\nimport {\n  waitFor,\n  WaitForActionContext,\n  WaitForCondition,\n} from \"@marcelkloubert/promises\";\nimport fs from \"fs\";\n\nconst waitForFile: WaitForCondition = async (context) =\u003e {\n  // use context.cancel() function\n  // to cancel the operation\n  // maybe for a timeout\n\n  // setup 'state' value for upcoming\n  // action\n  context.state = \"Foo Bar BUZZ\"; // (s. below in action)\n\n  // return a truthy value to keep waiting\n  // otherwise falsy to start execution of action\n  return !fs.existsSync(\"/path/to/my/file.xlsx\");\n};\n\nconst result = await waitFor(async ({ state }: WaitForActionContext) =\u003e {\n  // state === \"Foo Bar BUZZ\" (s. above)\n}, waitForFile);\n```\n\n### withCancellation(action: WithCancellationAction, ...args: any[]): Promise\n\n\u003e Invokes an action or promise, which can be cancelled.\n\n```typescript\nimport {\n  CancellationError,\n  withCancellation,\n  WithCancellationActionContext,\n} from \"@marcelkloubert/promises\";\n\nconst promise = withCancellation(\n  async (context: WithCancellationActionContext) =\u003e {\n    let hasBeenFinished = false;\n    while (!context.cancellationRequested \u0026\u0026 !hasBeenFinished) {\n      // do some long work here\n    }\n  }\n);\n\nsetTimeout(() =\u003e {\n  promise.cancel(\"Promise action takes too long\");\n}, 10000);\n\ntry {\n  await promise;\n} catch (ex) {\n  if (ex instanceof CancellationError) {\n    // has been cancelled\n  } else {\n    // other error\n  }\n}\n```\n\n### withRetries(action: WithRetriesAction, optionsOrMaxRetries: WithRetriesOptions | number, ...args: any[]): Promise\n\n\u003e Invokes an action or promise and throws an error if a maximum number of tries has been reached.\n\n```typescript\nimport {\n  MaximumTriesReachedError,\n  withRetries,\n} from \"@marcelkloubert/promises\";\n\nconst myAsyncAction = async () =\u003e {\n  // do something here\n};\n\ntry {\n  // try this action\n  await withTimeout(myAsyncAction, {\n    maxRetries: 9, // try invoke the myLongAction\n    // with a maximum of 10 times\n    // (first invocation + maxRetries)\n    waitBeforeRetry: 10000, // wait 10 seconds, before retry\n  });\n} catch (error) {\n  // error should be a MaximumTriesReachedError instance\n  console.error(\"Invokation of myLongAction failed\", error);\n}\n```\n\n### withTimeout(action: WithTimeoutAction, timeout: number, ...args: any[]): Promise\n\n\u003e Invokes an action or promise and throws an error on a timeout.\n\n```typescript\nimport { TimeoutError, withTimeout } from \"@marcelkloubert/promises\";\n\nconst action = () =\u003e {\n  return new Promise\u003cstring\u003e((resolve) =\u003e {\n    setTimeout(() =\u003e result(\"FOO\"), 1000);\n  });\n};\n\n// submit action as function\n// should NOT throw a TimeoutError\nconst fooResult1 = await withTimeout(action, 10000);\n\n// submit action as Promise\n// this should throw a TimeoutError\nconst fooResult2 = await withTimeout(action(), 100);\n```\n\n### withWorker(workerFileOrUrl: string | URL, options?: WithWorkerOptions): Promise\n\n\u003e Wraps the execution of a worker into a Promise.\n\n```typescript\nimport { withWorker } from \"@marcelkloubert/promises\";\n\n// this is code for Node.js\n// in a browser 'exitCode' will not exist\nconst { exitCode, lastMessage } = await withWorker(\"/path/to/worker_script.js\");\n```\n\n## Documentation\n\nThe API documentation can be found [here](https://mkloubert.github.io/js-promises/).\n\n## License\n\nMIT © [Marcel Joachim Kloubert](https://github.com/mkloubert)\n\n## Support\n\n\u003cspan class=\"badge-paypal\"\u003e\u003ca href=\"https://paypal.me/MarcelKloubert\" title=\"Donate to this project using PayPal\"\u003e\u003cimg src=\"https://img.shields.io/badge/paypal-donate-yellow.svg\" alt=\"PayPal donate button\" /\u003e\u003c/a\u003e\u003c/span\u003e\n\u003cspan class=\"badge-patreon\"\u003e\u003ca href=\"https://patreon.com/mkloubert\" title=\"Donate to this project using Patreon\"\u003e\u003cimg src=\"https://img.shields.io/badge/patreon-donate-yellow.svg\" alt=\"Patreon donate button\" /\u003e\u003c/a\u003e\u003c/span\u003e\n\u003cspan class=\"badge-buymeacoffee\"\u003e\u003ca href=\"https://buymeacoffee.com/mkloubert\" title=\"Donate to this project using Buy Me A Coffee\"\u003e\u003cimg src=\"https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg\" alt=\"Buy Me A Coffee donate button\" /\u003e\u003c/a\u003e\u003c/span\u003e\n\nOr visit https://marcel.coffee/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkloubert%2Fjs-promises","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkloubert%2Fjs-promises","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkloubert%2Fjs-promises/lists"}