@stonyx/cron 0.2.0 → 0.2.1-alpha.1

package/.claude/testing.md

@@ -0,0 +1,85 @@
+# Testing Guidelines
+
+## Testing Guidelines
+
+### Test Structure
+Tests are located in `stonyx-cron/test/unit/` and use QUnit modules:
+
+```javascript
+import QUnit from 'qunit';
+import sinon from 'sinon';
+import { setupIntegrationTests } from "stonyx/test-helpers";
+
+const { module, test } = QUnit;
+
+module('[Unit] Cron', function (hooks) {
+  setupIntegrationTests(hooks);
+
+  let cron, clock;
+
+  hooks.beforeEach(function () {
+    clock = sinon.useFakeTimers({ shouldAdvanceTime: false });
+    cron = new Cron();
+  });
+
+  hooks.afterEach(function () {
+    sinon.restore();
+  });
+
+  test('test description', async function (assert) {
+    // Test implementation
+  });
+});
+```
+
+### Fake Timers Pattern (CRITICAL)
+**Always use fake timers for time-based tests:**
+
+```javascript
+// Setup in beforeEach
+clock = sinon.useFakeTimers({ shouldAdvanceTime: false });
+
+// Advance time synchronously
+clock.tick(5000);  // Advance 5 seconds
+
+// For async operations, use tickAsync
+clock.tick(5000);
+await clock.tickAsync(0);  // Process async callbacks
+
+// Cleanup in afterEach
+sinon.restore();
+```
+
+**Why `shouldAdvanceTime: false`?**
+Prevents real time from interfering with fake time, ensuring deterministic tests.
+
+### Spies & Stubs Patterns
+```javascript
+// Spy on function calls
+const cb = sinon.spy();
+cron.register('job1', cb, 5);
+assert.ok(cb.calledOnce, 'Callback executed once');
+
+// Stub methods
+const stub = sinon.stub().rejects(new Error('boom'));
+cron.register('jobErr', stub, 1);
+
+// Spy on existing methods
+const logSpy = sinon.spy(log, 'cron');
+cron.log('test message');
+assert.ok(logSpy.calledOnce, 'Log called');
+```
+
+### Test Coverage Expectations
+Tests should cover:
+- Job registration and execution
+- Rescheduling behavior
+- Unregistration
+- Error handling
+- Configuration-driven logging
+- Edge cases (empty heap, multiple jobs, etc.)
+
+### Running Tests
+```bash
+pnpm test  # Runs: stonyx test
+```

package/.github/workflows/ci.yml

@@ -2,35 +2,15 @@ name: CI
 
 on:
   pull_request:
