@nicnocquee/dataqueue 1.30.0 → 1.31.0

package/dist/index.cjs

@@ -7,6 +7,7 @@ var pg = require('pg');
 var pgConnectionString = require('pg-connection-string');
 var fs = require('fs');
 var module$1 = require('module');
+var croner = require('croner');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -1005,6 +1006,297 @@ var PostgresBackend = class {
       client.release();
     }
   }
+  // ── Cron schedules ──────────────────────────────────────────────────
+  /** Create a cron schedule and return its ID. */
+  async addCronSchedule(input) {
+    const client = await this.pool.connect();
+    try {
+      const result = await client.query(
+        `INSERT INTO cron_schedules
+          (schedule_name, cron_expression, job_type, payload, max_attempts,
+           priority, timeout_ms, force_kill_on_timeout, tags, timezone,
+           allow_overlap, next_run_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+         RETURNING id`,
+        [
+          input.scheduleName,
+          input.cronExpression,
+          input.jobType,
+          input.payload,
+          input.maxAttempts,
+          input.priority,
+          input.timeoutMs,
+          input.forceKillOnTimeout,
+          input.tags ?? null,
+          input.timezone,
+          input.allowOverlap,
+          input.nextRunAt
+        ]
+      );
+      const id = result.rows[0].id;
+      log(`Added cron schedule ${id}: "${input.scheduleName}"`);
+      return id;
+    } catch (error) {
+      if (error?.code === "23505") {
+        throw new Error(
+          `Cron schedule with name "${input.scheduleName}" already exists`
+        );
+      }
+      log(`Error adding cron schedule: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /** Get a cron schedule by ID. */
+  async getCronSchedule(id) {
+    const client = await this.pool.connect();
+    try {
+      const result = await client.query(
+        `SELECT id, schedule_name AS "scheduleName", cron_expression AS "cronExpression",
+                job_type AS "jobType", payload, max_attempts AS "maxAttempts",
+                priority, timeout_ms AS "timeoutMs",
+                force_kill_on_timeout AS "forceKillOnTimeout", tags,
+                timezone, allow_overlap AS "allowOverlap", status,
+                last_enqueued_at AS "lastEnqueuedAt", last_job_id AS "lastJobId",
+                next_run_at AS "nextRunAt",
+                created_at AS "createdAt", updated_at AS "updatedAt"
+         FROM cron_schedules WHERE id = $1`,
+        [id]
+      );
+      if (result.rows.length === 0) return null;
+      return result.rows[0];
+    } catch (error) {
+      log(`Error getting cron schedule ${id}: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /** Get a cron schedule by its unique name. */
+  async getCronScheduleByName(name) {
+    const client = await this.pool.connect();
+    try {
+      const result = await client.query(
+        `SELECT id, schedule_name AS "scheduleName", cron_expression AS "cronExpression",
+                job_type AS "jobType", payload, max_attempts AS "maxAttempts",
+                priority, timeout_ms AS "timeoutMs",
+                force_kill_on_timeout AS "forceKillOnTimeout", tags,
+                timezone, allow_overlap AS "allowOverlap", status,
+                last_enqueued_at AS "lastEnqueuedAt", last_job_id AS "lastJobId",
+                next_run_at AS "nextRunAt",
+                created_at AS "createdAt", updated_at AS "updatedAt"
+         FROM cron_schedules WHERE schedule_name = $1`,
+        [name]
+      );
+      if (result.rows.length === 0) return null;
+      return result.rows[0];
+    } catch (error) {
+      log(`Error getting cron schedule by name "${name}": ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /** List cron schedules, optionally filtered by status. */
+  async listCronSchedules(status) {
+    const client = await this.pool.connect();
+    try {
+      let query = `SELECT id, schedule_name AS "scheduleName", cron_expression AS "cronExpression",
+                job_type AS "jobType", payload, max_attempts AS "maxAttempts",
+                priority, timeout_ms AS "timeoutMs",
+                force_kill_on_timeout AS "forceKillOnTimeout", tags,
+                timezone, allow_overlap AS "allowOverlap", status,
+                last_enqueued_at AS "lastEnqueuedAt", last_job_id AS "lastJobId",
+                next_run_at AS "nextRunAt",
+                created_at AS "createdAt", updated_at AS "updatedAt"
+         FROM cron_schedules`;
+      const params = [];
+      if (status) {
+        query += ` WHERE status = $1`;
+        params.push(status);
+      }
+      query += ` ORDER BY created_at ASC`;
+      const result = await client.query(query, params);
+      return result.rows;
+    } catch (error) {
+      log(`Error listing cron schedules: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /** Delete a cron schedule by ID. */
+  async removeCronSchedule(id) {
+    const client = await this.pool.connect();
+    try {
+      await client.query(`DELETE FROM cron_schedules WHERE id = $1`, [id]);
+      log(`Removed cron schedule ${id}`);
+    } catch (error) {
+      log(`Error removing cron schedule ${id}: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /** Pause a cron schedule. */
+  async pauseCronSchedule(id) {
+    const client = await this.pool.connect();
+    try {
+      await client.query(
+        `UPDATE cron_schedules SET status = 'paused', updated_at = NOW() WHERE id = $1`,
+        [id]
+      );
+      log(`Paused cron schedule ${id}`);
+    } catch (error) {
+      log(`Error pausing cron schedule ${id}: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /** Resume a paused cron schedule. */
+  async resumeCronSchedule(id) {
+    const client = await this.pool.connect();
+    try {
+      await client.query(
+        `UPDATE cron_schedules SET status = 'active', updated_at = NOW() WHERE id = $1`,
+        [id]
+      );
+      log(`Resumed cron schedule ${id}`);
+    } catch (error) {
+      log(`Error resuming cron schedule ${id}: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /** Edit a cron schedule. */
+  async editCronSchedule(id, updates, nextRunAt) {
+    const client = await this.pool.connect();
+    try {
+      const updateFields = [];
+      const params = [];
+      let paramIdx = 1;
+      if (updates.cronExpression !== void 0) {
+        updateFields.push(`cron_expression = $${paramIdx++}`);
+        params.push(updates.cronExpression);
+      }
+      if (updates.payload !== void 0) {
+        updateFields.push(`payload = $${paramIdx++}`);
+        params.push(updates.payload);
+      }
+      if (updates.maxAttempts !== void 0) {
+        updateFields.push(`max_attempts = $${paramIdx++}`);
+        params.push(updates.maxAttempts);
+      }
+      if (updates.priority !== void 0) {
+        updateFields.push(`priority = $${paramIdx++}`);
+        params.push(updates.priority);
+      }
+      if (updates.timeoutMs !== void 0) {
+        updateFields.push(`timeout_ms = $${paramIdx++}`);
+        params.push(updates.timeoutMs);
+      }
+      if (updates.forceKillOnTimeout !== void 0) {
+        updateFields.push(`force_kill_on_timeout = $${paramIdx++}`);
+        params.push(updates.forceKillOnTimeout);
+      }
+      if (updates.tags !== void 0) {
+        updateFields.push(`tags = $${paramIdx++}`);
+        params.push(updates.tags);
+      }
+      if (updates.timezone !== void 0) {
+        updateFields.push(`timezone = $${paramIdx++}`);
+        params.push(updates.timezone);
+      }
+      if (updates.allowOverlap !== void 0) {
+        updateFields.push(`allow_overlap = $${paramIdx++}`);
+        params.push(updates.allowOverlap);
+      }
+      if (nextRunAt !== void 0) {
+        updateFields.push(`next_run_at = $${paramIdx++}`);
+        params.push(nextRunAt);
+      }
+      if (updateFields.length === 0) {
+        log(`No fields to update for cron schedule ${id}`);
+        return;
+      }
+      updateFields.push(`updated_at = NOW()`);
+      params.push(id);
+      const query = `UPDATE cron_schedules SET ${updateFields.join(", ")} WHERE id = $${paramIdx}`;
+      await client.query(query, params);
+      log(`Edited cron schedule ${id}`);
+    } catch (error) {
+      log(`Error editing cron schedule ${id}: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Atomically fetch all active cron schedules whose nextRunAt <= NOW().
+   * Uses FOR UPDATE SKIP LOCKED to prevent duplicate enqueuing across workers.
+   */
+  async getDueCronSchedules() {
+    const client = await this.pool.connect();
+    try {
+      const result = await client.query(
+        `SELECT id, schedule_name AS "scheduleName", cron_expression AS "cronExpression",
+                job_type AS "jobType", payload, max_attempts AS "maxAttempts",
+                priority, timeout_ms AS "timeoutMs",
+                force_kill_on_timeout AS "forceKillOnTimeout", tags,
+                timezone, allow_overlap AS "allowOverlap", status,
+                last_enqueued_at AS "lastEnqueuedAt", last_job_id AS "lastJobId",
+                next_run_at AS "nextRunAt",
+                created_at AS "createdAt", updated_at AS "updatedAt"
+         FROM cron_schedules
+         WHERE status = 'active'
+           AND next_run_at IS NOT NULL
+           AND next_run_at <= NOW()
+         ORDER BY next_run_at ASC
+         FOR UPDATE SKIP LOCKED`
+      );
+      log(`Found ${result.rows.length} due cron schedules`);
+      return result.rows;
+    } catch (error) {
+      if (error?.code === "42P01") {
+        log("cron_schedules table does not exist, skipping cron enqueue");
+        return [];
+      }
+      log(`Error getting due cron schedules: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Update a cron schedule after a job has been enqueued.
+   * Sets lastEnqueuedAt, lastJobId, and advances nextRunAt.
+   */
+  async updateCronScheduleAfterEnqueue(id, lastEnqueuedAt, lastJobId, nextRunAt) {
+    const client = await this.pool.connect();
+    try {
+      await client.query(
+        `UPDATE cron_schedules
+         SET last_enqueued_at = $2,
+             last_job_id = $3,
+             next_run_at = $4,
+             updated_at = NOW()
+         WHERE id = $1`,
+        [id, lastEnqueuedAt, lastJobId, nextRunAt]
+      );
+      log(
+        `Updated cron schedule ${id}: lastJobId=${lastJobId}, nextRunAt=${nextRunAt?.toISOString() ?? "null"}`
+      );
+    } catch (error) {
+      log(`Error updating cron schedule ${id} after enqueue: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  // ── Internal helpers ──────────────────────────────────────────────────
   async setPendingReasonForUnpickedJobs(reason, jobType) {
     const client = await this.pool.connect();
     try {
@@ -1735,7 +2027,7 @@ async function processBatchWithHandlers(backend, workerId, batchSize, jobType, j
     next();
   });
 }
-var createProcessor = (backend, handlers, options = {}) => {
+var createProcessor = (backend, handlers, options = {}, onBeforeBatch) => {
   const {
     workerId = `worker-${Math.random().toString(36).substring(2, 9)}`,
     batchSize = 10,
@@ -1750,6 +2042,18 @@ var createProcessor = (backend, handlers, options = {}) => {
   setLogContext(options.verbose ?? false);
   const processJobs = async () => {
     if (!running) return 0;
+    if (onBeforeBatch) {
+      try {
+        await onBeforeBatch();
+      } catch (hookError) {
+        log(`onBeforeBatch hook error: ${hookError}`);
+        if (onError) {
+          onError(
+            hookError instanceof Error ? hookError : new Error(String(hookError))
+          );
+        }
+      }
+    }
     log(
       `Processing jobs with workerId: ${workerId}${jobType ? ` and jobType: ${Array.isArray(jobType) ? jobType.join(",") : jobType}` : ""}`
     );
@@ -2968,6 +3272,332 @@ var RedisBackend = class {
       return true;
     });
   }
+  // ── Cron schedules ──────────────────────────────────────────────────
+  /** Create a cron schedule and return its ID. */
+  async addCronSchedule(input) {
+    const existingId = await this.client.get(
+      `${this.prefix}cron_name:${input.scheduleName}`
+    );
+    if (existingId !== null) {
+      throw new Error(
+        `Cron schedule with name "${input.scheduleName}" already exists`
+      );
+    }
+    const id = await this.client.incr(`${this.prefix}cron_id_seq`);
+    const now = this.nowMs();
+    const key = `${this.prefix}cron:${id}`;
+    const fields = [
+      "id",
+      id.toString(),
+      "scheduleName",
+      input.scheduleName,
+      "cronExpression",
+      input.cronExpression,
+      "jobType",
+      input.jobType,
+      "payload",
+      JSON.stringify(input.payload),
+      "maxAttempts",
+      input.maxAttempts.toString(),
+      "priority",
+      input.priority.toString(),
+      "timeoutMs",
+      input.timeoutMs !== null ? input.timeoutMs.toString() : "null",
+      "forceKillOnTimeout",
+      input.forceKillOnTimeout ? "true" : "false",
+      "tags",
+      input.tags ? JSON.stringify(input.tags) : "null",
+      "timezone",
+      input.timezone,
+      "allowOverlap",
+      input.allowOverlap ? "true" : "false",
+      "status",
+      "active",
+      "lastEnqueuedAt",
+      "null",
+      "lastJobId",
+      "null",
+      "nextRunAt",
+      input.nextRunAt ? input.nextRunAt.getTime().toString() : "null",
+      "createdAt",
+      now.toString(),
+      "updatedAt",
+      now.toString()
+    ];
+    await this.client.hmset(key, ...fields);
+    await this.client.set(
+      `${this.prefix}cron_name:${input.scheduleName}`,
+      id.toString()
+    );
+    await this.client.sadd(`${this.prefix}crons`, id.toString());
+    await this.client.sadd(`${this.prefix}cron_status:active`, id.toString());
+    if (input.nextRunAt) {
+      await this.client.zadd(
+        `${this.prefix}cron_due`,
+        input.nextRunAt.getTime(),
+        id.toString()
+      );
+    }
+    log(`Added cron schedule ${id}: "${input.scheduleName}"`);
+    return id;
+  }
+  /** Get a cron schedule by ID. */
+  async getCronSchedule(id) {
+    const data = await this.client.hgetall(`${this.prefix}cron:${id}`);
+    if (!data || Object.keys(data).length === 0) return null;
+    return this.deserializeCronSchedule(data);
+  }
+  /** Get a cron schedule by its unique name. */
+  async getCronScheduleByName(name) {
+    const id = await this.client.get(`${this.prefix}cron_name:${name}`);
+    if (id === null) return null;
+    return this.getCronSchedule(Number(id));
+  }
+  /** List cron schedules, optionally filtered by status. */
+  async listCronSchedules(status) {
+    let ids;
+    if (status) {
+      ids = await this.client.smembers(`${this.prefix}cron_status:${status}`);
+    } else {
+      ids = await this.client.smembers(`${this.prefix}crons`);
+    }
+    if (ids.length === 0) return [];
+    const pipeline = this.client.pipeline();
+    for (const id of ids) {
+      pipeline.hgetall(`${this.prefix}cron:${id}`);
+    }
+    const results = await pipeline.exec();
+    const schedules = [];
+    if (results) {
+      for (const [err, data] of results) {
+        if (!err && data && typeof data === "object" && Object.keys(data).length > 0) {
+          schedules.push(
+            this.deserializeCronSchedule(data)
+          );
+        }
+      }
+    }
+    schedules.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+    return schedules;
+  }
+  /** Delete a cron schedule by ID. */
+  async removeCronSchedule(id) {
+    const data = await this.client.hgetall(`${this.prefix}cron:${id}`);
+    if (!data || Object.keys(data).length === 0) return;
+    const name = data.scheduleName;
+    const status = data.status;
+    await this.client.del(`${this.prefix}cron:${id}`);
+    await this.client.del(`${this.prefix}cron_name:${name}`);
+    await this.client.srem(`${this.prefix}crons`, id.toString());
+    await this.client.srem(
+      `${this.prefix}cron_status:${status}`,
+      id.toString()
+    );
+    await this.client.zrem(`${this.prefix}cron_due`, id.toString());
+    log(`Removed cron schedule ${id}`);
+  }
+  /** Pause a cron schedule. */
+  async pauseCronSchedule(id) {
+    const now = this.nowMs();
+    await this.client.hset(
+      `${this.prefix}cron:${id}`,
+      "status",
+      "paused",
+      "updatedAt",
+      now.toString()
+    );
+    await this.client.srem(`${this.prefix}cron_status:active`, id.toString());
+    await this.client.sadd(`${this.prefix}cron_status:paused`, id.toString());
+    await this.client.zrem(`${this.prefix}cron_due`, id.toString());
+    log(`Paused cron schedule ${id}`);
+  }
+  /** Resume a paused cron schedule. */
+  async resumeCronSchedule(id) {
+    const now = this.nowMs();
+    await this.client.hset(
+      `${this.prefix}cron:${id}`,
+      "status",
+      "active",
+      "updatedAt",
+      now.toString()
+    );
+    await this.client.srem(`${this.prefix}cron_status:paused`, id.toString());
+    await this.client.sadd(`${this.prefix}cron_status:active`, id.toString());
+    const nextRunAt = await this.client.hget(
+      `${this.prefix}cron:${id}`,
+      "nextRunAt"
+    );
+    if (nextRunAt && nextRunAt !== "null") {
+      await this.client.zadd(
+        `${this.prefix}cron_due`,
+        Number(nextRunAt),
+        id.toString()
+      );
+    }
+    log(`Resumed cron schedule ${id}`);
+  }
+  /** Edit a cron schedule. */
+  async editCronSchedule(id, updates, nextRunAt) {
+    const now = this.nowMs();
+    const fields = [];
+    if (updates.cronExpression !== void 0) {
+      fields.push("cronExpression", updates.cronExpression);
+    }
+    if (updates.payload !== void 0) {
+      fields.push("payload", JSON.stringify(updates.payload));
+    }
+    if (updates.maxAttempts !== void 0) {
+      fields.push("maxAttempts", updates.maxAttempts.toString());
+    }
+    if (updates.priority !== void 0) {
+      fields.push("priority", updates.priority.toString());
+    }
+    if (updates.timeoutMs !== void 0) {
+      fields.push(
+        "timeoutMs",
+        updates.timeoutMs !== null ? updates.timeoutMs.toString() : "null"
+      );
+    }
+    if (updates.forceKillOnTimeout !== void 0) {
+      fields.push(
+        "forceKillOnTimeout",
+        updates.forceKillOnTimeout ? "true" : "false"
+      );
+    }
+    if (updates.tags !== void 0) {
+      fields.push(
+        "tags",
+        updates.tags !== null ? JSON.stringify(updates.tags) : "null"
+      );
+    }
+    if (updates.timezone !== void 0) {
+      fields.push("timezone", updates.timezone);
+    }
+    if (updates.allowOverlap !== void 0) {
+      fields.push("allowOverlap", updates.allowOverlap ? "true" : "false");
+    }
+    if (nextRunAt !== void 0) {
+      const val = nextRunAt !== null ? nextRunAt.getTime().toString() : "null";
+      fields.push("nextRunAt", val);
+      if (nextRunAt !== null) {
+        await this.client.zadd(
+          `${this.prefix}cron_due`,
+          nextRunAt.getTime(),
+          id.toString()
+        );
+      } else {
+        await this.client.zrem(`${this.prefix}cron_due`, id.toString());
+      }
+    }
+    if (fields.length === 0) {
+      log(`No fields to update for cron schedule ${id}`);
+      return;
+    }
+    fields.push("updatedAt", now.toString());
+    await this.client.hmset(`${this.prefix}cron:${id}`, ...fields);
+    log(`Edited cron schedule ${id}`);
+  }
+  /**
+   * Fetch all active cron schedules whose nextRunAt <= now.
+   * Uses a sorted set (cron_due) for efficient range query.
+   */
+  async getDueCronSchedules() {
+    const now = this.nowMs();
+    const ids = await this.client.zrangebyscore(
+      `${this.prefix}cron_due`,
+      0,
+      now
+    );
+    if (ids.length === 0) {
+      log("Found 0 due cron schedules");
+      return [];
+    }
+    const schedules = [];
+    for (const id of ids) {
+      const data = await this.client.hgetall(`${this.prefix}cron:${id}`);
+      if (data && Object.keys(data).length > 0 && data.status === "active") {
+        schedules.push(this.deserializeCronSchedule(data));
+      }
+    }
+    log(`Found ${schedules.length} due cron schedules`);
+    return schedules;
+  }
+  /**
+   * Update a cron schedule after a job has been enqueued.
+   * Sets lastEnqueuedAt, lastJobId, and advances nextRunAt.
+   */
+  async updateCronScheduleAfterEnqueue(id, lastEnqueuedAt, lastJobId, nextRunAt) {
+    const fields = [
+      "lastEnqueuedAt",
+      lastEnqueuedAt.getTime().toString(),
+      "lastJobId",
+      lastJobId.toString(),
+      "nextRunAt",
+      nextRunAt ? nextRunAt.getTime().toString() : "null",
+      "updatedAt",
+      this.nowMs().toString()
+    ];
+    await this.client.hmset(`${this.prefix}cron:${id}`, ...fields);
+    if (nextRunAt) {
+      await this.client.zadd(
+        `${this.prefix}cron_due`,
+        nextRunAt.getTime(),
+        id.toString()
+      );
+    } else {
+      await this.client.zrem(`${this.prefix}cron_due`, id.toString());
+    }
+    log(
+      `Updated cron schedule ${id}: lastJobId=${lastJobId}, nextRunAt=${nextRunAt?.toISOString() ?? "null"}`
+    );
+  }
+  /** Deserialize a Redis hash into a CronScheduleRecord. */
+  deserializeCronSchedule(h) {
+    const nullish = (v) => v === void 0 || v === "null" || v === "" ? null : v;
+    const numOrNull = (v) => {
+      const n = nullish(v);
+      return n === null ? null : Number(n);
+    };
+    const dateOrNull = (v) => {
+      const n = numOrNull(v);
+      return n === null ? null : new Date(n);
+    };
+    let payload;
+    try {
+      payload = JSON.parse(h.payload);
+    } catch {
+      payload = h.payload;
+    }
+    let tags;
+    try {
+      const raw = h.tags;
+      if (raw && raw !== "null") {
+        tags = JSON.parse(raw);
+      }
+    } catch {
+    }
+    return {
+      id: Number(h.id),
+      scheduleName: h.scheduleName,
+      cronExpression: h.cronExpression,
+      jobType: h.jobType,
+      payload,
+      maxAttempts: Number(h.maxAttempts),
+      priority: Number(h.priority),
+      timeoutMs: numOrNull(h.timeoutMs),
+      forceKillOnTimeout: h.forceKillOnTimeout === "true",
+      tags,
+      timezone: h.timezone,
+      allowOverlap: h.allowOverlap === "true",
+      status: h.status,
+      lastEnqueuedAt: dateOrNull(h.lastEnqueuedAt),
+      lastJobId: numOrNull(h.lastJobId),
+      nextRunAt: dateOrNull(h.nextRunAt),
+      createdAt: new Date(Number(h.createdAt)),
+      updatedAt: new Date(Number(h.updatedAt))
+    };
+  }
+  // ── Private helpers (filters) ─────────────────────────────────────────
   async applyFilters(ids, filters) {
     let result = ids;
     if (filters.jobType) {
@@ -2997,6 +3627,19 @@ var RedisBackend = class {
     return result;
   }
 };
+function getNextCronOccurrence(cronExpression, timezone = "UTC", after, CronImpl = croner.Cron) {
+  const cron = new CronImpl(cronExpression, { timezone });
+  const next = cron.nextRun(after ?? /* @__PURE__ */ new Date());
+  return next ?? null;
+}
+function validateCronExpression(cronExpression, CronImpl = croner.Cron) {
+  try {
+    new CronImpl(cronExpression);
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 // src/handler-validation.ts
 function validateHandlerSerializable2(handler, jobType) {
@@ -3091,6 +3734,49 @@ var initJobQueue = (config) => {
     }
     return pool;
   };
+  const enqueueDueCronJobsImpl = async () => {
+    const dueSchedules = await backend.getDueCronSchedules();
+    let count = 0;
+    for (const schedule of dueSchedules) {
+      if (!schedule.allowOverlap && schedule.lastJobId !== null) {
+        const lastJob = await backend.getJob(schedule.lastJobId);
+        if (lastJob && (lastJob.status === "pending" || lastJob.status === "processing" || lastJob.status === "waiting")) {
+          const nextRunAt2 = getNextCronOccurrence(
+            schedule.cronExpression,
+            schedule.timezone
+          );
+          await backend.updateCronScheduleAfterEnqueue(
+            schedule.id,
+            /* @__PURE__ */ new Date(),
+            schedule.lastJobId,
+            nextRunAt2
+          );
+          continue;
+        }
+      }
+      const jobId = await backend.addJob({
+        jobType: schedule.jobType,
+        payload: schedule.payload,
+        maxAttempts: schedule.maxAttempts,
+        priority: schedule.priority,
+        timeoutMs: schedule.timeoutMs ?? void 0,
+        forceKillOnTimeout: schedule.forceKillOnTimeout,
+        tags: schedule.tags
+      });
+      const nextRunAt = getNextCronOccurrence(
+        schedule.cronExpression,
+        schedule.timezone
+      );
+      await backend.updateCronScheduleAfterEnqueue(
+        schedule.id,
+        /* @__PURE__ */ new Date(),
+        jobId,
+        nextRunAt
+      );
+      count++;
+    }
+    return count;
+  };
   return {
     // Job queue operations
     addJob: withLogContext(
@@ -3143,8 +3829,10 @@ var initJobQueue = (config) => {
       (tags, mode = "all", limit, offset) => backend.getJobsByTags(tags, mode, limit, offset),
       config.verbose ?? false
     ),
-    // Job processing
-    createProcessor: (handlers, options) => createProcessor(backend, handlers, options),
+    // Job processing — automatically enqueues due cron jobs before each batch
+    createProcessor: (handlers, options) => createProcessor(backend, handlers, options, async () => {
+      await enqueueDueCronJobsImpl();
+    }),
     // Job events
     getJobEvents: withLogContext(
       (jobId) => backend.getJobEvents(jobId),
@@ -3167,6 +3855,82 @@ var initJobQueue = (config) => {
       () => expireTimedOutWaitpoints(requirePool()),
       config.verbose ?? false
     ),
+    // Cron schedule operations
+    addCronJob: withLogContext(
+      (options) => {
+        if (!validateCronExpression(options.cronExpression)) {
+          return Promise.reject(
+            new Error(`Invalid cron expression: "${options.cronExpression}"`)
+          );
+        }
+        const nextRunAt = getNextCronOccurrence(
+          options.cronExpression,
+          options.timezone ?? "UTC"
+        );
+        const input = {
+          scheduleName: options.scheduleName,
+          cronExpression: options.cronExpression,
+          jobType: options.jobType,
+          payload: options.payload,
+          maxAttempts: options.maxAttempts ?? 3,
+          priority: options.priority ?? 0,
+          timeoutMs: options.timeoutMs ?? null,
+          forceKillOnTimeout: options.forceKillOnTimeout ?? false,
+          tags: options.tags,
+          timezone: options.timezone ?? "UTC",
+          allowOverlap: options.allowOverlap ?? false,
+          nextRunAt
+        };
+        return backend.addCronSchedule(input);
+      },
+      config.verbose ?? false
+    ),
+    getCronJob: withLogContext(
+      (id) => backend.getCronSchedule(id),
+      config.verbose ?? false
+    ),
+    getCronJobByName: withLogContext(
+      (name) => backend.getCronScheduleByName(name),
+      config.verbose ?? false
+    ),
+    listCronJobs: withLogContext(
+      (status) => backend.listCronSchedules(status),
+      config.verbose ?? false
+    ),
+    removeCronJob: withLogContext(
+      (id) => backend.removeCronSchedule(id),
+      config.verbose ?? false
+    ),
+    pauseCronJob: withLogContext(
+      (id) => backend.pauseCronSchedule(id),
+      config.verbose ?? false
+    ),
+    resumeCronJob: withLogContext(
+      (id) => backend.resumeCronSchedule(id),
+      config.verbose ?? false
+    ),
+    editCronJob: withLogContext(
+      async (id, updates) => {
+        if (updates.cronExpression !== void 0 && !validateCronExpression(updates.cronExpression)) {
+          throw new Error(
+            `Invalid cron expression: "${updates.cronExpression}"`
+          );
+        }
+        let nextRunAt;
+        if (updates.cronExpression !== void 0 || updates.timezone !== void 0) {
+          const existing = await backend.getCronSchedule(id);
+          const expr = updates.cronExpression ?? existing?.cronExpression ?? "";
+          const tz = updates.timezone ?? existing?.timezone ?? "UTC";
+          nextRunAt = getNextCronOccurrence(expr, tz);
+        }
+        await backend.editCronSchedule(id, updates, nextRunAt);
+      },
+      config.verbose ?? false
+    ),
+    enqueueDueCronJobs: withLogContext(
+      () => enqueueDueCronJobsImpl(),
+      config.verbose ?? false
+    ),
     // Advanced access
     getPool: () => {
       if (backendType !== "postgres") {
@@ -3195,8 +3959,10 @@ exports.FailureReason = FailureReason;
 exports.JobEventType = JobEventType;
 exports.PostgresBackend = PostgresBackend;
 exports.WaitSignal = WaitSignal;
+exports.getNextCronOccurrence = getNextCronOccurrence;
 exports.initJobQueue = initJobQueue;
 exports.testHandlerSerialization = testHandlerSerialization;
+exports.validateCronExpression = validateCronExpression;
 exports.validateHandlerSerializable = validateHandlerSerializable2;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map