0
# workerpool
1

2
workerpool offers an easy way to create a pool of workers for both dynamically offloading computations as well as managing a pool of dedicated workers. It implements a thread pool pattern with a natural, promise-based proxy interface, making workers accessible as if they are available directly in the main application.
3

4
workerpool runs on Node.js and in the browser, automatically selecting the appropriate worker type (Web Workers, child processes, or worker threads) based on the environment.
5

6
## Package Information
7

8
- **Package Name**: workerpool
9
- **Package Type**: npm
10
- **Language**: JavaScript
11
- **Installation**: `npm install workerpool`
12

13
## Core Imports
14

15
```javascript
16
const workerpool = require('workerpool');
17
```
18

19
For ES modules:
20

21
```javascript
22
import workerpool from 'workerpool';
23
// or
24
import { pool, worker, workerEmit } from 'workerpool';
25
```
26

27
## Basic Usage
28

29
```javascript
30
const workerpool = require('workerpool');
31

32
// Create a worker pool
33
const pool = workerpool.pool();
34

35
// Offload a function dynamically
36
function fibonacci(n) {
37
  if (n < 2) return n;
38
  return fibonacci(n - 2) + fibonacci(n - 1);
39
}
40

41
pool
42
  .exec(fibonacci, [10])
43
  .then(function (result) {
44
    console.log('Result:', result); // 55
45
  })
46
  .catch(function (err) {
47
    console.error(err);
48
  })
49
  .then(function () {
50
    pool.terminate(); // terminate all workers when done
51
  });
52
```
53

54
ES modules example:
55

56
```javascript
57
import workerpool from 'workerpool';
58

59
// Create a worker pool
60
const pool = workerpool.pool();
61

62
// Offload a function dynamically with async/await
63
const fibonacci = (n) => {
64
  if (n < 2) return n;
65
  return fibonacci(n - 2) + fibonacci(n - 1);
66
};
67

68
try {
69
  const result = await pool.exec(fibonacci, [10]);
70
  console.log('Result:', result); // 55
71
} catch (err) {
72
  console.error(err);
73
} finally {
74
  await pool.terminate(); // terminate all workers when done
75
}
76
```
77

78
## Architecture
79

80
workerpool is built around several key components:
81

82
- **Pool Management**: The `Pool` class manages a pool of workers, handling task queuing, worker allocation, and lifecycle management
83
- **Worker Context**: The `worker` module provides utilities for registering functions and handling communication within worker processes
84
- **Promise System**: Custom Promise implementation with cancellation, timeout, and cleanup capabilities
85
- **Environment Detection**: Automatic worker type selection based on platform capabilities (Web Workers, child processes, worker threads)
86
- **Transfer Objects**: Support for transferable objects to efficiently move data between workers
87

88
## Capabilities
89

90
### Worker Pool Management
91

92
Core functionality for creating and managing pools of workers. Handles dynamic function offloading, dedicated worker scripts, and worker lifecycle management.
93

94
```javascript { .api }
95
function pool(script, options) -> Pool
96
function pool(options) -> Pool
97

98
interface Pool {
99
  exec(method, params, options) -> Promise
100
  proxy() -> Promise<ProxyObject>
101
  terminate(force, timeout) -> Promise<void>
102
  stats() -> PoolStats
103
}
104
```
105

106
[Worker Pool Management](./pool-management.md)
107

108
### Worker Registration and Context
109

110
Utilities for setting up worker processes, registering functions, and handling communication between main thread and workers.
111

112
```javascript { .api }
113
function worker(methods, options) -> void
114
function workerEmit(payload) -> void
115

116
// Available within worker context
117
interface WorkerAPI {
118
  addAbortListener(listener) -> void
119
  emit(payload) -> void
120
}
121
```
122

123
[Worker Context](./worker-context.md)
124

125
### Promise and Transfer Utilities
126

127
Enhanced Promise implementation with cancellation and timeout support, plus utilities for transferring objects between workers.
128

129
```javascript { .api }
130
class Promise {
131
  constructor(handler, parent)
132
  then(onSuccess, onFail) -> Promise
133
  catch(onFail) -> Promise
134
  cancel() -> Promise
135
  timeout(delay) -> Promise
136
  always(fn) -> Promise
137
  finally(fn) -> Promise
138
}
139

140
class Transfer {
141
  constructor(message, transfer)
142
}
143
```
144

145
[Promise and Transfer Utilities](./promise-transfer.md)
146

147
## Environment Information
148

149
```javascript { .api }
150
const platform: 'node' | 'browser'
151
const isMainThread: boolean
152
const cpus: number
153
```
154

155
These constants provide information about the current execution environment and are useful for conditional logic based on platform capabilities.
156

157
## Types
158

159
```javascript { .api }
160
interface WorkerPoolOptions {
161
  minWorkers?: number | 'max'
162
  maxWorkers?: number
163
  maxQueueSize?: number
164
  workerType?: 'auto' | 'web' | 'process' | 'thread'
165
  workerTerminateTimeout?: number
166
  forkArgs?: string[]
167
  forkOpts?: object
168
  workerOpts?: object
169
  workerThreadOpts?: object
170
  emitStdStreams?: boolean
171
  onCreateWorker?: (args: WorkerArg) => WorkerArg | undefined
172
  onTerminateWorker?: (args: WorkerArg) => void
173
}
174

175
interface ExecOptions {
176
  on?: (payload: any) => unknown
177
  transfer?: object[]
178
}
179

180
interface WorkerRegisterOptions {
181
  onTerminate?: (code: number | undefined) => PromiseLike<void> | void
182
  abortListenerTimeout?: number
183
}
184

185
interface PoolStats {
186
  totalWorkers: number
187
  busyWorkers: number
188
  idleWorkers: number
189
  pendingTasks: number
190
  activeTasks: number
191
}
192

193
interface WorkerArg {
194
  forkArgs?: string[]
195
  forkOpts?: object
196
  workerOpts?: object
197
  workerThreadOpts?: object
198
  script?: string
199
}
200
```