@vox-ai-app/scheduler 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,71 @@
+# @vox-ai-app/scheduler
+
+Cron-based job scheduler for Vox — schedule recurring agent runs, heartbeats, and timed tasks with timezone support.
+
+## Install
+
+```sh
+npm install @vox-ai-app/scheduler
+```
+
+## Exports
+
+| Export                       | Contents                              |
+| ---------------------------- | ------------------------------------- |
+| `@vox-ai-app/scheduler`      | All scheduler exports                 |
+| `@vox-ai-app/scheduler/cron` | Job scheduling, cancellation, listing |
+
+## Usage
+
+```js
+import { scheduleJob, cancelJob, listJobs, computeNextRun } from '@vox-ai-app/scheduler'
+
+const job = scheduleJob(
+  'daily-check',
+  { expr: '0 9 * * *', tz: 'America/New_York' },
+  (id, meta) => {
+    console.log(`Job ${id} fired at ${meta.firedAt}`)
+  }
+)
+
+console.log(listJobs())
+cancelJob('daily-check')
+```
+
+Schedule persistence is handled by the app layer via `@vox-ai-app/storage/schedules`.
+
+## API
+
+### Cron
+
+| Function         | Description                                     |
+| ---------------- | ----------------------------------------------- |
+| `scheduleJob`    | Schedule a cron job with handler callback       |
+| `cancelJob`      | Cancel a job by ID                              |
+| `cancelAllJobs`  | Cancel all running jobs                         |
+| `getJob`         | Get job details by ID                           |
+| `listJobs`       | List all active jobs with next run times        |
+| `computeNextRun` | Compute the next run time for a cron expression |
+
+`scheduleJob` options:
+
+```js
+scheduleJob(
+  id,
+  {
+    expr: '0 9 * * 1-5',
+    tz: 'America/New_York',
+    runImmediately: false,
+    onError: (err) => {}
+  },
+  handler
+)
+```
+
+## Dependencies
+
+- [croner](https://github.com/hexagon/croner) ^9.0.0
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vox-ai-app/scheduler",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "license": "MIT",
   "description": "Cron-based job scheduler for Vox — schedule recurring agent runs, heartbeats, and timed tasks",
@@ -8,8 +8,7 @@
   "private": false,
   "exports": {
     ".": "./src/index.js",
-    "./cron": "./src/cron.js",
-    "./store": "./src/store.js"
+    "./cron": "./src/cron.js"
   },
   "publishConfig": {
     "access": "public",

package/src/cron.js

@@ -1,26 +1,64 @@
 import { Cron } from 'croner'
 
 const jobs = new Map()
+const CRON_EVAL_CACHE_MAX = 512
+const cronEvalCache = new Map()
+const MIN_REFIRE_GAP_MS = 2000
 
 function resolveTimezone(tz) {
   if (tz && typeof tz === 'string' && tz.trim()) return tz.trim()
-  try { return Intl.DateTimeFormat().resolvedOptions().timeZone } catch { return 'UTC' }
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone
+  } catch {
+    return 'UTC'
+  }
+}
+
+function getCachedCron(expr, timezone) {
+  const key = `${timezone}\0${expr}`
+  const cached = cronEvalCache.get(key)
+  if (cached) return cached
+  if (cronEvalCache.size >= CRON_EVAL_CACHE_MAX) {
+    const oldest = cronEvalCache.keys().next().value
+    cronEvalCache.delete(oldest)
+  }
+  const cron = new Cron(expr, { timezone, catch: false })
+  cronEvalCache.set(key, cron)
+  return cron
 }
 
 export function scheduleJob(id, config, handler) {
   if (jobs.has(id)) cancelJob(id)
 
-  const { expr, tz, runImmediately } = config
+  const { expr, tz, runImmediately, timeoutMs } = config
   const timezone = resolveTimezone(tz)
+  let lastFireMs = 0
 
-  const cron = new Cron(expr, {
-    timezone,
-    catch: (err) => {
-      if (config.onError) config.onError(err)
+  const cron = new Cron(
+    expr,
+    {
+      timezone,
+      catch: (err) => {
+        if (config.onError) config.onError(err)
+      }
+    },
+    () => {
+      const now = Date.now()
+      if (now - lastFireMs < MIN_REFIRE_GAP_MS) return
+      lastFireMs = now
+
+      const context = { scheduledAt: now, expr, timezone }
+      if (typeof timeoutMs === 'number' && timeoutMs > 0) {
+        const ac = new AbortController()
+        const timer = setTimeout(() => ac.abort(), timeoutMs)
+        Promise.resolve(handler(id, { ...context, signal: ac.signal })).finally(() =>
+          clearTimeout(timer)
+        )
+      } else {
+        handler(id, context)
+      }
     }
-  }, () => {
-    handler(id, { scheduledAt: Date.now(), expr, timezone })
-  })
+  )
 
   const job = {
     id,
@@ -28,7 +66,10 @@ export function scheduleJob(id, config, handler) {
     expr,
     timezone,
     createdAt: Date.now(),
-    handler
+    handler,
+    timeoutMs: timeoutMs || null,
+    lastFireMs: 0,
+    state: { runCount: 0, lastError: null, lastRunAtMs: null }
   }
 
   jobs.set(id, job)
@@ -49,7 +90,7 @@ export function cancelJob(id) {
 }
 
 export function cancelAllJobs() {
-  for (const [id, job] of jobs) {
+  for (const [, job] of jobs) {
     job.cron.stop()
   }
   jobs.clear()
@@ -64,24 +105,95 @@ export function getJob(id) {
     timezone: job.timezone,
     createdAt: job.createdAt,
     nextRun: job.cron.nextRun()?.getTime() || null,
-    running: job.cron.isBusy()
+    running: job.cron.isBusy(),
+    state: { ...job.state }
   }
 }
 
 export function listJobs() {
-  return Array.from(jobs.values()).map(job => ({
+  return Array.from(jobs.values()).map((job) => ({
     id: job.id,
     expr: job.expr,
     timezone: job.timezone,
     createdAt: job.createdAt,
     nextRun: job.cron.nextRun()?.getTime() || null,
-    running: job.cron.isBusy()
+    running: job.cron.isBusy(),
+    state: { ...job.state }
   }))
 }
 
 export function computeNextRun(expr, tz) {
   const timezone = resolveTimezone(tz)
-  const cron = new Cron(expr, { timezone })
+  const cron = getCachedCron(expr, timezone)
   const next = cron.nextRun()
   return next ? next.getTime() : null
 }
+
+export function parseAbsoluteTimeMs(input) {
+  const raw = typeof input === 'string' ? input.trim() : ''
+  if (!raw) return null
+  if (/^\d+$/.test(raw)) {
+    const n = Number(raw)
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null
+  }
+  const parsed = Date.parse(raw)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+export function scheduleAt(id, config, handler) {
+  if (jobs.has(id)) cancelJob(id)
+
+  const atMs = typeof config.at === 'number' ? config.at : parseAbsoluteTimeMs(config.at)
+  if (!atMs || atMs <= Date.now()) return null
+
+  const delay = atMs - Date.now()
+  const timer = setTimeout(() => {
+    handler(id, { scheduledAt: atMs, once: true })
+    jobs.delete(id)
+  }, delay)
+
+  const job = {
+    id,
+    timer,
+    atMs,
+    createdAt: Date.now(),
+    handler,
+    kind: 'at'
+  }
+  jobs.set(id, job)
+  return job
+}
+
+export function scheduleEvery(id, config, handler) {
+  if (jobs.has(id)) cancelJob(id)
+
+  const { intervalMs, timeoutMs } = config
+  if (!intervalMs || intervalMs < 1000) return null
+
+  const interval = setInterval(() => {
+    const context = { scheduledAt: Date.now(), intervalMs }
+    if (typeof timeoutMs === 'number' && timeoutMs > 0) {
+      const ac = new AbortController()
+      const t = setTimeout(() => ac.abort(), timeoutMs)
+      Promise.resolve(handler(id, { ...context, signal: ac.signal })).finally(() => clearTimeout(t))
+    } else {
+      handler(id, context)
+    }
+  }, intervalMs)
+
+  const job = {
+    id,
+    interval,
+    intervalMs,
+    createdAt: Date.now(),
+    handler,
+    kind: 'every'
+  }
+  jobs.set(id, job)
+
+  if (config.runImmediately) {
+    handler(id, { scheduledAt: Date.now(), intervalMs, immediate: true })
+  }
+
+  return job
+}

package/src/index.js

@@ -4,7 +4,8 @@ export {
   cancelAllJobs,
   getJob,
   listJobs,
-  computeNextRun
+  computeNextRun,
+  parseAbsoluteTimeMs,
+  scheduleAt,
+  scheduleEvery
 } from './cron.js'
-
-export { createStore } from './store.js'

package/src/store.js

@@ -1,52 +0,0 @@
-import fs from 'node:fs'
-import path from 'node:path'
-
-const SCHEDULES_FILE = 'schedules.json'
-
-export function createStore(dataDir) {
-  const filePath = path.join(dataDir, SCHEDULES_FILE)
-
-  function readAll() {
-    try {
-      const raw = fs.readFileSync(filePath, 'utf8')
-      return JSON.parse(raw)
-    } catch {
-      return []
-    }
-  }
-
-  function writeAll(schedules) {
-    fs.mkdirSync(dataDir, { recursive: true })
-    fs.writeFileSync(filePath, JSON.stringify(schedules, null, 2), 'utf8')
-  }
-
-  function save(schedule) {
-    const all = readAll()
-    const idx = all.findIndex(s => s.id === schedule.id)
-    if (idx >= 0) {
-      all[idx] = { ...all[idx], ...schedule, updatedAt: Date.now() }
-    } else {
-      all.push({ ...schedule, createdAt: Date.now() })
-    }
-    writeAll(all)
-    return schedule
-  }
-
-  function remove(id) {
-    const all = readAll()
-    const filtered = all.filter(s => s.id !== id)
-    if (filtered.length === all.length) return false
-    writeAll(filtered)
-    return true
-  }
-
-  function get(id) {
-    return readAll().find(s => s.id === id) || null
-  }
-
-  function list() {
-    return readAll()
-  }
-
-  return { save, remove, get, list }
-}