0
# Queue Management
1

2
Core queue functionality for creating, configuring, and controlling job execution with concurrency control and timeout management.
3

4
## Capabilities
5

6
### Queue Constructor
7

8
Creates a new Queue instance with optional configuration settings.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Queue instance
13
 * @param options - Configuration options for the queue
14
 */
15
constructor(options?: Options): Queue;
16

17
interface Options {
18
  /** Maximum number of jobs to process concurrently (default: Infinity) */
19
  concurrency?: number;
20
  /** Default timeout in milliseconds for jobs (default: 0 - no timeout) */
21
  timeout?: number;
22
  /** Automatically start processing when jobs are added (default: false) */
23
  autostart?: boolean;
24
  /** Array to collect job results (default: null) */
25
  results?: any[];
26
}
27
```
28

29
**Usage Examples:**
30

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

34
// Basic queue with unlimited concurrency
35
const basicQueue = new Queue();
36

37
// Queue with concurrency control
38
const limitedQueue = new Queue({
39
  concurrency: 3,
40
  timeout: 5000,
41
  results: []
42
});
43

44
// Auto-starting queue
45
const autoQueue = new Queue({
46
  autostart: true,
47
  concurrency: 2
48
});
49
```
50

51
### Start Processing
52

53
Explicitly starts processing jobs and provides feedback when the queue empties or an error occurs.
54

55
```javascript { .api }
56
/**
57
 * Start processing jobs in the queue
58
 * @param callback - Optional callback executed when queue empties or errors
59
 * @returns Promise resolving to results array if no callback provided
60
 */
61
start(): Promise<any[] | null>;
62
start(callback: (error?: Error, results?: any[] | null) => void): void;
63
```
64

65
**Usage Examples:**
66

67
```javascript
68
// With callback
69
q.start((err, results) => {
70
  if (err) throw err;
71
  console.log('Queue finished:', results);
72
});
73

74
// With Promise
75
try {
76
  const results = await q.start();
77
  console.log('Queue finished:', results);
78
} catch (error) {
79
  console.error('Queue failed:', error);
80
}
81
```
82

83
### Stop Processing
84

85
Stops the queue processing. Jobs can be resumed later with `start()`.
86

87
```javascript { .api }
88
/**
89
 * Stops queue processing (can be resumed)
90
 */
91
stop(): void;
92
```
93

94
**Usage Example:**
95

96
```javascript
97
// Stop processing temporarily
98
q.stop();
99

100
// Resume later
101
q.start();
102
```
103

104
### End Processing
105

106
Immediately stops and empties the queue. All pending jobs are discarded.
107

108
```javascript { .api }
109
/**
110
 * Stop and empty the queue immediately
111
 * @param error - Optional error to pass to the end event
112
 */
113
end(error?: Error): void;
114
```
115

116
**Usage Example:**
117

118
```javascript
119
// Emergency stop with error
120
q.end(new Error('Critical failure'));
121

122
// Clean shutdown
123
q.end();
124
```
125

126
### Queue Length
127

128
Gets the total number of jobs (pending execution + queued).
129

130
```javascript { .api }
131
/**
132
 * Total jobs pending execution and queued (readonly)
133
 */
134
readonly length: number;
135
```
136

137
**Usage Example:**
138

139
```javascript
140
console.log(`Queue has ${q.length} jobs total`);
141
```
142

143
### Queue Properties
144

145
Access and modify queue configuration at runtime.
146

147
```javascript { .api }
148
/**
149
 * Maximum number of jobs to process concurrently
150
 */
151
concurrency: number;
152

153
/**
154
 * Default timeout in milliseconds for jobs
155
 */
156
timeout: number;
157

158
/**
159
 * Automatically start processing when jobs are added
160
 */
161
autostart: boolean;
162

163
/**
164
 * Array to collect job results (null if disabled)
165
 */
166
results: any[] | null;
167

168
/**
169
 * Number of jobs currently being processed (readonly)
170
 */
171
readonly pending: number;
172

173
/**
174
 * Internal session counter for queue operations (readonly)
175
 */
176
readonly session: number;
177

178
/**
179
 * Whether the queue is currently running (readonly)
180
 */
181
readonly running: boolean;
182

183
/**
184
 * Internal array of queued jobs waiting to be processed (readonly)
185
 */
186
readonly jobs: QueueWorker[];
187

188
/**
189
 * Array of active timeout IDs for job timeouts (readonly)
190
 */
191
readonly timers: number[];
192
```
193

194
**Usage Examples:**
195

196
```javascript
197
// Adjust concurrency at runtime
198
q.concurrency = 5;
199

200
// Change default timeout
201
q.timeout = 10000;
202

203
// Enable result collection
204
q.results = [];
205

206
// Enable auto-start mode
207
q.autostart = true;
208

209
// Check queue status (readonly properties)
210
console.log(`Pending jobs: ${q.pending}`);
211
console.log(`Queue running: ${q.running}`);
212
console.log(`Jobs in queue: ${q.jobs.length}`);
213
console.log(`Active timeouts: ${q.timers.length}`);
214
```
215

216
### Clear Timers
217

218
Clears all active timeout timers for pending jobs.
219

220
```javascript { .api }
221
/**
222
 * Clear all active timeout timers
223
 */
224
clearTimers(): void;
225
```
226

227
**Usage Example:**
228

229
```javascript
230
// Cancel all timeouts but keep jobs running
231
q.clearTimers();
232
```