@stonyx/cron 0.2.1-beta.7 → 0.2.1-beta.71

package/.claude/extension-guide.md

@@ -1,291 +0,0 @@
-# Extension Guide
-
-## Extension Points
-
-This section provides specific guidance for common feature additions.
-
-### Adding Job Metadata
-
-**Where:** `stonyx-cron/src/main.js`
-
-**Pattern:**
-```javascript
-// In register method, extend job object:
-register(key, callback, interval, runOnInit=false, metadata={}) {
-  const job = {
-    callback,
-    interval,
-    key,
-    metadata  // Add metadata field
-  };
-  this.jobs[key] = job;
-  // ... rest of method
-}
-
-// Access metadata in runDueJobs or other methods:
-const { metadata } = job;
-if (metadata.priority === 'high') {
-  // Handle high priority jobs differently
-}
-```
-
-**Tests to add:** Verify metadata is stored and accessible in job object.
-
-### Adding Priority Levels
-
-**Where:**
-- `stonyx-cron/src/main.js` (Cron class)
-- `stonyx-cron/src/min-heap.js` (MinHeap comparison)
-
-**Pattern:**
-```javascript
-// Option 1: Secondary sort on priority
-// In min-heap.js bubbleUp/bubbleDown, change comparison:
-if (this.items[idx].nextTrigger < this.items[parentIdx].nextTrigger ||
-    (this.items[idx].nextTrigger === this.items[parentIdx].nextTrigger &&
-     this.items[idx].priority > this.items[parentIdx].priority)) {
-  // Swap
-}
-
-// Option 2: Offset nextTrigger by priority
-// In main.js setNextTrigger:
-setNextTrigger(job) {
-  const priorityOffset = job.priority || 0;
-  job.nextTrigger = getTimestamp() + parseInt(job.interval, 10) - priorityOffset;
-}
-```
-
-**Considerations:**
-- Option 1 maintains exact timing but adds complexity to heap
-- Option 2 is simpler but slightly alters execution timing
-- Add `priority` field to job object schema
-
-**Tests to add:** Jobs with higher priority run before lower priority when due at same time.
-
-### Adding Job Statistics
-
-**Where:** `stonyx-cron/src/main.js`
-
-**Pattern:**
-```javascript
-// Extend job object with stats:
-register(key, callback, interval, runOnInit=false) {
-  const job = {
-    callback,
-    interval,
-    key,
-    stats: {
-      runCount: 0,
-      lastRun: null,
-      lastError: null,
-      errorCount: 0
-    }
-  };
-  // ...
-}
-
-// Update stats in runDueJobs:
-async runDueJobs() {
-  // ...
-  try {
-    await job.callback();
-    job.stats.runCount++;
-    job.stats.lastRun = getTimestamp();
-  } catch (err) {
-    job.stats.errorCount++;
-    job.stats.lastError = err.message;
-    log.error(`Cron job "${job.key}" failed:`, err);
-  }
-  // ...
-}
-
-// Add method to retrieve stats:
-getJobStats(key) {
-  return this.jobs[key]?.stats;
-}
-```
-
-**Tests to add:** Verify stats increment correctly on success/error.
-
-### Adding Persistence
-
-**Where:** `stonyx-cron/src/main.js`
-
-**Pattern:**
-```javascript
-// Add save/load methods:
-async saveJobs() {
-  const jobData = Object.values(this.jobs).map(job => ({
-    key: job.key,
-    interval: job.interval,
-    // Don't save callback - must be re-registered
-  }));
-  // Write to file/database
-}
-
-async loadJobs(callbacks) {
-  const jobData = // Read from file/database
-  jobData.forEach(({ key, interval }) => {
-    if (callbacks[key]) {
-      this.register(key, callbacks[key], interval);
-    }
-  });
-}
-```
-
-**Considerations:**
-- Cannot serialize callbacks - must be re-registered on load
-- Save job metadata, intervals, and keys
-- Consider saving `nextTrigger` to maintain schedule across restarts
-
-**Tests to add:** Verify jobs can be saved and restored with same intervals.
-
-### Adding One-Time Jobs
-
-**Where:** `stonyx-cron/src/main.js`
-
-**Pattern:**
-```javascript
-// Add oneTime flag to job schema:
-register(key, callback, interval, runOnInit=false, oneTime=false) {
-  const job = { callback, interval, key, oneTime };
-  // ...
-}
-
-// Modify runDueJobs to unregister one-time jobs:
-async runDueJobs() {
-  const now = getTimestamp();
-  const { heap } = this;
-
-  while (!heap.isEmpty() && heap.peek().nextTrigger <= now) {
-    const job = heap.pop();
-
-    try {
-      await job.callback();
-    } catch (err) {
-      log.error(`Cron job "${job.key}" failed:`, err);
-    }
-
-    if (job.oneTime) {
-      delete this.jobs[job.key];  // Don't reschedule
-      if (config.debug) this.log('one-time job completed', job.key);
-    } else {
-      this.setNextTrigger(job);
-      heap.push(job);
-    }
-  }
-
-  this.scheduleNextRun();
-}
-```
-
-**Tests to add:** One-time jobs execute once and are not rescheduled.
-
----
-
-## Common Pitfalls & Gotchas
-
-### Time Units Confusion
-**Pitfall:** Mixing seconds and milliseconds
-
-**Correct:**
-```javascript
-// getTimestamp() returns SECONDS
-const now = getTimestamp();
-job.interval = 5;  // 5 seconds
-job.nextTrigger = now + 5;  // 5 seconds from now
-
-// setTimeout expects MILLISECONDS
-const delay = (job.nextTrigger - now) * 1000;
-setTimeout(callback, delay);
-```
-
-**Wrong:**
-```javascript
-// DON'T DO THIS
-const delay = job.nextTrigger - getTimestamp();  // Missing * 1000
-setTimeout(callback, delay);  // Will run almost immediately!
-```
-
-### Singleton Behavior
-**Pitfall:** Creating multiple Cron instances unexpectedly
-
-**Behavior:**
-```javascript
-const cron1 = new Cron();
-const cron2 = new Cron();
-console.log(cron1 === cron2);  // true - same instance!
-```
-
-**Implication:** Registering jobs on any instance affects the same scheduler.
-
-### Job Callback Async Handling
-**Pitfall:** Not awaiting async callbacks
-
-**Correct:**
-```javascript
-cron.register('job', async () => {
-  await someAsyncOperation();
-}, 10);
-```
-
-The scheduler awaits the callback, so errors are caught properly.
-
-**Wrong:**
-```javascript
-cron.register('job', () => {
-  someAsyncOperation();  // Not awaited - errors won't be caught!
-}, 10);
-```
-
-### Heap Reference Equality
-**Pitfall:** Modifying job objects outside the scheduler
-
-**Issue:**
-```javascript
-const job = cron.jobs['myJob'];
-job.interval = 20;  // This doesn't update the heap!
-```
-
-**Solution:** Always use `unregister` then `register` to update job properties.
-
-### Test Isolation
-**Pitfall:** Tests interfering with each other due to singleton
-
-**Solution:**
-```javascript
-hooks.beforeEach(function () {
-  clock = sinon.useFakeTimers({ shouldAdvanceTime: false });
-  cron = new Cron();  // Gets singleton
-
-  // Clear previous test's jobs
-  Object.keys(cron.jobs).forEach(key => cron.unregister(key));
-});
-
-hooks.afterEach(function () {
-  sinon.restore();  // Restores real timers
-});
-```
-
----
-
-## Future Enhancement Opportunities
-
-Ideas aligned with current architecture:
-
-1. **Job Prioritization** - Add priority levels for jobs due at same time
-2. **Persistence Layer** - Save/restore jobs across restarts
-3. **Job Statistics** - Track run counts, errors, execution time
-4. **Job Dependencies** - Wait for other jobs before running
-5. **Cron Expression Support** - Use cron syntax instead of intervals
-6. **Job Timeout** - Cancel jobs that run too long
-7. **Pause/Resume** - Temporarily stop/start the scheduler
-8. **Job Groups** - Batch operations on related jobs
-9. **Event Emitters** - Emit events on job lifecycle (start, complete, error)
-10. **Rate Limiting** - Limit concurrent job execution
-
-All enhancements should maintain:
-- Zero-crash guarantee (catch all errors)
-- O(log n) scheduling efficiency
-- Singleton pattern
-- Configuration-driven logging

