⏱️ cronz-scheduler

A lightweight, zero-dependency TypeScript/JavaScript cron and interval scheduler for Node.js.

🛠️ Schedule cron-based and interval-based jobs — with optional auto-expiration.

---

📦 Installation

npm install cronz-scheduler

🚀 Features

• ✅ Supports standard cron expressions (like * * * * *)

• ✅ Schedule jobs using seconds based intervals (5, 10, etc.)

• ✅ Optional endAt to auto stop jobs after a specific time

• ✅ Manually stop any job

• ✅ Lightweight and fast no external dependencies

• ✅ Fully written in TypeScript

🧠 Cron Expression Format

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

✨ Usage

const { CronScheduler } = require("cronz-scheduler");
const scheduler = new CronScheduler();

/**
 * 1. Cron job: Every minute
 */
scheduler.addJob("every-minute", "* * * * *", () => {
  console.log(
    "[every-minute] Running every minute:",
    new Date().toLocaleTimeString()
  );
});

/**
 * 2. Cron job: Every day at 3:30 AM
 */
scheduler.addJob("daily-3-30am", "30 3 * * *", () => {
  console.log("[daily-3-30am] It's 3:30 AM!");
});

/**
 * 3. Cron job: Every Monday at 12 PM
 */
scheduler.addJob("weekly-monday-noon", "0 12 * * 1", () => {
  console.log("[weekly-monday-noon] It's Monday Noon!");
});

/**
 * 4. Cron job: Every 5 minutes
 */
scheduler.addJob("every-5-min", "*/5 * * * *", () => {
  console.log("[every-5-min] Every 5 minutes");
});

/**
 * 5. Cron job: On 1st of every month at midnight
 */
scheduler.addJob("monthly-midnight", "0 0 1 * *", () => {
  console.log("[monthly-midnight] First day of the month at midnight!");
});

/**
 * 6. Cron job with `endAt`: Stop after 2 minutes
 */
scheduler.addJob(
  "limited-cron",
  "* * * * *",
  () => {
    console.log("[limited-cron] This will run only for 2 minutes");
  },
  {
    endAt: new Date(Date.now() + 2 * 60_000),
  }
);

/**
 * 7. Interval job: Every 10 seconds
 */
scheduler.addJob("interval-10s", 10, () => {
  console.log("[interval-10s] Runs every 10 seconds");
});

/**
 * 8. Interval job with `endAt`: Runs every 3 seconds, stops after 15 seconds
 */
scheduler.addJob(
  "temp-interval",
  3,
  () => {
    console.log("[temp-interval] Runs every 3s until endAt");
  },
  {
    endAt: new Date(Date.now() + 15_000),
  }
);

/**
 * 9. Manual stop after 20 seconds
 */
setTimeout(() => {
  scheduler.stopJob("interval-10s");
  console.log("[manual-stop] Stopped interval-10s manually");
}, 20_000);

// Start the scheduler
scheduler.start();

🧪 Advanced Cron Examples

Description	Expression
Every minute	* * * * *
Daily at 9:00 AM	0 9 * * *
Every Monday at 12:00 PM	0 12 * * 1
Every 5 minutes	*/5 * * * *
On the 1st of every month	0 0 1 * *
Every weekday at 9 AM	0 9 * * 1-5

🔧 API Reference

addJob(name, expressionOrSeconds, callback, options?)

Adds a new job to the scheduler.

Parameter	Type	Description
name	string	Unique name for the job.
expressionOrSeconds	string | number	Cron expression (* * * * *) or number of seconds for interval jobs.
callback	() => void	Function to execute when the job triggers.
options.endAt	Date (optional)	If provided, the job will auto-stop after this time.

Example:

scheduler.addJob("every-5-seconds", 5, () => {
  console.log("Runs every 5 seconds");
});

scheduler.addJob(
  "daily-job",
  "0 9 * * *",
  () => console.log("Runs every day at 9 AM"),
  { endAt: new Date(Date.now() + 60_000) } // optional
);

start(): void

Begins evaluating and running scheduled jobs.

Example

scheduler.start();

stopJob(name: string): void

Stops a job by its name.

Example

scheduler.stopJob("interval");

🔒 License

MIT © Ahmad Hassan Khan