@elysiumjs/heracles 0.4.4 → 0.5.1

package/dist/queue.d.ts

@@ -0,0 +1,247 @@
+import type { EventHandler } from '@elysiumjs/core';
+import type { JobClass, JobOverlapBehavior } from './job';
+import type { JobStatusInfo, TransportClass, TransportEvent } from './transport';
+import { InteractsWithConsole } from '@elysiumjs/core';
+import { Job, JobStatus } from './job';
+/**
+ * Options for dispatching a job to a queue.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type JobDispatchOptions = {
+    /**
+     * Schedule the job to run at a specific time.
+     */
+    scheduledFor?: Date;
+    /**
+     * Priority of this job (lower number = higher priority).
+     * @default 10
+     */
+    priority?: number;
+    /**
+     * Maximum number of retries for this job.
+     * Overrides both the job class and queue settings.
+     */
+    maxRetries?: number;
+    /**
+     * Delay between retries in milliseconds.
+     * Overrides both the job class and queue settings.
+     */
+    retryDelay?: number;
+    /**
+     * Optional job ID to use for this dispatch.
+     * If not provided, a unique ID will be generated.
+     */
+    jobId?: string;
+    /**
+     * A unique ID for this specific dispatch of the job.
+     * If not provided, one will be generated.
+     */
+    dispatchId?: string;
+    /**
+     * Defines how the job handles overlap with other instances of the same job ID.
+     * Overrides the setting from the job class.
+     */
+    overlapBehavior?: JobOverlapBehavior;
+    /**
+     * When using NO_OVERLAP behavior, specifies the delay in milliseconds
+     * between sequential executions of jobs with the same ID.
+     * Overrides the setting from the job class.
+     */
+    overlapDelay?: number;
+};
+/**
+ * Configuration options for a Queue.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type QueueOptions = {
+    /**
+     * The name of the queue.
+     */
+    name: string;
+    /**
+     * The transport class to use for this queue.
+     */
+    transport: TransportClass;
+    /**
+     * The maximum number of concurrent jobs to process in this queue.
+     * @default 1
+     */
+    concurrency?: number;
+    /**
+     * The maximum number of retries for failed jobs.
+     * @default 0
+     */
+    maxRetries?: number;
+    /**
+     * The delay in milliseconds between retries.
+     * @default 1000
+     */
+    retryDelay?: number;
+    /**
+     * Whether to pause processing when an error occurs.
+     * @default false
+     */
+    pauseOnError?: boolean;
+    /**
+     * Configuration options for the transport.
+     * This is passed to the transport constructor.
+     */
+    transportOptions?: Record<string, any>;
+};
+/**
+ * Generated ID when dispatching jobs in queues.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type JobDispatchId = {
+    /**
+     * The job ID.
+     */
+    jobId: string;
+    /**
+     * The dispatch ID.
+     */
+    dispatchId: string;
+};
+/**
+ * Queue class for dispatching jobs to workers.
+ * @author Axel Nana <axel.nana@icloud.com>
+ */
+export declare class Queue extends InteractsWithConsole {
+    /**
+     * Map of all registered queues.
+     */
+    private static queues;
+    /**
+     * Checks whether a queue exists.
+     * @param name The name of the queue.
+     * @returns `true` if the queue exists, `false` otherwise.
+     */
+    static exists(name: string): boolean;
+    /**
+     * Get a queue by name, or create it if it doesn't exist.
+     *
+     * @param name The name of the queue.
+     * @param config Optional configuration for the queue if it needs to be created.
+     * @returns The queue instance.
+     */
+    static get(name: string, config?: Omit<QueueOptions, 'name'>): Queue;
+    /**
+     * Get all registered queues.
+     *
+     * @returns A map of all registered queues.
+     */
+    static getAll(): Map<string, Queue>;
+    /**
+     * The name of this queue
+     */
+    readonly name: string;
+    /**
+     * The transport used by this queue
+     */
+    private readonly transport;
+    /**
+     * The transport class for this queue.
+     */
+    private transportClass?;
+    /**
+     * The transport options for this queue. These are passed to the transport constructor.
+     */
+    private transportOptions?;
+    /**
+     * The queue configuration options.
+     */
+    private options;
+    /**
+     * Array of job IDs currently being processed
+     */
+    private jobs;
+    /**
+     * Creates a new Queue instance.
+     *
+     * @param config The queue configuration.
+     */
+    private constructor();
+    on<TData, TSource = any>(event: TransportEvent['type'], handler: EventHandler<TData, TSource> | never): void;
+    once<TData, TSource = any>(event: TransportEvent['type'], handler: EventHandler<TData, TSource> | never): void;
+    private emit;
+    /**
+     * Handle messages from the transport
+     *
+     * @param message The message from the transport
+     */
+    private handleTransportMessage;
+    /**
+     * Update the status of a job.
+     *
+     * @param jobId The ID of the job.
+     * @param dispatchID The dispatch ID of the job.
+     * @param status The new status information.
+     */
+    private updateJobStatus;
+    /**
+     * Dispatch a job to this queue
+     *
+     * @param name The name of the job to dispatch
+     * @param args The arguments to pass to the job constructor
+     * @param options Optional dispatch options
+     * @returns A promise that resolves to the created job instance
+     */
+    dispatch<T extends Job, TClass extends JobClass<T> = JobClass<T>>(job: TClass, name: string, args?: ConstructorParameters<TClass>, options?: JobDispatchOptions): Promise<JobDispatchId>;
+    /**
+     * Cancel a job in this queue.
+     *
+     * @param id The ID of the dispatched job to cancel.
+     * @returns A promise that resolves to true if the job was found and canceled.
+     */
+    cancelJob(id: JobDispatchId): Promise<boolean>;
+    /**
+     * Cancel all jobs in this queue.
+     *
+     * @returns A promise that resolves to the number of jobs canceled.
+     */
+    cancelAllJobs(): Promise<number>;
+    /**
+     * Get the status of a job.
+     *
+     * @param id The ID of the job.
+     * @returns A promise that resolves to the job status or null if not found
+     */
+    getJobStatus(id: JobDispatchId): Promise<JobStatusInfo | null>;
+    /**
+     * Get all jobs in this queue
+     *
+     * @returns An array of job IDs
+     */
+    getAllJobs(): Array<JobDispatchId>;
+    /**
+     * Get jobs by status
+     *
+     * @param status The status to filter by
+     * @returns An array of jobs with the specified status
+     */
+    getJobsByStatus(status: JobStatus): Promise<JobDispatchId[]>;
+    /**
+     * Start the queue's transport.
+     *
+     * @returns A promise that resolves when the transport has started.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the queue's transport.
+     *
+     * @returns A promise that resolves when the transport has stopped.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the queue options.
+     *
+     * @returns The queue options.
+     */
+    getOptions(): QueueOptions;
+    /**
+     * Update the queue options.
+     *
+     * @param options The new options
+     */
+    updateOptions(options: Partial<QueueOptions>): void;
+}

