0
# Queue
1

2
Queue is a powerful asynchronous function queue implementation with adjustable concurrency control. It provides an Array-like API for managing jobs, supports both callback-based and Promise-based async functions, and includes comprehensive event handling with timeout support.
3

4
## Package Information
5

6
- **Package Name**: queue
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Module with TypeScript definitions)
9
- **Installation**: `npm install queue`
10

11
## Core Imports
12

13
```javascript
14
import Queue from "queue";
15
```
16

17
For named imports (ES modules):
18

19
```javascript
20
import Queue, { QueueEvent } from "queue";
21
```
22

23
For CommonJS (requires Node.js module compatibility):
24

25
```javascript
26
const Queue = require("queue").default;
27
const { QueueEvent } = require("queue");
28
```
29

30
## Basic Usage
31

32
```javascript
33
import Queue from "queue";
34

35
// Create queue with concurrency control
36
const q = new Queue({ 
37
  concurrency: 2,
38
  timeout: 5000,
39
  results: []
40
});
41

42
// Add jobs using Array-like methods
43
q.push((callback) => {
44
  setTimeout(() => {
45
    callback(null, "job 1 complete");
46
  }, 1000);
47
});
48

49
q.push(() => {
50
  return new Promise((resolve) => {
51
    setTimeout(() => resolve("job 2 complete"), 500);
52
  });
53
});
54

55
// Listen for events
56
q.addEventListener('success', (event) => {
57
  console.log('Job completed:', event.detail.result);
58
});
59

60
// Start processing
61
q.start((err, results) => {
62
  if (err) throw err;
63
  console.log('All jobs complete:', results);
64
});
65
```
66

67
## Architecture
68

69
Queue is built around several key components:
70

71
- **Queue Class**: Main queue implementation extending EventTarget for event handling
72
- **Array-like API**: Familiar methods (push, pop, shift, etc.) for job manipulation
73
- **Concurrency Control**: Configurable maximum concurrent job execution
74
- **Event System**: Comprehensive event emission for monitoring job lifecycle
75
- **Timeout Management**: Global and per-job timeout handling with cleanup
76
- **Result Collection**: Optional array for collecting job return values
77

78
## Capabilities
79

80
### Queue Management
81

82
Core queue functionality for creating, configuring, and controlling job execution. Handles both callback-based and Promise-based async functions.
83

84
```javascript { .api }
85
class Queue extends EventTarget {
86
  constructor(options?: Options);
87
  start(): Promise<any[] | null>;
88
  start(callback: (error?: Error, results?: any[] | null) => void): void;
89
  stop(): void;
90
  end(error?: Error): void;
91
  clearTimers(): void;
92
  readonly length: number;
93
  readonly pending: number;
94
  readonly session: number;
95
  readonly running: boolean;
96
  readonly jobs: QueueWorker[];
97
  readonly timers: number[];
98
}
99

100
interface Options {
101
  concurrency?: number;    // Default: Infinity
102
  timeout?: number;        // Default: 0 (no timeout)
103
  autostart?: boolean;     // Default: false
104
  results?: any[];         // Default: null
105
}
106
```
107

108
[Queue Management](./queue-management.md)
109

110
### Array-like Operations
111

112
Familiar Array methods for adding, removing, and manipulating jobs in the queue. All methods support the same signatures as native Array methods.
113

114
```javascript { .api }
115
// Job addition methods
116
push(...workers: QueueWorker[]): number;
117
unshift(...workers: QueueWorker[]): number;
118
splice(start: number, deleteCount?: number, ...workers: QueueWorker[]): Queue;
119

120
// Job removal methods  
121
pop(): QueueWorker | undefined;
122
shift(): QueueWorker | undefined;
123

124
// Job manipulation methods
125
slice(start?: number, end?: number): Queue;
126
reverse(): Queue;
127
indexOf(searchElement: QueueWorker, fromIndex?: number): number;
128
lastIndexOf(searchElement: QueueWorker, fromIndex?: number): number;
129
```
130

131
[Array Operations](./array-operations.md)
132

133
### Event System
134

135
Comprehensive event system for monitoring job lifecycle, handling errors, and responding to timeouts. Uses custom QueueEvent class with detailed event data.
136

137
```javascript { .api }
138
class QueueEvent extends Event {
139
  constructor(name: string, detail: any);
140
  readonly detail: any;
141
}
142

143
// Event types and their detail structures
144
interface EventsMap {
145
  start: { job?: QueueWorker };
146
  success: { result: any[] };
147
  error: { error: Error, job: QueueWorker };
148
  timeout: { next: (err?: Error, ...result: any[]) => void, job: QueueWorker };
149
  end: { error?: Error };
150
}
151
```
152

153
[Event System](./event-system.md)
154

155
## Types
156

157
```javascript { .api }
158
interface QueueWorker {
159
  (callback?: QueueWorkerCallback): void | Promise<any>;
160
  timeout?: number;     // Override queue timeout for this job
161
  promise?: Promise<any>; // Promise reference if job returns one
162
}
163

164
interface QueueWorkerCallback {
165
  (error?: Error, data?: Object): void;
166
}
167
```