0
# Promise Pool
1

2
Promise Pool provides map-like, concurrent promise processing for Node.js with configurable concurrency limits, error handling, and advanced features. It enables controlled parallel execution of asynchronous operations while maintaining fine-grained control over execution flow, error handling, and result ordering.
3

4
## Package Information
5

6
- **Package Name**: @supercharge/promise-pool
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @supercharge/promise-pool`
10

11
## Core Imports
12

13
```typescript
14
import { PromisePool } from "@supercharge/promise-pool";
15
```
16

17
Default import:
18

19
```typescript
20
import PromisePool from "@supercharge/promise-pool";
21
```
22

23
CommonJS:
24

25
```javascript
26
const { PromisePool } = require("@supercharge/promise-pool");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { PromisePool } from "@supercharge/promise-pool";
33

34
const users = [
35
  { name: "Marcus" },
36
  { name: "Norman" },
37
  { name: "Christian" }
38
];
39

40
const { results, errors } = await PromisePool
41
  .withConcurrency(2)
42
  .for(users)
43
  .process(async (userData, index, pool) => {
44
    const user = await User.createIfNotExisting(userData);
45
    return user;
46
  });
47
```
48

49
## Architecture
50

51
Promise Pool is built around several key components:
52

53
- **Fluent Interface**: `PromisePool` class providing chainable method calls for configuration
54
- **Executor Engine**: `PromisePoolExecutor` handles the internal processing logic
55
- **Error Handling**: Custom error classes and configurable error handling strategies
56
- **Progress Tracking**: Real-time statistics and callback system for monitoring task execution
57
- **Result Management**: Options for maintaining correspondence between source items and results
58
- **Concurrency Control**: Configurable limits with dynamic adjustment capabilities
59

60
## Capabilities
61

62
### Core Pool Management
63

64
Primary promise pool functionality for creating, configuring, and executing concurrent tasks with full type safety.
65

66
```typescript { .api }
67
class PromisePool<T, ShouldUseCorrespondingResults extends boolean = false> {
68
  constructor(items?: SomeIterable<T>);
69
  static withConcurrency(concurrency: number): PromisePool<unknown>;
70
  static withTaskTimeout(timeout: number): PromisePool<unknown>;
71
  static for<T>(items: SomeIterable<T>): PromisePool<T>;
72
  
73
  withConcurrency(concurrency: number): PromisePool<T>;
74
  withTaskTimeout(timeout: number): PromisePool<T>;
75
  for<ItemType>(items: SomeIterable<ItemType>): PromisePool<ItemType>;
76
  useCorrespondingResults(): PromisePool<T, true>;
77
  
78
  process<ResultType, ErrorType = any>(
79
    callback: ProcessHandler<T, ResultType>
80
  ): Promise<ReturnValue<T, ShouldUseCorrespondingResults extends true ? ResultType | symbol : ResultType, ErrorType>>;
81
}
82
```
83

84
[Core Pool Management](./core-pool-management.md)
85

86
### Error Handling
87

88
Comprehensive error handling system with custom error handlers, error wrapping, and selective error processing.
89

90
```typescript { .api }
91
handleError(handler: ErrorHandler<T>): PromisePool<T>;
92

93
type ErrorHandler<T> = (
94
  error: Error, 
95
  item: T, 
96
  pool: Stoppable & UsesConcurrency
97
) => Promise<void> | void;
98

99
class PromisePoolError<T, E = any> extends Error {
100
  item: T;
101
  raw: E;
102
  constructor(error: E, item: T);
103
  static createFrom<T, E = any>(error: E, item: T): PromisePoolError<T>;
104
}
105
```
106

107
[Error Handling](./error-handling.md)
108

109
### Progress Tracking
110

111
Real-time progress monitoring with task lifecycle callbacks and comprehensive statistics.
112

113
```typescript { .api }
114
onTaskStarted(handler: OnProgressCallback<T>): PromisePool<T>;
115
onTaskFinished(handler: OnProgressCallback<T>): PromisePool<T>;
116

117
type OnProgressCallback<T> = (
118
  item: T, 
119
  pool: Stoppable & Statistics<T> & UsesConcurrency
120
) => void;
121

122
interface Statistics<T> {
123
  activeTasksCount(): number;
124
  activeTaskCount(): number; // deprecated - use activeTasksCount
125
  processedItems(): T[];
126
  processedCount(): number;
127
  processedPercentage(): number;
128
}
129
```
130

131
[Progress Tracking](./progress-tracking.md)
132

133
### Pool Control
134

135
Manual pool control capabilities including stopping execution and checking pool state.
136

137
```typescript { .api }
138
interface Stoppable {
139
  stop(): void;
140
  isStopped(): boolean;
141
}
142

143
interface UsesConcurrency {
144
  useConcurrency(concurrency: number): this;
145
  concurrency(): number;
146
}
147
```
148

149
[Pool Control](./pool-control.md)
150

151
## Types
152

153
```typescript { .api }
154
type SomeIterable<T> = T[] | Iterable<T> | AsyncIterable<T>;
155

156
type ProcessHandler<T, R> = (
157
  item: T, 
158
  index: number, 
159
  pool: Stoppable & UsesConcurrency
160
) => Promise<R> | R;
161

162
interface ReturnValue<T, R, E = any> {
163
  results: R[];
164
  errors: Array<PromisePoolError<T, E>>;
165
}
166

167
// Special symbols for corresponding results
168
static readonly notRun: symbol;
169
static readonly failed: symbol;
170
```