poolifier 2.6.37 → 2.6.38

package/lib/worker/abstract-worker.d.ts

@@ -1,192 +0,0 @@
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-import { AsyncResource } from 'node:async_hooks';
-import type { Worker } from 'node:cluster';
-import type { MessagePort } from 'node:worker_threads';
-import type { MessageValue, Task, WorkerStatistics } from '../utility-types';
-import { type WorkerOptions } from './worker-options';
-import type { TaskAsyncFunction, TaskFunction, TaskFunctions, TaskSyncFunction } from './task-functions';
-/**
- * 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.
- */
-export declare abstract class AbstractWorker<MainWorker extends Worker | MessagePort, Data = unknown, Response = unknown> extends AsyncResource {
-    protected readonly isMain: boolean;
-    private readonly mainWorker;
-    protected opts: WorkerOptions;
-    /**
-     * Worker id.
-     */
-    protected abstract id: number;
-    /**
-     * Task function(s) processed by the worker when the pool's `execution` function is invoked.
-     */
-    protected taskFunctions: Map<string, TaskFunction<Data, Response>>;
-    /**
-     * Timestamp of the last task processed by this worker.
-     */
-    protected lastTaskTimestamp: number;
-    /**
-     * Performance statistics computation requirements.
-     */
-    protected statistics: WorkerStatistics;
-    /**
-     * Handler id of the `activeInterval` worker activity check.
-     */
-    protected activeInterval?: NodeJS.Timeout;
-    /**
-     * Constructs a new poolifier worker.
-     *
-     * @param type - The type of async event.
-     * @param isMain - Whether this is the main worker or not.
-     * @param mainWorker - Reference to main worker.
-     * @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(type: string, isMain: boolean, mainWorker: MainWorker, taskFunctions: TaskFunction<Data, Response> | TaskFunctions<Data, Response>, opts?: WorkerOptions);
-    private checkWorkerOptions;
-    private checkValidTaskFunction;
-    /**
-     * Checks if the `taskFunctions` parameter is passed to the constructor.
-     *
-     * @param taskFunctions - The task function(s) parameter that should be checked.
-     */
-    private checkTaskFunctions;
-    /**
-     * Checks if the worker has a task function with the given name.
-     *
-     * @param name - The name of the task function to check.
-     * @returns Whether the worker has a task function with the given name or not.
-     * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `name` parameter is not a string or an empty string.
-     */
-    hasTaskFunction(name: string): boolean;
-    /**
-     * Adds a task function to the worker.
-     * If a task function with the same name already exists, it is replaced.
-     *
-     * @param name - The name of the task function to add.
-     * @param fn - The task function to add.
-     * @returns Whether the task function was added or not.
-     * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `name` parameter is not a string or an empty string.
-     * @throws {@link https://nodejs.org/api/errors.html#class-error} If the `name` parameter is the default task function reserved name.
-     * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `fn` parameter is not a function.
-     */
-    addTaskFunction(name: string, fn: TaskFunction<Data, Response>): boolean;
-    /**
-     * Removes a task function from the worker.
-     *
-     * @param name - The name of the task function to remove.
-     * @returns Whether the task function existed and was removed or not.
-     * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `name` parameter is not a string or an empty string.
-     * @throws {@link https://nodejs.org/api/errors.html#class-error} If the `name` parameter is the default task function reserved name.
-     * @throws {@link https://nodejs.org/api/errors.html#class-error} If the `name` parameter is the task function used as default task function.
-     */
-    removeTaskFunction(name: string): boolean;
-    /**
-     * Lists the names of the worker's task functions.
-     *
-     * @returns The names of the worker's task functions.
-     */
-    listTaskFunctions(): string[];
-    /**
-     * Sets the default task function to use in the worker.
-     *
-     * @param name - The name of the task function to use as default task function.
-     * @returns Whether the default task function was set or not.
-     * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `name` parameter is not a string or an empty string.
-     * @throws {@link https://nodejs.org/api/errors.html#class-error} If the `name` parameter is the default task function reserved name.
-     * @throws {@link https://nodejs.org/api/errors.html#class-error} If the `name` parameter is a non-existing task function.
-     */
-    setDefaultTaskFunction(name: string): boolean;
-    private checkTaskFunctionName;
-    /**
-     * Handles the ready message sent by the main worker.
-     *
-     * @param message - The ready message.
-     */
-    protected abstract handleReadyMessage(message: MessageValue<Data>): void;
-    /**
-     * Worker message listener.
-     *
-     * @param message - The received message.
-     */
-    protected messageListener(message: MessageValue<Data>): void;
-    /**
-     * Handles a kill message sent by the main worker.
-     *
-     * @param message - The kill message.
-     */
-    protected handleKillMessage(message: MessageValue<Data>): void;
-    /**
-     * Check if the message worker id is set and matches the worker id.
-     *
-     * @param message - The message to check.
-     * @throws {@link https://nodejs.org/api/errors.html#class-error} If the message worker id is not set or does not match the worker id.
-     */
-    private checkMessageWorkerId;
-    /**
-     * Starts the worker check active interval.
-     */
-    private startCheckActive;
-    /**
-     * Stops the worker check active interval.
-     */
-    private stopCheckActive;
-    /**
-     * Checks if the worker should be terminated, because its living too long.
-     */
-    private checkActive;
-    /**
-     * Returns the main worker.
-     *
-     * @returns Reference to the main worker.
-     */
-    protected getMainWorker(): MainWorker;
-    /**
-     * Sends a message to main worker.
-     *
-     * @param message - The response message.
-     */
-    protected abstract sendToMainWorker(message: MessageValue<Response, Data>): void;
-    /**
-     * Sends the list of task function names to the main worker.
-     */
-    protected sendTaskFunctionsListToMainWorker(): void;
-    /**
-     * Handles an error and convert it to a string so it can be sent back to the main worker.
-     *
-     * @param e - The error raised by the worker.
-     * @returns The error message.
-     */
-    protected handleError(e: Error | string): string;
-    /**
-     * Runs the given task.
-     *
-     * @param task - The task to execute.
-     * @throws {@link https://nodejs.org/api/errors.html#class-error} If the task function is not found.
-     */
-    protected run(task: Task<Data>): void;
-    /**
-     * Runs the given task function synchronously.
-     *
-     * @param fn - Task function that will be executed.
-     * @param task - Input data for the task function.
-     */
-    protected runSync(fn: TaskSyncFunction<Data, Response>, task: Task<Data>): void;
-    /**
-     * Runs the given task function asynchronously.
-     *
-     * @param fn - Task function that will be executed.
-     * @param task - Input data for the task function.
-     */
-    protected runAsync(fn: TaskAsyncFunction<Data, Response>, task: Task<Data>): void;
-    private beginTaskPerformance;
-    private endTaskPerformance;
-    private checkStatistics;
-    private updateLastTaskTimestamp;
-}

