0
# Core Pool Management
1

2
Primary promise pool functionality for creating, configuring, and executing concurrent tasks with full type safety and flexible configuration options.
3

4
## Capabilities
5

6
### PromisePool Class
7

8
Main class for creating and managing promise pools with fluent interface pattern.
9

10
```typescript { .api }
11
/**
12
 * Main promise pool class with fluent interface for concurrent task processing
13
 */
14
class PromisePool<T, ShouldUseCorrespondingResults extends boolean = false> {
15
  constructor(items?: SomeIterable<T>);
16
  
17
  // Static factory methods
18
  static withConcurrency(concurrency: number): PromisePool<unknown>;
19
  static withTaskTimeout(timeout: number): PromisePool<unknown>;
20
  static for<T>(items: SomeIterable<T>): PromisePool<T>;
21
  
22
  // Instance configuration methods
23
  withConcurrency(concurrency: number): PromisePool<T>;
24
  withTaskTimeout(timeout: number): PromisePool<T>;
25
  for<ItemType>(items: SomeIterable<ItemType>): PromisePool<ItemType>;
26
  useCorrespondingResults(): PromisePool<T, true>;
27
  
28
  // Execution method
29
  process<ResultType, ErrorType = any>(
30
    callback: ProcessHandler<T, ResultType>
31
  ): Promise<ReturnValue<T, ShouldUseCorrespondingResults extends true ? ResultType | symbol : ResultType, ErrorType>>;
32
  
33
  // Static symbols for corresponding results
34
  static readonly notRun: symbol;
35
  static readonly failed: symbol;
36
}
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import { PromisePool } from "@supercharge/promise-pool";
43

44
// Basic usage with default concurrency (10)
45
const { results } = await PromisePool
46
  .for([1, 2, 3, 4, 5])
47
  .process(async (num) => num * 2);
48

49
// Custom concurrency
50
const { results } = await PromisePool
51
  .withConcurrency(3)
52
  .for(urls)
53
  .process(async (url) => fetch(url));
54

55
// With task timeout
56
const { results } = await PromisePool
57
  .for(tasks)
58
  .withTaskTimeout(5000) // 5 seconds per task
59
  .process(async (task) => processTask(task));
60
```
61

62
### Concurrency Configuration
63

64
Configure the number of tasks that run concurrently.
65

66
```typescript { .api }
67
/**
68
 * Set the number of tasks to process concurrently
69
 * @param concurrency - Number of concurrent tasks (must be >= 1)
70
 * @returns PromisePool instance for chaining
71
 */
72
withConcurrency(concurrency: number): PromisePool<T>;
73

74
/**
75
 * Static method to create pool with specified concurrency
76
 * @param concurrency - Number of concurrent tasks
77
 * @returns New PromisePool instance
78
 */
79
static withConcurrency(concurrency: number): PromisePool<unknown>;
80
```
81

82
### Task Timeout Configuration
83

84
Configure timeout for individual tasks.
85

86
```typescript { .api }
87
/**
88
 * Set the timeout in milliseconds for each task
89
 * @param timeout - Timeout in milliseconds (per task, not total)
90
 * @returns PromisePool instance for chaining
91
 */
92
withTaskTimeout(timeout: number): PromisePool<T>;
93

94
/**
95
 * Static method to create pool with task timeout
96
 * @param timeout - Timeout in milliseconds
97
 * @returns New PromisePool instance
98
 */
99
static withTaskTimeout(timeout: number): PromisePool<unknown>;
100
```
101

102
**Usage Example:**
103

104
```typescript
105
// Each task must complete within 2 seconds
106
const { results } = await PromisePool
107
  .for(items)
108
  .withTaskTimeout(2000)
109
  .process(async (item) => {
110
    // This task will timeout if it takes longer than 2 seconds
111
    return await processItem(item);
112
  });
113
```
114

115
### Items Configuration
116

117
Set the items to be processed by the pool.
118

