refactor: cleanup variables namespace
[poolifier.git] / src / pools / pool.ts
1 import EventEmitterAsyncResource from 'node:events'
2 import type {
3 ErrorHandler,
4 ExitHandler,
5 IWorker,
6 MessageHandler,
7 OnlineHandler,
8 WorkerNode
9 } from './worker'
10 import type {
11 WorkerChoiceStrategy,
12 WorkerChoiceStrategyOptions
13 } from './selection-strategies/selection-strategies-types'
14
15 /**
16 * Enumeration of pool types.
17 */
18 export const PoolTypes = Object.freeze({
19 /**
20 * Fixed pool type.
21 */
22 fixed: 'fixed',
23 /**
24 * Dynamic pool type.
25 */
26 dynamic: 'dynamic'
27 } as const)
28
29 /**
30 * Pool type.
31 */
32 export type PoolType = keyof typeof PoolTypes
33
34 /**
35 * Enumeration of worker types.
36 */
37 export const WorkerTypes = Object.freeze({
38 cluster: 'cluster',
39 thread: 'thread'
40 } as const)
41
42 /**
43 * Worker type.
44 */
45 export type WorkerType = keyof typeof WorkerTypes
46
47 /**
48 * Pool events emitter.
49 */
50 export class PoolEmitter extends EventEmitterAsyncResource {}
51
52 /**
53 * Enumeration of pool events.
54 */
55 export const PoolEvents = Object.freeze({
56 full: 'full',
57 busy: 'busy',
58 error: 'error',
59 taskError: 'taskError'
60 } as const)
61
62 /**
63 * Pool event.
64 */
65 export type PoolEvent = keyof typeof PoolEvents
66
67 /**
68 * Pool information.
69 */
70 export interface PoolInfo {
71 type: PoolType
72 worker: WorkerType
73 minSize: number
74 maxSize: number
75 workerNodes: number
76 idleWorkerNodes: number
77 busyWorkerNodes: number
78 executedTasks: number
79 executingTasks: number
80 queuedTasks: number
81 maxQueuedTasks: number
82 failedTasks: number
83 }
84
85 /**
86 * Worker tasks queue options.
87 */
88 export 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
97 /**
98 * Options for a poolifier pool.
99 *
100 * @typeParam Worker - Type of worker.
101 */
102 export interface PoolOptions<Worker extends IWorker> {
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 /**
120 * The worker choice strategy to use in this pool.
121 *
122 * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
123 */
124 workerChoiceStrategy?: WorkerChoiceStrategy
125 /**
126 * The worker choice strategy options.
127 */
128 workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
129 /**
130 * Restart worker on error.
131 */
132 restartWorkerOnError?: boolean
133 /**
134 * Pool events emission.
135 *
136 * @defaultValue true
137 */
138 enableEvents?: boolean
139 /**
140 * Pool worker tasks queue.
141 *
142 * @defaultValue false
143 */
144 enableTasksQueue?: boolean
145 /**
146 * Pool worker tasks queue options.
147 */
148 tasksQueueOptions?: TasksQueueOptions
149 }
150
151 /**
152 * Contract definition for a poolifier pool.
153 *
154 * @typeParam Worker - Type of worker which manages this pool.
155 * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
156 * @typeParam Response - Type of execution response. This can only be serializable data.
157 */
158 export interface IPool<
159 Worker extends IWorker,
160 Data = unknown,
161 Response = unknown
162 > {
163 /**
164 * Pool information.
165 */
166 readonly info: PoolInfo
167 /**
168 * Pool worker nodes.
169 */
170 readonly workerNodes: Array<WorkerNode<Worker, Data>>
171 /**
172 * Emitter on which events can be listened to.
173 *
174 * Events that can currently be listened to:
175 *
176 * - `'full'`: Emitted when the pool is dynamic and full.
177 * - `'busy'`: Emitted when the pool is busy.
178 * - `'error'`: Emitted when an uncaught error occurs.
179 * - `'taskError'`: Emitted when an error occurs while executing a task.
180 */
181 readonly emitter?: PoolEmitter
182 /**
183 * Executes the specified function in the worker constructor with the task data input parameter.
184 *
185 * @param data - The task input data for the specified worker function. This can only be serializable data.
186 * @param name - The name of the worker function to execute. If not specified, the default worker function will be executed.
187 * @returns Promise that will be fulfilled when the task is completed.
188 */
189 execute: (data?: Data, name?: string) => Promise<Response>
190 /**
191 * Terminate every current worker in this pool.
192 */
193 destroy: () => Promise<void>
194 /**
195 * Sets the worker choice strategy in this pool.
196 *
197 * @param workerChoiceStrategy - The worker choice strategy.
198 * @param workerChoiceStrategyOptions - The worker choice strategy options.
199 */
200 setWorkerChoiceStrategy: (
201 workerChoiceStrategy: WorkerChoiceStrategy,
202 workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
203 ) => void
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 */
218 enableTasksQueue: (
219 enable: boolean,
220 tasksQueueOptions?: TasksQueueOptions
221 ) => void
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
228 }