poolifier 2.1.0 → 2.2.0

package/lib/pools/selection-strategies.d.ts

@@ -1,58 +0,0 @@
-import type { IWorker } from './abstract-pool';
-import type { IPoolInternal } from './pool-internal';
-/**
- * Enumeration of worker choice strategies.
- */
-export declare const WorkerChoiceStrategies: Readonly<{
-    /**
-     * Round robin worker selection strategy.
-     */
-    readonly ROUND_ROBIN: "ROUND_ROBIN";
-    /**
-     * Less recently used worker selection strategy.
-     */
-    readonly LESS_RECENTLY_USED: "LESS_RECENTLY_USED";
-}>;
-/**
- * Worker choice strategy.
- */
-export declare type WorkerChoiceStrategy = keyof typeof WorkerChoiceStrategies;
-/**
- * The worker choice strategy context.
- *
- * @template Worker Type of worker.
- * @template Data Type of data sent to the worker. This can only be serializable data.
- * @template Response Type of response of execution. This can only be serializable data.
- */
-export declare class WorkerChoiceStrategyContext<Worker extends IWorker, Data, Response> {
-    private readonly pool;
-    private createDynamicallyWorkerCallback;
-    private workerChoiceStrategy;
-    /**
-     * Worker choice strategy context constructor.
-     *
-     * @param pool The pool instance.
-     * @param createDynamicallyWorkerCallback The worker creation callback for dynamic pool.
-     * @param workerChoiceStrategy The worker choice strategy.
-     */
-    constructor(pool: IPoolInternal<Worker, Data, Response>, createDynamicallyWorkerCallback: () => Worker, workerChoiceStrategy?: WorkerChoiceStrategy);
-    /**
-     * Get the worker choice strategy instance specific to the pool type.
-     *
-     * @param workerChoiceStrategy The worker choice strategy.
-     * @returns The worker choice strategy instance for the pool type.
-     */
-    private getPoolWorkerChoiceStrategy;
-    /**
-     * Set the worker choice strategy to use in the context.
-     *
-     * @param workerChoiceStrategy The worker choice strategy to set.
-     */
-    setWorkerChoiceStrategy(workerChoiceStrategy: WorkerChoiceStrategy): void;
-    /**
-     * Choose a worker with the underlying selection strategy.
-     *
-     * @returns The chosen one.
-     */
-    execute(): Worker;
-}

package/lib/pools/thread/dynamic.d.ts

@@ -1,31 +0,0 @@
-import type { PoolOptions } from '../abstract-pool';
-import { PoolType } from '../pool-internal';
-import type { ThreadWorkerWithMessageChannel } from './fixed';
-import { FixedThreadPool } from './fixed';
-/**
- * A thread pool with a dynamic number of threads, but a guaranteed minimum number of threads.
- *
- * 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, an event is emitted. If you want to listen to this event, use the pool's `emitter`.
- *
- * @template DataType of data sent to the worker. This can only be serializable data.
- * @template ResponseType of response of execution. This can only be serializable data.
- * @author [Alessandro Pio Ardizio](https://github.com/pioardi)
- * @since 0.0.1
- */
-export declare class DynamicThreadPool<Data = unknown, Response = unknown> extends FixedThreadPool<Data, Response> {
-    readonly max: number;
-    /**
-     * Constructs a new poolifier dynamic thread pool.
-     *
-     * @param min Minimum number of threads which are always active.
-     * @param max Maximum number of threads that can be created by this pool.
-     * @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?: PoolOptions<ThreadWorkerWithMessageChannel>);
-    /** @inheritdoc */
-    get type(): PoolType;
-    /** @inheritdoc */
-    get busy(): boolean;
-}

package/lib/pools/thread/fixed.d.ts

