src/utility-types.ts

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