@namnguyen.repl.it/nn-scheduler 1.0.0

package/Readme.md

@@ -0,0 +1,58 @@
+
+## Example usage with timeout handling in actions
+class MyAction {
+    static longRunningAction() {
+        return async () => {
+            try {
+                //console.log('Long running action started');
+                await new Promise((resolve, reject) => {
+                    const timeout = setTimeout(() => reject(new Error('Action timed out')), 90 * 1000);
+                    setTimeout(() => {
+                        clearTimeout(timeout);
+                        resolve();
+                    }, 120 * 1000);
+                });
+                //console.log('Long running action completed');
+            } catch (error) {
+                console.error(`Long running action failed: ${error}`);
+                throw error;
+            }
+        };
+    }
+
+    static failingAction() {
+        return async () => {
+            try {
+                //console.log('Failing action started');
+                await new Promise((_, reject) => setTimeout(() => reject(new Error('Action failed')), 1000));
+                //console.log('Failing action completed');
+            } catch (error) {
+                console.error(`Failing action failed: ${error}`);
+                throw error;
+            }
+        };
+    }
+}
+
+const scheduler = new Scheduler({
+    logHandler: (msg) => //console.log(msg)
+});
+
+scheduler.schedule([
+    { time: '07:15', action: MyAction.longRunningAction(), weekDays: ['*'] },
+    { time: '09:15', action: MyAction.failingAction(), weekDays: [6, 1, 2, 3] },
+]);
+
+scheduler.interval([
+    { interval: 60 * 1000, action: MyAction.longRunningAction(), weekDays: ['*'] },
+    { interval: 60 * 1000, action: MyAction.failingAction(), weekDays: [2, 3, 4] },
+]);
+
+
+Using PM2 to manage tasks:
+pm2 start scheduler.js --name scheduler
+pm2 list
+pm2 logs scheduler
+pm2 stop scheduler
+pm2 restart scheduler
+pm2 delete scheduler

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types/SchedulerType';
+export * from './scheduler';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types/SchedulerType"), exports);
+__exportStar(require("./scheduler"), exports);

package/dist/scheduler.d.ts

@@ -0,0 +1,55 @@
+import { IntervalTask, ScheduledTask, SchedulerConfig } from './types/SchedulerType';
+/**
+ * Scheduler class for managing background tasks in Node.js, designed to run under PM2.
+ * Supports two types of tasks:
+ * 1. Scheduled tasks that run at specific times on specified weekdays or matchPattern.
+ * 2. Interval tasks that run every n milliseconds if weekdays or matchPattern conditions are met.
+ * Runs indefinitely until stopped via PM2 commands (e.g., `pm2 stop scheduler`).
+ * Long-running or failing tasks are handled by the actions themselves.
+ */
+export declare class Scheduler {
+    private logHandler;
+    private cronJobs;
+    private intervalIds;
+    /**
+     * Creates a new Scheduler instance
+     * @param config Configuration object with optional logHandler
+     */
+    constructor(config?: SchedulerConfig);
+    /**
+     * Converts a time string and weekdays into a cron expression
+     * @param time Time in "HH:MM" format
+     * @param weekDays Array of weekdays (0-6 or '*')
+     * @returns Cron expression string (e.g., "15 7 * * *")
+     * @throws Error if time format is invalid
+     */
+    private timeToCron;
+    private patternToCron;
+    /**
+     * Checks if the current day matches the specified weekdays
+     * @param weekDays Array of weekdays (0-6 or '*')
+     * @returns True if today is in the weekday list or '*' is included
+     */
+    private isMatchingWeekDay;
+    private isMatchingPattern;
+    /**
+     * Schedules tasks to run at specific times on specified weekdays or matchPattern
+     * @param tasks Array of scheduled tasks to execute
+     */
+    schedule(tasks: ScheduledTask[]): void;
+    /**
+     * Schedules tasks to run every n milliseconds if weekdays or matchPattern conditions are met
+     * @param tasks Array of interval tasks to execute
+     */
+    interval(tasks: IntervalTask[]): void;
+    /**
+     * Stops all scheduled and interval tasks
+     * Called when PM2 sends a shutdown signal
+     */
+    stop(): void;
+    /**
+     * Sets up integration with PM2 by handling shutdown signals
+     * PM2 sends SIGINT when stopping the process
+     */
+    private setupPM2;
+}

package/dist/scheduler.js

