{"id":17531167,"url":"https://github.com/bartozzz/queue-promise","last_synced_at":"2025-08-23T15:11:44.094Z","repository":{"id":11984104,"uuid":"59246791","full_name":"Bartozzz/queue-promise","owner":"Bartozzz","description":"A simple, dependency-free library for concurrent promise-based queues. Comes with with concurrency and timeout control.","archived":false,"fork":false,"pushed_at":"2023-03-17T20:51:08.000Z","size":3738,"stargazers_count":92,"open_issues_count":13,"forks_count":11,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-31T07:06:53.974Z","etag":null,"topics":["javascript","nodejs","promise","promise-chain","promise-queue","queue"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/queue-promise","language":"JavaScript","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/Bartozzz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-19T22:19:44.000Z","updated_at":"2025-02-07T15:18:26.000Z","dependencies_parsed_at":"2024-06-18T15:39:20.537Z","dependency_job_id":null,"html_url":"https://github.com/Bartozzz/queue-promise","commit_stats":{"total_commits":690,"total_committers":11,"mean_commits":62.72727272727273,"dds":"0.30000000000000004","last_synced_commit":"a872e9e6e4bbf05e588b1b7de9340b2e967337d1"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bartozzz%2Fqueue-promise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bartozzz%2Fqueue-promise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bartozzz%2Fqueue-promise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bartozzz%2Fqueue-promise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bartozzz","download_url":"https://codeload.github.com/Bartozzz/queue-promise/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247622984,"owners_count":20968575,"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":["javascript","nodejs","promise","promise-chain","promise-queue","queue"],"created_at":"2024-10-20T17:23:07.344Z","updated_at":"2025-04-07T09:18:36.413Z","avatar_url":"https://github.com/Bartozzz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003equeue-promise\u003c/h1\u003e\n\n[![Default CI/CD](https://github.com/Bartozzz/queue-promise/workflows/Default%20CI/CD/badge.svg)](https://github.com/Bartozzz/queue-promise/actions)\n[![Known Vulnerabilities](https://snyk.io/test/github/Bartozzz/queue-promise/badge.svg?targetFile=package.json)](https://snyk.io/test/github/Bartozzz/queue-promise?targetFile=package.json)\n[![npm package size](https://img.badgesize.io/Bartozzz/queue-promise/master/dist/index.js?compression=gzip)](https://www.npmjs.com/package/queue-promise)\n[![npm version](https://img.shields.io/npm/v/queue-promise.svg)](https://www.npmjs.com/package/queue-promise)\n[![npm dependency Status](https://david-dm.org/Bartozzz/queue-promise.svg)](https://www.npmjs.com/package/queue-promise)\n[![npm downloads](https://img.shields.io/npm/dt/queue-promise.svg)](https://www.npmjs.com/package/queue-promise)\n\u003cbr\u003e\n\n`queue-promise` is a small, dependency-free library for promise-based queues. It will execute enqueued tasks concurrently at a given speed. When a task is being resolved or rejected, an event is emitted.\n\n\u003c/div\u003e\n\n## Installation\n\n```bash\n$ npm install queue-promise\n```\n\n## Usage\n\n### With automatic start\n\n```javascript\nimport Queue from \"queue-promise\";\n\nconst queue = new Queue({\n  concurrent: 1,\n  interval: 2000\n});\n\nqueue.on(\"start\", () =\u003e /* … */);\nqueue.on(\"stop\", () =\u003e /* … */);\nqueue.on(\"end\", () =\u003e /* … */);\n\nqueue.on(\"resolve\", data =\u003e console.log(data));\nqueue.on(\"reject\", error =\u003e console.error(error));\n\nqueue.enqueue(asyncTaskA); // resolved/rejected after 0ms\nqueue.enqueue(asyncTaskB); // resolved/rejected after 2000ms\nqueue.enqueue(asyncTaskC); // resolved/rejected after 4000ms\n```\n\n### Without automatic start\n\n```javascript\nimport Queue from \"queue-promise\";\n\nconst queue = new Queue({\n  concurrent: 1,\n  interval: 2000,\n  start: false,\n});\n\nqueue.enqueue(asyncTaskA);\nqueue.enqueue(asyncTaskB);\nqueue.enqueue(asyncTaskC);\n\nwhile (queue.shouldRun) {\n  // 1st iteration after 2000ms\n  // 2nd iteration after 4000ms\n  // 3rd iteration after 6000ms\n  const data = await queue.dequeue();\n}\n```\n\n## API\n\n#### `new Queue(options)`\n\nCreate a new `Queue` instance.\n\n| Option       | Default | Description                                                                 |\n| :----------- | :------ | :-------------------------------------------------------------------------- |\n| `concurrent` | `5`     | How many tasks should be executed in parallel                               |\n| `interval`   | `500`   | How often should new tasks be executed (in ms)                              |\n| `start`      | `true`  | Whether it should automatically execute new tasks as soon as they are added |\n\n#### **public** `.enqueue(tasks)`/`.add(tasks)`\n\nAdds a new task to the queue. A task should be an [async function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) (ES2017) or return a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). Throws an error if the provided `task` is not a valid function.\n\n**Example:**\n\n```javascript\nasync function getRepos(user) {\n  return await github.getRepos(user);\n}\n\nqueue.enqueue(() =\u003e {\n  return getRepos(\"userA\");\n});\n\nqueue.enqueue(async () =\u003e {\n  await getRepos(\"userB\");\n});\n\n// …equivalent to:\nqueue.enqueue([() =\u003e getRepos(\"userA\"), () =\u003e getRepos(\"userB\")]);\n```\n\n#### **public** `.dequeue()`\n\nExecutes _n_ concurrent (based od `options.concurrent`) promises from the queue. Uses global [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). Is called automatically if `options.start` is set to `true`. Emits `resolve` and `reject` events.\n\n**Example:**\n\n```javascript\nqueue.enqueue(() =\u003e getRepos(\"userA\"));\nqueue.enqueue(() =\u003e getRepos(\"userB\"));\n\n// If \"concurrent\" is set to 1, only one promise is executed on dequeue:\nconst userA = await queue.dequeue();\nconst userB = await queue.dequeue();\n\n// If \"concurrent\" is set to 2, two promises are executed concurrently:\nconst [userA, userB] = await queue.dequeue();\n```\n\n**Note:**\n\n`.dequeue()` function throttles (is executed at most once per every `options.interval` milliseconds).\n\n#### **public** `.on(event, callback)`\n\nSets a `callback` for an `event`. You can set callback for those events: `start`, `stop`, `resolve`, `reject`, `dequeue`, `end`.\n\n**Example:**\n\n```javascript\nqueue.on(\"dequeue\", () =\u003e …);\nqueue.on(\"resolve\", data =\u003e …);\nqueue.on(\"reject\", error =\u003e …);\nqueue.on(\"start\", () =\u003e …);\nqueue.on(\"stop\", () =\u003e …);\nqueue.on(\"end\", () =\u003e …);\n```\n\n**Note:**\n\n`dequeue`, `resolve` and `reject` events are emitted per task. This means that even if `concurrent` is set to `2`, `2` events will be emitted.\n\n#### **public** `.start()`\n\nStarts the queue – it will automatically dequeue tasks periodically. Emits `start` event.\n\n```javascript\nqueue.enqueue(() =\u003e getRepos(\"userA\"));\nqueue.enqueue(() =\u003e getRepos(\"userB\"));\nqueue.enqueue(() =\u003e getRepos(\"userC\"));\nqueue.enqueue(() =\u003e getRepos(\"userD\"));\nqueue.start();\n\n// No need to call `dequeue` – you can just listen for events:\nqueue.on(\"resolve\", data =\u003e …);\nqueue.on(\"reject\", error =\u003e …);\n```\n\n#### **public** `.stop()`\n\nForces the queue to stop. New tasks will not be executed automatically even if `options.start` was set to `true`. Emits `stop` event.\n\n#### **public** `.clear()`\n\nRemoves all tasks from the queue.\n\n#### **public** `.state`\n\n- `0`: Idle state;\n- `1`: Running state;\n- `2`: Stopped state;\n\n#### **public** `.size`\n\nSize of the queue.\n\n#### **public** `.isEmpty`\n\nWhether the queue is empty, i.e. there's no tasks.\n\n#### **public** `.shouldRun`\n\nChecks whether the queue is not empty and not stopped.\n\n## Tests\n\n```bash\n$ npm test\n```\n\n## Contributing\n\n### Development\n\nWe have prepared multiple commands to help you develop `queue-promise` on your own. You will need a local copy of [Node.js](https://nodejs.org/en/) installed on your machine. Then, install project dependencies using the following command:\n\n```bash\n$ npm install\n```\n\n#### Usage\n\n```bash\n$ npm run \u003ccommand\u003e\n```\n\n#### List of commands\n\n| Command           | Description                                              |\n| :---------------- | :------------------------------------------------------- |\n| `test`            | Run all `test:*` commands described below.               |\n| `test:flow`       | Test Flow types.                                         |\n| `test:typescript` | Test TypeScript types.                                   |\n| `test:unit`       | Run unit tests.                                          |\n| `test:lint`       | Run linter tests.                                        |\n| `defs:flow`       | Build Flow type definitions.                             |\n| `defs:typescript` | Build TypeScript type definitions.                       |\n| `clean`           | Clean `dist` directory.                                  |\n| `build`           | Build package and generate type definitions.             |\n| `watch`           | Build package in watch mode.                             |\n| `release`         | Bump package version and generate a `CHANGELOG.md` file. |\n\n### License\n\n`queue-promise` was created and developed by [Bartosz Łaniewski](https://github.com/Bartozzz). The full list of contributors can be found [here](https://github.com/Bartozzz/queue-promise/graphs/contributors). The package is [MIT licensed](https://github.com/Bartozzz/queue-promise/blob/master/LICENSE).\n\n### Bug reporting\n\n[![Github Open Issues](https://img.shields.io/github/issues-raw/Bartozzz/queue-promise.svg)](https://github.com/Bartozzz/queue-promise/issues)\n[![Github Closed Issues](https://img.shields.io/github/issues-closed-raw/Bartozzz/queue-promise.svg)](https://github.com/Bartozzz/queue-promise/issues?q=is%3Aissue+is%3Aclosed)\n[![Github Pull Requests](https://img.shields.io/github/issues-pr-raw/Bartozzz/queue-promise.svg)](https://github.com/Bartozzz/queue-promise/pulls)\n\n**We want contributing to `queue-promise` to be fun, enjoyable, and educational for anyone, and everyone.** Changes and improvements are more than welcome! Feel free to fork and open a pull request. We use [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages. If you have found any issues, please [report them here](https://github.com/Bartozzz/queue-promise/new) - they are being tracked on [GitHub Issues](https://github.com/Bartozzz/queue-promise/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartozzz%2Fqueue-promise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbartozzz%2Fqueue-promise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartozzz%2Fqueue-promise/lists"}