@chidchanun/bcp 0.2.9 → 0.2.11

package/packages/client/src/jobs.mjs

@@ -4,6 +4,33 @@ import {
 } from "node:crypto";
 function createMemoryJobQueueAdapter() {
   const jobs = /* @__PURE__ */ new Map();
+  const deadLetters = /* @__PURE__ */ new Map();
+  const recoverStale = (now, options = {}) => {
+    const limit = normalizePositiveInteger(
+      options.limit ?? 100,
+      "recovery limit"
+    );
+    const stale = Array.from(
+      jobs.values()
+    ).filter(
+      (job) => job.state === "running" && job.leaseUntil !== void 0 && job.leaseUntil <= now
+    ).sort(
+      (left, right) => (left.leaseUntil ?? 0) - (right.leaseUntil ?? 0) || left.id.localeCompare(
+        right.id
+      )
+    ).slice(
+      0,
+      limit
+    );
+    for (const job of stale) {
+      job.state = "queued";
+      job.availableAt = now;
+      job.startedAt = void 0;
+      clearLease(job);
+      job.recoveredAt = now;
+    }
+    return stale.length;
+  };
   return {
     async enqueue(job) {
       if (jobs.has(job.id)) {
@@ -16,7 +43,13 @@ function createMemoryJobQueueAdapter() {
         cloneJob(job)
       );
     },
-    async reserve(now) {
+    async reserve(now, options) {
+      recoverStale(
+        now,
+        {
+          limit: 100
+        }
+      );
       const candidate = Array.from(
         jobs.values()
       ).filter(
@@ -31,25 +64,43 @@ function createMemoryJobQueueAdapter() {
       candidate.attempts += 1;
       candidate.startedAt = now;
       candidate.error = void 0;
-      return cloneJob(
-        candidate
-      );
+      candidate.recoveredAt = void 0;
+      if (options) {
+        candidate.leaseOwner = normalizeWorkerId(
+          options.ownerId
+        );
+        candidate.leaseUntil = now + normalizePositiveInteger(
+          options.visibilityTimeoutMs,
+          "visibilityTimeoutMs"
+        );
+        candidate.heartbeatAt = now;
+      }
+      return cloneJob(candidate);
     },
-    async complete(id, completedAt) {
+    async complete(id, completedAt, ownerId) {
       const job = jobs.get(id);
-      if (!job || job.state === "cancelled") {
+      if (!job || job.state === "cancelled" || !leaseOwnerMatches(
+        job,
+        ownerId
+      )) {
         return;
       }
       job.state = "succeeded";
       job.completedAt = completedAt;
       job.error = void 0;
+      clearLease(job);
+      deadLetters.delete(id);
     },
     async fail(id, options) {
       const job = jobs.get(id);
-      if (!job || job.state === "cancelled") {
+      if (!job || job.state === "cancelled" || !leaseOwnerMatches(
+        job,
+        options.ownerId
+      )) {
         return;
       }
       job.error = options.error;
+      clearLease(job);
       if (options.retryAt !== void 0 && job.attempts < job.maxAttempts) {
         job.state = "queued";
         job.availableAt = options.retryAt;
@@ -58,6 +109,14 @@ function createMemoryJobQueueAdapter() {
       }
       job.state = "failed";
       job.completedAt = options.failedAt;
+      deadLetters.set(
+        id,
+        {
+          ...cloneJob(job),
+          state: "failed",
+          deadLetteredAt: options.failedAt
+        }
+      );
     },
     async cancel(id, cancelledAt) {
       const job = jobs.get(id);
@@ -66,6 +125,7 @@ function createMemoryJobQueueAdapter() {
       }
       job.state = "cancelled";
       job.completedAt = cancelledAt;
+      clearLease(job);
       return true;
     },
     async get(id) {
@@ -79,8 +139,91 @@ function createMemoryJobQueueAdapter() {
         (left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id)
       );
     },
+    async heartbeat(id, options) {
+      const job = jobs.get(id);
+      if (!job || job.state !== "running" || job.leaseOwner !== options.ownerId) {
+        return false;
+      }
+      const visibilityTimeoutMs = normalizePositiveInteger(
+        options.visibilityTimeoutMs,
+        "visibilityTimeoutMs"
+      );
+      job.heartbeatAt = options.heartbeatAt;
+      job.leaseUntil = options.heartbeatAt + visibilityTimeoutMs;
+      return true;
+    },
+    async recoverStale(now, options) {
+      return recoverStale(
+        now,
+        options
+      );
+    },
+    async listDeadLetters() {
+      return Array.from(
+        deadLetters.values()
+      ).map(cloneDeadLetter).sort(
+        (left, right) => left.deadLetteredAt - right.deadLetteredAt || left.id.localeCompare(
+          right.id
+        )
+      );
+    },
+    async requeueDeadLetter(id, now, options = {}) {
+      const job = jobs.get(id);
+      if (!job || job.state !== "failed" || !deadLetters.has(id)) {
+        return false;
+      }
+      const delayMs = normalizeNonNegativeNumber(
+        options.delayMs ?? 0,
+        "delayMs"
+      );
+      job.state = "queued";
+      job.availableAt = now + delayMs;
+      job.startedAt = void 0;
+      job.completedAt = void 0;
+      job.error = void 0;
+      job.recoveredAt = void 0;
+      clearLease(job);
+      if (options.resetAttempts !== false) {
+        job.attempts = 0;
+      }
+      deadLetters.delete(id);
+      return true;
+    },
+    async cleanup(options) {
+      const states = new Set(
+        options.states ?? [
+          "succeeded",
+          "failed",
+          "cancelled"
+        ]
+      );
+      let removed = 0;
+      for (const [
+        id,
+        job
+      ] of jobs) {
+        if (!states.has(
+          job.state
+        ) || job.completedAt === void 0 || job.completedAt >= options.before) {
+          continue;
+        }
+        jobs.delete(id);
+        deadLetters.delete(id);
+        removed += 1;
+      }
+      return removed;
+    },
+    async stats() {
+      return calculateJobStats(
+        Array.from(
+          jobs.values()
+        ),
+        deadLetters.size
+      );
+    },
     clear() {
       jobs.clear();
+      deadLetters.clear();
     }
   };
 }
@@ -147,9 +290,7 @@ function createJobQueue(options = {}) {
       );
       const job = {
         id,
-        name: normalizeJobName(
-          name
-        ),
+        name: normalizeJobName(name),
         payload,
         state: "queued",
         attempts: 0,
@@ -157,9 +298,7 @@ function createJobQueue(options = {}) {
         createdAt,
         availableAt: createdAt + delayMs
       };
-      await adapter.enqueue(
-        job
-      );
+      await adapter.enqueue(job);
       return cloneJob(job);
     },
     get(id) {
@@ -176,58 +315,103 @@ function createJobQueue(options = {}) {
         now()
       );
     },
-    async processNext(signal = new AbortController().signal) {
+    async processNext(signal = new AbortController().signal, processOptions = {}) {
       if (signal.aborted) {
         return false;
       }
-      const job = await adapter.reserve(
-        now()
+      const visibilityTimeoutMs = normalizePositiveInteger(
+        processOptions.visibilityTimeoutMs ?? 3e4,
+        "visibilityTimeoutMs"
       );
-      if (!job) {
-        return false;
-      }
-      const handler = handlers.get(
-        job.name
+      const heartbeatIntervalMs = normalizePositiveInteger(
+        processOptions.heartbeatIntervalMs ?? Math.max(
+          1,
+          Math.floor(
+            visibilityTimeoutMs / 3
+          )
+        ),
+        "heartbeatIntervalMs"
       );
-      if (!handler) {
-        await adapter.fail(
-          job.id,
+      const ownerId = normalizeWorkerId(
+        processOptions.ownerId ?? `process-${randomUUID()}`
+      );
+      if (adapter.recoverStale) {
+        await adapter.recoverStale(
+          now(),
           {
-            error: `No handler registered for job "${job.name}".`,
-            failedAt: now()
+            limit: normalizePositiveInteger(
+              processOptions.recoveryLimit ?? 100,
+              "recoveryLimit"
+            )
           }
         );
-        return true;
       }
+      const job = await adapter.reserve(
+        now(),
+        {
+          ownerId,
+          visibilityTimeoutMs
+        }
+      );
+      if (!job) {
+        return false;
+      }
+      const stopHeartbeat = startJobHeartbeat(
+        adapter,
+        job.id,
+        ownerId,
+        visibilityTimeoutMs,
+        heartbeatIntervalMs,
+        now,
+        signal
+      );
+      const handler = handlers.get(job.name);
       try {
-        await handler({
-          job: cloneJob(job),
-          payload: job.payload,
-          signal
-        });
-        await adapter.complete(
-          job.id,
-          now()
-        );
-      } catch (error) {
-        const failedAt = now();
-        const shouldRetry = job.attempts < job.maxAttempts;
-        const retryAt = shouldRetry ? failedAt + resolveRetryDelay(
-          retryDelay,
-          job.attempts
-        ) : void 0;
-        await adapter.fail(
-          job.id,
-          {
-            error: formatJobError(
-              error
-            ),
-            failedAt,
-            retryAt
-          }
-        );
+        if (!handler) {
+          await adapter.fail(
+            job.id,
+            {
+              error: `No handler registered for job "${job.name}".`,
+              failedAt: now(),
+              ownerId
+            }
+          );
+          return true;
+        }
+        try {
+          await handler({
+            job: cloneJob(job),
+            payload: job.payload,
+            signal
+          });
+          await adapter.complete(
+            job.id,
+            now(),
+            ownerId
+          );
+        } catch (error) {
+          const failedAt = now();
+          const shouldRetry = job.attempts < job.maxAttempts;
+          const retryAt = shouldRetry ? failedAt + resolveRetryDelay(
+            retryDelay,
+            job.attempts
+          ) : void 0;
+          await adapter.fail(
+            job.id,
+            {
+              error: formatJobError(
+                error
+              ),
+              failedAt,
+              retryAt,
+              ownerId
+            }
+          );
+        }
+        return true;
+      } finally {
+        stopHeartbeat();
       }
-      return true;
     },
     startWorker(workerOptions = {}) {
       const worker = createWorker(
@@ -240,6 +424,51 @@ function createJobQueue(options = {}) {
       workers.add(worker);
       return worker;
     },
+    async recoverStale(recoverOptions = {}) {
+      if (!adapter.recoverStale) {
+        return 0;
+      }
+      return adapter.recoverStale(
+        now(),
+        recoverOptions
+      );
+    },
+    async deadLetters() {
+      return adapter.listDeadLetters ? adapter.listDeadLetters() : [];
+    },
+    async requeueDeadLetter(id, requeueOptions = {}) {
+      if (!adapter.requeueDeadLetter) {
+        return false;
+      }
+      return adapter.requeueDeadLetter(
+        normalizeJobId(id),
+        now(),
+        requeueOptions
+      );
+    },
+    async cleanup(cleanupOptions) {
+      if (!adapter.cleanup) {
+        return 0;
+      }
+      const before = normalizeNonNegativeNumber(
+        cleanupOptions.before,
+        "cleanup before"
+      );
+      return adapter.cleanup({
+        ...cleanupOptions,
+        before
+      });
+    },
+    async stats() {
+      if (adapter.stats) {
+        return adapter.stats();
+      }
+      const jobs = await adapter.list();
+      return calculateJobStats(
+        jobs,
+        adapter.listDeadLetters ? (await adapter.listDeadLetters()).length : 0
+      );
+    },
     async close() {
       await Promise.all(
         Array.from(
@@ -263,6 +492,26 @@ function createWorker(queue, options, onStop) {
     options.pollIntervalMs ?? 250,
     "pollIntervalMs"
   );
+  const visibilityTimeoutMs = normalizePositiveInteger(
+    options.visibilityTimeoutMs ?? 3e4,
+    "visibilityTimeoutMs"
+  );
+  const heartbeatIntervalMs = normalizePositiveInteger(
+    options.heartbeatIntervalMs ?? Math.max(
+      1,
+      Math.floor(
+        visibilityTimeoutMs / 3
+      )
+    ),
+    "heartbeatIntervalMs"
+  );
+  const recoveryLimit = normalizePositiveInteger(
+    options.recoveryLimit ?? 100,
+    "recoveryLimit"
+  );
+  const workerId = normalizeWorkerId(
+    options.workerId ?? `worker-${randomUUID()}`
+  );
   const controller = new AbortController();
   let running = true;
   let stopPromise = null;
@@ -270,16 +519,24 @@ function createWorker(queue, options, onStop) {
     {
       length: concurrency
     },
-    () => runWorkerLoop(
+    (_, index) => runWorkerLoop(
       queue,
       controller.signal,
-      pollIntervalMs
+      pollIntervalMs,
+      {
+        ownerId: `${workerId}:${index + 1}`,
+        visibilityTimeoutMs,
+        heartbeatIntervalMs,
+        recoveryLimit
+      },
+      options.onError
     )
   );
   return {
     get running() {
       return running;
     },
+    workerId,
     stop() {
       if (stopPromise) {
         return stopPromise;
@@ -297,11 +554,24 @@ function createWorker(queue, options, onStop) {
     }
   };
 }
-async function runWorkerLoop(queue, signal, pollIntervalMs) {
+async function runWorkerLoop(queue, signal, pollIntervalMs, options, onError) {
   while (!signal.aborted) {
-    const processed = await queue.processNext(
-      signal
-    );
+    let processed = false;
+    try {
+      processed = await queue.processNext(
+        signal,
+        options
+      );
+    } catch (error) {
+      if (signal.aborted) {
+        break;
+      }
+      if (onError) {
+        await onError(error);
+      } else {
+        throw error;
+      }
+    }
     if (!processed && !signal.aborted) {
       await sleep(
         pollIntervalMs,
@@ -310,8 +580,50 @@ async function runWorkerLoop(queue, signal, pollIntervalMs) {
     }
   }
 }
+function startJobHeartbeat(adapter, jobId, ownerId, visibilityTimeoutMs, heartbeatIntervalMs, now, signal) {
+  if (!adapter.heartbeat) {
+    return () => void 0;
+  }
+  let stopped = false;
+  let timeout;
+  const schedule = () => {
+    if (stopped || signal.aborted) {
+      return;
+    }
+    timeout = setTimeout(
+      async () => {
+        if (stopped || signal.aborted) {
+          return;
+        }
+        try {
+          const active = await adapter.heartbeat?.(
+            jobId,
+            {
+              ownerId,
+              heartbeatAt: now(),
+              visibilityTimeoutMs
+            }
+          );
+          if (active !== false) {
+            schedule();
+          }
+        } catch {
+          schedule();
+        }
+      },
+      heartbeatIntervalMs
+    );
+  };
+  schedule();
+  return () => {
+    stopped = true;
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  };
+}
 function sleep(durationMs, signal) {
-  if (durationMs === 0 || signal.aborted) {
+  if (signal.aborted) {
     return Promise.resolve();
   }
   return new Promise(
@@ -339,6 +651,21 @@ function sleep(durationMs, signal) {
     }
   );
 }
+function calculateJobStats(jobs, deadLetters) {
+  const stats = {
+    total: jobs.length,
+    queued: 0,
+    running: 0,
+    succeeded: 0,
+    failed: 0,
+    cancelled: 0,
+    deadLetters
+  };
+  for (const job of jobs) {
+    stats[job.state] += 1;
+  }
+  return stats;
+}
 function resolveRetryDelay(value, attempt) {
   const delay = typeof value === "function" ? value(attempt) : value;
   return normalizeNonNegativeNumber(
@@ -374,6 +701,15 @@ function normalizeJobId(value) {
   }
   return id;
 }
+function normalizeWorkerId(value) {
+  const id = String(value).trim();
+  if (!id) {
+    throw new TypeError(
+      "BCP Jobs: worker id must be a non-empty string."
+    );
+  }
+  return id;
+}
 function normalizePositiveInteger(value, field) {
   if (!Number.isInteger(value) || value <= 0) {
     throw new TypeError(
@@ -404,11 +740,27 @@ function formatJobError(error) {
     return String(error);
   }
 }
+function leaseOwnerMatches(job, ownerId) {
+  if (ownerId === void 0) {
+    return true;
+  }
+  return job.leaseOwner === ownerId;
+}
+function clearLease(job) {
+  job.leaseOwner = void 0;
+  job.leaseUntil = void 0;
+  job.heartbeatAt = void 0;
+}
 function cloneJob(job) {
   return {
     ...job
   };
 }
+function cloneDeadLetter(job) {
+  return {
+    ...job
+  };
+}
 
 // packages/server/src/job-scheduler.ts
 import {
@@ -1030,11 +1382,908 @@ function cloneSchedule(schedule) {
     }
   };
 }
+
+// packages/server/src/jobs-redis.ts
+function createRedisJobQueueAdapter(options) {
+  const client = requireRedisClient(
+    options.client
+  );
+  const namespace = normalizeNamespace(
+    options.namespace
+  );
+  const keys = createQueueKeys(
+    namespace
+  );
+  return {
+    namespace,
+    async enqueue(job) {
+      const result = await evalRedis(
+        client,
+        ENQUEUE_SCRIPT,
+        [
+          jobKey(
+            keys.jobPrefix,
+            job.id
+          ),
+          keys.all,
+          keys.available
+        ],
+        [
+          job.id,
+          JSON.stringify(job),
+          String(
+            job.availableAt
+          )
+        ]
+      );
+      if (Number(result) !== 1) {
+        throw new Error(
+          `BCP Jobs Redis: job id "${job.id}" already exists.`
+        );
+      }
+    },
+    async reserve(now, reserveOptions) {
+      const options2 = reserveOptions ?? {
+        ownerId: "legacy-worker",
+        visibilityTimeoutMs: 3e4
+      };
+      const raw = await evalRedis(
+        client,
+        RESERVE_SCRIPT,
+        [
+          keys.available,
+          keys.running
+        ],
+        [
+          keys.jobPrefix,
+          String(now),
+          options2.ownerId,
+          String(
+            normalizePositiveInteger3(
+              options2.visibilityTimeoutMs,
+              "visibilityTimeoutMs"
+            )
+          )
+        ]
+      );
+      return parseJsonReply(raw);
+    },
+    async complete(id, completedAt, ownerId) {
+      await evalRedis(
+        client,
+        COMPLETE_SCRIPT,
+        [
+          jobKey(
+            keys.jobPrefix,
+            id
+          ),
+          keys.available,
+          keys.running,
+          keys.terminal,
+          keys.deadLetters
+        ],
+        [
+          id,
+          String(completedAt),
+          ownerId ?? ""
+        ]
+      );
+    },
+    async fail(id, failOptions) {
+      await evalRedis(
+        client,
+        FAIL_SCRIPT,
+        [
+          jobKey(
+            keys.jobPrefix,
+            id
+          ),
+          keys.available,
+          keys.running,
+          keys.terminal,
+          keys.deadLetters
+        ],
+        [
+          id,
+          failOptions.error,
+          String(
+            failOptions.failedAt
+          ),
+          failOptions.retryAt === void 0 ? "" : String(
+            failOptions.retryAt
+          ),
+          failOptions.ownerId ?? ""
+        ]
+      );
+    },
+    async cancel(id, cancelledAt) {
+      const result = await evalRedis(
+        client,
+        CANCEL_SCRIPT,
+        [
+          jobKey(
+            keys.jobPrefix,
+            id
+          ),
+          keys.available,
+          keys.running,
+          keys.terminal
+        ],
+        [
+          id,
+          String(cancelledAt)
+        ]
+      );
+      return Number(result) === 1;
+    },
+    async get(id) {
+      const raw = await client.sendCommand([
+        "GET",
+        jobKey(
+          keys.jobPrefix,
+          id
+        )
+      ]);
+      return parseJsonReply(raw);
+    },
+    async list() {
+      return readJobsByIds(
+        client,
+        keys.jobPrefix,
+        await readStringList(
+          client,
+          [
+            "SMEMBERS",
+            keys.all
+          ]
+        )
+      );
+    },
+    async heartbeat(id, heartbeatOptions) {
+      const result = await evalRedis(
+        client,
+        HEARTBEAT_SCRIPT,
+        [
+          jobKey(
+            keys.jobPrefix,
+            id
+          ),
+          keys.running
+        ],
+        [
+          id,
+          heartbeatOptions.ownerId,
+          String(
+            heartbeatOptions.heartbeatAt
+          ),
+          String(
+            normalizePositiveInteger3(
+              heartbeatOptions.visibilityTimeoutMs,
+              "visibilityTimeoutMs"
+            )
+          )
+        ]
+      );
+      return Number(result) === 1;
+    },
+    async recoverStale(now, recoverOptions = {}) {
+      const result = await evalRedis(
+        client,
+        RECOVER_STALE_SCRIPT,
+        [
+          keys.running,
+          keys.available
+        ],
+        [
+          keys.jobPrefix,
+          String(now),
+          String(
+            normalizePositiveInteger3(
+              recoverOptions.limit ?? 100,
+              "recovery limit"
+            )
+          )
+        ]
+      );
+      return Number(result) || 0;
+    },
+    async listDeadLetters() {
+      const ids = await readStringList(
+        client,
+        [
+          "ZRANGE",
+          keys.deadLetters,
+          "0",
+          "-1"
+        ]
+      );
+      const jobs = await readJobsByIds(
+        client,
+        keys.jobPrefix,
+        ids
+      );
+      return jobs.filter(
+        (job) => job.state === "failed" && job.completedAt !== void 0
+      ).map(
+        (job) => ({
+          ...job,
+          state: "failed",
+          deadLetteredAt: job.completedAt
+        })
+      );
+    },
+    async requeueDeadLetter(id, now, requeueOptions = {}) {
+      const result = await evalRedis(
+        client,
+        REQUEUE_DEAD_LETTER_SCRIPT,
+        [
+          jobKey(
+            keys.jobPrefix,
+            id
+          ),
+          keys.available,
+          keys.running,
+          keys.terminal,
+          keys.deadLetters
+        ],
+        [
+          id,
+          String(now),
+          String(
+            normalizeNonNegativeNumber2(
+              requeueOptions.delayMs ?? 0,
+              "delayMs"
+            )
+          ),
+          requeueOptions.resetAttempts === false ? "0" : "1"
+        ]
+      );
+      return Number(result) === 1;
+    },
+    async cleanup(cleanupOptions) {
+      const states = cleanupOptions.states ?? [
+        "succeeded",
+        "failed",
+        "cancelled"
+      ];
+      const result = await evalRedis(
+        client,
+        CLEANUP_SCRIPT,
+        [
+          keys.terminal,
+          keys.all,
+          keys.available,
+          keys.running,
+          keys.deadLetters
+        ],
+        [
+          keys.jobPrefix,
+          String(
+            cleanupOptions.before
+          ),
+          JSON.stringify(states)
+        ]
+      );
+      return Number(result) || 0;
+    },
+    async stats() {
+      const jobs = await readJobsByIds(
+        client,
+        keys.jobPrefix,
+        await readStringList(
+          client,
+          [
+            "SMEMBERS",
+            keys.all
+          ]
+        )
+      );
+      const deadLetters = Number(
+        await client.sendCommand([
+          "ZCARD",
+          keys.deadLetters
+        ])
+      ) || 0;
+      return calculateStats(
+        jobs,
+        deadLetters
+      );
+    },
+    async close() {
+      if (options.close) {
+        await options.close();
+      }
+    }
+  };
+}
+function createRedisJobScheduleStore(options) {
+  const client = requireRedisClient(
+    options.client
+  );
+  const namespace = normalizeNamespace(
+    options.namespace
+  );
+  const keys = createScheduleKeys(
+    namespace
+  );
+  return {
+    namespace,
+    async upsert(schedule) {
+      await evalRedis(
+        client,
+        UPSERT_SCHEDULE_SCRIPT,
+        [
+          scheduleKey(
+            keys.schedulePrefix,
+            schedule.id
+          ),
+          keys.all,
+          keys.due
+        ],
+        [
+          schedule.id,
+          JSON.stringify(schedule),
+          String(
+            schedule.nextRunAt
+          )
+        ]
+      );
+    },
+    async get(id) {
+      return parseJsonReply(
+        await client.sendCommand([
+          "GET",
+          scheduleKey(
+            keys.schedulePrefix,
+            id
+          )
+        ])
+      );
+    },
+    async list() {
+      const ids = await readStringList(
+        client,
+        [
+          "SMEMBERS",
+          keys.all
+        ]
+      );
+      const schedules = await readSchedulesByIds(
+        client,
+        keys.schedulePrefix,
+        ids
+      );
+      return schedules.sort(
+        (left, right) => left.nextRunAt - right.nextRunAt || left.id.localeCompare(
+          right.id
+        )
+      );
+    },
+    async remove(id) {
+      const result = await evalRedis(
+        client,
+        REMOVE_SCHEDULE_SCRIPT,
+        [
+          scheduleKey(
+            keys.schedulePrefix,
+            id
+          ),
+          keys.all,
+          keys.due
+        ],
+        [
+          id
+        ]
+      );
+      return Number(result) === 1;
+    },
+    async acquireDue(now, acquireOptions) {
+      const raw = await evalRedis(
+        client,
+        ACQUIRE_DUE_SCHEDULES_SCRIPT,
+        [
+          keys.due
+        ],
+        [
+          keys.schedulePrefix,
+          String(now),
+          acquireOptions.ownerId,
+          String(
+            normalizePositiveInteger3(
+              acquireOptions.leaseMs,
+              "schedule leaseMs"
+            )
+          ),
+          String(
+            normalizePositiveInteger3(
+              acquireOptions.limit,
+              "schedule limit"
+            )
+          )
+        ]
+      );
+      if (!Array.isArray(raw)) {
+        return [];
+      }
+      return raw.map(
+        (value) => parseJsonReply(value)
+      ).filter(
+        (value) => value !== null
+      );
+    },
+    async complete(id, completeOptions) {
+      await evalRedis(
+        client,
+        COMPLETE_SCHEDULE_SCRIPT,
+        [
+          scheduleKey(
+            keys.schedulePrefix,
+            id
+          ),
+          keys.due
+        ],
+        [
+          id,
+          completeOptions.ownerId,
+          String(
+            completeOptions.lastRunAt
+          ),
+          String(
+            completeOptions.nextRunAt
+          ),
+          String(
+            completeOptions.updatedAt
+          )
+        ]
+      );
+    },
+    async release(id, ownerId) {
+      await evalRedis(
+        client,
+        RELEASE_SCHEDULE_SCRIPT,
+        [
+          scheduleKey(
+            keys.schedulePrefix,
+            id
+          )
+        ],
+        [
+          ownerId
+        ]
+      );
+    },
+    async close() {
+      if (options.close) {
+        await options.close();
+      }
+    }
+  };
+}
+function createQueueKeys(namespace) {
+  return {
+    all: `${namespace}:jobs:all`,
+    available: `${namespace}:jobs:available`,
+    running: `${namespace}:jobs:running`,
+    terminal: `${namespace}:jobs:terminal`,
+    deadLetters: `${namespace}:jobs:dlq`,
+    jobPrefix: `${namespace}:job:`
+  };
+}
+function createScheduleKeys(namespace) {
+  return {
+    all: `${namespace}:schedules:all`,
+    due: `${namespace}:schedules:due`,
+    schedulePrefix: `${namespace}:schedule:`
+  };
+}
+function jobKey(prefix, id) {
+  return `${prefix}${id}`;
+}
+function scheduleKey(prefix, id) {
+  return `${prefix}${id}`;
+}
+async function evalRedis(client, script, keys, args) {
+  return client.sendCommand([
+    "EVAL",
+    script,
+    String(keys.length),
+    ...keys,
+    ...args
+  ]);
+}
+async function readStringList(client, command) {
+  const result = await client.sendCommand(
+    command
+  );
+  if (!Array.isArray(result)) {
+    return [];
+  }
+  return result.map(
+    (value) => redisString(value)
+  ).filter(
+    (value) => value !== null
+  );
+}
+async function readJobsByIds(client, prefix, ids) {
+  if (ids.length === 0) {
+    return [];
+  }
+  const raw = await client.sendCommand([
+    "MGET",
+    ...ids.map(
+      (id) => jobKey(
+        prefix,
+        id
+      )
+    )
+  ]);
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw.map(
+    (value) => parseJsonReply(value)
+  ).filter(
+    (value) => value !== null
+  ).sort(
+    (left, right) => left.createdAt - right.createdAt || left.id.localeCompare(
+      right.id
+    )
+  );
+}
+async function readSchedulesByIds(client, prefix, ids) {
+  if (ids.length === 0) {
+    return [];
+  }
+  const raw = await client.sendCommand([
+    "MGET",
+    ...ids.map(
+      (id) => scheduleKey(
+        prefix,
+        id
+      )
+    )
+  ]);
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw.map(
+    (value) => parseJsonReply(value)
+  ).filter(
+    (value) => value !== null
+  );
+}
+function parseJsonReply(value) {
+  const text = redisString(value);
+  if (text === null) {
+    return null;
+  }
+  return JSON.parse(text);
+}
+function redisString(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value instanceof Uint8Array) {
+    return Buffer.from(
+      value
+    ).toString("utf8");
+  }
+  if (typeof value === "number") {
+    return String(value);
+  }
+  return null;
+}
+function calculateStats(jobs, deadLetters) {
+  const stats = {
+    total: jobs.length,
+    queued: 0,
+    running: 0,
+    succeeded: 0,
+    failed: 0,
+    cancelled: 0,
+    deadLetters
+  };
+  for (const job of jobs) {
+    stats[job.state] += 1;
+  }
+  return stats;
+}
+function requireRedisClient(client) {
+  if (!client || typeof client.sendCommand !== "function") {
+    throw new TypeError(
+      "BCP Jobs Redis: client.sendCommand(command) is required."
+    );
+  }
+  return client;
+}
+function normalizeNamespace(value = "bcp:{jobs}") {
+  const namespace = String(value).trim();
+  if (!namespace) {
+    throw new TypeError(
+      "BCP Jobs Redis: namespace must be non-empty."
+    );
+  }
+  return namespace.replace(
+    /:+$/,
+    ""
+  );
+}
+function normalizePositiveInteger3(value, field) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError(
+      `BCP Jobs Redis: ${field} must be a positive integer.`
+    );
+  }
+  return value;
+}
+function normalizeNonNegativeNumber2(value, field) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new TypeError(
+      `BCP Jobs Redis: ${field} must be a non-negative finite number.`
+    );
+  }
+  return Math.floor(value);
+}
+var ENQUEUE_SCRIPT = `
+if redis.call('EXISTS', KEYS[1]) == 1 then
+    return 0
+end
+redis.call('SET', KEYS[1], ARGV[2])
+redis.call('SADD', KEYS[2], ARGV[1])
+redis.call('ZADD', KEYS[3], ARGV[3], ARGV[1])
+return 1
+`;
+var RESERVE_SCRIPT = `
+local ids = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[2], 'LIMIT', 0, 20)
+for _, id in ipairs(ids) do
+    local key = ARGV[1] .. id
+    local raw = redis.call('GET', key)
+    if not raw then
+        redis.call('ZREM', KEYS[1], id)
+    else
+        local job = cjson.decode(raw)
+        if job.state == 'queued' then
+            job.state = 'running'
+            job.attempts = (job.attempts or 0) + 1
+            job.startedAt = tonumber(ARGV[2])
+            job.error = nil
+            job.recoveredAt = nil
+            job.leaseOwner = ARGV[3]
+            job.leaseUntil = tonumber(ARGV[2]) + tonumber(ARGV[4])
+            job.heartbeatAt = tonumber(ARGV[2])
+            local encoded = cjson.encode(job)
+            redis.call('SET', key, encoded)
+            redis.call('ZREM', KEYS[1], id)
+            redis.call('ZADD', KEYS[2], job.leaseUntil, id)
+            return encoded
+        end
+        redis.call('ZREM', KEYS[1], id)
+    end
+end
+return nil
+`;
+var COMPLETE_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+local job = cjson.decode(raw)
+if job.state == 'cancelled' then return 0 end
+if ARGV[3] ~= '' and job.leaseOwner ~= ARGV[3] then return 0 end
+job.state = 'succeeded'
+job.completedAt = tonumber(ARGV[2])
+job.error = nil
+job.leaseOwner = nil
+job.leaseUntil = nil
+job.heartbeatAt = nil
+redis.call('SET', KEYS[1], cjson.encode(job))
+redis.call('ZREM', KEYS[2], ARGV[1])
+redis.call('ZREM', KEYS[3], ARGV[1])
+redis.call('ZADD', KEYS[4], ARGV[2], ARGV[1])
+redis.call('ZREM', KEYS[5], ARGV[1])
+return 1
+`;
+var FAIL_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+local job = cjson.decode(raw)
+if job.state == 'cancelled' then return 0 end
+if ARGV[5] ~= '' and job.leaseOwner ~= ARGV[5] then return 0 end
+job.error = ARGV[2]
+job.leaseOwner = nil
+job.leaseUntil = nil
+job.heartbeatAt = nil
+local retryAt = nil
+if ARGV[4] ~= '' then retryAt = tonumber(ARGV[4]) end
+if retryAt and (job.attempts or 0) < (job.maxAttempts or 1) then
+    job.state = 'queued'
+    job.availableAt = retryAt
+    job.startedAt = nil
+    redis.call('SET', KEYS[1], cjson.encode(job))
+    redis.call('ZREM', KEYS[3], ARGV[1])
+    redis.call('ZADD', KEYS[2], retryAt, ARGV[1])
+    return 2
+end
+job.state = 'failed'
+job.completedAt = tonumber(ARGV[3])
+redis.call('SET', KEYS[1], cjson.encode(job))
+redis.call('ZREM', KEYS[2], ARGV[1])
+redis.call('ZREM', KEYS[3], ARGV[1])
+redis.call('ZADD', KEYS[4], ARGV[3], ARGV[1])
+redis.call('ZADD', KEYS[5], ARGV[3], ARGV[1])
+return 1
+`;
+var CANCEL_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+local job = cjson.decode(raw)
+if job.state == 'succeeded' or job.state == 'failed' or job.state == 'cancelled' then
+    return 0
+end
+job.state = 'cancelled'
+job.completedAt = tonumber(ARGV[2])
+job.leaseOwner = nil
+job.leaseUntil = nil
+job.heartbeatAt = nil
+redis.call('SET', KEYS[1], cjson.encode(job))
+redis.call('ZREM', KEYS[2], ARGV[1])
+redis.call('ZREM', KEYS[3], ARGV[1])
+redis.call('ZADD', KEYS[4], ARGV[2], ARGV[1])
+return 1
+`;
+var HEARTBEAT_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+local job = cjson.decode(raw)
+if job.state ~= 'running' or job.leaseOwner ~= ARGV[2] then
+    return 0
+end
+job.heartbeatAt = tonumber(ARGV[3])
+job.leaseUntil = tonumber(ARGV[3]) + tonumber(ARGV[4])
+redis.call('SET', KEYS[1], cjson.encode(job))
+redis.call('ZADD', KEYS[2], job.leaseUntil, ARGV[1])
+return 1
+`;
+var RECOVER_STALE_SCRIPT = `
+local ids = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[2], 'LIMIT', 0, tonumber(ARGV[3]))
+local recovered = 0
+for _, id in ipairs(ids) do
+    local key = ARGV[1] .. id
+    local raw = redis.call('GET', key)
+    if not raw then
+        redis.call('ZREM', KEYS[1], id)
+    else
+        local job = cjson.decode(raw)
+        if job.state == 'running' and job.leaseUntil and tonumber(job.leaseUntil) <= tonumber(ARGV[2]) then
+            job.state = 'queued'
+            job.availableAt = tonumber(ARGV[2])
+            job.startedAt = nil
+            job.leaseOwner = nil
+            job.leaseUntil = nil
+            job.heartbeatAt = nil
+            job.recoveredAt = tonumber(ARGV[2])
+            redis.call('SET', key, cjson.encode(job))
+            redis.call('ZREM', KEYS[1], id)
+            redis.call('ZADD', KEYS[2], ARGV[2], id)
+            recovered = recovered + 1
+        end
+    end
+end
+return recovered
+`;
+var REQUEUE_DEAD_LETTER_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+if not redis.call('ZSCORE', KEYS[5], ARGV[1]) then return 0 end
+local job = cjson.decode(raw)
+if job.state ~= 'failed' then return 0 end
+job.state = 'queued'
+job.availableAt = tonumber(ARGV[2]) + tonumber(ARGV[3])
+job.startedAt = nil
+job.completedAt = nil
+job.error = nil
+job.leaseOwner = nil
+job.leaseUntil = nil
+job.heartbeatAt = nil
+job.recoveredAt = nil
+if ARGV[4] == '1' then job.attempts = 0 end
+redis.call('SET', KEYS[1], cjson.encode(job))
+redis.call('ZADD', KEYS[2], job.availableAt, ARGV[1])
+redis.call('ZREM', KEYS[3], ARGV[1])
+redis.call('ZREM', KEYS[4], ARGV[1])
+redis.call('ZREM', KEYS[5], ARGV[1])
+return 1
+`;
+var CLEANUP_SCRIPT = `
+local allowed = {}
+for _, state in ipairs(cjson.decode(ARGV[3])) do allowed[state] = true end
+local ids = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[2], 'LIMIT', 0, 1000)
+local removed = 0
+for _, id in ipairs(ids) do
+    local key = ARGV[1] .. id
+    local raw = redis.call('GET', key)
+    if not raw then
+        redis.call('ZREM', KEYS[1], id)
+        redis.call('SREM', KEYS[2], id)
+    else
+        local job = cjson.decode(raw)
+        if allowed[job.state] then
+            redis.call('DEL', key)
+            redis.call('SREM', KEYS[2], id)
+            redis.call('ZREM', KEYS[1], id)
+            redis.call('ZREM', KEYS[3], id)
+            redis.call('ZREM', KEYS[4], id)
+            redis.call('ZREM', KEYS[5], id)
+            removed = removed + 1
+        end
+    end
+end
+return removed
+`;
+var UPSERT_SCHEDULE_SCRIPT = `
+redis.call('SET', KEYS[1], ARGV[2])
+redis.call('SADD', KEYS[2], ARGV[1])
+redis.call('ZADD', KEYS[3], ARGV[3], ARGV[1])
+return 1
+`;
+var REMOVE_SCHEDULE_SCRIPT = `
+local existed = redis.call('DEL', KEYS[1])
+redis.call('SREM', KEYS[2], ARGV[1])
+redis.call('ZREM', KEYS[3], ARGV[1])
+return existed
+`;
+var ACQUIRE_DUE_SCHEDULES_SCRIPT = `
+local ids = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[2], 'LIMIT', 0, tonumber(ARGV[5]) * 4)
+local result = {}
+for _, id in ipairs(ids) do
+    if #result >= tonumber(ARGV[5]) then break end
+    local key = ARGV[1] .. id
+    local raw = redis.call('GET', key)
+    if not raw then
+        redis.call('ZREM', KEYS[1], id)
+    else
+        local schedule = cjson.decode(raw)
+        local leaseUntil = schedule.leaseUntil
+        if schedule.nextRunAt <= tonumber(ARGV[2]) and (not leaseUntil or tonumber(leaseUntil) <= tonumber(ARGV[2])) then
+            schedule.leaseOwner = ARGV[3]
+            schedule.leaseUntil = tonumber(ARGV[2]) + tonumber(ARGV[4])
+            local encoded = cjson.encode(schedule)
+            redis.call('SET', key, encoded)
+            table.insert(result, encoded)
+        end
+    end
+end
+return result
+`;
+var COMPLETE_SCHEDULE_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+local schedule = cjson.decode(raw)
+if schedule.leaseOwner ~= ARGV[2] then return 0 end
+schedule.lastRunAt = tonumber(ARGV[3])
+schedule.nextRunAt = tonumber(ARGV[4])
+schedule.updatedAt = tonumber(ARGV[5])
+schedule.leaseOwner = nil
+schedule.leaseUntil = nil
+redis.call('SET', KEYS[1], cjson.encode(schedule))
+redis.call('ZADD', KEYS[2], ARGV[4], ARGV[1])
+return 1
+`;
+var RELEASE_SCHEDULE_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+local schedule = cjson.decode(raw)
+if schedule.leaseOwner ~= ARGV[1] then return 0 end
+schedule.leaseOwner = nil
+schedule.leaseUntil = nil
+redis.call('SET', KEYS[1], cjson.encode(schedule))
+return 1
+`;
 export {
   createJobQueue,
   createJobScheduler,
   createMemoryJobQueueAdapter,
   createMemoryJobScheduleStore,
+  createRedisJobQueueAdapter,
+  createRedisJobScheduleStore,
   nextCronTime,
   nextScheduleTime
 };