package/.claude/improvements.md

@@ -1,53 +0,0 @@
-# Improvement Opportunities
-
-## `register()` does not validate duplicate keys
-
-**File:** `src/main.js`, `register()` method (line 67)
-
-When `register()` is called with a key that already exists, it overwrites the entry in `this.jobs[key]` but never removes the old job object from the heap. The old entry remains orphaned in the heap and will still trigger when its `nextTrigger` time arrives, even though it is no longer tracked in `this.jobs`.
-
-```javascript
-register(key, callback, interval, runOnInit=false) {
-  const job = { callback, interval, key };
-  this.jobs[key] = job;       // overwrites old reference
-  this.setNextTrigger(job);
-  this.heap.push(job);        // pushes new entry, old entry still in heap
-  // ...
-}
-```
-
-**Impact:** The orphaned heap entry will fire its old callback on the old schedule. Since it is no longer in `this.jobs`, it cannot be unregistered.
-
-**Suggested fix:** Check for an existing key and call `unregister(key)` before registering, or throw an error if the key is already registered.
-
----
-
-## `runOnInit` callback is not awaited
-
-**File:** `src/main.js`, `register()` method (line 79)
-
-When `runOnInit` is `true`, the callback is invoked synchronously without `await`:
-
-```javascript
-if (runOnInit) {
-  try {
-    callback();          // not awaited
-  } catch (err) {
-    log.error(`Cron job "${key}" failed on init:`, err);
-  }
-}
-```
-
-This is inconsistent with `runDueJobs()`, which does await the callback:
-
-```javascript
-try {
-  await job.callback();  // awaited
-} catch (err) {
-  log.error(`Cron job "${job.key}" failed:`, err);
-}
-```
-
-**Impact:** If the callback is async and throws, the rejection will not be caught by the `try/catch` block in `register()`. The error becomes an unhandled promise rejection instead of being logged.
-
-**Suggested fix:** Add `await` to the `callback()` call in the `runOnInit` branch and make `register()` async, or wrap in a `.catch()` handler.

