queue-jobs-worker 1.0.0

package/dist/core/backoff.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Backoff strategies
+ *
+ * Calculates the delay (in ms) before a failed job is re-queued.
+ *
+ * - fixed       — always uses `baseDelay`
+ * - linear      — baseDelay × attemptNumber
+ * - exponential — baseDelay × 2^(attemptNumber - 1), capped at MAX_DELAY
+ */
+import type { BackoffStrategy } from "../types/job.types.js";
+/**
+ * Returns the retry delay in milliseconds for the given attempt.
+ *
+ * @param strategy    - Backoff strategy name.
+ * @param baseDelay   - Base delay in ms (from job / queue / client config).
+ * @param attemptNumber - The 1-based attempt number that just failed.
+ */
+export declare function calculateBackoff(strategy: BackoffStrategy, baseDelay: number, attemptNumber: number): number;
+/**
+ * Returns the ISO timestamp at which a job should next become eligible,
+ * given the current time and the calculated delay.
+ */
+export declare function nextRunAt(delayMs: number, fromDate?: Date): string;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/core/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/core/backoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAK7D;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,MAAM,CAuBR;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,IAAiB,GAAG,MAAM,CAE9E"}

package/dist/core/client.d.ts

@@ -0,0 +1,93 @@
+/**
+ * QueueClient
+ *
+ * Primary entry point for the queue-jobs-worker package.
+ *
+ * Usage:
+ *
+ *   // In-memory (dev / tests)
+ *   const client = new QueueClient();
+ *   // init() is optional for "memory" but always safe to call
+ *
+ *   // Redis
+ *   const client = new QueueClient({ dialect: "redis", connectionString: "redis://localhost:6379" });
+ *   await client.init();   // connects, pings Redis
+ *
+ *   // PostgreSQL
+ *   const client = new QueueClient({ dialect: "postgres", connectionString: "postgresql://..." });
+ *   await client.init();   // connects, auto-creates qjw_ tables if missing
+ *
+ *   // MySQL
+ *   const client = new QueueClient({ dialect: "mysql", connectionString: "mysql://..." });
+ *   await client.init();   // connects, auto-creates qjw_ tables if missing
+ */
+import type { QueueClientOptions } from "../types/client.types.js";
+import type { QueueOptions } from "../types/queue.types.js";
+import type { StorageAdapter } from "../types/storage.types.js";
+import type { QueueEvents } from "../types/events.types.js";
+import { Queue } from "./queue.js";
+export declare class QueueClient {
+    /** @internal — mutable so withAdapter() can replace it */
+    _storage: StorageAdapter;
+    private readonly emitter;
+    private readonly defaults;
+    private readonly dialect;
+    private readonly connectionString;
+    private readonly queues;
+    private initialised;
+    private closed;
+    constructor(options?: QueueClientOptions);
+    private buildMemoryOrEagerAdapter;
+    /**
+     * Initialise the client and storage adapter.
+     *
+     * **Must be called** before creating queues when using Redis, PostgreSQL,
+     * or MySQL.
+     *
+     * What each adapter does:
+     *  - **memory**   — no-op (always safe to call)
+     *  - **redis**    — connects, sends PING, verifies PONG
+     *  - **postgres** — connects, runs `SELECT 1`, auto-creates `qjw_` tables
+     *  - **mysql**    — connects, runs `SELECT 1`, auto-creates `qjw_` tables
+     *
+     * Idempotent — safe to call multiple times.
+     */
+    init(): Promise<void>;
+    /** @deprecated Use `init()`. */
+    initialize(): Promise<void>;
+    private resolveAdapter;
+    /**
+     * Create a named queue with optional per-queue configuration.
+     *
+     * For external dialects (redis/postgres/mysql), call `await client.init()`
+     * first.
+     */
+    createQueue<TPayload = unknown>(name: string, options?: QueueOptions): Queue<TPayload>;
+    /** Returns the queue with the given name, or `undefined`. */
+    getQueue<TPayload = unknown>(name: string): Queue<TPayload> | undefined;
+    /** Returns the queue with the given name, or throws. */
+    requireQueue<TPayload = unknown>(name: string): Queue<TPayload>;
+    /** Names of all queues registered on this client. */
+    get queueNames(): string[];
+    /** `true` after `init()` has completed successfully. */
+    get isInitialised(): boolean;
+    on<K extends keyof QueueEvents>(event: K, listener: (...args: QueueEvents[K]) => void): this;
+    once<K extends keyof QueueEvents>(event: K, listener: (...args: QueueEvents[K]) => void): this;
+    off<K extends keyof QueueEvents>(event: K, listener: (...args: QueueEvents[K]) => void): this;
+    /**
+     * Stop all workers, close all queues, and release the storage connection.
+     * Safe to call multiple times.
+     */
+    close(): Promise<void>;
+    /**
+     * Create a QueueClient with a fully custom StorageAdapter.
+     *
+     * `init()` will call `adapter.initialize()`.
+     *
+     * @example
+     * const client = QueueClient.withAdapter(myAdapter);
+     * await client.init();
+     */
+    static withAdapter(adapter: StorageAdapter, options?: Omit<QueueClientOptions, "dialect" | "connectionString">): QueueClient;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/core/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAwBnC,qBAAa,WAAW;IACtB,0DAA0D;IAC1D,QAAQ,EAAE,cAAc,CAAC;IAEzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,GAAE,kBAAuB;IAe5C,OAAO,CAAC,yBAAyB;IAajC;;;;;;;;;;;;;OAaG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B,gCAAgC;IAC1B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAInB,cAAc;IAkC5B;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC;IAgBtF,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,SAAS;IAIvE,wDAAwD;IACxD,YAAY,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC;IAQ/D,qDAAqD;IACrD,IAAI,UAAU,IAAI,MAAM,EAAE,CAEzB;IAED,wDAAwD;IACxD,IAAI,aAAa,IAAI,OAAO,CAE3B;IAMD,EAAE,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAK5F,IAAI,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAK9F,GAAG,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAS7F;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;;;;;;;OAQG;IACH,MAAM,CAAC,WAAW,CAChB,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,kBAAkB,CAAM,GACrE,WAAW;CAKf"}

package/dist/core/id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Job ID generation
+ *
+ * Uses the built-in `crypto.randomUUID()` available in Node.js >= 14.17.
+ * No external dependency needed.
+ */
+/** Generate a new unique job ID. */
+export declare function generateJobId(): string;
+//# sourceMappingURL=id.d.ts.map

package/dist/core/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/core/id.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,oCAAoC;AACpC,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/core/index.d.ts

@@ -0,0 +1,7 @@
+export { Job } from "./job.js";
+export { Queue } from "./queue.js";
+export { Worker } from "./worker.js";
+export { QueueClient } from "./client.js";
+export { calculateBackoff, nextRunAt } from "./backoff.js";
+export { generateJobId } from "./id.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/core/job.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Job
+ *
+ * A rich wrapper around the raw JobData record stored in the storage layer.
+ * Exposes read-only accessors for all fields and a small set of helpers used
+ * by Queue and Worker internals.
+ *
+ * The Job instance is passed directly to user-supplied Processor functions.
+ * Users should never mutate the internal data object — all mutations happen
+ * through the storage adapter.
+ */
+import type { JobData, JobStatus, JobAttempt, BackoffStrategy } from "../types/job.types.js";
+export declare class Job<TPayload = unknown> {
+    /** @internal Raw data record — treat as immutable outside storage layer. */
+    readonly _data: JobData<TPayload>;
+    constructor(data: JobData<TPayload>);
+    /** Unique, stable job identifier. */
+    get id(): string;
+    /** Name of the queue this job belongs to. */
+    get queue(): string;
+    /** Application-defined job type (matches the registered processor). */
+    get type(): string;
+    /**
+     * User-supplied job payload.
+     * Never log this value — it may contain sensitive data.
+     */
+    get data(): TPayload;
+    /** Current lifecycle status. */
+    get status(): JobStatus;
+    /** Number of attempts already executed (0 = not yet started). */
+    get attemptsMade(): number;
+    /** Maximum allowed attempts. */
+    get maxAttempts(): number;
+    /** How many attempts remain (including the current one). */
+    get attemptsRemaining(): number;
+    /** Ordered list of past attempt records. */
+    get attemptHistory(): readonly JobAttempt[];
+    /** Base delay in ms between retry attempts. */
+    get retryDelay(): number;
+    /** Backoff strategy applied on retry. */
+    get backoff(): BackoffStrategy;
+    /** Per-attempt timeout in ms. */
+    get timeout(): number;
+    /** Processing priority — higher numbers are processed first. */
+    get priority(): number;
+    /** ISO timestamp when this job is eligible to run. */
+    get runAt(): string;
+    /** Cron expression for recurring jobs, or undefined. */
+    get cron(): string | undefined;
+    /** ID of the worker currently holding the lock, or null. */
+    get lockId(): string | null;
+    /** ISO timestamp when the current lock expires, or null. */
+    get lockExpiresAt(): string | null;
+    /** ISO timestamp when the job was first enqueued. */
+    get createdAt(): string;
+    /** ISO timestamp of the last status change. */
+    get updatedAt(): string;
+    /** ISO timestamp when the job completed successfully, or null. */
+    get completedAt(): string | null;
+    /** ISO timestamp when the job was moved to the DLQ, or null. */
+    get failedAt(): string | null;
+    /** Returns true when the job has been successfully processed. */
+    isCompleted(): boolean;
+    /** Returns true when the job is in the Dead Letter Queue. */
+    isDead(): boolean;
+    /** Returns true when the job is currently being processed by a worker. */
+    isActive(): boolean;
+    /** Returns true when the job is waiting to be claimed. */
+    isWaiting(): boolean;
+    /** Returns true when the job is scheduled for a future time. */
+    isDelayed(): boolean;
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+}
+//# sourceMappingURL=job.d.ts.map

package/dist/core/job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../../src/core/job.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7F,qBAAa,GAAG,CAAC,QAAQ,GAAG,OAAO;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAEtB,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC;IAQnC,qCAAqC;IACrC,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,6CAA6C;IAC7C,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,uEAAuE;IACvE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAMD;;;OAGG;IACH,IAAI,IAAI,IAAI,QAAQ,CAEnB;IAMD,gCAAgC;IAChC,IAAI,MAAM,IAAI,SAAS,CAEtB;IAED,iEAAiE;IACjE,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,gCAAgC;IAChC,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,4DAA4D;IAC5D,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,4CAA4C;IAC5C,IAAI,cAAc,IAAI,SAAS,UAAU,EAAE,CAE1C;IAMD,+CAA+C;IAC/C,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,yCAAyC;IACzC,IAAI,OAAO,IAAI,eAAe,CAE7B;IAMD,iCAAiC;IACjC,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,gEAAgE;IAChE,IAAI,QAAQ,IAAI,MAAM,CAErB;IAMD,sDAAsD;IACtD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,wDAAwD;IACxD,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IAMD,4DAA4D;IAC5D,IAAI,MAAM,IAAI,MAAM,GAAG,IAAI,CAE1B;IAED,4DAA4D;IAC5D,IAAI,aAAa,IAAI,MAAM,GAAG,IAAI,CAEjC;IAMD,qDAAqD;IACrD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,+CAA+C;IAC/C,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,kEAAkE;IAClE,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IAED,gEAAgE;IAChE,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IAMD,iEAAiE;IACjE,WAAW,IAAI,OAAO;IAItB,6DAA6D;IAC7D,MAAM,IAAI,OAAO;IAIjB,0EAA0E;IAC1E,QAAQ,IAAI,OAAO;IAInB,0DAA0D;IAC1D,SAAS,IAAI,OAAO;IAIpB,gEAAgE;IAChE,SAAS,IAAI,OAAO;IAQpB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAkBjC,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/core/queue.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Queue
+ *
+ * Represents an independent stream of jobs.  Applications use a Queue to:
+ *  - Enqueue jobs (with optional scheduling, priority, retry config).
+ *  - Register processors for job types.
+ *  - Create workers that consume jobs from this queue.
+ *  - Query job state and counts.
+ *
+ * Queue-level configuration overrides client defaults.
+ * Job-level options override queue configuration where applicable.
+ */
+import type { StorageAdapter } from "../types/storage.types.js";
+import type { JobOptions, JobStatus } from "../types/job.types.js";
+import type { QueueOptions } from "../types/queue.types.js";
+import type { WorkerOptions, Processor } from "../types/worker.types.js";
+import type { ClientDefaults } from "../types/client.types.js";
+import { Job } from "./job.js";
+import { Worker } from "./worker.js";
+import type { QueueEventEmitter } from "../events/emitter.js";
+type ResolvedDefaults = Required<ClientDefaults>;
+export declare class Queue<TPayload = unknown> {
+    /** The name of this queue — unique within a QueueClient. */
+    readonly name: string;
+    private readonly storage;
+    private readonly emitter;
+    private readonly resolvedConfig;
+    private readonly clientDefaults;
+    /** Registered processors keyed by job type. */
+    private readonly processors;
+    /** Active worker instances created by this queue. */
+    private readonly workers;
+    constructor(name: string, storage: StorageAdapter, emitter: QueueEventEmitter, options: QueueOptions | undefined, defaults: ResolvedDefaults);
+    /**
+     * Add a new job to the queue.
+     *
+     * @param type    - Job type string, must match a registered processor.
+     * @param payload - Arbitrary serialisable payload (never logged by default).
+     * @param options - Per-job overrides (attempts, delay, priority, etc.).
+     */
+    enqueue(type: string, payload: TPayload, options?: JobOptions): Promise<Job<TPayload>>;
+    /**
+     * Register a processor function for a given job type.
+     *
+     * Only one processor per type per queue is supported.
+     * Registering a second processor for the same type replaces the first.
+     */
+    process<P = TPayload>(type: string, processor: Processor<P>): void;
+    /**
+     * Create and start a Worker that consumes jobs from this queue.
+     *
+     * Worker-level `concurrency` overrides queue-level concurrency.
+     */
+    createWorker(options?: WorkerOptions): Worker;
+    /** Fetch a single job by its ID. Returns null if not found or wrong queue. */
+    getJob(jobId: string): Promise<Job<TPayload> | null>;
+    /** Fetch jobs from this queue, optionally filtered by status. */
+    getJobs(status?: JobStatus, limit?: number, offset?: number): Promise<Job<TPayload>[]>;
+    /** Get job counts by status for this queue. */
+    getJobCounts(): Promise<Record<JobStatus, number>>;
+    /**
+     * Gracefully stop all workers attached to this queue.
+     * Called automatically by QueueClient.close().
+     */
+    close(): Promise<void>;
+    /** Return all active worker instances on this queue. */
+    getWorkers(): readonly Worker[];
+}
+export {};
+//# sourceMappingURL=queue.d.ts.map

package/dist/core/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/core/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,KAAK,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;AA2BjD,qBAAa,KAAK,CAAC,QAAQ,GAAG,OAAO;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmB;IAElD,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyC;IAEpE,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;gBAGtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,QAAQ,EAAE,gBAAgB;IAa5B;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAqC5F;;;;;OAKG;IACH,OAAO,CAAC,CAAC,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAQlE;;;;OAIG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM;IAoB7C,8EAA8E;IACxE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAM1D,iEAAiE;IAC3D,OAAO,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,KAAK,SAAM,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;IAUpF,+CAA+C;IACzC,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAQxD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,wDAAwD;IACxD,UAAU,IAAI,SAAS,MAAM,EAAE;CAGhC"}

package/dist/core/worker.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Worker
+ *
+ * Claims jobs from a queue and executes registered processors concurrently.
+ *
+ * Key guarantees:
+ *  - At-most `concurrency` jobs run simultaneously.
+ *  - Job claiming is delegated to the storage adapter's atomic `claim()` call.
+ *  - Failed jobs are requeued (with backoff) or moved to the DLQ.
+ *  - Stalled jobs (expired locks from crashed workers) are recovered
+ *    periodically.
+ *  - Graceful shutdown: stop claiming, wait for active jobs, release any
+ *    locks that could not be finished within shutdownTimeout.
+ *  - Cron jobs: re-enqueued immediately after each successful execution.
+ */
+import type { StorageAdapter } from "../types/storage.types.js";
+import type { WorkerOptions, WorkerStatus, Processor } from "../types/worker.types.js";
+import type { QueueOptions } from "../types/queue.types.js";
+import type { ClientDefaults } from "../types/client.types.js";
+import type { QueueEventEmitter } from "../events/emitter.js";
+type ResolvedDefaults = Required<ClientDefaults>;
+export declare class Worker {
+    /** Unique identifier for this worker instance. */
+    readonly id: string;
+    private readonly queueName;
+    private readonly storage;
+    private readonly emitter;
+    private readonly processors;
+    private readonly config;
+    private _status;
+    private activeCount;
+    /**
+     * Tracks job IDs currently being processed so we can release their locks
+     * when graceful shutdown times out before they finish.
+     */
+    private readonly activeJobIds;
+    private pollTimer;
+    private stalledTimer;
+    /** Resolves when all active jobs finish during shutdown. */
+    private drainResolve;
+    constructor(queueName: string, storage: StorageAdapter, emitter: QueueEventEmitter, processors: Map<string, Processor<unknown>>, workerOptions: WorkerOptions, queueOptions: QueueOptions, defaults: ResolvedDefaults);
+    get status(): WorkerStatus;
+    /** Start polling for jobs. */
+    start(): void;
+    /**
+     * Gracefully stop the worker.
+     *
+     * 1. Stop accepting new jobs.
+     * 2. Wait up to `shutdownTimeout` ms for active jobs to finish.
+     * 3. Release locks on any jobs that did not finish in time so another
+     *    worker can reclaim them.
+     * 4. Emit stopped event.
+     */
+    stop(): Promise<void>;
+    private schedulePoll;
+    private poll;
+    private claimNext;
+    private executeJob;
+    private enqueueCronNext;
+    private handleFailure;
+    private scheduleStallCheck;
+    private recoverStalledJobs;
+}
+export {};
+//# sourceMappingURL=worker.d.ts.map

package/dist/core/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/core/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,KAAK,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;AAyBjD,qBAAa,MAAM;IACjB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAE1D,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,WAAW,CAAK;IAExB;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAElD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,YAAY,CAA+B;IAEnD,4DAA4D;IAC5D,OAAO,CAAC,YAAY,CAA6B;gBAG/C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,EAC3C,aAAa,EAAE,aAAa,EAC5B,YAAY,EAAE,YAAY,EAC1B,QAAQ,EAAE,gBAAgB;IAc5B,IAAI,MAAM,IAAI,YAAY,CAEzB;IAED,8BAA8B;IAC9B,KAAK,IAAI,IAAI;IAab;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiD3B,OAAO,CAAC,YAAY;YAQN,IAAI;YAsBJ,SAAS;YAiCT,UAAU;YAwDV,eAAe;YAwDf,aAAa;IA0C3B,OAAO,CAAC,kBAAkB;YAQZ,kBAAkB;CAkBjC"}

package/dist/events/emitter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * QueueEventEmitter
+ *
+ * A strongly-typed, lightweight event emitter built on top of Node.js
+ * EventEmitter.  All queue/worker/job lifecycle events flow through here.
+ *
+ * Using typed generics ensures that each event name maps to its exact
+ * argument tuple — no runtime guessing.
+ */
+import type { QueueEvents } from "../types/events.types.js";
+type EventKey = keyof QueueEvents;
+type EventArgs<K extends EventKey> = QueueEvents[K];
+export declare class QueueEventEmitter {
+    private readonly emitter;
+    constructor();
+    on<K extends EventKey>(event: K, listener: (...args: EventArgs<K>) => void): this;
+    once<K extends EventKey>(event: K, listener: (...args: EventArgs<K>) => void): this;
+    off<K extends EventKey>(event: K, listener: (...args: EventArgs<K>) => void): this;
+    emit<K extends EventKey>(event: K, ...args: EventArgs<K>): boolean;
+    removeAllListeners(event?: EventKey): this;
+    listenerCount(event: EventKey): number;
+}
+export {};
+//# sourceMappingURL=emitter.d.ts.map

package/dist/events/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../src/events/emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAM5D,KAAK,QAAQ,GAAG,MAAM,WAAW,CAAC;AAClC,KAAK,SAAS,CAAC,CAAC,SAAS,QAAQ,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;AAEpD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;;IAavC,EAAE,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAKjF,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAKnF,GAAG,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IASlF,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO;IAQlE,kBAAkB,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,IAAI;IAS1C,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM;CAGvC"}