refactor: cleanup variables namespace
[poolifier.git] / src / pools / pool.ts
CommitLineData
9e45c2c4 1import EventEmitterAsyncResource from 'node:events'
bdaf31cd
JB
2import type {
3 ErrorHandler,
4 ExitHandler,
50e66724 5 IWorker,
bdaf31cd 6 MessageHandler,
c4855468
JB
7 OnlineHandler,
8 WorkerNode
f06e48d8 9} from './worker'
da309861
JB
10import type {
11 WorkerChoiceStrategy,
12 WorkerChoiceStrategyOptions
13} from './selection-strategies/selection-strategies-types'
bdaf31cd 14
c4855468 15/**
6b27d407 16 * Enumeration of pool types.
c4855468 17 */
6b27d407 18export const PoolTypes = Object.freeze({
c4855468
JB
19 /**
20 * Fixed pool type.
21 */
6b27d407 22 fixed: 'fixed',
c4855468
JB
23 /**
24 * Dynamic pool type.
25 */
6b27d407
JB
26 dynamic: 'dynamic'
27} as const)
28
29/**
30 * Pool type.
31 */
32export type PoolType = keyof typeof PoolTypes
c4855468 33
184855e6
JB
34/**
35 * Enumeration of worker types.
36 */
37export const WorkerTypes = Object.freeze({
38 cluster: 'cluster',
39 thread: 'thread'
40} as const)
41
42/**
43 * Worker type.
44 */
45export type WorkerType = keyof typeof WorkerTypes
46
b4904890
JB
47/**
48 * Pool events emitter.
49 */
9e45c2c4 50export class PoolEmitter extends EventEmitterAsyncResource {}
b4904890 51
aee46736
JB
52/**
53 * Enumeration of pool events.
54 */
55export const PoolEvents = Object.freeze({
56 full: 'full',
1f68cede 57 busy: 'busy',
91ee39ed
JB
58 error: 'error',
59 taskError: 'taskError'
aee46736
JB
60} as const)
61
62/**
63 * Pool event.
64 */
65export type PoolEvent = keyof typeof PoolEvents
66
6b27d407
JB
67/**
68 * Pool information.
69 */
70export interface PoolInfo {
71 type: PoolType
184855e6 72 worker: WorkerType
6b27d407
JB
73 minSize: number
74 maxSize: number
75 workerNodes: number
76 idleWorkerNodes: number
77 busyWorkerNodes: number
a4e07f72
JB
78 executedTasks: number
79 executingTasks: number
6b27d407
JB
80 queuedTasks: number
81 maxQueuedTasks: number
a4e07f72 82 failedTasks: number
6b27d407
JB
83}
84
7171d33f
JB
85/**
86 * Worker tasks queue options.
87 */
88export interface TasksQueueOptions {
89 /**
90 * Maximum number of tasks that can be executed concurrently on a worker.
91 *
92 * @defaultValue 1
93 */
94 concurrency?: number
95}
96
bdaf31cd
JB
97/**
98 * Options for a poolifier pool.
c319c66b 99 *
d480d708 100 * @typeParam Worker - Type of worker.
bdaf31cd 101 */
50e66724 102export interface PoolOptions<Worker extends IWorker> {
bdaf31cd
JB
103 /**
104 * A function that will listen for message event on each worker.
105 */
106 messageHandler?: MessageHandler<Worker>
107 /**
108 * A function that will listen for error event on each worker.
109 */
110 errorHandler?: ErrorHandler<Worker>
111 /**
112 * A function that will listen for online event on each worker.
113 */
114 onlineHandler?: OnlineHandler<Worker>
115 /**
116 * A function that will listen for exit event on each worker.
117 */
118 exitHandler?: ExitHandler<Worker>
119 /**
46e857ca 120 * The worker choice strategy to use in this pool.
d29bce7c 121 *
95ec6006 122 * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
bdaf31cd
JB
123 */
124 workerChoiceStrategy?: WorkerChoiceStrategy
da309861
JB
125 /**
126 * The worker choice strategy options.
127 */
128 workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
1f68cede
JB
129 /**
130 * Restart worker on error.
131 */
132 restartWorkerOnError?: boolean
bdaf31cd
JB
133 /**
134 * Pool events emission.
135 *
38e795c1 136 * @defaultValue true
bdaf31cd
JB
137 */
138 enableEvents?: boolean
ff733df7
JB
139 /**
140 * Pool worker tasks queue.
141 *
ff733df7
JB
142 * @defaultValue false
143 */
144 enableTasksQueue?: boolean
7171d33f
JB
145 /**
146 * Pool worker tasks queue options.
7171d33f
JB
147 */
148 tasksQueueOptions?: TasksQueueOptions
bdaf31cd 149}
a35560ba 150
729c563d
S
151/**
152 * Contract definition for a poolifier pool.
153 *
c4855468 154 * @typeParam Worker - Type of worker which manages this pool.
38e795c1 155 * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
02706357 156 * @typeParam Response - Type of execution response. This can only be serializable data.
729c563d 157 */
c4855468
JB
158export interface IPool<
159 Worker extends IWorker,
160 Data = unknown,
161 Response = unknown
162> {
08f3f44c 163 /**
6b27d407 164 * Pool information.
08f3f44c 165 */
6b27d407 166 readonly info: PoolInfo
c4855468
JB
167 /**
168 * Pool worker nodes.
169 */
170 readonly workerNodes: Array<WorkerNode<Worker, Data>>
b4904890
JB
171 /**
172 * Emitter on which events can be listened to.
173 *
174 * Events that can currently be listened to:
175 *
164d950a
JB
176 * - `'full'`: Emitted when the pool is dynamic and full.
177 * - `'busy'`: Emitted when the pool is busy.
91ee39ed
JB
178 * - `'error'`: Emitted when an uncaught error occurs.
179 * - `'taskError'`: Emitted when an error occurs while executing a task.
b4904890
JB
180 */
181 readonly emitter?: PoolEmitter
729c563d 182 /**
61aa11a6 183 * Executes the specified function in the worker constructor with the task data input parameter.
729c563d 184 *
ef41a6e6 185 * @param data - The task input data for the specified worker function. This can only be serializable data.
a86b6df1 186 * @param name - The name of the worker function to execute. If not specified, the default worker function will be executed.
ef41a6e6 187 * @returns Promise that will be fulfilled when the task is completed.
729c563d 188 */
a86b6df1 189 execute: (data?: Data, name?: string) => Promise<Response>
280c2a77 190 /**
6c6afb84 191 * Terminate every current worker in this pool.
280c2a77 192 */
78cea37e 193 destroy: () => Promise<void>
a35560ba 194 /**
bdede008 195 * Sets the worker choice strategy in this pool.
a35560ba 196 *
38e795c1 197 * @param workerChoiceStrategy - The worker choice strategy.
59219cbb 198 * @param workerChoiceStrategyOptions - The worker choice strategy options.
a35560ba 199 */
59219cbb
JB
200 setWorkerChoiceStrategy: (
201 workerChoiceStrategy: WorkerChoiceStrategy,
202 workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
203 ) => void
a20f0ba5
JB
204 /**
205 * Sets the worker choice strategy options in this pool.
206 *
207 * @param workerChoiceStrategyOptions - The worker choice strategy options.
208 */
209 setWorkerChoiceStrategyOptions: (
210 workerChoiceStrategyOptions: WorkerChoiceStrategyOptions
211 ) => void
212 /**
213 * Enables/disables the worker tasks queue in this pool.
214 *
215 * @param enable - Whether to enable or disable the worker tasks queue.
216 * @param tasksQueueOptions - The worker tasks queue options.
217 */
8f52842f
JB
218 enableTasksQueue: (
219 enable: boolean,
220 tasksQueueOptions?: TasksQueueOptions
221 ) => void
a20f0ba5
JB
222 /**
223 * Sets the worker tasks queue options in this pool.
224 *
225 * @param tasksQueueOptions - The worker tasks queue options.
226 */
227 setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void
c97c7edb 228}