@stonyx/cron 0.2.1-alpha.2 → 0.2.1-alpha.21

package/src/cron-parser.js

@@ -1,246 +0,0 @@
-/**
- * 5-field cron expression parser with next-occurrence computation.
- * No external dependencies — built for stonyx-cron.
- *
- * Fields: minute(0-59) hour(0-23) day-of-month(1-31) month(1-12) day-of-week(0-6)
- * Supports: wildcards(*), ranges(1-5), steps(* /5), lists(1,3,5), names(jan-dec, sun-sat)
- */
-
-const MONTH_NAMES = { jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6, jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12 };
-const DAY_NAMES = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
-
-const FIELD_RANGES = [
-  { min: 0, max: 59 },  // minute
-  { min: 0, max: 23 },  // hour
-  { min: 1, max: 31 },  // day of month
-  { min: 1, max: 12 },  // month
-  { min: 0, max: 6 },   // day of week
-];
-
-/**
- * Parse a single cron field into a sorted array of allowed values.
- * @param {string} field - The field string (e.g., "1-5", "* /15", "mon,wed,fri")
- * @param {number} fieldIndex - Index (0=minute, 1=hour, 2=dom, 3=month, 4=dow)
- * @returns {number[]} Sorted array of allowed integer values
- */
-export function parseField(field, fieldIndex) {
-  const { min, max } = FIELD_RANGES[fieldIndex];
-  const names = fieldIndex === 3 ? MONTH_NAMES : fieldIndex === 4 ? DAY_NAMES : null;
-
-  const resolveToken = (token) => {
-    if (names) {
-      const lower = token.toLowerCase();
-      if (lower in names) return names[lower];
-    }
-    const n = Number(token);
-    if (!Number.isInteger(n)) throw new Error(`Invalid cron value: "${token}" in field ${fieldIndex}`);
-    // Normalize day-of-week 7 → 0 (both mean Sunday)
-    if (fieldIndex === 4 && n === 7) return 0;
-    return n;
-  };
-
-  const results = new Set();
-
-  for (const part of field.split(',')) {
-    const trimmed = part.trim();
-    const [rangeStr, stepStr] = trimmed.split('/');
-    const step = stepStr !== undefined ? Number(stepStr) : 1;
-
-    if (!Number.isInteger(step) || step < 1) {
-      throw new Error(`Invalid step "${stepStr}" in cron field ${fieldIndex}`);
-    }
-
-    let start, end;
-
-    if (rangeStr === '*') {
-      start = min;
-      end = max;
-    } else if (rangeStr.includes('-')) {
-      const [lo, hi] = rangeStr.split('-');
-      start = resolveToken(lo);
-      end = resolveToken(hi);
-    } else {
-      start = resolveToken(rangeStr);
-      end = stepStr !== undefined ? max : start;
-    }
-
-    if (start < min || start > max || end < min || end > max) {
-      throw new Error(`Value out of range [${min}-${max}] in cron field ${fieldIndex}: "${trimmed}"`);
-    }
-
-    for (let v = start; v <= end; v += step) {
-      results.add(v);
-    }
-  }
-
-  return [...results].sort((a, b) => a - b);
-}
-
-/**
- * Parse a 5-field cron expression into field arrays.
- * @param {string} expr - Cron expression (e.g., "0 9 * * 1-5")
- * @returns {{ minutes: number[], hours: number[], daysOfMonth: number[], months: number[], daysOfWeek: number[] }}
- */
-export function parseCronExpression(expr) {
-  const fields = expr.trim().split(/\s+/);
-  if (fields.length !== 5) {
-    throw new Error(`Cron expression must have exactly 5 fields, got ${fields.length}: "${expr}"`);
-  }
-
-  return {
-    minutes: parseField(fields[0], 0),
-    hours: parseField(fields[1], 1),
-    daysOfMonth: parseField(fields[2], 2),
-    months: parseField(fields[3], 3),
-    daysOfWeek: parseField(fields[4], 4),
-  };
-}
-
-/**
- * Get the number of days in a given month/year.
- */
-function daysInMonth(year, month) {
-  return new Date(year, month, 0).getDate();
-}
-
-/**
- * Check if a day-of-month + day-of-week pair matches the parsed expression.
- *
- * Standard cron behavior: if BOTH dom and dow are restricted (not *),
- * then EITHER matching is sufficient (OR logic).
- * If only one is restricted, it acts as the sole filter.
- */
-function dayMatches(parsed, domWild, dowWild, dayOfMonth, dayOfWeek) {
-  const domMatch = parsed.daysOfMonth.includes(dayOfMonth);
-  const dowMatch = parsed.daysOfWeek.includes(dayOfWeek);
-
-  if (domWild && dowWild) return true;
-  if (domWild) return dowMatch;
-  if (dowWild) return domMatch;
-  return domMatch || dowMatch; // Both restricted → OR
-}
-
-/**
- * Compute the next occurrence of a cron expression after a given timestamp.
- *
- * @param {string} expr - 5-field cron expression
- * @param {number} afterMs - Timestamp in milliseconds (exclusive — finds strictly after this)
- * @param {string} [tz] - IANA timezone (defaults to system timezone)
- * @returns {number|undefined} Next occurrence in milliseconds, or undefined if none within 4 years
- */
-export function nextOccurrence(expr, afterMs, tz) {
-  const parsed = parseCronExpression(expr);
-  const exprFields = expr.trim().split(/\s+/);
-  const domWild = exprFields[2] === '*';
-  const dowWild = exprFields[4] === '*';
-
-  // Start from the next whole minute after afterMs
-  const startDate = new Date(afterMs);
-  startDate.setSeconds(0, 0);
-  startDate.setMinutes(startDate.getMinutes() + 1);
-
-  // Convert to target timezone for field matching
-  const formatter = new Intl.DateTimeFormat('en-US', {
-    timeZone: tz || undefined,
-    year: 'numeric', month: 'numeric', day: 'numeric',
-    hour: 'numeric', minute: 'numeric', hour12: false,
-    weekday: 'short',
-  });
-
-  const dayMap = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
-
-  // Parse formatted date parts in the target timezone
-  function getLocalParts(date) {
-    const parts = {};
-    for (const { type, value } of formatter.formatToParts(date)) {
-      parts[type] = value;
-    }
-    return {
-      year: Number(parts.year),
-      month: Number(parts.month),
-      day: Number(parts.day),
-      hour: Number(parts.hour === '24' ? 0 : parts.hour),
-      minute: Number(parts.minute),
-      weekday: dayMap[parts.weekday] ?? 0,
-    };
-  }
-
-  // Search limit: 4 years of minutes (≈ 2.1M iterations max)
-  const maxMs = afterMs + 4 * 365.25 * 24 * 60 * 60 * 1000;
-  let candidate = new Date(startDate);
-
-  while (candidate.getTime() <= maxMs) {
-    const p = getLocalParts(candidate);
-
-    // Check month
-    if (!parsed.months.includes(p.month)) {
-      // Advance to next matching month
-      const nextMonth = parsed.months.find(m => m > p.month);
-      if (nextMonth) {
-        // Stay in same year, advance to first day of nextMonth
-        candidate = advanceToMonth(candidate, p.year, nextMonth, tz, formatter, dayMap);
-      } else {
-        // Wrap to next year, first matching month
-        candidate = advanceToMonth(candidate, p.year + 1, parsed.months[0], tz, formatter, dayMap);
-      }
-      continue;
-    }
-
-    // Check day (dom + dow)
-    if (!dayMatches(parsed, domWild, dowWild, p.day, p.weekday)) {
-      candidate.setMinutes(candidate.getMinutes() + (24 * 60 - p.hour * 60 - p.minute));
-      continue;
-    }
-
-    // Check hour
-    if (!parsed.hours.includes(p.hour)) {
-      const nextHour = parsed.hours.find(h => h > p.hour);
-      if (nextHour) {
-        candidate.setMinutes(candidate.getMinutes() + ((nextHour - p.hour) * 60 - p.minute));
-      } else {
-        // Advance to next day
-        candidate.setMinutes(candidate.getMinutes() + ((24 - p.hour) * 60 - p.minute));
-      }
-      continue;
-    }
-
-    // Check minute
-    if (!parsed.minutes.includes(p.minute)) {
-      const nextMin = parsed.minutes.find(m => m > p.minute);
-      if (nextMin) {
-        candidate.setMinutes(candidate.getMinutes() + (nextMin - p.minute));
-      } else {
-        // Advance to next hour
-        candidate.setMinutes(candidate.getMinutes() + (60 - p.minute));
-      }
-      continue;
-    }
-
-    // All fields match
-    return candidate.getTime();
-  }
-
-  return undefined;
-}
-
-/**
- * Create a Date advanced to the start of a specific month in a specific year,
- * using the target timezone's midnight.
- */
-function advanceToMonth(current, year, month, tz, formatter, dayMap) {
-  // Create a new date at ~start of the target month in UTC, then adjust
-  const d = new Date(current);
-  // Jump to approximately the right time
-  d.setFullYear(year, month - 1, 1);
-  d.setHours(0, 0, 0, 0);
-  return d;
-}
-
-/**
- * Validate a cron expression without computing next occurrence.
- * @param {string} expr - 5-field cron expression
- * @throws {Error} if the expression is invalid
- */
-export function validateCronExpression(expr) {
-  parseCronExpression(expr);
-}

