src/utility-types.ts

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