src/utility-types.ts

   1 import type { AsyncResource } from 'node:async_hooks'
   2 import type { EventLoopUtilization } from 'node:perf_hooks'
   3 import type { MessagePort, TransferListItem } from 'node:worker_threads'
   4
   5 import type { WorkerChoiceStrategy } from './pools/selection-strategies/selection-strategies-types.js'
   6 import type { KillBehavior } from './worker/worker-options.js'
   7
   8 /**
   9  * Worker error.
  10  *
  11  * @typeParam Data - Type of data sent to the worker triggering an error. This can only be structured-cloneable data.
  12  */
  13 export interface WorkerError<Data = unknown> {
  14   /**
  15    * Task function name triggering the error.
  16    */
  17   readonly name: string
  18   /**
  19    * Error message.
  20    */
  21   readonly message: string
  22   /**
  23    * Data triggering the error.
  24    */
  25   readonly data?: Data
  26 }
  27
  28 /**
  29  * Task performance.
  30  *
  31  * @internal
  32  */
  33 export interface TaskPerformance {
  34   /**
  35    * Task name.
  36    */
  37   readonly name: string
  38   /**
  39    * Task performance timestamp.
  40    */
  41   readonly timestamp: number
  42   /**
  43    * Task runtime.
  44    */
  45   readonly runTime?: number
  46   /**
  47    * Task event loop utilization.
  48    */
  49   readonly elu?: EventLoopUtilization
  50 }
  51
  52 /**
  53  * Worker task performance statistics computation settings.
  54  *
  55  * @internal
  56  */
  57 export interface WorkerStatistics {
  58   /**
  59    * Whether the worker computes the task runtime or not.
  60    */
  61   readonly runTime: boolean
  62   /**
  63    * Whether the worker computes the task event loop utilization (ELU) or not.
  64    */
  65   readonly elu: boolean
  66 }
  67
  68 /**
  69  * Task function properties.
  70  */
  71 export interface TaskFunctionProperties {
  72   /**
  73    * Task function name.
  74    */
  75   readonly name: string
  76   /**
  77    * Task function priority. Lower values have higher priority.
  78    */
  79   readonly priority?: number
  80   /**
  81    * Task function worker choice strategy.
  82    */
  83   readonly strategy?: WorkerChoiceStrategy
  84 }
  85
  86 /**
  87  * Message object that is passed as a task between main worker and worker.
  88  *
  89  * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
  90  * @internal
  91  */
  92 export interface Task<Data = unknown> {
  93   /**
  94    * Task name.
  95    */
  96   readonly name?: string
  97   /**
  98    * Task input data that will be passed to the worker.
  99    */
 100   readonly data?: Data
 101   /**
 102    * Task priority. Lower values have higher priority.
 103    *
 104    * @defaultValue 0
 105    */
 106   readonly priority?: number
 107   /**
 108    * Task worker choice strategy.
 109    */
 110   readonly strategy?: WorkerChoiceStrategy
 111   /**
 112    * Array of transferable objects.
 113    */
 114   readonly transferList?: readonly TransferListItem[]
 115   /**
 116    * Timestamp.
 117    */
 118   readonly timestamp?: number
 119   /**
 120    * Task UUID.
 121    */
 122   readonly taskId?: `${string}-${string}-${string}-${string}-${string}`
 123 }
 124
 125 /**
 126  * Message object that is passed between main worker and worker.
 127  *
 128  * @typeParam Data - Type of data sent to the worker or execution response. This can only be structured-cloneable data.
 129  * @typeParam ErrorData - Type of data sent to the worker triggering an error. This can only be structured-cloneable data.
 130  * @internal
 131  */
 132 export interface MessageValue<Data = unknown, ErrorData = unknown>
 133   extends Task<Data> {
 134   /**
 135    * Worker id.
 136    */
 137   readonly workerId?: number
 138   /**
 139    * Kill code.
 140    */
 141   readonly kill?: KillBehavior | true | 'success' | 'failure'
 142   /**
 143    * Worker error.
 144    */
 145   readonly workerError?: WorkerError<ErrorData>
 146   /**
 147    * Task performance.
 148    */
 149   readonly taskPerformance?: TaskPerformance
 150   /**
 151    * Task function operation:
 152    * - `'add'` - Add a task function.
 153    * - `'remove'` - Remove a task function.
 154    * - `'default'` - Set a task function as default.
 155    */
 156   readonly taskFunctionOperation?: 'add' | 'remove' | 'default'
 157   /**
 158    * Whether the task function operation is successful or not.
 159    */
 160   readonly taskFunctionOperationStatus?: boolean
 161   /**
 162    * Task function properties.
 163    */
 164   readonly taskFunctionProperties?: TaskFunctionProperties
 165   /**
 166    * Task function serialized to string.
 167    */
 168   readonly taskFunction?: string
 169   /**
 170    * Task functions properties.
 171    */
 172   readonly taskFunctionsProperties?: TaskFunctionProperties[]
 173   /**
 174    * Whether the worker computes the given statistics or not.
 175    */
 176   readonly statistics?: WorkerStatistics
 177   /**
 178    * Whether the worker is ready or not.
 179    */
 180   readonly ready?: boolean
 181   /**
 182    * Whether the worker starts or stops its activity check.
 183    */
 184   readonly checkActive?: boolean
 185   /**
 186    * Message port.
 187    */
 188   readonly port?: MessagePort
 189 }
 190
 191 /**
 192  * An object holding the task execution response promise resolve/reject callbacks.
 193  *
 194  * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
 195  * @internal
 196  */
 197 export interface PromiseResponseWrapper<Response = unknown> {
 198   /**
 199    * Resolve callback to fulfill the promise.
 200    */
 201   readonly resolve: (value: Response | PromiseLike<Response>) => void
 202   /**
 203    * Reject callback to reject the promise.
 204    */
 205   readonly reject: (reason?: unknown) => void
 206   /**
 207    * The worker node key executing the task.
 208    */
 209   readonly workerNodeKey: number
 210   /**
 211    * The asynchronous resource used to track the task execution.
 212    */
 213   readonly asyncResource?: AsyncResource
 214 }
 215
 216 export type Writable<T> = { -readonly [P in keyof T]: T[P] }