morpho-socket 0.3.0 → 0.4.0

package/packages/pending/index.js

@@ -0,0 +1,117 @@
+// @morpho/pending
+//
+// "Somebody proposes something, somebody else accepts it, or it expires": a challenge, an invite, a trade offer,
+// a "are you sure? yes/no". Morpho doesn't know what the request MEANS — it only holds it, lets exactly one
+// caller take it, and forgets it when its time is up.
+//
+//   const pending = createPending({ ttlMs: 2 * 60_000 })                    // in memory
+//   const pending = createPending({ store: db.collection("pending") })      // survives restarts (@morpho/kv)
+//
+//   const key = pending.key(g.chatId, target.number)                        // who is expected to answer
+//   const r = pending.create(key, { from: g.user.number, kind: "duel" })    // -> { ok: true, request }
+//   // r.ok === false, r.reason === "already-pending", r.request  -> there is one open already
+//
+//   const t = pending.take(key, { match: req => req.data.kind === "duel" }) // -> { ok: true, request }
+//   // t.ok === false, t.reason === "not-found" (never existed / expired / already taken) | "mismatch" (left untouched)
+//
+// Expected outcomes are values, never exceptions. Wrong usage (bad key, bad ttl) throws TypeError.
+// `store` is duck-typed and must be SYNCHRONOUS: get(key, fallback), set(key, value, { ttl }), delete(key), entries(prefix).
+// A @morpho/kv collection fits. Expiry is also checked here (request.expiresAt), so it never depends on the store's clock.
+
+const DEFAULT_TTL_MS = 2 * 60_000
+
+function memoryStore(now) {
+  const m = new Map()
+  const alive = e => e && (e.exp == null || e.exp > now())
+  return {
+    get(k, fallback) { const e = m.get(k); if (alive(e)) return e.v; m.delete(k); return fallback },
+    set(k, v, { ttl } = {}) { m.set(k, { v, exp: ttl == null ? null : now() + ttl }); return v },
+    delete(k) { return m.delete(k) },
+    entries(prefix = "") {
+      const out = []
+      for (const [k, e] of m) {
+        if (!alive(e)) { m.delete(k); continue }
+        if (k.startsWith(prefix)) out.push([k, e.v])
+      }
+      return out
+    },
+  }
+}
+
+const part = x => {
+  if (typeof x === "number" && Number.isFinite(x)) x = String(x)
+  if (typeof x !== "string" || !x) throw new TypeError("pending: keys and key parts must be non-empty strings")
+  return x
+}
+
+function createPending({ store, ttlMs = DEFAULT_TTL_MS, now = Date.now } = {}) {
+  if (!(ttlMs > 0) || !Number.isFinite(ttlMs)) throw new TypeError("pending: ttlMs must be a positive number (ms)")
+  store = store || memoryStore(now)
+  for (const fn of ["get", "set", "delete", "entries"])
+    if (typeof store[fn] !== "function") throw new TypeError(`pending: store needs a ${fn}() method (a @morpho/kv collection works)`)
+
+  function make(prefix) {
+    const full = k => prefix + part(k)
+    const view = rec => (rec ? { ...rec, msLeft: Math.max(0, rec.expiresAt - now()) } : null)
+    // the live record for a key (or null); an expired one is dropped on the way
+    const read = k => {
+      const f = full(k)
+      const rec = store.get(f)
+      if (!rec) return null
+      if (rec.expiresAt <= now()) { store.delete(f); return null }
+      return rec
+    }
+
+    const api = {
+      // a key from parts: pending.key(chatId, number) -> "chatId|number"
+      key(...parts) { if (!parts.length) throw new TypeError("pending.key: pass at least one part"); return parts.map(part).join("|") },
+
+      // opts: { ttl: ms (default ttlMs), replace: false }
+      create(key, data, { ttl = ttlMs, replace = false } = {}) {
+        if (!(ttl > 0) || !Number.isFinite(ttl)) throw new TypeError("pending.create: ttl must be a positive number (ms)")
+        const existing = read(key)
+        if (existing && !replace) return { ok: false, reason: "already-pending", request: view(existing) }
+        const t = now()
+        const rec = { key: part(key), data: data === undefined ? null : data, createdAt: t, expiresAt: t + ttl }
+        store.set(full(key), rec, { ttl })
+        return { ok: true, request: view(rec) }
+      },
+
+      // look without consuming
+      peek(key) { return view(read(key)) },
+      has(key) { return !!read(key) },
+
+      // consume it. opts.match(request) -> false leaves it in place and answers "mismatch"
+      take(key, { match } = {}) {
+        const rec = read(key)
+        if (!rec) return { ok: false, reason: "not-found" }
+        const v = view(rec)
+        if (match && !match(v)) return { ok: false, reason: "mismatch", request: v }
+        store.delete(full(key))
+        return { ok: true, request: v }
+      },
+
+      cancel(key) { const had = !!read(key); if (had) store.delete(full(key)); return had },
+
+      // every open request under a key prefix, oldest first
+      list(keyPrefix = "") {
+        return store.entries(prefix + keyPrefix)
+          .map(([, rec]) => rec)
+          .filter(rec => rec && rec.expiresAt > now())
+          .sort((a, b) => a.createdAt - b.createdAt)
+          .map(view)
+      },
+      clear(keyPrefix = "") { let n = 0; for (const r of api.list(keyPrefix)) if (store.delete(full(r.key))) n++; return n },
+
+      // a narrower view: pending.sub(clientId, chatId) -> keys are isolated from everyone else's
+      sub(...parts) {
+        if (!parts.length) throw new TypeError("pending.sub: pass at least one part")
+        return make(prefix + parts.map(p => { const s = part(p); if (s.includes("/")) throw new TypeError(`pending.sub: "${s}" can't contain "/"`); return s }).join("/") + "/")
+      },
+    }
+    return api
+  }
+  return make("")
+}
+
+module.exports = { createPending, DEFAULT_TTL_MS }

