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'
5 import type { WorkerChoiceStrategy
} from
'./pools/selection-strategies/selection-strategies-types.js'
6 import type { KillBehavior
} from
'./worker/worker-options.js'
10 * @typeParam Data - Type of data sent to the worker triggering an error. This can only be structured-cloneable data.
12 export interface WorkerError
<Data
= unknown
> {
14 * Task function name triggering the error.
20 readonly message
: string
22 * Data triggering the error.
31 export interface TaskPerformance
{
37 * Task performance timestamp.
39 readonly timestamp
: number
43 readonly runTime
?: number
45 * Task event loop utilization.
47 readonly elu
?: EventLoopUtilization
51 * Worker task performance statistics computation settings.
54 export interface WorkerStatistics
{
56 * Whether the worker computes the task runtime or not.
58 readonly runTime
: boolean
60 * Whether the worker computes the task event loop utilization (ELU) or not.
66 * Task function properties.
68 export interface TaskFunctionProperties
{
74 * Task function priority. Lower values have higher priority.
76 readonly priority
?: number
78 * Task function worker choice strategy.
80 readonly strategy
?: WorkerChoiceStrategy
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.
88 export interface Task
<Data
= unknown
> {
92 readonly name
?: string
94 * Task input data that will be passed to the worker.
98 * Task priority. Lower values have higher priority.
101 readonly priority
?: number
103 * Task worker choice strategy.
105 readonly strategy
?: WorkerChoiceStrategy
107 * Array of transferable objects.
109 readonly transferList
?: readonly TransferListItem
[]
113 readonly timestamp
?: number
117 readonly taskId
?: `${string}-${string}-${string}-${string}-${string}`
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.
126 export interface MessageValue
<Data
= unknown
, ErrorData
= unknown
>
131 readonly workerId
?: number
135 readonly kill
?: KillBehavior
| true | 'success' | 'failure'
139 readonly workerError
?: WorkerError
<ErrorData
>
143 readonly taskPerformance
?: TaskPerformance
145 * Task function operation:
146 * - `'add'` - Add a task function.
147 * - `'remove'` - Remove a task function.
148 * - `'default'` - Set a task function as default.
150 readonly taskFunctionOperation
?: 'add' | 'remove' | 'default'
152 * Whether the task function operation is successful or not.
154 readonly taskFunctionOperationStatus
?: boolean
156 * Task function properties.
158 readonly taskFunctionProperties
?: TaskFunctionProperties
160 * Task function serialized to string.
162 readonly taskFunction
?: string
164 * Task functions properties.
166 readonly taskFunctionsProperties
?: TaskFunctionProperties
[]
168 * Whether the worker computes the given statistics or not.
170 readonly statistics
?: WorkerStatistics
172 * Whether the worker is ready or not.
174 readonly ready
?: boolean
176 * Whether the worker starts or stops its activity check.
178 readonly checkActive
?: boolean
182 readonly port
?: MessagePort
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.
190 export interface PromiseResponseWrapper
<Response
= unknown
> {
192 * Resolve callback to fulfill the promise.
194 readonly resolve
: (value
: Response
| PromiseLike
<Response
>) => void
196 * Reject callback to reject the promise.
198 readonly reject
: (reason
?: unknown
) => void
200 * The worker node key executing the task.
202 readonly workerNodeKey
: number
204 * The asynchronous resource used to track the task execution.
206 readonly asyncResource
?: AsyncResource
210 * Remove readonly modifier from all properties of T.
211 * @typeParam T - Type to remove readonly modifier.
214 export type Writable
<T
> = { -readonly [P
in keyof T
]: T
[P
] }
217 * Default queue size.
220 export const defaultQueueSize
= 2048
224 * @typeParam T - Type of fixed queue node data.
227 export interface FixedQueueNode
<T
> {
234 * @typeParam T - Type of fixed queue data.
237 export interface IFixedQueue
<T
> {
238 /** The fixed queue capacity. */
239 readonly capacity
: number
240 /** The fixed queue size. */
241 readonly size
: number
242 /** The fixed queue node array. */
243 nodeArray
: FixedQueueNode
<T
>[]
245 * Checks if the fixed queue is empty.
246 * @returns `true` if the fixed queue is empty, `false` otherwise.
250 * Checks if the fixed queue is full.
251 * @returns `true` if the fixed queue is full, `false` otherwise.
255 * Enqueue data into the fixed queue.
256 * @param data - Data to enqueue.
257 * @param priority - Priority of the data. Lower values have higher priority.
258 * @returns The new size of the fixed queue.
259 * @throws If the fixed queue is full.
261 enqueue (data
: T
, priority
?: number): number
263 * Gets data from the fixed queue.
264 * @param index - The index of the data to get.
265 * @returns The data at the index or `undefined` if the fixed queue is empty or the index is out of bounds.
267 get (index
: number): T
| undefined
269 * Dequeue data from the fixed queue.
270 * @returns The dequeued data or `undefined` if the fixed queue is empty.
272 dequeue (): T
| undefined
274 * Clears the fixed queue.
278 * Returns an iterator for the fixed queue.
279 * @returns An iterator for the fixed queue.
280 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols
282 [Symbol
.iterator
] (): Iterator
<T
>
286 * Default bucket size.
289 export const defaultBucketSize
= 2048
292 * Priority queue node.
293 * @typeParam T - Type of priority queue node data.
296 export interface PriorityQueueNode
<T
> extends IFixedQueue
<T
> {
297 next
?: IFixedQueue
<T
>