0
# Array Operations
1

2
Familiar Array methods for adding, removing, and manipulating jobs in the queue. The Queue class implements most of the Array API for intuitive job management.
3

4
## Capabilities
5

6
### Add Jobs to Queue
7

8
#### Push Jobs
9

10
Adds one or more jobs to the end of the queue.
11

12
```javascript { .api }
13
/**
14
 * Adds jobs to the end of the queue
15
 * @param workers - Jobs to add to the queue
16
 * @returns New length of the queue
17
 */
18
push(...workers: QueueWorker[]): number;
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
// Add single job
25
q.push((callback) => {
26
  setTimeout(() => callback(null, 'done'), 1000);
27
});
28

29
// Add multiple jobs
30
q.push(
31
  (cb) => cb(null, 'job 1'),
32
  (cb) => cb(null, 'job 2'),
33
  () => Promise.resolve('job 3')
34
);
35

36
// With Promise-based job
37
q.push(async () => {
38
  const result = await fetch('/api/data');
39
  return result.json();
40
});
41
```
42

43
#### Unshift Jobs
44

45
Adds one or more jobs to the front of the queue (they'll execute first).
46

47
```javascript { .api }
48
/**
49
 * Adds jobs to the front of the queue
50
 * @param workers - Jobs to insert at the beginning
51
 * @returns New length of the queue
52
 */
53
unshift(...workers: QueueWorker[]): number;
54
```
55

56
**Usage Example:**
57

58
```javascript
59
// Add high-priority job to front
60
q.unshift((callback) => {
61
  console.log('High priority job');
62
  callback();
63
});
64
```
65

66
#### Splice Jobs
67

68
Adds and/or removes jobs at a specific index.
69

70
```javascript { .api }
71
/**
72
 * Changes queue contents by removing existing jobs and/or adding new jobs
73
 * @param start - Index to start changing the queue
74
 * @param deleteCount - Number of jobs to remove
75
 * @param workers - Jobs to add at the start index
76
 * @returns Queue instance for chaining
77
 */
78
splice(start: number, deleteCount?: number, ...workers: QueueWorker[]): Queue;
79
```
80

81
**Usage Examples:**
82

83
```javascript
84
// Insert job at position 2
85
q.splice(2, 0, (cb) => cb(null, 'inserted job'));
86

87
// Replace job at position 1
88
q.splice(1, 1, (cb) => cb(null, 'replacement job'));
89

90
// Remove 2 jobs starting at position 3
91
q.splice(3, 2);
92
```
93

94
### Remove Jobs from Queue
95

96
#### Pop Jobs
97

98
Removes and returns the last job from the queue.
99

100
```javascript { .api }
101
/**
102
 * Removes and returns the last job from the queue
103
 * @returns The removed job, or undefined if queue is empty
104
 */
105
pop(): QueueWorker | undefined;
106
```
107

108
**Usage Example:**
109

110
```javascript
111
const lastJob = q.pop();
112
if (lastJob) {
113
  console.log('Removed last job');
114
}
115
```
116

117
#### Shift Jobs
118

119
Removes and returns the first job from the queue.
120

121
```javascript { .api }
122
/**
123
 * Removes and returns the first job from the queue
124
 * @returns The removed job, or undefined if queue is empty
125
 */
126
shift(): QueueWorker | undefined;
127
```
128

129
**Usage Example:**
130

131
```javascript
132
const firstJob = q.shift();
133
if (firstJob) {
134
  console.log('Removed first job');
135
}
136
```
137

138
### Search and Manipulate Jobs
139

140
#### Find Job Index
141

142
Finds the index of a specific job in the queue.
143

144
```javascript { .api }
145
/**
146
 * Returns the first index of a job in the queue
147
 * @param searchElement - Job to locate
148
 * @param fromIndex - Index to start search from
149
 * @returns Index of the job, or -1 if not found
150
 */
151
indexOf(searchElement: QueueWorker, fromIndex?: number): number;
152

153
/**
154
 * Returns the last index of a job in the queue
155
 * @param searchElement - Job to locate  
156
 * @param fromIndex - Index to start search from (backwards)
157
 * @returns Index of the job, or -1 if not found
158
 */
159
lastIndexOf(searchElement: QueueWorker, fromIndex?: number): number;
160
```
161

162
**Usage Examples:**
163

164
```javascript
165
const myJob = (cb) => cb(null, 'my job');
166
q.push(myJob);
167

168
// Find the job
169
const index = q.indexOf(myJob);
170
console.log(`Job is at index ${index}`);
171

172
// Search from specific position
173
const laterIndex = q.indexOf(myJob, 5);
174
```
175

176
#### Extract Queue Section
177

178
Extracts a section of the queue and modifies the original queue.
179

180
```javascript { .api }
181
/**
182
 * Extracts a section of the queue (modifies original queue)
183
 * @param start - Beginning index of extraction
184
 * @param end - End index of extraction (exclusive)
185
 * @returns Queue instance for chaining
186
 */
187
slice(start?: number, end?: number): Queue;
188
```
189

190
**Usage Example:**
191

192
```javascript
193
// Keep only jobs 2-5
194
q.slice(2, 5);
195

196
// Keep jobs from index 3 onwards
197
q.slice(3);
198
```
199

200
#### Reverse Job Order
201

202
Reverses the order of jobs in the queue.
203

204
```javascript { .api }
205
/**
206
 * Reverses the order of jobs in the queue
207
 * @returns Queue instance for chaining
208
 */
209
reverse(): Queue;
210
```
211

212
**Usage Example:**
213

214
```javascript
215
// Reverse job execution order
216
q.reverse();
217
```
218

219
## Job Types
220

221
```javascript { .api }
222
/**
223
 * A job function that can accept a callback or return a Promise
224
 */
225
interface QueueWorker {
226
  (callback?: QueueWorkerCallback): void | Promise<any>;
227
  /** Override queue timeout for this specific job */
228
  timeout?: number;
229
  /** Promise reference if job returns a Promise */
230
  promise?: Promise<any>;
231
}
232

233
/**
234
 * Callback function for async jobs
235
 */
236
interface QueueWorkerCallback {
237
  (error?: Error, data?: Object): void;
238
}
239
```
240

241
**Job Examples:**
242

243
```javascript
244
// Callback-based job
245
function callbackJob(callback) {
246
  setTimeout(() => {
247
    callback(null, 'callback result');
248
  }, 1000);
249
}
250

251
// Promise-based job
252
function promiseJob() {
253
  return new Promise((resolve) => {
254
    setTimeout(() => resolve('promise result'), 1000);
255
  });
256
}
257

258
// Job with custom timeout
259
function slowJob(callback) {
260
  setTimeout(() => callback(null, 'slow result'), 5000);
261
}
262
slowJob.timeout = 6000; // Override queue timeout
263

264
// Mixed jobs
265
q.push(callbackJob, promiseJob, slowJob);
266
```