@constructive-io/job-scheduler 0.3.7

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## 0.3.7 (2025-12-18)
+
+**Note:** Version bump only for package @constructive-io/job-scheduler
+
+## [0.3.6](https://github.com/constructive-io/jobs/compare/@launchql/job-scheduler@0.3.5...@launchql/job-scheduler@0.3.6) (2025-12-17)
+
+**Note:** Version bump only for package @launchql/job-scheduler

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+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 @@
+# job-scheduler

package/dist/env.d.ts

@@ -0,0 +1,14 @@
+declare const _default: Readonly<{
+    PGUSER: string;
+    PGHOST: string;
+    PGPASSWORD: string;
+    PGPORT: number;
+    PGDATABASE: string;
+    JOBS_SCHEMA: string;
+    JOBS_SUPPORT_ANY: boolean;
+    JOBS_SUPPORTED: string[];
+    HOSTNAME: string;
+}> & import("envalid").CleanEnv & {
+    readonly [varName: string]: string;
+};
+export default _default;

package/dist/env.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const envalid_1 = require("envalid");
+const array = (0, envalid_1.makeValidator)((x) => x.split(',').filter((i) => i), '');
+exports.default = (0, envalid_1.cleanEnv)(process.env, {
+    PGUSER: (0, envalid_1.str)({ default: 'postgres' }),
+    PGHOST: (0, envalid_1.str)({ default: 'localhost' }),
+    PGPASSWORD: (0, envalid_1.str)({ default: 'password' }),
+    PGPORT: (0, envalid_1.port)({ default: 5432 }),
+    PGDATABASE: (0, envalid_1.str)({ default: 'jobs' }),
+    JOBS_SCHEMA: (0, envalid_1.str)({ default: 'app_jobs' }),
+    JOBS_SUPPORT_ANY: (0, envalid_1.bool)({ default: true }),
+    JOBS_SUPPORTED: array({ default: '' }),
+    HOSTNAME: (0, envalid_1.str)({
+        default: 'scheduler-0'
+    })
+}, { dotEnvPath: null });

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import type { PgClientLike } from '@constructive-io/job-utils';
+import type { Pool } from 'pg';
+export interface ScheduledJobRow {
+    id: number | string;
+    task_identifier: string;
+    schedule_info: unknown;
+}
+interface SchedulerJobHandle {
+    cancel(): void;
+}
+export default class Scheduler {
+    idleDelay: number;
+    supportedTaskNames: string[];
+    workerId: string;
+    doNextTimer?: NodeJS.Timeout;
+    pgPool: Pool;
+    jobs: Record<ScheduledJobRow['id'], SchedulerJobHandle>;
+    _initialized?: boolean;
+    constructor({ tasks, idleDelay, pgPool, workerId }: {
+        tasks: string[];
+        idleDelay?: number;
+        pgPool?: Pool;
+        workerId?: string;
+    });
+    initialize(client: PgClientLike): Promise<void>;
+    handleFatalError(client: PgClientLike, { err, fatalError, jobId }: {
+        err?: Error;
+        fatalError: unknown;
+        jobId: ScheduledJobRow['id'];
+    }): Promise<void>;
+    handleError(client: PgClientLike, { err, job, duration }: {
+        err: Error;
+        job: ScheduledJobRow;
+        duration: string;
+    }): Promise<void>;
+    handleSuccess(client: PgClientLike, { job, duration }: {
+        job: ScheduledJobRow;
+        duration: string;
+    }): Promise<void>;
+    scheduleJob(client: PgClientLike, job: ScheduledJobRow): Promise<void>;
+    doNext(client: PgClientLike): Promise<void>;
+    listen(): void;
+}
+export { Scheduler };

package/dist/index.js

