queue-jobs-worker 1.0.0

package/dist/storage/redis.adapter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * RedisStorageAdapter  (node-redis v4/v5)
+ *
+ * Key layout  — prefix: "qjw:"
+ * ─────────────────────────────────────────────────────────────────────────
+ *  qjw:job:{id}                → Hash   — all job fields (flat strings)
+ *  qjw:queue:{name}:waiting    → Sorted Set  score = -priority
+ *                                            (ZPOPMIN → highest priority first)
+ *  qjw:queue:{name}:delayed    → Sorted Set  score = runAt epoch-ms
+ *  qjw:queue:{name}:active     → Set
+ *  qjw:queue:{name}:completed  → Set
+ *  qjw:queue:{name}:dead       → Set
+ *  qjw:rate:{name}             → String  sliding-window counter
+ *  qjw:rate:{name}:ts          → String  window-start epoch-ms
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * Atomic claim
+ * ─────────────────────────────────────────────────────────────────────────
+ *  A Lua script executed by Redis guarantees that two concurrent workers
+ *  cannot claim the same job.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+import type { StorageAdapter } from "../types/storage.types.js";
+import type { EnqueueInput, ClaimInput, RequeueInput, MoveToDlqInput, GetJobsFilter } from "../types/storage.types.js";
+import type { JobData, JobStatus } from "../types/job.types.js";
+export declare class RedisStorageAdapter implements StorageAdapter {
+    private client;
+    private readonly url;
+    constructor(connectionString: string);
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    enqueue<TPayload = unknown>(input: EnqueueInput<TPayload>): Promise<JobData<TPayload>>;
+    claim<TPayload = unknown>(input: ClaimInput): Promise<JobData<TPayload> | null>;
+    complete(jobId: string): Promise<void>;
+    requeue(input: RequeueInput): Promise<void>;
+    moveToDlq(input: MoveToDlqInput): Promise<void>;
+    releaseLock(jobId: string): Promise<void>;
+    recoverStalledJobs(queue: string, now: string): Promise<string[]>;
+    getJob<TPayload = unknown>(jobId: string): Promise<JobData<TPayload> | null>;
+    getJobs<TPayload = unknown>(filter: GetJobsFilter): Promise<JobData<TPayload>[]>;
+    getJobCounts(queue: string): Promise<Record<JobStatus, number>>;
+    checkAndIncrementRateLimit(queue: string, max: number, windowMs: number, now: string): Promise<boolean>;
+}
+//# sourceMappingURL=redis.adapter.d.ts.map

package/dist/storage/redis.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.adapter.d.ts","sourceRoot":"","sources":["../../src/storage/redis.adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACd,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAc,MAAM,uBAAuB,CAAC;AA+I5E,qBAAa,mBAAoB,YAAW,cAAc;IACxD,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,gBAAgB,EAAE,MAAM;IAQ9B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB,OAAO,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAwDtF,KAAK,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAwB/E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBtC,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAuC3C,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAmC/C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYzC,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA+CjE,MAAM,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAM5E,OAAO,CAAC,QAAQ,GAAG,OAAO,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;IAkDhF,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAgB/D,0BAA0B,CAC9B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,OAAO,CAAC;CA2BpB"}

package/dist/types/client.types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Types for QueueClient configuration and supported storage dialects.
+ */
+import type { BackoffStrategy } from "./job.types.js";
+import type { RateLimitOptions } from "./queue.types.js";
+export type StorageDialect = "memory" | "redis" | "postgres" | "mysql";
+export interface ClientDefaults {
+    /** Default max attempts for all queues/jobs. Default: 3. */
+    attempts?: number;
+    /** Default base retry delay in ms. Default: 1 000. */
+    retryDelay?: number;
+    /** Default backoff strategy. Default: "exponential". */
+    backoff?: BackoffStrategy;
+    /** Default per-attempt timeout in ms. Default: 30 000. */
+    timeout?: number;
+    /** Default worker concurrency. Default: 10. */
+    concurrency?: number;
+    /** Default rate limiting. */
+    rateLimit?: RateLimitOptions;
+    /** Default polling interval in ms. Default: 1 000. */
+    pollInterval?: number;
+    /** Default stalled-job check interval in ms. Default: 30 000. */
+    stalledInterval?: number;
+    /** Default lock duration in ms. Default: 60 000. */
+    lockDuration?: number;
+}
+export interface QueueClientOptions {
+    /**
+     * Storage backend to use.
+     * Default: "memory" (in-process, non-persistent — for development/testing).
+     */
+    dialect?: StorageDialect;
+    /**
+     * Connection string for the selected storage backend.
+     * Not required for the "memory" dialect.
+     */
+    connectionString?: string;
+    /** Global defaults applied to all queues and workers. */
+    defaults?: ClientDefaults;
+}
+//# sourceMappingURL=client.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.types.d.ts","sourceRoot":"","sources":["../../src/types/client.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMzD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC;AAMvE,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,wDAAwD;IACxD,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAE7B,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,yDAAyD;IACzD,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B"}

