@n8n/scheduler 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class InvalidScheduleError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidScheduleError = void 0;
+class InvalidScheduleError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidScheduleError';
+    }
+}
+exports.InvalidScheduleError = InvalidScheduleError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAQA,MAAa,oBAAqB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACpC,CAAC;CACD;AALD,oDAKC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { ScheduleKindList, TaskStatusList } from './types';
+export type { ScheduleKind, CronSchedule, IntervalSchedule, OneOffSchedule, Schedule, TaskStatus, ScheduledJob, ScheduledTask, } from './types';
+export { InvalidScheduleError } from './errors';
+export { computeNextRunAt } from './recurrence/next-run';
+export { validateSchedule } from './recurrence/validate';
+export type { SchedulerStore } from './storage/storage';

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSchedule = exports.computeNextRunAt = exports.InvalidScheduleError = exports.TaskStatusList = exports.ScheduleKindList = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "ScheduleKindList", { enumerable: true, get: function () { return types_1.ScheduleKindList; } });
+Object.defineProperty(exports, "TaskStatusList", { enumerable: true, get: function () { return types_1.TaskStatusList; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "InvalidScheduleError", { enumerable: true, get: function () { return errors_1.InvalidScheduleError; } });
+var next_run_1 = require("./recurrence/next-run");
+Object.defineProperty(exports, "computeNextRunAt", { enumerable: true, get: function () { return next_run_1.computeNextRunAt; } });
+var validate_1 = require("./recurrence/validate");
+Object.defineProperty(exports, "validateSchedule", { enumerable: true, get: function () { return validate_1.validateSchedule; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAcA,iCAA2D;AAAlD,yGAAA,gBAAgB,OAAA;AAAE,uGAAA,cAAc,OAAA;AAazC,mCAAgD;AAAvC,8GAAA,oBAAoB,OAAA;AAE7B,kDAAyD;AAAhD,4GAAA,gBAAgB,OAAA;AACzB,kDAAyD;AAAhD,4GAAA,gBAAgB,OAAA"}

package/dist/recurrence/next-run.d.ts

@@ -0,0 +1,2 @@
+import type { Schedule } from '../types';
+export declare function computeNextRunAt(schedule: Schedule, after: Date): Date | null;

package/dist/recurrence/next-run.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeNextRunAt = computeNextRunAt;
+const cron_parser_1 = require("cron-parser");
+const errors_1 = require("../errors");
+const validate_1 = require("./validate");
+const MS_PER_SECOND = 1000;
+function cronNextRun(schedule, after, timezone) {
+    try {
+        const it = cron_parser_1.CronExpressionParser.parse(schedule.cronExpression, {
+            currentDate: after,
+            tz: timezone,
+        });
+        return it.next().toDate();
+    }
+    catch (error) {
+        throw new errors_1.InvalidScheduleError(`Failed to evaluate cron expression ${JSON.stringify(schedule.cronExpression)} in timezone ${JSON.stringify(timezone)}: ${error.message}`);
+    }
+}
+function intervalNextRun(schedule, after) {
+    return new Date(after.getTime() + schedule.intervalSeconds * MS_PER_SECOND);
+}
+function oneOffNextRun(schedule, after) {
+    return after.getTime() < schedule.fireAt.getTime() ? schedule.fireAt : null;
+}
+function computeNextRunAt(schedule, after) {
+    (0, validate_1.validateSchedule)(schedule);
+    switch (schedule.kind) {
+        case 'cron':
+            if (schedule.timezone === null) {
+                throw new errors_1.InvalidScheduleError('Cron timezone must be resolved to a concrete zone before computing the next run, got null');
+            }
+            return cronNextRun(schedule, after, schedule.timezone);
+        case 'interval':
+            return intervalNextRun(schedule, after);
+        case 'one_off':
+            return oneOffNextRun(schedule, after);
+        default: {
+            const exhaustive = schedule;
+            throw new errors_1.InvalidScheduleError(`Unknown schedule kind: ${JSON.stringify(exhaustive.kind)}`);
+        }
+    }
+}
+//# sourceMappingURL=next-run.js.map

package/dist/recurrence/next-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-run.js","sourceRoot":"","sources":["../../src/recurrence/next-run.ts"],"names":[],"mappings":";;AAwDA,4CAsBC;AA9ED,6CAAmD;AAEnD,sCAAiD;AAEjD,yCAA8C;AAE9C,MAAM,aAAa,GAAG,IAAI,CAAC;AAU3B,SAAS,WAAW,CAAC,QAAsB,EAAE,KAAW,EAAE,QAAgB;IACzE,IAAI,CAAC;QACJ,MAAM,EAAE,GAAG,kCAAoB,CAAC,KAAK,CAAC,QAAQ,CAAC,cAAc,EAAE;YAC9D,WAAW,EAAE,KAAK;YAClB,EAAE,EAAE,QAAQ;SACZ,CAAC,CAAC;QACH,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,6BAAoB,CAC7B,sCAAsC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,gBAAgB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAM,KAAe,CAAC,OAAO,EAAE,CACpJ,CAAC;IACH,CAAC;AACF,CAAC;AAOD,SAAS,eAAe,CAAC,QAA0B,EAAE,KAAW;IAC/D,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,eAAe,GAAG,aAAa,CAAC,CAAC;AAC7E,CAAC;AAGD,SAAS,aAAa,CAAC,QAAwB,EAAE,KAAW;IAC3D,OAAO,KAAK,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7E,CAAC;AAcD,SAAgB,gBAAgB,CAAC,QAAkB,EAAE,KAAW;IAC/D,IAAA,2BAAgB,EAAC,QAAQ,CAAC,CAAC;IAE3B,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;QACvB,KAAK,MAAM;YACV,IAAI,QAAQ,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;gBAChC,MAAM,IAAI,6BAAoB,CAC7B,2FAA2F,CAC3F,CAAC;YACH,CAAC;YACD,OAAO,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACxD,KAAK,UAAU;YACd,OAAO,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACzC,KAAK,SAAS;YACb,OAAO,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACvC,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,UAAU,GAAU,QAAQ,CAAC;YACnC,MAAM,IAAI,6BAAoB,CAC7B,0BAA0B,IAAI,CAAC,SAAS,CAAE,UAAuB,CAAC,IAAI,CAAC,EAAE,CACzE,CAAC;QACH,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/recurrence/validate.d.ts

@@ -0,0 +1,2 @@
+import type { Schedule } from '../types';
+export declare function validateSchedule(schedule: Schedule): void;

package/dist/recurrence/validate.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSchedule = validateSchedule;
+const cron_parser_1 = require("cron-parser");
+const luxon_1 = require("luxon");
+const errors_1 = require("../errors");
+const CRON_FIELD_COUNT = 6;
+function validateCron(schedule) {
+    const expression = schedule.cronExpression;
+    if (typeof expression !== 'string') {
+        throw new errors_1.InvalidScheduleError(`cron.cronExpression must be a string, got ${JSON.stringify(expression)}`);
+    }
+    const fieldCount = expression.trim().split(/\s+/).length;
+    if (fieldCount !== CRON_FIELD_COUNT) {
+        throw new errors_1.InvalidScheduleError(`Cron expression must have ${CRON_FIELD_COUNT} fields (seconds included), got ${fieldCount}: ${JSON.stringify(expression)}`);
+    }
+    if (schedule.timezone !== null && !luxon_1.IANAZone.isValidZone(schedule.timezone)) {
+        throw new errors_1.InvalidScheduleError(`Unknown IANA timezone: ${JSON.stringify(schedule.timezone)}`);
+    }
+    try {
+        cron_parser_1.CronExpressionParser.parse(expression, {
+            tz: schedule.timezone ?? 'UTC',
+        });
+    }
+    catch (error) {
+        throw new errors_1.InvalidScheduleError(`Invalid cron expression ${JSON.stringify(expression)}: ${error.message}`);
+    }
+}
+function validateInterval(schedule) {
+    if (!Number.isInteger(schedule.intervalSeconds) || schedule.intervalSeconds <= 0) {
+        throw new errors_1.InvalidScheduleError(`interval.intervalSeconds must be a positive integer, got ${JSON.stringify(schedule.intervalSeconds)}`);
+    }
+}
+function validateOneOff(schedule) {
+    const fireAt = schedule.fireAt;
+    if (!(fireAt instanceof Date) || Number.isNaN(fireAt.getTime())) {
+        throw new errors_1.InvalidScheduleError('one_off.fireAt must be a valid Date');
+    }
+}
+function validateSchedule(schedule) {
+    switch (schedule.kind) {
+        case 'cron':
+            return validateCron(schedule);
+        case 'interval':
+            return validateInterval(schedule);
+        case 'one_off':
+            return validateOneOff(schedule);
+        default: {
+            const exhaustive = schedule;
+            throw new errors_1.InvalidScheduleError(`Unknown schedule kind: ${JSON.stringify(exhaustive.kind)}`);
+        }
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/recurrence/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/recurrence/validate.ts"],"names":[],"mappings":";;AA8DA,4CAeC;AA7ED,6CAAmD;AACnD,iCAAiC;AAEjC,sCAAiD;AAIjD,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B,SAAS,YAAY,CAAC,QAAsB;IAG3C,MAAM,UAAU,GAAY,QAAQ,CAAC,cAAc,CAAC;IACpD,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,6BAAoB,CAC7B,6CAA6C,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CACzE,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;IACzD,IAAI,UAAU,KAAK,gBAAgB,EAAE,CAAC;QACrC,MAAM,IAAI,6BAAoB,CAC7B,6BAA6B,gBAAgB,mCAAmC,UAAU,KAAK,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAC3H,CAAC;IACH,CAAC;IAGD,IAAI,QAAQ,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,gBAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5E,MAAM,IAAI,6BAAoB,CAAC,0BAA0B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC/F,CAAC;IAED,IAAI,CAAC;QACJ,kCAAoB,CAAC,KAAK,CAAC,UAAU,EAAE;YACtC,EAAE,EAAE,QAAQ,CAAC,QAAQ,IAAI,KAAK;SAC9B,CAAC,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,6BAAoB,CAC7B,2BAA2B,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,KAAM,KAAe,CAAC,OAAO,EAAE,CACpF,CAAC;IACH,CAAC;AACF,CAAC;AAED,SAAS,gBAAgB,CAAC,QAA0B;IACnD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,QAAQ,CAAC,eAAe,IAAI,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,6BAAoB,CAC7B,4DAA4D,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CACtG,CAAC;IACH,CAAC;AACF,CAAC;AAED,SAAS,cAAc,CAAC,QAAwB;IAC/C,MAAM,MAAM,GAAY,QAAQ,CAAC,MAAM,CAAC;IACxC,IAAI,CAAC,CAAC,MAAM,YAAY,IAAI,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,6BAAoB,CAAC,qCAAqC,CAAC,CAAC;IACvE,CAAC;AACF,CAAC;AAOD,SAAgB,gBAAgB,CAAC,QAAkB;IAClD,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;QACvB,KAAK,MAAM;YACV,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC/B,KAAK,UAAU;YACd,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QACnC,KAAK,SAAS;YACb,OAAO,cAAc,CAAC,QAAQ,CAAC,CAAC;QACjC,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,UAAU,GAAU,QAAQ,CAAC;YACnC,MAAM,IAAI,6BAAoB,CAC7B,0BAA0B,IAAI,CAAC,SAAS,CAAE,UAAuB,CAAC,IAAI,CAAC,EAAE,CACzE,CAAC;QACH,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/storage/storage.d.ts

@@ -0,0 +1,6 @@
+import type { ScheduledJob, ScheduledTask } from '../types';
+export interface SchedulerStore {
+    getDueJobs(now: Date, limit: number): Promise<ScheduledJob[]>;
+    saveJob(job: ScheduledJob): Promise<void>;
+    createTask(task: ScheduledTask): Promise<void>;
+}

package/dist/storage/storage.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=storage.js.map

package/dist/storage/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/storage/storage.ts"],"names":[],"mappings":""}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schedule';
+export * from './task';

package/dist/types/index.js

@@ -0,0 +1,19 @@
+"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("./schedule"), exports);
+__exportStar(require("./task"), exports);
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,yCAAuB"}

package/dist/types/schedule.d.ts

@@ -0,0 +1,24 @@
+import type { CronExpression } from 'n8n-workflow';
+export declare const ScheduleKindList: readonly ["cron", "interval", "one_off"];
+export type ScheduleKind = (typeof ScheduleKindList)[number];
+export interface CronSchedule {
+    kind: 'cron';
+    cronExpression: CronExpression;
+    timezone: string | null;
+}
+export interface IntervalSchedule {
+    kind: 'interval';
+    intervalSeconds: number;
+}
+export interface OneOffSchedule {
+    kind: 'one_off';
+    fireAt: Date;
+}
+export type Schedule = CronSchedule | IntervalSchedule | OneOffSchedule;
+export interface ScheduledJob {
+    id: string;
+    schedule: Schedule;
+    enabled: boolean;
+    nextRunAt: Date | null;
+    lastFiredAt: Date | null;
+}

package/dist/types/schedule.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScheduleKindList = void 0;
+exports.ScheduleKindList = ['cron', 'interval', 'one_off'];
+//# sourceMappingURL=schedule.js.map

package/dist/types/schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.js","sourceRoot":"","sources":["../../src/types/schedule.ts"],"names":[],"mappings":";;;AAiBa,QAAA,gBAAgB,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAU,CAAC"}

package/dist/types/task.d.ts

@@ -0,0 +1,13 @@
+export declare const TaskStatusList: readonly ["pending", "running", "succeeded", "failed", "missed", "cancelled"];
+export type TaskStatus = (typeof TaskStatusList)[number];
+export interface ScheduledTask {
+    id: string;
+    jobId: string;
+    taskType: string;
+    payload: unknown;
+    scheduledFor: Date;
+    runAt: Date;
+    status: TaskStatus;
+    attempts: number;
+    maxAttempts: number;
+}

package/dist/types/task.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskStatusList = void 0;
+exports.TaskStatusList = [
+    'pending',
+    'running',
+    'succeeded',
+    'failed',
+    'missed',
+    'cancelled',
+];
+//# sourceMappingURL=task.js.map

package/dist/types/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/types/task.ts"],"names":[],"mappings":";;;AAaa,QAAA,cAAc,GAAG;IAC7B,SAAS;IACT,SAAS;IACT,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,WAAW;CACF,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@n8n/scheduler",
+  "version": "0.1.0",
+  "main": "dist/index.js",
+  "module": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "dependencies": {
+    "cron-parser": "5.6.1",
+    "luxon": "3.7.2",
+    "n8n-workflow": "2.29.0"
+  },
+  "devDependencies": {
+    "@types/luxon": "3.2.0",
+    "@vitest/coverage-v8": "4.1.9",
+    "vitest": "^4.1.9",
+    "vitest-mock-extended": "^3.1.0",
+    "@n8n/typescript-config": "1.7.0",
+    "@n8n/vitest-config": "1.16.0"
+  },
+  "license": "LicenseRef-n8n-sustainable-use",
+  "scripts": {
+    "clean": "rimraf dist .turbo",
+    "dev": "pnpm watch",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "build:unchecked": "tsc -p tsconfig.build.json --noCheck",
+    "format": "biome format --write .",
+    "format:check": "biome ci .",
+    "lint": "eslint . --quiet",
+    "lint:fix": "eslint . --fix",
+    "watch": "tsc -p tsconfig.build.json --watch",
+    "test": "vitest run --passWithNoTests",
+    "test:unit": "vitest run --passWithNoTests",
+    "test:dev": "vitest --silent=false"
+  }
+}