package/.claude/project-structure.md

@@ -1,139 +0,0 @@
-# stonyx-cron Project Structure
-
-## Detailed Guides
-
-- [Architecture & Core Components](./architecture.md) — Deep dive into Cron and MinHeap classes, dependencies, code patterns, and configuration reference
-- [Testing Guidelines](./testing.md) — Test structure, fake timers, spies/stubs patterns, and running tests
-- [Extension Guide](./extension-guide.md) — Extension points, common pitfalls, and future enhancement opportunities
-
----
-
-## 1. Project Overview
-
-**stonyx-cron** is a lightweight async job scheduler for the Stonyx framework that uses a min-heap priority queue for efficient job scheduling.
-
-**Core Purpose:**
-- Schedule and execute async jobs at specified intervals
-- O(log n) scheduling efficiency via min-heap priority queue
-- Robust error handling that never crashes the scheduler
-- Configuration-driven logging aligned with Stonyx patterns
-
-**Technology Stack:**
-- **Module System:** ES Modules (ESM)
-- **Testing:** QUnit with Sinon for spies/stubs/fake timers
-- **Dependencies:** Stonyx framework, @stonyx/utils/date
-- **Node Version:** Specified in `.nvmrc`
-
----
-
-## 2. Architecture & Design Decisions
-
-### Singleton Pattern
-The `Cron` class uses a singleton pattern to ensure only one scheduler instance exists across the entire application. The constructor returns the existing instance if one has already been created.
-
-```javascript
-constructor() {
-  if (Cron.instance) return Cron.instance;
-  Cron.instance = this;
-}
-```
-
-**Rationale:** Prevents multiple competing schedulers and ensures consistent job management.
-
-### Min-Heap Priority Queue
-Jobs are stored in a min-heap ordered by `nextTrigger` timestamp, allowing O(log n) insertion and O(1) peek of the next job to run.
-
-**Heap Property:** Parent nodes have earlier `nextTrigger` values than their children, so the root is always the next job to execute.
-
-### Async Job Execution Strategy
-- Jobs are executed with `await job.callback()` to handle async operations
-- Errors are caught and logged but never crash the scheduler
-- After execution (success or failure), jobs are rescheduled and re-inserted into the heap
-- The scheduler reschedules itself after processing all due jobs
-
-### Configuration-Driven Logging
-Logging follows Stonyx patterns:
-- Check `config.debug` before debug logs
-- Check `config.cron?.log` before cron-specific logs
-- Use `log.cron()` for cron messages, `log.error()` for errors
-
----
-
-## 3. File Structure
-
-```
-stonyx-cron/
-├── .claude/
-│   ├── project-structure.md             - Project overview & structure
-│   ├── architecture.md                  - Core components & code patterns
-│   ├── testing.md                       - Testing guidelines
-│   ├── extension-guide.md              - Extension points & pitfalls
-│   └── improvements.md                 - Known improvement opportunities
-├── .github/
-│   └── workflows/
-│       ├── ci.yml                       - CI pipeline (PR checks)
-│       └── publish.yml                  - NPM publish workflow
-├── config/
-│   └── environment.js                   - Cron module configuration
-├── src/
-│   ├── main.js                          - Cron class (singleton scheduler)
-│   └── min-heap.js                      - MinHeap priority queue implementation
-├── test/
-│   └── unit/
-│       ├── cron-test.js                 - Cron class unit tests
-│       └── min-heap-test.js             - MinHeap unit tests
-├── package.json                         - Package metadata and exports
-├── README.md                            - Project documentation
-├── LICENSE.md                           - Apache 2.0 license
-├── .npmignore                           - Files excluded from npm publish
-├── .nvmrc                               - Node version specification
-└── .gitignore                           - Git ignore rules
-```
-
----
-
-## 4. Package Exports
-
-**File:** `stonyx-cron/package.json`
-
-```json
-{
-  "exports": {
-    ".": "./src/main.js",
-    "./min-heap": "./src/min-heap.js"
-  }
-}
-```
-
-**Usage:**
-```javascript
-// Import Cron class (default export)
-import Cron from '@stonyx/cron';
-
-// Import MinHeap class (for advanced usage)
-import MinHeap from '@stonyx/cron/min-heap';
-```
-
----
-
-## 5. Related Resources
-
-### Stonyx Framework
-- Main repository: https://github.com/abofs/stonyx
-- Configuration patterns: See `stonyx/config` documentation
-- Logging patterns: See `stonyx/log` documentation
-- Test helpers: See `stonyx/test-helpers` documentation
-
-### Testing
-- QUnit documentation: https://qunitjs.com/
-- Sinon documentation: https://sinonjs.org/
-- Fake timers: https://sinonjs.org/releases/latest/fake-timers/
-
-### Data Structures
-- Min-heap algorithm: https://en.wikipedia.org/wiki/Binary_heap
-- Priority queue patterns: See MinHeap implementation
-
-### Project Repository
-- GitHub: https://github.com/abofs/stonyx-cron
-- Issues: https://github.com/abofs/stonyx-cron/issues
-- License: Apache 2.0