package/dist/types/events.types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * All event names and their payload types for QueueEventEmitter.
+ */
+import type { JobData } from "./job.types.js";
+import type { WorkerStatus } from "./worker.types.js";
+export interface QueueEvents<TPayload = unknown> {
+    "job:enqueued": [job: JobData<TPayload>];
+    "job:started": [job: JobData<TPayload>];
+    "job:completed": [job: JobData<TPayload>];
+    "job:failed": [job: JobData<TPayload>, error: Error];
+    "job:retrying": [job: JobData<TPayload>, error: Error, nextRunAt: string];
+    "job:dead": [job: JobData<TPayload>, error: Error];
+    "job:stalled": [jobId: string];
+    "job:recovered": [jobId: string];
+    "worker:started": [workerId: string];
+    "worker:stopped": [workerId: string];
+    "worker:status": [workerId: string, status: WorkerStatus];
+    "worker:error": [workerId: string, error: Error];
+    "queue:error": [queueName: string, error: Error];
+    error: [error: Error];
+}
+//# sourceMappingURL=events.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.types.d.ts","sourceRoot":"","sources":["../../src/types/events.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAMtD,MAAM,WAAW,WAAW,CAAC,QAAQ,GAAG,OAAO;IAE7C,cAAc,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzC,aAAa,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxC,eAAe,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC1C,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IACrD,cAAc,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IAC1E,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IACnD,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/B,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAGjC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACrC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACrC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IAC1D,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAGjD,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAGjD,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;CACvB"}

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public type re-exports.
+ */
+export type { JobStatus, JobAttempt, JobSchedule, JobOptions, BackoffStrategy, JobData, } from "./job.types.js";
+export type { RateLimitOptions, QueueOptions } from "./queue.types.js";
+export type { Processor, WorkerOptions, WorkerStatus } from "./worker.types.js";
+export type { StorageAdapter, EnqueueInput, ClaimInput, ClaimResult, RequeueInput, MoveToDlqInput, GetJobsFilter, } from "./storage.types.js";
+export type { StorageDialect, ClientDefaults, QueueClientOptions } from "./client.types.js";
+export type { QueueEvents } from "./events.types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACX,UAAU,EACV,eAAe,EACf,OAAO,GACR,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEvE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEhF,YAAY,EACV,cAAc,EACd,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,aAAa,GACd,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5F,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types/job.types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * All types related to Job identity, state, configuration, and lifecycle.
+ */
+export type JobStatus = "waiting" | "active" | "completed" | "delayed" | "dead";
+export interface JobAttempt {
+    /** 1-based attempt number. */
+    readonly attempt: number;
+    /** ISO timestamp when this attempt started. */
+    readonly startedAt: string;
+    /** ISO timestamp when this attempt finished (success or failure). */
+    readonly finishedAt: string;
+    /** Error message if the attempt failed. */
+    readonly error?: string;
+    /** Error stack trace if the attempt failed (never logged by default). */
+    readonly stack?: string | undefined;
+}
+export interface JobSchedule {
+    /**
+     * Delay in milliseconds before the job becomes eligible.
+     * Mutually exclusive with `runAt`.
+     */
+    delay?: number;
+    /**
+     * Absolute timestamp (ISO string or epoch ms) when the job becomes eligible.
+     * Mutually exclusive with `delay`.
+     */
+    runAt?: string | number;
+    /**
+     * Cron expression for recurring jobs.
+     * When set the job re-enqueues itself after each successful execution.
+     */
+    cron?: string;
+}
+export interface JobOptions {
+    /** Maximum number of processing attempts (default: inherited from queue/client). */
+    attempts?: number;
+    /**
+     * Base delay in milliseconds between retry attempts.
+     * Used by the backoff strategy.
+     */
+    retryDelay?: number;
+    /** Backoff strategy applied on retry. */
+    backoff?: BackoffStrategy;
+    /** Maximum execution time in milliseconds for a single attempt. */
+    timeout?: number;
+    /**
+     * Priority value — higher numbers are processed first.
+     * Default: 0.
+     */
+    priority?: number;
+    /** Scheduling options (delay / runAt / cron). */
+    schedule?: JobSchedule;
+}
+export type BackoffStrategy = "fixed" | "exponential" | "linear";
+export interface JobData<TPayload = unknown> {
+    /** Unique, stable job identifier. */
+    readonly id: string;
+    /** Name of the queue this job belongs to. */
+    readonly queue: string;
+    /** Application-defined job type (matches processor registration). */
+    readonly type: string;
+    /** User-supplied job payload. Never logged by default. */
+    readonly payload: TPayload;
+    /** Current lifecycle status. */
+    status: JobStatus;
+    /** Number of attempts already executed (0 = not yet started). */
+    attemptsMade: number;
+    /** Maximum allowed attempts. */
+    maxAttempts: number;
+    /** Base delay in ms between retries. */
+    retryDelay: number;
+    /** Backoff strategy. */
+    backoff: BackoffStrategy;
+    /** Per-attempt timeout in ms. */
+    timeout: number;
+    /** Processing priority — higher = sooner. */
+    priority: number;
+    /** ISO timestamp when the job is eligible to run (for delayed/scheduled jobs). */
+    runAt: string;
+    /** Cron expression (recurring jobs only). */
+    cron?: string | undefined;
+    /** Ordered list of past attempt records. */
+    attempts: JobAttempt[];
+    /** ID of the worker lock currently owning this job (null when not active). */
+    lockId: string | null;
+    /** ISO timestamp when the current lock expires. */
+    lockExpiresAt: string | null;
+    /** ISO timestamp when the job was enqueued. */
+    readonly createdAt: string;
+    /** ISO timestamp of the last status change. */
+    updatedAt: string;
+    /** ISO timestamp when processing completed successfully. */
+    completedAt: string | null;
+    /** ISO timestamp when the job was moved to the DLQ. */
+    failedAt: string | null;
+}
+//# sourceMappingURL=job.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"job.types.d.ts","sourceRoot":"","sources":["../../src/types/job.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,QAAQ,GACR,WAAW,GACX,SAAS,GACT,MAAM,CAAC;AAMX,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAMD,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,MAAM,WAAW,UAAU;IACzB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,yCAAyC;IACzC,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAMD,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,aAAa,GAAG,QAAQ,CAAC;AAMjE,MAAM,WAAW,OAAO,CAAC,QAAQ,GAAG,OAAO;IACzC,qCAAqC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAE3B,gCAAgC;IAChC,MAAM,EAAE,SAAS,CAAC;IAElB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IAErB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IAEpB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IAEnB,wBAAwB;IACxB,OAAO,EAAE,eAAe,CAAC;IAEzB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAEhB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IAEjB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IAEd,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1B,4CAA4C;IAC5C,QAAQ,EAAE,UAAU,EAAE,CAAC;IAEvB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtB,mDAAmD;IACnD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAElB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,uDAAuD;IACvD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB"}

