@stonyx/cron 0.2.1-beta.14 → 0.2.1-beta.140

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: