### Install fastq via npm

Source: https://github.com/mcollina/fastq/blob/master/README.md

Install the fastq package using npm. This is the first step to using the library in your project.

```bash
npm i fastq --save
```

--------------------------------

### TypeScript Integration (Callback API)

Source: https://github.com/mcollina/fastq/blob/master/README.md

Provides an example of using fastq with TypeScript, demonstrating type definitions for tasks and the worker callback. Imports necessary types from 'fastq'.

```typescript
'use strict'

import * as fastq from "fastq";
import type { queue, done } from "fastq";

type Task = {
  id: number
}

const q: queue<Task> = fastq(worker, 1)

q.push({ id: 42})

function worker (arg: Task, cb: done) {
  console.log(arg.id)
  cb(null)
}
```

--------------------------------

### Push Task

Source: https://context7.com/mcollina/fastq/llms.txt

Adds a task to the end of the queue. The task will start immediately if a slot is available, otherwise it waits. An optional callback can be provided to be notified upon completion.

```APIDOC
## `queue.push(task[, done])` — Add a task to the end of the queue

Enqueues a task. If a slot is available it starts immediately; otherwise the task waits. The optional `done(err, result)` callback is called when the worker finishes.

### Parameters

- **task** (any) - Required - The task data to be processed.
- **done** (function) - Optional - A callback function that receives `(err, result)` when the task is completed.

### Example

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  cb(null, `processed: ${task}`)
}, 1)

// With callback
queue.push('hello', (err, result) => {
  if (err) throw err
  console.log(result) // processed: hello
})

// Without callback (result is discarded)
queue.push('fire-and-forget')

// Introspect queue length before tasks run
queue.push('a')
queue.push('b')
console.log(queue.length()) // 1 or 2 depending on timing
```
```

--------------------------------

### queue.running()

Source: https://context7.com/mcollina/fastq/llms.txt

Get the number of tasks currently being processed by workers. This counts tasks that have started but not yet completed.

```APIDOC
## queue.running()

### Description
Returns the number of tasks that are currently in flight, meaning they have been dispatched to a worker but have not yet called their callback.

### Method
- `running()`

### Returns
- (number) The count of tasks currently being processed.
```

--------------------------------

### queue.concurrency

Source: https://context7.com/mcollina/fastq/llms.txt

Get or set the concurrency level of the queue at runtime. Increasing concurrency dispatches more waiting tasks immediately.

```APIDOC
## queue.concurrency

### Description
This read/write property allows you to get or set the maximum number of tasks that can be processed concurrently. Increasing the concurrency immediately starts more waiting tasks. Decreasing it takes effect once in-flight tasks complete. Setting it below 1 will throw an error.

### Property
- `concurrency` (number) - The current concurrency level.
```

--------------------------------

### Get Number of Running Tasks with `queue.running()`

Source: https://context7.com/mcollina/fastq/llms.txt

Returns the count of worker invocations currently in progress. This includes tasks that have started but not yet completed their callback.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  console.log('running:', queue.running()) // 1 or 2
  setTimeout(() => cb(null), 50)
}, 2)

queue.push(1)
queue.push(2)
queue.push(3)

// After two tasks start: queue.running() === 2

```

--------------------------------

### Get Number of Waiting Tasks with `queue.length()`

Source: https://context7.com/mcollina/fastq/llms.txt

Returns the count of tasks queued but not yet dispatched. Tasks currently being processed are not included in this count.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  setImmediate(() => cb(null))
}, 1)

queue.push(1)
queue.push(2)
queue.push(3)

console.log(queue.length()) // 2 (task 1 is running, 2 and 3 are waiting)

```

--------------------------------

### Adjust Concurrency at Runtime with `queue.concurrency`

Source: https://context7.com/mcollina/fastq/llms.txt

A read/write property to get or set the number of concurrent tasks. Increasing concurrency immediately dispatches more tasks. Decreasing it takes effect after current tasks finish. Setting concurrency below 1 throws an error.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  setTimeout(() => cb(null), 100)
}, 1)

;[1,2,3,4,5].forEach(n => queue.push(n))

console.log(queue.concurrency)   // 1
console.log(queue.running())     // 1

// Scale up: immediately dispatches more tasks
queue.concurrency = 3
console.log(queue.running())     // 3

// Scale down: takes effect after current workers finish
queue.concurrency = 1

```

--------------------------------

### Wait for Promise Queue to Drain

Source: https://context7.com/mcollina/fastq/llms.txt

Use `drained()` to get a Promise that resolves when all tasks in a promise-based queue have been processed. This can be called multiple times for independent waiting.

```javascript
'use strict'
const { promise: queueAsPromised } = require('fastqueue')
const { promisify } = require('util')
const sleep = promisify(setTimeout)

const queue = queueAsPromised(async function worker(task) {
  await sleep(task)
  return task
}, 2)

// Push tasks without awaiting individual results
for (const ms of [30, 20, 10, 40]) {
  queue.push(ms)
}

console.log('waiting for queue to drain...')
await queue.drained()
console.log('all done')

// Re-use the queue after draining
for (const ms of [5, 15]) {
  queue.push(ms)
}
await queue.drained()
console.log('second batch done')
```

--------------------------------

### Run ESLint with Neostandard Configuration

Source: https://github.com/mcollina/fastq/blob/master/CLAUDE.md

Execute ESLint with the neostandard configuration for code linting. This command enforces coding style and identifies potential issues.

```bash
npm run lint
```

--------------------------------

### Run Linting and Unit Tests

Source: https://github.com/mcollina/fastq/blob/master/CLAUDE.md

Execute all tests and linting checks with a 100% coverage requirement. This command ensures code quality and correctness.

```bash
npm test
```

--------------------------------

### Basic Usage with Promise API

Source: https://github.com/mcollina/fastq/blob/master/README.md

Shows how to create a queue using the promise-based API. The worker function is async and returns a promise. Tasks are pushed and awaited.

```javascript
const queue = require('fastq').promise(worker, 1)

async function worker (arg) {
  return arg * 2
}

async function run () {
  const result = await queue.push(42)
  console.log('the result is', result)
}

run()
```

--------------------------------

### Basic Usage with Callback API

Source: https://github.com/mcollina/fastq/blob/master/README.md

Demonstrates creating a queue with a concurrency of 1 and pushing a task. The worker function processes the task and returns a result via a callback.

```javascript
'use strict'

const queue = require('fastq')(worker, 1)

queue.push(42, function (err, result) {
  if (err) { throw err }
  console.log('the result is', result)
})

function worker (arg, cb) {
  cb(null, arg * 2)
}
```

--------------------------------

### Queue with Context

Source: https://context7.com/mcollina/fastq/llms.txt

Demonstrates how to bind a context object to the worker function, making it available as `this` within the worker.

```APIDOC
## `fastqueue([context], worker, concurrency)` with `this` context — Bind a context object to the worker

Pass a context object as the first argument to have it available as `this` inside the worker function.

### Parameters

- **context** (object) - Required - The context object to bind to the worker function.
- **worker** (function) - Required - The function to execute for each task. It receives `(task, callback)` and `this` refers to the context object.
- **concurrency** (number) - Required - The maximum number of tasks to run in parallel. Must be at least 1.

### Example

```javascript
'use strict'
const fastqueue = require('fastqueue')

const ctx = { multiplier: 10 }

const queue = fastqueue(ctx, function worker(task, cb) {
  // `this` is ctx
  cb(null, task * this.multiplier)
}, 1)

queue.push(7, (err, result) => {
  console.log(result) // 70
})
```
```

--------------------------------

### Create Callback-Based Queue with fastqueue

Source: https://context7.com/mcollina/fastq/llms.txt

Use this to create a queue that processes tasks using a callback-style worker function. Set lifecycle hooks like `drain`, `empty`, and `saturated` for event handling. An error handler can be globally registered.

```javascript
'use strict'
const fastqueue = require('fastqueue')

// Worker receives (task, cb) — call cb(err, result) when done
function worker(task, cb) {
  // Simulate async work
  setTimeout(() => {
    if (task < 0) return cb(new Error('negative task'))
    cb(null, task * 2)
  }, 10)
}

// Create queue with concurrency 2
const queue = fastqueue(worker, 2)

// Set a global error handler (called for every errored task)
queue.error(function (err, task) {
  console.error('Task failed:', task, err.message)
})

// Called when the last running task completes
queue.drain = function () {
  console.log('All tasks done')
}

// Called when the last task leaves the waiting list
queue.empty = function () {
  console.log('No more tasks waiting')
}

// Called when the queue reaches the concurrency limit
queue.saturated = function () {
  console.log('Queue saturated, tasks are waiting')
}

queue.push(1, (err, result) => {
  if (err) throw err
  console.log('Result:', result) // Result: 2
})

queue.push(2, (err, result) => {
  if (err) throw err
  console.log('Result:', result) // Result: 4
})

// Push without callback (fire-and-forget)
queue.push(3)

// Push multiple tasks
;[4, 5, 6].forEach(n => queue.push(n, (err, res) => {
  if (err) throw err
  console.log(`Task ${n} → ${res}`)
}))
// Output (order may vary per concurrency):
// Queue saturated, tasks are waiting
// No more tasks waiting
// Result: 2
// Result: 4
// Task 4 → 8  ... etc.
// All tasks done

```

--------------------------------

### fastqueue()

Source: https://github.com/mcollina/fastq/blob/master/README.md

Creates a new queue instance. It can optionally take a 'that' context for the worker function.

```APIDOC
## fastqueue([that], worker, concurrency)

### Description
Creates a new queue.

### Parameters
* `that` (object, optional) - Context of the `worker` function.
* `worker` (function) - The function to execute for each task.
* `concurrency` (number) - The number of tasks that can be executed in parallel.
```

--------------------------------

### Wrap Queue with Promise API

Source: https://github.com/mcollina/fastq/blob/master/CLAUDE.md

Wraps an existing callback-based queue with a Promise-compatible API. This allows for modern async/await usage.

```javascript
queueAsPromised()
```

--------------------------------

### queue.resume()