package/src/job.js

@@ -1,200 +0,0 @@
-/**
- * Job data model and state machine for the advanced scheduling system.
- */
-import { computeNextRunAtMs, validateSchedule } from './schedule.js';
-
-/**
- * Error backoff table (milliseconds).
- * Applied after consecutive errors to prevent hammering.
- */
-const ERROR_BACKOFF_MS = [30_000, 60_000, 300_000, 900_000, 3_600_000];
-
-export function errorBackoffMs(consecutiveErrors) {
-  if (consecutiveErrors < 1) return 0;
-  return ERROR_BACKOFF_MS[Math.min(consecutiveErrors - 1, ERROR_BACKOFF_MS.length - 1)];
-}
-
-/**
- * Create a new job object from input.
- *
- * @param {object} input - Job creation input
- * @param {string} input.name - Job name
- * @param {object} input.schedule - Schedule definition (at/every/cron)
- * @param {object} input.payload - What to execute
- * @param {string} [input.description]
- * @param {boolean} [input.enabled=true]
- * @param {boolean} [input.deleteAfterRun=false]
- * @param {string} [input.sessionTarget="isolated"]
- * @param {string} [input.wakeMode="now"]
- * @param {object} [input.delivery]
- * @returns {object} Complete job object with state
- */
-export function createJob(input) {
-  validateSchedule(input.schedule);
-
-  const nowMs = Date.now();
-  const enabled = input.enabled !== false;
-  const deleteAfterRun = input.deleteAfterRun ?? (input.schedule.kind === 'at');
-
-  const job = {
-    id: crypto.randomUUID(),
-    name: input.name,
-    description: input.description || undefined,
-    enabled,
-    deleteAfterRun,
-    createdAtMs: nowMs,
-    updatedAtMs: nowMs,
-    schedule: { ...input.schedule },
-    sessionTarget: input.sessionTarget || 'isolated',
-    wakeMode: input.wakeMode || 'now',
-    payload: { ...input.payload },
-    delivery: input.delivery ? { ...input.delivery } : undefined,
-    state: {
-      nextRunAtMs: undefined,
-      runningAtMs: undefined,
-      lastRunAtMs: undefined,
-      lastStatus: undefined,
-      lastError: undefined,
-      lastDurationMs: undefined,
-      consecutiveErrors: 0,
-      scheduleErrorCount: 0,
-    },
-  };
-
-  // Compute initial next run
-  if (enabled) {
-    try {
-      job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
-    } catch {
-      job.state.scheduleErrorCount = 1;
-    }
-  }
-
-  return job;
-}
-
-/**
- * Apply an update patch to a job.
- *
- * @param {object} job - Existing job
- * @param {object} patch - Fields to update
- * @returns {object} Updated job (same reference, mutated)
- */
-export function updateJob(job, patch) {
-  const nowMs = Date.now();
-
-  if (patch.name !== undefined) job.name = patch.name;
-  if (patch.description !== undefined) job.description = patch.description || undefined;
-  if (patch.deleteAfterRun !== undefined) job.deleteAfterRun = patch.deleteAfterRun;
-  if (patch.sessionTarget !== undefined) job.sessionTarget = patch.sessionTarget;
-  if (patch.wakeMode !== undefined) job.wakeMode = patch.wakeMode;
-  if (patch.payload !== undefined) job.payload = { ...patch.payload };
-  if (patch.delivery !== undefined) job.delivery = patch.delivery ? { ...patch.delivery } : undefined;
-
-  if (patch.schedule !== undefined) {
-    validateSchedule(patch.schedule);
-    job.schedule = { ...patch.schedule };
-    job.state.scheduleErrorCount = 0;
-    // Recompute next run
-    if (job.enabled) {
-      try {
-        job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
-      } catch {
-        job.state.scheduleErrorCount = 1;
-      }
-    }
-  }
-
-  if (patch.enabled !== undefined) {
-    job.enabled = patch.enabled;
-    if (job.enabled && !job.state.nextRunAtMs) {
-      try {
-        job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
-      } catch {
-        job.state.scheduleErrorCount++;
-      }
-    }
-    if (!job.enabled) {
-      job.state.nextRunAtMs = undefined;
-    }
-  }
-
-  job.updatedAtMs = nowMs;
-  return job;
-}
-
-/**
- * Mark a job as started (running).
- */
-export function markRunning(job) {
-  job.state.runningAtMs = Date.now();
-}
-
-/**
- * Apply the result of a job execution.
- *
- * @param {object} job - The job
- * @param {"ok"|"error"|"skipped"} status - Execution result
- * @param {string} [error] - Error message if status is "error"
- * @param {number} [durationMs] - Execution duration
- */
-export function applyResult(job, status, error, durationMs) {
-  const nowMs = Date.now();
-
-  job.state.lastRunAtMs = job.state.runningAtMs || nowMs;
-  job.state.runningAtMs = undefined;
-  job.state.lastStatus = status;
-  job.state.lastError = status === 'error' ? error : undefined;
-  job.state.lastDurationMs = durationMs;
-
-  if (status === 'error') {
-    job.state.consecutiveErrors = (job.state.consecutiveErrors || 0) + 1;
-  } else {
-    job.state.consecutiveErrors = 0;
-  }
-
-  // One-shot jobs: disable after any terminal status
-  if (job.schedule.kind === 'at') {
-    job.enabled = false;
-    job.state.nextRunAtMs = undefined;
-    return;
-  }
-
-  // Recurring jobs: compute next run with backoff
-  if (job.enabled) {
-    try {
-      const normalNext = computeNextRunAtMs(job.schedule, nowMs);
-      if (normalNext === undefined) {
-        job.enabled = false;
-        job.state.nextRunAtMs = undefined;
-        return;
-      }
-
-      if (status === 'error' && job.state.consecutiveErrors > 0) {
-        const backoff = errorBackoffMs(job.state.consecutiveErrors);
-        job.state.nextRunAtMs = Math.max(normalNext, nowMs + backoff);
-      } else {
-        job.state.nextRunAtMs = normalNext;
-      }
-
-      job.state.scheduleErrorCount = 0;
-    } catch {
-      job.state.scheduleErrorCount = (job.state.scheduleErrorCount || 0) + 1;
-      // Auto-disable after 3 consecutive schedule computation errors
-      if (job.state.scheduleErrorCount >= 3) {
-        job.enabled = false;
-        job.state.nextRunAtMs = undefined;
-      }
-    }
-  }
-}
-
-/**
- * Check if a job is due to run.
- */
-export function isDue(job, nowMs) {
-  return job.enabled
-    && !job.state.runningAtMs
-    && job.state.nextRunAtMs !== undefined
-    && job.state.nextRunAtMs <= nowMs;
-}