@@ -0,0 +1,212 @@
+"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 __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scheduler = void 0;
+const jobs = __importStar(require("@constructive-io/job-utils"));
+const node_schedule_1 = __importDefault(require("node-schedule"));
+const job_pg_1 = __importDefault(require("@constructive-io/job-pg"));
+const logger_1 = require("@pgpmjs/logger");
+const log = new logger_1.Logger('jobs:scheduler');
+class Scheduler {
+    idleDelay;
+    supportedTaskNames;
+    workerId;
+    doNextTimer;
+    pgPool;
+    jobs;
+    _initialized;
+    constructor({ tasks, idleDelay = 15000, pgPool = job_pg_1.default.getPool(), workerId = 'scheduler-0' }) {
+        /*
+         * idleDelay: This is how long to wait between polling for jobs.
+         *
+         * Note: this does NOT need to be short, because we use LISTEN/NOTIFY to be
+         * notified when new jobs are added - this is just used in the case where
+         * LISTEN/NOTIFY fails for whatever reason.
+         */
+        this.idleDelay = idleDelay;
+        this.supportedTaskNames = tasks;
+        this.workerId = workerId;
+        this.doNextTimer = undefined;
+        this.pgPool = pgPool;
+        this.jobs = {};
+        job_pg_1.default.onClose(async () => {
+            await jobs.releaseScheduledJobs(pgPool, {
+                workerId: this.workerId,
+                // When ids is omitted the DB function releases all scheduled jobs
+                ids: undefined
+            });
+        });
+    }
+    async initialize(client) {
+        if (this._initialized === true)
+            return;
+        await jobs.releaseScheduledJobs(client, {
+            workerId: this.workerId,
+            // When ids is omitted the DB function releases all scheduled jobs
+            ids: undefined
+        });
+        this._initialized = true;
+        await this.doNext(client);
+    }
+    async handleFatalError(client, { err, fatalError, jobId }) {
+        const when = err ? `after failure '${err.message}'` : 'after success';
+        log.error(`Failed to release job '${jobId}' ${when}; committing seppuku`);
+        log.error(String(fatalError));
+        await job_pg_1.default.close();
+        process.exit(1);
+    }
+    async handleError(client, { err, job, duration }) {
+        log.error(`Failed to initialize scheduler for ${job.id} (${job.task_identifier}) with error ${err.message} (${duration}ms)`);
+        const j = this.jobs[job.id];
+        if (j)
+            j.cancel();
+        await jobs.releaseScheduledJobs(client, {
+            workerId: this.workerId,
+            ids: [job.id]
+        });
+    }
+    async handleSuccess(client, { job, duration }) {
+        log.info(`initialized ${job.id} (${job.task_identifier}) with success (${duration}ms)`);
+    }
+    async scheduleJob(client, job) {
+        const { id, task_identifier, schedule_info } = job;
+        const j = node_schedule_1.default.scheduleJob(schedule_info, async () => {
+            const newjob = (await jobs.runScheduledJob(client, {
+                jobId: id
+            }));
+            if (newjob) {
+                if (newjob.id) {
+                    log.info(`spinning up job[${newjob.task_identifier}]`);
+                }
+                else {
+                    // this means the scheduled_job has been deleted from db, so cancel it
+                    log.info(`attempted job[${job.task_identifier}] but it's probably non existent, unscheduling...`);
+                    const scheduledJob = this.jobs[job.id];
+                    if (scheduledJob)
+                        scheduledJob.cancel();
+                }
+            }
+            else {
+                log.info(`job already scheduled but not yet run or complete: [${job.task_identifier}]`);
+            }
+        });
+        this.jobs[id] = j;
+    }
+    async doNext(client) {
+        if (!this._initialized) {
+            return await this.initialize(client);
+        }
+        if (this.doNextTimer) {
+            clearTimeout(this.doNextTimer);
+            this.doNextTimer = undefined;
+        }
+        try {
+            const job = await jobs.getScheduledJob(client, {
+                workerId: this.workerId,
+                supportedTaskNames: jobs.getJobSupportAny()
+                    ? null
+                    : this.supportedTaskNames
+            });
+            if (!job || !job.id) {
+                this.doNextTimer = setTimeout(() => this.doNext(client), this.idleDelay);
+                return;
+            }
+            const start = process.hrtime();
+            let err = null;
+            try {
+                await this.scheduleJob(client, job);
+            }
+            catch (error) {
+                err = error;
+            }
+            const durationRaw = process.hrtime(start);
+            const duration = ((durationRaw[0] * 1e9 + durationRaw[1]) / 1e6).toFixed(2);
+            const jobId = job.id;
+            try {
+                if (err) {
+                    await this.handleError(client, { err, job, duration });
+                }
+                else {
+                    await this.handleSuccess(client, { job, duration });
+                }
+            }
+            catch (fatalError) {
+                await this.handleFatalError(client, { err, fatalError, jobId });
+            }
+            return this.doNext(client);
+        }
+        catch (err) {
+            this.doNextTimer = setTimeout(() => this.doNext(client), this.idleDelay);
+        }
+    }
+    listen() {
+        const listenForChanges = (err, client, release) => {
+            if (err) {
+                log.error('Error connecting with notify listener', err);
+                if (err instanceof Error && err.stack) {
+                    log.debug(err.stack);
+                }
+                // Try again in 5 seconds
+                // should this really be done in the node process?
+                setTimeout(this.listen, 5000);
+                return;
+            }
+            client.on('notification', () => {
+                log.info('a NEW scheduled JOB!');
+                if (this.doNextTimer) {
+                    // Must be idle, do something!
+                    this.doNext(client);
+                }
+            });
+            client.query('LISTEN "scheduled_jobs:insert"');
+            client.on('error', (e) => {
+                log.error('Error with database notify listener', e);
+                if (e instanceof Error && e.stack) {
+                    log.debug(e.stack);
+                }
+                release();
+                this.listen();
+            });
+            log.info(`${this.workerId} connected and looking for scheduled jobs...`);
+            this.doNext(client);
+        };
+        this.pgPool.connect(listenForChanges);
+    }
+}
+exports.default = Scheduler;
+exports.Scheduler = Scheduler;