Source: https://github.com/mcollina/fastq/blob/master/README.md

Resumes the processing of tasks in the queue.

```APIDOC
## queue.resume()

### Description
Resume the processing of tasks.
```

--------------------------------

### Run Tests on Legacy Node.js Versions

Source: https://github.com/mcollina/fastq/blob/master/CLAUDE.md

Execute tests on older versions of Node.js to ensure compatibility. This is important for maintaining support for a wider range of environments.

```bash
npm run legacy
```

--------------------------------

### TypeScript Integration (Promise API)

Source: https://github.com/mcollina/fastq/blob/master/README.md

Shows TypeScript usage with the promise-based API of fastq. Includes type definitions for tasks and the async worker function, highlighting automatic error handling.

```typescript
'use strict'

import * as fastq from "fastq";
import type { queueAsPromised } from "fastq";

type Task = {
  id: number
}

const q: queueAsPromised<Task> = fastq.promise(asyncWorker, 1)

q.push({ id: 42}).catch((err) => console.error(err))

async function asyncWorker (arg: Task): Promise<void> {
  // No need for a try-catch block, fastq handles errors automatically
  console.log(arg.id)
}
```

--------------------------------

### Kill Queue and Drain Once with `queue.killAndDrain()`

Source: https://context7.com/mcollina/fastq/llms.txt

Similar to `kill()`, but calls the current `drain` function one final time before resetting it to a no-op. Useful for graceful shutdowns requiring a single completion signal.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  setImmediate(() => cb(null))
}, 1)

queue.drain = () => console.log('drain called once during killAndDrain')

queue.push(1)
queue.push(2)
queue.push(3)

queue.killAndDrain()
// Output: drain called once during killAndDrain

```

--------------------------------

### queue.unshift(task) => Promise

Source: https://github.com/mcollina/fastq/blob/master/README.md

Adds a task to the beginning of the queue. Returns a Promise that resolves/rejects when the task is completed.

```APIDOC
## queue.unshift(task) => Promise

### Description
Add a task at the beginning of the queue. The returned `Promise` will be fulfilled (rejected) when the task is completed successfully (unsuccessfully).

This promise could be ignored as it will not lead to a `'unhandledRejection'`.

### Parameters
* **task** (any) - The task to add to the queue.
```

--------------------------------

### queue.unshift(task, done)

Source: https://github.com/mcollina/fastq/blob/master/README.md

Adds a task to the beginning of the queue. The provided callback function will be invoked upon task completion.

```APIDOC
## queue.unshift(task, done)

### Description
Add a task at the beginning of the queue. `done(err, result)` will be called when the task was processed.

### Parameters
* `task` - The task to be added to the queue.
* `done` (function) - Callback function `done(err, result)` executed when the task is processed.
```

--------------------------------

### fastqueue.promise([that], worker(arg), concurrency)

Source: https://github.com/mcollina/fastq/blob/master/README.md

Creates a new queue with Promise APIs, offering modified push and unshift methods.

```APIDOC
## fastqueue.promise([that], worker(arg), concurrency)

### Description
Creates a new queue with `Promise` apis. It also offers all the methods and properties of the object returned by [`fastqueue`](#fastqueue) with the modified [`push`](#pushPromise) and [`unshift`](#unshiftPromise) methods.

Node v10+ is required to use the promisified version.

### Arguments
* `that`, optional context of the `worker` function.
* `worker`, worker function, it would be called with `that` as `this`, if that is specified. It MUST return a `Promise`.
* `concurrency`, number of concurrent tasks that could be executed in parallel.
```

--------------------------------

### Run Unit Tests Only

Source: https://github.com/mcollina/fastq/blob/master/CLAUDE.md

Execute unit tests with coverage checks for lines, branches, and functions. This is useful for focused testing.

```bash
npm run unit
```

--------------------------------

### Generate HTML Coverage Reports

Source: https://github.com/mcollina/fastq/blob/master/CLAUDE.md

Generate detailed HTML reports for code coverage. This helps in identifying areas that need more testing.

```bash
npm run coverage
```

--------------------------------

### Setting 'this' Context for Worker

Source: https://github.com/mcollina/fastq/blob/master/README.md

Illustrates how to set a custom 'this' context for the worker function when creating the queue. Both the queue creation and the worker function demonstrate accessing 'this'.

```javascript
'use strict'

const that = { hello: 'world' }
const queue = require('fastq')(that, worker, 1)

queue.push(42, function (err, result) {
  if (err) { throw err }
  console.log(this)
  console.log('the result is', result)
})

function worker (arg, cb) {
  console.log(this)
  cb(null, arg * 2)
}
```

--------------------------------

### Add Task to Front of Queue with fastqueue.unshift

Source: https://context7.com/mcollina/fastq/llms.txt

Use `queue.unshift` to add tasks to the beginning of the queue, giving them higher priority than tasks added with `push`. This is useful for immediately processing urgent tasks.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const order = []
const queue = fastqueue(function worker(task, cb) {
  order.push(task)
  setImmediate(() => cb(null, task))
}, 1)

queue.push(1)
queue.push(4)
queue.unshift(3)  // jumps ahead of 4
queue.unshift(2)  // jumps ahead of 3

// Worker sees tasks in order: 1, 2, 3, 4
queue.drain = () => console.log(order) // [1, 2, 3, 4]

```

--------------------------------

### Push Task to Promise Queue

Source: https://github.com/mcollina/fastq/blob/master/CLAUDE.md

Adds a task to the queue and returns a Promise. This is suitable for use with async/await.

```javascript
await queue.push(task)
```

--------------------------------

### queue.pause() / queue.resume()

Source: https://context7.com/mcollina/fastq/llms.txt

Pause and resume task processing. `pause()` stops dispatching new tasks, while `resume()` restarts it. The `queue.paused` property indicates the current state.

```APIDOC
## queue.pause() / queue.resume()

### Description
Pauses task dispatching to workers. In-flight tasks continue processing. `resume()` restarts task dispatching.

### Method
- `pause()`
- `resume()`

### Property
- `queue.paused` (boolean) - Read-only property reflecting the current paused state.
```

--------------------------------

### queue.killAndDrain()

Source: https://github.com/mcollina/fastq/blob/master/README.md

Similar to `kill()`, but the `drain` function is called before resetting to empty.

```APIDOC
## queue.killAndDrain()

### Description
Same than `kill` but the `drain` function will be called before reset to empty.

### Method
`killAndDrain()`

### Parameters
None
```

--------------------------------

### Inspect Waiting Tasks with `queue.getQueue()`

Source: https://context7.com/mcollina/fastq/llms.txt

Returns an array of tasks currently waiting to be dispatched. Useful for debugging or implementing custom shutdown logic.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  setImmediate(() => cb(null))
}, 1)

