queue-jobs-worker 1.0.4 → 2.0.0

package/dist/index.js

@@ -1,2519 +1,1388 @@
-import { randomUUID } from 'crypto';
-import { Cron } from 'croner';
-import { EventEmitter } from 'events';
-
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-// src/storage/redis.adapter.ts
-var redis_adapter_exports = {};
-__export(redis_adapter_exports, {
-  RedisStorageAdapter: () => RedisStorageAdapter
-});
-async function loadRedis() {
-  try {
-    return await import('redis');
-  } catch {
-    throw new Error(
-      'RedisStorageAdapter requires the "redis" package (node-redis v4+).\nInstall it: npm install redis'
-    );
+// src/storage/memory.storage.ts
+var MemoryStorage = class {
+  /**
+   * Top-level map: queueName → (jobId → Job).
+   * Each queue gets its own inner Map so lookups stay O(1).
+   */
+  store = /* @__PURE__ */ new Map();
+  // ─── IStorage ─────────────────────────────────────────────────────────────
+  async connect() {
   }
-}
-function jobToHash(job) {
-  return {
-    id: job.id,
-    queue: job.queue,
-    type: job.type,
-    payload: JSON.stringify(job.payload),
-    status: job.status,
-    attemptsMade: String(job.attemptsMade),
-    maxAttempts: String(job.maxAttempts),
-    retryDelay: String(job.retryDelay),
-    backoff: job.backoff,
-    timeout: String(job.timeout),
-    priority: String(job.priority),
-    runAt: job.runAt,
-    ...job.cron !== void 0 ? { cron: job.cron } : {},
-    attempts: JSON.stringify(job.attempts),
-    lockId: job.lockId ?? "",
-    lockExpiresAt: job.lockExpiresAt ?? "",
-    createdAt: job.createdAt,
-    updatedAt: job.updatedAt,
-    completedAt: job.completedAt ?? "",
-    failedAt: job.failedAt ?? ""
-  };
-}
-function hashToJob(h) {
-  const job = {
-    id: h["id"] ?? "",
-    queue: h["queue"] ?? "",
-    type: h["type"] ?? "",
-    payload: JSON.parse(h["payload"] ?? "null"),
-    status: h["status"] ?? "waiting",
-    attemptsMade: Number(h["attemptsMade"] ?? 0),
-    maxAttempts: Number(h["maxAttempts"] ?? 1),
-    retryDelay: Number(h["retryDelay"] ?? 1e3),
-    backoff: h["backoff"] ?? "exponential",
-    timeout: Number(h["timeout"] ?? 3e4),
-    priority: Number(h["priority"] ?? 0),
-    runAt: h["runAt"] ?? (/* @__PURE__ */ new Date()).toISOString(),
-    attempts: JSON.parse(h["attempts"] ?? "[]"),
-    lockId: h["lockId"] || null,
-    lockExpiresAt: h["lockExpiresAt"] || null,
-    createdAt: h["createdAt"] ?? (/* @__PURE__ */ new Date()).toISOString(),
-    updatedAt: h["updatedAt"] ?? (/* @__PURE__ */ new Date()).toISOString(),
-    completedAt: h["completedAt"] || null,
-    failedAt: h["failedAt"] || null
-  };
-  if (h["cron"]) job.cron = h["cron"];
-  return job;
-}
-var PREFIX, k, CLAIM_LUA, RECOVER_STALLED_LUA, RENEW_LOCK_LUA, RedisStorageAdapter;
-var init_redis_adapter = __esm({
-  "src/storage/redis.adapter.ts"() {
-    PREFIX = "qjw:";
-    k = {
-      job: (id) => `${PREFIX}job:${id}`,
-      waiting: (q) => `${PREFIX}queue:${q}:waiting`,
-      delayed: (q) => `${PREFIX}queue:${q}:delayed`,
-      active: (q) => `${PREFIX}queue:${q}:active`,
-      completed: (q) => `${PREFIX}queue:${q}:completed`,
-      dead: (q) => `${PREFIX}queue:${q}:dead`,
-      rateCount: (q) => `${PREFIX}rate:${q}`,
-      rateTs: (q) => `${PREFIX}rate:${q}:ts`
+  async disconnect() {
+    this.store.clear();
+  }
+  async saveJob(queueName, job) {
+    const queue = this.getOrCreateQueue(queueName);
+    queue.set(job.id, job);
+  }
+  async getJob(queueName, jobId) {
+    const queue = this.store.get(queueName);
+    if (!queue) return void 0;
+    const job = queue.get(jobId);
+    return job;
+  }
+  async updateJob(queueName, jobId, patch) {
+    const queue = this.store.get(queueName);
+    if (!queue) return;
+    const existing = queue.get(jobId);
+    if (!existing) return;
+    const updated = {
+      ...existing,
+      ...patch,
+      updatedAt: Date.now()
     };
-    CLAIM_LUA = `
-local prefix    = ARGV[4]
-local now_ms    = tonumber(ARGV[3])
-
--- Promote due delayed jobs into the waiting set.
-local due = redis.call('ZRANGEBYSCORE', KEYS[2], '-inf', now_ms)
-for _, jid in ipairs(due) do
-  local pri_raw = redis.call('HGET', prefix .. 'job:' .. jid, 'priority')
-  local pri = tonumber(pri_raw) or 0
-  redis.call('ZADD',  KEYS[1], -pri, jid)
-  redis.call('ZREM',  KEYS[2], jid)
-  redis.call('HSET',  prefix .. 'job:' .. jid, 'status', 'waiting')
-end
-
--- Pop the top-priority job.
-local items = redis.call('ZPOPMIN', KEYS[1], 1)
-if #items == 0 then return '' end
-local job_id = items[1]
-
--- Lock it.
-redis.call('SADD', KEYS[3], job_id)
-redis.call('HSET', prefix .. 'job:' .. job_id,
-  'status',        'active',
-  'lockId',        ARGV[1],
-  'lockExpiresAt', ARGV[2],
-  'updatedAt',     ARGV[2]
-)
-return job_id
-`;
-    RECOVER_STALLED_LUA = `
-local job_key        = KEYS[1]
-local active_set     = KEYS[2]
-local waiting_zset   = KEYS[3]
-
-local job_id         = ARGV[1]
-local expected_exp   = ARGV[2]
-local expected_lock  = ARGV[3]
-local recovery_ts    = ARGV[4]
-local priority_score = tonumber(ARGV[5])
-
--- Re-read the three guard fields in one atomic HMGET.
-local fields = redis.call('HMGET', job_key, 'lockExpiresAt', 'lockId', 'status')
-local current_exp    = fields[1] or ''
-local current_lock   = fields[2] or ''
-local current_status = fields[3] or ''
-
--- Guard 1: job must still be active.
--- If the worker already completed, failed, or moved to DLQ, skip.
-if current_status ~= 'active' then return 0 end
-
--- Guard 2: lockId must not have changed.
--- A different worker may have claimed the job after the original lock expired
--- and before this script runs.
-if current_lock ~= expected_lock then return 0 end
-
--- Guard 3: lockExpiresAt must be exactly what the caller observed.
--- If the worker renewed its lock the timestamp will be later than observed;
--- the CAS mismatch catches that without needing ISO\u2192epoch conversion in Lua.
-if current_exp ~= expected_exp then return 0 end
-
--- All guards passed \u2014 recover atomically.
-redis.call('HSET', job_key,
-  'status',        'waiting',
-  'lockId',        '',
-  'lockExpiresAt', '',
-  'updatedAt',     recovery_ts
-)
-redis.call('SREM', active_set,   job_id)
-redis.call('ZADD', waiting_zset, priority_score, job_id)
-return 1
-`;
-    RENEW_LOCK_LUA = `
-local job_key = KEYS[1]
-local lock_id = ARGV[1]
-local new_exp = ARGV[2]
-local now_iso = ARGV[3]
-
-local fields = redis.call('HMGET', job_key, 'status', 'lockId', 'lockExpiresAt')
-local status = fields[1] or ''
-local current_lock = fields[2] or ''
-local current_exp = fields[3] or ''
-
-if status ~= 'active' then return 0 end
-if current_lock ~= lock_id then return 0 end
-if current_exp == '' or current_exp <= now_iso then return 0 end
+    queue.set(jobId, updated);
+  }
+  async removeJob(queueName, jobId) {
+    this.store.get(queueName)?.delete(jobId);
+  }
+  async listJobs(queueName, status) {
+    const queue = this.store.get(queueName);
+    if (!queue) return [];
+    let jobs = Array.from(queue.values());
+    if (status !== void 0) {
+      jobs = jobs.filter((j) => j.status === status);
+    }
+    return this.sortJobs(jobs);
+  }
+  async getNextJob(queueName) {
+    const queue = this.store.get(queueName);
+    if (!queue) return void 0;
+    const now = Date.now();
+    const candidates = Array.from(queue.values()).filter(
+      (j) => (j.status === "waiting" || j.status === "retrying") && j.runAt <= now
+    );
+    if (candidates.length === 0) return void 0;
+    const next = this.sortJobs(candidates)[0];
+    const claimed = {
+      ...next,
+      status: "active",
+      processedAt: now,
+      updatedAt: now
+    };
+    queue.set(next.id, claimed);
+    return claimed;
+  }
+  async clearQueue(queueName) {
+    this.store.delete(queueName);
+  }
+  async countJobs(queueName) {
+    return this.store.get(queueName)?.size ?? 0;
+  }
+  // ─── Private helpers ──────────────────────────────────────────────────────
+  getOrCreateQueue(queueName) {
+    let queue = this.store.get(queueName);
+    if (!queue) {
+      queue = /* @__PURE__ */ new Map();
+      this.store.set(queueName, queue);
+    }
+    return queue;
+  }
+  /**
+   * Sort jobs by priority ascending (lower number = higher priority),
+   * then by createdAt ascending (older jobs run first).
+   */
+  sortJobs(jobs) {
+    return jobs.slice().sort((a, b) => {
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      return a.createdAt - b.createdAt;
+    });
+  }
+};
 
-redis.call('HSET', job_key, 'lockExpiresAt', new_exp, 'updatedAt', now_iso)
-return 1
-`;
-    RedisStorageAdapter = class {
-      client;
-      url;
-      constructor(connectionString) {
-        this.url = connectionString;
-      }
-      // -------------------------------------------------------------------------
-      // Lifecycle
-      // -------------------------------------------------------------------------
-      async initialize() {
-        const { createClient } = await loadRedis();
-        this.client = createClient({ url: this.url });
-        this.client.on("error", () => {
-        });
-        await this.client.connect();
-        const pong = await this.client.ping();
-        if (pong !== "PONG") {
-          throw new Error(
-            "RedisStorageAdapter: PING returned unexpected response. Connection may be unhealthy."
-          );
-        }
-      }
-      async close() {
-        if (this.client) {
-          await this.client.quit();
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Enqueue
-      // -------------------------------------------------------------------------
-      async enqueue(input) {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        const runAtMs = new Date(input.runAt).getTime();
-        const isDelayed = runAtMs > Date.now();
-        const job = {
-          id: input.id,
-          queue: input.queue,
-          type: input.type,
-          payload: input.payload,
-          status: isDelayed ? "delayed" : "waiting",
-          attemptsMade: 0,
-          maxAttempts: input.maxAttempts,
-          retryDelay: input.retryDelay,
-          backoff: input.backoff,
-          timeout: input.timeout,
-          priority: input.priority,
-          runAt: input.runAt,
-          ...input.cron !== void 0 ? { cron: input.cron } : {},
-          attempts: [],
-          lockId: null,
-          lockExpiresAt: null,
-          createdAt: now,
-          updatedAt: now,
-          completedAt: null,
-          failedAt: null
-        };
-        const key = k.job(input.id);
-        const exists = await this.client.exists(key);
-        if (exists) {
-          const hash = await this.client.hGetAll(key);
-          return hashToJob(hash);
-        }
-        const multi = this.client.multi();
-        multi.hSet(key, jobToHash(job));
-        if (isDelayed) {
-          multi.zAdd(k.delayed(input.queue), { score: runAtMs, value: input.id });
-        } else {
-          multi.zAdd(k.waiting(input.queue), { score: -input.priority, value: input.id });
-        }
-        await multi.exec();
-        return job;
-      }
-      // -------------------------------------------------------------------------
-      // Claim  (atomic Lua)
-      // -------------------------------------------------------------------------
-      async claim(input) {
-        const { queue, lockId, lockDuration, now } = input;
-        const nowMs = new Date(now).getTime();
-        const lockExpiresAt = new Date(nowMs + lockDuration).toISOString();
-        const jobId = await this.client.eval(CLAIM_LUA, {
-          keys: [k.waiting(queue), k.delayed(queue), k.active(queue)],
-          arguments: [lockId, lockExpiresAt, String(nowMs), PREFIX]
-        });
-        if (!jobId) return null;
-        const hash = await this.client.hGetAll(k.job(jobId));
-        if (!hash || Object.keys(hash).length === 0) return null;
-        return hashToJob(hash);
-      }
-      // -------------------------------------------------------------------------
-      // Renew lock
-      // -------------------------------------------------------------------------
-      async renewLock(jobId, lockId, lockDuration) {
-        const nowMs = Date.now();
-        const nowIso = new Date(nowMs).toISOString();
-        const newExpiresAt = new Date(nowMs + lockDuration).toISOString();
-        const res = await this.client.eval(RENEW_LOCK_LUA, {
-          keys: [k.job(jobId)],
-          arguments: [lockId, newExpiresAt, nowIso]
-        });
-        return Number(res) === 1;
-      }
-      // -------------------------------------------------------------------------
-      // Complete
-      // -------------------------------------------------------------------------
-      async complete(jobId, lockId) {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        const hash = await this.client.hGetAll(k.job(jobId));
-        if (!hash || Object.keys(hash).length === 0) return;
-        if (lockId !== void 0) {
-          if (hash["status"] !== "active" || hash["lockId"] !== lockId) return;
-        }
-        const queue = hash["queue"] ?? "";
-        const multi = this.client.multi();
-        multi.hSet(k.job(jobId), {
-          status: "completed",
-          lockId: "",
-          lockExpiresAt: "",
-          completedAt: now,
-          updatedAt: now
-        });
-        multi.sRem(k.active(queue), jobId);
-        multi.sAdd(k.completed(queue), jobId);
-        await multi.exec();
-      }
-      // -------------------------------------------------------------------------
-      // Requeue
-      // -------------------------------------------------------------------------
-      async requeue(input) {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        const hash = await this.client.hGetAll(k.job(input.jobId));
-        if (!hash || Object.keys(hash).length === 0) return;
-        if (input.lockId !== void 0) {
-          if (hash["status"] !== "active" || hash["lockId"] !== input.lockId) return;
-        }
-        const queue = hash["queue"] ?? "";
-        const attempts = JSON.parse(hash["attempts"] ?? "[]");
-        attempts.push({
-          attempt: input.attemptNumber,
-          startedAt: hash["updatedAt"] ?? now,
-          finishedAt: now,
-          error: input.error,
-          ...input.stack !== void 0 ? { stack: input.stack } : {}
-        });
-        const multi = this.client.multi();
-        multi.hSet(k.job(input.jobId), {
-          status: "waiting",
-          attemptsMade: String(input.attemptNumber),
-          attempts: JSON.stringify(attempts),
-          runAt: input.runAt,
-          lockId: "",
-          lockExpiresAt: "",
-          updatedAt: now
-        });
-        multi.sRem(k.active(queue), input.jobId);
-        multi.zAdd(k.delayed(queue), {
-          score: new Date(input.runAt).getTime(),
-          value: input.jobId
-        });
-        await multi.exec();
-      }
-      // -------------------------------------------------------------------------
-      // Move to DLQ
-      // -------------------------------------------------------------------------
-      async moveToDlq(input) {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        const hash = await this.client.hGetAll(k.job(input.jobId));
-        if (!hash || Object.keys(hash).length === 0) return;
-        if (input.lockId !== void 0) {
-          if (hash["status"] !== "active" || hash["lockId"] !== input.lockId) return;
-        }
-        const queue = hash["queue"] ?? "";
-        const attempts = JSON.parse(hash["attempts"] ?? "[]");
-        attempts.push({
-          attempt: input.attemptNumber,
-          startedAt: hash["updatedAt"] ?? now,
-          finishedAt: now,
-          error: input.error,
-          ...input.stack !== void 0 ? { stack: input.stack } : {}
-        });
-        const multi = this.client.multi();
-        multi.hSet(k.job(input.jobId), {
-          status: "dead",
-          attemptsMade: String(input.attemptNumber),
-          attempts: JSON.stringify(attempts),
-          lockId: "",
-          lockExpiresAt: "",
-          failedAt: now,
-          updatedAt: now
-        });
-        multi.sRem(k.active(queue), input.jobId);
-        multi.sAdd(k.dead(queue), input.jobId);
-        await multi.exec();
-      }
-      // -------------------------------------------------------------------------
-      // Release lock
-      // -------------------------------------------------------------------------
-      async releaseLock(jobId, lockId) {
-        const hash = await this.client.hGetAll(k.job(jobId));
-        if (!hash || Object.keys(hash).length === 0) return;
-        if (lockId !== void 0) {
-          if (hash["status"] !== "active" || hash["lockId"] !== lockId) return;
-        }
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        await this.client.hSet(k.job(jobId), {
-          lockId: "",
-          lockExpiresAt: now,
-          updatedAt: now
-        });
-      }
-      // -------------------------------------------------------------------------
-      // Recover stalled jobs  (atomic compare-and-swap per job via Lua)
-      //
-      // Previous implementation: two-phase read pipeline → write pipeline.
-      // Race condition: a worker could complete or renew its lock between the two
-      // phases, causing recovery to overwrite a legitimately-active job.
-      //
-      // Fix (issue #6): for each candidate job the RECOVER_STALLED_LUA script
-      // re-reads lockExpiresAt, lockId, and status atomically and only applies
-      // the recovery if all three still match what was observed in the read phase
-      // (compare-and-swap).  If the worker renewed or completed the job in the
-      // window between the read and the Lua call, the CAS mismatch causes the
-      // script to return 0 and the job is left untouched.
-      // -------------------------------------------------------------------------
-      async recoverStalledJobs(queue, now) {
-        const nowMs = new Date(now).getTime();
-        const activeIds = await this.client.sMembers(k.active(queue));
-        if (activeIds.length === 0) return [];
-        const fetchPipeline = this.client.multi();
-        for (const jobId of activeIds) {
-          fetchPipeline.hmGet(k.job(jobId), ["lockExpiresAt", "lockId", "priority"]);
-        }
-        const fetchResults = await fetchPipeline.exec();
-        const recovered = [];
-        const evalPromises = [];
-        for (let i = 0; i < activeIds.length; i++) {
-          const jobId = activeIds[i];
-          const fields = fetchResults[i];
-          if (!fields) continue;
-          const [lockExpiresAt, lockId, priorityStr] = fields;
-          if (!lockExpiresAt) continue;
-          if (new Date(lockExpiresAt).getTime() > nowMs) continue;
-          const priority = Number(priorityStr ?? "0");
-          const priorityScore = String(-priority);
-          const p = this.client.eval(RECOVER_STALLED_LUA, {
-            keys: [k.job(jobId), k.active(queue), k.waiting(queue)],
-            arguments: [jobId, lockExpiresAt, lockId ?? "", now, priorityScore]
-          }).then((result) => {
-            if (result === 1) recovered.push(jobId);
-          });
-          evalPromises.push(p);
-        }
-        await Promise.all(evalPromises);
-        return recovered;
-      }
-      // -------------------------------------------------------------------------
-      // Reads
-      // -------------------------------------------------------------------------
-      async getJob(jobId) {
-        const hash = await this.client.hGetAll(k.job(jobId));
-        if (!hash || Object.keys(hash).length === 0) return null;
-        return hashToJob(hash);
-      }
-      async getJobs(filter) {
-        const { queue, status, limit = 100, offset = 0 } = filter;
-        let ids = [];
-        if (queue && status) {
-          switch (status) {
-            case "waiting":
-              ids = await this.client.zRange(k.waiting(queue), 0, -1);
-              break;
-            case "delayed":
-              ids = await this.client.zRange(k.delayed(queue), 0, -1);
-              break;
-            case "active":
-              ids = await this.client.sMembers(k.active(queue));
-              break;
-            case "completed":
-              ids = await this.client.sMembers(k.completed(queue));
-              break;
-            case "dead":
-              ids = await this.client.sMembers(k.dead(queue));
-              break;
-            default:
-              ids = [];
-          }
-        } else {
-          for await (const key of this.client.scanIterator({
-            MATCH: `${PREFIX}job:*`,
-            COUNT: 500
-          })) {
-            const keyStr = Array.isArray(key) ? String(key[0]) : String(key);
-            ids.push(keyStr.replace(`${PREFIX}job:`, ""));
-          }
-        }
-        const results = [];
-        const page = ids.slice(offset, offset + limit);
-        for (const id of page) {
-          const job = await this.getJob(id);
-          if (!job) continue;
-          if (queue && job.queue !== queue) continue;
-          if (status && job.status !== status) continue;
-          results.push(job);
-        }
-        return results;
+// src/storage/redis.storage.ts
+import { readFile } from "fs/promises";
+import { fileURLToPath } from "url";
+import { join, dirname } from "path";
+var RedisStorage = class {
+  client = null;
+  connectionString;
+  /** SHA1 digests returned by SCRIPT LOAD, keyed by script name. */
+  sha = {};
+  constructor(connectionString) {
+    this.connectionString = connectionString;
+  }
+  // ─── Lifecycle ────────────────────────────────────────────────────────────
+  async connect() {
+    let mod;
+    try {
+      mod = await import("redis");
+    } catch {
+      throw new Error(
+        "[queue-jobs-worker] Redis dialect requires the `redis` package. Run: npm install redis"
+      );
+    }
+    const c = mod.createClient({ url: this.connectionString });
+    c.on("error", (err) => console.error("[queue-jobs-worker] Redis error:", err));
+    await c.connect();
+    this.client = c;
+    await this.loadScripts();
+  }
+  async disconnect() {
+    if (this.client) {
+      await this.client.quit();
+      this.client = null;
+    }
+  }
+  // ─── IStorage implementation ──────────────────────────────────────────────
+  /**
+   * Persist a new job.
+   * 1 round-trip (save-job.lua: SET + ZADD index + conditional ZADD waiting).
+   */
+  async saveJob(queueName, job) {
+    const eligible = job.status === "waiting" || job.status === "retrying" ? "1" : "0";
+    await this.evalSha("save-job", {
+      keys: [this.hashKey(job.id), this.indexKey(queueName), this.waitingKey(queueName)],
+      arguments: [JSON.stringify(job), job.id, String(job.priority), String(job.runAt), eligible]
+    });
+  }
+  /**
+   * Fetch a single job by ID.
+   * 1 round-trip (GET).
+   */
+  async getJob(_queueName, jobId) {
+    const raw = await this.assertClient().get(this.hashKey(jobId));
+    if (!raw) return void 0;
+    return JSON.parse(raw);
+  }
+  /**
+   * Atomically patch a job and update sorted-set membership.
+   * 1 round-trip (update-job.lua: GET + patch + SET server-side).
+   *
+   * Fields are decomposed into three RS-delimited (ASCII 0x1E) lists:
+   *   strFields  — "key\x1evalue\x1ekey\x1evalue…"  for string fields
+   *   numFields  — "key\x1evalue\x1ekey\x1evalue…"  for numeric fields
+   *   nullFields — "key\x1ekey\x1e…"                fields to set to null
+   *
+   * RS (record separator, 0x1E) is used instead of pipe so that error
+   * messages containing "|" characters are never mistaken for delimiters.
+   */
+  async updateJob(queueName, jobId, patch) {
+    const newStatus = patch.status ?? "";
+    const nowMs = String(Date.now());
+    const runAt = patch.runAt !== void 0 ? String(patch.runAt) : "-1";
+    const priority = patch.priority !== void 0 ? String(patch.priority) : "-1";
+    const RS = "";
+    const strParts = [];
+    const numParts = [];
+    const nullParts = [];
+    const boolParts = [];
+    for (const [key, val] of Object.entries(patch)) {
+      if (key === "status" || key === "updatedAt" || key === "runAt") continue;
+      if (val === null || val === void 0) {
+        nullParts.push(key);
+      } else if (typeof val === "number") {
+        numParts.push(key, String(val));
+      } else if (typeof val === "boolean") {
+        boolParts.push(key, val ? "true" : "false");
+      } else if (typeof val === "string") {
+        strParts.push(key, val);
       }
-      async getJobCounts(queue) {
-        const [waiting, delayed, active, completed, dead] = await Promise.all([
-          this.client.zCard(k.waiting(queue)),
-          this.client.zCard(k.delayed(queue)),
-          this.client.sCard(k.active(queue)),
-          this.client.sCard(k.completed(queue)),
-          this.client.sCard(k.dead(queue))
-        ]);
-        return { waiting, delayed, active, completed, dead };
+    }
+    await this.evalSha("update-job", {
+      keys: [this.hashKey(jobId), this.indexKey(queueName), this.waitingKey(queueName)],
+      arguments: [
+        newStatus,
+        nowMs,
+        runAt,
+        priority,
+        strParts.join(RS),
+        numParts.join(RS),
+        nullParts.join(RS),
+        boolParts.join(RS)
+        // ARGV[8] — new in update-job.lua v5
+      ]
+    });
+  }
+  /**
+   * Permanently delete a job and clean up sorted sets.
+   * 1 round-trip (remove-job.lua: EXISTS + DEL + ZREM × 2).
+   */
+  async removeJob(queueName, jobId) {
+    await this.evalSha("remove-job", {
+      keys: [this.hashKey(jobId), this.indexKey(queueName), this.waitingKey(queueName)],
+      arguments: [jobId]
+    });
+  }
+  /**
+   * List all jobs, optionally filtered by status.
+   * 1 round-trip (list-jobs.lua: ZRANGE + N×GET server-side).
+   * Results are already sorted by priority ASC (index set order).
+   */
+  async listJobs(queueName, status) {
+    const raw = await this.evalSha("list-jobs", {
+      keys: [this.indexKey(queueName)],
+      arguments: [status ?? ""]
+    });
+    if (!Array.isArray(raw) || raw.length === 0) return [];
+    return raw.map((r) => JSON.parse(r));
+  }
+  /**
+   * Atomically claim the next eligible job and mark it active.
+   * 1 round-trip (claim-job.lua).
+   */
+  async getNextJob(queueName) {
+    const raw = await this.evalSha("claim-job", {
+      keys: [this.indexKey(queueName), this.waitingKey(queueName)],
+      arguments: [String(Date.now())]
+    });
+    if (!raw || typeof raw !== "string") return void 0;
+    return JSON.parse(raw);
+  }
+  /**
+   * Delete every job in a queue and drop both sorted sets.
+   * 1 round-trip (clear-queue.lua: ZRANGE + N×DEL + 2×DEL server-side).
+   */
+  async clearQueue(queueName) {
+    await this.evalSha("clear-queue", {
+      keys: [this.indexKey(queueName), this.waitingKey(queueName)],
+      arguments: []
+    });
+  }
+  /**
+   * Return the total number of jobs in a queue (all statuses).
+   * 1 round-trip (ZCARD on the index set).
+   */
+  async countJobs(queueName) {
+    return this.assertClient().zCard(this.indexKey(queueName));
+  }
+  // ─── Script loading ───────────────────────────────────────────────────────
+  /**
+   * Read every Lua script from disk and SCRIPT LOAD it into Redis.
+   * Uses async readFile so the event loop is never blocked.
+   * Called once on connect, and again automatically on NOSCRIPT errors.
+   */
+  async loadScripts() {
+    const c = this.assertClient();
+    const dir = join(dirname(fileURLToPath(import.meta.url)), "..", "scripts");
+    const names = [
+      "save-job",
+      "update-job",
+      "remove-job",
+      "clear-queue",
+      "list-jobs",
+      "claim-job"
+    ];
+    const sources = await Promise.all(
+      names.map((name) => readFile(join(dir, `${name}.lua`), "utf8"))
+    );
+    const shas = await Promise.all(sources.map((src) => c.scriptLoad(src)));
+    for (let i = 0; i < names.length; i++) {
+      const sha = shas[i];
+      if (sha !== void 0) {
+        this.sha[names[i]] = sha;
       }
-      // -------------------------------------------------------------------------
-      // Rate limiting
-      // -------------------------------------------------------------------------
-      async checkAndIncrementRateLimit(queue, max, windowMs, now) {
-        const nowMs = new Date(now).getTime();
-        const ck = k.rateCount(queue);
-        const tk = k.rateTs(queue);
-        const windowStart = await this.client.get(tk);
-        const ttlSec = Math.ceil(windowMs / 1e3);
-        if (!windowStart || nowMs - Number(windowStart) >= windowMs) {
-          const multi = this.client.multi();
-          multi.set(ck, "1");
-          multi.expire(ck, ttlSec);
-          multi.set(tk, String(nowMs));
-          multi.expire(tk, ttlSec);
-          await multi.exec();
-          return true;
-        }
-        const count = await this.client.incr(ck);
-        if (count > max) {
-          await this.client.decr(ck);
-          return false;
-        }
-        return true;
+    }
+  }
+  // ─── Private helpers ──────────────────────────────────────────────────────
+  /**
+   * Call EVALSHA and automatically reload scripts on NOSCRIPT errors
+   * (e.g. after a Redis server restart that flushed the script cache).
+   */
+  async evalSha(name, opts) {
+    const c = this.assertClient();
+    const sha = this.sha[name];
+    if (!sha) {
+      throw new Error(
+        `[queue-jobs-worker] Lua script "${name}" has not been loaded. This is a bug \u2014 please open an issue.`
+      );
+    }
+    try {
+      return await c.evalSha(sha, opts);
+    } catch (err) {
+      if (isNoscriptError(err)) {
+        await this.loadScripts();
+        const reloadedSha = this.sha[name];
+        if (!reloadedSha) throw err;
+        return c.evalSha(reloadedSha, opts);
       }
-    };
+      throw err;
+    }
+  }
+  assertClient() {
+    if (!this.client) {
+      throw new Error(
+        "[queue-jobs-worker] RedisStorage is not connected. Call client.init() first."
+      );
+    }
+    return this.client;
+  }
+  hashKey(jobId) {
+    return `qjw:job:${jobId}`;
+  }
+  indexKey(queueName) {
+    return `qjw:${queueName}:index`;
+  }
+  waitingKey(queueName) {
+    return `qjw:${queueName}:waiting`;
   }
-});
+};
+function isNoscriptError(err) {
+  return err instanceof Error && err.message.toUpperCase().includes("NOSCRIPT");
+}
 
-// src/storage/postgres.adapter.ts
-var postgres_adapter_exports = {};
-__export(postgres_adapter_exports, {
-  PostgreSQLStorageAdapter: () => PostgreSQLStorageAdapter
-});
-async function loadPg() {
-  try {
-    return await import('pg');
-  } catch {
-    throw new Error(
-      'PostgreSQLStorageAdapter requires the "pg" package (node-postgres).\nInstall it: npm install pg'
+// src/storage/postgres.storage.ts
+var PostgresStorage = class {
+  pool = null;
+  connectionString;
+  constructor(connectionString) {
+    this.connectionString = connectionString;
+  }
+  // ─── IStorage ─────────────────────────────────────────────────────────────
+  async connect() {
+    let pgModule;
+    try {
+      pgModule = await import("pg");
+    } catch {
+      throw new Error(
+        "[queue-jobs-worker] Postgres dialect requires the `pg` package. Run: npm install pg"
+      );
+    }
+    this.pool = new pgModule.Pool({ connectionString: this.connectionString });
+    await this.ensureTable();
+  }
+  async disconnect() {
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = null;
+    }
+  }
+  async saveJob(queueName, job) {
+    const p = this.assertPool();
+    await p.query(
+      `INSERT INTO qjw_jobs (id, queue_name, payload, status, priority, run_at, created_at)
+       VALUES ($1, $2, $3::jsonb, $4, $5, $6, $7)
+       ON CONFLICT (queue_name, id) DO UPDATE SET payload = EXCLUDED.payload,
+         status = EXCLUDED.status, priority = EXCLUDED.priority, run_at = EXCLUDED.run_at`,
+      [job.id, queueName, JSON.stringify(job), job.status, job.priority, job.runAt, job.createdAt]
     );
   }
-}
-function rowToJob(row) {
-  const job = {
-    id: row.id,
-    queue: row.queue,
-    type: row.type,
-    payload: row.payload,
-    status: row.status,
-    attemptsMade: row.attempts_made,
-    maxAttempts: row.max_attempts,
-    retryDelay: row.retry_delay,
-    backoff: row.backoff,
-    timeout: row.timeout,
-    priority: row.priority,
-    runAt: row.run_at.toISOString(),
-    attempts: row.attempts,
-    lockId: row.lock_id,
-    lockExpiresAt: row.lock_expires_at ? row.lock_expires_at.toISOString() : null,
-    createdAt: row.created_at.toISOString(),
-    updatedAt: row.updated_at.toISOString(),
-    completedAt: row.completed_at ? row.completed_at.toISOString() : null,
-    failedAt: row.failed_at ? row.failed_at.toISOString() : null
-  };
-  if (row.cron) job.cron = row.cron;
-  return job;
-}
-var CREATE_JOBS_TABLE, CREATE_RATE_TABLE, PostgreSQLStorageAdapter;
-var init_postgres_adapter = __esm({
-  "src/storage/postgres.adapter.ts"() {
-    CREATE_JOBS_TABLE = `
-CREATE TABLE IF NOT EXISTS qjw_jobs (
-  id               TEXT        NOT NULL PRIMARY KEY,
-  queue            TEXT        NOT NULL,
-  type             TEXT        NOT NULL,
-  payload          JSONB       NOT NULL DEFAULT '{}',
-  status           TEXT        NOT NULL DEFAULT 'waiting',
-  attempts_made    INTEGER     NOT NULL DEFAULT 0,
-  max_attempts     INTEGER     NOT NULL DEFAULT 3,
-  retry_delay      INTEGER     NOT NULL DEFAULT 1000,
-  backoff          TEXT        NOT NULL DEFAULT 'exponential',
-  timeout          INTEGER     NOT NULL DEFAULT 30000,
-  priority         INTEGER     NOT NULL DEFAULT 0,
-  run_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  cron             TEXT,
-  attempts         JSONB       NOT NULL DEFAULT '[]',
-  lock_id          TEXT,
-  lock_expires_at  TIMESTAMPTZ,
-  created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  updated_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  completed_at     TIMESTAMPTZ,
-  failed_at        TIMESTAMPTZ
-);
-CREATE INDEX IF NOT EXISTS qjw_jobs_claim_idx
-  ON qjw_jobs (queue, status, run_at, priority DESC)
-  WHERE status IN ('waiting', 'delayed');
-`;
-    CREATE_RATE_TABLE = `
-CREATE TABLE IF NOT EXISTS qjw_rate_limits (
-  queue        TEXT    NOT NULL PRIMARY KEY,
-  count        INTEGER NOT NULL DEFAULT 0,
-  window_start BIGINT  NOT NULL DEFAULT 0
-);
-`;
-    PostgreSQLStorageAdapter = class {
-      pool;
-      connectionString;
-      constructor(connectionString) {
-        this.connectionString = connectionString;
-      }
-      // -------------------------------------------------------------------------
-      // Lifecycle
-      // -------------------------------------------------------------------------
-      async initialize() {
-        const { Pool } = await loadPg();
-        this.pool = new Pool({ connectionString: this.connectionString });
-        const client = await this.pool.connect();
-        try {
-          await client.query("SELECT 1");
-          await client.query(CREATE_JOBS_TABLE);
-          await client.query(CREATE_RATE_TABLE);
-        } finally {
-          client.release();
-        }
-      }
-      async close() {
-        if (this.pool) {
-          await this.pool.end();
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Enqueue
-      // -------------------------------------------------------------------------
-      async enqueue(input) {
-        const res = await this.pool.query(
-          `INSERT INTO qjw_jobs
-         (id, queue, type, payload, status, attempts_made, max_attempts,
-          retry_delay, backoff, timeout, priority, run_at, cron,
-          attempts, lock_id, lock_expires_at, created_at, updated_at,
-          completed_at, failed_at)
-       VALUES ($1,$2,$3,$4,
-         CASE WHEN $5::timestamptz > NOW() THEN 'delayed' ELSE 'waiting' END,
-         0,$6,$7,$8,$9,$10,$5,$11,
-         '[]'::jsonb, NULL, NULL, NOW(), NOW(), NULL, NULL)
-       ON CONFLICT (id) DO NOTHING
-       RETURNING *`,
-          [
-            input.id,
-            input.queue,
-            input.type,
-            JSON.stringify(input.payload),
-            input.runAt,
-            input.maxAttempts,
-            input.retryDelay,
-            input.backoff,
-            input.timeout,
-            input.priority,
-            input.cron ?? null
-          ]
-        );
-        if (res.rows.length > 0) {
-          return rowToJob(res.rows[0]);
-        }
-        const existing = await this.pool.query("SELECT * FROM qjw_jobs WHERE id = $1", [
-          input.id
-        ]);
-        return rowToJob(existing.rows[0]);
-      }
-      // -------------------------------------------------------------------------
-      // Claim  (SELECT … FOR UPDATE SKIP LOCKED)
-      // -------------------------------------------------------------------------
-      async claim(input) {
-        const { queue, lockId, lockDuration, now } = input;
-        const lockExpiresAt = new Date(new Date(now).getTime() + lockDuration).toISOString();
-        const client = await this.pool.connect();
-        try {
-          await client.query("BEGIN");
-          const res = await client.query(
-            `SELECT * FROM qjw_jobs
-         WHERE queue  = $1
-           AND status IN ('waiting', 'delayed')
-           AND run_at <= $2::timestamptz
-           AND (lock_expires_at IS NULL OR lock_expires_at <= $2::timestamptz)
-         ORDER BY priority DESC, run_at ASC, created_at ASC
+  async getJob(queueName, jobId) {
+    const p = this.assertPool();
+    const { rows } = await p.query(
+      `SELECT payload FROM qjw_jobs WHERE queue_name = $1 AND id = $2`,
+      [queueName, jobId]
+    );
+    return rows[0]?.payload;
+  }
+  async updateJob(queueName, jobId, patch) {
+    const p = this.assertPool();
+    const patchWithTs = { ...patch, updatedAt: Date.now() };
+    const newStatus = patch.status !== void 0 ? patch.status : null;
+    const newPriority = patch.priority !== void 0 ? patch.priority : null;
+    const newRunAt = patch.runAt !== void 0 ? patch.runAt : null;
+    await p.query(
+      `UPDATE qjw_jobs
+       SET payload  = payload || $1::jsonb,
+           status   = COALESCE($2, status),
+           priority = COALESCE($3::integer, priority),
+           run_at   = COALESCE($4::bigint, run_at)
+       WHERE queue_name = $5 AND id = $6`,
+      [JSON.stringify(patchWithTs), newStatus, newPriority, newRunAt, queueName, jobId]
+    );
+  }
+  async removeJob(queueName, jobId) {
+    const p = this.assertPool();
+    await p.query(`DELETE FROM qjw_jobs WHERE queue_name = $1 AND id = $2`, [queueName, jobId]);
+  }
+  async listJobs(queueName, status) {
+    const p = this.assertPool();
+    let sql = `SELECT payload FROM qjw_jobs WHERE queue_name = $1`;
+    const params = [queueName];
+    if (status !== void 0) {
+      sql += ` AND status = $2`;
+      params.push(status);
+    }
+    sql += ` ORDER BY priority ASC, created_at ASC`;
+    const { rows } = await p.query(sql, params);
+    return rows.map((r) => r.payload);
+  }
+  async getNextJob(queueName) {
+    const p = this.assertPool();
+    const now = Date.now();
+    const { rows } = await p.query(
+      `WITH claimed AS (
+         SELECT id FROM qjw_jobs
+         WHERE queue_name = $1
+           AND status IN ('waiting', 'retrying')
+           AND run_at <= $2
+         ORDER BY priority ASC, created_at ASC
          LIMIT 1
-         FOR UPDATE SKIP LOCKED`,
-            [queue, now]
-          );
-          if (res.rows.length === 0) {
-            await client.query("ROLLBACK");
-            return null;
-          }
-          const row = res.rows[0];
-          await client.query(
-            `UPDATE qjw_jobs
-         SET status = 'active', lock_id = $1, lock_expires_at = $2, updated_at = NOW()
-         WHERE id = $3`,
-            [lockId, lockExpiresAt, row.id]
-          );
-          await client.query("COMMIT");
-          const updated = await this.pool.query("SELECT * FROM qjw_jobs WHERE id = $1", [
-            row.id
-          ]);
-          return rowToJob(updated.rows[0]);
-        } catch (err) {
-          await client.query("ROLLBACK");
-          throw err;
-        } finally {
-          client.release();
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Renew lock
-      // -------------------------------------------------------------------------
-      async renewLock(jobId, lockId, lockDuration) {
-        const newLockExpiresAt = new Date(Date.now() + lockDuration).toISOString();
-        const res = await this.pool.query(
-          `UPDATE qjw_jobs
-       SET lock_expires_at = $1::timestamptz,
-           updated_at = NOW()
-       WHERE id = $2 AND status = 'active' AND lock_id = $3 AND lock_expires_at > NOW()`,
-          [newLockExpiresAt, jobId, lockId]
-        );
-        return (res.rowCount ?? 0) > 0;
-      }
-      // -------------------------------------------------------------------------
-      // Complete
-      // -------------------------------------------------------------------------
-      async complete(jobId, lockId) {
-        if (lockId !== void 0) {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status = 'completed', lock_id = NULL, lock_expires_at = NULL,
-             completed_at = NOW(), updated_at = NOW()
-         WHERE id = $1 AND status = 'active' AND lock_id = $2`,
-            [jobId, lockId]
-          );
-        } else {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status = 'completed', lock_id = NULL, lock_expires_at = NULL,
-             completed_at = NOW(), updated_at = NOW()
-         WHERE id = $1`,
-            [jobId]
-          );
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Requeue
-      // -------------------------------------------------------------------------
-      async requeue(input) {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        const attempt = {
-          attempt: input.attemptNumber,
-          startedAt: now,
-          finishedAt: now,
-          error: input.error,
-          ...input.stack !== void 0 ? { stack: input.stack } : {}
-        };
-        if (input.lockId !== void 0) {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status          = 'waiting',
-             attempts_made   = $1,
-             attempts        = attempts || $2::jsonb,
-             run_at          = $3::timestamptz,
-             lock_id         = NULL,
-             lock_expires_at = NULL,
-             updated_at      = NOW()
-         WHERE id = $4 AND status = 'active' AND lock_id = $5`,
-            [input.attemptNumber, JSON.stringify([attempt]), input.runAt, input.jobId, input.lockId]
-          );
-        } else {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status         = 'waiting',
-             attempts_made  = $1,
-             attempts       = attempts || $2::jsonb,
-             run_at         = $3::timestamptz,
-             lock_id        = NULL,
-             lock_expires_at = NULL,
-             updated_at     = NOW()
-         WHERE id = $4`,
-            [input.attemptNumber, JSON.stringify([attempt]), input.runAt, input.jobId]
-          );
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Move to DLQ
-      // -------------------------------------------------------------------------
-      async moveToDlq(input) {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        const attempt = {
-          attempt: input.attemptNumber,
-          startedAt: now,
-          finishedAt: now,
-          error: input.error,
-          ...input.stack !== void 0 ? { stack: input.stack } : {}
-        };
-        if (input.lockId !== void 0) {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status          = 'dead',
-             attempts_made   = $1,
-             attempts        = attempts || $2::jsonb,
-             lock_id         = NULL,
-             lock_expires_at = NULL,
-             failed_at       = NOW(),
-             updated_at      = NOW()
-         WHERE id = $3 AND status = 'active' AND lock_id = $4`,
-            [input.attemptNumber, JSON.stringify([attempt]), input.jobId, input.lockId]
-          );
-        } else {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status          = 'dead',
-             attempts_made   = $1,
-             attempts        = attempts || $2::jsonb,
-             lock_id         = NULL,
-             lock_expires_at = NULL,
-             failed_at       = NOW(),
-             updated_at      = NOW()
-         WHERE id = $3`,
-            [input.attemptNumber, JSON.stringify([attempt]), input.jobId]
-          );
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Release lock
-      // -------------------------------------------------------------------------
-      async releaseLock(jobId, lockId) {
-        if (lockId !== void 0) {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET lock_id = NULL, lock_expires_at = NOW(), updated_at = NOW()
-         WHERE id = $1 AND status = 'active' AND lock_id = $2`,
-            [jobId, lockId]
-          );
-        } else {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET lock_id = NULL, lock_expires_at = NOW(), updated_at = NOW()
-         WHERE id = $1`,
-            [jobId]
-          );
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Recover stalled jobs
-      // -------------------------------------------------------------------------
-      async recoverStalledJobs(queue, now) {
-        const res = await this.pool.query(
-          `UPDATE qjw_jobs
-       SET status = 'waiting', lock_id = NULL, lock_expires_at = NULL, updated_at = NOW()
-       WHERE queue = $1
-         AND status = 'active'
-         AND lock_expires_at <= $2::timestamptz
-       RETURNING id`,
-          [queue, now]
-        );
-        return res.rows.map((r) => r.id);
-      }
-      // -------------------------------------------------------------------------
-      // Reads
-      // -------------------------------------------------------------------------
-      async getJob(jobId) {
-        const res = await this.pool.query("SELECT * FROM qjw_jobs WHERE id = $1", [jobId]);
-        if (res.rows.length === 0) return null;
-        return rowToJob(res.rows[0]);
-      }
-      async getJobs(filter) {
-        const { queue, status, limit = 100, offset = 0 } = filter;
-        const conditions = [];
-        const params = [];
-        let idx = 1;
-        if (queue !== void 0) {
-          conditions.push(`queue = $${idx++}`);
-          params.push(queue);
-        }
-        if (status !== void 0) {
-          conditions.push(`status = $${idx++}`);
-          params.push(status);
-        }
-        const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-        params.push(limit, offset);
-        const res = await this.pool.query(
-          `SELECT * FROM qjw_jobs ${where}
-       ORDER BY priority DESC, run_at ASC, created_at ASC
-       LIMIT $${idx++} OFFSET $${idx}`,
-          params
-        );
-        return res.rows.map((r) => rowToJob(r));
-      }
-      async getJobCounts(queue) {
-        const res = await this.pool.query(
-          "SELECT status, COUNT(*)::int AS count FROM qjw_jobs WHERE queue = $1 GROUP BY status",
-          [queue]
-        );
-        const counts = {
-          waiting: 0,
-          active: 0,
-          completed: 0,
-          delayed: 0,
-          dead: 0
-        };
-        for (const row of res.rows) {
-          if (row.status in counts) {
-            counts[row.status] = Number(row.count);
-          }
-        }
-        return counts;
-      }
-      // -------------------------------------------------------------------------
-      // Rate limiting
-      // -------------------------------------------------------------------------
-      async checkAndIncrementRateLimit(queue, max, windowMs, now) {
-        const nowMs = new Date(now).getTime();
-        const res = await this.pool.query(
-          "SELECT count, window_start FROM qjw_rate_limits WHERE queue = $1",
-          [queue]
-        );
-        if (res.rows.length === 0 || nowMs - Number(res.rows[0]?.window_start ?? 0) >= windowMs) {
-          await this.pool.query(
-            `INSERT INTO qjw_rate_limits (queue, count, window_start)
-         VALUES ($1, 1, $2)
-         ON CONFLICT (queue) DO UPDATE
-           SET count = 1, window_start = EXCLUDED.window_start`,
-            [queue, nowMs]
-          );
-          return true;
-        }
-        const current = res.rows[0].count;
-        if (current >= max) return false;
-        await this.pool.query("UPDATE qjw_rate_limits SET count = count + 1 WHERE queue = $1", [queue]);
-        return true;
-      }
-    };
+         FOR UPDATE SKIP LOCKED
+       ),
+       updated AS (
+         UPDATE qjw_jobs j
+         SET status  = 'active',
+             payload = j.payload || jsonb_build_object(
+                         'status',      'active',
+                         'updatedAt',   $2::bigint,
+                         'processedAt', $2::bigint
+                       )
+         FROM claimed
+         WHERE j.queue_name = $1 AND j.id = claimed.id
+         RETURNING j.payload || jsonb_build_object(
+                     'status',      'active',
+                     'updatedAt',   $2::bigint,
+                     'processedAt', $2::bigint
+                   ) AS payload
+       )
+       SELECT payload FROM updated`,
+      [queueName, now]
+    );
+    return rows[0]?.payload;
+  }
+  async clearQueue(queueName) {
+    const p = this.assertPool();
+    await p.query(`DELETE FROM qjw_jobs WHERE queue_name = $1`, [queueName]);
+  }
+  async countJobs(queueName) {
+    const p = this.assertPool();
+    const { rows } = await p.query(
+      `SELECT COUNT(*) AS count FROM qjw_jobs WHERE queue_name = $1`,
+      [queueName]
+    );
+    return parseInt(rows[0]?.count ?? "0", 10);
   }
-});
+  // ─── Private helpers ──────────────────────────────────────────────────────
+  assertPool() {
+    if (!this.pool) {
+      throw new Error(
+        "[queue-jobs-worker] PostgresStorage is not connected. Did you call client.init()?"
+      );
+    }
+    return this.pool;
+  }
+  async ensureTable() {
+    const p = this.assertPool();
+    await p.query(`
+      CREATE TABLE IF NOT EXISTS qjw_jobs (
+        id          TEXT    NOT NULL,
+        queue_name  TEXT    NOT NULL,
+        payload     JSONB   NOT NULL,
+        status      TEXT    NOT NULL,
+        priority    INTEGER NOT NULL DEFAULT 0,
+        run_at      BIGINT  NOT NULL,
+        created_at  BIGINT  NOT NULL,
+        PRIMARY KEY (queue_name, id)
+      );
+      CREATE INDEX IF NOT EXISTS qjw_jobs_next_idx
+        ON qjw_jobs (queue_name, status, priority ASC, created_at ASC);
+    `);
+  }
+};
 
-// src/storage/mysql.adapter.ts
-var mysql_adapter_exports = {};
-__export(mysql_adapter_exports, {
-  MySQLStorageAdapter: () => MySQLStorageAdapter
-});
-async function loadMySQL2() {
-  try {
-    return await import('mysql2/promise');
-  } catch {
-    throw new Error(
-      'MySQLStorageAdapter requires the "mysql2" package.\nInstall it: npm install mysql2'
+// src/storage/mysql.storage.ts
+var MysqlStorage = class {
+  pool = null;
+  connectionString;
+  constructor(connectionString) {
+    this.connectionString = connectionString;
+  }
+  // ─── IStorage ─────────────────────────────────────────────────────────────
+  async connect() {
+    let mysql2Module;
+    try {
+      mysql2Module = await import("mysql2/promise");
+    } catch {
+      throw new Error(
+        "[queue-jobs-worker] MySQL dialect requires the `mysql2` package. Run: npm install mysql2"
+      );
+    }
+    this.pool = mysql2Module.createPool({
+      uri: this.connectionString,
+      waitForConnections: true,
+      connectionLimit: 10
+    });
+    await this.ensureTable();
+  }
+  async disconnect() {
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = null;
+    }
+  }
+  async saveJob(queueName, job) {
+    const p = this.assertPool();
+    await p.execute(
+      `INSERT INTO qjw_jobs (id, queue_name, payload, status, priority, run_at, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON DUPLICATE KEY UPDATE
+         payload    = VALUES(payload),
+         status     = VALUES(status),
+         priority   = VALUES(priority),
+         run_at     = VALUES(run_at)`,
+      [job.id, queueName, JSON.stringify(job), job.status, job.priority, job.runAt, job.createdAt]
     );
   }
-}
-function rowToJob2(row) {
-  const payload = typeof row.payload === "string" ? JSON.parse(row.payload) : row.payload;
-  const attempts = typeof row.attempts === "string" ? JSON.parse(row.attempts) : row.attempts ?? [];
-  const job = {
-    id: row.id,
-    queue: row.queue,
-    type: row.type,
-    payload,
-    status: row.status,
-    attemptsMade: Number(row.attempts_made),
-    maxAttempts: Number(row.max_attempts),
-    retryDelay: Number(row.retry_delay),
-    backoff: row.backoff,
-    timeout: Number(row.timeout),
-    priority: Number(row.priority),
-    runAt: row.run_at instanceof Date ? row.run_at.toISOString() : String(row.run_at),
-    attempts,
-    lockId: row.lock_id,
-    lockExpiresAt: row.lock_expires_at instanceof Date ? row.lock_expires_at.toISOString() : null,
-    createdAt: row.created_at instanceof Date ? row.created_at.toISOString() : String(row.created_at),
-    updatedAt: row.updated_at instanceof Date ? row.updated_at.toISOString() : String(row.updated_at),
-    completedAt: row.completed_at instanceof Date ? row.completed_at.toISOString() : null,
-    failedAt: row.failed_at instanceof Date ? row.failed_at.toISOString() : null
-  };
-  if (row.cron) job.cron = row.cron;
-  return job;
-}
-var CREATE_JOBS_TABLE2, CREATE_RATE_TABLE2, MySQLStorageAdapter;
-var init_mysql_adapter = __esm({
-  "src/storage/mysql.adapter.ts"() {
-    CREATE_JOBS_TABLE2 = `
-CREATE TABLE IF NOT EXISTS qjw_jobs (
-  id               VARCHAR(36)  NOT NULL PRIMARY KEY,
-  queue            VARCHAR(255) NOT NULL,
-  type             VARCHAR(255) NOT NULL,
-  payload          JSON         NOT NULL,
-  status           VARCHAR(20)  NOT NULL DEFAULT 'waiting',
-  attempts_made    INT          NOT NULL DEFAULT 0,
-  max_attempts     INT          NOT NULL DEFAULT 3,
-  retry_delay      INT          NOT NULL DEFAULT 1000,
-  backoff          VARCHAR(20)  NOT NULL DEFAULT 'exponential',
-  timeout          INT          NOT NULL DEFAULT 30000,
-  priority         INT          NOT NULL DEFAULT 0,
-  run_at           DATETIME(3)  NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
-  cron             VARCHAR(255),
-  attempts         JSON         NOT NULL,
-  lock_id          VARCHAR(255),
-  lock_expires_at  DATETIME(3),
-  created_at       DATETIME(3)  NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
-  updated_at       DATETIME(3)  NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
-  completed_at     DATETIME(3),
-  failed_at        DATETIME(3),
-  INDEX qjw_jobs_claim_idx (queue, status, run_at, priority)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-`;
-    CREATE_RATE_TABLE2 = `
-CREATE TABLE IF NOT EXISTS qjw_rate_limits (
-  queue        VARCHAR(255) NOT NULL PRIMARY KEY,
-  count        INT          NOT NULL DEFAULT 0,
-  window_start BIGINT       NOT NULL DEFAULT 0
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-`;
-    MySQLStorageAdapter = class {
-      pool;
-      connectionString;
-      constructor(connectionString) {
-        this.connectionString = connectionString;
-      }
-      // -------------------------------------------------------------------------
-      // Lifecycle
-      // -------------------------------------------------------------------------
-      async initialize() {
-        const mysql2 = await loadMySQL2();
-        this.pool = mysql2.createPool({
-          uri: this.connectionString,
-          waitForConnections: true,
-          connectionLimit: 10,
-          queueLimit: 0
-        });
-        const conn = await this.pool.getConnection();
-        try {
-          await conn.query("SELECT 1");
-          await conn.query(CREATE_JOBS_TABLE2);
-          await conn.query(CREATE_RATE_TABLE2);
-        } finally {
-          conn.release();
-        }
-      }
-      async close() {
-        if (this.pool) {
-          await this.pool.end();
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Enqueue
-      // -------------------------------------------------------------------------
-      async enqueue(input) {
-        const runAtMs = new Date(input.runAt).getTime();
-        const isDelayed = runAtMs > Date.now();
-        const status = isDelayed ? "delayed" : "waiting";
-        await this.pool.query(
-          `INSERT IGNORE INTO qjw_jobs
-         (id, queue, type, payload, status, attempts_made, max_attempts,
-          retry_delay, backoff, timeout, priority, run_at, cron,
-          attempts, lock_id, lock_expires_at, created_at, updated_at,
-          completed_at, failed_at)
-       VALUES (?,?,?,?,?,0,?,?,?,?,?,?,?,?,NULL,NULL,NOW(3),NOW(3),NULL,NULL)`,
-          [
-            input.id,
-            input.queue,
-            input.type,
-            JSON.stringify(input.payload),
-            status,
-            input.maxAttempts,
-            input.retryDelay,
-            input.backoff,
-            input.timeout,
-            input.priority,
-            input.runAt,
-            input.cron ?? null,
-            JSON.stringify([])
-          ]
-        );
-        const rows = await this.pool.query("SELECT * FROM qjw_jobs WHERE id = ?", [input.id]);
-        const row = rows[0][0];
-        return rowToJob2(row);
-      }
-      // -------------------------------------------------------------------------
-      // Claim  (transaction + SELECT … FOR UPDATE SKIP LOCKED)
-      // -------------------------------------------------------------------------
-      async claim(input) {
-        const { queue, lockId, lockDuration, now } = input;
-        const lockExpiresAt = new Date(new Date(now).getTime() + lockDuration).toISOString().slice(0, 23).replace("T", " ");
-        const nowMysql = new Date(now).toISOString().slice(0, 23).replace("T", " ");
-        const conn = await this.pool.getConnection();
-        try {
-          await conn.beginTransaction();
-          const [rows] = await conn.query(
-            `SELECT * FROM qjw_jobs
-         WHERE queue  = ?
-           AND status IN ('waiting', 'delayed')
+  async getJob(queueName, jobId) {
+    const p = this.assertPool();
+    const [rows] = await p.execute(
+      `SELECT payload FROM qjw_jobs WHERE queue_name = ? AND id = ? LIMIT 1`,
+      [queueName, jobId]
+    );
+    const row = rows[0];
+    if (!row) return void 0;
+    const raw = typeof row.payload === "string" ? JSON.parse(row.payload) : row.payload;
+    return raw;
+  }
+  async updateJob(queueName, jobId, patch) {
+    const p = this.assertPool();
+    const patchWithTs = { ...patch, updatedAt: Date.now() };
+    const newStatus = patch.status !== void 0 ? patch.status : null;
+    const newPriority = patch.priority !== void 0 ? patch.priority : null;
+    const newRunAt = patch.runAt !== void 0 ? patch.runAt : null;
+    await p.execute(
+      `UPDATE qjw_jobs
+       SET payload   = JSON_MERGE_PATCH(payload, ?),
+           status    = COALESCE(?, status),
+           priority  = COALESCE(?, priority),
+           run_at    = COALESCE(?, run_at)
+       WHERE queue_name = ? AND id = ?`,
+      [JSON.stringify(patchWithTs), newStatus, newPriority, newRunAt, queueName, jobId]
+    );
+  }
+  async removeJob(queueName, jobId) {
+    const p = this.assertPool();
+    await p.execute(`DELETE FROM qjw_jobs WHERE queue_name = ? AND id = ?`, [queueName, jobId]);
+  }
+  async listJobs(queueName, status) {
+    const p = this.assertPool();
+    let sql = `SELECT payload FROM qjw_jobs WHERE queue_name = ?`;
+    const params = [queueName];
+    if (status !== void 0) {
+      sql += ` AND status = ?`;
+      params.push(status);
+    }
+    sql += ` ORDER BY priority ASC, created_at ASC`;
+    const [rows] = await p.execute(sql, params);
+    return rows.map((r) => {
+      const raw = typeof r.payload === "string" ? JSON.parse(r.payload) : r.payload;
+      return raw;
+    });
+  }
+  async getNextJob(queueName) {
+    const p = this.assertPool();
+    const now = Date.now();
+    const conn = await p.getConnection();
+    try {
+      await conn.beginTransaction();
+      const [rows] = await conn.execute(
+        `SELECT id, payload FROM qjw_jobs
+         WHERE queue_name = ?
+           AND status IN ('waiting', 'retrying')
            AND run_at <= ?
-           AND (lock_expires_at IS NULL OR lock_expires_at <= ?)
-         ORDER BY priority DESC, run_at ASC, created_at ASC
+         ORDER BY priority ASC, created_at ASC
          LIMIT 1
          FOR UPDATE SKIP LOCKED`,
-            [queue, nowMysql, nowMysql]
-          );
-          if (!rows || rows.length === 0) {
-            await conn.rollback();
-            return null;
-          }
-          const row = rows[0];
-          await conn.query(
-            `UPDATE qjw_jobs
-         SET status = 'active', lock_id = ?, lock_expires_at = ?, updated_at = NOW(3)
-         WHERE id = ?`,
-            [lockId, lockExpiresAt, row.id]
-          );
-          await conn.commit();
-          const [updated] = await this.pool.query("SELECT * FROM qjw_jobs WHERE id = ?", [
-            row.id
-          ]);
-          return rowToJob2(updated[0]);
-        } catch (err) {
-          await conn.rollback();
-          throw err;
-        } finally {
-          conn.release();
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Renew lock
-      // -------------------------------------------------------------------------
-      async renewLock(jobId, lockId, lockDuration) {
-        const newLockExpiresAt = new Date(Date.now() + lockDuration).toISOString().slice(0, 23).replace("T", " ");
-        const [result] = await this.pool.query(
-          `UPDATE qjw_jobs
-       SET lock_expires_at = ?, updated_at = NOW(3)
-       WHERE id = ? AND status = 'active' AND lock_id = ? AND lock_expires_at > NOW(3)`,
-          [newLockExpiresAt, jobId, lockId]
-        );
-        return result.affectedRows > 0;
-      }
-      // -------------------------------------------------------------------------
-      // Complete
-      // -------------------------------------------------------------------------
-      async complete(jobId, lockId) {
-        if (lockId !== void 0) {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status = 'completed', lock_id = NULL, lock_expires_at = NULL,
-             completed_at = NOW(3), updated_at = NOW(3)
-         WHERE id = ? AND status = 'active' AND lock_id = ?`,
-            [jobId, lockId]
-          );
-        } else {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status = 'completed', lock_id = NULL, lock_expires_at = NULL,
-             completed_at = NOW(3), updated_at = NOW(3)
-         WHERE id = ?`,
-            [jobId]
-          );
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Requeue
-      // -------------------------------------------------------------------------
-      async requeue(input) {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        const attempt = JSON.stringify({
-          attempt: input.attemptNumber,
-          startedAt: now,
-          finishedAt: now,
-          error: input.error,
-          ...input.stack !== void 0 ? { stack: input.stack } : {}
-        });
-        if (input.lockId !== void 0) {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status          = 'waiting',
-             attempts_made   = attempts_made + 1,
-             attempts        = JSON_ARRAY_APPEND(attempts, '$', CAST(? AS JSON)),
-             run_at          = ?,
-             lock_id         = NULL,
-             lock_expires_at = NULL,
-             updated_at      = NOW(3)
-         WHERE id = ? AND status = 'active' AND lock_id = ?`,
-            [attempt, input.runAt, input.jobId, input.lockId]
-          );
-        } else {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status          = 'waiting',
-             attempts_made   = attempts_made + 1,
-             attempts        = JSON_ARRAY_APPEND(attempts, '$', CAST(? AS JSON)),
-             run_at          = ?,
-             lock_id         = NULL,
-             lock_expires_at = NULL,
-             updated_at      = NOW(3)
-         WHERE id = ?`,
-            [attempt, input.runAt, input.jobId]
-          );
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Move to DLQ
-      // -------------------------------------------------------------------------
-      async moveToDlq(input) {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        const attempt = JSON.stringify({
-          attempt: input.attemptNumber,
-          startedAt: now,
-          finishedAt: now,
-          error: input.error,
-          ...input.stack !== void 0 ? { stack: input.stack } : {}
-        });
-        if (input.lockId !== void 0) {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status          = 'dead',
-             attempts_made   = attempts_made + 1,
-             attempts        = JSON_ARRAY_APPEND(attempts, '$', CAST(? AS JSON)),
-             lock_id         = NULL,
-             lock_expires_at = NULL,
-             failed_at       = NOW(3),
-             updated_at      = NOW(3)
-         WHERE id = ? AND status = 'active' AND lock_id = ?`,
-            [attempt, input.jobId, input.lockId]
-          );
-        } else {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET status          = 'dead',
-             attempts_made   = attempts_made + 1,
-             attempts        = JSON_ARRAY_APPEND(attempts, '$', CAST(? AS JSON)),
-             lock_id         = NULL,
-             lock_expires_at = NULL,
-             failed_at       = NOW(3),
-             updated_at      = NOW(3)
-         WHERE id = ?`,
-            [attempt, input.jobId]
-          );
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Release lock
-      // -------------------------------------------------------------------------
-      async releaseLock(jobId, lockId) {
-        if (lockId !== void 0) {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET lock_id = NULL, lock_expires_at = NOW(3), updated_at = NOW(3)
-         WHERE id = ? AND status = 'active' AND lock_id = ?`,
-            [jobId, lockId]
-          );
-        } else {
-          await this.pool.query(
-            `UPDATE qjw_jobs
-         SET lock_id = NULL, lock_expires_at = NOW(3), updated_at = NOW(3)
-         WHERE id = ?`,
-            [jobId]
-          );
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Recover stalled jobs  (atomic — SELECT … FOR UPDATE inside transaction)
-      // -------------------------------------------------------------------------
-      async recoverStalledJobs(queue, now) {
-        const nowMysql = new Date(now).toISOString().slice(0, 23).replace("T", " ");
-        const conn = await this.pool.getConnection();
-        try {
-          await conn.beginTransaction();
-          const [rows] = await conn.query(
-            `SELECT id FROM qjw_jobs
-         WHERE queue = ?
-           AND status = 'active'
-           AND lock_expires_at <= ?
-         FOR UPDATE SKIP LOCKED`,
-            [queue, nowMysql]
-          );
-          const ids = rows.map((r) => String(r["id"]));
-          if (ids.length > 0) {
-            await conn.query(
-              `UPDATE qjw_jobs
-           SET status = 'waiting', lock_id = NULL, lock_expires_at = NULL, updated_at = NOW(3)
-           WHERE id IN (?)`,
-              [ids]
-            );
-          }
-          await conn.commit();
-          return ids;
-        } catch (err) {
-          await conn.rollback();
-          throw err;
-        } finally {
-          conn.release();
-        }
-      }
-      // -------------------------------------------------------------------------
-      // Reads
-      // -------------------------------------------------------------------------
-      async getJob(jobId) {
-        const [rows] = await this.pool.query("SELECT * FROM qjw_jobs WHERE id = ?", [jobId]);
-        const list = rows;
-        if (!list || list.length === 0) return null;
-        return rowToJob2(list[0]);
-      }
-      async getJobs(filter) {
-        const { queue, status, limit = 100, offset = 0 } = filter;
-        const conditions = [];
-        const params = [];
-        if (queue !== void 0) {
-          conditions.push("queue = ?");
-          params.push(queue);
-        }
-        if (status !== void 0) {
-          conditions.push("status = ?");
-          params.push(status);
-        }
-        const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-        params.push(limit, offset);
-        const [rows] = await this.pool.query(
-          `SELECT * FROM qjw_jobs ${where}
-       ORDER BY priority DESC, run_at ASC, created_at ASC
-       LIMIT ? OFFSET ?`,
-          params
-        );
-        return rows.map((r) => rowToJob2(r));
-      }
-      async getJobCounts(queue) {
-        const [rows] = await this.pool.query(
-          "SELECT status, COUNT(*) AS count FROM qjw_jobs WHERE queue = ? GROUP BY status",
-          [queue]
-        );
-        const counts = {
-          waiting: 0,
-          active: 0,
-          completed: 0,
-          delayed: 0,
-          dead: 0
-        };
-        for (const row of rows) {
-          const s = String(row["status"]);
-          if (s in counts) counts[s] = Number(row["count"]);
-        }
-        return counts;
-      }
-      // -------------------------------------------------------------------------
-      // Rate limiting
-      // -------------------------------------------------------------------------
-      async checkAndIncrementRateLimit(queue, max, windowMs, now) {
-        const nowMs = new Date(now).getTime();
-        const [rows] = await this.pool.query(
-          "SELECT count, window_start FROM qjw_rate_limits WHERE queue = ?",
-          [queue]
-        );
-        const existing = rows[0];
-        if (!existing || nowMs - Number(existing["window_start"]) >= windowMs) {
-          await this.pool.query(
-            `INSERT INTO qjw_rate_limits (queue, count, window_start) VALUES (?,1,?)
-         ON DUPLICATE KEY UPDATE count = 1, window_start = VALUES(window_start)`,
-            [queue, nowMs]
-          );
-          return true;
-        }
-        if (Number(existing["count"]) >= max) return false;
-        await this.pool.query("UPDATE qjw_rate_limits SET count = count + 1 WHERE queue = ?", [queue]);
-        return true;
+        [queueName, now]
+      );
+      const row = rows[0];
+      if (!row) {
+        await conn.commit();
+        return void 0;
       }
-    };
+      const jobId = row.id;
+      const raw = typeof row.payload === "string" ? JSON.parse(row.payload) : row.payload;
+      const job = raw;
+      const updated = {
+        ...job,
+        status: "active",
+        updatedAt: now,
+        processedAt: now
+      };
+      await conn.execute(
+        `UPDATE qjw_jobs
+         SET payload = ?, status = 'active', run_at = run_at
+         WHERE queue_name = ? AND id = ?`,
+        [JSON.stringify(updated), queueName, jobId]
+      );
+      await conn.commit();
+      return updated;
+    } catch (err) {
+      await conn.rollback().catch(() => void 0);
+      throw err;
+    } finally {
+      conn.release();
+    }
   }
-});
-
-// src/core/job.ts
-var Job = class {
-  /** @internal Raw data record — treat as immutable outside storage layer. */
-  _data;
-  constructor(data) {
-    this._data = data;
-  }
-  // -------------------------------------------------------------------------
-  // Identity
-  // -------------------------------------------------------------------------
-  /** Unique, stable job identifier. */
-  get id() {
-    return this._data.id;
-  }
-  /** Name of the queue this job belongs to. */
-  get queue() {
-    return this._data.queue;
-  }
-  /** Application-defined job type (matches the registered processor). */
-  get type() {
-    return this._data.type;
-  }
-  // -------------------------------------------------------------------------
-  // Payload
-  // -------------------------------------------------------------------------
-  /**
-   * User-supplied job payload.
-   * Never log this value — it may contain sensitive data.
-   */
-  get data() {
-    return this._data.payload;
-  }
-  // -------------------------------------------------------------------------
-  // Status & attempts
-  // -------------------------------------------------------------------------
-  /** Current lifecycle status. */
-  get status() {
-    return this._data.status;
-  }
-  /** Number of attempts already executed (0 = not yet started). */
-  get attemptsMade() {
-    return this._data.attemptsMade;
-  }
-  /** Maximum allowed attempts. */
-  get maxAttempts() {
-    return this._data.maxAttempts;
-  }
-  /** How many attempts remain (including the current one). */
-  get attemptsRemaining() {
-    return Math.max(0, this._data.maxAttempts - this._data.attemptsMade);
-  }
-  /** Ordered list of past attempt records. */
-  get attemptHistory() {
-    return this._data.attempts;
-  }
-  // -------------------------------------------------------------------------
-  // Retry configuration
-  // -------------------------------------------------------------------------
-  /** Base delay in ms between retry attempts. */
-  get retryDelay() {
-    return this._data.retryDelay;
-  }
-  /** Backoff strategy applied on retry. */
-  get backoff() {
-    return this._data.backoff;
-  }
-  // -------------------------------------------------------------------------
-  // Execution config
-  // -------------------------------------------------------------------------
-  /** Per-attempt timeout in ms. */
-  get timeout() {
-    return this._data.timeout;
-  }
-  /** Processing priority — higher numbers are processed first. */
-  get priority() {
-    return this._data.priority;
-  }
-  // -------------------------------------------------------------------------
-  // Scheduling
-  // -------------------------------------------------------------------------
-  /** ISO timestamp when this job is eligible to run. */
-  get runAt() {
-    return this._data.runAt;
-  }
-  /** Cron expression for recurring jobs, or undefined. */
-  get cron() {
-    return this._data.cron;
-  }
-  // -------------------------------------------------------------------------
-  // Lock
-  // -------------------------------------------------------------------------
-  /** ID of the worker currently holding the lock, or null. */
-  get lockId() {
-    return this._data.lockId;
-  }
-  /** ISO timestamp when the current lock expires, or null. */
-  get lockExpiresAt() {
-    return this._data.lockExpiresAt;
-  }
-  // -------------------------------------------------------------------------
-  // Timestamps
-  // -------------------------------------------------------------------------
-  /** ISO timestamp when the job was first enqueued. */
-  get createdAt() {
-    return this._data.createdAt;
-  }
-  /** ISO timestamp of the last status change. */
-  get updatedAt() {
-    return this._data.updatedAt;
-  }
-  /** ISO timestamp when the job completed successfully, or null. */
-  get completedAt() {
-    return this._data.completedAt;
-  }
-  /** ISO timestamp when the job was moved to the DLQ, or null. */
-  get failedAt() {
-    return this._data.failedAt;
-  }
-  // -------------------------------------------------------------------------
-  // Derived helpers
-  // -------------------------------------------------------------------------
-  /** Returns true when the job has been successfully processed. */
-  isCompleted() {
-    return this._data.status === "completed";
-  }
-  /** Returns true when the job is in the Dead Letter Queue. */
-  isDead() {
-    return this._data.status === "dead";
-  }
-  /** Returns true when the job is currently being processed by a worker. */
-  isActive() {
-    return this._data.status === "active";
-  }
-  /** Returns true when the job is waiting to be claimed. */
-  isWaiting() {
-    return this._data.status === "waiting";
-  }
-  /** Returns true when the job is scheduled for a future time. */
-  isDelayed() {
-    return this._data.status === "delayed";
-  }
-  // -------------------------------------------------------------------------
-  // Debug representation (intentionally omits payload)
-  // -------------------------------------------------------------------------
-  toJSON() {
-    return {
-      id: this._data.id,
-      queue: this._data.queue,
-      type: this._data.type,
-      status: this._data.status,
-      attemptsMade: this._data.attemptsMade,
-      maxAttempts: this._data.maxAttempts,
-      priority: this._data.priority,
-      runAt: this._data.runAt,
-      createdAt: this._data.createdAt,
-      updatedAt: this._data.updatedAt,
-      completedAt: this._data.completedAt,
-      failedAt: this._data.failedAt
-      // Payload intentionally excluded to prevent accidental logging.
-    };
+  async clearQueue(queueName) {
+    const p = this.assertPool();
+    await p.execute(`DELETE FROM qjw_jobs WHERE queue_name = ?`, [queueName]);
   }
-  toString() {
-    return `Job(${this._data.id}, type=${this._data.type}, status=${this._data.status}, attempt=${this._data.attemptsMade}/${this._data.maxAttempts})`;
+  async countJobs(queueName) {
+    const p = this.assertPool();
+    const [rows] = await p.execute(
+      `SELECT COUNT(*) AS count FROM qjw_jobs WHERE queue_name = ?`,
+      [queueName]
+    );
+    const row = rows[0];
+    if (!row) return 0;
+    return parseInt(String(row.count ?? 0), 10);
+  }
+  // ─── Private helpers ──────────────────────────────────────────────────────
+  assertPool() {
+    if (!this.pool) {
+      throw new Error(
+        "[queue-jobs-worker] MysqlStorage is not connected. Did you call client.init()?"
+      );
+    }
+    return this.pool;
+  }
+  async ensureTable() {
+    const p = this.assertPool();
+    await p.execute(`
+      CREATE TABLE IF NOT EXISTS qjw_jobs (
+        id          VARCHAR(36)  NOT NULL,
+        queue_name  VARCHAR(255) NOT NULL,
+        payload     JSON         NOT NULL,
+        status      VARCHAR(20)  NOT NULL,
+        priority    INT          NOT NULL DEFAULT 0,
+        run_at      BIGINT       NOT NULL,
+        created_at  BIGINT       NOT NULL,
+        PRIMARY KEY (queue_name, id),
+        INDEX qjw_jobs_next_idx (queue_name, status, priority ASC, created_at ASC)
+      ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+    `);
   }
 };
 
-// src/core/backoff.ts
-var MAX_DELAY_MS = 10 * 60 * 1e3;
-function calculateBackoff(strategy, baseDelay, attemptNumber) {
-  const attempt = Math.max(1, attemptNumber);
-  switch (strategy) {
-    case "fixed":
-      return baseDelay;
-    case "linear":
-      return baseDelay * attempt;
-    case "exponential": {
-      const delay = baseDelay * Math.pow(2, attempt - 1);
-      return Math.min(delay, MAX_DELAY_MS);
-    }
+// src/utils/resolve-storage.ts
+function resolveStorage(dialect, connectionString) {
+  switch (dialect) {
+    case "memory":
+      return new MemoryStorage();
+    case "redis":
+      assertConnectionString(dialect, connectionString);
+      return new RedisStorage(connectionString);
+    case "postgres":
+      assertConnectionString(dialect, connectionString);
+      return new PostgresStorage(connectionString);
+    case "mysql":
+      assertConnectionString(dialect, connectionString);
+      return new MysqlStorage(connectionString);
     default: {
-      return baseDelay;
+      const _unreachable = dialect;
+      throw new Error(
+        `[queue-jobs-worker] Unknown storage dialect: "${String(_unreachable)}". Valid options are: "memory", "redis", "postgres", "mysql".`
+      );
     }
   }
 }
-function nextRunAt(delayMs, fromDate = /* @__PURE__ */ new Date()) {
-  return new Date(fromDate.getTime() + delayMs).toISOString();
+function assertConnectionString(dialect, connectionString) {
+  if (!connectionString) {
+    throw new Error(
+      `[queue-jobs-worker] Dialect "${dialect}" requires a connectionString. Example: { dialect: "${dialect}", connectionString: "${exampleDsn(dialect)}" }`
+    );
+  }
 }
-function generateJobId() {
-  return randomUUID();
+function exampleDsn(dialect) {
+  switch (dialect) {
+    case "redis":
+      return "redis://localhost:6379";
+    case "postgres":
+      return "postgresql://user:pass@localhost:5432/mydb";
+    case "mysql":
+      return "mysql://user:pass@localhost:3306/mydb";
+    default:
+      return "";
+  }
 }
 
-// src/core/worker.ts
-function resolveConfig(workerOptions, queueOptions, defaults) {
-  return {
-    concurrency: workerOptions.concurrency ?? queueOptions.concurrency ?? defaults.concurrency,
-    shutdownTimeout: workerOptions.shutdownTimeout ?? 3e4,
-    pollInterval: queueOptions.pollInterval ?? defaults.pollInterval,
-    stalledInterval: queueOptions.stalledInterval ?? defaults.stalledInterval,
-    lockDuration: queueOptions.lockDuration ?? defaults.lockDuration,
-    rateLimit: queueOptions.rateLimit ?? defaults.rateLimit
-  };
-}
-var Worker = class {
-  /** Unique identifier for this worker instance. */
-  id;
-  queueName;
-  storage;
-  emitter;
-  processors;
-  config;
-  _status = "idle";
-  activeCount = 0;
-  /**
-   * Tracks job IDs currently being processed so we can release their locks
-   * when graceful shutdown times out before they finish.
-   */
-  activeJobIds = /* @__PURE__ */ new Set();
-  pollTimer = null;
-  stalledTimer = null;
-  /** Resolves when all active jobs finish during shutdown. */
-  drainResolve = null;
-  constructor(queueName, storage, emitter, processors, workerOptions, queueOptions, defaults) {
-    this.id = `worker:${queueName}:${randomUUID()}`;
-    this.queueName = queueName;
-    this.storage = storage;
-    this.emitter = emitter;
-    this.processors = processors;
-    this.config = resolveConfig(workerOptions, queueOptions, defaults);
-  }
-  // -------------------------------------------------------------------------
-  // Public API
-  // -------------------------------------------------------------------------
-  get status() {
-    return this._status;
-  }
-  /** Start polling for jobs. */
-  start() {
-    if (this._status !== "idle" && this._status !== "stopped") {
-      return;
+// src/constants/client.constants.ts
+var DEFAULT_QUEUE_CONFIG = {
+  attempts: 3,
+  retryDelay: 1e3,
+  // 1 second base delay
+  backoff: "exponential",
+  timeout: 3e4
+  // 30 seconds
+};
+
+// src/classes/client.ts
+var QueueClient = class _QueueClient {
+  // ── Singleton default ───────────────────────────────────────────────────
+  static _default;
+  // ── Instance state ───────────────────────────────────────────────────────
+  _dialect;
+  _connectionString;
+  _debug;
+  _config;
+  _storage = null;
+  _initialized = false;
+  _closed = false;
+  constructor(opts) {
+    this._dialect = opts.dialect;
+    this._debug = opts.debug ?? false;
+    this._config = { ...DEFAULT_QUEUE_CONFIG, ...opts.options };
+    if (opts.connectionString !== void 0) {
+      this._connectionString = opts.connectionString;
     }
-    this._status = "running";
-    this.emitter.emit("worker:started", this.id);
-    this.emitter.emit("worker:status", this.id, this._status);
-    this.schedulePoll();
-    this.scheduleStallCheck();
   }
+  // ── Lifecycle ────────────────────────────────────────────────────────────
   /**
-   * Gracefully stop the worker.
+   * Open the storage connection and mark this client as ready.
    *
-   * 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.
+   * 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()
    */
-  async stop() {
-    if (this._status === "stopped" || this._status === "stopping") {
-      return;
-    }
-    this._status = "stopping";
-    this.emitter.emit("worker:status", this.id, this._status);
-    if (this.pollTimer) {
-      clearTimeout(this.pollTimer);
-      this.pollTimer = null;
-    }
-    if (this.stalledTimer) {
-      clearTimeout(this.stalledTimer);
-      this.stalledTimer = null;
-    }
-    if (this.activeCount > 0) {
-      await Promise.race([
-        new Promise((resolve) => {
-          this.drainResolve = resolve;
-        }),
-        new Promise((resolve) => setTimeout(resolve, this.config.shutdownTimeout))
-      ]);
+  async init() {
+    if (this._initialized) {
+      throw new Error("[queue-jobs-worker] QueueClient is already initialized.");
     }
-    if (this.activeJobIds.size > 0) {
-      await Promise.all(
-        Array.from(this.activeJobIds).map(
-          (jobId) => this.storage.releaseLock(jobId, this.id).catch(() => {
-          })
-        )
+    if (this._closed) {
+      throw new Error(
+        "[queue-jobs-worker] QueueClient has been closed and cannot be re-initialized. Create a new instance instead."
       );
     }
-    this._status = "stopped";
-    this.emitter.emit("worker:stopped", this.id);
-    this.emitter.emit("worker:status", this.id, this._status);
-  }
-  // -------------------------------------------------------------------------
-  // Poll loop
-  // -------------------------------------------------------------------------
-  schedulePoll() {
-    if (this._status !== "running") return;
-    this.pollTimer = setTimeout(() => {
-      void this.poll();
-    }, this.config.pollInterval);
-  }
-  async poll() {
-    if (this._status !== "running") return;
-    try {
-      while (this._status === "running" && this.activeCount < this.config.concurrency) {
-        const claimed = await this.claimNext();
-        if (!claimed) break;
-      }
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      this.emitter.emit("queue:error", this.queueName, error);
-      this.emitter.emit("worker:error", this.id, error);
-    }
-    this.schedulePoll();
-  }
-  // -------------------------------------------------------------------------
-  // Claim & execute
-  // -------------------------------------------------------------------------
-  async claimNext() {
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const raw = await this.storage.claim({
-      queue: this.queueName,
-      lockId: this.id,
-      lockDuration: this.config.lockDuration,
-      now
-    });
-    if (!raw) return false;
-    if (this.config.rateLimit) {
-      const allowed = await this.storage.checkAndIncrementRateLimit(
-        this.queueName,
-        this.config.rateLimit.max,
-        this.config.rateLimit.duration,
-        now
-      );
-      if (!allowed) {
-        await this.storage.releaseLock(raw.id, this.id);
-        return false;
-      }
+    this._storage = resolveStorage(this._dialect, this._connectionString);
+    await this._storage.connect();
+    this._initialized = true;
+    if (!_QueueClient._default) {
+      _QueueClient._default = this;
     }
-    const job = new Job(raw);
-    this.activeCount += 1;
-    this.activeJobIds.add(job.id);
-    void this.executeJob(job);
-    return true;
-  }
-  async executeJob(job) {
-    this.emitter.emit("job:started", job._data);
-    const processor = this.processors.get(job.type);
-    if (!processor) {
-      const error = new Error(
-        `No processor registered for job type "${job.type}" in queue "${this.queueName}"`
-      );
-      await this.handleFailure(job, error);
-      return;
+    this._log(`QueueClient initialized (dialect: ${this._dialect})`);
+    return 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.
+   */
+  async close() {
+    if (this._closed) return;
+    if (!this._initialized) {
+      throw new Error("[queue-jobs-worker] Cannot close a QueueClient that was never initialized.");
     }
-    const abortController = new AbortController();
-    let timeoutHandle = null;
-    let lockRenewTimer = null;
-    const lockRenewInterval = Math.max(100, Math.floor(this.config.lockDuration / 2));
-    lockRenewTimer = setInterval(async () => {
-      try {
-        const renewed = await this.storage.renewLock(job.id, this.id, this.config.lockDuration);
-        if (!renewed && lockRenewTimer) {
-          clearInterval(lockRenewTimer);
-          lockRenewTimer = null;
-        }
-      } catch {
-      }
-    }, lockRenewInterval);
-    try {
-      await new Promise((resolve, reject) => {
-        timeoutHandle = setTimeout(() => {
-          const timeoutError = new Error(`Job timed out after ${job.timeout}ms`);
-          abortController.abort(timeoutError);
-          reject(timeoutError);
-        }, job.timeout);
-        Promise.resolve(processor(job, abortController.signal)).then(resolve, reject);
-      });
-      if (timeoutHandle) clearTimeout(timeoutHandle);
-      if (lockRenewTimer) {
-        clearInterval(lockRenewTimer);
-        lockRenewTimer = null;
-      }
-      await this.storage.complete(job.id, this.id);
-      const completedData = await this.storage.getJob(job.id) ?? job._data;
-      this.emitter.emit("job:completed", completedData);
-      if (job.cron) {
-        await this.enqueueCronNext(job);
-      }
-    } catch (err) {
-      if (timeoutHandle) clearTimeout(timeoutHandle);
-      if (lockRenewTimer) {
-        clearInterval(lockRenewTimer);
-        lockRenewTimer = null;
-      }
-      const error = err instanceof Error ? err : new Error(String(err));
-      await this.handleFailure(job, error);
-    } finally {
-      if (lockRenewTimer) {
-        clearInterval(lockRenewTimer);
-        lockRenewTimer = null;
-      }
-      this.activeJobIds.delete(job.id);
-      this.activeCount -= 1;
-      if (this.activeCount === 0 && this.drainResolve) {
-        this.drainResolve();
-        this.drainResolve = null;
-      }
+    await this._storage.disconnect();
+    this._closed = true;
+    this._initialized = false;
+    if (_QueueClient._default === this) {
+      _QueueClient._default = void 0;
     }
+    this._log("QueueClient closed.");
   }
-  // -------------------------------------------------------------------------
-  // Cron — re-enqueue the next occurrence after a successful run
-  // -------------------------------------------------------------------------
-  async enqueueCronNext(job) {
-    try {
-      let nextDate;
-      try {
-        const cronInstance = new Cron(job.cron);
-        nextDate = cronInstance.nextRun();
-      } catch (cronErr) {
-        const error = cronErr instanceof Error ? cronErr : new Error(
-          `croner failed to initialize for expression "${job.cron}": ${String(cronErr)}`
-        );
-        this.emitter.emit("worker:error", this.id, error);
-        return;
-      }
-      if (nextDate === null) {
-        const error = new Error(
-          `Cron expression "${job.cron}" has no future occurrences \u2014 job "${job.id}" will not be re-enqueued`
-        );
-        this.emitter.emit("worker:error", this.id, error);
-        return;
-      }
-      const runAt = nextDate.toISOString();
-      await this.storage.enqueue({
-        id: generateJobId(),
-        queue: this.queueName,
-        type: job.type,
-        payload: job._data.payload,
-        maxAttempts: job.maxAttempts,
-        retryDelay: job.retryDelay,
-        backoff: job.backoff,
-        timeout: job.timeout,
-        priority: job.priority,
-        runAt,
-        cron: job.cron
-      });
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      this.emitter.emit("worker:error", this.id, error);
-    }
+  // ── Static helpers ────────────────────────────────────────────────────────
+  /** Returns the process-wide default client, or undefined if none is set. */
+  static getDefaultClient() {
+    return _QueueClient._default;
   }
-  // -------------------------------------------------------------------------
-  // Failure handling — requeue or DLQ
-  // -------------------------------------------------------------------------
-  async handleFailure(job, error) {
-    const attemptNumber = job.attemptsMade + 1;
-    const hasMore = attemptNumber < job.maxAttempts;
-    this.emitter.emit("job:failed", job._data, error);
-    if (hasMore) {
-      const delayMs = calculateBackoff(job.backoff, job.retryDelay, attemptNumber);
-      const runAt = nextRunAt(delayMs);
-      await this.storage.requeue({
-        jobId: job.id,
-        runAt,
-        error: error.message,
-        attemptNumber,
-        lockId: this.id,
-        ...error.stack !== void 0 && { stack: error.stack }
-      });
-      const updated = await this.storage.getJob(job.id);
-      if (updated) {
-        this.emitter.emit("job:retrying", updated, error, runAt);
-      }
-    } else {
-      await this.storage.moveToDlq({
-        jobId: job.id,
-        error: error.message,
-        attemptNumber,
-        lockId: this.id,
-        ...error.stack !== void 0 && { stack: error.stack }
-      });
-      const dead = await this.storage.getJob(job.id);
-      if (dead) {
-        this.emitter.emit("job:dead", dead, error);
-      }
+  /**
+   * Explicitly set (or replace) the process-wide default client.
+   * Useful in tests or multi-client setups.
+   */
+  static setDefaultClient(client) {
+    _QueueClient._default = client;
+  }
+  /** Clear the default client reference (useful between tests). */
+  static clearDefaultClient() {
+    _QueueClient._default = void 0;
+  }
+  // ── Accessors (read-only to the outside world) ───────────────────────────
+  /** True after init() succeeds and before close() is called. */
+  isInitialized() {
+    return this._initialized;
+  }
+  /** True after close() has been called. */
+  isClosed() {
+    return this._closed;
+  }
+  /** The merged global job execution defaults. */
+  getConfig() {
+    return { ...this._config };
+  }
+  /** The storage dialect this client was created with. */
+  getDialect() {
+    return this._dialect;
+  }
+  /** The connection string (may be undefined for the memory dialect). */
+  getConnectionString() {
+    return this._connectionString;
+  }
+  /** Whether debug logging is enabled. */
+  isDebugMode() {
+    return this._debug;
+  }
+  /**
+   * The underlying IStorage instance.
+   *
+   * Exposed so Queue / Worker can call storage methods directly.
+   * Throws if the client has not been initialized yet.
+   *
+   * @internal
+   */
+  getStorage() {
+    if (!this._storage || !this._initialized) {
+      throw new Error(
+        "[queue-jobs-worker] QueueClient must be initialized before accessing storage. Did you forget to call await client.init()?"
+      );
     }
+    return this._storage;
   }
-  // -------------------------------------------------------------------------
-  // Stalled-job recovery
-  // -------------------------------------------------------------------------
-  scheduleStallCheck() {
-    if (this._status !== "running") return;
-    this.stalledTimer = setTimeout(() => {
-      void this.recoverStalledJobs();
-    }, this.config.stalledInterval);
-  }
-  async recoverStalledJobs() {
-    if (this._status !== "running") return;
-    try {
-      const now = (/* @__PURE__ */ new Date()).toISOString();
-      const recovered = await this.storage.recoverStalledJobs(this.queueName, now);
-      for (const jobId of recovered) {
-        this.emitter.emit("job:stalled", jobId);
-        this.emitter.emit("job:recovered", jobId);
-      }
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      this.emitter.emit("worker:error", this.id, error);
+  // ── Internal helpers ──────────────────────────────────────────────────────
+  /**
+   * 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) {
+    if (this._debug) {
+      console.log(`[queue-jobs-worker] ${message}`);
     }
-    this.scheduleStallCheck();
   }
 };
 
-// src/core/queue.ts
-function mergeQueueConfig(options, defaults) {
-  return {
-    concurrency: options?.concurrency ?? defaults.concurrency,
-    attempts: options?.attempts ?? defaults.attempts,
-    retryDelay: options?.retryDelay ?? defaults.retryDelay,
-    backoff: options?.backoff ?? defaults.backoff,
-    timeout: options?.timeout ?? defaults.timeout,
-    rateLimit: options?.rateLimit ?? defaults.rateLimit ?? void 0,
-    pollInterval: options?.pollInterval ?? defaults.pollInterval,
-    stalledInterval: options?.stalledInterval ?? defaults.stalledInterval,
-    lockDuration: options?.lockDuration ?? defaults.lockDuration
-  };
+// src/classes/queue.ts
+import { randomUUID } from "crypto";
+import { Cron } from "croner";
+var VALID_QUEUE_NAME = /^[a-zA-Z0-9_\-:.]+$/;
+function assertQueueName(name) {
+  if (!name || !VALID_QUEUE_NAME.test(name)) {
+    throw new Error(
+      `[queue-jobs-worker] Invalid queue name "${name}". Queue names must be non-empty and may only contain: letters, digits, hyphens (-), underscores (_), colons (:), and dots (.).`
+    );
+  }
 }
 var Queue = class {
-  /** The name of this queue — unique within a QueueClient. */
   name;
-  storage;
-  emitter;
-  resolvedConfig;
-  clientDefaults;
-  /** Registered processors keyed by job type. */
-  processors = /* @__PURE__ */ new Map();
-  /** Active worker instances created by this queue. */
-  workers = [];
-  constructor(name, storage, emitter, options, defaults) {
+  client;
+  options;
+  /** Active croner handles keyed by jobId — used to cancel scheduled jobs. */
+  _cronHandles = /* @__PURE__ */ new Map();
+  /** Workers attached to this queue — auto-closed when queue.close() is called. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  _workers = /* @__PURE__ */ new Set();
+  /** Guards against double-close. */
+  _closed = false;
+  constructor(name, client, options = {}) {
+    const activeClient = client ?? QueueClient.getDefaultClient();
+    if (!activeClient?.isInitialized()) {
+      throw new Error(
+        "[queue-jobs-worker] QueueClient must be initialized before creating a Queue. Call await client.init() first."
+      );
+    }
+    assertQueueName(name);
     this.name = name;
-    this.storage = storage;
-    this.emitter = emitter;
-    this.clientDefaults = defaults;
-    this.resolvedConfig = mergeQueueConfig(options, defaults);
-  }
-  // -------------------------------------------------------------------------
-  // Enqueue
-  // -------------------------------------------------------------------------
+    this.client = activeClient;
+    this.options = {
+      rateLimit: options.rateLimit ?? { max: 0, duration: 0 },
+      defaultJobOpts: options.defaultJobOpts ?? {}
+    };
+  }
+  // ── Storage shortcut ──────────────────────────────────────────────────────
+  get storage() {
+    return this.client.getStorage();
+  }
+  // ── Public API ────────────────────────────────────────────────────────────
   /**
-   * Add a new job to the queue.
+   * Add a 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.).
+   * 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).
    */
-  async enqueue(type, payload, options) {
-    const cfg = this.resolvedConfig;
-    const now = /* @__PURE__ */ new Date();
-    let runAt;
-    if (options?.schedule?.runAt !== void 0) {
-      runAt = new Date(options.schedule.runAt);
-    } else if (options?.schedule?.delay !== void 0) {
-      runAt = new Date(now.getTime() + options.schedule.delay);
-    } else {
-      runAt = now;
+  async add(name, data, opts = {}) {
+    const clientCfg = this.client.getConfig();
+    const queueDefs = this.options.defaultJobOpts;
+    const delay = opts.delay ?? queueDefs.delay ?? 0;
+    const now = Date.now();
+    const job = {
+      id: opts.jobId ?? randomUUID(),
+      name,
+      data,
+      // Cron jobs begin as "delayed"; the croner callback flips them to
+      // "waiting" on each scheduled tick so a Worker can pick them up.
+      // Plain delayed jobs use "waiting" straight away — runAt gates pickup.
+      status: opts.cron ? "delayed" : "waiting",
+      opts,
+      attempts: opts.attempts ?? queueDefs.attempts ?? clientCfg.attempts,
+      attemptsMade: 0,
+      delay,
+      runAt: now + delay,
+      priority: opts.priority ?? queueDefs.priority ?? 0,
+      // exactOptionalPropertyTypes: only include the optional `cron` field
+      // when it is actually defined — never assign undefined to it explicitly.
+      ...opts.cron !== void 0 && { cron: opts.cron },
+      createdAt: now,
+      updatedAt: now
+    };
+    await this.storage.saveJob(this.name, job);
+    this.client._log(`Queue[${this.name}] added "${name}" id=${job.id}`);
+    if (opts.cron) {
+      this._scheduleCron(job);
     }
-    const raw = await this.storage.enqueue({
-      id: generateJobId(),
-      queue: this.name,
-      type,
-      payload,
-      maxAttempts: options?.attempts ?? cfg.attempts,
-      retryDelay: options?.retryDelay ?? cfg.retryDelay,
-      backoff: options?.backoff ?? cfg.backoff,
-      timeout: options?.timeout ?? cfg.timeout,
-      priority: options?.priority ?? 0,
-      runAt: runAt.toISOString(),
-      ...options?.schedule?.cron !== void 0 && { cron: options.schedule.cron }
-    });
-    const job = new Job(raw);
-    this.emitter.emit("job:enqueued", raw);
     return job;
   }
-  // -------------------------------------------------------------------------
-  // Processor registration
-  // -------------------------------------------------------------------------
   /**
-   * 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.
+   * Fetch a single job by ID.
+   * Returns `undefined` when the job does not exist or has been removed.
    */
-  process(type, processor) {
-    this.processors.set(type, processor);
+  async get(jobId) {
+    return this.storage.getJob(this.name, jobId);
   }
-  // -------------------------------------------------------------------------
-  // Worker creation
-  // -------------------------------------------------------------------------
   /**
-   * Create and start a Worker that consumes jobs from this queue.
-   *
-   * Worker-level `concurrency` overrides queue-level concurrency.
+   * Permanently remove a job from the queue.
+   * If the job has an active cron schedule, it is also cancelled.
    */
-  createWorker(options) {
-    const worker = new Worker(
-      this.name,
-      this.storage,
-      this.emitter,
-      this.processors,
-      options ?? {},
-      this.resolvedConfig,
-      this.clientDefaults
-    );
-    this.workers.push(worker);
-    worker.start();
-    return worker;
-  }
-  // -------------------------------------------------------------------------
-  // Reads
-  // -------------------------------------------------------------------------
-  /** Fetch a single job by its ID. Returns null if not found or wrong queue. */
-  async getJob(jobId) {
-    const raw = await this.storage.getJob(jobId);
-    if (!raw || raw.queue !== this.name) return null;
-    return new Job(raw);
-  }
-  /** Fetch jobs from this queue, optionally filtered by status. */
-  async getJobs(status, limit = 100, offset = 0) {
-    const raws = await this.storage.getJobs({
-      queue: this.name,
-      ...status !== void 0 && { status },
-      limit,
-      offset
-    });
-    return raws.map((r) => new Job(r));
-  }
-  /** Get job counts by status for this queue. */
-  async getJobCounts() {
-    return this.storage.getJobCounts(this.name);
+  async remove(jobId) {
+    this._cancelCron(jobId);
+    await this.storage.removeJob(this.name, jobId);
+    this.client._log(`Queue[${this.name}] removed id=${jobId}`);
   }
-  // -------------------------------------------------------------------------
-  // Lifecycle
-  // -------------------------------------------------------------------------
   /**
-   * Gracefully stop all workers attached to this queue.
-   * Called automatically by QueueClient.close().
+   * List jobs, optionally filtered by status.
+   * Results are sorted: priority ASC, createdAt ASC.
+   *
+   * @param status - `"waiting" | "delayed" | "active" | "completed" | "failed" | "retrying"`
    */
-  async close() {
-    await Promise.all(this.workers.map((w) => w.stop()));
+  async list(status) {
+    return this.storage.listJobs(this.name, status);
   }
-  /** Return all active worker instances on this queue. */
-  getWorkers() {
-    return this.workers;
+  /**
+   * Remove every job in this queue (all statuses).
+   * All active cron schedules for this queue are also cancelled.
+   */
+  async clear() {
+    for (const [id] of this._cronHandles) {
+      this._cancelCron(id);
+    }
+    await this.storage.clearQueue(this.name);
+    this.client._log(`Queue[${this.name}] cleared.`);
   }
-};
-
-// src/storage/in-memory.adapter.ts
-var InMemoryStorageAdapter = class {
-  jobs = /* @__PURE__ */ new Map();
-  rateLimitBuckets = /* @__PURE__ */ new Map();
-  // -------------------------------------------------------------------------
-  // Lifecycle
-  // -------------------------------------------------------------------------
-  async initialize() {
+  /**
+   * Return the total number of jobs in this queue (all statuses combined).
+   */
+  async count() {
+    return this.storage.countJobs(this.name);
   }
+  /**
+   * 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.
+   */
   async close() {
-    this.jobs.clear();
-    this.rateLimitBuckets.clear();
-  }
-  // -------------------------------------------------------------------------
-  // Enqueue
-  // -------------------------------------------------------------------------
-  async enqueue(input) {
-    if (this.jobs.has(input.id)) {
-      return this.jobs.get(input.id);
+    if (this._closed) return;
+    this._closed = true;
+    await Promise.all([...this._workers].map((w) => w.close()));
+    this._workers.clear();
+    for (const [id] of this._cronHandles) {
+      this._cancelCron(id);
     }
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const runAt = input.runAt;
-    const isDelayed = new Date(runAt).getTime() > Date.now();
-    const job = {
-      id: input.id,
-      queue: input.queue,
-      type: input.type,
-      payload: input.payload,
-      status: isDelayed ? "delayed" : "waiting",
-      attemptsMade: 0,
-      maxAttempts: input.maxAttempts,
-      retryDelay: input.retryDelay,
-      backoff: input.backoff,
-      timeout: input.timeout,
-      priority: input.priority,
-      runAt,
-      ...input.cron !== void 0 && { cron: input.cron },
-      attempts: [],
-      lockId: null,
-      lockExpiresAt: null,
-      createdAt: now,
-      updatedAt: now,
-      completedAt: null,
-      failedAt: null
-    };
-    this.jobs.set(job.id, job);
-    return job;
+    this.client._log(`Queue[${this.name}] closed.`);
   }
-  // -------------------------------------------------------------------------
-  // Claim (atomic within a single event-loop tick)
-  // -------------------------------------------------------------------------
-  async claim(input) {
-    const { queue, lockId, lockDuration, now } = input;
-    const nowMs = new Date(now).getTime();
-    const eligible = [];
-    for (const job2 of this.jobs.values()) {
-      if (job2.queue !== queue) continue;
-      if (job2.status !== "waiting" && job2.status !== "delayed") continue;
-      if (new Date(job2.runAt).getTime() > nowMs) continue;
-      if (job2.lockId !== null && job2.lockExpiresAt !== null) {
-        const lockExpiry = new Date(job2.lockExpiresAt).getTime();
-        if (lockExpiry > nowMs) continue;
-      }
-      eligible.push(job2);
+  // ── Internal — used by Worker only ───────────────────────────────────────
+  /**
+   * Register a Worker so it is auto-closed when queue.close() is called.
+   * @internal
+   */
+  _registerWorker(worker) {
+    if (this._closed) {
+      throw new Error(
+        `[queue-jobs-worker] Cannot create a Worker for Queue "${this.name}" because the queue has already been closed.`
+      );
     }
-    if (eligible.length === 0) return null;
-    eligible.sort((a, b) => {
-      if (b.priority !== a.priority) return b.priority - a.priority;
-      const runAtDiff = new Date(a.runAt).getTime() - new Date(b.runAt).getTime();
-      if (runAtDiff !== 0) return runAtDiff;
-      return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
-    });
-    const job = eligible[0];
-    if (!job) return null;
-    const lockExpiresAt = new Date(nowMs + lockDuration).toISOString();
-    job.status = "active";
-    job.lockId = lockId;
-    job.lockExpiresAt = lockExpiresAt;
-    job.updatedAt = now;
-    return job;
+    this._workers.add(worker);
   }
-  // -------------------------------------------------------------------------
-  // Renew lock
-  // -------------------------------------------------------------------------
-  async renewLock(jobId, lockId, lockDuration) {
-    const job = this.jobs.get(jobId);
-    if (!job) return false;
-    if (job.status !== "active" || job.lockId !== lockId) return false;
-    const nowMs = Date.now();
-    if (job.lockExpiresAt !== null && new Date(job.lockExpiresAt).getTime() <= nowMs) {
-      return false;
-    }
-    job.lockExpiresAt = new Date(nowMs + lockDuration).toISOString();
-    job.updatedAt = new Date(nowMs).toISOString();
-    return true;
-  }
-  // -------------------------------------------------------------------------
-  // Complete
-  // -------------------------------------------------------------------------
-  async complete(jobId, lockId) {
-    const job = this.jobs.get(jobId);
-    if (!job) return;
-    if (lockId !== void 0 && (job.status !== "active" || job.lockId !== lockId)) {
-      return;
-    }
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    job.status = "completed";
-    job.lockId = null;
-    job.lockExpiresAt = null;
-    job.completedAt = now;
-    job.updatedAt = now;
-  }
-  // -------------------------------------------------------------------------
-  // Requeue (retry)
-  // -------------------------------------------------------------------------
-  async requeue(input) {
-    const job = this.jobs.get(input.jobId);
-    if (!job) return;
-    if (input.lockId !== void 0 && (job.status !== "active" || job.lockId !== input.lockId)) {
-      return;
-    }
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    job.attempts.push({
-      attempt: input.attemptNumber,
-      startedAt: job.updatedAt,
-      finishedAt: now,
-      error: input.error,
-      ...input.stack !== void 0 && { stack: input.stack }
-    });
-    job.attemptsMade = input.attemptNumber;
-    job.status = "waiting";
-    job.runAt = input.runAt;
-    job.lockId = null;
-    job.lockExpiresAt = null;
-    job.updatedAt = now;
-  }
-  // -------------------------------------------------------------------------
-  // Move to DLQ
-  // -------------------------------------------------------------------------
-  async moveToDlq(input) {
-    const job = this.jobs.get(input.jobId);
-    if (!job) return;
-    if (input.lockId !== void 0 && (job.status !== "active" || job.lockId !== input.lockId)) {
-      return;
-    }
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    job.attempts.push({
-      attempt: input.attemptNumber,
-      startedAt: job.updatedAt,
-      finishedAt: now,
-      error: input.error,
-      ...input.stack !== void 0 && { stack: input.stack }
-    });
-    job.attemptsMade = input.attemptNumber;
-    job.status = "dead";
-    job.lockId = null;
-    job.lockExpiresAt = null;
-    job.failedAt = now;
-    job.updatedAt = now;
-  }
-  // -------------------------------------------------------------------------
-  // Release lock
-  // -------------------------------------------------------------------------
-  async releaseLock(jobId, lockId) {
-    const job = this.jobs.get(jobId);
-    if (!job) return;
-    if (lockId !== void 0 && (job.status !== "active" || job.lockId !== lockId)) {
-      return;
-    }
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    job.lockId = null;
-    job.lockExpiresAt = now;
-    job.updatedAt = now;
-  }
-  // -------------------------------------------------------------------------
-  // Recover stalled jobs
-  //
-  // Fix (issue #6): snapshot lockId and lockExpiresAt before the eligibility
-  // check, then re-validate both values at write time.  In a single-process
-  // scenario all operations are synchronous within one event-loop tick, so
-  // the race is theoretical — but the guard makes the adapter consistent with
-  // the Redis CAS semantics and protects against any future async paths.
-  // -------------------------------------------------------------------------
-  async recoverStalledJobs(queue, now) {
-    const nowMs = new Date(now).getTime();
-    const recovered = [];
-    for (const job of this.jobs.values()) {
-      if (job.queue !== queue) continue;
-      if (job.status !== "active") continue;
-      if (job.lockExpiresAt === null) continue;
-      const lockExpiry = new Date(job.lockExpiresAt).getTime();
-      if (lockExpiry > nowMs) continue;
-      const snapshotLockId = job.lockId;
-      const snapshotLockExpiresAt = job.lockExpiresAt;
-      if (job.status !== "active") continue;
-      if (job.lockId !== snapshotLockId) continue;
-      if (job.lockExpiresAt !== snapshotLockExpiresAt) continue;
-      job.status = "waiting";
-      job.lockId = null;
-      job.lockExpiresAt = null;
-      job.updatedAt = now;
-      recovered.push(job.id);
-    }
-    return recovered;
-  }
-  // -------------------------------------------------------------------------
-  // Reads
-  // -------------------------------------------------------------------------
-  async getJob(jobId) {
-    return this.jobs.get(jobId) ?? null;
-  }
-  async getJobs(filter) {
-    const { queue, status, limit = 100, offset = 0 } = filter;
-    const results = [];
-    for (const job of this.jobs.values()) {
-      if (queue !== void 0 && job.queue !== queue) continue;
-      if (status !== void 0 && job.status !== status) continue;
-      results.push(job);
-    }
-    results.sort((a, b) => {
-      if (b.priority !== a.priority) return b.priority - a.priority;
-      return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
-    });
-    return results.slice(offset, offset + limit);
-  }
-  async getJobCounts(queue) {
-    const counts = {
-      waiting: 0,
-      active: 0,
-      completed: 0,
-      delayed: 0,
-      dead: 0
-    };
-    for (const job of this.jobs.values()) {
-      if (job.queue !== queue) continue;
-      counts[job.status] += 1;
-    }
-    return counts;
-  }
-  // -------------------------------------------------------------------------
-  // Rate limiting
-  // -------------------------------------------------------------------------
-  async checkAndIncrementRateLimit(queue, max, windowMs, now) {
-    const nowMs = new Date(now).getTime();
-    const existing = this.rateLimitBuckets.get(queue);
-    if (!existing || nowMs - existing.windowStart >= windowMs) {
-      this.rateLimitBuckets.set(queue, { count: 1, windowStart: nowMs });
-      return true;
-    }
-    if (existing.count >= max) {
-      return false;
-    }
-    existing.count += 1;
-    return true;
-  }
-  // -------------------------------------------------------------------------
-  // Internal helpers
-  // -------------------------------------------------------------------------
-  requireJob(jobId) {
-    const job = this.jobs.get(jobId);
-    if (!job) {
-      throw new Error(`Job not found: ${jobId}`);
-    }
-    return job;
+  /**
+   * Remove a Worker from the auto-close registry (called by worker.close()).
+   * @internal
+   */
+  _unregisterWorker(worker) {
+    this._workers.delete(worker);
   }
-};
-var QueueEventEmitter = class {
-  emitter;
-  constructor() {
-    this.emitter = new EventEmitter();
-    this.emitter.setMaxListeners(100);
-  }
-  // -------------------------------------------------------------------------
-  // Subscribe
-  // -------------------------------------------------------------------------
-  on(event, listener) {
-    this.emitter.on(event, listener);
-    return this;
+  /**
+   * Atomically claim the next eligible job.
+   * Eligibility: `status IN ('waiting','retrying') AND runAt <= now`.
+   * Returns `undefined` when nothing is ready.
+   * @internal
+   */
+  async _nextJob() {
+    return this.storage.getNextJob(this.name);
   }
-  once(event, listener) {
-    this.emitter.once(event, listener);
-    return this;
+  /**
+   * Persist a partial status update to a job.
+   * @internal
+   */
+  async _updateJob(jobId, patch) {
+    await this.storage.updateJob(this.name, jobId, patch);
   }
-  off(event, listener) {
-    this.emitter.off(event, listener);
-    return this;
+  // ── Cron helpers ──────────────────────────────────────────────────────────
+  _scheduleCron(job) {
+    if (!job.cron) return;
+    const handle = new Cron(job.cron, async () => {
+      try {
+        const current = await this.storage.getJob(this.name, job.id);
+        if (!current) {
+          this._cancelCron(job.id);
+          return;
+        }
+        if (current.status === "completed" || current.status === "delayed" || current.status === "failed") {
+          await this.storage.updateJob(this.name, job.id, {
+            status: "waiting",
+            attemptsMade: 0,
+            runAt: Date.now(),
+            error: null,
+            stacktrace: null,
+            result: null
+          });
+          this.client._log(`Queue[${this.name}] cron tick \u2014 "${job.name}" id=${job.id} re-queued`);
+        }
+      } catch (err) {
+        this.client._log(
+          `Queue[${this.name}] cron tick error \u2014 "${job.name}" id=${job.id}: ` + (err instanceof Error ? err.message : String(err))
+        );
+        console.error(
+          `[queue-jobs-worker] Queue[${this.name}] cron tick error \u2014 "${job.name}" id=${job.id}:`,
+          err
+        );
+      }
+    });
+    this._cronHandles.set(job.id, handle);
   }
-  // ---------------------------------------------------------------------------
-  // Publish
-  // ---------------------------------------------------------------------------
-  emit(event, ...args) {
-    return this.emitter.emit(event, ...args);
-  }
-  // ---------------------------------------------------------------------------
-  // Utility
-  // ---------------------------------------------------------------------------
-  removeAllListeners(event) {
-    if (event) {
-      this.emitter.removeAllListeners(event);
-    } else {
-      this.emitter.removeAllListeners();
+  _cancelCron(jobId) {
+    const handle = this._cronHandles.get(jobId);
+    if (handle) {
+      handle.stop();
+      this._cronHandles.delete(jobId);
     }
-    return this;
-  }
-  listenerCount(event) {
-    return this.emitter.listenerCount(event);
   }
 };
 
-// src/core/client.ts
-var HARD_DEFAULTS = {
-  attempts: 3,
-  retryDelay: 1e3,
-  backoff: "exponential",
-  timeout: 3e4,
-  concurrency: 10,
-  rateLimit: void 0,
-  pollInterval: 1e3,
-  stalledInterval: 3e4,
-  lockDuration: 6e4
-};
-var QueueClient = class _QueueClient {
-  /** @internal — mutable so withAdapter() can replace it */
-  _storage;
-  emitter;
-  defaults;
-  dialect;
-  connectionString;
-  queues = /* @__PURE__ */ new Map();
-  initialised = false;
-  closed = false;
-  /** True when the adapter was supplied via {@link withAdapter}; init() skips resolveAdapter() in that case. */
-  _customAdapter = false;
-  constructor(options = {}) {
-    this.defaults = { ...HARD_DEFAULTS, ...options.defaults };
-    this.dialect = options.dialect ?? "memory";
-    this.connectionString = options.connectionString;
-    this._storage = this.buildMemoryOrEagerAdapter();
-    this.emitter = new QueueEventEmitter();
-  }
-  // -------------------------------------------------------------------------
-  // Eager adapter construction (memory only; external adapters built in init)
-  // -------------------------------------------------------------------------
-  buildMemoryOrEagerAdapter() {
-    if (this.dialect === "memory") {
-      return new InMemoryStorageAdapter();
-    }
-    return new InMemoryStorageAdapter();
-  }
-  // -------------------------------------------------------------------------
-  // Initialisation
-  // -------------------------------------------------------------------------
+// src/classes/worker.ts
+import { EventEmitter } from "events";
+var Worker = class extends EventEmitter {
+  /** The Queue this worker consumes from. Read-only after construction. */
+  queue;
+  handler;
+  concurrency;
+  pollInterval;
+  running = false;
+  _closed = false;
+  loopTimer = null;
+  activeCount = 0;
   /**
-   * 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.
+   * @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).
    */
-  async init() {
-    if (this.initialised) return;
-    if (!this._customAdapter) {
-      this._storage = await this.resolveAdapter();
-    }
-    await this._storage.initialize();
-    this.initialised = true;
-  }
-  /** @deprecated Use `init()`. */
-  async initialize() {
-    return this.init();
-  }
-  async resolveAdapter() {
-    const cs = this.connectionString;
-    switch (this.dialect) {
-      case "memory":
-        return new InMemoryStorageAdapter();
-      case "redis": {
-        if (!cs) throw new Error('dialect "redis" requires a connectionString.');
-        const { RedisStorageAdapter: RedisStorageAdapter2 } = await Promise.resolve().then(() => (init_redis_adapter(), redis_adapter_exports));
-        return new RedisStorageAdapter2(cs);
-      }
-      case "postgres": {
-        if (!cs) throw new Error('dialect "postgres" requires a connectionString.');
-        const { PostgreSQLStorageAdapter: PostgreSQLStorageAdapter2 } = await Promise.resolve().then(() => (init_postgres_adapter(), postgres_adapter_exports));
-        return new PostgreSQLStorageAdapter2(cs);
-      }
-      case "mysql": {
-        if (!cs) throw new Error('dialect "mysql" requires a connectionString.');
-        const { MySQLStorageAdapter: MySQLStorageAdapter2 } = await Promise.resolve().then(() => (init_mysql_adapter(), mysql_adapter_exports));
-        return new MySQLStorageAdapter2(cs);
-      }
-      default:
-        throw new Error(`Unknown storage dialect: "${this.dialect}"`);
+  constructor(queue, handler, options = {}) {
+    super();
+    this.queue = queue;
+    this.handler = handler;
+    this.concurrency = Math.max(1, options.concurrency ?? 1);
+    this.pollInterval = Math.max(0, options.pollInterval ?? 500);
+    this.queue._registerWorker(this);
+  }
+  // ── Lifecycle ─────────────────────────────────────────────────────────────
+  /**
+   * 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() {
+    if (this._closed) {
+      throw new Error(
+        `[queue-jobs-worker] Worker[${this.queue.name}] has been closed and cannot be restarted. Create a new Worker instance instead.`
+      );
     }
+    if (this.running) return this;
+    this.running = true;
+    this.emit("started");
+    this._log(`Worker[${this.queue.name}] started (concurrency=${this.concurrency}).`);
+    this.scheduleLoop();
+    return this;
   }
-  // -------------------------------------------------------------------------
-  // Queue management
-  // -------------------------------------------------------------------------
   /**
-   * Create a named queue with optional per-queue configuration.
+   * 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.
    *
-   * For external dialects (redis/postgres/mysql), call `await client.init()`
-   * first.
+   * Safe to call even if start() was never called.
    */
-  createQueue(name, options) {
-    if (this.closed) throw new Error("QueueClient has been closed.");
-    if (this.queues.has(name)) {
-      throw new Error(`A queue named "${name}" already exists on this client.`);
-    }
-    if (!this.initialised && this.dialect === "memory") {
-      void this.init();
+  async close() {
+    if (!this.running) {
+      this.queue._unregisterWorker(this);
+      this._closed = true;
+      return;
     }
-    const queue = new Queue(name, this._storage, this.emitter, options, this.defaults);
-    this.queues.set(name, queue);
-    return queue;
-  }
-  /** Returns the queue with the given name, or `undefined`. */
-  getQueue(name) {
-    return this.queues.get(name);
-  }
-  /** Returns the queue with the given name, or throws. */
-  requireQueue(name) {
-    const queue = this.getQueue(name);
-    if (!queue) {
-      throw new Error(`Queue "${name}" not found. Did you call createQueue("${name}")?`);
+    this.running = false;
+    if (this.loopTimer) {
+      clearTimeout(this.loopTimer);
+      this.loopTimer = null;
     }
-    return queue;
+    await this.drainActive();
+    this.queue._unregisterWorker(this);
+    this._closed = true;
+    this.emit("stopped");
+    this._log(`Worker[${this.queue.name}] stopped.`);
   }
-  /** Names of all queues registered on this client. */
-  get queueNames() {
-    return Array.from(this.queues.keys());
+  /** `true` while the polling loop is active. */
+  isRunning() {
+    return this.running;
   }
-  /** `true` after `init()` has completed successfully. */
-  get isInitialised() {
-    return this.initialised;
+  /** `true` after close() has been called. */
+  isClosed() {
+    return this._closed;
   }
-  // -------------------------------------------------------------------------
-  // Events
-  // -------------------------------------------------------------------------
+  // ── Typed EventEmitter overloads ──────────────────────────────────────────
   on(event, listener) {
-    this.emitter.on(event, listener);
-    return this;
+    return super.on(event, listener);
   }
   once(event, listener) {
-    this.emitter.once(event, listener);
-    return this;
+    return super.once(event, listener);
   }
-  off(event, listener) {
-    this.emitter.off(event, listener);
-    return 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(event, ...args) {
+    if (event === "error" && this.listenerCount("error") === 0) {
+      return false;
+    }
+    return super.emit(event, ...args);
+  }
+  // ── Poll loop ─────────────────────────────────────────────────────────────
+  scheduleLoop() {
+    if (!this.running) return;
+    this.loopTimer = setTimeout(
+      () => void this.tick().finally(() => this.scheduleLoop()),
+      this.pollInterval
+    );
   }
-  // -------------------------------------------------------------------------
-  // Graceful shutdown
-  // -------------------------------------------------------------------------
   /**
-   * Stop all workers, close all queues, and release the storage connection.
-   * Safe to call multiple times.
+   * One iteration of the poll loop.
+   * Starts as many jobs as concurrency allows, then returns.
    */
-  async close() {
-    if (this.closed) return;
-    this.closed = true;
-    await Promise.all(Array.from(this.queues.values()).map((q) => q.close()));
-    await this._storage.close();
-    this.emitter.removeAllListeners();
-  }
-  // -------------------------------------------------------------------------
-  // Advanced: custom StorageAdapter
-  // -------------------------------------------------------------------------
+  async tick() {
+    while (this.running && this.activeCount < this.concurrency) {
+      if (!this.client.isInitialized()) break;
+      let job;
+      try {
+        job = await this.queue._nextJob();
+      } catch {
+        break;
+      }
+      if (!this.running) break;
+      if (!job) break;
+      this.activeCount++;
+      void this.processJob(job).finally(() => {
+        this.activeCount = Math.max(0, this.activeCount - 1);
+      });
+    }
+  }
+  // ── Job execution ─────────────────────────────────────────────────────────
+  async processJob(job) {
+    const config = this.client.getConfig();
+    const timeout = job.opts.timeout ?? config.timeout;
+    const fetched = await this.queue.get(job.id).catch(() => void 0);
+    const active = fetched ?? { ...job, status: "active" };
+    this.emit("active", active);
+    this._log(
+      `Worker[${this.queue.name}] processing "${job.name}" id=${job.id} attempt=${active.attemptsMade + 1}/${active.attempts === 0 ? "\u221E" : active.attempts}`
+    );
+    let result;
+    try {
+      result = await this.runWithTimeout(active, timeout);
+    } catch (raw) {
+      await this.handleFailure(active, raw);
+      return;
+    }
+    const removeOnComplete = job.opts.removeOnComplete ?? this.queue.options.defaultJobOpts.removeOnComplete ?? false;
+    const finishedAt = Date.now();
+    const completedSnapshot = {
+      ...active,
+      status: "completed",
+      result,
+      finishedAt
+    };
+    if (removeOnComplete) {
+      await this.queue.remove(job.id);
+    } else {
+      const encodedResult = result === null || result === void 0 || typeof result === "string" || typeof result === "number" || typeof result === "boolean" ? result : JSON.stringify(result);
+      await this.queue._updateJob(job.id, {
+        status: "completed",
+        result: encodedResult,
+        finishedAt
+      });
+    }
+    this.emit("completed", completedSnapshot, result);
+    this._log(`Worker[${this.queue.name}] completed "${job.name}" id=${job.id}`);
+  }
   /**
-   * Create a QueueClient with a fully custom StorageAdapter.
-   *
-   * `init()` will call `adapter.initialize()`.
+   * 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.
+   */
+  runWithTimeout(job, timeoutMs) {
+    const work = Promise.resolve(this.handler(job));
+    if (timeoutMs <= 0) return work;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`Job timed out after ${timeoutMs} ms`)),
+        timeoutMs
+      );
+      work.then(
+        (val) => {
+          clearTimeout(timer);
+          resolve(val);
+        },
+        (err) => {
+          clearTimeout(timer);
+          reject(err);
+        }
+      );
+    });
+  }
+  /** Decide between a retry and a permanent failure. */
+  async handleFailure(job, rawErr) {
+    const err = rawErr instanceof Error ? rawErr : new Error(String(rawErr));
+    const fetched = await this.queue.get(job.id).catch(() => void 0);
+    const current = fetched ?? job;
+    const attemptsMade = (fetched?.attemptsMade ?? job.attemptsMade) + 1;
+    const maxAttempts = current.attempts;
+    const canRetry = maxAttempts === 0 || attemptsMade < maxAttempts;
+    this.emit("error", { ...current, attemptsMade }, err);
+    this._log(
+      `Worker[${this.queue.name}] attempt ${attemptsMade}/${maxAttempts === 0 ? "\u221E" : maxAttempts} failed \u2014 "${current.name}" id=${current.id}: ${err.message}`
+    );
+    if (canRetry) {
+      const delay = this.calcBackoff(attemptsMade, current);
+      const retryAt = Date.now() + delay;
+      await this.queue._updateJob(current.id, {
+        status: "retrying",
+        attemptsMade,
+        runAt: retryAt,
+        error: err.message,
+        ...err.stack !== void 0 && { stacktrace: err.stack }
+      });
+      this._log(
+        `Worker[${this.queue.name}] retry in ${delay}ms \u2014 attempt ${attemptsMade + 1}/${maxAttempts === 0 ? "\u221E" : maxAttempts}`
+      );
+      return;
+    }
+    const removeOnFail = current.opts.removeOnFail ?? this.queue.options.defaultJobOpts.removeOnFail ?? false;
+    if (removeOnFail) {
+      await this.queue.remove(current.id);
+    } else {
+      await this.queue._updateJob(current.id, {
+        status: "failed",
+        attemptsMade,
+        error: err.message,
+        ...err.stack !== void 0 && { stacktrace: err.stack },
+        finishedAt: Date.now()
+      });
+    }
+    const failed = await this.queue.get(current.id) ?? {
+      ...current,
+      status: "failed",
+      attemptsMade
+    };
+    this.emit("failed", failed, err);
+    this._log(`Worker[${this.queue.name}] permanently failed \u2014 "${current.name}" id=${current.id}`);
+  }
+  /**
+   * Calculate the delay before the next retry.
    *
-   * @example
-   * const client = QueueClient.withAdapter(myAdapter);
-   * await client.init();
+   * fixed       → base
+   * linear      → base × attemptsMade
+   * exponential → base × 2^(attemptsMade − 1)   capped at 30 min
    */
-  static withAdapter(adapter, options = {}) {
-    const client = new _QueueClient(options);
-    client._storage = adapter;
-    client._customAdapter = true;
-    return client;
+  calcBackoff(attemptsMade, job) {
+    const cfg = this.client.getConfig();
+    const base = cfg.retryDelay;
+    const strategy = cfg.backoff;
+    const MAX = 30 * 60 * 1e3;
+    let delay;
+    switch (strategy) {
+      case "fixed":
+        delay = base;
+        break;
+      case "linear":
+        delay = base * attemptsMade;
+        break;
+      case "exponential":
+        delay = base * Math.pow(2, attemptsMade - 1);
+        break;
+    }
+    const perJobBase = job.opts.retryDelay;
+    if (perJobBase !== void 0) {
+      switch (strategy) {
+        case "fixed":
+          delay = perJobBase;
+          break;
+        case "linear":
+          delay = perJobBase * attemptsMade;
+          break;
+        case "exponential":
+          delay = perJobBase * Math.pow(2, attemptsMade - 1);
+          break;
+        default:
+          delay = perJobBase;
+          break;
+      }
+    }
+    return Math.min(delay, MAX);
+  }
+  /** Poll every 50 ms until no jobs are actively processing, with a 30 s safety timeout. */
+  drainActive() {
+    return new Promise((resolve, reject) => {
+      const DRAIN_TIMEOUT_MS = 3e4;
+      const deadline = setTimeout(() => {
+        reject(
+          new Error(
+            `[queue-jobs-worker] Worker[${this.queue.name}] drain timed out after ${DRAIN_TIMEOUT_MS}ms \u2014 ${this.activeCount} job(s) still active. This may indicate an unhandled error in a job handler.`
+          )
+        );
+      }, DRAIN_TIMEOUT_MS);
+      const poll = () => {
+        if (this.activeCount === 0) {
+          clearTimeout(deadline);
+          resolve();
+        } else {
+          setTimeout(poll, 50);
+        }
+      };
+      poll();
+    });
+  }
+  // ── Convenience accessors ─────────────────────────────────────────────────
+  get client() {
+    return this.queue.client;
+  }
+  _log(msg) {
+    this.client._log(msg);
   }
 };
 
-// src/index.ts
-init_redis_adapter();
-init_postgres_adapter();
-init_mysql_adapter();
-
-export { InMemoryStorageAdapter, Job, MySQLStorageAdapter, PostgreSQLStorageAdapter, Queue, QueueClient, QueueEventEmitter, RedisStorageAdapter, Worker, calculateBackoff, generateJobId, nextRunAt };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+// src/version.ts
+var VERSION = "2.0.0";
+export {
+  Queue,
+  QueueClient,
+  VERSION,
+  Worker
+};