poolifier 5.1.7 → 5.3.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> {
@@ -585,8 +599,10 @@ declare class PriorityQueue<T> {
      * @param enablePriority - Whether to enable priority.
      */
     set enablePriority(enablePriority: boolean);
+    private readonly agingFactor;
     private readonly bucketSize;
     private head;
+    private readonly loadExponent;
     private priorityEnabled;
     private tail;
     /**
@@ -595,9 +611,13 @@ declare class PriorityQueue<T> {
      * @defaultValue defaultBucketSize
      * @param enablePriority - Whether to enable priority.
      * @defaultValue false
+     * @param agingFactor - Aging factor for priority boosting (priority points per millisecond).
+     * @defaultValue defaultAgingFactor
+     * @param loadExponent - Load exponent for aging adjustment based on queue fill ratio.
+     * @defaultValue defaultLoadExponent
      * @returns PriorityQueue.
      */
-    constructor(bucketSize?: number, enablePriority?: boolean);
+    constructor(bucketSize?: number, enablePriority?: boolean, agingFactor?: number, loadExponent?: number);
     /**
      * Clears the priority queue.
      */
@@ -633,27 +653,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 +803,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 {
@@ -963,8 +983,10 @@ interface WorkerNodeEventDetail {
  */
 interface WorkerNodeOptions {
     env?: Record<string, unknown>;
+    tasksQueueAgingFactor: number | undefined;
     tasksQueueBackPressureSize: number | undefined;
     tasksQueueBucketSize: number | undefined;
+    tasksQueueLoadExponent: number | undefined;
     tasksQueuePriority: boolean | undefined;
     workerOptions?: WorkerOptions$1;
 }
@@ -1024,9 +1046,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 +1233,7 @@ interface PoolInfo {
 }
 /**
  * Options for a poolifier pool.
- * @typeParam Worker - Type of worker.
+ * @template Worker - Type of worker.
  */
 interface PoolOptions<Worker extends IWorker> {
     /**
@@ -1286,11 +1308,21 @@ interface PoolOptions<Worker extends IWorker> {
  * Worker node tasks queue options.
  */
 interface TasksQueueOptions {
+    /**
+     * Controls the priority queue anti-starvation aging rate.
+     * @defaultValue 0.001
+     */
+    readonly agingFactor?: number;
     /**
      * Maximum number of tasks that can be executed concurrently on a worker node.
      * @defaultValue 1
      */
     readonly concurrency?: number;
+    /**
+     * Controls load-based aging adjustment exponent.
+     * @defaultValue 0.667
+     */
+    readonly loadExponent?: number;
     /**
      * Maximum tasks queue size per worker node flagging it as back pressured.
      * @defaultValue (pool maximum size)^2
@@ -1320,9 +1352,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 +1388,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 +1448,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 +1465,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 +1759,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 +1856,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 +1905,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 +1957,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 +2004,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 +2052,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 +2062,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 +2128,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 +2303,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 +2339,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
  */