queue.push(10)
queue.push(20)
queue.push(30)

console.log(queue.getQueue()) // [20, 30]  (10 is already running)

```

--------------------------------

### High-priority enqueue with Promise return using queue.unshift()

Source: https://context7.com/mcollina/fastq/llms.txt

Similar to `push` in a promise queue, `queue.unshift()` also returns a Promise but inserts the task at the beginning of the waiting list, giving it higher priority.

```javascript
'use strict'
const { promise: queueAsPromised } = require('fastqueue')

const order = []
const queue = queueAsPromised(async function worker(task) {
  order.push(task)
  return task
}, 1)

await Promise.all([
  queue.push(1),
  queue.push(4),
  queue.unshift(3),
  queue.unshift(2)
])

console.log(order) // [1, 2, 3, 4]
```

--------------------------------

### Create Callback-Based Queue

Source: https://github.com/mcollina/fastq/blob/master/CLAUDE.md

Factory function to create a callback-based queue. It takes a context, a worker function, and a concurrency limit.

```javascript
fastqueue(context, worker, concurrency)
```

--------------------------------

### queue.push(task) => Promise (promise queue)

Source: https://context7.com/mcollina/fastq/llms.txt

In a promise-based queue, this method enqueues a task and returns a Promise. The Promise resolves with the worker's return value or rejects if the worker throws an error. Unhandled rejections are prevented even if the returned Promise is ignored.

```APIDOC
## queue.push(task) => Promise (promise queue)

### Description
In a promise queue, `push` returns a Promise that resolves with the worker's return value or rejects with any thrown error. The ignored Promise does **not** cause an `unhandledRejection`.

### Parameters
#### task
- **task** (any) - Required - The task to be added to the queue.

### Returns
- **Promise** - A Promise that resolves with the result of the worker function or rejects with an error.

### Example
```javascript
'use strict'
const { promise: queueAsPromised } = require('fastqueue')

const queue = queueAsPromised(async function worker(task) {
  return `hello ${task}`
}, 1)

const res = await queue.push('world')
console.log(res) // hello world

queue.push('node')
  .then(r => console.log(r))   // hello node
  .catch(err => console.error(err))
```
```

--------------------------------

### queue.push(task) => Promise

Source: https://github.com/mcollina/fastq/blob/master/README.md

Adds a task to the end of the queue. Returns a Promise that resolves/rejects when the task is completed.

```APIDOC
## queue.push(task) => Promise

### Description
Add a task at the end of the queue. The returned `Promise` will be fulfilled (rejected) when the task is completed successfully (unsuccessfully).

This promise could be ignored as it will not lead to a `'unhandledRejection'`.

### Parameters
* **task** (any) - The task to add to the queue.
```

--------------------------------

### Create a Promise-based queue with fastqueue.promise()

Source: https://context7.com/mcollina/fastq/llms.txt

Use `fastqueue.promise()` to create a queue where `push` and `unshift` return Promises. The worker function must be an async function or return a Promise. This API inherits all methods from the callback queue and adds `drained()`.

```javascript
'use strict'
const { promise: queueAsPromised } = require('fastqueue')
const { promisify } = require('util')
const sleep = promisify(setTimeout)

async function worker(task) {
  await sleep(10)
  if (task < 0) throw new Error('negative')
  return task * 3
}

const queue = queueAsPromised(worker, 2)