package/packages/pending/package.json

@@ -0,0 +1 @@
+{ "name": "@morpho/pending", "version": "0.1.0", "description": "Requests that wait for an answer and expire by themselves: invites, challenges, trades, confirmations. In memory or on top of @morpho/kv.", "main": "index.js", "license": "MIT" }

package/packages/scheduler/README.md

@@ -0,0 +1,79 @@
+# morpho-socket/scheduler
+
+"Do this later" and "do this every day at 18:30" — and still do it after a restart. Morpho doesn't know what a job *means* (a reminder, a group opening, a buff expiring, a weekly ranking). It stores the job in [`kv`](../kv), wakes up at the right time and hands it to the handler you registered for its `type`.
+
+```js
+const { openKV } = require("morpho-socket/kv")
+const { createScheduler } = require("morpho-socket/scheduler")
+
+const db = openKV("data/bot.sqlite")
+const sched = createScheduler({
+  db,
+  tz: "America/Sao_Paulo",                                  // default zone for daily()
+  onError:  (job, err) => console.error(job.type, err),
+  onMissed: (job, { delayMs }) => console.warn("missed", job.type, delayMs),
+})
+
+sched.on("reminder", async (job, ctx) => {
+  const sock = sockets.get(ctx.scope[0])                    // scope = [clientId, chatId] (see sub below)
+  await sock.sendMessage(job.payload.to, { text: ctx.late ? `(late) ${job.payload.text}` : job.payload.text })
+})
+sched.start()
+
+sched.after(30 * 60_000, "reminder", { to, text })          // once, in 30 minutes
+sched.at(new Date("2026-12-25T09:00:00-03:00"), "reminder", { to, text })
+sched.every(3600e3, "sweep", null)                          // every hour
+sched.daily("18:30", "close-group", { jid }, { days: [1, 2, 3, 4, 5] })   // Mon–Fri, 0 = Sunday
+```
+
+## Scopes
+
+`sub(...)` gives a view over one client or group. Jobs created through it remember their scope, and the handler receives it in `ctx.scope`:
+
+```js
+const room = sched.sub(clientId, chatId)
+room.after(5000, "ping", null, { owner: g.user.number, max: 10 })   // { ok: false, reason: "limit-reached" } past 10 per owner
+room.list({ owner: g.user.number })                                 // "my reminders"
+room.cancel(id)
+room.clear()                                                        // group removed: forget all its jobs
+```
+
+The root sees every scope (handy for a dashboard); a `sub` sees its own and deeper ones. The same `id` can exist in different scopes.
+
+## Guarantees
+
+- **Claim before run.** A job is rescheduled (or deleted) *before* its handler runs, so a crash never runs it twice. One-shots are at-most-once unless you ask for `attempts: 3` (retried after `retryMs`, default 30 s). Two processes on the same database never run the same job twice.
+- **Downtime.** A job later than its `lateMs` (default 10 min) is **not** run; `onMissed` hears about it. Pass `lateMs: Infinity` per job for "run it however late" (a reminder); `ctx.late` and `ctx.delayMs` tell the handler how late it is. Recurring jobs never replay a backlog: after downtime they skip to the next slot on their original rhythm.
+- **A broken handler** goes to `onError`; it never stops the other jobs or the loop. A recurring job simply carries on.
+- **No handler yet?** The job is left untouched, so you can `on()` after `start()`.
+- **Time zones** come from `Intl` (no dependency) and follow daylight saving.
+
+## API
+
+| | |
+|---|---|
+| `createScheduler({ db, name = "scheduler", tickMs = 15 s, lateMs = 10 min, retryMs = 30 s, tz = "UTC", now?, onError?, onMissed?, log? })` | |
+| `on(type, fn)` | `fn(job, { late, delayMs, attempt, scope })`; returns a function that removes it |
+| `start()` · `stop()` · `running` | timer (unref'd); `start()` also runs one tick at once |
+| `tick()` | runs what is due right now; returns how many handlers ran (use it in tests) |
+| `at(when, type, payload?, opts?)` | `Date`, epoch ms or ISO string |
+| `after(ms, type, payload?, opts?)` | |
+| `every(ms, type, payload?, opts?)` | `ms >= 1000`; `opts.startAt` for the first run |
+| `daily("HH:MM", type, payload?, opts?)` | `opts.tz`, `opts.days` |
+| `get(id)` · `cancel(id)` | |
+| `list(filter?)` · `count(filter?)` · `clear(filter?)` | `filter`: `{ type, owner }`; `list` is soonest first |
+| `sub(...parts)` | scoped view |
+
+`opts` for every creator: `id` · `owner` · `max` (per owner, needs `owner`) · `replace` · `allowPast` · `attempts` · `retryMs` · `lateMs`.
+
+Creators return `{ ok: true, job }` or `{ ok: false, reason }` with `"exists"` (+ `job`), `"in-the-past"` or `"limit-reached"`. A repeated `id` is refused unless `replace: true`, which makes ids good de-duplication keys (`"birthday:5511999"`).
+Wrong usage (bad time, type name or time zone, a payload that isn't JSON) throws `TypeError`.
+
+A `job` is `{ id, type, payload, at, every, owner, scope, createdAt, attempts, tries }`.
+
+## Notes
+
+- Parsing human input ("30min", "tomorrow 9am") is **yours**: it depends on the language. Turn it into milliseconds or a `Date` and call `after`/`at`.
+- Each tick reads the scheduler's jobs from SQLite; thousands of jobs are fine. For millions you would want a different design.
+- `payload` is stored as JSON: keep ids and data in it, not sockets or functions. Look the socket up in the handler.
+- Delivery is "about `tickMs` after the due time" (15 s by default). Lower `tickMs` if you need more precision.

package/packages/scheduler/index.js

@@ -0,0 +1,251 @@
+// @morpho/scheduler
+//
+// "Do this later" / "do this every day at 18:30", and still do it after a restart. Morpho doesn't know what a job
+// MEANS (a reminder, a group opening, a buff expiring, a weekly ranking...) — it stores it, wakes up at the right
+// time, and hands it to the handler you registered for its `type`.
+//
+//   const sched = createScheduler({ db, tz: "America/Sao_Paulo" })          // db from @morpho/kv
+//   sched.on("reminder", async (job, ctx) => { await send(job.payload.to, job.payload.text) })
+//   sched.start()
+//
+//   sched.after(30 * 60_000, "reminder", { to, text })                      // once, in 30 minutes
+//   sched.at(new Date("2026-12-25T09:00:00-03:00"), "reminder", { to, text })
+//   sched.every(3600e3, "sweep", {})                                        // every hour
+//   sched.daily("18:30", "close-group", { jid }, { days: [1, 2, 3, 4, 5] }) // Mon–Fri 18:30 in `tz`
+//
+//   const room = sched.sub(clientId, chatId)                                // jobs of one client/group; job.scope tells the handler where it came from
+//   room.after(5000, "ping", null, { owner: g.user.number, max: 10 })       // { ok: false, reason: "limit-reached" } past 10
+//   room.clear()                                                            // group removed: forget its jobs
+//
+// Guarantees
+//   - A job is claimed (rescheduled or deleted) BEFORE its handler runs: a crash never runs it twice.
+//     One-shots are at-most-once unless you ask for `attempts`.
+//   - Downtime: a job later than its `lateMs` (default 10 min) is NOT run; `onMissed` hears about it. Use lateMs: Infinity
+//     for "always run it, however late" (ctx.late tells the handler). Recurring jobs never "catch up": they skip to the next slot.
+//   - Expected outcomes are values: { ok: false, reason: "exists" | "in-the-past" | "limit-reached" }.
+//     Wrong usage (bad time, bad type name, non-JSON payload) throws TypeError.
+//
+// Handler: (job, { late, delayMs, attempt, scope }) — a throw goes to onError (and retries a one-shot if attempts > 1).
+// Jobs whose type has no handler yet are left untouched, so handlers can be registered after start().
+
+const crypto = require("node:crypto")
+
+const TYPE = /^[A-Za-z0-9_.:-]+$/
+const TIME = /^([01]\d|2[0-3]):([0-5]\d)$/
+const DEFAULTS = { tickMs: 15_000, lateMs: 10 * 60_000, retryMs: 30_000, tz: "UTC" }
+
+// ---------- time zones (no dependency: Intl) ----------
+const dtfs = new Map()
+function dtf(tz) {
+  let f = dtfs.get(tz)
+  if (!f) {
+    try { f = new Intl.DateTimeFormat("en-CA", { timeZone: tz, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit", hourCycle: "h23" }) }
+    catch { throw new TypeError(`scheduler: unknown time zone "${tz}"`) }
+    dtfs.set(tz, f)
+  }
+  return f
+}
+const parts = (tz, ms) => Object.fromEntries(dtf(tz).formatToParts(new Date(ms)).map(x => [x.type, x.value]))
+function offsetMs(tz, ms) {                                    // local wall clock minus UTC, at that instant
+  const p = parts(tz, ms)
+  return Date.UTC(+p.year, +p.month - 1, +p.day, +p.hour % 24, +p.minute, +p.second) - Math.floor(ms / 1000) * 1000
+}
+function zoned(tz, y, m, d, h, mi) {                           // wall clock in tz -> epoch ms (m is 0-based)
+  const naive = Date.UTC(y, m, d, h, mi)
+  let t = naive - offsetMs(tz, naive)
+  t = naive - offsetMs(tz, t)                                  // second pass settles DST edges
+  return t
+}
+function nextDaily(spec, after) {
+  const p = parts(spec.tz, after)
+  const [h, mi] = spec.time.split(":").map(Number)
+  for (let off = 0; off <= 14; off++) {
+    const day = new Date(Date.UTC(+p.year, +p.month - 1, +p.day + off))
+    if (spec.days && !spec.days.includes(day.getUTCDay())) continue
+    const cand = zoned(spec.tz, day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate(), h, mi)
+    if (cand > after) return cand
+  }
+  return null
+}
+// first slot of a recurring spec strictly after `t`, staying on the original rhythm
+function nextAfter(spec, t, anchor) {
+  if (spec.kind === "interval") return anchor + (Math.floor((t - anchor) / spec.ms) + 1) * spec.ms
+  return nextDaily(spec, t)
+}
+
+// ---------- helpers ----------
+const typeName = t => { if (typeof t !== "string" || !TYPE.test(t)) throw new TypeError("scheduler: type must match [A-Za-z0-9_.:-]+"); return t }
+const part = x => {
+  if (typeof x === "number" && Number.isFinite(x)) x = String(x)
+  if (typeof x !== "string" || !x || x.includes("/")) throw new TypeError('scheduler: ids and scope parts must be non-empty strings without "/"')
+  return x
+}
+const toMs = when => {
+  const ms = when instanceof Date ? when.getTime() : typeof when === "string" ? Date.parse(when) : when
+  if (typeof ms !== "number" || !Number.isFinite(ms)) throw new TypeError("scheduler.at: pass a Date, an epoch in ms or an ISO string")
+  return ms
+}
+const view = r => ({ id: r.id, type: r.type, payload: r.payload, at: r.at, every: r.every ?? null, owner: r.owner ?? null, scope: [...r.scope], createdAt: r.createdAt, attempts: r.attempts, tries: r.tries })
+
+function createScheduler({
+  db, name = "scheduler", tickMs = DEFAULTS.tickMs, lateMs = DEFAULTS.lateMs, retryMs = DEFAULTS.retryMs, tz = DEFAULTS.tz,
+  now = Date.now, onError = () => {}, onMissed = () => {}, log = () => {},
+} = {}) {
+  if (!db || typeof db.collection !== "function" || typeof db.transaction !== "function")
+    throw new TypeError("scheduler: pass { db } from @morpho/kv (openKV(...))")
+  dtf(tz)                                                       // validates the default zone early
+  const col = db.collection(name)
+  const handlers = new Map()
+  const fullKey = r => [...r.scope, r.id].join("/")
+  let timer = null, ticking = false
+
+  // ----- claim: atomically move a due job to its next slot (or delete it) before running it -----
+  function claim(job, t) {
+    return db.transaction(() => {
+      const fk = fullKey(job)
+      const cur = col.get(fk)
+      if (!cur || cur.at !== job.at) return null               // taken by another process, cancelled or rescheduled meanwhile
+      const delayMs = t - cur.at
+      const missed = delayMs > (cur.lateMs ?? lateMs)
+      if (cur.every) {
+        const next = nextAfter(cur.every, t, cur.anchor ?? cur.at)
+        if (next == null) col.delete(fk); else col.set(fk, { ...cur, at: next })
+      } else col.delete(fk)
+      return { job: cur, missed, delayMs }
+    })
+  }
+
+  async function run(job, delayMs, t) {
+    const attempt = (job.tries || 0) + 1
+    try {
+      await handlers.get(job.type)(view({ ...job, tries: attempt }), { late: delayMs > tickMs, delayMs, attempt, scope: [...job.scope] })
+    } catch (e) {
+      try { onError(view(job), e) } catch { /* a broken onError must not break the loop */ }
+      // retry only one-shots, and only if nobody re-created the same id meanwhile
+      if (!job.every && attempt < (job.attempts || 1) && !col.has(fullKey(job)))
+        col.set(fullKey(job), { ...job, at: now() + (job.retryMs ?? retryMs), tries: attempt })
+    }
+  }
+
+  // runs everything that is due right now. Called by the timer; call it yourself in tests. Returns how many handlers ran.
+  async function tick() {
+    if (ticking) return 0
+    ticking = true
+    try {
+      const t = now()
+      const due = col.entries("")
+        .map(([, j]) => j)
+        .filter(j => j && j.at <= t && handlers.has(j.type))
+        .sort((a, b) => a.at - b.at)
+      const runs = []
+      for (const job of due) {
+        const c = claim(job, t)
+        if (!c) continue
+        if (c.missed) { try { onMissed(view(c.job), { delayMs: c.delayMs }) } catch { /* ignore */ } continue }
+        runs.push(run(c.job, c.delayMs, t))
+      }
+      await Promise.all(runs)
+      return runs.length
+    } finally { ticking = false }
+  }
+
+  // ----- a view over one scope (the root sees every scope; sub(...) sees its own) -----
+  function make(scope) {
+    const prefix = scope.length ? scope.join("/") + "/" : ""
+    const mine = () => col.entries(prefix).map(([, j]) => j).filter(Boolean)
+    const matches = ({ type, owner } = {}) => j => (type === undefined || j.type === type) && (owner === undefined || j.owner === owner)
+
+    function create(at, every, type, payload, o = {}) {
+      typeName(type)
+      const { id = crypto.randomBytes(8).toString("hex"), owner, max, replace = false, allowPast = false, attempts = 1, lateMs: jobLate, retryMs: jobRetry } = o
+      part(id)
+      if (payload !== undefined && JSON.stringify(payload) === undefined) throw new TypeError("scheduler: payload must be JSON-serializable")
+      if (max != null && owner == null) throw new TypeError("scheduler: `max` needs an `owner` (the limit is per owner)")
+      if (!(attempts >= 1)) throw new TypeError("scheduler: attempts must be >= 1")
+      const t = now()
+      if (at <= t && !allowPast) return { ok: false, reason: "in-the-past" }
+      return db.transaction(() => {
+        const fk = prefix + id
+        const existing = col.get(fk)
+        if (existing && !replace) return { ok: false, reason: "exists", job: view(existing) }
+        if (max != null) {
+          const n = mine().filter(j => j.owner === owner && j.scope.join("/") === scope.join("/") && fullKey(j) !== fk).length
+          if (n >= max) return { ok: false, reason: "limit-reached" }
+        }
+        const rec = {
+          id, type, payload: payload === undefined ? null : payload, at, anchor: at, every, owner: owner ?? null, scope: [...scope],
+          createdAt: t, attempts, tries: 0,
+          ...(jobLate !== undefined ? { lateMs: jobLate === Infinity ? 1e18 : jobLate } : {}),
+          ...(jobRetry !== undefined ? { retryMs: jobRetry } : {}),
+        }
+        col.set(fk, rec)
+        return { ok: true, job: view(rec) }
+      })
+    }
+
+    const api = {
+      // opts for all creators: { id, owner, max, replace, allowPast, attempts, retryMs, lateMs }
+      at(when, type, payload, opts) { return create(toMs(when), null, type, payload, opts) },
+      after(ms, type, payload, opts) {
+        if (!Number.isFinite(ms) || ms < 0) throw new TypeError("scheduler.after: ms must be >= 0")
+        return create(now() + ms, null, type, payload, opts)
+      },
+      // opts.startAt: first run (default: now + ms). Keeps its rhythm after downtime and never runs a backlog.
+      every(ms, type, payload, opts = {}) {
+        if (!Number.isFinite(ms) || ms < 1000) throw new TypeError("scheduler.every: ms must be >= 1000")
+        return create(opts.startAt !== undefined ? toMs(opts.startAt) : now() + ms, { kind: "interval", ms }, type, payload, { allowPast: true, ...opts })
+      },
+      // "HH:MM" in opts.tz (default: the scheduler's). opts.days: [0..6], 0 = Sunday (default: every day)
+      daily(time, type, payload, opts = {}) {
+        if (typeof time !== "string" || !TIME.test(time)) throw new TypeError('scheduler.daily: time must be "HH:MM" (24h)')
+        const zone = opts.tz ?? tz
+        dtf(zone)
+        let days = null
+        if (opts.days !== undefined) {
+          if (!Array.isArray(opts.days) || !opts.days.length || opts.days.some(d => !Number.isInteger(d) || d < 0 || d > 6))
+            throw new TypeError("scheduler.daily: days must be a non-empty array of 0..6 (0 = Sunday)")
+          days = [...new Set(opts.days)].sort()
+        }
+        const spec = { kind: "daily", time, tz: zone, days }
+        return create(nextDaily(spec, now()), spec, type, payload, opts)
+      },
+
+      get(id) { const r = col.get(prefix + part(id)); return r ? view(r) : null },
+      cancel(id) { return col.delete(prefix + part(id)) },
+      // jobs of this scope (the root: all of them), soonest first. filter: { type, owner }
+      list(filter) { return mine().filter(matches(filter)).sort((a, b) => a.at - b.at).map(view) },
+      count(filter) { return mine().filter(matches(filter)).length },
+      // forget jobs (a group was removed, a person left). Returns how many.
+      clear(filter) { let n = 0; for (const j of mine().filter(matches(filter))) if (col.delete(fullKey(j))) n++; return n },
+
+      sub(...p) {
+        if (!p.length) throw new TypeError("scheduler.sub: pass at least one part")
+        return make([...scope, ...p.map(part)])
+      },
+    }
+    return api
+  }
+
+  const root = make([])
+  return {
+    ...root,
+    // handler for a job type. Returns a function that removes it.
+    on(type, fn) {
+      typeName(type)
+      if (typeof fn !== "function") throw new TypeError("scheduler.on: pass a function")
+      handlers.set(type, fn)
+      return () => { if (handlers.get(type) === fn) handlers.delete(type) }
+    },
+    tick,
+    start({ immediate = true } = {}) {
+      if (timer) return
+      timer = setInterval(() => { tick().catch(e => log("tick-error", e)) }, tickMs)
+      timer.unref?.()
+      if (immediate) tick().catch(e => log("tick-error", e))
+    },
+    stop() { if (timer) { clearInterval(timer); timer = null } },
+    get running() { return !!timer },
+  }
+}
+
+module.exports = { createScheduler }

package/packages/scheduler/package.json

@@ -0,0 +1 @@
+{ "name": "@morpho/scheduler", "version": "0.1.0", "description": "Jobs that run later or on repeat and survive restarts: one-shot, every N ms, daily/weekly at HH:MM in a timezone. Tolerance for downtime, retries, scopes. Built on @morpho/kv.", "main": "index.js", "engines": { "node": ">=22.5.0" }, "license": "MIT" }