src/pools/pool.ts

   1 import EventEmitter from 'node:events'
   2 import type {
   3   ErrorHandler,
   4   ExitHandler,
   5   IWorker,
   6   MessageHandler,
   7   OnlineHandler
   8 } from './worker'
   9 import type {
  10   WorkerChoiceStrategy,
  11   WorkerChoiceStrategyOptions
  12 } from './selection-strategies/selection-strategies-types'
  13
  14 /**
  15  * Pool events emitter.
  16  */
  17 export class PoolEmitter extends EventEmitter {}
  18
  19 /**
  20  * Enumeration of pool events.
  21  */
  22 export const PoolEvents = Object.freeze({
  23   full: 'full',
  24   busy: 'busy'
  25 } as const)
  26
  27 /**
  28  * Pool event.
  29  */
  30 export type PoolEvent = keyof typeof PoolEvents
  31
  32 /**
  33  * Worker tasks queue options.
  34  */
  35 export interface TasksQueueOptions {
  36   /**
  37    * Maximum number of tasks that can be executed concurrently on a worker.
  38    *
  39    * @defaultValue 1
  40    */
  41   concurrency?: number
  42 }
  43
  44 /**
  45  * Options for a poolifier pool.
  46  */
  47 export interface PoolOptions<Worker extends IWorker> {
  48   /**
  49    * A function that will listen for message event on each worker.
  50    */
  51   messageHandler?: MessageHandler<Worker>
  52   /**
  53    * A function that will listen for error event on each worker.
  54    */
  55   errorHandler?: ErrorHandler<Worker>
  56   /**
  57    * A function that will listen for online event on each worker.
  58    */
  59   onlineHandler?: OnlineHandler<Worker>
  60   /**
  61    * A function that will listen for exit event on each worker.
  62    */
  63   exitHandler?: ExitHandler<Worker>
  64   /**
  65    * The worker choice strategy to use in this pool.
  66    */
  67   workerChoiceStrategy?: WorkerChoiceStrategy
  68   /**
  69    * The worker choice strategy options.
  70    */
  71   workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
  72   /**
  73    * Pool events emission.
  74    *
  75    * @defaultValue true
  76    */
  77   enableEvents?: boolean
  78   /**
  79    * Pool worker tasks queue.
  80    *
  81    * @experimental
  82    * @defaultValue false
  83    */
  84   enableTasksQueue?: boolean
  85   /**
  86    * Pool worker tasks queue options.
  87    *
  88    * @experimental
  89    * @defaultValue \{ concurrency: 1 \}
  90    */
  91   tasksQueueOptions?: TasksQueueOptions
  92 }
  93
  94 /**
  95  * Contract definition for a poolifier pool.
  96  *
  97  * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
  98  * @typeParam Response - Type of response of execution. This can only be serializable data.
  99  */
 100 export interface IPool<Data = unknown, Response = unknown> {
 101   /**
 102    * Emitter on which events can be listened to.
 103    *
 104    * Events that can currently be listened to:
 105    *
 106    * - `'full'`: Emitted when the pool is dynamic and full.
 107    * - `'busy'`: Emitted when the pool is busy.
 108    */
 109   readonly emitter?: PoolEmitter
 110   /**
 111    * Performs the task specified in the constructor with the data parameter.
 112    *
 113    * @param data - The input for the specified task. This can only be serializable data.
 114    * @returns Promise that will be resolved when the task is successfully completed.
 115    */
 116   execute: (data: Data) => Promise<Response>
 117   /**
 118    * Shutdowns every current worker in this pool.
 119    */
 120   destroy: () => Promise<void>
 121   /**
 122    * Sets the worker choice strategy in this pool.
 123    *
 124    * @param workerChoiceStrategy - The worker choice strategy.
 125    */
 126   setWorkerChoiceStrategy: (workerChoiceStrategy: WorkerChoiceStrategy) => void
 127 }