als-schedule

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'
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