// Awaitable push
async function main() {
  const result = await queue.push(7)
  console.log(result) // 21

  // Error handling
  try {
    await queue.push(-1)
  } catch (err) {
    console.error(err.message) // negative
  }

  // Ignore returned Promise safely — no unhandledRejection
  queue.push(-5)

  // Fire many tasks and wait for all
  const results = await Promise.all([4, 5, 6].map(n => queue.push(n)))
  console.log(results) // [12, 15, 18]
}

main()
```

--------------------------------

### queue.kill()

Source: https://context7.com/mcollina/fastq/llms.txt

Drain the waiting list without running remaining tasks. In-flight tasks will complete, but all tasks still in the queue will be discarded.

```APIDOC
## queue.kill()

### Description
Removes all tasks currently waiting in the queue without executing them. Any tasks already being processed by workers will continue to completion. The `drain` event handler is reset to a no-op.

### Method
- `kill()`
```

--------------------------------

### queue.getQueue()

Source: https://context7.com/mcollina/fastq/llms.txt

Inspect the list of tasks currently waiting in the queue. This is useful for debugging or implementing custom drain logic.

```APIDOC
## queue.getQueue()

### Description
Returns an array containing all tasks that are currently waiting in the queue and have not yet been dispatched.

### Method
- `getQueue()`

### Returns
- (Array) An array of waiting tasks.
```

--------------------------------

### queue.push(task, done)

Source: https://github.com/mcollina/fastq/blob/master/README.md

Adds a task to the end of the queue. The provided callback function will be invoked upon task completion.

```APIDOC
## queue.push(task, done)

### Description
Add a task at the end of the queue. `done(err, result)` will be called when the task was processed.

### Parameters
* `task` - The task to be added to the queue.
* `done` (function) - Callback function `done(err, result)` executed when the task is processed.
```

--------------------------------

### Callback-based Queue Creation

Source: https://context7.com/mcollina/fastq/llms.txt

Creates a new callback-based queue that processes tasks concurrently up to a specified limit. The optional context object can be bound to the worker function.

```APIDOC
## `fastqueue([context], worker, concurrency)` — Create a callback-based queue

Creates a new queue that calls `worker(task, callback)` for each task, up to `concurrency` tasks in parallel. The optional `context` object becomes `this` inside the worker. Throws if `concurrency` is less than 1.

### Parameters

- **context** (object) - Optional - The context object to bind to the worker function.
- **worker** (function) - Required - The function to execute for each task. It receives `(task, callback)`.
- **concurrency** (number) - Required - The maximum number of tasks to run in parallel. Must be at least 1.

### Example

```javascript
'use strict'
const fastqueue = require('fastqueue')

// Worker receives (task, cb) — call cb(err, result) when done
function worker(task, cb) {
  // Simulate async work
  setTimeout(() => {
    if (task < 0) return cb(new Error('negative task'))
    cb(null, task * 2)
  }, 10)
}

// Create queue with concurrency 2
const queue = fastqueue(worker, 2)

// Set a global error handler (called for every errored task)
queue.error(function (err, task) {
  console.error('Task failed:', task, err.message)
})

// Called when the last running task completes
queue.drain = function () {
  console.log('All tasks done')
}

// Called when the last task leaves the waiting list
queue.empty = function () {
  console.log('No more tasks waiting')
}

// Called when the queue reaches the concurrency limit
queue.saturated = function () {
  console.log('Queue saturated, tasks are waiting')
}

queue.push(1, (err, result) => {
  if (err) throw err
  console.log('Result:', result) // Result: 2
})

queue.push(2, (err, result) => {
  if (err) throw err
  console.log('Result:', result) // Result: 4
})

// Push without callback (fire-and-forget)
queue.push(3)

// Push multiple tasks
;[4, 5, 6].forEach(n => queue.push(n, (err, res) => {
  if (err) throw err
  console.log(`Task ${n} → ${res}`)
}))
```
```

--------------------------------

### Enqueue with Promise return using queue.push() in a promise queue

Source: https://context7.com/mcollina/fastq/llms.txt

In a promise-based queue, `queue.push()` returns a Promise that resolves with the worker's result or rejects with any thrown error. Ignored Promises do not cause unhandled rejections.

```javascript
'use strict'
const { promise: queueAsPromised } = require('fastqueue')

const queue = queueAsPromised(async function worker(task) {
  return `hello ${task}`
}, 1)

// Await individual result
const res = await queue.push('world')
console.log(res) // hello world

// Chain with .then/.catch
queue.push('node')
  .then(r => console.log(r))   // hello node
  .catch(err => console.error(err))
```

--------------------------------

### Unshift Task

Source: https://context7.com/mcollina/fastq/llms.txt

Adds a task to the front of the queue, giving it higher priority than tasks already waiting.

```APIDOC
## `queue.unshift(task[, done])` — Add a task to the front of the queue

Like `push`, but inserts the task at the beginning of the waiting list, giving it highest priority among queued (not yet started) tasks.

### Parameters

- **task** (any) - Required - The task data to be processed.
- **done** (function) - Optional - A callback function that receives `(err, result)` when the task is completed.

### Example