package/.claude/testing.md

@@ -1,85 +0,0 @@
-# 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/.git/config

@@ -1,18 +0,0 @@
-[core]
-	repositoryformatversion = 0
-	filemode = true
-	bare = false
-	logallrefupdates = true
-[remote "origin"]
-	url = https://github.com/abofs/stonyx-cron
-	fetch = +refs/heads/*:refs/remotes/origin/*
-[gc]
-	auto = 0
-[http "https://github.com/"]
-	extraheader = AUTHORIZATION: basic eC1hY2Nlc3MtdG9rZW46Z2hwX2hBdU5WbnJNcml2bktkZTlmaU80WW9lZk9QenZtdTFiUWtQNA==
-[branch "main"]
-	remote = origin
-	merge = refs/heads/main
-[user]
-	name = github-actions[bot]
-	email = github-actions[bot]@users.noreply.github.com

package/.github/workflows/ci.yml

@@ -1,16 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches: [dev, main]
-
-concurrency:
-  group: ci-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -1,51 +0,0 @@
-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

@@ -1,16 +0,0 @@
-# dependencies
-/node_modules/
-
-# config
-config/environment.js
-
-# logs
-*logs/*
-
-# os / IDE
-.vscode/*
-*.vsix%
-*DS_Store*
-
-# npm auth (never commit tokens)
-.npmrc

package/.npmignore

@@ -1,5 +0,0 @@
-# tests
-test/
-
-# config
-.nvmrc

package/logs/error.log

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