119
```typescript { .api }
120
/**
121
 * Set the items to be processed in the promise pool
122
 * @param items - Array, Iterable, or AsyncIterable of items
123
 * @returns New PromisePool instance with specified items
124
 */
125
for<ItemType>(items: SomeIterable<ItemType>): PromisePool<ItemType>;
126

127
/**
128
 * Static method to create pool for specified items
129
 * @param items - Items to process
130
 * @returns New PromisePool instance
131
 */
132
static for<T>(items: SomeIterable<T>): PromisePool<T>;
133

134
type SomeIterable<T> = T[] | Iterable<T> | AsyncIterable<T>;
135
```
136

137
**Usage Examples:**
138

139
```typescript
140
// With arrays
141
await PromisePool.for([1, 2, 3]).process(async (num) => num * 2);
142

143
// With generators/iterables
144
function* numberGenerator() {
145
  for (let i = 0; i < 10; i++) yield i;
146
}
147
await PromisePool.for(numberGenerator()).process(async (num) => num * 2);
148

149
// With async iterables
150
async function* asyncGenerator() {
151
  for (let i = 0; i < 5; i++) {
152
    await new Promise(resolve => setTimeout(resolve, 100));
153
    yield i;
154
  }
155
}
156
await PromisePool.for(asyncGenerator()).process(async (num) => num * 2);
157
```
158

159
### Corresponding Results
160

161
Enable result-source correspondence to maintain order between input items and results.
162

163
```typescript { .api }
164
/**
165
 * Configure results to correspond with source items by position
166
 * @returns PromisePool with corresponding results enabled
167
 */
168
useCorrespondingResults(): PromisePool<T, true>;
169
```
170

171
When using corresponding results, the results array will contain:
172
- The actual result value for successful tasks
173
- `PromisePool.notRun` symbol for tasks that didn't execute
174
- `PromisePool.failed` symbol for tasks that failed
175

176
**Usage Example:**
177

178
```typescript
179
const { results } = await PromisePool
180
  .for([1, 2, 3])
181
  .withConcurrency(2)
182
  .useCorrespondingResults()
183
  .process(async (num, index) => {
184
    if (num === 2) throw new Error("Skip 2");
185
    return num * 10;
186
  });
187

188
// Results array will be: [10, Symbol(failed), 30]
189
// Corresponding to input: [1, 2, 3]
190

191
// Filter for successful results only
192
const successfulResults = results.filter(result => 
193
  result !== PromisePool.failed && result !== PromisePool.notRun
194
);
195
```
196

197
### Process Execution
198

199
Execute the promise pool with a processing function.
200

201
```typescript { .api }
202
/**
203
 * Process all items through the provided callback function
204
 * @param callback - Function to process each item
205
 * @returns Promise resolving to results and errors
206
 */
207
process<ResultType, ErrorType = any>(
208
  callback: ProcessHandler<T, ResultType>
209
): Promise<ReturnValue<T, ShouldUseCorrespondingResults extends true ? ResultType | symbol : ResultType, ErrorType>>;
210

211
type ProcessHandler<T, R> = (
212
  item: T, 
213
  index: number, 
214
  pool: Stoppable & UsesConcurrency
215
) => Promise<R> | R;
216

217
interface ReturnValue<T, R, E = any> {
218
  results: R[];
219
  errors: Array<PromisePoolError<T, E>>;
220
}
221
```
222

223
The processing callback receives:
224
- `item`: The current item being processed
225
- `index`: The index of the item in the source array/iterable
226
- `pool`: Pool instance with control methods (`stop()`, `isStopped()`, etc.)
227

228
**Usage Examples:**
229

230
```typescript
231
// Basic processing
232
const { results, errors } = await PromisePool
233
  .for(users)
234
  .process(async (user, index, pool) => {
235
    // Access to current item, index, and pool control
236
    if (user.invalid) {
237
      pool.stop(); // Stop processing remaining items
238
      return null;
239
    }
240
    return await processUser(user);
241
  });
242

243
// Handle errors separately
244
if (errors.length > 0) {
245
  console.log("Errors occurred:", errors);
246
  errors.forEach(error => {
247
    console.log(`Error processing item ${error.item}:`, error.message);
248
  });
249
}
250
```