package/dist/types/queue.types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Types for Queue configuration and queue-level options.
+ */
+import type { BackoffStrategy } from "./job.types.js";
+export interface RateLimitOptions {
+    /** Maximum number of jobs to process within `duration`. */
+    max: number;
+    /** Time window in milliseconds. */
+    duration: number;
+}
+export interface QueueOptions {
+    /**
+     * Maximum concurrent jobs processed across all workers of this queue.
+     * Default: 10.
+     */
+    concurrency?: number;
+    /** Default max attempts for jobs in this queue. */
+    attempts?: number;
+    /** Default base retry delay in ms for jobs in this queue. */
+    retryDelay?: number;
+    /** Default backoff strategy. */
+    backoff?: BackoffStrategy;
+    /** Default per-attempt timeout in ms. */
+    timeout?: number;
+    /** Queue-level rate limiting. */
+    rateLimit?: RateLimitOptions;
+    /**
+     * Interval in ms between each poll cycle (how often the worker checks for
+     * new jobs). Default: 1 000 ms.
+     */
+    pollInterval?: number;
+    /**
+     * Interval in ms between stalled-job recovery checks.
+     * Default: 30 000 ms.
+     */
+    stalledInterval?: number;
+    /**
+     * How long a lock is valid before it is considered expired.
+     * Default: 60 000 ms.
+     */
+    lockDuration?: number;
+}
+//# sourceMappingURL=queue.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queue.types.d.ts","sourceRoot":"","sources":["../../src/types/queue.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAMtD,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,gCAAgC;IAChC,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,iCAAiC;IACjC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAE7B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/types/storage.types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Types for the StorageAdapter abstraction.
+ */
+import type { JobData, JobStatus, BackoffStrategy } from "./job.types.js";
+export interface EnqueueInput<TPayload = unknown> {
+    id: string;
+    queue: string;
+    type: string;
+    payload: TPayload;
+    maxAttempts: number;
+    retryDelay: number;
+    backoff: BackoffStrategy;
+    timeout: number;
+    priority: number;
+    runAt: string;
+    cron?: string | undefined;
+}
+export interface ClaimInput {
+    queue: string;
+    lockId: string;
+    lockDuration: number;
+    now: string;
+}
+export interface ClaimResult<TPayload = unknown> {
+    job: JobData<TPayload>;
+}
+export interface RequeueInput {
+    jobId: string;
+    runAt: string;
+    error: string;
+    stack?: string | undefined;
+    /** 1-based attempt number that just failed (used to populate attempt history). */
+    attemptNumber: number;
+}
+export interface MoveToDlqInput {
+    jobId: string;
+    error: string;
+    stack?: string | undefined;
+    /** 1-based attempt number that just failed (used to populate attempt history). */
+    attemptNumber: number;
+}
+export interface GetJobsFilter {
+    queue?: string | undefined;
+    status?: JobStatus | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}
+/**
+ * StorageAdapter is the only way the core interacts with persistence.
+ *
+ * All implementations must honour the atomicity requirements documented on each
+ * method.
+ */
+export interface StorageAdapter {
+    /**
+     * Initialise the adapter (create tables, indexes, connection pools, etc.).
+     * Called once by QueueClient before any queue or worker operation.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Tear down the adapter (close connections, flush buffers).
+     * Called once when the client is closing.
+     */
+    close(): Promise<void>;
+    /**
+     * Persist a new job in `waiting` (or `delayed`) status.
+     * Must be idempotent when called with the same `id`.
+     */
+    enqueue<TPayload = unknown>(input: EnqueueInput<TPayload>): Promise<JobData<TPayload>>;
+    /**
+     * Atomically claim the next eligible job in `queue`.
+     *
+     * Eligible means:
+     *   - status === 'waiting'
+     *   - runAt <= now
+     *   - no valid (non-expired) lock held
+     *
+     * The implementation MUST guarantee that concurrent callers cannot claim the
+     * same job.  Returns `null` when no eligible job is found.
+     */
+    claim<TPayload = unknown>(input: ClaimInput): Promise<JobData<TPayload> | null>;
+    /**
+     * Mark a job as successfully completed and release its lock.
+     */
+    complete(jobId: string): Promise<void>;
+    /**
+     * Requeue a failed job for another attempt (retry).
+     * Records the failure in `attempts` history.
+     * Must NOT create a new job identity.
+     */
+    requeue(input: RequeueInput): Promise<void>;
+    /**
+     * Move a permanently-failed job to the DLQ.
+     * Sets status to `'dead'` and records the final failure.
+     */
+    moveToDlq(input: MoveToDlqInput): Promise<void>;
+    /**
+     * Release the lock on a job without changing its status.
+     * Used during graceful shutdown when a job cannot complete in time.
+     */
+    releaseLock(jobId: string): Promise<void>;
+    /**
+     * Recover stalled jobs — jobs that are `active` but whose lock has expired.
+     * Returns the list of recovered job IDs.
+     */
+    recoverStalledJobs(queue: string, now: string): Promise<string[]>;
+    /** Fetch a single job by its ID. Returns `null` if not found. */
+    getJob<TPayload = unknown>(jobId: string): Promise<JobData<TPayload> | null>;
+    /** Fetch multiple jobs matching the given filter. */
+    getJobs<TPayload = unknown>(filter: GetJobsFilter): Promise<JobData<TPayload>[]>;
+    /** Count jobs by status in a queue. */
+    getJobCounts(queue: string): Promise<Record<JobStatus, number>>;
+    /**
+     * Increment the rate-limit counter for `queue` within the current window.
+     * Returns `true` when the job is allowed to proceed, `false` when the rate
+     * limit has been reached.
+     */
+    checkAndIncrementRateLimit(queue: string, max: number, windowMs: number, now: string): Promise<boolean>;
+}
+//# sourceMappingURL=storage.types.d.ts.map

