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