poolifier 3.0.14 → 3.1.0

package/lib/index.d.ts

@@ -1,9 +1,9 @@
 /// <reference types="node" />
-import { TransferListItem, MessagePort, MessageChannel, Worker as Worker$1, WorkerOptions as WorkerOptions$1 } from 'node:worker_threads';
+import { TransferListItem, MessagePort, MessageChannel, Worker as Worker$1 } from 'node:worker_threads';
 import { EventEmitter, EventEmitterAsyncResource } from 'node:events';
 import { EventLoopUtilization } from 'node:perf_hooks';
 import { AsyncResource } from 'node:async_hooks';
-import { Worker, ClusterSettings } from 'node:cluster';
+import { ClusterSettings, Worker } from 'node:cluster';
 
 /**
  * Enumeration of kill behaviors.
@@ -29,7 +29,7 @@ type KillHandler = () => void | Promise<void>;
 /**
  * Options for workers.
  */
-interface WorkerOptions {
+interface WorkerOptions$1 {
     /**
      * `killBehavior` dictates if your worker will be deleted in case a task is active on it.
      *
@@ -480,33 +480,50 @@ interface StrategyData {
  */
 interface IWorker {
     /**
-     * Worker id.
+     * Cluster worker id.
      */
     readonly id?: number;
+    /**
+     * Worker thread worker id.
+     */
     readonly threadId?: number;
     /**
-     * Registers an event listener.
+     * Registers an event handler.
      *
      * @param event - The event.
      * @param handler - The event handler.
      */
-    readonly on: ((event: 'online', handler: OnlineHandler<this>) => void) & ((event: 'message', handler: MessageHandler<this>) => void) & ((event: 'error', handler: ErrorHandler<this>) => void) & ((event: 'exit', handler: ExitHandler<this>) => void);
+    readonly on: (event: string, handler: OnlineHandler<this> | MessageHandler<this> | ErrorHandler<this> | ExitHandler<this>) => void;
     /**
-     * Registers a listener to the exit event that will only be performed once.
+     * Registers once an event handler.
      *
-     * @param event - The `'exit'` event.
-     * @param handler - The exit handler.
+     * @param event - The event.
+     * @param handler - The event handler.
+     */
+    readonly once: (event: string, handler: OnlineHandler<this> | MessageHandler<this> | ErrorHandler<this> | ExitHandler<this>) => void;
+    /**
+     * Stop all JavaScript execution in the worker thread as soon as possible.
+     * Returns a Promise for the exit code that is fulfilled when the `'exit' event` is emitted.
+     */
+    readonly terminate?: () => Promise<number>;
+    /**
+     * Cluster worker disconnect.
      */
-    readonly once: (event: 'exit', handler: ExitHandler<this>) => void;
+    readonly disconnect?: () => void;
+    /**
+     * Cluster worker kill.
+     */
+    readonly kill?: (signal?: string) => void;
 }
 /**
- * Worker node event detail.
+ * Worker node options.
  *
  * @internal
  */
-interface WorkerNodeEventDetail {
-    workerId: number;
-    workerNodeKey?: number;
+interface WorkerNodeOptions {
+    workerOptions?: WorkerOptions;
+    env?: Record<string, unknown>;
+    tasksQueueBackPressureSize: number;
 }
 /**
  * Worker node interface.
@@ -534,7 +551,7 @@ interface IWorkerNode<Worker extends IWorker, Data = unknown> extends EventEmitt
      */
     strategyData?: StrategyData;
     /**
-     * Message channel (worker_threads only).
+     * Message channel (worker thread only).
      */
     readonly messageChannel?: MessageChannel;
     /**
@@ -589,9 +606,23 @@ interface IWorkerNode<Worker extends IWorker, Data = unknown> extends EventEmitt
      */
     readonly resetUsage: () => void;
     /**
-     * Closes communication channel.
+     * Terminates the worker node.
+     */
+    readonly terminate: () => Promise<void>;
+    /**
+     * Registers a worker event handler.
+     *
+     * @param event - The event.
+     * @param handler - The event handler.
+     */
+    readonly registerWorkerEventHandler: (event: string, handler: OnlineHandler<Worker> | MessageHandler<Worker> | ErrorHandler<Worker> | ExitHandler<Worker>) => void;
+    /**
+     * Registers once a worker event handler.
+     *
+     * @param event - The event.
+     * @param handler - The event handler.
      */
-    readonly closeChannel: () => void;
+    readonly registerOnceWorkerEventHandler: (event: string, handler: OnlineHandler<Worker> | MessageHandler<Worker> | ErrorHandler<Worker> | ExitHandler<Worker>) => void;
     /**
      * Gets task function worker usage statistics.
      *
@@ -607,6 +638,15 @@ interface IWorkerNode<Worker extends IWorker, Data = unknown> extends EventEmitt
      */
     readonly deleteTaskFunctionWorkerUsage: (name: string) => boolean;
 }
+/**
+ * Worker node event detail.
+ *
+ * @internal
+ */
+interface WorkerNodeEventDetail {
+    workerId: number;
+    workerNodeKey?: number;
+}
 
 /**
  * Enumeration of worker choice strategies.
@@ -985,6 +1025,24 @@ interface PoolOptions<Worker extends IWorker> {
      * Pool worker node tasks queue options.
      */
     tasksQueueOptions?: TasksQueueOptions;
+    /**
+     * Worker options.
+     *
+     * @see https://nodejs.org/api/worker_threads.html#new-workerfilename-options
+     */
+    workerOptions?: WorkerOptions;
+    /**
+     * Key/value pairs to add to worker process environment.
+     *
+     * @see https://nodejs.org/api/cluster.html#cluster_cluster_fork_env
+     */
+    env?: Record<string, unknown>;
+    /**
+     * Cluster settings.
+     *
+     * @see https://nodejs.org/api/cluster.html#cluster_cluster_settings
+     */
+    settings?: ClusterSettings;
 }
 /**
  * Contract definition for a poolifier pool.
@@ -1328,6 +1386,7 @@ declare abstract class AbstractPool<Worker extends IWorker, Data = unknown, Resp
      * @returns Worker nodes busyness boolean status.
      */
     protected internalBusy(): boolean;
+    private isWorkerNodeBusy;
     private sendTaskFunctionOperationToWorker;
     private sendTaskFunctionOperationToWorkers;
     /** @inheritDoc */
@@ -1354,7 +1413,7 @@ declare abstract class AbstractPool<Worker extends IWorker, Data = unknown, Resp
      *
      * @param workerNodeKey - The worker node key.
      */
-    protected abstract destroyWorkerNode(workerNodeKey: number): Promise<void>;
+    protected destroyWorkerNode(workerNodeKey: number): Promise<void>;
     /**
      * Setup hook to execute code before worker nodes are created in the abstract constructor.
      * Can be overridden.
@@ -1415,12 +1474,6 @@ declare abstract class AbstractPool<Worker extends IWorker, Data = unknown, Resp
      * @param transferList - The optional array of transferable objects.
      */
     protected abstract sendToWorker(workerNodeKey: number, message: MessageValue<Data>, transferList?: TransferListItem[]): void;
-    /**
-     * Creates a new worker.
-     *
-     * @returns Newly created worker.
-     */
-    protected abstract createWorker(): Worker;
     /**
      * Creates a new, completely set up worker node.
      *
@@ -1473,6 +1526,7 @@ declare abstract class AbstractPool<Worker extends IWorker, Data = unknown, Resp
      * @param workerNodeKey - The worker node key.
      */
     private sendStatisticsMessageToWorker;
+    private handleTask;
     private redistributeQueuedTasks;
     private updateTaskStolenStatisticsWorkerUsage;
     private updateTaskSequentiallyStolenStatisticsWorkerUsage;
@@ -1499,17 +1553,23 @@ declare abstract class AbstractPool<Worker extends IWorker, Data = unknown, Resp
      */
     protected getWorkerInfo(workerNodeKey: number): WorkerInfo;
     /**
-     * Adds the given worker in the pool worker nodes.
+     * Creates a worker node.
      *
-     * @param worker - The worker.
+     * @returns The created worker node.
+     */
+    private createWorkerNode;
+    /**
+     * Adds the given worker node in the pool worker nodes.
+     *
+     * @param workerNode - The worker node.
      * @returns The added worker node key.
      * @throws {@link https://nodejs.org/api/errors.html#class-error} If the added worker node is not found.
      */
     private addWorkerNode;
     /**
-     * Removes the given worker from the pool worker nodes.
+     * Removes the worker node from the pool worker nodes.
      *
-     * @param worker - The worker.
+     * @param workerNode - The worker node.
      */
     private removeWorkerNode;
     protected flagWorkerNodeAsNotReady(workerNodeKey: number): void;
@@ -1530,23 +1590,6 @@ declare abstract class AbstractPool<Worker extends IWorker, Data = unknown, Resp
     private flushTasksQueues;
 }
 