package/lib/worker/cluster-worker.d.ts

@@ -1,35 +0,0 @@
-/// <reference types="node" />
-import { type Worker } from 'node:cluster';
-import type { MessageValue } from '../utility-types';
-import { AbstractWorker } from './abstract-worker';
-import type { WorkerOptions } from './worker-options';
-import type { TaskFunction, TaskFunctions } from './task-functions';
-/**
- * A cluster worker used by a poolifier `ClusterPool`.
- *
- * When this worker is inactive for more than the given `maxInactiveTime`,
- * it will send a termination request to its main worker.
- *
- * 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.
- * @author [Christopher Quadflieg](https://github.com/Shinigami92)
- * @since 2.0.0
- */
-export declare class ClusterWorker<Data = unknown, Response = unknown> extends AbstractWorker<Worker, Data, Response> {
-    /**
-     * Constructs a new poolifier cluster worker.
-     *
-     * @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);
-    /** @inheritDoc */
-    protected handleReadyMessage(message: MessageValue<Data>): void;
-    /** @inheritDoc */
-    protected get id(): number;
-    /** @inheritDoc */
-    protected sendToMainWorker(message: MessageValue<Response>): void;
-}

package/lib/worker/task-functions.d.ts

@@ -1,33 +0,0 @@
-/**
- * Task synchronous function that can be executed.
- *
- * @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.
- */
-export type TaskSyncFunction<Data = unknown, Response = unknown> = (data?: Data) => Response;
-/**
- * Task asynchronous function that can be executed.
- * This function must return a 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.
- */
-export 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.
- */
-export type TaskFunction<Data = unknown, Response = unknown> = TaskSyncFunction<Data, Response> | TaskAsyncFunction<Data, Response>;
-/**
- * Tasks functions that can be executed.
- * This object can contain synchronous or asynchronous functions.
- * The key is the name of the function.
- * The value is the function itself.
- *
- * @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.
- */
-export type TaskFunctions<Data = unknown, Response = unknown> = Record<string, TaskFunction<Data, Response>>;