package/dist/run.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/run.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = __importDefault(require("./index"));
+const job_pg_1 = __importDefault(require("@constructive-io/job-pg"));
+const job_utils_1 = require("@constructive-io/job-utils");
+const pgPool = job_pg_1.default.getPool();
+const scheduler = new index_1.default({
+    pgPool,
+    workerId: (0, job_utils_1.getSchedulerHostname)(),
+    tasks: (0, job_utils_1.getJobSupported)()
+});
+scheduler.listen();

package/jest.config.js

@@ -0,0 +1,18 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        babelConfig: false,
+        tsconfig: 'tsconfig.json',
+      },
+    ],
+  },
+  transformIgnorePatterns: [`/node_modules/*`],
+  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  modulePathIgnorePatterns: ['dist/*'],
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@constructive-io/job-scheduler",
+  "version": "0.3.7",
+  "description": "job scheduler",
+  "author": "Constructive <developers@constructive.io>",
+  "homepage": "https://github.com/constructive-io/jobs/tree/master/packages/job-scheduler#readme",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "dist/index.js",
+  "directories": {
+    "lib": "src",
+    "test": "__tests__"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/jobs"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:debug": "node --inspect node_modules/.bin/jest --runInBand",
+    "build": "tsc -p tsconfig.json",
+    "build:watch": "tsc -p tsconfig.json -w"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/jobs/issues"
+  },
+  "dependencies": {
+    "@constructive-io/job-pg": "^0.3.5",
+    "@constructive-io/job-utils": "^0.5.0",
+    "@pgpmjs/logger": "^1.3.3",
+    "node-schedule": "1.3.2"
+  },
+  "gitHead": "86d74dc4fce9051df0d2b5bcc163607aba42f009"
+}

package/src/index.ts

