mq-flow/dist/index.d.mts

A lightweight, simple queue system designed for small tasks that need to be executed in a queued manner

import { EventEmitter } from 'stream';

/**
 * Enum representing the priority of a process in the queue.
 *
 * @enum {number}
 */
declare enum Priority {
    /** High priority process. Tasks with HIGH priority are placed at the front of the queue. */
    HIGH = 1,
    /** Low priority process. Tasks with LOW priority are placed at the back of the queue. */
    LOW = 0
}

/**
 * Type definition for a process in the queue.
 */
type Process = {
    /**
     * The asynchronous function to be executed when the process is processed by the queue.
     */
    CallableFunction: () => Promise<any>;
    /**
     * An optional unique identifier for the process.
     * If not provided, it is auto-generated based on the queue length.
     */
    ProcessId?: string | number;
};
/**
 * Type definition for the return value of push and pop operations.
 */
type PushPopReturnType = {
    /** The unique identifier of the process added to or removed from the queue. */
    ProcessId?: string | number;
    /** The updated length of the queue after the operation. */
    QueueLength: number;
};
/**
 * Type definition for the result of a process execution.
 */
type Result = {
    /** The value returned by the executed process. */
    value: any;
    /** The unique identifier of the process that was executed. */
    processId: string | number;
    /** The updated length of the queue after the process execution. */
    queueLength: number;
};
/**
 * Type definition for options when adding a process to the queue.
 */
type Options = {
    /**
     * The priority of the process.
     * Can be HIGH (1) or LOW (0). Defaults to LOW if not provided.
     */
    Priority?: number | Priority;
    /**
     * An optional unique identifier for the process.
     * If not provided, it is auto-generated based on the queue length.
     */
    ProcessId?: string | number;
};

/**
 * Queue Class
 *
 * A lightweight, efficient, and event-driven queue implementation for managing and executing asynchronous processes.
 * Built for Node.js environments, this class uses a FIFO (First-In-First-Out) mechanism with support for priority
 * processing, dynamic addition/removal of tasks, and real-time event notifications.
 *
 * Features:
 * - Push processes with priority handling (HIGH or LOW).
 * - Dynamically remove or pop processes from the queue.
 * - Start and stop the queue processing.
 * - Event-driven mechanism to retrieve process results.
 *
 * Dependencies:
 * - Uses Node.js `EventEmitter` for event-based operations.
 *
 * Usage:
 * ```javascript
 * import { Queue } from './queue';
 *
 * const queue = new Queue();
 *
 * // Push a process
 * queue.mqPush(async () => {
 *   // Some asynchronous operation
 * }, { ProcessId: 'task1', Priority: Priority.HIGH });
 *
 * // Start the queue processing
 * queue.mqStart();
 *
 * // Listen for results
 * queue.on('getResult', (result) => {
 *   console.log(result);
 * });
 * ```
 */
declare class Queue extends EventEmitter {
    #private;
    CurrentProcessId: string | number | null;
    /**
    * Adds a new process to the queue with an optional priority.
    * If the queue is already processing, it starts processing the new process immediately.
    *
    * @param {() => Promise<any>} Process - The asynchronous function to be executed.
    * @param {Options} [Options] - Additional options for the process:
    *   - ProcessId: A unique identifier for the process.
    *   - Priority: Priority of the process (HIGH (1) or LOW (0)).
    *
    * @returns {PushPopReturnType} An object containing the ProcessId and the updated QueueLength.
    *
    * @throws {Error} If an invalid priority is provided.
    */
    mqPush(Process: () => Promise<any>, Options?: Options): PushPopReturnType;
    /**
     * Removes the last process from the queue.
     *
     * @returns {PushPopReturnType} An object containing the ProcessId of the removed process and the updated QueueLength.
     *
     * @throws {Error} If the queue is empty or if the last process is currently under execution.
     */
    mqPop(): PushPopReturnType;
    /**
     * Removes a specific process from the queue by its ProcessId.
     *
     * @param {string | number} ProcessId - The unique identifier of the process to be removed.
     *
     * @returns {PushPopReturnType} An object containing the ProcessId of the removed process and the updated QueueLength.
     *
     * @throws {Error} If the queue is empty or if the specified process is currently under execution.
     */
    mqRemove(ProcessId: string | number): PushPopReturnType;
    /**
     * Starts processing the queue.
     * Processes are executed sequentially in the order they are added unless a higher priority is specified.
     */
    mqStart(): void;
    /**
     * Stops processing the queue.
     * This does not clear the queue, and processes can resume when `mqStart()` is called again.
     */
    mqEnd(): void;
    /**
     * Retrieves the ProcessId of the process currently being executed.
     *
     * @returns {string | number | null} The ProcessId of the current process, or null if no process is under execution.
     */
    getCurrentProcessId(): string | number | null;
    /**
     * Gets the current length of the queue.
     *
     * @returns {number} The number of processes currently in the queue.
     */
    getQueueLength(): number;
}

export { type Options, type Process, type PushPopReturnType, Queue, type Result };