queue-jobs-worker 1.0.5 → 2.0.0

package/dist/index.d.ts

@@ -1,39 +1,556 @@
+import { EventEmitter } from 'node:events';
+
 /**
- * queue-jobs-worker
+ * All possible lifecycle states a job can be in.
  *
- * Reliable job queue and background worker system for Node.js.
+ * waiting   — Job has been added to the queue and is waiting to be picked up.
+ * delayed   — Job is scheduled to run in the future (delay or cron).
+ * active    — Job is currently being processed by a worker.
+ * completed — Job finished successfully.
+ * failed    — Job exhausted all retry attempts and is permanently failed.
+ * retrying  — Job failed once but still has remaining attempts; waiting for next retry.
+ */
+type JobStatus = "waiting" | "delayed" | "active" | "completed" | "failed" | "retrying";
+/**
+ * Options you can pass when adding a job to the queue.
+ *
+ * @property attempts   - Max retry attempts for this specific job (overrides queue default).
+ * @property delay      - Milliseconds to wait before the job becomes eligible to run.
+ * @property priority   - Lower number = higher priority (default: 0).
+ * @property jobId      - Custom job ID. Auto-generated (crypto UUID) if not provided.
+ * @property cron       - A cron expression to schedule the job on a recurring schedule.
+ *                        Uses the `croner` library syntax, e.g. "0 * * * *" (every hour).
+ * @property removeOnComplete - Auto-remove the job from storage after it completes.
+ * @property removeOnFail     - Auto-remove the job from storage after it permanently fails.
+ */
+interface JobOptions {
+    attempts?: number;
+    delay?: number;
+    priority?: number;
+    jobId?: string;
+    cron?: string;
+    removeOnComplete?: boolean;
+    removeOnFail?: boolean;
+}
+/**
+ * The full job record stored in the queue.
+ *
+ * @property id          - Unique identifier (UUID v4 via node:crypto).
+ * @property name        - Logical job name, e.g. "send-welcome-email".
+ * @property data        - Arbitrary payload passed to the worker handler.
+ * @property status      - Current lifecycle state.
+ * @property opts        - Original options this job was created with.
+ * @property attempts    - Max number of attempts allowed.
+ * @property attemptsMade - Number of attempts that have been made so far.
+ * @property delay       - Milliseconds to wait before first run.
+ * @property runAt       - Absolute timestamp (ms) when the job becomes eligible.
+ * @property priority    - Scheduling priority; lower = runs first.
+ * @property cron        - Cron expression for recurring jobs.
+ * @property result      - Return value from the handler on success.
+ * @property error       - Error message from the last failed attempt.
+ * @property stacktrace  - Error stack trace from the last failed attempt.
+ * @property createdAt   - Unix timestamp (ms) when the job was created.
+ * @property updatedAt   - Unix timestamp (ms) of the last status change.
+ * @property processedAt - Unix timestamp (ms) when processing started.
+ * @property finishedAt  - Unix timestamp (ms) when the job completed or permanently failed.
+ */
+interface Job<TData = unknown, TResult = unknown> {
+    id: string;
+    name: string;
+    data: TData;
+    status: JobStatus;
+    opts: JobOptions;
+    attempts: number;
+    attemptsMade: number;
+    delay: number;
+    runAt: number;
+    priority: number;
+    cron?: string;
+    result?: TResult;
+    error?: string;
+    stacktrace?: string;
+    createdAt: number;
+    updatedAt: number;
+    processedAt?: number;
+    finishedAt?: number;
+}
+
+/**
+ * Every storage backend must implement this interface.
+ * The Queue and Worker classes talk exclusively to this contract —
+ * they never know whether the data is in a Map, Redis, Postgres, or MySQL.
+ */
+interface IStorage {
+    /**
+     * Open the connection / initialise the storage.
+     * Called once by QueueClient.init().
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the connection and release all resources.
+     * Called once by QueueClient.close().
+     */
+    disconnect(): Promise<void>;
+    /** Persist a new job. */
+    saveJob<TData = unknown, TResult = unknown>(queueName: string, job: Job<TData, TResult>): Promise<void>;
+    /** Fetch a single job by its ID. Returns undefined if not found. */
+    getJob<TData = unknown, TResult = unknown>(queueName: string, jobId: string): Promise<Job<TData, TResult> | undefined>;
+    /** Update an existing job (partial or full). */
+    updateJob<TData = unknown, TResult = unknown>(queueName: string, jobId: string, patch: Partial<Job<TData, TResult>>): Promise<void>;
+    /** Permanently remove a job from storage. */
+    removeJob(queueName: string, jobId: string): Promise<void>;
+    /**
+     * Return all jobs for a queue, optionally filtered by status.
+     * Results are sorted: lower priority number first, then older createdAt first.
+     */
+    listJobs<TData = unknown, TResult = unknown>(queueName: string, status?: JobStatus): Promise<Job<TData, TResult>[]>;
+    /**
+     * Pick the next job that is eligible to run right now.
+     *
+     * Eligibility rules:
+     *  - status === "waiting" AND runAt <= Date.now()
+     *  - OR status === "retrying" AND runAt <= Date.now()
+     *
+     * Returns undefined when the queue has nothing ready.
+     */
+    getNextJob<TData = unknown, TResult = unknown>(queueName: string): Promise<Job<TData, TResult> | undefined>;
+    /** Remove every job in a queue. */
+    clearQueue(queueName: string): Promise<void>;
+    /** Return the total number of jobs in a queue (all statuses). */
+    countJobs(queueName: string): Promise<number>;
+}
+
+/**
+ * The storage backend to use.
+ *
+ * - memory   — In-process Map; no external dependencies. Good for dev and testing.
+ * - redis    — Redis via the `redis` npm package (peer dependency).
+ * - postgres — PostgreSQL via the `pg` npm package (peer dependency).
+ * - mysql    — MySQL/MariaDB via the `mysql2` npm package (peer dependency).
+ */
+type StorageDialect = "memory" | "redis" | "mysql" | "postgres";
+/**
+ * The retry backoff strategy applied between successive attempts.
+ *
+ * - fixed       — Always wait `retryDelay` ms.
+ * - linear      — Wait `retryDelay * attemptNumber` ms.
+ * - exponential — Wait `retryDelay * 2^(attemptNumber - 1)` ms.
+ */
+type BackoffStrategy = "fixed" | "linear" | "exponential";
+/**
+ * Global defaults applied to every job unless overridden at the queue or job level.
+ *
+ * @property attempts    - Max retry attempts per job (0 = unlimited). Default: 3.
+ * @property retryDelay  - Base delay in ms before the first retry. Default: 1000.
+ * @property backoff     - Backoff strategy. Default: "exponential".
+ * @property timeout     - Max ms a job can run before being marked failed. Default: 30000.
+ */
+interface QueueClientConfigOptions {
+    attempts?: number;
+    retryDelay?: number;
+    backoff?: BackoffStrategy;
+    timeout?: number;
+}
+/**
+ * Options passed to `new QueueClient(...)`.
+ *
+ * @property dialect          - Which storage backend to use.
+ * @property connectionString - DSN/URL for Redis, PostgreSQL, or MySQL.
+ *                              Not required for `memory` dialect.
+ * @property debug            - When true, the client logs internal operations to console.
+ * @property options          - Global job execution defaults.
+ */
+interface QueueClientOptions {
+    dialect: StorageDialect;
+    connectionString?: string;
+    debug?: boolean;
+    options?: QueueClientConfigOptions;
+}
+type storageDialect = StorageDialect;
+type rateLimitOptions = RateLimitOptions;
+/**
+ * Rate-limiting configuration for a queue.
+ *
+ * @property max      - Maximum number of jobs to start within the `duration` window.
+ * @property duration - Length of the rate-limit window in milliseconds.
+ */
+interface RateLimitOptions {
+    max: number;
+    duration: number;
+}
+
+/**
+ * QueueClient — the entry point for the entire queue system.
+ *
+ * Every Queue and Worker you create is tied to a QueueClient instance.
+ * One client holds one storage connection and one set of global defaults.
+ *
+ * Typical usage
+ * ─────────────
+ * // 1. Create and initialise the client (do this once at app startup)
+ * const client = new QueueClient({ dialect: "memory" });
+ * await client.init();
  *
- * Quick start:
+ * // 2. Create queues and workers … (see Queue / Worker docs)
+ *
+ * // 3. Gracefully shut everything down (call on app exit / SIGTERM)
+ * await client.close();
+ *
+ * Singleton default client
+ * ────────────────────────
+ * The first client you call .init() on is automatically stored as the
+ * process-wide default.  Any Queue or Worker constructed without an explicit
+ * client argument will pick it up automatically.
+ *
+ * You can also set the default explicitly:
+ *   QueueClient.setDefaultClient(client);
+ */
+declare class QueueClient {
+    private static _default;
+    private readonly _dialect;
+    private readonly _connectionString?;
+    private readonly _debug;
+    private readonly _config;
+    private _storage;
+    private _initialized;
+    private _closed;
+    constructor(opts: QueueClientOptions);
+    /**
+     * Open the storage connection and mark this client as ready.
+     *
+     * Must be called before creating any Queue or Worker.
+     * Calling init() more than once throws to prevent accidental double-init.
+     *
+     * @returns `this` so you can chain:  await new QueueClient(…).init()
+     */
+    init(): Promise<this>;
+    /**
+     * Close the storage connection and release all resources.
+     *
+     * Call this on application shutdown (e.g. SIGTERM handler, NestJS onModuleDestroy,
+     * Express app.close()).  Any in-flight worker processing will finish its current
+     * job before the worker's own close() stops the polling loop.
+     */
+    close(): Promise<void>;
+    /** Returns the process-wide default client, or undefined if none is set. */
+    static getDefaultClient(): QueueClient | undefined;
+    /**
+     * Explicitly set (or replace) the process-wide default client.
+     * Useful in tests or multi-client setups.
+     */
+    static setDefaultClient(client: QueueClient): void;
+    /** Clear the default client reference (useful between tests). */
+    static clearDefaultClient(): void;
+    /** True after init() succeeds and before close() is called. */
+    isInitialized(): boolean;
+    /** True after close() has been called. */
+    isClosed(): boolean;
+    /** The merged global job execution defaults. */
+    getConfig(): Required<QueueClientConfigOptions>;
+    /** The storage dialect this client was created with. */
+    getDialect(): StorageDialect;
+    /** The connection string (may be undefined for the memory dialect). */
+    getConnectionString(): string | undefined;
+    /** Whether debug logging is enabled. */
+    isDebugMode(): boolean;
+    /**
+     * The underlying IStorage instance.
+     *
+     * Exposed so Queue / Worker can call storage methods directly.
+     * Throws if the client has not been initialized yet.
+     *
+     * @internal
+     */
+    getStorage(): IStorage;
+    /**
+     * Write a debug-mode log line.
+     *
+     * FIX: the old signature accepted `...args: unknown[]` which let callers
+     * accidentally spread raw objects into the console output, potentially
+     * leaking internal state (job payloads, connection strings, stack traces)
+     * into log aggregators.  The new signature accepts only a pre-formatted
+     * string so callers must stringify anything sensitive before passing it.
+     *
+     * @internal
+     */
+    _log(message: string): void;
+}
+
+/**
+ * Options for `new Queue(name, client, options)`.
+ *
+ * Queue is a pure producer — it only manages job storage.
+ * Concurrency, polling, and execution belong to the Worker.
+ *
+ * @property rateLimit      - Optional rate-limit config (max jobs per duration).
+ * @property defaultJobOpts - Per-queue job defaults (override client-level defaults).
+ */
+interface QueueOptions {
+    rateLimit?: RateLimitOptions;
+    defaultJobOpts?: {
+        attempts?: number;
+        delay?: number;
+        priority?: number;
+        removeOnComplete?: boolean;
+        removeOnFail?: boolean;
+    };
+}
+/**
+ * Options for `new Worker(queue, handler, options)`.
+ *
+ * Worker is a pure consumer — it only processes jobs from a Queue.
+ *
+ * @property concurrency  - Max parallel jobs. Default: 1.
+ * @property pollInterval - Ms between queue polls when idle. Default: 500.
+ */
+interface WorkerOptions {
+    concurrency?: number;
+    pollInterval?: number;
+}
+
+/**
+ * Queue — pure job producer.
+ *
+ * Responsible for one thing: managing a named collection of jobs in storage.
+ * It does not poll, process, or execute anything. A Worker consumes from it.
+ *
+ * Usage
+ * ─────
+ * const client = new QueueClient({ dialect: "redis", connectionString: "…" });
+ * await client.init();
+ *
+ * const queue = new Queue("emails", client);
+ *
+ * // Add jobs
+ * const job = await queue.add("welcome", { to: "user@example.com" });
+ * await queue.add("reminder", { userId: 42 }, { delay: 60_000 });
+ * await queue.add("report",   {},             { cron: "0 9 * * *" });
+ *
+ * // Inspect
+ * const job  = await queue.get(id);
+ * const all  = await queue.list();
+ * const n    = await queue.count();
+ *
+ * // Remove
+ * await queue.remove(id);
+ * await queue.clear();
+ */
+declare class Queue<TData = unknown, TResult = unknown> {
+    readonly name: string;
+    readonly client: QueueClient;
+    readonly options: Required<QueueOptions>;
+    /** Active croner handles keyed by jobId — used to cancel scheduled jobs. */
+    private readonly _cronHandles;
+    /** Workers attached to this queue — auto-closed when queue.close() is called. */
+    private readonly _workers;
+    /** Guards against double-close. */
+    private _closed;
+    constructor(name: string, client?: QueueClient, options?: QueueOptions);
+    private get storage();
+    /**
+     * Add a job to the queue.
+     *
+     * The job is immediately persisted to storage with status `"waiting"`.
+     * Cron jobs start as `"delayed"` and are moved to `"waiting"` on each tick.
+     *
+     * @param name - Job type identifier, e.g. `"send-welcome-email"`.
+     * @param data - Arbitrary payload forwarded to the Worker handler.
+     * @param opts - Per-job overrides for attempts, delay, priority, cron, etc.
+     * @returns    The fully populated Job record (with auto-generated UUID id).
+     */
+    add(name: string, data: TData, opts?: JobOptions): Promise<Job<TData, TResult>>;
+    /**
+     * Fetch a single job by ID.
+     * Returns `undefined` when the job does not exist or has been removed.
+     */
+    get(jobId: string): Promise<Job<TData, TResult> | undefined>;
+    /**
+     * Permanently remove a job from the queue.
+     * If the job has an active cron schedule, it is also cancelled.
+     */
+    remove(jobId: string): Promise<void>;
+    /**
+     * List jobs, optionally filtered by status.
+     * Results are sorted: priority ASC, createdAt ASC.
+     *
+     * @param status - `"waiting" | "delayed" | "active" | "completed" | "failed" | "retrying"`
+     */
+    list(status?: JobStatus): Promise<Job<TData, TResult>[]>;
+    /**
+     * Remove every job in this queue (all statuses).
+     * All active cron schedules for this queue are also cancelled.
+     */
+    clear(): Promise<void>;
+    /**
+     * Return the total number of jobs in this queue (all statuses combined).
+     */
+    count(): Promise<number>;
+    /**
+     * Gracefully shut down everything tied to this queue.
+     *
+     * In order:
+     * 1. Stop all Workers that were created from this queue (waits for
+     *    in-flight jobs to finish before each worker resolves).
+     * 2. Cancel all active cron schedules.
+     *
+     * Idempotent — safe to call multiple times.
+     * You do NOT need to call worker.close() separately — this handles it.
+     */
+    close(): Promise<void>;
+    /**
+     * Register a Worker so it is auto-closed when queue.close() is called.
+     * @internal
+     */
+    _registerWorker(worker: {
+        close(): Promise<void>;
+    }): void;
+    /**
+     * Remove a Worker from the auto-close registry (called by worker.close()).
+     * @internal
+     */
+    _unregisterWorker(worker: {
+        close(): Promise<void>;
+    }): void;
+    /**
+     * Atomically claim the next eligible job.
+     * Eligibility: `status IN ('waiting','retrying') AND runAt <= now`.
+     * Returns `undefined` when nothing is ready.
+     * @internal
+     */
+    _nextJob(): Promise<Job<TData, TResult> | undefined>;
+    /**
+     * Persist a partial status update to a job.
+     * @internal
+     */
+    _updateJob(jobId: string, patch: Partial<Job<TData, TResult>>): Promise<void>;
+    private _scheduleCron;
+    private _cancelCron;
+}
+
+/**
+ * The function you write to process a single job.
+ *
+ * - Return any value — it is stored in `job.result` on success.
+ * - Throw any error — the Worker handles retries, backoff, and status updates.
+ */
+type WorkerHandler<TData = unknown, TResult = unknown> = (job: Job<TData, TResult>) => TResult | Promise<TResult>;
+/**
+ * Typed events emitted by a Worker instance.
+ */
+interface WorkerEvents<TData, TResult> {
+    /** A job has been picked up and is now processing. */
+    active: [job: Job<TData, TResult>];
+    /** A job finished successfully. result is the handler's return value. */
+    completed: [job: Job<TData, TResult>, result: TResult];
+    /** One attempt failed — job may still retry. */
+    error: [job: Job<TData, TResult>, error: Error];
+    /** All attempts exhausted — job is permanently failed. */
+    failed: [job: Job<TData, TResult>, error: Error];
+    /** Polling loop started. */
+    started: [];
+    /** Polling loop stopped and all in-flight jobs drained. */
+    stopped: [];
+}
+/**
+ * Worker — pure job consumer.
  *
- *   import { QueueClient } from "queue-jobs-worker";
+ * A Worker takes a Queue and a handler function. It polls the Queue for
+ * eligible jobs, executes them through the handler, and manages the full
+ * job lifecycle: status transitions, timeouts, retries, backoff, and events.
  *
- *   // In-memory (dev / tests)
- *   const client = new QueueClient();
+ * It does NOT add, list, or remove jobs — those operations belong on Queue.
  *
- *   // Redis
- *   const client = new QueueClient({ dialect: "redis", connectionString: "redis://localhost:6379" });
- *   await client.init();
+ * Usage
+ * ─────
+ * const queue  = new Queue("emails", client);
+ * const worker = new Worker(queue, async (job) => {
+ *   await sendEmail(job.data);
+ * });
  *
- *   // PostgreSQL
- *   const client = new QueueClient({ dialect: "postgres", connectionString: "postgresql://..." });
- *   await client.init();
+ * worker.start();
  *
- *   // MySQL
- *   const client = new QueueClient({ dialect: "mysql", connectionString: "mysql://..." });
- *   await client.init();
+ * // Lifecycle events
+ * worker.on("completed", (job, result) => console.log(job.id, result));
+ * worker.on("failed",    (job, err)    => console.error(job.id, err));
  *
- * @module queue-jobs-worker
+ * // Graceful shutdown — waits for in-flight jobs before resolving
+ * await worker.close();
  */
