poolifier 5.1.7 → 5.2.0

package/lib/index.d.ts

@@ -88,11 +88,11 @@ declare const Measurements: Readonly<{
 interface IWorkerChoiceStrategy {
     /**
      * Chooses a worker node in the pool and returns its key.
-     * If no worker nodes are not eligible, `undefined` is returned.
-     * If `undefined` is returned, the caller retry.
+     * If no worker nodes are eligible, `undefined` is returned and the caller retries.
+     * @param workerNodeKeysSet - The worker node keys affinity set. If undefined, all workers are eligible.
      * @returns The worker node key or `undefined`.
      */
-    readonly choose: () => number | undefined;
+    readonly choose: (workerNodeKeysSet?: ReadonlySet<number>) => number | undefined;
     /**
      * The worker choice strategy name.
      */
@@ -276,8 +276,8 @@ interface WorkerOptions {
 
 /**
  * Message object that is passed between main worker and worker.
- * @typeParam Data - Type of data sent to the worker or execution response. This can only be structured-cloneable data.
- * @typeParam ErrorData - Type of data sent to the worker triggering an error. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker or execution response. This can only be structured-cloneable data.
+ * @template ErrorData - Type of data sent to the worker triggering an error. This can only be structured-cloneable data.
  * @internal
  */
 interface MessageValue<Data = unknown, ErrorData = unknown> extends Task<Data> {
@@ -344,7 +344,7 @@ interface MessageValue<Data = unknown, ErrorData = unknown> extends Task<Data> {
 }
 /**
  * An object holding the task execution response promise resolve/reject callbacks.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  * @internal
  */
 interface PromiseResponseWrapper<Response = unknown> {
@@ -371,7 +371,7 @@ interface PromiseResponseWrapper<Response = unknown> {
 }
 /**
  * Message object that is passed as a task between main worker and worker.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
  * @internal
  */
 interface Task<Data = unknown> {
@@ -425,6 +425,13 @@ interface TaskFunctionProperties {
      * Task function worker choice strategy.
      */
     readonly strategy?: WorkerChoiceStrategy;
+    /**
+     * Task function worker node keys affinity.
+     * Restricts task execution to specified worker nodes by their indices.
+     * Must contain valid indices within [0, pool max size - 1].
+     * If undefined, task can execute on any worker node.
+     */
+    readonly workerNodeKeys?: number[];
 }
 /**
  * Task performance.
@@ -450,7 +457,7 @@ interface TaskPerformance {
 }
 /**
  * Worker error.
- * @typeParam Data - Type of data sent to the worker triggering an error. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker triggering an error. This can only be structured-cloneable data.
  */
 interface WorkerError<Data = unknown> {
     /**
@@ -494,7 +501,7 @@ interface WorkerStatistics {
 }
 /**
  * Remove readonly modifier from all properties of T.
- * @typeParam T - Type to remove readonly modifier.
+ * @template T - Type to remove readonly modifier.
  * @internal
  */
 type Writable<T> = {
@@ -506,21 +513,21 @@ type Writable<T> = {
  * This function must return a promise.
  * @param data - Data sent to the worker.
  * @returns Execution response promise.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  */
 type TaskAsyncFunction<Data = unknown, Response = unknown> = (data?: Data) => Promise<Response>;
 /**
  * Task function that can be executed.
  * This function can be synchronous or asynchronous.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  */
 type TaskFunction<Data = unknown, Response = unknown> = TaskAsyncFunction<Data, Response> | TaskSyncFunction<Data, Response>;
 /**
  * Task function object.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  */
 interface TaskFunctionObject<Data = unknown, Response = unknown> {
     /**
@@ -535,6 +542,13 @@ interface TaskFunctionObject<Data = unknown, Response = unknown> {
      * Task function.
      */
     taskFunction: TaskFunction<Data, Response>;
+    /**
+     * Task function worker node keys affinity.
+     * Restricts task execution to specified worker nodes by their indices.
+     * Must contain valid indices within [0, pool max size - 1].
+     * If undefined, task can execute on any worker node.
+     */
+    workerNodeKeys?: number[];
 }
 /**
  * Task function operation result.
@@ -547,22 +561,22 @@ interface TaskFunctionOperationResult {
  * Tasks functions that can be executed.
  * The key is the name of the task function or task function object.
  * The value is the task function or task function object.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  */
 type TaskFunctions<Data = unknown, Response = unknown> = Record<string, TaskFunction<Data, Response> | TaskFunctionObject<Data, Response>>;
 /**
  * Task synchronous function that can be executed.
  * @param data - Data sent to the worker.
  * @returns Execution response.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  */
 type TaskSyncFunction<Data = unknown, Response = unknown> = (data?: Data) => Response;
 
 /**
  * Priority queue.
- * @typeParam T - Type of priority queue data.
+ * @template T - Type of priority queue data.
  * @internal
  */
 declare class PriorityQueue<T> {
@@ -633,27 +647,27 @@ declare class PriorityQueue<T> {
 
 /**
  * Callback invoked if the worker raised an error.
- * @typeParam Worker - Type of worker.
+ * @template Worker - Type of worker.
  */
 type ErrorHandler<Worker extends IWorker> = (this: Worker, error: Error) => void;
 /**
  * Worker event handler.
- * @typeParam Worker - Type of worker.
+ * @template Worker - Type of worker.
  */
 type EventHandler<Worker extends IWorker> = ErrorHandler<Worker> | ExitHandler<Worker> | MessageHandler<Worker> | OnlineHandler<Worker>;
 /**
  * Callback invoked when the worker exits successfully.
- * @typeParam Worker - Type of worker.
+ * @template Worker - Type of worker.
  */
 type ExitHandler<Worker extends IWorker> = (this: Worker, exitCode: number) => void;
 /**
  * Callback invoked if the worker has received a message.
- * @typeParam Worker - Type of worker.
+ * @template Worker - Type of worker.
  */
 type MessageHandler<Worker extends IWorker> = (this: Worker, message: unknown) => void;
 /**
  * Callback invoked when the worker has started successfully.
- * @typeParam Worker - Type of worker.
+ * @template Worker - Type of worker.
  */
 type OnlineHandler<Worker extends IWorker> = (this: Worker) => void;
 /**
@@ -783,8 +797,8 @@ interface IWorker extends EventEmitter {
 }
 /**
  * Worker node interface.
- * @typeParam Worker - Type of worker.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Worker - Type of worker.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
  * @internal
  */
 interface IWorkerNode<Worker extends IWorker, Data = unknown> extends EventEmitter {
@@ -1024,9 +1038,9 @@ declare const PoolEvents: Readonly<{
 }>;
 /**
  * Contract definition for a poolifier pool.
- * @typeParam Worker - Type of worker which manages this pool.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Worker - Type of worker which manages this pool.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  */
 interface IPool<Worker extends IWorker, Data = unknown, Response = unknown> {
     /**
@@ -1211,7 +1225,7 @@ interface PoolInfo {
 }
 /**
  * Options for a poolifier pool.
- * @typeParam Worker - Type of worker.
+ * @template Worker - Type of worker.
  */
 interface PoolOptions<Worker extends IWorker> {
     /**
@@ -1320,9 +1334,9 @@ interface TasksQueueOptions {
 
 /**
  * The worker choice strategies context.
- * @typeParam Worker - Type of worker.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Worker - Type of worker.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  * @internal
  */
 declare class WorkerChoiceStrategiesContext<Worker extends IWorker, Data = unknown, Response = unknown> {
@@ -1356,13 +1370,13 @@ declare class WorkerChoiceStrategiesContext<Worker extends IWorker, Data = unkno
      */
     constructor(pool: IPool<Worker, Data, Response>, workerChoiceStrategies?: WorkerChoiceStrategy[], opts?: WorkerChoiceStrategyOptions);
     /**
-     * Executes the given worker choice strategy in the context algorithm.
-     * @param workerChoiceStrategy - The worker choice strategy algorithm to execute.
-     * @defaultValue this.defaultWorkerChoiceStrategy
+     * Executes the given worker choice strategy.
+     * @param workerChoiceStrategy - The worker choice strategy.
+     * @param workerNodeKeysSet - The worker node keys affinity set. If undefined, all workers are eligible.
      * @returns The key of the worker node.
      * @throws {Error} If after computed retries the worker node key is null or undefined.
      */
-    execute(workerChoiceStrategy?: WorkerChoiceStrategy): number;
+    execute(workerChoiceStrategy?: WorkerChoiceStrategy, workerNodeKeysSet?: ReadonlySet<number>): number;
     /**
      * Gets the active worker choice strategies in the context policy.
      * @returns The strategies policy.
@@ -1416,8 +1430,9 @@ declare class WorkerChoiceStrategiesContext<Worker extends IWorker, Data = unkno
      */
     private addWorkerChoiceStrategy;
     /**
-     * Executes the given worker choice strategy.
-     * @param workerChoiceStrategy - The worker choice strategy.
+     * Executes the given worker choice strategy in the context algorithm.
+     * @param workerChoiceStrategy - The worker choice strategy algorithm to execute.
+     * @param workerNodeKeysSet - The worker node keys affinity set. If undefined, all workers are eligible.
      * @returns The key of the worker node.
      * @throws {Error} If after computed retries the worker node key is null or undefined.
      */
@@ -1432,9 +1447,9 @@ declare class WorkerChoiceStrategiesContext<Worker extends IWorker, Data = unkno
 
 /**
  * Base class that implements some shared logic for all poolifier pools.
- * @typeParam Worker - Type of worker which manages this pool.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Worker - Type of worker which manages this pool.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  */
 declare abstract class AbstractPool<Worker extends IWorker, Data = unknown, Response = unknown> implements IPool<Worker, Data, Response> {
     protected readonly minimumNumberOfWorkers: number;
@@ -1726,6 +1741,12 @@ declare abstract class AbstractPool<Worker extends IWorker, Data = unknown, Resp
      * @returns The task function worker choice strategy if the task function worker choice strategy is defined, `undefined` otherwise.
      */
     private readonly getTaskFunctionWorkerChoiceStrategy;
+    /**
+     * Gets task function worker node keys affinity set, if any.
+     * @param name - The task function name.
+     * @returns The task function worker node keys affinity set, or `undefined` if not defined.
+     */
+    private readonly getTaskFunctionWorkerNodeKeysSet;
     private getTasksQueuePriority;
     /**
      * Gets the worker choice strategies registered in this pool.
@@ -1817,8 +1838,8 @@ declare abstract class AbstractPool<Worker extends IWorker, Data = unknown, Resp
 type ClusterPoolOptions = PoolOptions<Worker>;
 /**
  * A cluster pool with a fixed number of workers.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  * @author [Christopher Quadflieg](https://github.com/Shinigami92)
  * @since 2.0.0
  */
@@ -1866,8 +1887,8 @@ declare class FixedClusterPool<Data = unknown, Response = unknown> extends Abstr
  *
  * This cluster pool creates new workers when the others are busy, up to the maximum number of workers.
  * When the maximum number of workers is reached and workers are busy, an event is emitted. If you want to listen to this event, use the pool's `emitter`.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  * @author [Christopher Quadflieg](https://github.com/Shinigami92)
  * @since 2.0.0
  */
@@ -1918,8 +1939,8 @@ declare class DynamicClusterPool<Data = unknown, Response = unknown> extends Fix
 type ThreadPoolOptions = PoolOptions<Worker$1>;
 /**
  * A thread pool with a fixed number of threads.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  * @author [Alessandro Pio Ardizio](https://github.com/pioardi)
  * @since 0.0.1
  */
@@ -1965,8 +1986,8 @@ declare class FixedThreadPool<Data = unknown, Response = unknown> extends Abstra
  *
  * This thread pool creates new threads when the others are busy, up to the maximum number of threads.
  * When the maximum number of threads is reached and workers are busy, an event is emitted. If you want to listen to this event, use the pool's `emitter`.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
+ * @template Data - Type of data sent to the worker. This can only be structured-cloneable data.
+ * @template Response - Type of execution response. This can only be structured-cloneable data.
  * @author [Alessandro Pio Ardizio](https://github.com/pioardi)
  * @since 0.0.1
  */
@@ -2013,7 +2034,7 @@ declare class DynamicThreadPool<Data = unknown, Response = unknown> extends Fixe
 
 /**
  * Fixed queue node.
- * @typeParam T - Type of fixed queue node data.
+ * @template T - Type of fixed queue node data.
  * @internal
  */
 interface FixedQueueNode<T> {
@@ -2023,7 +2044,7 @@ interface FixedQueueNode<T> {
 }
 /**
  * Fixed queue.
- * @typeParam T - Type of fixed queue data.
+ * @template T - Type of fixed queue data.
  * @internal
  */
 interface IFixedQueue<T> {
@@ -2089,9 +2110,9 @@ declare const availableParallelism: () => number;
 
 /**
  * Base class that implements some shared logic for all poolifier workers.
- * @typeParam MainWorker - Type of main worker.
- * @typeParam Data - Type of data this worker receives from pool's execution. This can only be structured-cloneable data.
- * @typeParam Response - Type of response the worker sends back to the main worker. This can only be structured-cloneable data.
+ * @template MainWorker - Type of main worker.
+ * @template Data - Type of data this worker receives from pool's execution. This can only be structured-cloneable data.
+ * @template Response - Type of response the worker sends back to the main worker. This can only be structured-cloneable data.
  */
 declare abstract class AbstractWorker<MainWorker extends MessagePort | Worker, Data = unknown, Response = unknown> {
     protected readonly isMain: boolean | undefined;
@@ -2264,8 +2285,8 @@ declare abstract class AbstractWorker<MainWorker extends MessagePort | Worker, D
  *
  * If you use a `DynamicClusterPool` the extra workers that were created will be terminated,
  * but the minimum number of workers will be guaranteed.
- * @typeParam Data - Type of data this worker receives from pool's execution. This can only be structured-cloneable data.
- * @typeParam Response - Type of response the worker sends back to the main worker. This can only be structured-cloneable data.
+ * @template Data - Type of data this worker receives from pool's execution. This can only be structured-cloneable data.
+ * @template Response - Type of response the worker sends back to the main worker. This can only be structured-cloneable data.
  * @author [Christopher Quadflieg](https://github.com/Shinigami92)
  * @since 2.0.0
  */
@@ -2300,8 +2321,8 @@ declare class ClusterWorker<Data = unknown, Response = unknown> extends Abstract
  *
  * If you use a `DynamicThreadPool` the extra workers that were created will be terminated,
  * but the minimum number of workers will be guaranteed.
- * @typeParam Data - Type of data this worker receives from pool's execution. This can only be structured-cloneable data.
- * @typeParam Response - Type of response the worker sends back to the main thread. This can only be structured-cloneable data.
+ * @template Data - Type of data this worker receives from pool's execution. This can only be structured-cloneable data.
+ * @template Response - Type of response the worker sends back to the main thread. This can only be structured-cloneable data.
  * @author [Alessandro Pio Ardizio](https://github.com/pioardi)
  * @since 0.0.1
  */