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  * @internal
  72  */
  73 export interface TaskFunctionProperties {
  74   /**
  75    * Task function name.
  76    */
  77   name: string
  78   /**
  79    * Task function priority. Lower values have higher priority.
  80    */
  81   priority?: number
  82   /**
  83    * Task function worker choice strategy.
  84    */
  85   strategy?: WorkerChoiceStrategy
  86 }
  87
  88 /**
  89  * Message object that is passed as a task between main worker and worker.
  90  *
  91  * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
  92  * @internal
  93  */
  94 export interface Task<Data = unknown> {
  95   /**
  96    * Task name.
  97    */
  98   readonly name?: string
  99   /**
 100    * Task input data that will be passed to the worker.
 101    */
 102   readonly data?: Data
 103   /**
 104    * Array of transferable objects.
 105    */
 106   readonly transferList?: readonly TransferListItem[]
 107   /**
 108    * Timestamp.
 109    */
 110   readonly timestamp?: number
 111   /**
 112    * Task UUID.
 113    */
 114   readonly taskId?: string
 115 }
 116
 117 /**
 118  * Message object that is passed between main worker and worker.
 119  *
 120  * @typeParam Data - Type of data sent to the worker or execution response. This can only be structured-cloneable data.
 121  * @typeParam ErrorData - Type of data sent to the worker triggering an error. This can only be structured-cloneable data.
 122  * @internal
 123  */
 124 export interface MessageValue<Data = unknown, ErrorData = unknown>
 125   extends Task<Data> {
 126   /**
 127    * Worker id.
 128    */
 129   readonly workerId?: number
 130   /**
 131    * Kill code.
 132    */
 133   readonly kill?: KillBehavior | true | 'success' | 'failure'
 134   /**
 135    * Worker error.
 136    */
 137   readonly workerError?: WorkerError<ErrorData>
 138   /**
 139    * Task performance.
 140    */
 141   readonly taskPerformance?: TaskPerformance
 142   /**
 143    * Task function operation:
 144    * - `'add'` - Add a task function.
 145    * - `'remove'` - Remove a task function.
 146    * - `'default'` - Set a task function as default.
 147    */
 148   readonly taskFunctionOperation?: 'add' | 'remove' | 'default'
 149   /**
 150    * Whether the task function operation is successful or not.
 151    */
 152   readonly taskFunctionOperationStatus?: boolean
 153   /**
 154    * Task function properties.
 155    */
 156   readonly taskFunctionProperties?: TaskFunctionProperties
 157   /**
 158    * Task function serialized to string.
 159    */
 160   readonly taskFunction?: string
 161   /**
 162    * Task functions properties.
 163    */
 164   readonly taskFunctionsProperties?: TaskFunctionProperties[]
 165   /**
 166    * Whether the worker computes the given statistics or not.
 167    */
 168   readonly statistics?: WorkerStatistics
 169   /**
 170    * Whether the worker is ready or not.
 171    */
 172   readonly ready?: boolean
 173   /**
 174    * Whether the worker starts or stops its activity check.
 175    */
 176   readonly checkActive?: boolean
 177   /**
 178    * Message port.
 179    */
 180   readonly port?: MessagePort
 181 }
 182
 183 /**
 184  * An object holding the task execution response promise resolve/reject callbacks.
 185  *
 186  * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
 187  * @internal
 188  */
 189 export interface PromiseResponseWrapper<Response = unknown> {
 190   /**
 191    * Resolve callback to fulfill the promise.
 192    */
 193   readonly resolve: (value: Response | PromiseLike<Response>) => void
 194   /**
 195    * Reject callback to reject the promise.
 196    */
 197   readonly reject: (reason?: unknown) => void
 198   /**
 199    * The worker node key executing the task.
 200    */
 201   readonly workerNodeKey: number
 202   /**
 203    * The asynchronous resource used to track the task execution.
 204    */
 205   readonly asyncResource?: AsyncResource
 206 }
 207
 208 export type Writable<T> = { -readonly [P in keyof T]: T[P] }