pnscheduler 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nil Mustard (https://github.com/nilmus)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# PNScheduler
+
+Persistent NodeJS Scheduler - A simple job scheduler for Node.js applications, with Postgres-based persistence.
+
+## Installation
+
+```bash
+$ npm install pnscheduler
+```
+
+## Features
+
+- Schedule jobs at a specific time
+- Jobs persist between restarts
+- Configurable grace periods
+
+## Set Up
+
+First of all, set the PGCONNECTIONSTRING environment variable for your Postgres database:
+
+```bash
+#.env
+PGCONNECTIONSTRING=<connection_string>
+```
+
+Secondly, run the migration script to create the database tables:
+
+```bash
+$ node --env-file=.env node_modules/pnscheduler/dist/db/migrationScript.js
+```
+
+## Quick Start
+
+Just define a job, schedule it, and start the scheduler.
+
+```typescript
+import scheduler from 'pnscheduler';
+
+// Define a simple job
+scheduler.defineJob("greeting", () => {
+  console.log("Hello, world!");
+});
+
+// Schedule it for tomorrow
+await scheduler.scheduleJob("greeting", new Date(Date.now() + 86400000));
+
+// Start the scheduler
+scheduler.start();
+```
+
+## Usage Examples
+
+### Defining Jobs
+
+```typescript
+// Job without parameters
+scheduler.defineJob("simple-job", () => {
+  console.log("Hello without params!");
+});
+
+// Job with parameters
+scheduler.defineJob("parameterized-job", 
+  ({ something }: { something: string }) => {
+    console.log(something);
+  }
+);
+```
+
+### Scheduling Jobs
+
+```typescript
+// Basic scheduling
+await scheduler.scheduleJob("simple-job", new Date(2084, 0, 1));
+
+// With parameters
+await scheduler.scheduleJob("parameterized-job", new Date(2084, 0, 1), {
+  something: "Hello, world!"
+});
+
+// With grace period (5 minutes)
+await scheduler.scheduleJob("simple-job", new Date(2084, 0, 1), null, 300_000);
+```
+
+### Job Management
+
+```typescript
+// Unscheduling a job
+const job = await scheduler.scheduleJob("simple-job", new Date(2084, 0, 1));
+await scheduler.unscheduleJob(job);
+
+// Manual job execution
+await scheduler.executeJob(job);
+
+// Finding scheduled jobs
+const scheduledJobs = await scheduler.findScheduledJobs();
+console.log(scheduledJobs);
+
+// Finding due jobs
+const dueJobs = await scheduler.findDueJobs();
+console.log(dueJobs);
+```
+
+### Scheduler Control
+
+```typescript
+// Start the scheduler (30s check interval)
+scheduler.start(3000);
+
+// Stop the scheduler
+scheduler.stop();
+```
+
+## API Reference
+
+### Scheduler Methods
+
+- `defineJob(name: string, handler: Function): void`
+- `scheduleJob(name: string, date: Date, params?: any, gracePeriod?: number): Promise<Job>`
+- `unscheduleJob(job: Job): Promise<void>`
+- `executeJob(job: Job): Promise<void>`
+- `findScheduledJobs(): Promise<Job[]>`
+- `start(interval: number): void`
+- `stop(): void`
+
+### Scheduler Properties
+
+- `jobRegistry` - As an alternative to `defineJob`, you can also define jobs by assigning directly to this property,  
+  e.g. `scheduler.jobRegistry = {"job-name", () => {}}`.
+- `verbose` - Set this to true to enable verbose logging,  
+  e.g. `scheduler.verbose = true;`
+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License

package/dist/db/index.d.ts

@@ -0,0 +1,2 @@
+export declare const query: (text: string, params?: any[]) => Promise<import("pg").QueryResult<any>>;
+export declare const closePool: () => Promise<void>;

package/dist/db/index.js

@@ -0,0 +1,18 @@
+import { Pool } from "pg";
+function validateEnv() {
+    if (!process.env.PGCONNECTIONSTRING) {
+        throw new Error("env variable PGCONNECTIONSTRING is not set");
+    }
+}
+let pool = null;
+const getPool = () => {
+    if (!pool) {
+        validateEnv();
+        pool = new Pool({ connectionString: process.env.PGCONNECTIONSTRING });
+    }
+    return pool;
+};
+export const query = (text, params) => {
+    return getPool().query(text, params);
+};
+export const closePool = () => getPool().end();

package/dist/db/migration.d.ts

@@ -0,0 +1 @@
+export declare const migrationQuery: Promise<import("pg").QueryResult<any>>;

package/dist/db/migration.js

@@ -0,0 +1,18 @@
+import * as db from "./index.js";
+export const migrationQuery = db.query(`
+  DROP SCHEMA IF EXISTS pnscheduler CASCADE;
+
+  CREATE SCHEMA IF NOT EXISTS pnscheduler;
+
+  CREATE TYPE pnscheduler.status_type AS ENUM ('pending', 'executed', 'failed', 'skipped');
+  
+  CREATE TABLE IF NOT EXISTS pnscheduler.jobs (
+        id SERIAL PRIMARY KEY,
+        name VARCHAR(255) NOT NULL,
+        execution_date TIMESTAMPTZ NOT NULL,
+        grace_period INTEGER,
+        params JSONB,
+        status pnscheduler.status_type DEFAULT 'pending' NOT NULL,
+        created_at TIMESTAMPTZ DEFAULT NOW()
+  )
+  `);

package/dist/db/migrationScript.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/db/migrationScript.js

@@ -0,0 +1,8 @@
+import * as db from "./index.js";
+import { migrationQuery } from "./migration.js";
+(async () => {
+    console.log("Running migration...");
+    await migrationQuery;
+    console.log("Migration complete!");
+    await db.closePool();
+})();

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import scheduler from "./scheduler.js";
+export default scheduler;
+export type { Job } from "./jobs.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+import scheduler from "./scheduler.js";
+export default scheduler;

package/dist/jobs.d.ts

@@ -0,0 +1,19 @@
+export type JobStatus = "pending" | "executed" | "failed" | "skipped";
+type JobRow = {
+    id: number;
+    name: string;
+    execution_date: Date;
+    grace_period: number | null;
+    params: any | null;
+    status: JobStatus;
+};
+export declare class Job {
+    id: number;
+    name: string;
+    executionDate: Date;
+    gracePeriod: number | null;
+    params: any;
+    status: JobStatus;
+    constructor({ id, name, execution_date, grace_period, params, status, }: JobRow);
+}
+export {};

package/dist/jobs.js

@@ -0,0 +1,42 @@
+function validateJobRow(row) {
+    if (typeof row !== "object" || row === null)
+        throw new Error("Invalid job row");
+    if (typeof row.id !== "number")
+        throw new Error(`Invalid job row column: id - ${row.id}`);
+    if (typeof row.name !== "string")
+        throw new Error(`Invalid job row column: name - ${row.name}`);
+    if (!(row.execution_date instanceof Date))
+        throw new Error(`Invalid job row column: execution_date - ${row.execution_date}`);
+    if (typeof row.grace_period !== "number" && row.grace_period !== null)
+        throw new Error(`Invalid job row column: grace_period - ${row.grace_period}`);
+    if (row.params !== null && typeof row.params !== "object")
+        throw new Error(`Invalid job row column: params - ${row.params}`);
+    if (typeof row.status !== "string" ||
+        !["pending", "executed", "failed", "skipped"].includes(row.status))
+        throw new Error(`Invalid job row column: status - ${row.status}`);
+    return row;
+}
+export class Job {
+    id;
+    name;
+    executionDate;
+    gracePeriod;
+    params;
+    status;
+    constructor({ id, name, execution_date, grace_period, params, status, }) {
+        const row = validateJobRow({
+            id,
+            name,
+            execution_date,
+            grace_period,
+            params,
+            status,
+        });
+        this.id = row.id;
+        this.name = row.name;
+        this.executionDate = row.execution_date;
+        this.gracePeriod = row.grace_period;
+        this.params = row.params;
+        this.status = row.status;
+    }
+}

package/dist/scheduler.d.ts

@@ -0,0 +1,31 @@
+import { Job } from "./jobs.js";
+declare class PNScheduler {
+    #private;
+    constructor();
+    verbose: boolean;
+    jobRegistry: Record<string, Function>;
+    defineJob(name: string, func: Function): void;
+    /**
+     * Schedules a job to be executed at a specific date and time, with specific parameters.
+     *
+     * @param name The name of the job, as defined with the "defineJob" method.
+     * @param executionDate The date and time at which to run the job.
+     * @param params The params (as an object) to pass to the job function.
+     * @param gracePeriod The grace period past the execution date (in seconds) before a job is marked as "skipped". Defaults to null.
+     */
+    scheduleJob(name: string, executionDate: Date, params?: any, gracePeriod?: number | null): Promise<Job>;
+    unscheduleJob(job: Job): Promise<void>;
+    executeJob(job: Job): Promise<void>;
+    findDueJobs(): Promise<Job[]>;
+    findScheduledJobs(): Promise<Job[]>;
+    /**
+     * Starts the scheduler and sets up a recurring interval to scan for and run scheduled jobs.
+     *
+     * @param checkFrequency The frequency (in seconds) at which to check for scheduled jobs. Defaults to 1.
+     */
+    start(checkFrequency?: number): void;
+    stop(): Promise<void>;
+    reset(): Promise<void>;
+}
+declare const _default: PNScheduler;
+export default _default;

package/dist/scheduler.js

@@ -0,0 +1,125 @@
+import * as db from "./db/index.js";
+import { Job } from "./jobs.js";
+class PNScheduler {
+    constructor() { }
+    verbose = false; // When true, print logs to console
+    jobRegistry = {};
+    #interval;
+    #log(message) {
+        if (this.verbose) {
+            console.log(message);
+        }
+    }
+    defineJob(name, func) {
+        this.#log(`Defining job "${name}"...`);
+        this.jobRegistry[name] = func;
+    }
+    /**
+     * Schedules a job to be executed at a specific date and time, with specific parameters.
+     *
+     * @param name The name of the job, as defined with the "defineJob" method.
+     * @param executionDate The date and time at which to run the job.
+     * @param params The params (as an object) to pass to the job function.
+     * @param gracePeriod The grace period past the execution date (in seconds) before a job is marked as "skipped". Defaults to null.
+     */
+    async scheduleJob(name, executionDate, params, gracePeriod = null) {
+        this.#log(`Scheduling job "${name}" to be executed at ${executionDate}`);
+        if (!this.jobRegistry[name]) {
+            throw new Error(`Job "${name}" is not defined — before scheduling a job, define it with the "defineJob" method`);
+        }
+        const res = await db.query(`
+      INSERT INTO pnscheduler.jobs (name, execution_date, grace_period, params)
+      VALUES ($1, $2, $3, $4)
+      RETURNING *
+      `, [name, executionDate, gracePeriod, JSON.stringify(params)]);
+        const jobRow = res.rows[0];
+        return new Job(jobRow);
+    }
+    async unscheduleJob(job) {
+        this.#log(`Unscheduling job ${job.name} with id ${job.id}...`);
+        await db.query(`DELETE FROM pnscheduler.jobs WHERE id = $1`, [job.id]);
+    }
+    async executeJob(job) {
+        this.#log(`Executing job "${job.name}" with id ${job.id}...`);
+        const func = this.jobRegistry[job.name];
+        if (!func) {
+            console.error(`Failed execution of job "${job.name}" — job is not defined`);
+            await this.#markJobStatusAs(job, "failed");
+            return;
+        }
+        try {
+            await func(job.params);
+        }
+        catch (err) {
+            console.error(`Error executing job "${job.name}" with id ${job.id}:`, err);
+            await this.#markJobStatusAs(job, "failed");
+            return;
+        }
+        await this.#markJobStatusAs(job, "executed");
+    }
+    async #markJobStatusAs(job, status) {
+        this.#log(`Marking job "${job.name}" with id ${job.id} as ${status}...`);
+        await db.query(`UPDATE pnscheduler.jobs SET status = $1 WHERE id = $2`, [
+            status,
+            job.id,
+        ]);
+    }
+    async findDueJobs() {
+        this.#log("Finding due jobs...");
+        const res = await db.query(`
+        WITH updated_jobs AS (
+            UPDATE pnscheduler.jobs
+            SET status = 'skipped'
+            WHERE status = 'pending'
+                AND execution_date <= NOW()
+                AND grace_period IS NOT NULL
+                AND execution_date + (grace_period * INTERVAL '1 second') < NOW()
+        )
+        SELECT *
+        FROM pnscheduler.jobs
+        WHERE status = 'pending'
+            AND execution_date <= NOW()
+            AND (
+                grace_period IS NULL
+                OR execution_date + (grace_period * INTERVAL '1 second') >= NOW()
+            );
+      `);
+        return res.rows.map((job) => new Job(job));
+    }
+    async findScheduledJobs() {
+        this.#log("Finding scheduled jobs...");
+        const res = await db.query(`
+        SELECT *
+        FROM pnscheduler.jobs
+        WHERE status = 'pending'
+      `);
+        return res.rows.map((job) => new Job(job));
+    }
+    async #scanAndRun() {
+        const jobs = await this.findDueJobs();
+        this.#log(`Found ${jobs.length} scheduled jobs: ${jobs
+            .map((job) => job.name)
+            .join(", ")}`);
+        for (const job of jobs) {
+            await this.executeJob(job);
+        }
+    }
+    /**
+     * Starts the scheduler and sets up a recurring interval to scan for and run scheduled jobs.
+     *
+     * @param checkFrequency The frequency (in seconds) at which to check for scheduled jobs. Defaults to 1.
+     */
+    start(checkFrequency = 1) {
+        this.#log("Starting scheduler...");
+        this.#interval = setInterval(this.#scanAndRun.bind(this), 1000 * checkFrequency);
+    }
+    async stop() {
+        this.#log("Stopping scheduler...");
+        clearInterval(this.#interval);
+    }
+    async reset() {
+        this.#log("Resetting scheduler...");
+        await db.query("DELETE FROM pnscheduler.jobs");
+    }
+}
+export default new PNScheduler();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "pnscheduler",
+  "version": "0.0.1",
+  "description": "Persistent NodeJS Scheduler - A simple job scheduler for Node.js applications, with Postgres-based persistence.",
+  "keywords": [
+    "node",
+    "nodejs",
+    "scheduler",
+    "postgres",
+    "postgresql",
+    "persistent",
+    "job"
+  ],
+  "homepage": "https://github.com/nilmus/pnscheduler",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/nilmus/pnscheduler.git",
+    "directory": "packages/pg"
+  },
+  "license": "MIT",
+  "author": "Nil Mustard",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest",
+    "migrate": "node --env-file=.env src/db/migrationScript.ts",
+    "start": "node --env-file=.env index.ts"
+  },
+  "dependencies": {
+    "pg": "^8.16.3"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.15.5",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}