package/dist/transport.d.ts

@@ -0,0 +1,427 @@
+import type { JobDispatchOptions } from './queue';
+/**
+ * Discriminated union of all events carried by a transport channel.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TransportEvent = TransportProcessMessage | TransportCancelMessage | TransportCancelAllMessage | TransportJobStatusMessage | TransportWorkerStatusMessage | TransportJobResultMessage | TransportWorkerRegistrationMessage | TransportWorkerReadyMessage | TransportJobUpdateMessage;
+/**
+ * Message sent to process a job.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TransportProcessMessage = {
+    /**
+     * The type of message.
+     */
+    type: 'job:process';
+    /**
+     * The name of the job to process. It should match the name of the job class,
+     * or the alias in the Service container.
+     */
+    job: string;
+    /**
+     * Arguments to pass to the job constructor.
+     */
+    args: unknown[];
+    /**
+     * The name of the queue to process the job.
+     */
+    queue: string;
+    /**
+     * The ID of the job.
+     * When creating a new job, this will be generated if not provided.
+     */
+    jobId: string;
+    /**
+     * The dispatch ID of the job.
+     * This is unique for each dispatch, even if the job ID is the same.
+     */
+    dispatchId: string;
+    /**
+     * Optional job dispatch configuration.
+     * Note: scheduledFor is transmitted as ISO string instead of Date object.
+     */
+    options?: Omit<JobDispatchOptions, 'scheduledFor'> & {
+        /**
+         * When the job should be scheduled to run (ISO string).
+         */
+        scheduledFor?: string;
+    };
+};
+/**
+ * Message sent to cancel a job (by ID).
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TransportCancelMessage = {
+    /**
+     * The type of message.
+     */
+    type: 'job:cancel';
+    /**
+     * The ID of the job to cancel.
+     */
+    jobId: string;
+    /**
+     * The ID of the dispatch.
+     */
+    dispatchId: string;
+    /**
+     * The name of the queue where the job is located.
+     */
+    queue: string;
+};
+/**
+ * Message sent to cancel all jobs.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TransportCancelAllMessage = {
+    /**
+     * The type of message.
+     */
+    type: 'job:cancelAll';
+    /**
+     * The name of the queue to cancel all jobs in.
+     */
+    queue: string;
+};
+/**
+ * Message with job status information.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TransportJobStatusMessage = {
+    /**
+     * The type of message.
+     */
+    type: 'job:status';
+    /**
+     * The ID of the job.
+     */
+    jobId: string;
+    /**
+     * The ID of the dispatch that created the job.
+     */
+    dispatchId: string;
+    /**
+     * The name of the queue the job belongs to.
+     */
+    queue: string;
+    /**
+     * The current status of the job.
+     */
+    status: string;
+    /**
+     * The error message if the job failed.
+     */
+    error?: string;
+    /**
+     * The number of retries attempted.
+     */
+    retries?: number;
+    /**
+     * Timestamp when the job started.
+     */
+    startedAt?: string;
+    /**
+     * Timestamp when the job completed or failed.
+     */
+    completedAt?: string;
+    /**
+     * Timestamp when this status update was created.
+     */
+    updatedAt?: string;
+    /**
+     * Timestamp when the job was created.
+     */
+    createdAt?: string;
+};
+/**
+ * Message with worker status information.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TransportWorkerStatusMessage = {
+    /**
+     * The type of message.
+     */
+    type: 'worker:status';
+    /**
+     * The ID of the worker.
+     */
+    workerId: string;
+    /**
+     * The queues this worker is handling.
+     */
+    queues: string[];
+    /**
+     * The current status of the worker.
+     */
+    status: 'active' | 'paused' | 'draining' | 'stopped';
+    /**
+     * The number of jobs currently being processed by this worker.
+     */
+    processing: number;
+    /**
+     * The number of jobs waiting in this worker's queues.
+     */
+    waiting: number;
+};
+/**
+ * Message with job results.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TransportJobResultMessage = {
+    /**
+     * The type of message.
+     */
+    type: 'job:result';
+    /**
+     * The ID of the job.
+     */
+    jobId: string;
+    /**
+     * The ID of the dispatch that created the job.
+     */
+    dispatchId: string;
+    /**
+     * The name of the queue the job belongs to.
+     */
+    queue: string;
+    /**
+     * The final status of the job.
+     */
+    status: string;
+    /**
+     * The error message if the job failed.
+     */
+    error?: string;
+    /**
+     * Timestamp when the job completed or failed.
+     */
+    completedAt: string;
+    /**
+     * Timestamp when this update was created.
+     */
+    updatedAt?: string;
+    /**
+     * The number of retries that were attempted.
+     */
+    retries?: number;
+};
+/**
+ * Message for worker registration.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TransportWorkerRegistrationMessage = {
+    /**
+     * The type of message.
+     */
+    type: 'worker:register' | 'worker:unregister';
+    /**
+     * The ID of the worker.
+     */
+    workerId: string;
+    /**
+     * The queues the worker handles (for registration).
+     */
+    queues?: string[];
+};
+/**
+ * Message indicating a worker is ready.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TransportWorkerReadyMessage = {
+    /**
+     * The type of message.
+     */
+    type: 'worker:ready';
+    /**
+     * The ID of the worker.
+     */
+    id: string;
+    /**
+     * The queues the worker handles.
+     */
+    queues: string[];
+    /**
+     * The timestamp when the worker became ready.
+     */
+    timestamp?: number;
+    /**
+     * The worker status.
+     */
+    status?: string;
+};
+/**
+ * Job status information.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface JobStatusInfo {
+    /**
+     * The ID of the job.
+     */
+    jobId: string;
+    /**
+     * The dispatch ID of the job.
+     * This uniquely identifies a specific dispatch of a job, even if the job ID is the same.
+     */
+    dispatchId: string;
+    /**
+     * The name of the queue the job belongs to.
+     */
+    queue: string;
+    /**
+     * The current status of the job.
+     */
+    status: string;
+    /**
+     * The error message if the job failed.
+     */
+    error?: string;
+    /**
+     * The number of retries attempted.
+     */
+    retries: number;
+    /**
+     * Timestamp when the job was created.
+     */
+    createdAt: string;
+    /**
+     * Timestamp when the job started.
+     */
+    startedAt?: string;
+    /**
+     * Timestamp when the job completed or failed.
+     */
+    completedAt?: string;
+    /**
+     * Timestamp when this status was last updated.
+     */
+    updatedAt?: string;
+    /**
+     * The original message ID in the Redis stream (internal use).
+     */
+    messageId?: string;
+}
+/**
+ * Indicates what mode a Transport is operating in.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare enum TransportMode {
+    /**
+     * Listens for jobs/events from the transport (e.g., worker).
+     */
+    CONSUMER = "consumer",
+    /**
+     * Actively pushes jobs/events to the transport (e.g., dispatcher).
+     */
+    PRODUCER = "producer"
+}
+/**
+ * Message specific to job status updates.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TransportJobUpdateMessage = {
+    /**
+     * The type of message.
+     */
+    type: 'job:update';
+    /**
+     * The ID of the job.
+     */
+    jobId: string;
+    /**
+     * The ID of the dispatch.
+     */
+    dispatchId: string;
+    /**
+     * The name of the queue the job belongs to.
+     */
+    queue: string;
+    /**
+     * The current status of the job.
+     */
+    status: string;
+    /**
+     * Updates to the job status fields.
+     */
+    updates: Partial<JobStatusInfo>;
+    /**
+     * Whether to create a new entry if the job doesn't exist.
+     */
+    createIfNotExist?: boolean;
+};
+/**
+ * Interface for any transport layer that delivers job events between queue and worker.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface Transport {
+    /**
+     * Starts the transport.
+     *
+     * This method should initialize the transport and mark it as ready to receive messages.
+     */
+    start(): Promise<void> | void;
+    /**
+     * Stops the transport.
+     *
+     * This method should stop the transport and mark it as stopped.
+     */
+    stop(): Promise<void> | void;
+    /**
+     * Sends a message over the transport.
+     *
+     * @param message The message to send.
+     * @returns A promise that resolves when the message has been sent.
+     */
+    send(message: TransportEvent): Promise<void> | void;
+    /**
+     * Registers a callback for receiving messages from the transport.
+     *
+     * @param handler The handler function to call when a message is received.
+     */
+    onMessage(handler: (message: TransportEvent) => void | Promise<void>): void;
+    /**
+     * Gets the current status of a job.
+     *
+     * @param jobId The ID of the job to get the status for.
+     * @param dispatchId The ID generated for the dispatch of the job.
+     * @param queueName The name of the queue the job belongs to.
+     * @returns A promise that resolves with the current job status.
+     */
+    getJobStatus(jobId: string, dispatchId: string, queueName: string): Promise<JobStatusInfo>;
+    /**
+     * Registers a worker with the transport.
+     *
+     * @param workerId The ID of the worker.
+     * @param queues The queues the worker handles.
+     * @returns A promise that resolves when the worker is registered.
+     */
+    registerWorker(workerId: string, queues: string[]): Promise<void>;
+    /**
+     * Unregisters a worker from the transport.
+     *
+     * @param workerId The ID of the worker to unregister.
+     * @returns A promise that resolves when the worker is unregistered.
+     */
+    unregisterWorker(workerId: string): Promise<void>;
+    /**
+     * Updates a job status directly without creating a new message.
+     *
+     * @param jobId The ID of the job to update.
+     * @param queueName The name of the queue the job belongs to.
+     * @param updates The status updates to apply.
+     * @returns A promise that resolves when the job is updated.
+     */
+    updateJobStatus(jobId: string, dispatchId: string, queueName: string, updates: Partial<JobStatusInfo>): Promise<void>;
+}
+/**
+ * Type signature for a transport constructor.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TransportClass<T extends Transport = Transport> = {
+    /**
+     * Creates a new transport instance.
+     *
+     * @param mode The mode of the transport (consumer or producer).
+     * @param options The options to pass to the transport.
+     */
+    new (mode: TransportMode, options?: Record<string, any>): T;
+};