-export { QueueClient } from "./core/client.js";
-export { Queue } from "./core/queue.js";
-export { Job } from "./core/job.js";
-export { Worker } from "./core/worker.js";
-export { InMemoryStorageAdapter } from "./storage/in-memory.adapter.js";
-export { RedisStorageAdapter } from "./storage/redis.adapter.js";
-export { PostgreSQLStorageAdapter } from "./storage/postgres.adapter.js";
-export { MySQLStorageAdapter } from "./storage/mysql.adapter.js";
-export { QueueEventEmitter } from "./events/emitter.js";
-export { calculateBackoff, nextRunAt } from "./core/backoff.js";
-export { generateJobId } from "./core/id.js";
-export type { JobStatus, JobAttempt, JobSchedule, JobOptions, BackoffStrategy, JobData, RateLimitOptions, QueueOptions, Processor, WorkerOptions, WorkerStatus, StorageAdapter, EnqueueInput, ClaimInput, ClaimResult, RequeueInput, MoveToDlqInput, GetJobsFilter, StorageDialect, ClientDefaults, QueueClientOptions, QueueEvents, } from "./types/index.js";
-//# sourceMappingURL=index.d.ts.map
+declare class Worker<TData = unknown, TResult = unknown> extends EventEmitter {
+    /** The Queue this worker consumes from. Read-only after construction. */
+    readonly queue: Queue<TData, TResult>;
+    private readonly handler;
+    private readonly concurrency;
+    private readonly pollInterval;
+    private running;
+    private _closed;
+    private loopTimer;
+    private activeCount;
+    /**
+     * @param queue   - The Queue to consume jobs from.
+     * @param handler - Async function that processes one job at a time.
+     * @param options - `concurrency` (default 1) and `pollInterval` ms (default 500).
+     */
+    constructor(queue: Queue<TData, TResult>, handler: WorkerHandler<TData, TResult>, options?: WorkerOptions);
+    /**
+     * Start the polling loop.
+     * Calling start() on an already-running worker is a no-op.
+     * Calling start() after close() throws — create a new Worker instead.
+     */
+    start(): this;
+    /**
+     * Gracefully stop the worker.
+     *
+     * - No new jobs are picked up after this call.
+     * - Already in-flight jobs are allowed to finish.
+     * - Resolves once the poll loop has stopped and active count reaches 0.
+     *
+     * Safe to call even if start() was never called.
+     */
+    close(): Promise<void>;
+    /** `true` while the polling loop is active. */
+    isRunning(): boolean;
+    /** `true` after close() has been called. */
+    isClosed(): boolean;
+    on<K extends keyof WorkerEvents<TData, TResult>>(event: K, listener: (...args: WorkerEvents<TData, TResult>[K]) => void): this;
+    once<K extends keyof WorkerEvents<TData, TResult>>(event: K, listener: (...args: WorkerEvents<TData, TResult>[K]) => void): this;
+    /**
+     * FIX: Override emit() to guard against ERR_UNHANDLED_ERROR only when no
+     * real "error" listener is registered. This avoids the blank-listener
+     * anti-pattern that would have swallowed errors in tests / callers that DO
+     * register their own listener (since all listeners are always called).
+     */
+    emit<K extends keyof WorkerEvents<TData, TResult>>(event: K, ...args: WorkerEvents<TData, TResult>[K]): boolean;
+    private scheduleLoop;
+    /**
+     * One iteration of the poll loop.
+     * Starts as many jobs as concurrency allows, then returns.
+     */
+    private tick;
+    private processJob;
+    /**
+     * Race the handler against a hard timeout.
+     * FIX: clear the deadline timer when the handler wins the race — without
+     * this, the setTimeout handle keeps the event loop alive and Node.js will
+     * not exit cleanly in tests or short-lived scripts.
+     */
+    private runWithTimeout;
+    /** Decide between a retry and a permanent failure. */
+    private handleFailure;
+    /**
+     * Calculate the delay before the next retry.
+     *
+     * fixed       → base
+     * linear      → base × attemptsMade
+     * exponential → base × 2^(attemptsMade − 1)   capped at 30 min
+     */
+    private calcBackoff;
+    /** Poll every 50 ms until no jobs are actively processing, with a 30 s safety timeout. */
+    private drainActive;
+    private get client();
+    private _log;
+}
+
+declare const VERSION = "2.0.0";
+
+export { type BackoffStrategy, type IStorage, type Job, type JobOptions, type JobStatus, Queue, QueueClient, type QueueClientConfigOptions, type QueueClientOptions, type QueueOptions, type RateLimitOptions, type StorageDialect, VERSION, Worker, type WorkerEvents, type WorkerHandler, type WorkerOptions, type rateLimitOptions, type storageDialect };