-/**
- * Options for a poolifier cluster pool.
- */
-interface ClusterPoolOptions extends PoolOptions<Worker> {
-    /**
-     * Key/value pairs to add to worker process environment.
-     *
-     * @see https://nodejs.org/api/cluster.html#cluster_cluster_fork_env
-     */
-    env?: Record<string, unknown>;
-    /**
-     * Cluster settings.
-     *
-     * @see https://nodejs.org/api/cluster.html#cluster_cluster_settings
-     */
-    settings?: ClusterSettings;
-}
 /**
  * A cluster pool with a fixed number of workers.
  *
@@ -1556,7 +1599,7 @@ interface ClusterPoolOptions extends PoolOptions<Worker> {
  * @since 2.0.0
  */
 declare class FixedClusterPool<Data = unknown, Response = unknown> extends AbstractPool<Worker, Data, Response> {
-    protected readonly opts: ClusterPoolOptions;
+    protected readonly opts: PoolOptions<Worker>;
     /**
      * Constructs a new poolifier fixed cluster pool.
      *
@@ -1564,14 +1607,12 @@ declare class FixedClusterPool<Data = unknown, Response = unknown> extends Abstr
      * @param filePath - Path to an implementation of a `ClusterWorker` file, which can be relative or absolute.
      * @param opts - Options for this fixed cluster pool.
      */
-    constructor(numberOfWorkers: number, filePath: string, opts?: ClusterPoolOptions);
+    constructor(numberOfWorkers: number, filePath: string, opts?: PoolOptions<Worker>);
     /** @inheritDoc */
     protected setupHook(): void;
     /** @inheritDoc */
     protected isMain(): boolean;
     /** @inheritDoc */
-    protected destroyWorkerNode(workerNodeKey: number): Promise<void>;
-    /** @inheritDoc */
     protected sendToWorker(workerNodeKey: number, message: MessageValue<Data>): void;
     /** @inheritDoc */
     protected sendStartupMessageToWorker(workerNodeKey: number): void;
@@ -1582,8 +1623,6 @@ declare class FixedClusterPool<Data = unknown, Response = unknown> extends Abstr
     /** @inheritDoc */
     protected deregisterWorkerMessageListener<Message extends Data | Response>(workerNodeKey: number, listener: (message: MessageValue<Message>) => void): void;
     /** @inheritDoc */
-    protected createWorker(): Worker;
-    /** @inheritDoc */
     protected get type(): PoolType;
     /** @inheritDoc */
     protected get worker(): WorkerType;
@@ -1612,24 +1651,13 @@ declare class DynamicClusterPool<Data = unknown, Response = unknown> extends Fix
      * @param filePath - Path to an implementation of a `ClusterWorker` file, which can be relative or absolute.
      * @param opts - Options for this dynamic cluster pool.
      */
-    constructor(min: number, max: number, filePath: string, opts?: ClusterPoolOptions);
+    constructor(min: number, max: number, filePath: string, opts?: PoolOptions<Worker>);
     /** @inheritDoc */
     protected get type(): PoolType;
     /** @inheritDoc */
     protected get busy(): boolean;
 }
 
