@toolkit-p2p/cron

Distributed cron job scheduler for P2P applications with standard 5-field cron expression support.

Features

• Standard 5-field cron expression parsing (minute hour day month weekday)
• Job scheduling with automatic execution
• Job lifecycle management (enable, disable, query)
• Retry and timeout support
• Execution history tracking
• Optional persistence via storage adapter
• Statistics and monitoring

Installation

npm install @toolkit-p2p/cron

Usage

import { CronScheduler } from '@toolkit-p2p/cron';

// Create scheduler
const scheduler = new CronScheduler();

// Add a job
await scheduler.addJob({
  name: 'daily-cleanup',
  schedule: '0 0 * * *', // Daily at midnight
  handler: async (context) => {
    console.log(`Running ${context.jobName} at ${new Date(context.executionTime)}`);
    // Your job logic here
  },
  metadata: { priority: 'high' },
});

// Query jobs
const jobs = scheduler.queryJobs({ enabled: true });

// Get statistics
const stats = scheduler.getStats();
console.log(`Total jobs: ${stats.totalJobs}, Enabled: ${stats.enabledJobs}`);

Cron Expression Format

The scheduler supports standard 5-field cron expressions:

* * * * *
│ │ │ │ │
│ │ │ │ └─ Day of week (0-6, 0=Sunday)
│ │ │ └─── Month (1-12)
│ │ └───── Day of month (1-31)
│ └─────── Hour (0-23)
└───────── Minute (0-59)

Examples

• * * * * * - Every minute
• 0 * * * * - Every hour
• 0 0 * * * - Daily at midnight
• 0 0 * * 0 - Every Sunday at midnight
• */5 * * * * - Every 5 minutes
• 0,30 * * * * - Every hour at 0 and 30 minutes
• 0-15 * * * * - First 15 minutes of every hour

API

CronScheduler

Constructor

const scheduler = new CronScheduler(options?: SchedulerOptions);

Options:

• autoStart - Auto-start scheduler (default: true)
• checkIntervalMs - Job check interval (default: 1000ms)
• maxConcurrentJobs - Max concurrent jobs (default: 10)
• enablePersistence - Enable persistence (default: false)
• storageAdapter - Storage adapter for persistence
• defaultTimezone - Default timezone (default: 'UTC')

Methods

• addJob(options) - Add a new job
• removeJob(jobId) - Remove a job
• getJob(jobId) - Get job by ID
• enableJob(jobId) - Enable a job
• disableJob(jobId) - Disable a job
• queryJobs(query?) - Query jobs with filters
• getStats() - Get scheduler statistics
• start() - Start the scheduler
• stop() - Stop the scheduler

Job Options

interface CreateJobOptions {
  name: string;
  schedule: string;
  handler: (context: JobContext) => void | Promise<void>;
  metadata?: Record<string, unknown>;
  enabled?: boolean;
  maxRetries?: number;
  retryDelayMs?: number;
  timeoutMs?: number;
  timezone?: string;
}

Job Context

Job handlers receive a context object:

interface JobContext {
  jobId: string;
  jobName: string;
  scheduledTime: number;
  executionTime: number;
  runCount: number;
  metadata?: Record<string, unknown>;
  signal?: AbortSignal;
}

Testing

pnpm test

License

MIT