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