als-schedule

A universal task scheduler for Node.js with support for repetition, cron expressions, local time, and time zones.
Precise, flexible, and battle-tested.

📦 Installation

npm install als-schedule

🚀 Quick Start

import Schedule from 'als-schedule';

const tm = new Schedule();

tm.schedule({
  every: 'day',
  at: '08:00',
  on: 30,
  fn: () => console.log('Good morning!')
});

✅ Features

• Supports multiple tasks at the same timestamp
• Automatically splits long delays into chunks (≤ 24 days)
• Dynamically rebuilds the queue when tasks are cancelled
• Supports:
  • finite repetitions (repeat > 0)
  • infinite loops (repeat = -1)
• Scheduling modes:
  • day: run daily at a specific time
  • week: run on specific weekdays
  • month: run on specific days of the month
  • cron: arbitrary cron expressions
• Full timezone support via IANA strings (Europe/Kiev, America/New_York, etc.)

📘 Examples

🔁 Every day at 08:00, 30 times

tm.schedule({
  every: 'day',
  at: '08:00',
  on: 30,
  fn: sendReport
});

📅 Every Monday and Thursday at 19:30

tm.schedule({
  every: 'week',
  days: [1, 4], // 0 = Sunday, 1 = Monday, ..., 6 = Saturday
  at: '19:30',
  on: Infinity,
  fn: backup
});

⏱ Cron: 1st and 15th of each month at 10:15

tm.schedule({
  every: 'cron',
  expr: '15 10 1,15 * *', // min hour dom mon dow
  on: Infinity,
  fn: sendSalaryReminder
});

🌍 Every Saturday at 22:00 (New York timezone)

tm.schedule({
  every: 'week',
  days: [6], // Saturday
  at: '22:00',
  timezone: 'America/New_York',
  on: Infinity,
  fn: () => syncDB('us')
});

🔧 Rule Fields

| Field | Type | Default | Description | |-------------|----------------------------------------|-----------|---------------------------------------------------------| | every | 'day' | 'week' | 'month' | 'cron' | – | Base interval | | at | string 'HH:MM' | '00:00' | Local time of day for execution | | days | number[] | All | For week mode: days of week (0 = Sunday, 6 = Saturday) | | expr | string (cron expression) | – | Cron expression (used when every: 'cron') | | on | number or Infinity | 1 | How many times to run the task | | timezone | string (IANA) | 'local' | Timezone name (e.g., 'Europe/Kiev') | | fn | function(task) | – | Task callback (receives the task instance) |

🛠 Compatibility

• Node.js 18+ (Node 20+ recommended)
• Works in both ESM and CommonJS

📤 Import Options

// ESM
import Schedule from 'als-schedule';

// CommonJS
const Schedule = require('als-schedule');

🧪 Testing

Tested with node:test. Includes both unit and live scheduling integration tests with timeouts and repetitions.

🧾 License

MIT