queue-jobs-worker 1.0.0

package/dist/index.cjs

@@ -0,0 +1,2229 @@
+'use strict';
+
+var crypto = require('crypto');
+var events = require('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: () => exports.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'
+    );
+  }
+}
+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; exports.RedisStorageAdapter = void 0;
+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`
+    };
+    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
+`;
+    exports.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);
+      }
+      // -------------------------------------------------------------------------
+      // Complete
+      // -------------------------------------------------------------------------
+      async complete(jobId) {
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        const hash = await this.client.hGetAll(k.job(jobId));
+        if (!hash) 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) 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) 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) {
+        await this.client.hSet(k.job(jobId), {
+          lockId: "",
+          lockExpiresAt: "",
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      // -------------------------------------------------------------------------
+      // Recover stalled jobs  (batched — one pipeline per stalled job)
+      // -------------------------------------------------------------------------
+      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", "priority"]);
+        }
+        const fetchResults = await fetchPipeline.exec();
+        const recovered = [];
+        const recoverPipeline = this.client.multi();
+        for (let i = 0; i < activeIds.length; i++) {
+          const jobId = activeIds[i];
+          const fields = fetchResults[i];
+          if (!fields) continue;
+          const [lockExpiresAt, priorityStr] = fields;
+          if (!lockExpiresAt) continue;
+          if (new Date(lockExpiresAt).getTime() > nowMs) continue;
+          const priority = Number(priorityStr ?? "0");
+          recoverPipeline.hSet(k.job(jobId), {
+            status: "waiting",
+            lockId: "",
+            lockExpiresAt: "",
+            updatedAt: now
+          });
+          recoverPipeline.sRem(k.active(queue), jobId);
+          recoverPipeline.zAdd(k.waiting(queue), { score: -priority, value: jobId });
+          recovered.push(jobId);
+        }
+        if (recovered.length > 0) {
+          await recoverPipeline.exec();
+        }
+        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;
+      }
+      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 };
+      }
+      // -------------------------------------------------------------------------
+      // 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;
+      }
+    };
+  }
+});
+
+// src/storage/postgres.adapter.ts
+var postgres_adapter_exports = {};
+__export(postgres_adapter_exports, {
+  PostgreSQLStorageAdapter: () => exports.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'
+    );
+  }
+}
+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; exports.PostgreSQLStorageAdapter = void 0;
+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
+);
+`;
+    exports.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
+         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();
+        }
+      }
+      // -------------------------------------------------------------------------
+      // Complete
+      // -------------------------------------------------------------------------
+      async complete(jobId) {
+        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 } : {}
+        };
+        await this.pool.query(
+          `UPDATE qjw_jobs
+       SET status         = 'waiting',
+           attempts_made  = attempts_made + 1,
+           attempts       = attempts || $1::jsonb,
+           run_at         = $2::timestamptz,
+           lock_id        = NULL,
+           lock_expires_at = NULL,
+           updated_at     = NOW()
+       WHERE id = $3`,
+          [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 } : {}
+        };
+        await this.pool.query(
+          `UPDATE qjw_jobs
+       SET status          = 'dead',
+           attempts_made   = attempts_made + 1,
+           attempts        = attempts || $1::jsonb,
+           lock_id         = NULL,
+           lock_expires_at = NULL,
+           failed_at       = NOW(),
+           updated_at      = NOW()
+       WHERE id = $2`,
+          [JSON.stringify([attempt]), input.jobId]
+        );
+      }
+      // -------------------------------------------------------------------------
+      // Release lock
+      // -------------------------------------------------------------------------
+      async releaseLock(jobId) {
+        await this.pool.query(
+          `UPDATE qjw_jobs
+       SET lock_id = NULL, lock_expires_at = NULL, 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;
+      }
+    };
+  }
+});
+
+// src/storage/mysql.adapter.ts
+var mysql_adapter_exports = {};
+__export(mysql_adapter_exports, {
+  MySQLStorageAdapter: () => exports.MySQLStorageAdapter
+});
+async function loadMySQL2() {
+  try {
+    return await import('mysql2/promise');
+  } catch {
+    throw new Error(
+      'MySQLStorageAdapter requires the "mysql2" package.\nInstall it: npm install mysql2'
+    );
+  }
+}
+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; exports.MySQLStorageAdapter = void 0;
+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;
+`;
+    exports.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')
+           AND run_at <= ?
+           AND (lock_expires_at IS NULL OR lock_expires_at <= ?)
+         ORDER BY priority DESC, run_at 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();
+        }
+      }
+      // -------------------------------------------------------------------------
+      // Complete
+      // -------------------------------------------------------------------------
+      async complete(jobId) {
+        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 } : {}
+        });
+        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 } : {}
+        });
+        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) {
+        await this.pool.query(
+          `UPDATE qjw_jobs
+       SET lock_id = NULL, lock_expires_at = NULL, 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;
+      }
+    };
+  }
+});
+
+// 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.
+    };
+  }
+  toString() {
+    return `Job(${this._data.id}, type=${this._data.type}, status=${this._data.status}, attempt=${this._data.attemptsMade}/${this._data.maxAttempts})`;
+  }
+};
+
+// 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);
+    }
+    default: {
+      return baseDelay;
+    }
+  }
+}
+function nextRunAt(delayMs, fromDate = /* @__PURE__ */ new Date()) {
+  return new Date(fromDate.getTime() + delayMs).toISOString();
+}
+function generateJobId() {
+  return crypto.randomUUID();
+}
+
+// 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}:${crypto.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;
+    }
+    this._status = "running";
+    this.emitter.emit("worker:started", this.id);
+    this.emitter.emit("worker:status", this.id, this._status);
+    this.schedulePoll();
+    this.scheduleStallCheck();
+  }
+  /**
+   * Gracefully stop the worker.
+   *
+   * 1. Stop accepting new jobs.
+   * 2. Wait up to `shutdownTimeout` ms for active jobs to finish.
+   * 3. Release locks on any jobs that did not finish in time so another
+   *    worker can reclaim them.
+   * 4. Emit stopped event.
+   */
+  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))
+      ]);
+    }
+    if (this.activeJobIds.size > 0) {
+      await Promise.all(
+        Array.from(this.activeJobIds).map(
+          (jobId) => this.storage.releaseLock(jobId).catch(() => {
+          })
+        )
+      );
+    }
+    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();
+    if (this.config.rateLimit) {
+      const allowed = await this.storage.checkAndIncrementRateLimit(
+        this.queueName,
+        this.config.rateLimit.max,
+        this.config.rateLimit.duration,
+        now
+      );
+      if (!allowed) return false;
+    }
+    const raw = await this.storage.claim({
+      queue: this.queueName,
+      lockId: this.id,
+      lockDuration: this.config.lockDuration,
+      now
+    });
+    if (!raw) return false;
+    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;
+    }
+    let timeoutHandle = null;
+    try {
+      await new Promise((resolve, reject) => {
+        timeoutHandle = setTimeout(() => {
+          reject(new Error(`Job timed out after ${job.timeout}ms`));
+        }, job.timeout);
+        Promise.resolve(processor(job)).then(resolve, reject);
+      });
+      if (timeoutHandle) clearTimeout(timeoutHandle);
+      await this.storage.complete(job.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);
+      const error = err instanceof Error ? err : new Error(String(err));
+      await this.handleFailure(job, error);
+    } finally {
+      this.activeJobIds.delete(job.id);
+      this.activeCount -= 1;
+      if (this.activeCount === 0 && this.drainResolve) {
+        this.drainResolve();
+        this.drainResolve = null;
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Cron — re-enqueue the next occurrence after a successful run
+  // -------------------------------------------------------------------------
+  async enqueueCronNext(job) {
+    try {
+      let nextMs;
+      try {
+        const specifier = "croner";
+        const croner = await import(
+          /* @vite-ignore */
+          specifier
+        );
+        const CronClass = croner.Cron ?? croner.default?.Cron ?? croner.default;
+        if (typeof CronClass === "function") {
+          const cronInstance = new CronClass(job.cron);
+          const nextDate = cronInstance.nextRun();
+          nextMs = nextDate ? nextDate.getTime() : Date.now() + 6e4;
+        } else {
+          nextMs = Date.now() + 6e4;
+        }
+      } catch {
+        nextMs = Date.now() + 6e4;
+      }
+      const runAt = new Date(nextMs).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);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // 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,
+        ...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,
+        ...error.stack !== void 0 && { stack: error.stack }
+      });
+      const dead = await this.storage.getJob(job.id);
+      if (dead) {
+        this.emitter.emit("job:dead", dead, error);
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // 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);
+    }
+    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
+  };
+}
+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) {
+    this.name = name;
+    this.storage = storage;
+    this.emitter = emitter;
+    this.clientDefaults = defaults;
+    this.resolvedConfig = mergeQueueConfig(options, defaults);
+  }
+  // -------------------------------------------------------------------------
+  // Enqueue
+  // -------------------------------------------------------------------------
+  /**
+   * Add a new job to the queue.
+   *
+   * @param type    - Job type string, must match a registered processor.
+   * @param payload - Arbitrary serialisable payload (never logged by default).
+   * @param options - Per-job overrides (attempts, delay, priority, etc.).
+   */
+  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;
+    }
+    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.
+   */
+  process(type, processor) {
+    this.processors.set(type, processor);
+  }
+  // -------------------------------------------------------------------------
+  // Worker creation
+  // -------------------------------------------------------------------------
+  /**
+   * Create and start a Worker that consumes jobs from this queue.
+   *
+   * Worker-level `concurrency` overrides queue-level concurrency.
+   */
+  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);
+  }
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+  /**
+   * Gracefully stop all workers attached to this queue.
+   * Called automatically by QueueClient.close().
+   */
+  async close() {
+    await Promise.all(this.workers.map((w) => w.stop()));
+  }
+  /** Return all active worker instances on this queue. */
+  getWorkers() {
+    return this.workers;
+  }
+};
+
+// src/storage/in-memory.adapter.ts
+var InMemoryStorageAdapter = class {
+  jobs = /* @__PURE__ */ new Map();
+  rateLimitBuckets = /* @__PURE__ */ new Map();
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+  async initialize() {
+  }
+  async close() {
+    this.jobs.clear();
+    this.rateLimitBuckets.clear();
+  }
+  // -------------------------------------------------------------------------
+  // Enqueue
+  // -------------------------------------------------------------------------
+  async enqueue(input) {
+    if (this.jobs.has(input.id)) {
+      return this.jobs.get(input.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;
+  }
+  // -------------------------------------------------------------------------
+  // 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);
+    }
+    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;
+  }
+  // -------------------------------------------------------------------------
+  // Complete
+  // -------------------------------------------------------------------------
+  async complete(jobId) {
+    const job = this.requireJob(jobId);
+    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.requireJob(input.jobId);
+    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.requireJob(input.jobId);
+    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) {
+    const job = this.jobs.get(jobId);
+    if (!job) return;
+    job.lockId = null;
+    job.lockExpiresAt = null;
+    job.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  }
+  // -------------------------------------------------------------------------
+  // Recover stalled jobs
+  // -------------------------------------------------------------------------
+  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) {
+        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;
+  }
+};
+var QueueEventEmitter = class {
+  emitter;
+  constructor() {
+    this.emitter = new events.EventEmitter();
+    this.emitter.setMaxListeners(100);
+  }
+  // -------------------------------------------------------------------------
+  // Subscribe
+  // -------------------------------------------------------------------------
+  on(event, listener) {
+    this.emitter.on(event, listener);
+    return this;
+  }
+  once(event, listener) {
+    this.emitter.once(event, listener);
+    return this;
+  }
+  off(event, listener) {
+    this.emitter.off(event, listener);
+    return this;
+  }
+  // ---------------------------------------------------------------------------
+  // Publish
+  // ---------------------------------------------------------------------------
+  emit(event, ...args) {
+    return this.emitter.emit(event, ...args);
+  }
+  // ---------------------------------------------------------------------------
+  // Utility
+  // ---------------------------------------------------------------------------
+  removeAllListeners(event) {
+    if (event) {
+      this.emitter.removeAllListeners(event);
+    } else {
+      this.emitter.removeAllListeners();
+    }
+    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;
+  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
+  // -------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async init() {
+    if (this.initialised) return;
+    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}"`);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Queue management
+  // -------------------------------------------------------------------------
+  /**
+   * Create a named queue with optional per-queue configuration.
+   *
+   * For external dialects (redis/postgres/mysql), call `await client.init()`
+   * first.
+   */
+  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();
+    }
+    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}")?`);
+    }
+    return queue;
+  }
+  /** Names of all queues registered on this client. */
+  get queueNames() {
+    return Array.from(this.queues.keys());
+  }
+  /** `true` after `init()` has completed successfully. */
+  get isInitialised() {
+    return this.initialised;
+  }
+  // -------------------------------------------------------------------------
+  // Events
+  // -------------------------------------------------------------------------
+  on(event, listener) {
+    this.emitter.on(event, listener);
+    return this;
+  }
+  once(event, listener) {
+    this.emitter.once(event, listener);
+    return this;
+  }
+  off(event, listener) {
+    this.emitter.off(event, listener);
+    return this;
+  }
+  // -------------------------------------------------------------------------
+  // Graceful shutdown
+  // -------------------------------------------------------------------------
+  /**
+   * Stop all workers, close all queues, and release the storage connection.
+   * Safe to call multiple times.
+   */
+  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
+  // -------------------------------------------------------------------------
+  /**
+   * Create a QueueClient with a fully custom StorageAdapter.
+   *
+   * `init()` will call `adapter.initialize()`.
+   *
+   * @example
+   * const client = QueueClient.withAdapter(myAdapter);
+   * await client.init();
+   */
+  static withAdapter(adapter, options = {}) {
+    const client = new _QueueClient(options);
+    client._storage = adapter;
+    return client;
+  }
+};
+
+// src/index.ts
+init_redis_adapter();
+init_postgres_adapter();
+init_mysql_adapter();
+
+exports.InMemoryStorageAdapter = InMemoryStorageAdapter;
+exports.Job = Job;
+exports.Queue = Queue;
+exports.QueueClient = QueueClient;
+exports.QueueEventEmitter = QueueEventEmitter;
+exports.Worker = Worker;
+exports.calculateBackoff = calculateBackoff;
+exports.generateJobId = generateJobId;
+exports.nextRunAt = nextRunAt;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map