-    branches:
-      - dev
-      - main
+    branches: [dev, main]
 
 concurrency:
   group: ci-${{ github.head_ref || github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   test:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 22.18.0
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Run tests
-        run: pnpm test
+    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to NPM
+
+on:
+  repository_dispatch:
+    types: [cascade-publish]
+  workflow_dispatch:
+    inputs:
+      version-type:
+        description: 'Version type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      custom-version:
+        description: 'Custom version (optional, overrides version-type)'
+        required: false
+        type: string
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.event_name == 'repository_dispatch' && 'cascade-update' || format('publish-{0}', github.ref) }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  id-token: write
+  pull-requests: write
+
+jobs:
+  publish:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    uses: abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main
+    with:
+      version-type: ${{ github.event.inputs.version-type }}
+      custom-version: ${{ github.event.inputs.custom-version }}
+      cascade-source: ${{ github.event.client_payload.source_package || '' }}
+    secrets: inherit
+
+  cascade:
+    needs: publish
+    uses: abofs/stonyx-workflows/.github/workflows/cascade.yml@main
+    with:
+      package-name: ${{ needs.publish.outputs.package-name }}
+      published-version: ${{ needs.publish.outputs.published-version }}
+    secrets: inherit

package/.gitignore

@@ -11,3 +11,6 @@ config/environment.js
 .vscode/*
 *.vsix%
 *DS_Store*
+
+# npm auth (never commit tokens)
+.npmrc

package/.npmignore

@@ -2,4 +2,6 @@
 test/
 
 # config
-.nvmrc
+.nvmrc
+# git
+.git

package/README.md

@@ -20,19 +20,18 @@ cron.register('exampleJob', async () => {
 
 ## How it works
 
-`stonyx-cron` uses a min-heap internally to efficiently track the next job to run. Each job has a scheduled trigger time, and the heap ensures the job with the earliest trigger is always at the top.  
+`stonyx-cron` uses a min-heap internally to efficiently track the next job to run. Each job has a scheduled trigger time, and the heap ensures the job with the earliest trigger is always at the top.
 
 When a job is executed, its next trigger time is updated, and it is re-inserted into the heap. This allows `Cron` to always know which job should run next without scanning all jobs, keeping scheduling efficient even with many jobs.
 
-
-### Public Methods
+## Public Methods
 
 |    Method    |                                Parameters                                | Description                                                                                                              |
 | :----------: | :----------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------- |
 |  `register`  | `key: string, callback: Function, interval: number, runOnInit?: boolean` | Register a new job with a given interval in seconds. If `runOnInit` is true, the job runs immediately upon registration. |
 | `unregister` |                               `key: string`                              | Remove a previously registered job.                                                                                      |
 
-> All other methods and classes (like `MinHeap`) are used internally by `Cron` and are not intended for direct use.
+> `MinHeap` is also exported as a public subpath (`@stonyx/cron/min-heap`) and can be imported directly for advanced usage.
 
 ## Configuration
 

package/logs/error.log

@@ -1 +1,2 @@
-[12/31/1969, 7:00:01 PM] Cron job "jobErr" failed:
+[1/1/1970, 12:00:01 AM] Cron job "jobErr" failed:
+[1/1/1970, 12:00:01 AM] Cron job "jobErr" failed:

package/package.json

@@ -3,8 +3,8 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.0",
-  "description": "",
+  "version": "0.2.1-alpha.1",
+  "description": "Cron/job scheduler for Stonyx framework",
   "main": "src/main.js",
   "type": "module",
   "files": [
@@ -12,8 +12,19 @@
   ],
   "exports": {
     ".": "./src/main.js",
+    "./service": "./src/service.js",
+    "./cron-parser": "./src/cron-parser.js",
+    "./schedule": "./src/schedule.js",
+    "./job": "./src/job.js",
+    "./normalize": "./src/normalize.js",
+    "./locked": "./src/locked.js",
+    "./run-log": "./src/run-log.js",
     "./min-heap": "./src/min-heap.js"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/abofs/stonyx-cron.git"
@@ -28,14 +39,14 @@
   },
   "homepage": "https://github.com/abofs/stonyx-cron#readme",
   "devDependencies": {
-    "@stonyx/utils": "^0.2.2",
+    "@stonyx/utils": "0.2.3-beta.7",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },
   "dependencies": {
-    "stonyx": "^0.2.2"
+    "stonyx": "0.2.3-beta.11"
   },
   "scripts": {
-    "test": "qunit --require ./stonyx-bootstrap.cjs"
+    "test": "stonyx test"
   }
 }

package/pnpm-lock.yaml

@@ -9,12 +9,12 @@ importers:
   .:
     dependencies:
       stonyx:
-        specifier: ^0.2.2
-        version: 0.2.2
+        specifier: 0.2.3-beta.11
+        version: 0.2.3-beta.11
     devDependencies:
       '@stonyx/utils':
-        specifier: ^0.2.2
-        version: 0.2.2
+        specifier: 0.2.3-beta.7
+        version: 0.2.3-beta.7
       qunit:
         specifier: ^2.24.1
         version: 2.25.0
@@ -33,8 +33,8 @@ packages:
   '@sinonjs/samsam@8.0.3':
     resolution: {integrity: sha512-hw6HbX+GyVZzmaYNh82Ecj1vdGZrqVIn/keDTg63IgAwiQPO+xCz99uG6Woqgb4tM0mUiFENKZ4cqd7IX94AXQ==}
 
-  '@stonyx/utils@0.2.2':
-    resolution: {integrity: sha512-z/pDbX3QPeVJ3kFpU1rQURj3+BLwvGkLHVJiSckmjaBZ/vQIZzaerkf6BTZnHbSmQuUwO0lFzJRwlKOTIaXp0g==}
+  '@stonyx/utils@0.2.3-beta.7':
+    resolution: {integrity: sha512-SF6ZZZJ/f1n/+SJJDj8BJdlgvv+WDLGWGUMIkwTpruA5jv/AYJqSoVIgTpYfuMTnYDIsp3KoruaIKy/qd2ETPQ==}
 
   call-bind-apply-helpers@1.0.2:
     resolution: {integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==}
@@ -164,8 +164,9 @@ packages:
   sinon@21.0.1:
     resolution: {integrity: sha512-Z0NVCW45W8Mg5oC/27/+fCqIHFnW8kpkFOq0j9XJIev4Ld0mKmERaZv5DMLAb9fGCevjKwaEeIQz5+MBXfZcDw==}
 
-  stonyx@0.2.2:
-    resolution: {integrity: sha512-X37/2R2YklI+CX4wKHckPg2pFmOL1hk0CwOMvn7E00sE+8JjhmbHvAeTI+0t50kufBsXKREPX3FBHVUd4Yi4Fw==}
+  stonyx@0.2.3-beta.11:
+    resolution: {integrity: sha512-HqDH7/8q7JeuTOdlekY8BGAM8FGHWTLKPWhd3xC6dAYBvK1zQWJrzINbIIymemReBxy/sDw3cs7PG8kcoOK1dg==}
+    hasBin: true
 
   supports-color@7.2.0:
     resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
@@ -204,7 +205,7 @@ snapshots:
       '@sinonjs/commons': 3.0.1
       type-detect: 4.1.0
 
-  '@stonyx/utils@0.2.2': {}
+  '@stonyx/utils@0.2.3-beta.7': {}
 
   call-bind-apply-helpers@1.0.2:
     dependencies:
@@ -342,7 +343,7 @@ snapshots:
       diff: 8.0.3
       supports-color: 7.2.0
 
-  stonyx@0.2.2:
+  stonyx@0.2.3-beta.11:
     dependencies:
       node-chronicle: 0.2.0
 

package/src/cron-parser.js

@@ -0,0 +1,246 @@
+/**
+ * 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);
+}