@stonyx/cron 0.2.1-alpha.4 → 0.2.1-alpha.6

package/src/schedule.js

@@ -1,81 +0,0 @@
-/**
- * Schedule types and next-run computation.
- *
- * Three schedule kinds:
- *   - "at": One-shot at an absolute ISO-8601 timestamp
- *   - "every": Recurring interval in milliseconds
- *   - "cron": 5-field cron expression with optional timezone
- */
-import { nextOccurrence, validateCronExpression } from './cron-parser.js';
-
-/**
- * Compute the next run time for a schedule.
- *
- * @param {object} schedule - Schedule definition
- * @param {string} schedule.kind - "at" | "every" | "cron"
- * @param {number} nowMs - Current time in milliseconds
- * @returns {number|undefined} Next run time in ms, or undefined if no future occurrence
- */
-export function computeNextRunAtMs(schedule, nowMs) {
-  if (schedule.kind === 'at') {
-    const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
-    if (!Number.isFinite(atMs)) return undefined;
-    return atMs > nowMs ? atMs : undefined;
-  }
-
-  if (schedule.kind === 'every') {
-    const everyMs = Math.max(1, Math.floor(schedule.everyMs));
-    const anchor = Math.max(0, Math.floor(schedule.anchorMs ?? nowMs));
-
-    if (nowMs < anchor) return anchor;
-
-    const elapsed = nowMs - anchor;
-    const steps = Math.max(1, Math.floor((elapsed + everyMs - 1) / everyMs));
-    return anchor + steps * everyMs;
-  }
-
-  if (schedule.kind === 'cron') {
-    const tz = schedule.tz?.trim() || undefined;
-    // Round nowMs down to the current second to avoid sub-second drift
-    const nowSecondMs = Math.floor(nowMs / 1000) * 1000;
-    return nextOccurrence(schedule.expr.trim(), nowSecondMs, tz);
-  }
-
-  throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
-}
-
-/**
- * Validate a schedule definition.
- * @param {object} schedule
- * @throws {Error} if the schedule is invalid
- */
-export function validateSchedule(schedule) {
-  if (!schedule || typeof schedule !== 'object') {
-    throw new Error('Schedule must be an object');
-  }
-
-  if (schedule.kind === 'at') {
-    const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
-    if (!Number.isFinite(atMs)) {
-      throw new Error(`Invalid "at" timestamp: "${schedule.at}"`);
-    }
-    return;
-  }
-
-  if (schedule.kind === 'every') {
-    if (typeof schedule.everyMs !== 'number' || schedule.everyMs < 1) {
-      throw new Error(`"every" schedule requires everyMs >= 1, got: ${schedule.everyMs}`);
-    }
-    return;
-  }
-
-  if (schedule.kind === 'cron') {
-    if (typeof schedule.expr !== 'string' || !schedule.expr.trim()) {
-      throw new Error('"cron" schedule requires a non-empty expr string');
-    }
-    validateCronExpression(schedule.expr.trim());
-    return;
-  }
-
-  throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
-}

package/src/service.js