```javascript
'use strict'
const fastqueue = require('fastqueue')

const order = []
const queue = fastqueue(function worker(task, cb) {
  order.push(task)
  setImmediate(() => cb(null, task))
}, 1)

queue.push(1)
queue.push(4)
queue.unshift(3)  // jumps ahead of 4
queue.unshift(2)  // jumps ahead of 3

// Worker sees tasks in order: 1, 2, 3, 4
queue.drain = () => console.log(order) // [1, 2, 3, 4]
```
```

--------------------------------

### fastqueue.promise(worker, concurrency)

Source: https://github.com/mcollina/fastq/blob/master/README.md

Creates a new queue instance that resolves promises upon task completion.

```APIDOC
## fastqueue.promise(worker, concurrency)

### Description
Creates a new queue that resolves promises upon task completion.

### Parameters
* `worker` (function) - The async function to execute for each task.
* `concurrency` (number) - The number of tasks that can be executed in parallel.
```

--------------------------------

### Push Task to Callback Queue

Source: https://github.com/mcollina/fastq/blob/master/CLAUDE.md

Adds a task to the queue using the traditional Node.js callback style. The `done` callback is invoked upon completion.

```javascript
queue.push(task, done)
```

--------------------------------

### queue.kill()

Source: https://github.com/mcollina/fastq/blob/master/README.md

Removes all tasks waiting to be processed and resets the 'drain' function to an empty function.

```APIDOC
## queue.kill()

### Description
Removes all tasks waiting to be processed, and reset `drain` to an empty function.

### Method
`kill()`

### Parameters
None
```

--------------------------------

### Pause and Resume Task Processing with `queue.pause()` and `queue.resume()`

Source: https://context7.com/mcollina/fastq/llms.txt

Use `pause()` to stop dispatching new tasks; in-flight tasks continue. `resume()` restarts processing. The `queue.paused` property indicates the current state.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  setImmediate(() => cb(null, task))
}, 2)

queue.pause()
console.log(queue.paused) // true

queue.push(1, (err, res) => console.log('done:', res))
queue.push(2, (err, res) => console.log('done:', res))

// Nothing executes yet; queue.length() === 2
console.log(queue.length()) // 2

queue.resume()
console.log(queue.paused) // false
// Workers now start processing
// done: 1
// done: 2

```

--------------------------------

### fastqueue.promise([context], asyncWorker, concurrency)

Source: https://context7.com/mcollina/fastq/llms.txt

Creates a queue where task processing methods (`push`, `unshift`) return Promises. The provided `asyncWorker` must be an async function or return a Promise. This API inherits all methods from the callback queue and adds `drained()`.

```APIDOC
## fastqueue.promise([context], asyncWorker, concurrency)

### Description
Returns a queue whose `push` and `unshift` methods return Promises. The worker must be an async function (or return a Promise). Inherits all properties and methods of the callback queue, plus `drained()`.

### Parameters
#### context
- **context** (any) - Optional - The `this` context for the worker function.
#### asyncWorker
- **asyncWorker** (function) - Required - An async function that processes tasks.
#### concurrency
- **concurrency** (number) - Required - The maximum number of tasks to process concurrently.

### Example
```javascript
'use strict'
const { promise: queueAsPromised } = require('fastqueue')
const { promisify } = require('util')
const sleep = promisify(setTimeout)

async function worker(task) {
  await sleep(10)
  if (task < 0) throw new Error('negative')
  return task * 3
}

const queue = queueAsPromised(worker, 2)

async function main() {
  const result = await queue.push(7)
  console.log(result) // 21

  try {
    await queue.push(-1)
  } catch (err) {
    console.error(err.message) // negative
  }

  queue.push(-5)

  const results = await Promise.all([4, 5, 6].map(n => queue.push(n)))
  console.log(results) // [12, 15, 18]
}

main()
```
```

--------------------------------

### queue.getQueue()

Source: https://github.com/mcollina/fastq/blob/master/README.md

Retrieves all tasks currently being processed or waiting in the queue. Returns an empty array if the queue is empty.

```APIDOC
## queue.getQueue()

### Description
Returns all the tasks be processed (in the queue). Returns empty array when there are no tasks
```

--------------------------------

### queue.killAndDrain()

Source: https://context7.com/mcollina/fastq/llms.txt

Kill the queue and call the `drain` function once. This method discards all waiting tasks and then executes the `drain` handler one final time.

```APIDOC
## queue.killAndDrain()

### Description
Combines the functionality of `kill()` with a final invocation of the `drain` handler. All waiting tasks are discarded, and then the `drain` function is called once before being reset to a no-op. This is useful for graceful shutdown procedures.

### Method
- `killAndDrain()`
```

--------------------------------

### Set a global error handler with queue.error(handler)

Source: https://context7.com/mcollina/fastq/llms.txt

Register a global error handler using `queue.error(handler)` to centrally log errors for any task that completes with an error. This handler is invoked in addition to any per-task callback.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  if (task === 'bad') return cb(new Error('bad task'))
  cb(null, task.toUpperCase())
}, 1)

