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  * Pool types.
  17  *
  18  * @enum
  19  * @internal
  20  */
  21 export enum PoolType {
  22   /**
  23    * Fixed pool type.
  24    */
  25   FIXED = 'fixed',
  26   /**
  27    * Dynamic pool type.
  28    */
  29   DYNAMIC = 'dynamic'
  30 }
  31
  32 /**
  33  * Pool events emitter.
  34  */
  35 export class PoolEmitter extends EventEmitterAsyncResource {}
  36
  37 /**
  38  * Enumeration of pool events.
  39  */
  40 export const PoolEvents = Object.freeze({
  41   full: 'full',
  42   busy: 'busy',
  43   error: 'error'
  44 } as const)
  45
  46 /**
  47  * Pool event.
  48  */
  49 export type PoolEvent = keyof typeof PoolEvents
  50
  51 /**
  52  * Worker tasks queue options.
  53  */
  54 export interface TasksQueueOptions {
  55   /**
  56    * Maximum number of tasks that can be executed concurrently on a worker.
  57    *
  58    * @defaultValue 1
  59    */
  60   concurrency?: number
  61 }
  62
  63 /**
  64  * Options for a poolifier pool.
  65  *
  66  * @typeParam Worker - Type of worker.
  67  */
  68 export interface PoolOptions<Worker extends IWorker> {
  69   /**
  70    * A function that will listen for message event on each worker.
  71    */
  72   messageHandler?: MessageHandler<Worker>
  73   /**
  74    * A function that will listen for error event on each worker.
  75    */
  76   errorHandler?: ErrorHandler<Worker>
  77   /**
  78    * A function that will listen for online event on each worker.
  79    */
  80   onlineHandler?: OnlineHandler<Worker>
  81   /**
  82    * A function that will listen for exit event on each worker.
  83    */
  84   exitHandler?: ExitHandler<Worker>
  85   /**
  86    * The worker choice strategy to use in this pool.
  87    *
  88    * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
  89    */
  90   workerChoiceStrategy?: WorkerChoiceStrategy
  91   /**
  92    * The worker choice strategy options.
  93    */
  94   workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
  95   /**
  96    * Restart worker on error.
  97    */
  98   restartWorkerOnError?: boolean
  99   /**
 100    * Pool events emission.
 101    *
 102    * @defaultValue true
 103    */
 104   enableEvents?: boolean
 105   /**
 106    * Pool worker tasks queue.
 107    *
 108    * @defaultValue false
 109    */
 110   enableTasksQueue?: boolean
 111   /**
 112    * Pool worker tasks queue options.
 113    */
 114   tasksQueueOptions?: TasksQueueOptions
 115 }
 116
 117 /**
 118  * Contract definition for a poolifier pool.
 119  *
 120  * @typeParam Worker - Type of worker which manages this pool.
 121  * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
 122  * @typeParam Response - Type of execution response. This can only be serializable data.
 123  */
 124 export interface IPool<
 125   Worker extends IWorker,
 126   Data = unknown,
 127   Response = unknown
 128 > {
 129   /**
 130    * Pool type.
 131    *
 132    * If it is `'dynamic'`, it provides the `max` property.
 133    */
 134   readonly type: PoolType
 135   /**
 136    * Pool maximum size.
 137    */
 138   readonly size: number
 139   /**
 140    * Pool worker nodes.
 141    */
 142   readonly workerNodes: Array<WorkerNode<Worker, Data>>
 143   /**
 144    * Emitter on which events can be listened to.
 145    *
 146    * Events that can currently be listened to:
 147    *
 148    * - `'full'`: Emitted when the pool is dynamic and full.
 149    * - `'busy'`: Emitted when the pool is busy.
 150    * - `'error'`: Emitted when an error occurs.
 151    */
 152   readonly emitter?: PoolEmitter
 153   /**
 154    * Executes the specified function in the worker constructor with the task data input parameter.
 155    *
 156    * @param data - The task input data for the specified worker function. This can only be serializable data.
 157    * @param name - The name of the worker function to execute. If not specified, the default worker function will be executed.
 158    * @returns Promise that will be fulfilled when the task is completed.
 159    */
 160   execute: (data?: Data, name?: string) => Promise<Response>
 161   /**
 162    * Shutdowns every current worker in this pool.
 163    */
 164   destroy: () => Promise<void>
 165   /**
 166    * Sets the worker choice strategy in this pool.
 167    *
 168    * @param workerChoiceStrategy - The worker choice strategy.
 169    * @param workerChoiceStrategyOptions - The worker choice strategy options.
 170    */
 171   setWorkerChoiceStrategy: (
 172     workerChoiceStrategy: WorkerChoiceStrategy,
 173     workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
 174   ) => void
 175   /**
 176    * Sets the worker choice strategy options in this pool.
 177    *
 178    * @param workerChoiceStrategyOptions - The worker choice strategy options.
 179    */
 180   setWorkerChoiceStrategyOptions: (
 181     workerChoiceStrategyOptions: WorkerChoiceStrategyOptions
 182   ) => void
 183   /**
 184    * Enables/disables the worker tasks queue in this pool.
 185    *
 186    * @param enable - Whether to enable or disable the worker tasks queue.
 187    * @param tasksQueueOptions - The worker tasks queue options.
 188    */
 189   enableTasksQueue: (
 190     enable: boolean,
 191     tasksQueueOptions?: TasksQueueOptions
 192   ) => void
 193   /**
 194    * Sets the worker tasks queue options in this pool.
 195    *
 196    * @param tasksQueueOptions - The worker tasks queue options.
 197    */
 198   setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void
 199 }