jsm-scheduler

A lightweight and intuitive job scheduler library for Node.js. Leverage decorators to define and manage cron jobs in a clean and scalable way.

Features

• Schedule jobs using simple decorators like @Cron, @Delay, @MaxFreezeTime, etc.
• Supports production-only jobs with @ProductionOnly.
• Modular and clean architecture.
• Built on top of the powerful node-schedule library.

Installation

Install the package using npm:

npm install jsm-scheduler

Or with yarn:

yarn add jsm-scheduler

Usage

Basic Example

Here is how you can use jsm-scheduler to define and manage scheduled tasks:

1. Define Your Scheduler Class

import { Scheduler, Cron, Delay, MaxFreezeTime, TaskName, ProductionOnly } from 'jsm-scheduler';

@Scheduler
class TaskScheduler {
  /**
   * Cron syntax breakdown:
   *  - ┌───────────── second (optional)
   *  - │ ┌───────────── minute (0 - 59)
   *  - │ │ ┌───────────── hour (0 - 23)
   *  - │ │ │ ┌───────────── day of the month (1 - 31)
   *  - │ │ │ │ ┌───────────── month (1 - 12)
   *  - │ │ │ │ │ ┌───────────── day of the week (0 - 7) (0 or 7 are Sunday)
   *  - │ │ │ │ │ │
   *  - 0 * * * * *
   *
   *  Example usage:
   *  - `0 0 0 * * *`: Runs at midnight every day.
   *  - `0 0 12 * * *`: Runs at noon (12:00 PM) every day.
   *  - `0 0 0 1 * *`: Runs at midnight on the first day of every month.
   *  - `0 0 0 * * 1`: Runs at midnight every Monday.
   *  - `0 * /30 * * * *`: Runs every 30 minutes.
   *  - `0 0 0 * /2 * *`: Runs at midnight every other day.
   *
   */  
  @Cron('0 0 0 * * *')
  @Delay(1000) // Adds a 1-second delay before execution
  @MaxFreezeTime(15 * 60 * 1000) // Ensures tasks are frozen for a maximum of 15 minutes
  @TaskName('midnightTask') // Custom task name
  @ProductionOnly() // Executes only in production environments
  async midnightTask() {
    console.log('Executing midnight task logic...');
    // Add your custom task logic here
  }
}

2. Initialize the Scheduler

Simply import the file containing your scheduler class to initialize it:

// index.ts
import './task-scheduler'; // Import your scheduler class

When you run your application, the scheduler will automatically register and execute the defined jobs.

Advanced Example

You can define multiple jobs with different configurations:

import { Scheduler, Cron, Delay, TaskName } from 'jsm-scheduler';

@Scheduler
class AdvancedScheduler {
  @Cron('*/10 * * * * *') // Runs every 10 seconds
  @TaskName('heartbeat')
  async heartbeatTask() {
    console.log('Heartbeat task running...');
  }

  @Cron('0 0 12 * * *') // Runs every day at noon
  async dailyReportTask() {
    console.log('Generating daily report...');
    // Your report generation logic here
  }
}

Decorators

@Cron(cron: string)

Defines the cron expression for the task.

@Delay(delay: number)

Adds a delay (in milliseconds) before the task execution.

@MaxFreezeTime(maxFreezeTime: number)

Ensures a task cannot be frozen for more than the specified time (in milliseconds).

@TaskName(name: string)

Sets a custom name for the task.

@ProductionOnly()

Restricts the execution of the task to production environments (NODE_ENV=production).

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! If you'd like to report issues or submit pull requests, please visit the GitHub repository.

Links

• GitHub Repository: reevosolutions/jsm-scheduler
• npm Package: jsm-scheduler

Author

Developed by Reevo Solutions.