-/**
- * Options for a poolifier thread pool.
- */
-interface ThreadPoolOptions extends PoolOptions<Worker$1> {
-    /**
-     * Worker options.
-     *
-     * @see https://nodejs.org/api/worker_threads.html#new-workerfilename-options
-     */
-    workerOptions?: WorkerOptions$1;
-}
 /**
  * A thread pool with a fixed number of threads.
  *
@@ -1639,7 +1667,7 @@ interface ThreadPoolOptions extends PoolOptions<Worker$1> {
  * @since 0.0.1
  */
 declare class FixedThreadPool<Data = unknown, Response = unknown> extends AbstractPool<Worker$1, Data, Response> {
-    protected readonly opts: ThreadPoolOptions;
+    protected readonly opts: PoolOptions<Worker$1>;
     /**
      * Constructs a new poolifier fixed thread pool.
      *
@@ -1647,12 +1675,10 @@ declare class FixedThreadPool<Data = unknown, Response = unknown> extends Abstra
      * @param filePath - Path to an implementation of a `ThreadWorker` file, which can be relative or absolute.
      * @param opts - Options for this fixed thread pool.
      */
-    constructor(numberOfThreads: number, filePath: string, opts?: ThreadPoolOptions);
+    constructor(numberOfThreads: number, filePath: string, opts?: PoolOptions<Worker$1>);
     /** @inheritDoc */
     protected isMain(): boolean;
     /** @inheritDoc */
-    protected destroyWorkerNode(workerNodeKey: number): Promise<void>;
-    /** @inheritDoc */
     protected sendToWorker(workerNodeKey: number, message: MessageValue<Data>, transferList?: TransferListItem[]): void;
     /** @inheritDoc */
     protected sendStartupMessageToWorker(workerNodeKey: number): void;
@@ -1663,8 +1689,6 @@ declare class FixedThreadPool<Data = unknown, Response = unknown> extends Abstra
     /** @inheritDoc */
     protected deregisterWorkerMessageListener<Message extends Data | Response>(workerNodeKey: number, listener: (message: MessageValue<Message>) => void): void;
     /** @inheritDoc */
-    protected createWorker(): Worker$1;
-    /** @inheritDoc */
     protected get type(): PoolType;
     /** @inheritDoc */
     protected get worker(): WorkerType;
@@ -1693,7 +1717,7 @@ declare class DynamicThreadPool<Data = unknown, Response = unknown> extends Fixe
      * @param filePath - Path to an implementation of a `ThreadWorker` file, which can be relative or absolute.
      * @param opts - Options for this dynamic thread pool.
      */
-    constructor(min: number, max: number, filePath: string, opts?: ThreadPoolOptions);
+    constructor(min: number, max: number, filePath: string, opts?: PoolOptions<Worker$1>);
     /** @inheritDoc */
     protected get type(): PoolType;
     /** @inheritDoc */
@@ -1710,7 +1734,7 @@ declare class DynamicThreadPool<Data = unknown, Response = unknown> extends Fixe
 declare abstract class AbstractWorker<MainWorker extends Worker | MessagePort, Data = unknown, Response = unknown> {
     protected readonly isMain: boolean;
     private readonly mainWorker;
-    protected opts: WorkerOptions;
+    protected opts: WorkerOptions$1;
     /**
      * Worker id.
      */
@@ -1739,7 +1763,7 @@ declare abstract class AbstractWorker<MainWorker extends Worker | MessagePort, D
      * @param taskFunctions - Task function(s) processed by the worker when the pool's `execution` function is invoked. The first function is the default function.
      * @param opts - Options for the worker.
      */
-    constructor(isMain: boolean, mainWorker: MainWorker, taskFunctions: TaskFunction<Data, Response> | TaskFunctions<Data, Response>, opts?: WorkerOptions);
+    constructor(isMain: boolean, mainWorker: MainWorker, taskFunctions: TaskFunction<Data, Response> | TaskFunctions<Data, Response>, opts?: WorkerOptions$1);
     private checkWorkerOptions;
     /**
      * Checks if the `taskFunctions` parameter is passed to the constructor and valid.
@@ -1892,7 +1916,7 @@ declare class ClusterWorker<Data = unknown, Response = unknown> extends Abstract
      * @param taskFunctions - Task function(s) processed by the worker when the pool's `execution` function is invoked.
      * @param opts - Options for the worker.
      */
-    constructor(taskFunctions: TaskFunction<Data, Response> | TaskFunctions<Data, Response>, opts?: WorkerOptions);
+    constructor(taskFunctions: TaskFunction<Data, Response> | TaskFunctions<Data, Response>, opts?: WorkerOptions$1);
     /** @inheritDoc */
     protected handleReadyMessage(message: MessageValue<Data>): void;
     /** @inheritDoc */
@@ -1926,7 +1950,7 @@ declare class ThreadWorker<Data = unknown, Response = unknown> extends AbstractW
      * @param taskFunctions - Task function(s) processed by the worker when the pool's `execution` function is invoked.
      * @param opts - Options for the worker.
      */
-    constructor(taskFunctions: TaskFunction<Data, Response> | TaskFunctions<Data, Response>, opts?: WorkerOptions);
+    constructor(taskFunctions: TaskFunction<Data, Response> | TaskFunctions<Data, Response>, opts?: WorkerOptions$1);
     /** @inheritDoc */
     protected handleReadyMessage(message: MessageValue<Data>): void;
     /** @inheritDoc */
@@ -2034,4 +2058,4 @@ declare class Deque<T> {
  */
 declare const availableParallelism: () => number;
 
-export { AbstractPool, AbstractWorker, CircularArray, type ClusterPoolOptions, ClusterWorker, Deque, DynamicClusterPool, DynamicThreadPool, type ErrorHandler, type EventLoopUtilizationMeasurementStatistics, type ExitHandler, FixedClusterPool, FixedThreadPool, type IPool, type IWorker, type IWorkerChoiceStrategy, type IWorkerNode, type KillBehavior, KillBehaviors, type KillHandler, type Measurement, type MeasurementOptions, type MeasurementStatistics, type MeasurementStatisticsRequirements, Measurements, type MessageHandler, type MessageValue, Node, type OnlineHandler, type PoolEvent, PoolEvents, type PoolInfo, type PoolOptions, type PoolType, PoolTypes, type PromiseResponseWrapper, type StrategyData, type StrategyPolicy, type Task, type TaskAsyncFunction, type TaskFunction, type TaskFunctionOperationResult, type TaskFunctions, type TaskPerformance, type TaskStatistics, type TaskStatisticsRequirements, type TaskSyncFunction, type TasksQueueOptions, type ThreadPoolOptions, ThreadWorker, WorkerChoiceStrategies, type WorkerChoiceStrategy, WorkerChoiceStrategyContext, type WorkerChoiceStrategyOptions, type WorkerError, type WorkerInfo, type WorkerNodeEventDetail, type WorkerOptions, type WorkerStatistics, type WorkerType, WorkerTypes, type WorkerUsage, type Writable, availableParallelism };
+export { AbstractPool, AbstractWorker, CircularArray, ClusterWorker, Deque, DynamicClusterPool, DynamicThreadPool, type ErrorHandler, type EventLoopUtilizationMeasurementStatistics, type ExitHandler, FixedClusterPool, FixedThreadPool, type IPool, type IWorker, type IWorkerChoiceStrategy, type IWorkerNode, type KillBehavior, KillBehaviors, type KillHandler, type Measurement, type MeasurementOptions, type MeasurementStatistics, type MeasurementStatisticsRequirements, Measurements, type MessageHandler, type MessageValue, Node, type OnlineHandler, type PoolEvent, PoolEvents, type PoolInfo, type PoolOptions, type PoolType, PoolTypes, type PromiseResponseWrapper, type StrategyData, type StrategyPolicy, type Task, type TaskAsyncFunction, type TaskFunction, type TaskFunctionOperationResult, type TaskFunctions, type TaskPerformance, type TaskStatistics, type TaskStatisticsRequirements, type TaskSyncFunction, type TasksQueueOptions, ThreadWorker, WorkerChoiceStrategies, type WorkerChoiceStrategy, WorkerChoiceStrategyContext, type WorkerChoiceStrategyOptions, type WorkerError, type WorkerInfo, type WorkerNodeEventDetail, type WorkerNodeOptions, type WorkerOptions$1 as WorkerOptions, type WorkerStatistics, type WorkerType, WorkerTypes, type WorkerUsage, type Writable, availableParallelism };