@@ -1,48 +0,0 @@
-/// <reference types="node" />
-import { MessageChannel, Worker } from 'worker_threads';
-import type { Draft, MessageValue } from '../../utility-types';
-import type { PoolOptions } from '../abstract-pool';
-import { AbstractPool } from '../abstract-pool';
-import { PoolType } from '../pool-internal';
-/**
- * A thread worker with message channels for communication between main thread and thread worker.
- */
-export declare type ThreadWorkerWithMessageChannel = Worker & Draft<MessageChannel>;
-/**
- * A thread pool with a fixed number of threads.
- *
- * It is possible to perform tasks in sync or asynchronous mode as you prefer.
- *
- * This pool selects the threads in a round robin fashion.
- *
- * @template DataType of data sent to the worker. This can only be serializable data.
- * @template ResponseType of response of execution. This can only be serializable data.
- * @author [Alessandro Pio Ardizio](https://github.com/pioardi)
- * @since 0.0.1
- */
-export declare class FixedThreadPool<Data = unknown, Response = unknown> extends AbstractPool<ThreadWorkerWithMessageChannel, Data, Response> {
-    /**
-     * Constructs a new poolifier fixed thread pool.
-     *
-     * @param numberOfThreads Number of threads for this pool.
-     * @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?: PoolOptions<ThreadWorkerWithMessageChannel>);
-    /** @inheritdoc */
-    protected isMain(): boolean;
-    /** @inheritdoc */
-    destroyWorker(worker: ThreadWorkerWithMessageChannel): Promise<void>;
-    /** @inheritdoc */
-    protected sendToWorker(worker: ThreadWorkerWithMessageChannel, message: MessageValue<Data>): void;
-    /** @inheritdoc */
-    registerWorkerMessageListener<Message extends Data | Response>(messageChannel: ThreadWorkerWithMessageChannel, listener: (message: MessageValue<Message>) => void): void;
-    /** @inheritdoc */
-    protected createWorker(): ThreadWorkerWithMessageChannel;
-    /** @inheritdoc */
-    protected afterWorkerSetup(worker: ThreadWorkerWithMessageChannel): void;
-    /** @inheritdoc */
-    get type(): PoolType;
-    /** @inheritdoc */
-    get busy(): boolean;
-}

package/lib/utility-types.d.ts

@@ -1,58 +0,0 @@
-/// <reference types="node" />
-import type { Worker } from 'cluster';
-import type { MessagePort } from 'worker_threads';
-import type { IWorker } from './pools/abstract-pool';
-import type { KillBehavior } from './worker/worker-options';
-/**
- * Make all properties in T non-readonly.
- */
-export declare type Draft<T> = {
-    -readonly [P in keyof T]?: T[P];
-};
-/**
- * Message object that is passed between worker and main worker.
- */
-export interface MessageValue<Data = unknown, MainWorker extends Worker | MessagePort | unknown = unknown> {
-    /**
-     * Input data that will be passed to the worker.
-     */
-    readonly data?: Data;
-    /**
-     * Id of the message.
-     */
-    readonly id?: number;
-    /**
-     * Kill code.
-     */
-    readonly kill?: KillBehavior | 1;
-    /**
-     * Error.
-     */
-    readonly error?: string;
-    /**
-     * Reference to main worker.
-     *
-     * _Only for internal use_
-     */
-    readonly parent?: MainWorker;
-}
-/**
- * An object holding the worker that will be used to resolve/rejects the promise later on.
- *
- * @template Worker Type of worker.
- * @template Response Type of response of execution. This can only be serializable data.
- */
-export interface PromiseWorkerResponseWrapper<Worker extends IWorker, Response = unknown> {
-    /**
-     * Resolve callback to fulfill the promise.
-     */
-    readonly resolve: (value: Response) => void;
-    /**
-     * Reject callback to reject the promise.
-     */
-    readonly reject: (reason?: string) => void;
-    /**
-     * The worker that has the assigned task.
-     */
-    readonly worker: Worker;
-}

package/lib/utils.d.ts

@@ -1,4 +0,0 @@
-/**
- * An intentional empty function.
- */
-export declare const EMPTY_FUNCTION: () => void;

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

@@ -1,79 +0,0 @@
-/// <reference types="node" />
-import { AsyncResource } from 'async_hooks';
-import type { Worker } from 'cluster';
-import type { MessagePort } from 'worker_threads';
-import type { MessageValue } from '../utility-types';
-import type { WorkerOptions } from './worker-options';
-/**
- * Base class containing some shared logic for all poolifier workers.
- *
- * @template MainWorker Type of main worker.
- * @template Data Type of data this worker receives from pool's execution. This can only be serializable data.
- * @template Response Type of response the worker sends back to the main worker. This can only be serializable data.
- */
-export declare abstract class AbstractWorker<MainWorker extends Worker | MessagePort, Data = unknown, Response = unknown> extends AsyncResource {
-    protected mainWorker: MainWorker | null;
-    readonly opts: WorkerOptions;
-    /**
-     * Timestamp of the last task processed by this worker.
-     */
-    protected lastTaskTimestamp: number;
-    /**
-     * Handler Id of the `aliveInterval` worker alive check.
-     */
-    protected readonly aliveInterval?: 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 fn Function processed by the worker when the pool's `execution` function is invoked.
-     * @param mainWorker Reference to main worker.
-     * @param opts Options for the worker.
-     */
-    constructor(type: string, isMain: boolean, fn: (data: Data) => Response, mainWorker: MainWorker | null, opts?: WorkerOptions);
-    private checkWorkerOptions;
-    /**
-     * Check if the `fn` parameter is passed to the constructor.
-     *
-     * @param fn The function that should be defined.
-     */
-    private checkFunctionInput;
-    /**
-     * Returns the main worker.
-     *
-     * @returns Reference to the main worker.
-     */
-    protected getMainWorker(): MainWorker;
-    /**
-     * Send a message to the main worker.
-     *
-     * @param message The response message.
-     */
-    protected abstract sendToMainWorker(message: MessageValue<Response>): void;
-    /**
-     * Check to see if the worker should be terminated, because its living too long.
-     */
-    protected checkAlive(): void;
-    /**
-     * Handle 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 Message of the error.
-     */
-    protected handleError(e: Error | string): string;
-    /**
-     * Run the given function synchronously.
-     *
-     * @param fn Function that will be executed.
-     * @param value Input data for the given function.
-     */
-    protected run(fn: (data?: Data) => Response, value: MessageValue<Data>): void;
-    /**
-     * Run the given function asynchronously.
-     *
-     * @param fn Function that will be executed.
-     * @param value Input data for the given function.
-     */
-    protected runAsync(fn: (data?: Data) => Promise<Response>, value: MessageValue<Data>): void;
-}

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

