# queue-promise
> A simple, dependency-free library for concurrent promise-based queues. Comes with with concurrency and timeout control.
Latest version **2.2.1** (published 2021-05-18) · MIT license · 0 weekly downloads
## Install
```sh
npm install queue-promise
pnpm add queue-promise
yarn add queue-promise
bun add queue-promise
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 2.2.1 |
| Published | 2021-05-18 |
| First published | 2016-05-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=8.12.0 |
| Dependencies | 0 |
| Unpacked size | 28.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 92 |
| Author | Łaniewski Bartosz |
| Maintainers | bartozzz |
| Keywords | queue, queue-tasks, queue-promise, promise, promise-chain, promise-queue |
## Links
- npm: https://www.npmjs.com/package/queue-promise
- Repository: https://github.com/Bartozzz/queue-promise
- Homepage: https://github.com/Bartozzz/queue-promise#readme
- Issues: https://github.com/Bartozzz/queue-promise/issues
- npm.io page: https://npm.io/package/queue-promise
## Alternatives
- [cron](https://npm.io/package/cron.md) — 4.9M weekly downloads
- [@vercel/queue](https://npm.io/package/@vercel/queue.md) — 731.6K weekly downloads
- [create-sonicjs](https://npm.io/package/create-sonicjs.md) — 1.6K weekly downloads
- [@exellix/jobs-api](https://npm.io/package/@exellix/jobs-api.md) — 941 weekly downloads
- [@forwardimpact/libskill](https://npm.io/package/@forwardimpact/libskill.md) — 575 weekly downloads
## Recent versions
- 2.2.1 (latest) — 2021-05-18
- 2.2.0 — 2021-05-01
- 2.1.0 — 2020-07-01
- 2.0.1 — 2020-03-29
- 2.0.0 — 2020-03-29
- 1.3.33 — 2020-03-27
- 1.3.32 — 2020-01-26
- 1.3.31 — 2019-12-13
- 1.3.3 — 2019-12-13
- 1.3.2 — 2019-11-11
- 1.3.1 — 2019-11-05
- 1.3.0 — 2018-09-27
- 1.2.1 — 2018-04-06
- 1.1.0 — 2018-03-31
- 1.0.0 — 2017-10-07
- … 4 more at https://npm.io/package/queue-promise/versions
## README
queue-promise
[](https://github.com/Bartozzz/queue-promise/actions)
[](https://snyk.io/test/github/Bartozzz/queue-promise?targetFile=package.json)
[](https://www.npmjs.com/package/queue-promise)
[](https://www.npmjs.com/package/queue-promise)
[](https://www.npmjs.com/package/queue-promise)
[](https://www.npmjs.com/package/queue-promise)
`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.
## Installation
```bash
$ npm install queue-promise
```
## Usage
### With automatic start
```javascript
import Queue from "queue-promise";
const queue = new Queue({
concurrent: 1,
interval: 2000
});
queue.on("start", () => /* … */);
queue.on("stop", () => /* … */);
queue.on("end", () => /* … */);
queue.on("resolve", data => console.log(data));
queue.on("reject", error => console.error(error));
queue.enqueue(asyncTaskA); // resolved/rejected after 0ms
queue.enqueue(asyncTaskB); // resolved/rejected after 2000ms
queue.enqueue(asyncTaskC); // resolved/rejected after 4000ms
```
### Without automatic start
```javascript
import Queue from "queue-promise";
const queue = new Queue({
concurrent: 1,
interval: 2000,
start: false,
});
queue.enqueue(asyncTaskA);
queue.enqueue(asyncTaskB);
queue.enqueue(asyncTaskC);
while (queue.shouldRun) {
// 1st iteration after 2000ms
// 2nd iteration after 4000ms
// 3rd iteration after 6000ms
const data = await queue.dequeue();
}
```
## API
#### `new Queue(options)`
Create a new `Queue` instance.
| Option | Default | Description |
| :----------- | :------ | :-------------------------------------------------------------------------- |
| `concurrent` | `5` | How many tasks should be executed in parallel |
| `interval` | `500` | How often should new tasks be executed (in ms) |
| `start` | `true` | Whether it should automatically execute new tasks as soon as they are added |
#### **public** `.enqueue(tasks)`/`.add(tasks)`
Adds 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.
**Example:**
```javascript
async function getRepos(user) {
return await github.getRepos(user);
}
queue.enqueue(() => {
return getRepos("userA");
});
queue.enqueue(async () => {
await getRepos("userB");
});
// …equivalent to:
queue.enqueue([() => getRepos("userA"), () => getRepos("userB")]);
```
#### **public** `.dequeue()`
Executes _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.
**Example:**
```javascript
queue.enqueue(() => getRepos("userA"));
queue.enqueue(() => getRepos("userB"));
// If "concurrent" is set to 1, only one promise is executed on dequeue:
const userA = await queue.dequeue();
const userB = await queue.dequeue();
// If "concurrent" is set to 2, two promises are executed concurrently:
const [userA, userB] = await queue.dequeue();
```
**Note:**
`.dequeue()` function throttles (is executed at most once per every `options.interval` milliseconds).
#### **public** `.on(event, callback)`
Sets a `callback` for an `event`. You can set callback for those events: `start`, `stop`, `resolve`, `reject`, `dequeue`, `end`.
**Example:**
```javascript
queue.on("dequeue", () => …);
queue.on("resolve", data => …);
queue.on("reject", error => …);
queue.on("start", () => …);
queue.on("stop", () => …);
queue.on("end", () => …);
```
**Note:**
`dequeue`, `resolve` and `reject` events are emitted per task. This means that even if `concurrent` is set to `2`, `2` events will be emitted.
#### **public** `.start()`
Starts the queue – it will automatically dequeue tasks periodically. Emits `start` event.
```javascript
queue.enqueue(() => getRepos("userA"));
queue.enqueue(() => getRepos("userB"));
queue.enqueue(() => getRepos("userC"));
queue.enqueue(() => getRepos("userD"));
queue.start();
// No need to call `dequeue` – you can just listen for events:
queue.on("resolve", data => …);
queue.on("reject", error => …);
```
#### **public** `.stop()`
Forces the queue to stop. New tasks will not be executed automatically even if `options.start` was set to `true`. Emits `stop` event.
#### **public** `.clear()`
Removes all tasks from the queue.
#### **public** `.started`
Whether the queue is running.
#### **public** `.stopped`
Whether the queue has been forced to stop by calling `Queue.stop`.
#### **public** `.size`
Size of the queue.
#### **public** `.isEmpty`
Whether the queue is empty, i.e. there's no tasks.
#### **public** `.shouldRun`
Checks whether the queue is not empty and not stopped.
## Tests
```bash
$ npm test
```
## Contributing
### Development
We 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:
```bash
$ npm install
```
#### Usage
```bash
$ npm run
```
#### List of commands
| Command | Description |
| :---------------- | :------------------------------------------------------- |
| `test` | Run all `test:*` commands described below. |
| `test:flow` | Test Flow types. |
| `test:typescript` | Test TypeScript types. |
| `test:unit` | Run unit tests. |
| `test:lint` | Run linter tests. |
| `defs:flow` | Build Flow type definitions. |
| `defs:typescript` | Build TypeScript type definitions. |
| `clean` | Clean `dist` directory. |
| `build` | Build package and generate type definitions. |
| `watch` | Build package in watch mode. |
| `release` | Bump package version and generate a `CHANGELOG.md` file. |
### License
`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).
### Bug reporting
[](https://github.com/Bartozzz/queue-promise/issues)
[](https://github.com/Bartozzz/queue-promise/issues?q=is%3Aissue+is%3Aclosed)
[](https://github.com/Bartozzz/queue-promise/pulls)
**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).
---
_Source: https://npm.io/package/queue-promise · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._