@@ -1,303 +0,0 @@
-/**
- * CronService — the main API for advanced job scheduling.
- *
- * Manages jobs in memory with a min-heap for efficient next-job lookup.
- * Supports pluggable store interface (memory-only by default, ORM in PR 2).
- * All state mutations are serialized via async locking.
- */
-import config from 'stonyx/config';
-import log from 'stonyx/log';
-import MinHeap from './min-heap.js';
-import { createJob, updateJob, markRunning, applyResult, isDue } from './job.js';
-import { computeNextRunAtMs } from './schedule.js';
-import { locked } from './locked.js';
-import { normalizeJobInput, recoverFlatParams } from './normalize.js';
-import RunLog from './run-log.js';
-
-const MAX_TIMER_DELAY_MS = 60_000;
-
-export default class CronService {
-  constructor() {
-    this.jobs = new Map();       // id → job
-    this.heap = new MinHeap();   // ordered by nextRunAtMs
-    this.timer = null;
-    this.running = false;
-    this.runLog = new RunLog();
-    this.started = false;
-
-    // Pluggable callbacks for consumers
-    this.onJobDue = null;        // async (job) => { status, error?, summary? }
-  }
-
-  // ── Lifecycle ──────────────────────────────────────────────
-
-  /**
-   * Start the service. Loads jobs from store (if any), arms timer.
-   */
-  async start(initialJobs) {
-    if (this.started) return;
-    this.started = true;
-
-    if (initialJobs) {
-      for (const job of initialJobs) {
-        this.jobs.set(job.id, job);
-        if (job.enabled && job.state.nextRunAtMs) {
-          this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
-        }
-      }
-    }
-
-    this.armTimer();
-  }
-
-  /**
-   * Stop the service. Clears timer.
-   */
-  stop() {
-    this.started = false;
-    clearTimeout(this.timer);
-    this.timer = null;
-  }
-
-  // ── CRUD ───────────────────────────────────────────────────
-
-  /**
-   * Get service status.
-   */
-  status() {
-    const peek = this.heap.peek();
-    return {
-      started: this.started,
-      jobCount: this.jobs.size,
-      nextWakeAtMs: peek ? peek.nextTrigger : undefined,
-    };
-  }
-
-  /**
-   * List jobs, optionally including disabled ones.
-   */
-  list(opts) {
-    const includeDisabled = opts?.includeDisabled ?? false;
-    const jobs = [...this.jobs.values()];
-    const filtered = includeDisabled ? jobs : jobs.filter(j => j.enabled);
-    return filtered.sort((a, b) => (a.state.nextRunAtMs ?? Infinity) - (b.state.nextRunAtMs ?? Infinity));
-  }
-
-  /**
-   * Get a single job by ID.
-   */
-  get(id) {
-    return this.jobs.get(id) || null;
-  }
-
-  /**
-   * Add a new job. Input is normalized for AI compatibility.
-   */
-  async add(rawInput) {
-    return locked(() => {
-      const input = normalizeJobInput(recoverFlatParams(rawInput));
-      const job = createJob(input);
-      this.jobs.set(job.id, job);
-
-      if (job.enabled && job.state.nextRunAtMs) {
-        this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
-        this.armTimer();
-      }
-
-      return job;
-    });
-  }
-
-  /**
-   * Update an existing job.
-   */
-  async update(id, patch) {
-    return locked(() => {
-      const job = this.jobs.get(id);
-      if (!job) throw new Error(`Job not found: ${id}`);
-
-      const oldNextRun = job.state.nextRunAtMs;
-      updateJob(job, patch);
-
-      // Update heap entry
-      this.removeFromHeap(id);
-      if (job.enabled && job.state.nextRunAtMs) {
-        this.heap.push({ key: id, nextTrigger: job.state.nextRunAtMs });
-      }
-
-      if (job.state.nextRunAtMs !== oldNextRun) {
-        this.armTimer();
-      }
-
-      return job;
-    });
-  }
-
-  /**
-   * Remove a job.
-   */
-  async remove(id) {
-    return locked(() => {
-      const job = this.jobs.get(id);
-      if (!job) throw new Error(`Job not found: ${id}`);
-
-      this.jobs.delete(id);
-      this.removeFromHeap(id);
-      this.runLog.removeJob(id);
-      this.armTimer();
-    });
-  }
-
-  /**
-   * Manually trigger a job.
-   *
-   * @param {string} id - Job ID
-   * @param {"due"|"force"} [mode="force"] - "due" only runs if the job is due, "force" runs regardless
-   */
-  async run(id, mode = 'force') {
-    const job = this.jobs.get(id);
-    if (!job) throw new Error(`Job not found: ${id}`);
-
-    if (mode === 'due' && !isDue(job, Date.now())) {
-      return { status: 'skipped', reason: 'not due' };
-    }
-
-    return this.executeJob(job);
-  }
-
-  /**
-   * Get run history for a job.
-   */
-  runs(id, limit) {
-    return this.runLog.get(id, limit);
-  }
-
-  // ── Timer Engine ──────────────────────────────────────��────
-
-  armTimer() {
-    clearTimeout(this.timer);
-    if (!this.started) return;
-
-    const peek = this.heap.peek();
-    if (!peek) return;
-
-    const delay = Math.min(Math.max(peek.nextTrigger - Date.now(), 0), MAX_TIMER_DELAY_MS);
-    this.timer = setTimeout(() => this.onTimer(), delay);
-  }
-
-  async onTimer() {
-    if (this.running) {
-      // Already processing — re-arm at max delay to prevent scheduler death
-      this.timer = setTimeout(() => this.onTimer(), MAX_TIMER_DELAY_MS);
-      return;
-    }
-
-    this.running = true;
-
-    try {
-      await locked(async () => {
-        const nowMs = Date.now();
-        const dueJobs = this.findDueJobs(nowMs);
-
-        for (const job of dueJobs) {
-          markRunning(job);
-        }
-
-        for (const job of dueJobs) {
-          await this.executeJob(job);
-        }
-      });
-    } finally {
-      this.running = false;
-      this.armTimer();
-    }
-  }
-
-  findDueJobs(nowMs) {
-    const due = [];
-
-    while (!this.heap.isEmpty()) {
-      const peek = this.heap.peek();
-      if (peek.nextTrigger > nowMs) break;
-
-      this.heap.pop();
-      const job = this.jobs.get(peek.key);
-      if (job && isDue(job, nowMs)) {
-        due.push(job);
-      }
-    }
-
-    return due;
-  }
-
-  async executeJob(job) {
-    const startMs = Date.now();
-    let status = 'ok';
-    let error;
-    let summary;
-
-    try {
-      if (this.onJobDue) {
-        const result = await this.onJobDue(job);
-        if (result) {
-          status = result.status || 'ok';
-          error = result.error;
-          summary = result.summary;
-        }
-      }
-    } catch (err) {
-      status = 'error';
-      error = err?.message || String(err);
-      this.log(`Job "${job.name}" (${job.id}) failed: ${error}`);
-    }
-
-    const durationMs = Date.now() - startMs;
-
-    applyResult(job, status, error, durationMs);
-
-    // Log the run
-    this.runLog.record({
-      jobId: job.id,
-      status,
-      error,
-      summary,
-      runAtMs: startMs,
-      durationMs,
-      nextRunAtMs: job.state.nextRunAtMs,
-    });
-
-    // Handle one-shot auto-delete
-    if (job.deleteAfterRun && status === 'ok' && !job.enabled) {
-      this.jobs.delete(job.id);
-      this.runLog.removeJob(job.id);
-      return { status, summary, deleted: true };
-    }
-
-    // Re-insert into heap if still active
-    if (job.enabled && job.state.nextRunAtMs) {
-      this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
-    }
-
-    return { status, error, summary, durationMs };
-  }
-
-  // ── Helpers ────────────────────────────────────────────────
-
-  removeFromHeap(id) {
-    // MinHeap doesn't support remove-by-key efficiently,
-    // so we rebuild. Fine for typical job counts (< 1000).
-    const remaining = [];
-    while (!this.heap.isEmpty()) {
-      const item = this.heap.pop();
-      if (item.key !== id) remaining.push(item);
-    }
-    for (const item of remaining) {
-      this.heap.push(item);
-    }
-  }
-
-  log(message) {
-    if (!config.cron?.log) return;
-    log.cron(`Cron — ${message}`);
-  }
-}