queue.error(function (err, task) {
  // Called whenever a worker invokes cb(err, ...)
  console.error(`[error] task="${task}" message="${err.message}"`) 
})

queue.push('good', (err, res) => console.log(res))       // GOOD
queue.push('bad',  (err) => console.log(err.message))    // bad task
// [error] task="bad" message="bad task"
```

--------------------------------

### Add Task to End of Queue with fastqueue.push

Source: https://context7.com/mcollina/fastq/llms.txt

Use `queue.push` to add tasks to the end of the queue. A callback can be provided to handle the result or error of the task processing. Tasks can also be pushed without a callback for fire-and-forget behavior.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  cb(null, `processed: ${task}`)
}, 1)

// With callback
queue.push('hello', (err, result) => {
  if (err) throw err
  console.log(result) // processed: hello
})

// Without callback (result is discarded)
queue.push('fire-and-forget')

// Introspect queue length before tasks run
queue.push('a')
queue.push('b')
console.log(queue.length()) // 1 or 2 depending on timing

```

--------------------------------

### Discard Waiting Tasks with `queue.kill()`

Source: https://context7.com/mcollina/fastq/llms.txt

Removes all waiting tasks from the queue and resets the `drain` handler to a no-op. In-flight tasks will still complete.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  setImmediate(() => cb(null, task))
}, 1)

queue.drain = () => console.log('drained') // will NOT fire after kill()

queue.push(1, (err, res) => console.log('task 1 done:', res)) // will run (already dispatched)
queue.push(2, (err) => console.log('task 2'))  // will be discarded
queue.push(3, (err) => console.log('task 3'))  // will be discarded

queue.kill()

console.log(queue.length()) // 0
// Output: task 1 done: 1  (tasks 2 and 3 never run)

```

--------------------------------

### queue.idle()

Source: https://github.com/mcollina/fastq/blob/master/README.md

Checks if the queue is idle. Returns true if no tasks are being processed or waiting, false otherwise.

```APIDOC
## queue.idle()

### Description
Returns `false` if there are tasks being processed or waiting to be processed. `true` otherwise.
```

--------------------------------

### Check if Queue is Idle with `queue.idle()`

Source: https://context7.com/mcollina/fastq/llms.txt

Returns `true` when no tasks are running or waiting. Returns `false` if any task is in-flight or in the waiting list.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  setImmediate(() => cb(null))
}, 1)

console.log(queue.idle()) // true

queue.push(42, () => {
  // Inside callback: worker finished, but drain hasn't fired yet
  console.log(queue.idle()) // false (may still have queued items)
  setImmediate(() => console.log(queue.idle())) // true
})

queue.push(43)
console.log(queue.idle()) // false

```

--------------------------------

### queue.pause()

Source: https://github.com/mcollina/fastq/blob/master/README.md

Pauses the processing of tasks in the queue. Tasks currently being worked on are not affected.

```APIDOC
## queue.pause()

### Description
Pause the processing of tasks. Currently worked tasks are not stopped.
```

--------------------------------

### queue.length()

Source: https://github.com/mcollina/fastq/blob/master/README.md

Returns the number of tasks currently waiting to be processed in the queue.

```APIDOC
## queue.length()

### Description
Returns the number of tasks waiting to be processed (in the queue).
```

--------------------------------

### Bind Context to Callback-Based Worker

Source: https://context7.com/mcollina/fastq/llms.txt

Use this pattern to provide a specific context object that will be available as `this` within the worker function. This is useful for accessing shared state or methods.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const ctx = { multiplier: 10 }

const queue = fastqueue(ctx, function worker(task, cb) {
  // `this` is ctx
  cb(null, task * this.multiplier)
}, 1)

queue.push(7, (err, result) => {
  console.log(result) // 70
})

```

--------------------------------

### TypeScript Callback Queue with Generics

Source: https://context7.com/mcollina/fastq/llms.txt

Define custom types for context, tasks, and results when using callback-based queues with TypeScript. Ensure the worker function signature matches the defined types.

```typescript
import * as fastq from 'fastq'
import type { queue, queueAsPromised, done } from 'fastq'
import { promise as queueAsPromised2 } from 'fastq'

// --- Callback queue with generics ---

interface Ctx { base: number }
type Task = { id: number; value: number }
type Result = string

const ctx: Ctx = { base: 100 }

const q: queue<Task, Result> = fastq<Ctx, Task, Result>(ctx, function worker(task, cb: done<Result>) {
  cb(null, `${this.base + task.value} (id=${task.id})`)
}, 2)

q.push({ id: 1, value: 42 }, (err, result) => {
  if (err) throw err
  console.log(result) // "142 (id=1)"
})

q.error((err, task) => {
  console.error('failed task', task.id, err.message)
})
```

--------------------------------

### queue.abort()

Source: https://context7.com/mcollina/fastq/llms.txt

Cancels all tasks currently waiting in the queue. Each waiting task will have its callback invoked (or Promise rejected) with an error indicating abortion. This method also resets the queue's drain behavior.

```APIDOC
## queue.abort()

### Description
Cancels all waiting tasks and calls each task's callback (or rejects the Promise for promise queues) with `new Error('abort')`. Also invokes the global error handler if one is set. Resets `drain` to a no-op.

