@namnguyen.repl.it/nn-scheduler 1.0.0 → 2.0.0

package/dist/scheduler.d.ts

@@ -1,4 +1,4 @@
-import { IntervalTask, ScheduledTask, SchedulerConfig } from './types/SchedulerType';
+import { IntervalTask, ScheduledTask, SchedulerConfig, JobRegistry, JobRecord } from "./types/SchedulerType";
 /**
  * Scheduler class for managing background tasks in Node.js, designed to run under PM2.
  * Supports two types of tasks:
@@ -11,11 +11,54 @@ export declare class Scheduler {
     private logHandler;
     private cronJobs;
     private intervalIds;
+    private db;
+    private jobHandlers;
+    private jobPollerInterval;
     /**
      * Creates a new Scheduler instance
-     * @param config Configuration object with optional logHandler
+     * @param config Configuration object with optional logHandler and dbPath
      */
     constructor(config?: SchedulerConfig);
+    /**
+     * Initializes the SQLite database schema for job persistence
+     */
+    private initializeDatabase;
+    /**
+     * Registers job handlers that can be invoked by name
+     * @param jobs Object mapping job names to handler functions
+     */
+    registerJobs(jobs: JobRegistry): void;
+    /**
+     * Schedules a one-time job to run at a specific time
+     * @param time Time to run in "HH:MM" format (24-hour)
+     * @param jobName Name of the registered job handler
+     * @param data Data to pass to the job handler (can be any JSON-serializable value)
+     * @returns The job ID
+     */
+    job(time: string, jobName: string, data?: any): number;
+    /**
+     * Starts the internal job poller that checks for pending jobs every minute
+     */
+    private startJobPoller;
+    /**
+     * Polls the database for pending jobs that are ready to execute
+     */
+    private pollJobs;
+    /**
+     * Executes a single job and updates its status
+     */
+    private executeJob;
+    /**
+     * Gets all pending jobs from the database
+     * @returns Array of pending job records
+     */
+    getPendingJobs(): JobRecord[];
+    /**
+     * Cancels a scheduled job by ID
+     * @param jobId The job ID to cancel
+     * @returns True if job was cancelled, false if not found
+     */
+    cancelJob(jobId: number): boolean;
     /**
      * Converts a time string and weekdays into a cron expression
      * @param time Time in "HH:MM" format

package/dist/scheduler.js

@@ -41,17 +41,21 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 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"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 /** 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 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' });
+    fs.appendFileSync(logFile, logMessage, { encoding: "utf8" });
 };
 /**
  * Scheduler class for managing background tasks in Node.js, designed to run under PM2.
@@ -64,14 +68,174 @@ const defaultLogHandler = (message) => {
 class Scheduler {
     /**
      * Creates a new Scheduler instance
-     * @param config Configuration object with optional logHandler
+     * @param config Configuration object with optional logHandler and dbPath
      */
     constructor(config = {}) {
         this.cronJobs = [];
         this.intervalIds = [];
+        this.jobHandlers = new Map();
+        this.jobPollerInterval = null;
         this.logHandler = config.logHandler || defaultLogHandler;
+        const dbPath = config.dbPath || path.join(process.cwd(), "scheduler.db");
+        this.db = new better_sqlite3_1.default(dbPath);
+        this.initializeDatabase();
+        this.startJobPoller();
         this.setupPM2();
     }