package/src/locked.js

@@ -1,34 +0,0 @@
-/**
- * Async locking mechanism to serialize state mutations.
- * Prevents concurrent operations from corrupting job state.
- */
-
-let chain = Promise.resolve();
-
-/**
- * Execute a function with exclusive access to cron state.
- * Operations queue behind each other — no concurrent mutations.
- *
- * @param {Function} fn - Async function to execute under lock
- * @returns {Promise<*>} Result of fn
- */
-export async function locked(fn) {
-  let resolve;
-  const prev = chain;
-  chain = new Promise(r => { resolve = r; });
-
-  await prev;
-
-  try {
-    return await fn();
-  } finally {
-    resolve();
-  }
-}
-
-/**
- * Reset the lock chain. Only for testing.
- */
-export function resetLock() {
-  chain = Promise.resolve();
-}

package/src/main.js

@@ -1,112 +0,0 @@
-/*
- * Copyright 2025 Stone Costa
- *
- * Licensed under the Apache License, Version 2.0 (the 'License');
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import config from 'stonyx/config';
-import log from 'stonyx/log';
-import { getTimestamp } from "@stonyx/utils/date";
-import MinHeap from '@stonyx/cron/min-heap';
-
-export default class Cron {
-  jobs = {};
-  heap = new MinHeap();
-  timer = null;
-
-  constructor() {
-    if (Cron.instance) return Cron.instance;
-    Cron.instance = this;
-  }
-
-  scheduleNextRun() {
-    clearTimeout(this.timer);
-
-    const { heap } = this;
-
-    if (heap.isEmpty()) return;
-
-    const nextJob = heap.peek();
-    const delay = Math.max(0, nextJob.nextTrigger - getTimestamp()) * 1000;
-
-    this.timer = setTimeout(() => this.runDueJobs(), delay);
-  }
-
-  async runDueJobs() {
-    const now = getTimestamp();
-    const { heap } = this;
-
-    while (!heap.isEmpty() && heap.peek().nextTrigger <= now) {
-      const job = heap.pop();
-
-      if (config.debug) this.log('job has been triggered', job.key);
-
-      try {
-        await job.callback();
-      } catch (err) {
-        log.error(`Cron job "${job.key}" failed:`, err);
-      }
-
-      this.setNextTrigger(job);
-      heap.push(job);
-    }
-
-    this.scheduleNextRun();
-  }
-
-  register(key, callback, interval, runOnInit=false) {
-    const job = { callback, interval, key };
-    this.jobs[key] = job;
-    this.setNextTrigger(job);
-    this.heap.push(job);
-
-    if (config.debug) {
-      this.log(`job has been registered with interval: ${interval}`, key);
-    }
-
-    if (runOnInit) {
-      try {
-        callback();
-      } catch (err) {
-        log.error(`Cron job "${key}" failed on init:`, err);
-      }
-    }
-
-    this.scheduleNextRun();
-  }
-
-  unregister(key) {
-    const { heap, jobs } = this;
-    const job = jobs[key];
-    
-    if (!job) return;
-
-    delete jobs[key];
-    heap.remove(job);
-
-    if (config.debug) this.log('job has been unregistered', key);
-
-    this.scheduleNextRun();
-  }
-
-  setNextTrigger(job) {
-    job.nextTrigger = getTimestamp() + parseInt(job.interval, 10);
-  }
-
-  log(text, key = null) {
-    if (!config.cron?.log) return;
-    
-    const tag = key ? `Cron::${key}` : `Cron`;
-    log.cron(`${tag} - ${text}:`);
-  }
-}

package/src/min-heap.js

@@ -1,73 +0,0 @@
-export default class MinHeap {
-  constructor() {
-    this.items = [];
-  }
-
-  push(job) {
-    this.items.push(job);
-    this.bubbleUp();
-  }
-
-  pop() {
-    if (this.items.length === 1) return this.items.pop();
-    const top = this.items[0];
-    this.items[0] = this.items.pop();
-    this.bubbleDown();
-    return top;
-  }
-
-  peek() {
-    return this.items[0];
-  }
-
-  bubbleUp() {
-    let idx = this.items.length - 1;
-    while (idx > 0) {
-      const parentIdx = Math.floor((idx - 1) / 2);
-      if (this.items[idx].nextTrigger >= this.items[parentIdx].nextTrigger) break;
-      [this.items[idx], this.items[parentIdx]] = [this.items[parentIdx], this.items[idx]];
-      idx = parentIdx;
-    }
-  }
-
-  bubbleDown() {
-    let idx = 0;
-    const length = this.items.length;
-
-    while (true) {
-      let leftIdx = 2 * idx + 1;
-      let rightIdx = 2 * idx + 2;
-      let swapIdx = null;
-
-      if (leftIdx < length && this.items[leftIdx].nextTrigger < this.items[idx].nextTrigger) {
-        swapIdx = leftIdx;
-      }
-      if (
-        rightIdx < length &&
-        this.items[rightIdx].nextTrigger < (
-          swapIdx === null ? this.items[idx].nextTrigger : this.items[leftIdx].nextTrigger
-        )
-      ) {
-        swapIdx = rightIdx;
-      }
-      if (swapIdx === null) break;
-      [this.items[idx], this.items[swapIdx]] = [this.items[swapIdx], this.items[idx]];
-      idx = swapIdx;
-    }
-  }
-
-  remove(job) {
-    const idx = this.items.indexOf(job);
-    if (idx === -1) return;
-    const end = this.items.pop();
-    if (idx < this.items.length) {
-      this.items[idx] = end;
-      this.bubbleUp();
-      this.bubbleDown();
-    }
-  }
-
-  isEmpty() {
-    return this.items.length === 0;
-  }
-}