@@ -1,32 +0,0 @@
-/// <reference types="node" />
-import type { Worker } from 'cluster';
-import type { MessageValue } from '../utility-types';
-import { AbstractWorker } from './abstract-worker';
-import type { WorkerOptions } from './worker-options';
-/**
- * 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.
- *
- * @template DataType of data this worker receives from pool's execution. This can only be serializable data.
- * @template ResponseType of response the worker sends back to the main worker. This can only be serializable 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 fn Function processed by the worker when the pool's `execution` function is invoked.
-     * @param opts Options for the worker.
-     */
-    constructor(fn: (data: Data) => Response, opts?: WorkerOptions);
-    /** @inheritdoc */
-    protected sendToMainWorker(message: MessageValue<Response>): void;
-    /** @inheritdoc */
-    protected handleError(e: Error | string): string;
-}

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

@@ -1,30 +0,0 @@
-/// <reference types="node" />
-import type { MessagePort } from 'worker_threads';
-import type { MessageValue } from '../utility-types';
-import { AbstractWorker } from './abstract-worker';
-import type { WorkerOptions } from './worker-options';
-/**
- * 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.
- *
- * @template DataType of data this worker receives from pool's execution. This can only be serializable data.
- * @template ResponseType of response the worker sends back to the main thread. This can only be serializable 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> {
-    /**
-     * Constructs a new poolifier thread worker.
-     *
-     * @param fn Function processed by the worker when the pool's `execution` function is invoked.
-     * @param opts Options for the worker.
-     */
-    constructor(fn: (data: Data) => Response, opts?: WorkerOptions);
-    /** @inheritdoc */
-    protected sendToMainWorker(message: MessageValue<Response>): void;
-}

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 running, then the worker **wont** be deleted.
-     */
-    readonly SOFT: "SOFT";
-    /**
-     * If `lastActiveTime` is greater than `maxInactiveTime` but a task is still running, then the worker will be deleted.
-     */
-    readonly HARD: "HARD";
-}>;
-/**
- * Kill behavior.
- */
-export declare type KillBehavior = keyof typeof KillBehaviors;
-/**
- * Detects whether the given value is a kill behavior or not.
- *
- * @template KB Which specific KillBehavior to test against.
- * @param killBehavior Which kind of kill behavior to detect.
- * @param value Any value.
- * @returns `true` if `value` was strictly equals to `killBehavior`, otherwise `false`.
- */
-export declare function isKillBehavior<KB extends KillBehavior>(killBehavior: KB, value: unknown): value is KB;
-/**
- * Options for workers.
- */
-export interface WorkerOptions {
-    /**
-     * Maximum waiting time in milliseconds for tasks.
-     *
-     * After this time, newly created workers will be terminated.
-     * The last active time of your worker unit will be updated when a task is submitted to a worker or when a worker terminate 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 and 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.
-     *
-     * @default 60.000 ms
-     */
-    maxInactiveTime?: number;
-    /**
-     * Whether your worker will perform asynchronous or not.
-     *
-     * @default false
-     */
-    async?: boolean;
-    /**
-     * `killBehavior` dictates if your async unit (worker/process) will be deleted in case that a task is active on it.
-     *
-     * - SOFT: If `currentTime - lastActiveTime` is greater than `maxInactiveTime` but a task is still running, then the worker **won't** be deleted.
-     * - HARD: If `lastActiveTime` is greater than `maxInactiveTime` but a task is still running, then the worker will be deleted.
-     *
-     * This option only apply to the newly created workers.
-     *
-     * @default KillBehaviors.SOFT
-     */
-    killBehavior?: KillBehavior;
-}