package/dist/types/storage.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.types.d.ts","sourceRoot":"","sources":["../../src/types/storage.types.ts"],"names":[],"mappings":"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"}

package/dist/types/worker.types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Types for Worker configuration, processor functions, and worker state.
+ */
+import type { Job } from "../core/job.js";
+/**
+ * A user-supplied function that handles a single job.
+ *
+ * Must resolve to indicate success.
+ * Throwing (or rejecting) marks the job as failed for this attempt.
+ */
+export type Processor<TPayload = unknown> = (job: Job<TPayload>) => Promise<void>;
+export interface WorkerOptions {
+    /**
+     * Maximum number of jobs processed concurrently by this worker.
+     * Overrides the queue-level concurrency setting.
+     */
+    concurrency?: number;
+    /**
+     * How long to wait for active jobs to finish during graceful shutdown (ms).
+     * Default: 30 000 ms.
+     */
+    shutdownTimeout?: number;
+}
+export type WorkerStatus = "idle" | "running" | "stopping" | "stopped";
+//# sourceMappingURL=worker.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worker.types.d.ts","sourceRoot":"","sources":["../../src/types/worker.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAM1C;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,QAAQ,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAMlF,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC"}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "queue-jobs-worker",
+  "version": "1.0.0",
+  "description": "Reliable job queue and background worker system for Node.js with retries, concurrency, scheduling, and failure recovery.",
+  "keywords": [
+    "queue",
+    "job-queue",
+    "background-jobs",
+    "background-processing",
+    "worker",
+    "nodejs",
+    "retry",
+    "concurrency",
+    "scheduling",
+    "dlq",
+    "dead-letter-queue",
+    "redis",
+    "postgres",
+    "mysql",
+    "typescript"
+  ],
+  "homepage": "https://github.com/rafidahmed870/queue-jobs-worker#readme",
+  "bugs": {
+    "url": "https://github.com/rafidahmed870/queue-jobs-worker/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rafidahmed870/queue-jobs-worker.git"
+  },
+  "license": "MIT",
+  "author": "Rafid Ahmed",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.dts.json",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "redis": ">=4.0.0",
+    "pg": ">=8.0.0",
+    "mysql2": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "redis": { "optional": true },
+    "pg": { "optional": true },
+    "mysql2": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/node": "*",
+    "@types/pg": "^8.23.1",
+    "@typescript-eslint/eslint-plugin": "*",
+    "@typescript-eslint/parser": "*",
+    "eslint": "*",
+    "eslint-config-prettier": "*",
+    "eslint-plugin-prettier": "*",
+    "mysql2": "^3.24.2",
+    "pg": "^8.23.0",
+    "prettier": "*",
+    "redis": "^6.2.1",
+    "tsup": "*",
+    "typescript": "*",
+    "vitest": "*"
+  }
+}