src/utility-types.ts

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