package/lib/worker/thread-worker.d.ts

@@ -1,43 +0,0 @@
-/// <reference types="node" />
-import { type MessagePort } from 'node:worker_threads';
-import type { MessageValue } from '../utility-types';
-import { AbstractWorker } from './abstract-worker';
-import type { WorkerOptions } from './worker-options';
-import type { TaskFunction, TaskFunctions } from './task-functions';
-/**
- * A thread worker used by a poolifier `ThreadPool`.
- *
- * When this worker is inactive for more than the given `maxInactiveTime`,
- * it will send a termination request to its main thread.
- *
- * 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.
- * @author [Alessandro Pio Ardizio](https://github.com/pioardi)
- * @since 0.0.1
- */
-export declare class ThreadWorker<Data = unknown, Response = unknown> extends AbstractWorker<MessagePort, Data, Response> {
-    /**
-     * Message port used to communicate with the main worker.
-     */
-    private port;
-    /**
-     * Constructs a new poolifier thread worker.
-     *
-     * @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);
-    /** @inheritDoc */
-    protected handleReadyMessage(message: MessageValue<Data>): void;
-    /** @inheritDoc */
-    protected handleKillMessage(message: MessageValue<Data>): void;
-    /** @inheritDoc */
-    protected get id(): number;
-    /** @inheritDoc */
-    protected sendToMainWorker(message: MessageValue<Response>): void;
-    /** @inheritDoc */
-    protected handleError(e: Error | string): string;
-}

package/lib/worker/worker-options.d.ts

@@ -1,61 +0,0 @@
-/**
- * Enumeration of kill behaviors.
- */
-export declare const KillBehaviors: Readonly<{
-    /**
-     * If `currentTime - lastActiveTime` is greater than `maxInactiveTime` but a task is still executing or queued, then the worker **wont** be deleted.
-     */
-    readonly SOFT: "SOFT";
-    /**
-     * If `currentTime - lastActiveTime` is greater than `maxInactiveTime` but a task is still executing or queued, then the worker will be deleted.
-     */
-    readonly HARD: "HARD";
-}>;
-/**
- * Kill behavior.
- */
-export type KillBehavior = keyof typeof KillBehaviors;
-/**
- * Handler called when a worker is killed.
- */
-export type KillHandler = () => void | Promise<void>;
-/**
- * Options for workers.
- */
-export interface WorkerOptions {
-    /**
-     * `killBehavior` dictates if your worker will be deleted in case a task is active on it.
-     *
-     * - SOFT: If `currentTime - lastActiveTime` is greater than `maxInactiveTime` but a task is still executing or queued, then the worker **won't** be deleted.
-     * - HARD: If `currentTime - lastActiveTime` is greater than `maxInactiveTime` but a task is still executing or queued, then the worker will be deleted.
-     *
-     * This option only apply to the newly created workers.
-     *
-     * @defaultValue KillBehaviors.SOFT
-     */
-    killBehavior?: KillBehavior;
-    /**
-     * Maximum waiting time in milliseconds for tasks on newly created workers.
-     *
-     * After this time, newly created workers will be terminated.
-     * The last active time of your worker will be updated when it terminates a task.
-     *
-     * - If `killBehavior` is set to `KillBehaviors.HARD` this value represents also the timeout for the tasks that you submit to the pool,
-     *   when this timeout expires your tasks is interrupted before completion and removed. The worker is killed if is not part of the minimum size of the pool.
-     * - If `killBehavior` is set to `KillBehaviors.SOFT` your tasks have no timeout and your workers will not be terminated until your task is completed.
-     *
-     * @defaultValue 60000
-     */
-    maxInactiveTime?: number;
-    /**
-     * The function to call when a worker is killed.
-     */
-    killHandler?: KillHandler;
-    /**
-     * Whether your worker will perform asynchronous or not.
-     *
-     * @defaultValue false
-     * @deprecated This option will be removed in the next major version.
-     */
-    async?: boolean;
-}