# grouped-queue

> In memory queue system prioritizing tasks

Latest version **2.1.0** (published 2025-08-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install grouped-queue
pnpm add grouped-queue
yarn add grouped-queue
bun add grouped-queue
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2025-08-17 |
| First published | 2013-11-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=8.0.0 |
| Dependencies | 0 |
| Unpacked size | 9.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 86 |
| Author | Simon Boudrias |
| Maintainers | sboudrias, mshima |
| Keywords | queue, async, task, flow, control |

## Links

- npm: https://www.npmjs.com/package/grouped-queue
- Repository: https://github.com/SBoudrias/grouped-queue
- Homepage: https://github.com/SBoudrias/grouped-queue#readme
- Issues: https://github.com/SBoudrias/grouped-queue/issues
- npm.io page: https://npm.io/package/grouped-queue

## 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.1.0 (latest) — 2025-08-17
- 2.0.0-beta.2 (next-2) — 2020-11-20
- 2.0.0 — 2021-01-29
- 2.0.0-beta.1 — 2020-11-18
- 2.0.0-beta.0 — 2020-11-17
- 1.1.0 — 2020-04-16
- 1.0.0 — 2020-01-10
- 0.3.3 — 2016-11-20
- 0.3.2 — 2015-11-30
- 0.3.0 — 2014-06-02
- 0.2.1 — 2014-01-22
- 0.2.0 — 2014-01-17
- 0.1.2 — 2014-01-13
- 0.1.1 — 2014-01-13
- 0.1.0 — 2013-11-26

## README

# Grouped Queue

In memory queue system prioritizing tasks.

# Documentation

## Installation

```bash
npm install --save grouped-queue
```

## Methods

### Constructor

The constructor takes an optional array of task groups. The first `String` name will be the first queue to be emptied, the second string will be the second group emptied, etc.

By default, the constructor will always add a `default` queue in the last position. You can overwrite the position of the `default` group if you specify it explicitly.

```javascript
import Queue from "grouped-queue";

const queue = new Queue(["first", "second", "third"]);
```

### Queue#add `add( [group], task, [options] )`

Add a task into a group queue. If no group name is specified, `default` will be used.

Implicitly, each time you add a task, the queue will start emptying (if not already running).

Each task function is passed a callback function. This callback must be called when the task is complete.

```javascript
queue.add((cb) => {
  DB.fetch().then(cb);
});
```

#### Option: `once`

You can register tasks in queues that will be dropped if they're already planned. This is done with the `once` option. You pass a String (basically a name) to the `once` option.

```javascript
// This one will eventually run
queue.add(method, { once: "readDB" });

// This one will be dropped as `method` is currently in the queue
queue.add(method3, { once: "readDB" });
```

#### Option: `run`

You can register a task without launching the run loop by passing the argument `run: false`.

```javascript
queue.add(method, { run: false });
```

### Delaying runs

If you don't want tasks to run as they're added, you can hold the queue until manually starting.

```javascript
const queue = new Queue(
  ["first", "second", "third"],
  // `runOnAdd` option; this boolean instruct the queue to not auto-start.
  false,
);

// Later on, to start processing
queue.start();

// And pause to stop processing new tasks; running task will complete.
queue.pause();
```

## Events

### `end`

This event is called **each time** the queue emptied itself.

```javascript
queue.on("end", () => {
  console.log("done!");
});
```

# Contributing

- **Unit test**: Unit tests are written in Mocha. Please add a unit test for every new feature
  or bug fix. `npm test` to run the test suite.
- **Documentation**: Add documentation for every API change. Feel free to send corrections
  or better docs!
- **Pull Requests**: Send _fixes_ PR on the `master` branch.

# License

Copyright (c) 2013 Simon Boudrias (twitter: @vaxilart)  
Licensed under the MIT license.

---
_Source: https://npm.io/package/grouped-queue · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._