@@ -0,0 +1,229 @@
+import * as jobs from '@constructive-io/job-utils';
+import type { PgClientLike } from '@constructive-io/job-utils';
+import schedule from 'node-schedule';
+import poolManager from '@constructive-io/job-pg';
+import type { Pool, PoolClient } from 'pg';
+import { Logger } from '@pgpmjs/logger';
+
+export interface ScheduledJobRow {
+  id: number | string;
+  task_identifier: string;
+  schedule_info: unknown;
+}
+
+interface SchedulerJobHandle {
+  cancel(): void;
+}
+
+const log = new Logger('jobs:scheduler');
+
+export default class Scheduler {
+  idleDelay: number;
+  supportedTaskNames: string[];
+  workerId: string;
+  doNextTimer?: NodeJS.Timeout;
+  pgPool: Pool;
+  jobs: Record<ScheduledJobRow['id'], SchedulerJobHandle>;
+  _initialized?: boolean;
+
+  constructor({
+    tasks,
+    idleDelay = 15000,
+    pgPool = poolManager.getPool(),
+    workerId = 'scheduler-0'
+  }: {
+    tasks: string[];
+    idleDelay?: number;
+    pgPool?: Pool;
+    workerId?: string;
+  }) {
+    /*
+     * idleDelay: This is how long to wait between polling for jobs.
+     *
+     * Note: this does NOT need to be short, because we use LISTEN/NOTIFY to be
+     * notified when new jobs are added - this is just used in the case where
+     * LISTEN/NOTIFY fails for whatever reason.
+     */
+    this.idleDelay = idleDelay;
+    this.supportedTaskNames = tasks;
+    this.workerId = workerId;
+    this.doNextTimer = undefined;
+    this.pgPool = pgPool;
+    this.jobs = {};
+    poolManager.onClose(async () => {
+      await jobs.releaseScheduledJobs(pgPool, {
+        workerId: this.workerId,
+        // When ids is omitted the DB function releases all scheduled jobs
+        ids: undefined as unknown as Array<number | string>
+      });
+    });
+  }
+  async initialize(client: PgClientLike) {
+    if (this._initialized === true) return;
+    await jobs.releaseScheduledJobs(client, {
+      workerId: this.workerId,
+      // When ids is omitted the DB function releases all scheduled jobs
+      ids: undefined as unknown as Array<number | string>
+    });
+    this._initialized = true;
+    await this.doNext(client);
+  }
+  async handleFatalError(
+    client: PgClientLike,
+    {
+      err,
+      fatalError,
+      jobId
+    }: { err?: Error; fatalError: unknown; jobId: ScheduledJobRow['id'] }
+  ) {
+    const when = err ? `after failure '${err.message}'` : 'after success';
+    log.error(`Failed to release job '${jobId}' ${when}; committing seppuku`);
+    log.error(String(fatalError));
+    await poolManager.close();
+    process.exit(1);
+  }
+  async handleError(
+    client: PgClientLike,
+    {
+      err,
+      job,
+      duration
+    }: { err: Error; job: ScheduledJobRow; duration: string }
+  ) {
+    log.error(
+      `Failed to initialize scheduler for ${job.id} (${job.task_identifier}) with error ${err.message} (${duration}ms)`
+    );
+    const j = this.jobs[job.id];
+    if (j) j.cancel();
+    await jobs.releaseScheduledJobs(client, {
+      workerId: this.workerId,
+      ids: [job.id]
+    });
+  }
+  async handleSuccess(
+    client: PgClientLike,
+    { job, duration }: { job: ScheduledJobRow; duration: string }
+  ) {
+    log.info(
+      `initialized ${job.id} (${job.task_identifier}) with success (${duration}ms)`
+    );
+  }
+  async scheduleJob(client: PgClientLike, job: ScheduledJobRow) {
+    const { id, task_identifier, schedule_info } = job;
+    const j = schedule.scheduleJob(schedule_info as never, async () => {
+      const newjob = (await jobs.runScheduledJob(client, {
+        jobId: id
+      })) as ScheduledJobRow | null;
+
+      if (newjob) {
+        if (newjob.id) {
+          log.info(`spinning up job[${newjob.task_identifier}]`);
+        } else {
+          // this means the scheduled_job has been deleted from db, so cancel it
+          log.info(
+            `attempted job[${job.task_identifier}] but it's probably non existent, unscheduling...`
+          );
+          const scheduledJob = this.jobs[job.id];
+          if (scheduledJob) scheduledJob.cancel();
+        }
+      } else {
+        log.info(
+          `job already scheduled but not yet run or complete: [${job.task_identifier}]`
+        );
+      }
+    });
+    this.jobs[id] = j as SchedulerJobHandle;
+  }
+  async doNext(client: PgClientLike): Promise<void> {
+    if (!this._initialized) {
+      return await this.initialize(client);
+    }
+
+    if (this.doNextTimer) {
+      clearTimeout(this.doNextTimer);
+      this.doNextTimer = undefined;
+    }
+    try {
+      const job = await jobs.getScheduledJob<ScheduledJobRow>(client, {
+        workerId: this.workerId,
+        supportedTaskNames: jobs.getJobSupportAny()
+          ? null
+          : this.supportedTaskNames
+      });
+      if (!job || !job.id) {
+        this.doNextTimer = setTimeout(
+          () => this.doNext(client),
+          this.idleDelay
+        );
+        return;
+      }
+      const start = process.hrtime();
+
+      let err: Error | null = null;
+      try {
+        await this.scheduleJob(client, job);
+      } catch (error) {
+        err = error as Error;
+      }
+
+      const durationRaw = process.hrtime(start);
+      const duration = ((durationRaw[0] * 1e9 + durationRaw[1]) / 1e6).toFixed(
+        2
+      );
+      const jobId = job.id;
+      try {
+        if (err) {
+          await this.handleError(client, { err, job, duration });
+        } else {
+          await this.handleSuccess(client, { job, duration });
+        }
+      } catch (fatalError: unknown) {
+        await this.handleFatalError(client, { err, fatalError, jobId });
+      }
+      return this.doNext(client);
+    } catch (err: unknown) {
+      this.doNextTimer = setTimeout(() => this.doNext(client), this.idleDelay);
+    }
+  }
+  listen() {
+    const listenForChanges = (
+      err: Error | null,
+      client: PoolClient,
+      release: () => void
+    ) => {
+      if (err) {
+        log.error('Error connecting with notify listener', err);
+        if (err instanceof Error && err.stack) {
+          log.debug(err.stack);
+        }
+        // Try again in 5 seconds
+        // should this really be done in the node process?
+        setTimeout(this.listen, 5000);
+        return;
+      }
+      client.on('notification', () => {
+        log.info('a NEW scheduled JOB!');
+        if (this.doNextTimer) {
+          // Must be idle, do something!
+          this.doNext(client);
+        }
+      });
+      client.query('LISTEN "scheduled_jobs:insert"');
+      client.on('error', (e: unknown) => {
+        log.error('Error with database notify listener', e);
+        if (e instanceof Error && e.stack) {
+          log.debug(e.stack);
+        }
+        release();
+        this.listen();
+      });
+      log.info(
+        `${this.workerId} connected and looking for scheduled jobs...`
+      );
+      this.doNext(client);
+    };
+    this.pgPool.connect(listenForChanges);
+  }
+}
+
+export { Scheduler };

package/src/run.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import Scheduler from './index';
+import poolManager from '@constructive-io/job-pg';
+import {
+  getSchedulerHostname,
+  getJobSupported
+} from '@constructive-io/job-utils';
+
+const pgPool = poolManager.getPool();
+
+const scheduler = new Scheduler({
+  pgPool,
+  workerId: getSchedulerHostname(),
+  tasks: getJobSupported()
+});
+
+scheduler.listen();

package/tsconfig.esm.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/esm",
+    "module": "es2022",
+    "rootDir": "src/",
+    "declaration": false
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src/"
+  },
+  "include": ["src/**/*.ts", "../../types/**/*.d.ts"],
+  "exclude": ["dist", "node_modules", "**/*.spec.*", "**/*.test.*"]
+}