cronz-scheduler/README.md

A lightweight cron and interval scheduler for Node.js written in TypeScript.

# ⏱️ 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

```bash
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
```bash
*    *    *    *    *
│    │    │    │    └── Day of week (0 - 6) (Sunday = 0)
│    │    │    └────── Month (1 - 12)
│    │    └─────────── Day of month (1 - 31)
│    └──────────────── Hour (0 - 23)
└───────────────────── Minute (0 - 59)
```
# ✨ Usage
```ts
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:
```ts
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
```ts
scheduler.start();
```

### `stopJob(name: string): void`
Stops a job by its name.

#### Example
```ts
scheduler.stopJob("interval");
```

# 🔒 License
MIT © Ahmad Hassan Khan