@monlite/cron 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emad Jumaah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @monlite/cron
+
+**Cron-style scheduling** for [`@monlite/core`](https://www.npmjs.com/package/@monlite/core), backed by SQLite. Persisted schedules (survive restarts), a zero-dependency 5-field cron parser, and atomic firing so multiple processes won't double-run. Part of the [local AI-agent harness](https://github.com/qataruts/monlite#readme).
+
+```bash
+npm install @monlite/core @monlite/cron
+```
+
+## Quick start
+
+```ts
+import { createDb } from "@monlite/core";
+import { createCron } from "@monlite/cron";
+
+const db = createDb("app.db");
+const cron = createCron(db);
+
+cron.schedule("cleanup", "0 3 * * *", async () => {
+  await purgeOldRows(); // runs every day at 03:00 (local time)
+});
+
+cron.on("error", (err, name) => console.warn(name, err));
+```
+
+## Durable scheduled work (compose with the queue)
+
+A cron handler runs in-process, so for durable work, have it **enqueue** a job
+into [`@monlite/queue`](https://www.npmjs.com/package/@monlite/queue) — the
+schedule is persisted and the work is durable & retried:
+
+```ts
+import { createQueue } from "@monlite/queue";
+const queue = createQueue(db);
+queue.process("report", async (job) => generateReport(job.payload));
+
+cron.schedule("nightly-report", "0 0 * * *", () => {
+  queue.add("report", { day: new Date().toISOString() });
+});
+```
+
+## Cron syntax
+
+Standard 5 fields — `minute hour day-of-month month day-of-week`:
+
+```
+*     every value          0 9 * * 1     09:00 every Monday
+*/15  every 15             */15 * * * *  every 15 minutes
+1-5   range                0 9-17 * * *  hourly, 9am–5pm
+1,15  list                 0 0 1,15 * *  1st and 15th at midnight
+```
+
+Day-of-week is `0–6` (0 = Sunday). Times are **local**. When both day-of-month
+and day-of-week are restricted, either match fires (POSIX behavior).
+
+## API
+
+```ts
+const cron = createCron(db, { checkInterval: 1000 }); // poll cadence (ms)
+cron.schedule(name, cronExpr, handler); // register/update + start
+cron.unschedule(name);                  // remove
+cron.next(name);                        // next run (epoch ms) | undefined
+cron.on("error", (err, name) => {});
+cron.stop();                            // stop scheduling (schedules persist)
+
+// utility:
+import { nextCronRun } from "@monlite/cron";
+nextCronRun("0 9 * * 1"); // → Date of the next Monday 09:00
+```
+
+Firing is **atomic** (a claim on the schedule row), so running the same schedule
+in multiple processes fires each occurrence exactly once.
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,142 @@
+'use strict';
+
+var events = require('events');
+
+// src/index.ts
+function parseField(field, min, max) {
+  const out = /* @__PURE__ */ new Set();
+  for (const part of field.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart === void 0 ? 1 : parseInt(stepPart, 10);
+    let lo;
+    let hi;
+    if (rangePart === "*") {
+      lo = min;
+      hi = max;
+    } else if (rangePart.includes("-")) {
+      const [a, b] = rangePart.split("-");
+      lo = parseInt(a, 10);
+      hi = parseInt(b, 10);
+    } else {
+      lo = hi = parseInt(rangePart, 10);
+    }
+    if (Number.isNaN(lo) || Number.isNaN(hi) || Number.isNaN(step) || step < 1 || lo < min || hi > max || lo > hi) {
+      throw new Error(`Invalid cron field "${field}" (expected ${min}-${max})`);
+    }
+    for (let v = lo; v <= hi; v += step) out.add(v);
+  }
+  return out;
+}
+function parseCron(expr) {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(
+      `Cron expression must have 5 fields, got ${parts.length}: "${expr}"`
+    );
+  }
+  return {
+    minute: parseField(parts[0], 0, 59),
+    hour: parseField(parts[1], 0, 23),
+    dom: parseField(parts[2], 1, 31),
+    month: parseField(parts[3], 1, 12),
+    dow: parseField(parts[4], 0, 6),
+    domRestricted: parts[2] !== "*",
+    dowRestricted: parts[4] !== "*"
+  };
+}
+function dayMatches(c, d) {
+  const dom = c.dom.has(d.getDate());
+  const dow = c.dow.has(d.getDay());
+  if (c.domRestricted && c.dowRestricted) return dom || dow;
+  return dom && dow;
+}
+function nextCronRun(expr, from = /* @__PURE__ */ new Date()) {
+  const c = typeof expr === "string" ? parseCron(expr) : expr;
+  const d = new Date(from.getTime());
+  d.setSeconds(0, 0);
+  d.setMinutes(d.getMinutes() + 1);
+  for (let i = 0; i < 366 * 24 * 60 + 60; i++) {
+    if (c.minute.has(d.getMinutes()) && c.hour.has(d.getHours()) && c.month.has(d.getMonth() + 1) && dayMatches(c, d)) {
+      return d;
+    }
+    d.setMinutes(d.getMinutes() + 1);
+  }
+  throw new Error(`Could not compute next run for cron "${expr}"`);
+}
+var ensured = /* @__PURE__ */ new WeakSet();
+var nowMs = () => Date.now();
+var Cron = class extends events.EventEmitter {
+  driver;
+  checkInterval;
+  handlers = /* @__PURE__ */ new Map();
+  timer;
+  constructor(db, opts = {}) {
+    super();
+    this.driver = db.driver;
+    this.checkInterval = opts.checkInterval ?? 1e3;
+    if (!ensured.has(db)) {
+      this.driver.exec(
+        `CREATE TABLE IF NOT EXISTS _schedules (
+          name TEXT PRIMARY KEY, cron TEXT NOT NULL,
+          next_run INTEGER NOT NULL, last_run INTEGER
+        )`
+      );
+      ensured.add(db);
+    }
+  }
+  /** Register (or update) a schedule and start the scheduler. */
+  schedule(name, expr, handler) {
+    const c = parseCron(expr);
+    const existing = this.driver.prepare(`SELECT next_run FROM _schedules WHERE name = ?`).get(name);
+    const next = existing ? existing.next_run : nextCronRun(c).getTime();
+    this.driver.prepare(
+      `INSERT INTO _schedules (name, cron, next_run, last_run) VALUES (?, ?, ?, NULL)
+         ON CONFLICT(name) DO UPDATE SET cron = excluded.cron`
+    ).run(name, expr, next);
+    this.handlers.set(name, { c, fn: handler });
+    if (!this.timer) {
+      this.timer = setInterval(() => this.tick(), this.checkInterval);
+      this.timer.unref?.();
+    }
+  }
+  /** Remove a schedule. */
+  unschedule(name) {
+    this.handlers.delete(name);
+    this.driver.prepare(`DELETE FROM _schedules WHERE name = ?`).run(name);
+  }
+  /** The next scheduled run (epoch ms) for a registered schedule. */
+  next(name) {
+    const row = this.driver.prepare(`SELECT next_run FROM _schedules WHERE name = ?`).get(name);
+    return row?.next_run;
+  }
+  /** @internal — exposed for tests; runs one scheduling pass. */
+  tick() {
+    const t = nowMs();
+    for (const [name, reg] of this.handlers) {
+      const row = this.driver.prepare(`SELECT next_run FROM _schedules WHERE name = ?`).get(name);
+      if (!row || row.next_run > t) continue;
+      const next = nextCronRun(reg.c, new Date(t)).getTime();
+      const claimed = this.driver.prepare(
+        `UPDATE _schedules SET last_run = ?, next_run = ? WHERE name = ? AND next_run <= ?`
+      ).run(t, next, name, t).changes > 0;
+      if (claimed) {
+        Promise.resolve().then(() => reg.fn()).catch((err) => this.emit("error", err, name));
+      }
+    }
+  }
+  /** Stop the scheduler (schedules remain persisted). */
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+  }
+};
+function createCron(db, opts) {
+  return new Cron(db, opts);
+}
+
+exports.Cron = Cron;
+exports.createCron = createCron;
+exports.nextCronRun = nextCronRun;
+exports.parseCron = parseCron;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["EventEmitter"],"mappings":"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","file":"index.cjs","sourcesContent":["import { EventEmitter } from \"node:events\";\nimport type { Monlite } from \"@monlite/core\";\n\nexport interface CronOptions {\n  /** How often the scheduler checks for due jobs (ms). Default 1000. */\n  checkInterval?: number;\n}\n\nexport type CronHandler = () => void | Promise<void>;\n\nexport interface ParsedCron {\n  minute: Set<number>;\n  hour: Set<number>;\n  dom: Set<number>;\n  month: Set<number>;\n  dow: Set<number>;\n  domRestricted: boolean;\n  dowRestricted: boolean;\n}\n\nfunction parseField(field: string, min: number, max: number): Set<number> {\n  const out = new Set<number>();\n  for (const part of field.split(\",\")) {\n    const [rangePart, stepPart] = part.split(\"/\");\n    const step = stepPart === undefined ? 1 : parseInt(stepPart, 10);\n    let lo: number;\n    let hi: number;\n    if (rangePart === \"*\") {\n      lo = min;\n      hi = max;\n    } else if (rangePart.includes(\"-\")) {\n      const [a, b] = rangePart.split(\"-\");\n      lo = parseInt(a, 10);\n      hi = parseInt(b, 10);\n    } else {\n      lo = hi = parseInt(rangePart, 10);\n    }\n    if (\n      Number.isNaN(lo) ||\n      Number.isNaN(hi) ||\n      Number.isNaN(step) ||\n      step < 1 ||\n      lo < min ||\n      hi > max ||\n      lo > hi\n    ) {\n      throw new Error(`Invalid cron field \"${field}\" (expected ${min}-${max})`);\n    }\n    for (let v = lo; v <= hi; v += step) out.add(v);\n  }\n  return out;\n}\n\n/** Parse a standard 5-field cron expression (`min hour dom month dow`). */\nexport function parseCron(expr: string): ParsedCron {\n  const parts = expr.trim().split(/\\s+/);\n  if (parts.length !== 5) {\n    throw new Error(\n      `Cron expression must have 5 fields, got ${parts.length}: \"${expr}\"`,\n    );\n  }\n  return {\n    minute: parseField(parts[0], 0, 59),\n    hour: parseField(parts[1], 0, 23),\n    dom: parseField(parts[2], 1, 31),\n    month: parseField(parts[3], 1, 12),\n    dow: parseField(parts[4], 0, 6),\n    domRestricted: parts[2] !== \"*\",\n    dowRestricted: parts[4] !== \"*\",\n  };\n}\n\nfunction dayMatches(c: ParsedCron, d: Date): boolean {\n  const dom = c.dom.has(d.getDate());\n  const dow = c.dow.has(d.getDay()); // 0 = Sunday\n  // POSIX: when both day-of-month and day-of-week are restricted, either matches.\n  if (c.domRestricted && c.dowRestricted) return dom || dow;\n  return dom && dow;\n}\n\n/** The next time (strictly after `from`, local time) a cron expression fires. */\nexport function nextCronRun(\n  expr: string | ParsedCron,\n  from: Date = new Date(),\n): Date {\n  const c = typeof expr === \"string\" ? parseCron(expr) : expr;\n  const d = new Date(from.getTime());\n  d.setSeconds(0, 0);\n  d.setMinutes(d.getMinutes() + 1);\n  for (let i = 0; i < 366 * 24 * 60 + 60; i++) {\n    if (\n      c.minute.has(d.getMinutes()) &&\n      c.hour.has(d.getHours()) &&\n      c.month.has(d.getMonth() + 1) &&\n      dayMatches(c, d)\n    ) {\n      return d;\n    }\n    d.setMinutes(d.getMinutes() + 1);\n  }\n  throw new Error(`Could not compute next run for cron \"${expr}\"`);\n}\n\nconst ensured = new WeakSet<object>();\nconst nowMs = () => Date.now();\n\n/**\n * A persisted cron scheduler. Schedules survive restarts (next-run is stored),\n * and firing is atomic so multiple processes won't double-run an occurrence.\n * Compose with a queue for durable work: `cron.schedule(n, expr, () => queue.add(...))`.\n * Emits `\"error\"` (err, name) if a handler throws.\n */\nexport class Cron extends EventEmitter {\n  private readonly driver: Monlite[\"driver\"];\n  private readonly checkInterval: number;\n  private readonly handlers = new Map<\n    string,\n    { c: ParsedCron; fn: CronHandler }\n  >();\n  private timer: ReturnType<typeof setInterval> | undefined;\n\n  constructor(db: Monlite, opts: CronOptions = {}) {\n    super();\n    this.driver = db.driver;\n    this.checkInterval = opts.checkInterval ?? 1000;\n    if (!ensured.has(db)) {\n      this.driver.exec(\n        `CREATE TABLE IF NOT EXISTS _schedules (\n          name TEXT PRIMARY KEY, cron TEXT NOT NULL,\n          next_run INTEGER NOT NULL, last_run INTEGER\n        )`,\n      );\n      ensured.add(db);\n    }\n  }\n\n  /** Register (or update) a schedule and start the scheduler. */\n  schedule(name: string, expr: string, handler: CronHandler): void {\n    const c = parseCron(expr);\n    const existing = this.driver\n      .prepare(`SELECT next_run FROM _schedules WHERE name = ?`)\n      .get(name) as { next_run: number } | undefined;\n    const next = existing ? existing.next_run : nextCronRun(c).getTime();\n    this.driver\n      .prepare(\n        `INSERT INTO _schedules (name, cron, next_run, last_run) VALUES (?, ?, ?, NULL)\n         ON CONFLICT(name) DO UPDATE SET cron = excluded.cron`,\n      )\n      .run(name, expr, next);\n    this.handlers.set(name, { c, fn: handler });\n    if (!this.timer) {\n      this.timer = setInterval(() => this.tick(), this.checkInterval);\n      this.timer.unref?.();\n    }\n  }\n\n  /** Remove a schedule. */\n  unschedule(name: string): void {\n    this.handlers.delete(name);\n    this.driver.prepare(`DELETE FROM _schedules WHERE name = ?`).run(name);\n  }\n\n  /** The next scheduled run (epoch ms) for a registered schedule. */\n  next(name: string): number | undefined {\n    const row = this.driver\n      .prepare(`SELECT next_run FROM _schedules WHERE name = ?`)\n      .get(name) as { next_run: number } | undefined;\n    return row?.next_run;\n  }\n\n  /** @internal — exposed for tests; runs one scheduling pass. */\n  tick(): void {\n    const t = nowMs();\n    for (const [name, reg] of this.handlers) {\n      const row = this.driver\n        .prepare(`SELECT next_run FROM _schedules WHERE name = ?`)\n        .get(name) as { next_run: number } | undefined;\n      if (!row || row.next_run > t) continue;\n      const next = nextCronRun(reg.c, new Date(t)).getTime();\n      // Atomic claim: only the process that flips next_run gets to fire.\n      const claimed =\n        this.driver\n          .prepare(\n            `UPDATE _schedules SET last_run = ?, next_run = ? WHERE name = ? AND next_run <= ?`,\n          )\n          .run(t, next, name, t).changes > 0;\n      if (claimed) {\n        Promise.resolve()\n          .then(() => reg.fn())\n          .catch((err) => this.emit(\"error\", err, name));\n      }\n    }\n  }\n\n  /** Stop the scheduler (schedules remain persisted). */\n  stop(): void {\n    if (this.timer) clearInterval(this.timer);\n    this.timer = undefined;\n  }\n}\n\n/** Create a cron scheduler over a monlite database. */\nexport function createCron(db: Monlite, opts?: CronOptions): Cron {\n  return new Cron(db, opts);\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,48 @@
+import { EventEmitter } from 'node:events';
+import { Monlite } from '@monlite/core';
+
+interface CronOptions {
+    /** How often the scheduler checks for due jobs (ms). Default 1000. */
+    checkInterval?: number;
+}
+type CronHandler = () => void | Promise<void>;
+interface ParsedCron {
+    minute: Set<number>;
+    hour: Set<number>;
+    dom: Set<number>;
+    month: Set<number>;
+    dow: Set<number>;
+    domRestricted: boolean;
+    dowRestricted: boolean;
+}
+/** Parse a standard 5-field cron expression (`min hour dom month dow`). */
+declare function parseCron(expr: string): ParsedCron;
+/** The next time (strictly after `from`, local time) a cron expression fires. */
+declare function nextCronRun(expr: string | ParsedCron, from?: Date): Date;
+/**
+ * A persisted cron scheduler. Schedules survive restarts (next-run is stored),
+ * and firing is atomic so multiple processes won't double-run an occurrence.
+ * Compose with a queue for durable work: `cron.schedule(n, expr, () => queue.add(...))`.
+ * Emits `"error"` (err, name) if a handler throws.
+ */
+declare class Cron extends EventEmitter {
+    private readonly driver;
+    private readonly checkInterval;
+    private readonly handlers;
+    private timer;
+    constructor(db: Monlite, opts?: CronOptions);
+    /** Register (or update) a schedule and start the scheduler. */
+    schedule(name: string, expr: string, handler: CronHandler): void;
+    /** Remove a schedule. */
+    unschedule(name: string): void;
+    /** The next scheduled run (epoch ms) for a registered schedule. */
+    next(name: string): number | undefined;
+    /** @internal — exposed for tests; runs one scheduling pass. */
+    tick(): void;
+    /** Stop the scheduler (schedules remain persisted). */
+    stop(): void;
+}
+/** Create a cron scheduler over a monlite database. */
+declare function createCron(db: Monlite, opts?: CronOptions): Cron;
+
+export { Cron, type CronHandler, type CronOptions, type ParsedCron, createCron, nextCronRun, parseCron };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { EventEmitter } from 'node:events';
+import { Monlite } from '@monlite/core';
+
+interface CronOptions {
+    /** How often the scheduler checks for due jobs (ms). Default 1000. */
+    checkInterval?: number;
+}
+type CronHandler = () => void | Promise<void>;
+interface ParsedCron {
+    minute: Set<number>;
+    hour: Set<number>;
+    dom: Set<number>;
+    month: Set<number>;
+    dow: Set<number>;
+    domRestricted: boolean;
+    dowRestricted: boolean;
+}
+/** Parse a standard 5-field cron expression (`min hour dom month dow`). */
+declare function parseCron(expr: string): ParsedCron;
+/** The next time (strictly after `from`, local time) a cron expression fires. */
+declare function nextCronRun(expr: string | ParsedCron, from?: Date): Date;
+/**
+ * A persisted cron scheduler. Schedules survive restarts (next-run is stored),
+ * and firing is atomic so multiple processes won't double-run an occurrence.
+ * Compose with a queue for durable work: `cron.schedule(n, expr, () => queue.add(...))`.
+ * Emits `"error"` (err, name) if a handler throws.
+ */
+declare class Cron extends EventEmitter {
+    private readonly driver;
+    private readonly checkInterval;
+    private readonly handlers;
+    private timer;
+    constructor(db: Monlite, opts?: CronOptions);
+    /** Register (or update) a schedule and start the scheduler. */
+    schedule(name: string, expr: string, handler: CronHandler): void;
+    /** Remove a schedule. */
+    unschedule(name: string): void;
+    /** The next scheduled run (epoch ms) for a registered schedule. */
+    next(name: string): number | undefined;
+    /** @internal — exposed for tests; runs one scheduling pass. */
+    tick(): void;
+    /** Stop the scheduler (schedules remain persisted). */
+    stop(): void;
+}
+/** Create a cron scheduler over a monlite database. */
+declare function createCron(db: Monlite, opts?: CronOptions): Cron;
+
+export { Cron, type CronHandler, type CronOptions, type ParsedCron, createCron, nextCronRun, parseCron };

package/dist/index.js

@@ -0,0 +1,137 @@
+import { EventEmitter } from 'events';
+
+// src/index.ts
+function parseField(field, min, max) {
+  const out = /* @__PURE__ */ new Set();
+  for (const part of field.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart === void 0 ? 1 : parseInt(stepPart, 10);
+    let lo;
+    let hi;
+    if (rangePart === "*") {
+      lo = min;
+      hi = max;
+    } else if (rangePart.includes("-")) {
+      const [a, b] = rangePart.split("-");
+      lo = parseInt(a, 10);
+      hi = parseInt(b, 10);
+    } else {
+      lo = hi = parseInt(rangePart, 10);
+    }
+    if (Number.isNaN(lo) || Number.isNaN(hi) || Number.isNaN(step) || step < 1 || lo < min || hi > max || lo > hi) {
+      throw new Error(`Invalid cron field "${field}" (expected ${min}-${max})`);
+    }
+    for (let v = lo; v <= hi; v += step) out.add(v);
+  }
+  return out;
+}
+function parseCron(expr) {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(
+      `Cron expression must have 5 fields, got ${parts.length}: "${expr}"`
+    );
+  }
+  return {
+    minute: parseField(parts[0], 0, 59),
+    hour: parseField(parts[1], 0, 23),
+    dom: parseField(parts[2], 1, 31),
+    month: parseField(parts[3], 1, 12),
+    dow: parseField(parts[4], 0, 6),
+    domRestricted: parts[2] !== "*",
+    dowRestricted: parts[4] !== "*"
+  };
+}
+function dayMatches(c, d) {
+  const dom = c.dom.has(d.getDate());
+  const dow = c.dow.has(d.getDay());
+  if (c.domRestricted && c.dowRestricted) return dom || dow;
+  return dom && dow;
+}
+function nextCronRun(expr, from = /* @__PURE__ */ new Date()) {
+  const c = typeof expr === "string" ? parseCron(expr) : expr;
+  const d = new Date(from.getTime());
+  d.setSeconds(0, 0);
+  d.setMinutes(d.getMinutes() + 1);
+  for (let i = 0; i < 366 * 24 * 60 + 60; i++) {
+    if (c.minute.has(d.getMinutes()) && c.hour.has(d.getHours()) && c.month.has(d.getMonth() + 1) && dayMatches(c, d)) {
+      return d;
+    }
+    d.setMinutes(d.getMinutes() + 1);
+  }
+  throw new Error(`Could not compute next run for cron "${expr}"`);
+}
+var ensured = /* @__PURE__ */ new WeakSet();
+var nowMs = () => Date.now();
+var Cron = class extends EventEmitter {
+  driver;
+  checkInterval;
+  handlers = /* @__PURE__ */ new Map();
+  timer;
+  constructor(db, opts = {}) {
+    super();
+    this.driver = db.driver;
+    this.checkInterval = opts.checkInterval ?? 1e3;
+    if (!ensured.has(db)) {
+      this.driver.exec(
+        `CREATE TABLE IF NOT EXISTS _schedules (
+          name TEXT PRIMARY KEY, cron TEXT NOT NULL,
+          next_run INTEGER NOT NULL, last_run INTEGER
+        )`
+      );
+      ensured.add(db);
+    }
+  }
+  /** Register (or update) a schedule and start the scheduler. */
+  schedule(name, expr, handler) {
+    const c = parseCron(expr);
+    const existing = this.driver.prepare(`SELECT next_run FROM _schedules WHERE name = ?`).get(name);
+    const next = existing ? existing.next_run : nextCronRun(c).getTime();
+    this.driver.prepare(
+      `INSERT INTO _schedules (name, cron, next_run, last_run) VALUES (?, ?, ?, NULL)
+         ON CONFLICT(name) DO UPDATE SET cron = excluded.cron`
+    ).run(name, expr, next);
+    this.handlers.set(name, { c, fn: handler });
+    if (!this.timer) {
+      this.timer = setInterval(() => this.tick(), this.checkInterval);
+      this.timer.unref?.();
+    }
+  }
+  /** Remove a schedule. */
+  unschedule(name) {
+    this.handlers.delete(name);
+    this.driver.prepare(`DELETE FROM _schedules WHERE name = ?`).run(name);
+  }
+  /** The next scheduled run (epoch ms) for a registered schedule. */
+  next(name) {
+    const row = this.driver.prepare(`SELECT next_run FROM _schedules WHERE name = ?`).get(name);
+    return row?.next_run;
+  }
+  /** @internal — exposed for tests; runs one scheduling pass. */
+  tick() {
+    const t = nowMs();
+    for (const [name, reg] of this.handlers) {
+      const row = this.driver.prepare(`SELECT next_run FROM _schedules WHERE name = ?`).get(name);
+      if (!row || row.next_run > t) continue;
+      const next = nextCronRun(reg.c, new Date(t)).getTime();
+      const claimed = this.driver.prepare(
+        `UPDATE _schedules SET last_run = ?, next_run = ? WHERE name = ? AND next_run <= ?`
+      ).run(t, next, name, t).changes > 0;
+      if (claimed) {
+        Promise.resolve().then(() => reg.fn()).catch((err) => this.emit("error", err, name));
+      }
+    }
+  }
+  /** Stop the scheduler (schedules remain persisted). */
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+  }
+};
+function createCron(db, opts) {
+  return new Cron(db, opts);
+}
+
+export { Cron, createCron, nextCronRun, parseCron };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { EventEmitter } from \"node:events\";\nimport type { Monlite } from \"@monlite/core\";\n\nexport interface CronOptions {\n  /** How often the scheduler checks for due jobs (ms). Default 1000. */\n  checkInterval?: number;\n}\n\nexport type CronHandler = () => void | Promise<void>;\n\nexport interface ParsedCron {\n  minute: Set<number>;\n  hour: Set<number>;\n  dom: Set<number>;\n  month: Set<number>;\n  dow: Set<number>;\n  domRestricted: boolean;\n  dowRestricted: boolean;\n}\n\nfunction parseField(field: string, min: number, max: number): Set<number> {\n  const out = new Set<number>();\n  for (const part of field.split(\",\")) {\n    const [rangePart, stepPart] = part.split(\"/\");\n    const step = stepPart === undefined ? 1 : parseInt(stepPart, 10);\n    let lo: number;\n    let hi: number;\n    if (rangePart === \"*\") {\n      lo = min;\n      hi = max;\n    } else if (rangePart.includes(\"-\")) {\n      const [a, b] = rangePart.split(\"-\");\n      lo = parseInt(a, 10);\n      hi = parseInt(b, 10);\n    } else {\n      lo = hi = parseInt(rangePart, 10);\n    }\n    if (\n      Number.isNaN(lo) ||\n      Number.isNaN(hi) ||\n      Number.isNaN(step) ||\n      step < 1 ||\n      lo < min ||\n      hi > max ||\n      lo > hi\n    ) {\n      throw new Error(`Invalid cron field \"${field}\" (expected ${min}-${max})`);\n    }\n    for (let v = lo; v <= hi; v += step) out.add(v);\n  }\n  return out;\n}\n\n/** Parse a standard 5-field cron expression (`min hour dom month dow`). */\nexport function parseCron(expr: string): ParsedCron {\n  const parts = expr.trim().split(/\\s+/);\n  if (parts.length !== 5) {\n    throw new Error(\n      `Cron expression must have 5 fields, got ${parts.length}: \"${expr}\"`,\n    );\n  }\n  return {\n    minute: parseField(parts[0], 0, 59),\n    hour: parseField(parts[1], 0, 23),\n    dom: parseField(parts[2], 1, 31),\n    month: parseField(parts[3], 1, 12),\n    dow: parseField(parts[4], 0, 6),\n    domRestricted: parts[2] !== \"*\",\n    dowRestricted: parts[4] !== \"*\",\n  };\n}\n\nfunction dayMatches(c: ParsedCron, d: Date): boolean {\n  const dom = c.dom.has(d.getDate());\n  const dow = c.dow.has(d.getDay()); // 0 = Sunday\n  // POSIX: when both day-of-month and day-of-week are restricted, either matches.\n  if (c.domRestricted && c.dowRestricted) return dom || dow;\n  return dom && dow;\n}\n\n/** The next time (strictly after `from`, local time) a cron expression fires. */\nexport function nextCronRun(\n  expr: string | ParsedCron,\n  from: Date = new Date(),\n): Date {\n  const c = typeof expr === \"string\" ? parseCron(expr) : expr;\n  const d = new Date(from.getTime());\n  d.setSeconds(0, 0);\n  d.setMinutes(d.getMinutes() + 1);\n  for (let i = 0; i < 366 * 24 * 60 + 60; i++) {\n    if (\n      c.minute.has(d.getMinutes()) &&\n      c.hour.has(d.getHours()) &&\n      c.month.has(d.getMonth() + 1) &&\n      dayMatches(c, d)\n    ) {\n      return d;\n    }\n    d.setMinutes(d.getMinutes() + 1);\n  }\n  throw new Error(`Could not compute next run for cron \"${expr}\"`);\n}\n\nconst ensured = new WeakSet<object>();\nconst nowMs = () => Date.now();\n\n/**\n * A persisted cron scheduler. Schedules survive restarts (next-run is stored),\n * and firing is atomic so multiple processes won't double-run an occurrence.\n * Compose with a queue for durable work: `cron.schedule(n, expr, () => queue.add(...))`.\n * Emits `\"error\"` (err, name) if a handler throws.\n */\nexport class Cron extends EventEmitter {\n  private readonly driver: Monlite[\"driver\"];\n  private readonly checkInterval: number;\n  private readonly handlers = new Map<\n    string,\n    { c: ParsedCron; fn: CronHandler }\n  >();\n  private timer: ReturnType<typeof setInterval> | undefined;\n\n  constructor(db: Monlite, opts: CronOptions = {}) {\n    super();\n    this.driver = db.driver;\n    this.checkInterval = opts.checkInterval ?? 1000;\n    if (!ensured.has(db)) {\n      this.driver.exec(\n        `CREATE TABLE IF NOT EXISTS _schedules (\n          name TEXT PRIMARY KEY, cron TEXT NOT NULL,\n          next_run INTEGER NOT NULL, last_run INTEGER\n        )`,\n      );\n      ensured.add(db);\n    }\n  }\n\n  /** Register (or update) a schedule and start the scheduler. */\n  schedule(name: string, expr: string, handler: CronHandler): void {\n    const c = parseCron(expr);\n    const existing = this.driver\n      .prepare(`SELECT next_run FROM _schedules WHERE name = ?`)\n      .get(name) as { next_run: number } | undefined;\n    const next = existing ? existing.next_run : nextCronRun(c).getTime();\n    this.driver\n      .prepare(\n        `INSERT INTO _schedules (name, cron, next_run, last_run) VALUES (?, ?, ?, NULL)\n         ON CONFLICT(name) DO UPDATE SET cron = excluded.cron`,\n      )\n      .run(name, expr, next);\n    this.handlers.set(name, { c, fn: handler });\n    if (!this.timer) {\n      this.timer = setInterval(() => this.tick(), this.checkInterval);\n      this.timer.unref?.();\n    }\n  }\n\n  /** Remove a schedule. */\n  unschedule(name: string): void {\n    this.handlers.delete(name);\n    this.driver.prepare(`DELETE FROM _schedules WHERE name = ?`).run(name);\n  }\n\n  /** The next scheduled run (epoch ms) for a registered schedule. */\n  next(name: string): number | undefined {\n    const row = this.driver\n      .prepare(`SELECT next_run FROM _schedules WHERE name = ?`)\n      .get(name) as { next_run: number } | undefined;\n    return row?.next_run;\n  }\n\n  /** @internal — exposed for tests; runs one scheduling pass. */\n  tick(): void {\n    const t = nowMs();\n    for (const [name, reg] of this.handlers) {\n      const row = this.driver\n        .prepare(`SELECT next_run FROM _schedules WHERE name = ?`)\n        .get(name) as { next_run: number } | undefined;\n      if (!row || row.next_run > t) continue;\n      const next = nextCronRun(reg.c, new Date(t)).getTime();\n      // Atomic claim: only the process that flips next_run gets to fire.\n      const claimed =\n        this.driver\n          .prepare(\n            `UPDATE _schedules SET last_run = ?, next_run = ? WHERE name = ? AND next_run <= ?`,\n          )\n          .run(t, next, name, t).changes > 0;\n      if (claimed) {\n        Promise.resolve()\n          .then(() => reg.fn())\n          .catch((err) => this.emit(\"error\", err, name));\n      }\n    }\n  }\n\n  /** Stop the scheduler (schedules remain persisted). */\n  stop(): void {\n    if (this.timer) clearInterval(this.timer);\n    this.timer = undefined;\n  }\n}\n\n/** Create a cron scheduler over a monlite database. */\nexport function createCron(db: Monlite, opts?: CronOptions): Cron {\n  return new Cron(db, opts);\n}\n"]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@monlite/cron",
+  "version": "0.1.0",
+  "description": "Cron-style job scheduling for @monlite/core: persisted schedules, 5-field cron, multi-process safe.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "monlite",
+    "cron",
+    "scheduler",
+    "schedule",
+    "jobs",
+    "tasks",
+    "sqlite"
+  ],
+  "license": "MIT",
+  "author": "Emad Jumaah <emadjumaah@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qataruts/monlite.git",
+    "directory": "packages/kv"
+  },
+  "homepage": "https://github.com/qataruts/monlite/tree/main/packages/kv#readme",
+  "bugs": {
+    "url": "https://github.com/qataruts/monlite/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@monlite/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "better-sqlite3": "^11.8.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}