📆 @nodeboot/starter-scheduler – Node-Boot Scheduling Starter

Overview

The @nodeboot/starter-scheduler package provides a simple yet powerful mechanism to schedule jobs within a Node-Boot application, similar to how Spring Boot Scheduler works.

It leverages node-cron under the hood to execute scheduled tasks at specified intervals based on cron expressions.

With minimal configuration, developers can automatically trigger functions within beans using the @Scheduler decorator.

✨ Features

✅ Annotation-based scheduling – Just add @Scheduler(cronExpression) to any bean method. ✅ Cron-based execution – Supports flexible scheduling using cron expressions.
✅ Lifecycle-aware – Scheduling starts when the application initializes.
✅ Minimal setup – Requires only @EnableScheduling to activate.

🚀 Installation

Ensure you have Node-Boot installed in your project. Then, install the scheduler starter package:

pnpm add @nodeboot/starter-scheduler

🔥 Usage

1️⃣ Enable Scheduling in Your Application

To activate the scheduling system, add @EnableScheduling() to your application class:

import {EnableScheduling} from "@nodeboot/starter-scheduler";
import {NodeBootApplication, NodeBoot, ExpressServer} from "@nodeboot/core";

@EnableScheduling()
@NodeBootApplication()
export class SampleApp implements NodeBootApp {
    start(): Promise<NodeBootAppView> {
        return NodeBoot.run(ExpressServer);
    }
}

2️⃣ Schedule Jobs Using @Scheduler

To schedule a method to run at a specific interval, add the @Scheduler decorator to a method inside a bean (@Service, @Component, etc.).

The method will automatically run based on the cron expression provided.

Example: Run a Task Every Minute

import {Scheduler} from "@nodeboot/starter-scheduler";
import {Service} from "@nodeboot/core";

@Service()
export class TaskService {
    @Scheduler("* * * * *") // Runs every minute
    public logMessage() {
        console.log(`Task executed at: ${new Date().toISOString()}`);
    }
}

✅ This will log a message every minute! 🕒

3️⃣ Understanding Cron Expressions

The @Scheduler decorator follows standard cron syntax:

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

| Expression | Meaning | | --------------- | --------------------------------- | | "* * * * *" | Runs every minute | | "0 * * * *" | Runs every hour (at 0 min) | | "0 0 * * *" | Runs daily at midnight | | "0 0 * * 1" | Runs every Monday at midnight | | "*/5 * * * *" | Runs every 5 minutes |

For more advanced cron expressions, refer to node-cron documentation.

🛠️ How It Works Internally

🔹 @Scheduler(cronExpression: string)

This decorator:

• Registers the method as a scheduled job.
• Uses the Adapter Pattern to integrate with the Node-Boot lifecycle.
• Triggers execution based on the cron expression.

🔹 @EnableScheduling()

• Enables automatic scheduling in the application.
• Registers the Scheduler Adapter into the Node-Boot lifecycle.
• Ensures all @Scheduler jobs are scheduled at startup.

🎯 Example: Sending Notifications Every Hour

Imagine you need to send notifications to users every hour. You can achieve this with:

import {Scheduler} from "@nodeboot/starter-scheduler";
import {Service} from "@nodeboot/core";

@Service()
export class NotificationService {
    @Scheduler("0 * * * *") // Runs at the start of every hour
    public sendNotifications() {
        console.log(`📢 Sending notifications to users at ${new Date().toISOString()}`);
    }
}

🔔 This will trigger notifications every hour, automatically!

⚠️ Common Issues & Debugging

❌ @Scheduler Not Running?

✔️ Ensure @EnableScheduling() is added to your application class.
✔️ Verify the cron expression is correct.
✔️ Check the logs to see if the scheduler is registered.

📚 Additional Resources

• Node-Cron Documentation
• Understanding Cron Expressions
• Node-Boot Framework

🎉 Conclusion

The @nodeboot/starter-scheduler package makes scheduling effortless and declarative within Node-Boot applications.

By simply adding @Scheduler(cronExpression), you can automate periodic tasks, without manually managing timers.

Happy scheduling! 🚀🎯