@@ -0,0 +1,318 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scheduler = void 0;
+const cron = __importStar(require("node-cron"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Writes log messages to a file named by date (e.g., "2025-03-24.log") in the current directory */
+const defaultLogHandler = (message) => {
+    const date = new Date().toISOString().split('T')[0];
+    const logFile = path.join(process.cwd(), `${date}.log`);
+    const logMessage = `${new Date().toISOString()} - ${message}\n`;
+    fs.appendFileSync(logFile, logMessage, { encoding: 'utf8' });
+};
+/**
+ * Scheduler class for managing background tasks in Node.js, designed to run under PM2.
+ * Supports two types of tasks:
+ * 1. Scheduled tasks that run at specific times on specified weekdays or matchPattern.
+ * 2. Interval tasks that run every n milliseconds if weekdays or matchPattern conditions are met.
+ * Runs indefinitely until stopped via PM2 commands (e.g., `pm2 stop scheduler`).
+ * Long-running or failing tasks are handled by the actions themselves.
+ */
+class Scheduler {
+    /**
+     * Creates a new Scheduler instance
+     * @param config Configuration object with optional logHandler
+     */
+    constructor(config = {}) {
+        this.cronJobs = [];
+        this.intervalIds = [];
+        this.logHandler = config.logHandler || defaultLogHandler;
+        this.setupPM2();
+    }
+    /**
+     * Converts a time string and weekdays into a cron expression
+     * @param time Time in "HH:MM" format
+     * @param weekDays Array of weekdays (0-6 or '*')
+     * @returns Cron expression string (e.g., "15 7 * * *")
+     * @throws Error if time format is invalid
+     */
+    timeToCron(time, weekDays) {
+        const [hours, minutes] = time.split(':').map(Number);
+        if (isNaN(hours) || isNaN(minutes) || hours < 0 || hours > 23 || minutes < 0 || minutes > 59) {
+            throw new Error(`Invalid time format: ${time}`);
+        }
+        const weekDayStr = weekDays.includes('*') ? '*' : weekDays.join(',');
+        return `${minutes} ${hours} * * ${weekDayStr}`;
+    }
+    // Converts a time string and matchPattern into a cron expression
+    // @param time Time in "HH:MM" format
+    // @param matchPattern Pattern (e.g., '2025/**/**', '2025/06/01')
+    // @returns Cron expression string
+    // @throws Error if time or pattern is invalid
+    patternToCron(time, matchPattern) {
+        const [hours, minutes] = time.split(':').map(Number);
+        if (isNaN(hours) || isNaN(minutes) || hours < 0 || hours > 23 || minutes < 0 || minutes > 59) {
+            throw new Error(`Invalid time format: ${time}`);
+        }
+        // Validate pattern format (yyyy/mm/dd with ** wildcards)
+        if (!matchPattern.match(/^\d{4}\/(\d{2}|\*\*)\/(\d{2}|\*\*)$/)) {
+            throw new Error(`Invalid pattern format: ${matchPattern}`);
+        }
+        const [year, month, day] = matchPattern.split('/');
+        const yearNum = parseInt(year, 10);
+        const monthNum = month === '**' ? '*' : parseInt(month, 10);
+        const dayNum = day === '**' ? '*' : parseInt(day, 10);
+        // Validate year (basic range check, assuming 1970-2099 for cron compatibility)
+        if (isNaN(yearNum) || yearNum < new Date().getFullYear() || yearNum > 3000) {
+            throw new Error(`Invalid year in pattern: ${matchPattern}`);
+        }
+        // Validate month//
+        //@ts-ignore
+        if (month !== '**' && (isNaN(monthNum) || monthNum < 1 || monthNum > 12)) {
+            throw new Error(`Invalid month in pattern: ${matchPattern}`);
+        }
+        // Validate day
+        //@ts-ignore
+        if (day !== '**' && (isNaN(dayNum) || dayNum < 1 || dayNum > 31)) {
+            throw new Error(`Invalid day in pattern: ${matchPattern}`);
+        }
+        // Note: Cron doesn't support year directly, so we rely on pattern matching in schedule
+        // For simplicity, we generate a cron expression for day/month, assuming year is handled externally
+        return `${minutes} ${hours} ${dayNum} ${monthNum} *`;
+    }
+    /**
+     * Checks if the current day matches the specified weekdays
+     * @param weekDays Array of weekdays (0-6 or '*')
+     * @returns True if today is in the weekday list or '*' is included
+     */
+    isMatchingWeekDay(weekDays) {
+        const currentDay = new Date().getDay();
+        return weekDays.includes('*') || weekDays.includes(currentDay);
+    }
+    //Checks if the current date matches the specified match signalling
+    //@param matchPattern Pattern (e.g., '2025/**/** ', '2025 /06 /01')
+    //@returns True if today matches the pattern
+    isMatchingPattern(matchPattern) {
+        const today = new Date();
+        const day = today.getDate();
+        const month = today.getMonth() + 1; // getMonth() is 0-based
+        const year = today.getFullYear();
+        // Validate pattern format (yyyy/mm/dd with ** wildcards)
+        if (!matchPattern.match(/^\d{4}\/(\d{2}|\*\*)\/(\d{2}|\*\*)$/)) {
+            return false;
+        }
+        const [patternYear, patternMonth, patternDay] = matchPattern.split('/');
+        const yearNum = parseInt(patternYear, 10);
+        const monthNum = patternMonth === '**' ? month : parseInt(patternMonth, 10);
+        const dayNum = patternDay === '**' ? day : parseInt(patternDay, 10);
+        // Validate parsed values
+        if (isNaN(yearNum) || (patternMonth !== '**' && isNaN(monthNum)) || (patternDay !== '**' && isNaN(dayNum))) {
+            return false;
+        }
+        // Check year match
+        if (yearNum !== year) {
+            return false;
+        }
+        // Check month match
+        if (patternMonth !== '**' && monthNum !== month) {
+            return false;
+        }
+        // Check day match
+        if (patternDay !== '**' && dayNum !== day) {
+            return false;
+        }
+        // Validate date (e.g., avoid Feb 30)
+        if (patternMonth !== '**' && patternDay !== '**') {
+            const date = new Date(yearNum, monthNum - 1, dayNum);
+            if (date.getFullYear() !== yearNum || date.getMonth() + 1 !== monthNum || date.getDate() !== dayNum) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Schedules tasks to run at specific times on specified weekdays or matchPattern
+     * @param tasks Array of scheduled tasks to execute
+     */
+    schedule(tasks) {
+        for (const task of tasks) {
+            if (!task.time) {
+                this.logHandler('No valid time provided for scheduled task, skipping');
+                continue;
+            }
+            // Weekdays trigger
+            try {
+                const cronExpression = this.timeToCron(task.time, task.weekDays);
+                if (!cron.validate(cronExpression)) {
+                    this.logHandler(`Invalid cron expression for task at ${task.time}: ${cronExpression}`);
+                    continue;
+                }
+                const cronJob = cron.schedule(cronExpression, () => __awaiter(this, void 0, void 0, function* () {
+                    try {
+                        this.logHandler(`Executing scheduled task at ${task.time} (weekdays trigger)`);
+                        yield task.action();
+                        this.logHandler(`Scheduled task at ${task.time} (weekdays trigger) completed`);
+                    }
+                    catch (error) {
+                        this.logHandler(`Error in scheduled task at ${task.time} (weekdays trigger): ${error}`);
+                    }
+                }));
+                this.cronJobs.push(cronJob);
+                this.logHandler(`Scheduled task at ${task.time} with weekdays ${task.weekDays.join(',')}`);
+            }
+            catch (error) {
+                this.logHandler(`Error processing task at ${task.time} for weekdays: ${error}`);
+            }
+            // MatchPattern trigger
+            if (task.matchPattern) {
+                for (const pattern of task.matchPattern) {
+                    try {
+                        const cronExpression = this.patternToCron(task.time, pattern);
+                        if (!cron.validate(cronExpression)) {
+                            this.logHandler(`Invalid cron expression for task at ${task.time}, pattern ${pattern}: ${cronExpression}`);
+                            continue;
+                        }
+                        const cronJob = cron.schedule(cronExpression, () => __awaiter(this, void 0, void 0, function* () {
+                            try {
+                                this.logHandler(`Executing scheduled task at ${task.time} (pattern ${pattern} trigger)`);
+                                yield task.action();
+                                this.logHandler(`Scheduled task at ${task.time} (pattern ${pattern} trigger) completed`);
+                            }
+                            catch (error) {
+                                this.logHandler(`Error in scheduled task at ${task.time} (pattern ${pattern} trigger): ${error}`);
+                            }
+                        }));
+                        this.cronJobs.push(cronJob);
+                        this.logHandler(`Scheduled task at ${task.time} with pattern ${pattern}`);
+                    }
+                    catch (error) {
+                        this.logHandler(`Error processing task at ${task.time}, pattern ${pattern}: ${error}`);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Schedules tasks to run every n milliseconds if weekdays or matchPattern conditions are met
+     * @param tasks Array of interval tasks to execute
+     */
+    interval(tasks) {
+        for (const task of tasks) {
+            if (task.interval <= 0 || !Number.isInteger(task.interval)) {
+                this.logHandler(`Invalid interval: ${task.interval}`);
+                continue;
+            }
+            const intervalId = setInterval(() => __awaiter(this, void 0, void 0, function* () {
+                let triggered = false;
+                // Check weekdays
+                if (this.isMatchingWeekDay(task.weekDays)) {
+                    triggered = true;
+                    try {
+                        this.logHandler(`Executing interval task every ${task.interval / 1000} seconds (weekdays trigger)`);
+                        yield task.action();
+                        this.logHandler(`Interval task every ${task.interval / 1000} seconds (weekdays trigger) completed`);
+                    }
+                    catch (error) {
+                        this.logHandler(`Error in interval task every ${task.interval / 1000} seconds (weekdays trigger): ${error}`);
+                    }
+                }
+                // Check matchPattern
+                if (task.matchPattern) {
+                    for (const pattern of task.matchPattern) {
+                        if (this.isMatchingPattern(pattern)) {
+                            triggered = true;
+                            try {
+                                this.logHandler(`Executing interval task every ${task.interval / 1000} seconds (pattern ${pattern} trigger)`);
+                                yield task.action();
+                                this.logHandler(`Interval task every ${task.interval / 1000} seconds (pattern ${pattern} trigger) completed`);
+                            }
+                            catch (error) {
+                                this.logHandler(`Error in interval task every ${task.interval / 1000} seconds (pattern ${pattern} trigger): ${error}`);
+                            }
+                        }
+                    }
+                }
+                if (!triggered) {
+                    this.logHandler(`Interval task every ${task.interval / 1000} seconds skipped (no matching weekdays or patterns)`);
+                }
+            }), task.interval);
+            this.intervalIds.push(intervalId);
+            this.logHandler(`Started interval task every ${task.interval / 1000} seconds with weekdays ${task.weekDays.join(',')} and patterns ${task.matchPattern ? task.matchPattern.join(',') : 'none'}`);
+        }
+    }
+    /**
+     * Stops all scheduled and interval tasks
+     * Called when PM2 sends a shutdown signal
+     */
+    stop() {
+        this.cronJobs.forEach(job => job.stop());
+        this.cronJobs = [];
+        this.logHandler('All scheduled tasks stopped');
+        this.intervalIds.forEach(id => clearInterval(id));
+        this.intervalIds = [];
+        this.logHandler('All interval tasks stopped');
+    }
+    /**
+     * Sets up integration with PM2 by handling shutdown signals
+     * PM2 sends SIGINT when stopping the process
+     */
+    setupPM2() {
+        process.on('SIGINT', () => {
+            this.logHandler('Received SIGINT from PM2, stopping scheduler...');
+            this.stop();
+            process.exit(0);
+        });
+        process.on('message', (msg) => {
+            if (msg === 'shutdown') {
+                this.logHandler('Received shutdown message from PM2, stopping scheduler...');
+                this.stop();
+                process.exit(0);
+            }
+        });
+        this.logHandler(`Scheduler started with PID ${process.pid}. Manage with PM2 commands (e.g., 'pm2 stop scheduler').`);
+    }
+}
+exports.Scheduler = Scheduler;

package/dist/types/SchedulerType.d.ts

@@ -0,0 +1,34 @@
+/** A task is a function that can be executed synchronously or asynchronously */
+export type Task = () => void | Promise<void>;
+/** A log handler is a function that processes log messages */
+export type LogHandler = (message: string) => void;
+/**
+ * Configuration options for the Scheduler
+ */
+export interface SchedulerConfig {
+    /** Optional custom log handler. If not provided, logs are written to daily files (e.g., "2025-03-24.log") */
+    logHandler?: LogHandler;
+}
+/**
+ * Definition of a scheduled task with time, matchPattern, and weekday constraints
+ */
+export interface ScheduledTask {
+    /** Time to run the task in "HH:MM" format (24-hour, e.g., "07:15") */
+    time: string;
+    matchPattern?: string[];
+    /** The task to execute */
+    action: Task;
+    /** Array of weekdays to run on (0-6 for Sun-Sat, or '*' for all days) */
+    weekDays: Array<number | '*'>;
+}
+/**
+ * Definition of an interval task with time, matchPattern, and weekday constraints
+ */
+export interface IntervalTask {
+    interval: number;
+    matchPattern?: string[];
+    /** The task to execute */
+    action: Task;
+    /** Array of weekdays to run on (0-6 for Sun-Sat, or '*' for all days) */
+    weekDays: Array<number | '*'>;
+}

package/dist/types/SchedulerType.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@namnguyen.repl.it/nn-scheduler",
+  "version": "1.0.0",
+  "description": "A scheduler module for NodeJS",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest"
+  },
+  "keywords": [],
+  "dependencies": {
+    "node-cron": "^3.0.3"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.10",
+    "@babel/preset-env": "^7.26.9",
+    "@babel/preset-typescript": "^7.26.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.17.30",
+    "@types/node-cron": "^3.0.11",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "author": "namnguyen.repl.it@gmail.com",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/NamReplIT/nn-scheduler/issues"
+  },
+  "homepage": "https://github.com/NamReplIT/nn-scheduler#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}