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