+    /**
+     * Initializes the SQLite database schema for job persistence
+     */
+    initializeDatabase() {
+        this.db.exec(`
+            CREATE TABLE IF NOT EXISTS jobs (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                job_name TEXT NOT NULL,
+                scheduled_at TEXT NOT NULL,
+                data TEXT,
+                status TEXT DEFAULT 'pending',
+                created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+                error TEXT
+            )
+        `);
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_jobs_status_scheduled ON jobs(status, scheduled_at)`);
+        this.logHandler("Database initialized");
+    }
+    /**
+     * Registers job handlers that can be invoked by name
+     * @param jobs Object mapping job names to handler functions
+     */
+    registerJobs(jobs) {
+        for (const [name, handler] of Object.entries(jobs)) {
+            this.jobHandlers.set(name, handler);
+            this.logHandler(`Registered job handler: ${name}`);
+        }
+    }
+    /**
+     * Schedules a one-time job to run at a specific time
+     * @param time Time to run in "HH:MM" format (24-hour)
+     * @param jobName Name of the registered job handler
+     * @param data Data to pass to the job handler (can be any JSON-serializable value)
+     * @returns The job ID
+     */
+    job(time, jobName, data) {
+        // Validate time format
+        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}`);
+        }
+        // Check if job handler exists
+        if (!this.jobHandlers.has(jobName)) {
+            throw new Error(`Job handler not registered: ${jobName}`);
+        }
+        // Calculate scheduled_at datetime
+        const now = new Date();
+        const scheduledAt = new Date(now);
+        scheduledAt.setHours(hours, minutes, 0, 0);
+        // If time has passed today, schedule for tomorrow
+        if (scheduledAt <= now) {
+            scheduledAt.setDate(scheduledAt.getDate() + 1);
+        }
+        const scheduledAtStr = scheduledAt.toISOString();
+        const dataStr = data !== undefined ? JSON.stringify(data) : null;
+        const stmt = this.db.prepare(`
+            INSERT INTO jobs (job_name, scheduled_at, data, status)
+            VALUES (?, ?, ?, 'pending')
+        `);
+        const result = stmt.run(jobName, scheduledAtStr, dataStr);
+        this.logHandler(`Scheduled job '${jobName}' for ${scheduledAtStr} (ID: ${result.lastInsertRowid})`);
+        return result.lastInsertRowid;
+    }
+    /**
+     * Starts the internal job poller that checks for pending jobs every minute
+     */
+    startJobPoller() {
+        // Run immediately on start
+        this.pollJobs();
+        // Then run every minute
+        this.jobPollerInterval = setInterval(() => {
+            this.pollJobs();
+        }, 60000); // 60 seconds
+        this.logHandler("Job poller started (runs every minute)");
+    }
+    /**
+     * Polls the database for pending jobs that are ready to execute
+     */
+    pollJobs() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const now = new Date().toISOString();
+            const stmt = this.db.prepare(`
+            SELECT * FROM jobs 
+            WHERE status = 'pending' AND scheduled_at <= ?
+        `);
+            const pendingJobs = stmt.all(now);
+            for (const job of pendingJobs) {
+                yield this.executeJob(job);
+            }
+        });
+    }
+    /**
+     * Executes a single job and updates its status
+     */
+    executeJob(job) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const handler = this.jobHandlers.get(job.job_name);
+            if (!handler) {
+                this.logHandler(`Job handler not found: ${job.job_name} (ID: ${job.id})`);
+                this.db
+                    .prepare(`UPDATE jobs SET status = 'failed', error = ? WHERE id = ?`)
+                    .run("Handler not found", job.id);
+                return;
+            }
+            // Mark as processing
+            this.db
+                .prepare(`UPDATE jobs SET status = 'processing' WHERE id = ?`)
+                .run(job.id);
+            try {
+                const data = job.data ? JSON.parse(job.data) : undefined;
+                this.logHandler(`Executing job '${job.job_name}' (ID: ${job.id})`);
+                yield handler(data);
+                // Mark as completed and delete
+                this.db.prepare(`DELETE FROM jobs WHERE id = ?`).run(job.id);
+                this.logHandler(`Job '${job.job_name}' completed and removed (ID: ${job.id})`);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                this.db
+                    .prepare(`UPDATE jobs SET status = 'failed', error = ? WHERE id = ?`)
+                    .run(errorMessage, job.id);
+                this.logHandler(`Job '${job.job_name}' failed (ID: ${job.id}): ${errorMessage}`);
+            }
+        });
+    }
+    /**
+     * Gets all pending jobs from the database
+     * @returns Array of pending job records
+     */
+    getPendingJobs() {
+        return this.db
+            .prepare(`SELECT * FROM jobs WHERE status = 'pending' ORDER BY scheduled_at`)
+            .all();
+    }
+    /**
+     * Cancels a scheduled job by ID
+     * @param jobId The job ID to cancel
+     * @returns True if job was cancelled, false if not found
+     */
+    cancelJob(jobId) {
+        const result = this.db
+            .prepare(`DELETE FROM jobs WHERE id = ? AND status = 'pending'`)
+            .run(jobId);
+        if (result.changes > 0) {
+            this.logHandler(`Cancelled job ID: ${jobId}`);
+            return true;
+        }
+        return false;
+    }
     /**
      * Converts a time string and weekdays into a cron expression
      * @param time Time in "HH:MM" format
@@ -80,11 +244,16 @@ class Scheduler {
      * @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) {
+        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(',');
+        const weekDayStr = weekDays.includes("*") ? "*" : weekDays.join(",");
         return `${minutes} ${hours} * * ${weekDayStr}`;
     }
     // Converts a time string and matchPattern into a cron expression
@@ -93,30 +262,37 @@ class Scheduler {
     // @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) {
+        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 [year, month, day] = matchPattern.split("/");
         const yearNum = parseInt(year, 10);
-        const monthNum = month === '**' ? '*' : parseInt(month, 10);
-        const dayNum = day === '**' ? '*' : parseInt(day, 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) {
+        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)) {
+        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)) {
+        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
@@ -130,7 +306,7 @@ class Scheduler {
      */
     isMatchingWeekDay(weekDays) {
         const currentDay = new Date().getDay();
-        return weekDays.includes('*') || weekDays.includes(currentDay);
+        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')
@@ -144,12 +320,14 @@ class Scheduler {
         if (!matchPattern.match(/^\d{4}\/(\d{2}|\*\*)\/(\d{2}|\*\*)$/)) {
             return false;
         }
-        const [patternYear, patternMonth, patternDay] = matchPattern.split('/');
+        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);
+        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))) {
+        if (isNaN(yearNum) ||
+            (patternMonth !== "**" && isNaN(monthNum)) ||
+            (patternDay !== "**" && isNaN(dayNum))) {
             return false;
         }
         // Check year match
@@ -157,17 +335,19 @@ class Scheduler {
             return false;
         }
         // Check month match
-        if (patternMonth !== '**' && monthNum !== month) {
+        if (patternMonth !== "**" && monthNum !== month) {
             return false;
         }
         // Check day match
-        if (patternDay !== '**' && dayNum !== day) {
+        if (patternDay !== "**" && dayNum !== day) {
             return false;
         }
         // Validate date (e.g., avoid Feb 30)
-        if (patternMonth !== '**' && patternDay !== '**') {
+        if (patternMonth !== "**" && patternDay !== "**") {
             const date = new Date(yearNum, monthNum - 1, dayNum);
-            if (date.getFullYear() !== yearNum || date.getMonth() + 1 !== monthNum || date.getDate() !== dayNum) {
+            if (date.getFullYear() !== yearNum ||
+                date.getMonth() + 1 !== monthNum ||
+                date.getDate() !== dayNum) {
                 return false;
             }
         }
@@ -180,7 +360,7 @@ class Scheduler {
     schedule(tasks) {
         for (const task of tasks) {
             if (!task.time) {
-                this.logHandler('No valid time provided for scheduled task, skipping');
+                this.logHandler("No valid time provided for scheduled task, skipping");
                 continue;
             }
             // Weekdays trigger
@@ -201,7 +381,7 @@ class Scheduler {
                     }
                 }));
                 this.cronJobs.push(cronJob);
-                this.logHandler(`Scheduled task at ${task.time} with weekdays ${task.weekDays.join(',')}`);
+                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}`);
@@ -280,7 +460,7 @@ class Scheduler {
                 }
             }), 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'}`);
+            this.logHandler(`Started interval task every ${task.interval / 1000} seconds with weekdays ${task.weekDays.join(",")} and patterns ${task.matchPattern ? task.matchPattern.join(",") : "none"}`);
         }
     }
     /**
@@ -288,26 +468,33 @@ class Scheduler {
      * Called when PM2 sends a shutdown signal
      */
     stop() {
-        this.cronJobs.forEach(job => job.stop());
+        this.cronJobs.forEach((job) => job.stop());
         this.cronJobs = [];
-        this.logHandler('All scheduled tasks stopped');
-        this.intervalIds.forEach(id => clearInterval(id));
+        this.logHandler("All scheduled tasks stopped");
+        this.intervalIds.forEach((id) => clearInterval(id));
         this.intervalIds = [];
-        this.logHandler('All interval tasks stopped');
+        this.logHandler("All interval tasks stopped");
+        if (this.jobPollerInterval) {
+            clearInterval(this.jobPollerInterval);
+            this.jobPollerInterval = null;
+            this.logHandler("Job poller stopped");
+        }
+        this.db.close();
+        this.logHandler("Database connection closed");
     }
     /**
      * 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...');
+        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...');
+        process.on("message", (msg) => {
+            if (msg === "shutdown") {
+                this.logHandler("Received shutdown message from PM2, stopping scheduler...");
                 this.stop();
                 process.exit(0);
             }

package/dist/types/SchedulerType.d.ts

@@ -2,12 +2,28 @@
 export type Task = () => void | Promise<void>;
 /** A log handler is a function that processes log messages */
 export type LogHandler = (message: string) => void;
+/** A job handler receives data of any type and processes it */
+export type JobHandler<T = any> = (data: T) => void | Promise<void>;
+/** Registry of job handlers keyed by job name */
+export type JobRegistry = Record<string, JobHandler>;
+/** A stored job record in the database */
+export interface JobRecord {
+    id: number;
+    job_name: string;
+    scheduled_at: string;
+    data: string;
+    status: "pending" | "processing" | "completed" | "failed";
+    created_at: string;
+    error?: string;
+}
 /**
  * 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;
+    /** Path to SQLite database file for job persistence. Defaults to 'scheduler.db' in current directory */
+    dbPath?: string;
 }
 /**
  * Definition of a scheduled task with time, matchPattern, and weekday constraints
@@ -19,7 +35,7 @@ export interface ScheduledTask {
     /** The task to execute */
     action: Task;
     /** Array of weekdays to run on (0-6 for Sun-Sat, or '*' for all days) */
-    weekDays: Array<number | '*'>;
+    weekDays: Array<number | "*">;
 }
 /**
  * Definition of an interval task with time, matchPattern, and weekday constraints
@@ -30,5 +46,5 @@ export interface IntervalTask {
     /** The task to execute */
     action: Task;
     /** Array of weekdays to run on (0-6 for Sun-Sat, or '*' for all days) */
-    weekDays: Array<number | '*'>;
+    weekDays: Array<number | "*">;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namnguyen.repl.it/nn-scheduler",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "A scheduler module for NodeJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,9 +11,11 @@
   },
   "keywords": [],
   "dependencies": {
+    "better-sqlite3": "^11.0.0",
     "node-cron": "^3.0.3"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
     "@babel/core": "^7.26.10",
     "@babel/preset-env": "^7.26.9",
     "@babel/preset-typescript": "^7.26.0",