### Method
`queue.abort()`

### Example
```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  setTimeout(() => cb(null, task), 1000)
}, 1)

queue.error((err, task) => {
  console.log('error handler:', err.message, 'for task', task)
})

queue.pause()
queue.push(1, (err) => console.log('task 1:', err.message))
queue.push(2, (err) => console.log('task 2:', err.message))
queue.push(3, (err) => console.log('task 3:', err.message))

queue.abort()

console.log(queue.length()) // 0
```
```

--------------------------------

### queue.error(handler)

Source: https://github.com/mcollina/fastq/blob/master/README.md

Sets a global error handler that is called when a task completes with an error.

```APIDOC
## queue.error(handler)

### Description
Set a global error handler. `handler(err, task)` will be called each time a task is completed, `err` will be not null if the task has thrown an error.

### Method
`error(handler)`

### Parameters
* **handler** (function) - The error handler function. It receives `err` and `task` as arguments.
```

--------------------------------

### Cancel all waiting tasks with an error using queue.abort()

Source: https://context7.com/mcollina/fastq/llms.txt

Use `queue.abort()` to remove all pending tasks and reject their associated Promises or callbacks with an error. This method also resets the `drain` behavior to a no-op.

```javascript
'use strict'
const fastqueue = require('fastqueue')

const queue = fastqueue(function worker(task, cb) {
  setTimeout(() => cb(null, task), 1000)
}, 1)

queue.error((err, task) => {
  console.log('error handler:', err.message, 'for task', task)
})

// Pause so tasks queue up without starting
queue.pause()
queue.push(1, (err) => console.log('task 1:', err.message)) // abort
queue.push(2, (err) => console.log('task 2:', err.message)) // abort
queue.push(3, (err) => console.log('task 3:', err.message)) // abort

queue.abort()

console.log(queue.length()) // 0
// Output:
// error handler: abort for task 1
// task 1: abort
// error handler: abort for task 2
// task 2: abort
// error handler: abort for task 3
// task 3: abort
```

--------------------------------

### queue.paused

Source: https://github.com/mcollina/fastq/blob/master/README.md

A read-only property that returns `true` if the queue is currently paused.

```APIDOC
## queue.paused

### Description
Property (Read-Only) that returns `true` when the queue is in a paused state.

### Type
Boolean
```

--------------------------------

### queue.concurrency

Source: https://github.com/mcollina/fastq/blob/master/README.md

A property that returns the number of concurrent tasks that can be executed in parallel. This can be modified at runtime.

```APIDOC
## queue.concurrency

### Description
Property that returns the number of concurrent tasks that could be executed in parallel. It can be altered at runtime.

### Type
Number
```

--------------------------------

### Type Check TypeScript Declarations

Source: https://github.com/mcollina/fastq/blob/master/CLAUDE.md

Perform type checking on the TypeScript declaration files. This helps catch type-related errors in the TypeScript definitions.

```bash
npm run typescript
```

--------------------------------

### queue.drained() => Promise

Source: https://github.com/mcollina/fastq/blob/master/README.md

Waits for the queue to be drained. The returned Promise resolves when all tasks have been processed.

```APIDOC
## queue.drained() => Promise

### Description
Wait for the queue to be drained. The returned `Promise` will be resolved when all tasks in the queue have been processed by a worker.

This promise could be ignored as it will not lead to a `'unhandledRejection'`.

### Method
`drained()`

### Returns
* `Promise` - A promise that resolves when the queue is empty.
```

--------------------------------

### queue.empty

Source: https://github.com/mcollina/fastq/blob/master/README.md

A function that is called when the last item from the queue has been assigned to a worker. This can be modified at runtime.

```APIDOC
## queue.empty

### Description
Function that will be called when the last item from the queue has been assigned to a worker. It can be altered at runtime.

### Type
Function
```

--------------------------------

### TypeScript Promise Queue with Generics

Source: https://context7.com/mcollina/fastq/llms.txt

Utilize generics with promise-based queues in TypeScript to specify the types for tasks and their results. The async worker function should return a Promise of the specified result type.

```typescript
// --- Promise queue with generics ---

const pq: queueAsPromised<number, number> = queueAsPromised2<null, number, number>(
  async function asyncWorker(n: number): Promise<number> {
    return n * n
  },
  3
)

const squared = await pq.push(9)
console.log(squared) // 81

await pq.drained()
```

--------------------------------

### queue.saturated

Source: https://github.com/mcollina/fastq/blob/master/README.md

A function that is called when the queue reaches its concurrency limit. This can be modified at runtime.

```APIDOC
## queue.saturated

### Description
Function that will be called when the queue hits the concurrency limit. It can be altered at runtime.

### Type
Function
```

--------------------------------

### queue.drain

Source: https://github.com/mcollina/fastq/blob/master/README.md

A function that is called when the last item from the queue has been processed. This can be modified at runtime.

```APIDOC
## queue.drain

### Description
Function that will be called when the last item from the queue has been processed by a worker. It can be altered at runtime.

### Type
Function
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.