exisjs 0.7.5 → 0.7.7

package/dist/cron/manager.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineCron = exports.CronManager = void 0;
+exports.cron = cron;
+const job_1 = require("./job");
+const expressions_1 = require("./expressions");
+class CronManager {
+    constructor(app) {
+        this.jobs = new Map();
+        this.app = app;
+    }
+    /**
+     * Checks whether a cron job with the given name is registered.
+     */
+    has(name) {
+        return this.jobs.has(name);
+    }
+    /**
+     * Registers and optionally starts a scheduled background task or cron job.
+     *
+     * @param nameOrOptions Job name or configuration options
+     * @param schedule Optional cron schedule pattern if name is passed as first argument
+     * @param handler Optional execution handler if name is passed as first argument
+     * @param options Optional additional configuration options
+     * @returns Active `CronJob` instance
+     *
+     * @example
+     * ```ts
+     * app.cron.schedule({
+     *   name: 'nightly-backup',
+     *   schedule: '0 2 * * *',
+     *   timezone: 'UTC',
+     *   run: async ({ log }) => {
+     *     log.info('Running database backup')
+     *   }
+     * })
+     * ```
+     */
+    schedule(nameOrOptions, schedule, handler, options) {
+        let opts;
+        if (typeof nameOrOptions === 'string') {
+            opts = {
+                name: nameOrOptions,
+                schedule: schedule,
+                run: handler,
+                ...options,
+            };
+        }
+        else {
+            opts = nameOrOptions;
+        }
+        const job = new job_1.CronJob(opts, this.app);
+        if (this.jobs.has(job.name)) {
+            this.app.log?.warn({ job: job.name }, `[exis:cron] Overwriting existing cron job "${job.name}"`);
+            this.jobs.get(job.name)?.stop();
+        }
+        this.jobs.set(job.name, job);
+        return job;
+    }
+    /**
+     * Schedules a recurring task using fixed millisecond intervals.
+     */
+    interval(name, ms, handler, options) {
+        return this.schedule({
+            name,
+            interval: ms,
+            run: handler,
+            ...options,
+        });
+    }
+    /**
+     * Schedules a one-time delayed task.
+     */
+    timeout(name, ms, handler, options) {
+        return this.schedule({
+            name,
+            timeout: ms,
+            run: handler,
+            ...options,
+        });
+    }
+    /**
+     * Retrieves a registered cron job by its unique identifier.
+     */
+    getJob(name) {
+        return this.jobs.get(name);
+    }
+    /**
+     * Returns a snapshot map of all registered cron jobs and their execution statistics.
+     */
+    getJobs() {
+        return this.jobs;
+    }
+    /**
+     * Returns an array of statistics for all registered jobs (last run, failure count, execution duration).
+     */
+    getStats() {
+        return Array.from(this.jobs.values()).map((job) => job.getStats());
+    }
+    /**
+     * Starts all registered idle, paused, or stopped cron jobs.
+     */
+    startAll() {
+        for (const job of this.jobs.values()) {
+            job.start();
+        }
+    }
+    /**
+     * Pauses all registered active cron jobs.
+     */
+    pauseAll() {
+        for (const job of this.jobs.values()) {
+            job.pause();
+        }
+    }
+    /**
+     * Permanently stops all registered cron jobs.
+     */
+    stopAll() {
+        for (const job of this.jobs.values()) {
+            job.stop();
+        }
+    }
+    /**
+     * Triggers immediate manual execution of a specific cron job by name.
+     */
+    async trigger(name) {
+        const job = this.jobs.get(name);
+        if (!job) {
+            throw new Error(`[exis:cron] Job "${name}" not found`);
+        }
+        return job.trigger();
+    }
+    /**
+     * Gracefully waits for all in-flight cron job executions to finish before server shutdown.
+     */
+    async drain(timeoutMs = 5000) {
+        const drainPromises = Array.from(this.jobs.values()).map((job) => job.drain(timeoutMs));
+        await Promise.all(drainPromises);
+    }
+}
+exports.CronManager = CronManager;
+/**
+ * Declarative helper for creating scheduled background jobs and cron tasks.
+ *
+ * @param scheduleOrOptions Standard 5/6-field cron pattern (e.g. `'0 * * * *'`) or full `CronJobOptions`
+ * @param handler Execution function receiving `CronContext`
+ * @returns Functional cron definition ready for export
+ *
+ * @example
+ * ```ts
+ * // src/cron/cleanup.ts
+ * export default cron('0 0 * * *', async ({ log }) => {
+ *   log.info('Running nightly cleanup')
+ * })
+ * ```
+ */
+function cron(scheduleOrOptions, handler) {
+    let options;
+    if (typeof scheduleOrOptions === 'string') {
+        options = {
+            schedule: scheduleOrOptions,
+            run: handler,
+        };
+    }
+    else {
+        options = {
+            ...scheduleOrOptions,
+            run: handler || scheduleOrOptions.run || scheduleOrOptions.handle,
+        };
+    }
+    return {
+        __isExisCron: true,
+        options,
+        handler: options.run,
+    };
+}
+/**
+ * Schedules a cron job with human-readable English duration expressions.
+ *
+ * @param duration Natural language interval (e.g. `'5 minutes'`, `'1 hour'`, `'30 seconds'`, `'every weekday'`)
+ * @param handler Execution function receiving `CronContext`
+ * @param options Additional job options (retries, timezone, onError)
+ * @returns Functional cron definition
+ *
+ * @example
+ * ```ts
+ * export default cron.every('15 minutes', async ({ log }) => {
+ *   log.info('Heartbeat check')
+ * })
+ * ```
+ */
+cron.every = function (duration, handler, options = {}) {
+    return cron({
+        schedule: (0, expressions_1.every)(duration),
+        run: handler,
+        ...options,
+    });
+};
+/**
+ * Schedules a background task using millisecond fixed intervals with drift correction.
+ *
+ * @param ms Millisecond interval between executions
+ * @param handler Execution function receiving `CronContext`
+ * @param options Additional job options (retries, preventOverlap)
+ * @returns Functional cron definition
+ *
+ * @example
+ * ```ts
+ * export default cron.interval(60000, async ({ log }) => {
+ *   log.info('Running every 60 seconds')
+ * })
+ * ```
+ */
+cron.interval = function (ms, handler, options = {}) {
+    return cron({
+        interval: ms,
+        run: handler,
+        ...options,
+    });
+};
+/**
+ * Schedules a one-time background task to execute after a specified delay.
+ *
+ * @param ms Delay in milliseconds before execution
+ * @param handler Execution function receiving `CronContext`
+ * @param options Additional job options
+ * @returns Functional cron definition
+ *
+ * @example
+ * ```ts
+ * export default cron.timeout(5000, async ({ log }) => {
+ *   log.info('Executed once after 5s startup delay')
+ * })
+ * ```
+ */
+cron.timeout = function (ms, handler, options = {}) {
+    return cron({
+        timeout: ms,
+        run: handler,
+        ...options,
+    });
+};
+exports.defineCron = cron;
+//# sourceMappingURL=manager.js.map

package/dist/cron/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/cron/manager.ts"],"names":[],"mappings":";;;AAuMA,oBAuBC;AA7ND,+BAA+B;AAE/B,+CAAqC;AAErC,MAAa,WAAW;IAItB,YAAY,GAAa;QAHjB,SAAI,GAAG,IAAI,GAAG,EAAmB,CAAA;QAIvC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAA;IAChB,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,QAAQ,CACb,aAAsC,EACtC,QAAiB,EACjB,OAAmC,EACnC,OAAiC;QAEjC,IAAI,IAAoB,CAAA;QACxB,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;YACtC,IAAI,GAAG;gBACL,IAAI,EAAE,aAAa;gBACnB,QAAQ,EAAE,QAAS;gBACnB,GAAG,EAAE,OAAQ;gBACb,GAAG,OAAO;aACX,CAAA;QACH,CAAC;aAAM,CAAC;YACN,IAAI,GAAG,aAAa,CAAA;QACtB,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,aAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;QACvC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAChB,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,EACjB,8CAA8C,GAAG,CAAC,IAAI,GAAG,CAC1D,CAAA;YACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAA;QACjC,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QAC5B,OAAO,GAAG,CAAA;IACZ,CAAC;IAED;;OAEG;IACI,QAAQ,CACb,IAAY,EACZ,EAAU,EACV,OAAkC,EAClC,OAAiC;QAEjC,OAAO,IAAI,CAAC,QAAQ,CAAC;YACnB,IAAI;YACJ,QAAQ,EAAE,EAAE;YACZ,GAAG,EAAE,OAAO;YACZ,GAAG,OAAO;SACX,CAAC,CAAA;IACJ,CAAC;IAED;;OAEG;IACI,OAAO,CACZ,IAAY,EACZ,EAAU,EACV,OAAkC,EAClC,OAAiC;QAEjC,OAAO,IAAI,CAAC,QAAQ,CAAC;YACnB,IAAI;YACJ,OAAO,EAAE,EAAE;YACX,GAAG,EAAE,OAAO;YACZ,GAAG,OAAO;SACX,CAAC,CAAA;IACJ,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,IAAY;QACxB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC5B,CAAC;IAED;;OAEG;IACI,OAAO;QACZ,OAAO,IAAI,CAAC,IAAI,CAAA;IAClB,CAAC;IAED;;OAEG;IACI,QAAQ;QACb,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAA;IACpE,CAAC;IAED;;OAEG;IACI,QAAQ;QACb,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,GAAG,CAAC,KAAK,EAAE,CAAA;QACb,CAAC;IACH,CAAC;IAED;;OAEG;IACI,QAAQ;QACb,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,GAAG,CAAC,KAAK,EAAE,CAAA;QACb,CAAC;IACH,CAAC;IAED;;OAEG;IACI,OAAO;QACZ,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,GAAG,CAAC,IAAI,EAAE,CAAA;QACZ,CAAC;IACH,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,OAAO,CAAC,IAAY;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC/B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,aAAa,CAAC,CAAA;QACxD,CAAC;QACD,OAAO,GAAG,CAAC,OAAO,EAAE,CAAA;IACtB,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI;QACjC,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAC/D,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CACrB,CAAA;QACD,MAAM,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;IAClC,CAAC;CACF;AAxKD,kCAwKC;AAWD;;;;;;;;;;;;;;GAcG;AACH,SAAgB,IAAI,CAClB,iBAA0C,EAC1C,OAAmC;IAEnC,IAAI,OAAuB,CAAA;IAE3B,IAAI,OAAO,iBAAiB,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,GAAG;YACR,QAAQ,EAAE,iBAAiB;YAC3B,GAAG,EAAE,OAAO;SACb,CAAA;IACH,CAAC;SAAM,CAAC;QACN,OAAO,GAAG;YACR,GAAG,iBAAiB;YACpB,GAAG,EAAE,OAAO,IAAI,iBAAiB,CAAC,GAAG,IAAI,iBAAiB,CAAC,MAAM;SAClE,CAAA;IACH,CAAC;IAED,OAAO;QACL,YAAY,EAAE,IAAI;QAClB,OAAO;QACP,OAAO,EAAE,OAAO,CAAC,GAAG;KACrB,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,IAAI,CAAC,KAAK,GAAG,UACX,QAAgB,EAChB,OAAkC,EAClC,UAA+D,EAAE;IAEjE,OAAO,IAAI,CAAC;QACV,QAAQ,EAAE,IAAA,mBAAK,EAAC,QAAQ,CAAC;QACzB,GAAG,EAAE,OAAO;QACZ,GAAG,OAAO;KACX,CAAC,CAAA;AACJ,CAAC,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,IAAI,CAAC,QAAQ,GAAG,UACd,EAAU,EACV,OAAkC,EAClC,UAA+D,EAAE;IAEjE,OAAO,IAAI,CAAC;QACV,QAAQ,EAAE,EAAE;QACZ,GAAG,EAAE,OAAO;QACZ,GAAG,OAAO;KACX,CAAC,CAAA;AACJ,CAAC,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,IAAI,CAAC,OAAO,GAAG,UACb,EAAU,EACV,OAAkC,EAClC,UAA8D,EAAE;IAEhE,OAAO,IAAI,CAAC;QACV,OAAO,EAAE,EAAE;QACX,GAAG,EAAE,OAAO;QACZ,GAAG,OAAO;KACX,CAAC,CAAA;AACJ,CAAC,CAAA;AAEY,QAAA,UAAU,GAAG,IAAI,CAAA"}

package/dist/cron/parser.d.ts

@@ -0,0 +1,22 @@
+export interface ParsedCronPattern {
+    hasSeconds: boolean;
+    seconds: Set<number>;
+    minutes: Set<number>;
+    hours: Set<number>;
+    daysOfMonth: Set<number>;
+    months: Set<number>;
+    daysOfWeek: Set<number>;
+}
+/**
+ * Parses a 5 or 6 field cron expression into a structured pattern object.
+ */
+export declare function parseCronExpression(expression: string): ParsedCronPattern;
+/**
+ * Validates whether a cron expression is syntactically valid.
+ */
+export declare function isValidCron(expression: string): boolean;
+/**
+ * Calculates the next occurrence Date for a cron pattern from a base date.
+ */
+export declare function getNextCronDate(pattern: ParsedCronPattern | string, fromDate?: Date, timezone?: string): Date;
+//# sourceMappingURL=parser.d.ts.map

package/dist/cron/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/cron/parser.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,CAAA;IACnB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACpB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACpB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAClB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACnB,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CACxB;AA8ED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAkCzE;AAkFD;;GAEG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAOvD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,iBAAiB,GAAG,MAAM,EACnC,QAAQ,OAAa,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CAwDN"}

package/dist/cron/parser.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCronExpression = parseCronExpression;
+exports.isValidCron = isValidCron;
+exports.getNextCronDate = getNextCronDate;
+const MONTH_NAMES = {
+    jan: 1,
+    feb: 2,
+    mar: 3,
+    apr: 4,
+    may: 5,
+    jun: 6,
+    jul: 7,
+    aug: 8,
+    sep: 9,
+    oct: 10,
+    nov: 11,
+    dec: 12,
+};
+const DAY_NAMES = {
+    sun: 0,
+    mon: 1,
+    tue: 2,
+    wed: 3,
+    thu: 4,
+    fri: 5,
+    sat: 6,
+};
+const MACROS = {
+    '@yearly': '0 0 1 1 *',
+    '@annually': '0 0 1 1 *',
+    '@monthly': '0 0 1 * *',
+    '@weekly': '0 0 * * 0',
+    '@daily': '0 0 * * *',
+    '@midnight': '0 0 * * *',
+    '@hourly': '0 * * * *',
+};
+/**
+ * Parses a single cron field expression (e.g. `*`, `1,2,5`, `10-20`, `* /5`, `L`, `W`).
+ */
+function parseField(field, min, max, aliases) {
+    const result = new Set();
+    const str = field.trim().toLowerCase();
+    if (!str)
+        return result;
+    let normalized = str;
+    if (aliases) {
+        for (const [alias, val] of Object.entries(aliases)) {
+            normalized = normalized.replace(new RegExp(alias, 'g'), String(val));
+        }
+    }
+    const parts = normalized.split(',');
+    for (const part of parts) {
+        if (part === '*' || part === '?') {
+            for (let i = min; i <= max; i++)
+                result.add(i);
+        }
+        else if (part.includes('/')) {
+            const [rangeStr, stepStr] = part.split('/');
+            const step = parseInt(stepStr, 10);
+            if (isNaN(step) || step <= 0) {
+                throw new Error(`Invalid cron step: ${part}`);
+            }
+            let start = min;
+            let end = max;
+            if (rangeStr && rangeStr !== '*' && rangeStr !== '?') {
+                if (rangeStr.includes('-')) {
+                    const [s, e] = rangeStr.split('-').map((v) => parseInt(v, 10));
+                    start = isNaN(s) ? min : s;
+                    end = isNaN(e) ? max : e;
+                }
+                else {
+                    start = parseInt(rangeStr, 10);
+                }
+            }
+            for (let i = start; i <= end; i += step) {
+                if (i >= min && i <= max)
+                    result.add(i);
+            }
+        }
+        else if (part.includes('-')) {
+            const [sStr, eStr] = part.split('-');
+            const s = parseInt(sStr, 10);
+            const e = parseInt(eStr, 10);
+            if (isNaN(s) || isNaN(e) || s > e || s < min || e > max) {
+                throw new Error(`Invalid cron range: ${part} (min: ${min}, max: ${max})`);
+            }
+            for (let i = s; i <= e; i++)
+                result.add(i);
+        }
+        else {
+            const val = parseInt(part, 10);
+            if (isNaN(val) || val < min || val > max) {
+                if (min === 0 && max === 6 && val === 7) {
+                    result.add(0);
+                }
+                else {
+                    throw new Error(`Invalid cron value: ${part} (expected ${min}-${max})`);
+                }
+            }
+            else {
+                result.add(val);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Parses a 5 or 6 field cron expression into a structured pattern object.
+ */
+function parseCronExpression(expression) {
+    const trimmed = expression.trim();
+    const exp = MACROS[trimmed] || trimmed;
+    const tokens = exp.split(/\s+/).filter(Boolean);
+    if (tokens.length !== 5 && tokens.length !== 6) {
+        throw new Error(`Invalid cron expression "${expression}". Expected 5 or 6 fields, received ${tokens.length}.`);
+    }
+    const hasSeconds = tokens.length === 6;
+    let secStr = '0';
+    let minStr;
+    let hourStr;
+    let domStr;
+    let monthStr;
+    let dowStr;
+    if (hasSeconds) {
+        ;
+        [secStr, minStr, hourStr, domStr, monthStr, dowStr] = tokens;
+    }
+    else {
+        ;
+        [minStr, hourStr, domStr, monthStr, dowStr] = tokens;
+    }
+    return {
+        hasSeconds,
+        seconds: parseField(secStr, 0, 59),
+        minutes: parseField(minStr, 0, 59),
+        hours: parseField(hourStr, 0, 23),
+        daysOfMonth: parseField(domStr, 1, 31),
+        months: parseField(monthStr, 1, 12, MONTH_NAMES),
+        daysOfWeek: parseField(dowStr, 0, 6, DAY_NAMES),
+    };
+}
+const formatterCache = new Map();
+function getFormatter(timezone) {
+    if (!timezone || timezone.toUpperCase() === 'UTC')
+        return null;
+    let fmt = formatterCache.get(timezone);
+    if (!fmt) {
+        fmt = new Intl.DateTimeFormat('en-US', {
+            timeZone: timezone,
+            year: 'numeric',
+            month: 'numeric',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric',
+            second: 'numeric',
+            weekday: 'short',
+            hour12: false,
+        });
+        formatterCache.set(timezone, fmt);
+    }
+    return fmt;
+}
+const dayOfWeekMap = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+};
+/**
+ * Computes date parts in a given IANA timezone using cached formatter.
+ */
+function getDatePartsInTimezone(date, timezone) {
+    const formatter = getFormatter(timezone);
+    if (!formatter) {
+        return {
+            year: date.getUTCFullYear(),
+            month: date.getUTCMonth() + 1,
+            day: date.getUTCDate(),
+            hour: date.getUTCHours(),
+            minute: date.getUTCMinutes(),
+            second: date.getUTCSeconds(),
+            dayOfWeek: date.getUTCDay(),
+        };
+    }
+    const parts = formatter.formatToParts(date);
+    const map = {};
+    for (const part of parts) {
+        map[part.type] = part.value;
+    }
+    let hour = parseInt(map.hour, 10);
+    if (hour === 24)
+        hour = 0;
+    return {
+        year: parseInt(map.year, 10),
+        month: parseInt(map.month, 10),
+        day: parseInt(map.day, 10),
+        hour,
+        minute: parseInt(map.minute, 10),
+        second: parseInt(map.second, 10),
+        dayOfWeek: dayOfWeekMap[map.weekday] ?? date.getUTCDay(),
+    };
+}
+/**
+ * Validates whether a cron expression is syntactically valid.
+ */
+function isValidCron(expression) {
+    try {
+        parseCronExpression(expression);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Calculates the next occurrence Date for a cron pattern from a base date.
+ */
+function getNextCronDate(pattern, fromDate = new Date(), timezone) {
+    const parsed = typeof pattern === 'string' ? parseCronExpression(pattern) : pattern;
+    const current = new Date(fromDate.getTime());
+    if (parsed.hasSeconds) {
+        current.setUTCSeconds(current.getUTCSeconds() + 1, 0);
+    }
+    else {
+        current.setUTCSeconds(0, 0);
+        current.setUTCMinutes(current.getUTCMinutes() + 1);
+    }
+    const stepMs = parsed.hasSeconds ? 1000 : 60 * 1000;
+    const maxIterations = 5 * 365 * 24 * 60; // 5 years
+    for (let i = 0; i < maxIterations; i++) {
+        const parts = getDatePartsInTimezone(current, timezone);
+        if (!parsed.months.has(parts.month)) {
+            current.setTime(current.getTime() + 12 * 60 * 60 * 1000);
+            continue;
+        }
+        const domMatch = parsed.daysOfMonth.has(parts.day);
+        const dowMatch = parsed.daysOfWeek.has(parts.dayOfWeek);
+        if (!domMatch || !dowMatch) {
+            current.setTime(current.getTime() + 12 * 60 * 60 * 1000);
+            continue;
+        }
+        if (!parsed.hours.has(parts.hour)) {
+            current.setTime(current.getTime() + 60 * 60 * 1000);
+            // Align to start of hour in current timezone
+            const hourPart = getDatePartsInTimezone(current, timezone);
+            if (hourPart.minute !== 0) {
+                current.setTime(current.getTime() - hourPart.minute * 60 * 1000);
+            }
+            continue;
+        }
+        if (!parsed.minutes.has(parts.minute)) {
+            current.setTime(current.getTime() + stepMs);
+            continue;
+        }
+        if (parsed.hasSeconds) {
+            if (!parsed.seconds.has(parts.second)) {
+                current.setTime(current.getTime() + 1000);
+                continue;
+            }
+        }
+        return current;
+    }
+    throw new Error('Unable to find next cron execution within 5-year window');
+}
+//# sourceMappingURL=parser.js.map

package/dist/cron/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/cron/parser.ts"],"names":[],"mappings":"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"}

package/dist/cron/types.d.ts

@@ -0,0 +1,76 @@
+import type { App } from '../server/app';
+import type { Logger } from '../types';
+export type CronSchedule = string | Date | number;
+export type OverlapPolicy = 'skip' | 'queue';
+export type CronJobStatus = 'idle' | 'running' | 'paused' | 'stopped';
+export interface CronJobOptions {
+    /** Unique name for the cron job */
+    name?: string;
+    /** Cron pattern (e.g. '0 0 * * *' or '0 *\/5 * * * *') */
+    schedule?: string;
+    /** Interval in milliseconds */
+    interval?: number;
+    /** Timeout delay in milliseconds (runs once) */
+    timeout?: number;
+    /** IANA Timezone string (e.g. 'UTC', 'America/New_York', 'Asia/Kolkata') */
+    timezone?: string;
+    /**
+     * If true, prevents concurrent executions if the job takes longer than its interval.
+     * Default: true
+     */
+    preventOverlap?: boolean;
+    /** Action to take when an execution overlaps ('skip' to drop, 'queue' to run immediately after) */
+    onOverlap?: OverlapPolicy;
+    /** Whether the job starts running automatically upon registration. Default: true */
+    autoStart?: boolean;
+    /** Number of retry attempts if the handler throws an error */
+    retries?: number;
+    /** Backoff strategy between retries in milliseconds */
+    retryDelayMs?: number;
+    /** Optional error hook specific to this job */
+    onError?: (err: Error, context: CronContext) => void | Promise<void>;
+    /** Handler function for the cron job */
+    run?: (context: CronContext) => any | Promise<any>;
+    /** Alternative handler key name */
+    handle?: (context: CronContext) => any | Promise<any>;
+}
+export interface CronContext {
+    /** The Exis application instance */
+    app: App<any>;
+    /** Structured logger */
+    log: Logger;
+    /** Name of the running job */
+    jobName: string;
+    /** Timestamp when this execution started */
+    startedAt: Date;
+    /** Current execution iteration count */
+    iteration: number;
+    /** Signal that aborts when the server initiates graceful shutdown */
+    signal?: AbortSignal;
+}
+export interface CronJobStats {
+    name: string;
+    status: CronJobStatus;
+    schedule?: string;
+    intervalMs?: number;
+    timezone?: string;
+    preventOverlap: boolean;
+    lastRun?: Date;
+    nextRun?: Date;
+    executionCount: number;
+    failureCount: number;
+    lastDurationMs?: number;
+    lastError?: string;
+}
+export interface IntervalOptions {
+    name?: string;
+    preventOverlap?: boolean;
+    autoStart?: boolean;
+    onError?: (err: Error, context: CronContext) => void | Promise<void>;
+}
+export interface TimeoutOptions {
+    name?: string;
+    autoStart?: boolean;
+    onError?: (err: Error, context: CronContext) => void | Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cron/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cron/types.ts"],"names":[],"mappings":"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"}

package/dist/cron/types.js

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

package/dist/cron/types.js.map

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

package/dist/decorators/constants.d.ts

@@ -9,6 +9,8 @@ export declare const PARAM_METADATA: unique symbol;
 export declare const SERVER_CONFIG: unique symbol;
 export declare const BOUNDARY_CONFIG: unique symbol;
 export declare const MODULE_METADATA: unique symbol;
+export declare const CRON_REGISTRY: unique symbol;
+export declare const CRON_META: unique symbol;
 export declare const ROUTE_META: unique symbol;
 export declare const METHOD_MIDDLEWARES: unique symbol;
 export declare const ROUTE_METADATA_PROP: unique symbol;

package/dist/decorators/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/decorators/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAGvD,eAAO,MAAM,cAAc,eAA8B,CAAA;AACzD,eAAO,MAAM,iBAAiB,eAAyC,CAAA;AACvE,eAAO,MAAM,eAAe,eAAuC,CAAA;AACnE,eAAO,MAAM,mBAAmB,eAAmC,CAAA;AACnE,eAAO,MAAM,cAAc,eAAsC,CAAA;AACjE,eAAO,MAAM,kBAAkB,eAA0C,CAAA;AACzE,eAAO,MAAM,cAAc,eAAsC,CAAA;AACjE,eAAO,MAAM,aAAa,eAAqC,CAAA;AAC/D,eAAO,MAAM,eAAe,eAAuC,CAAA;AACnE,eAAO,MAAM,eAAe,eAAuC,CAAA;AAEnE,eAAO,MAAM,UAAU,eAAkC,CAAA;AACzD,eAAO,MAAM,kBAAkB,eAA0C,CAAA;AACzE,eAAO,MAAM,mBAAmB,eAA2C,CAAA;AAC3E,eAAO,MAAM,uBAAuB,eAEnC,CAAA;AACD,eAAO,MAAM,mBAAmB,eAA2C,CAAA;AAE3E,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;IACxC,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;IACf,SAAS,CAAC,EAAE,GAAG,EAAE,CAAA;IACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;IACZ,KAAK,CAAC,EAAE,GAAG,EAAE,CAAA;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;IACf,UAAU,CAAC,EAAE,GAAG,EAAE,CAAA;IAClB,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;IACf,MAAM,CAAC,EAAE,GAAG,EAAE,CAAA;IACd,YAAY,CAAC,EAAE,GAAG,EAAE,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC,CAAA;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC9B,IAAI,CAAC,EAAE,GAAG,CAAA;IACV,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;IACf,SAAS,CAAC,EAAE,GAAG,EAAE,CAAA;IACjB,YAAY,CAAC,EAAE,GAAG,CAAA;IAClB,WAAW,CAAC,EAAE,GAAG,CAAA;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;IACf,WAAW,CAAC,EAAE,GAAG,EAAE,CAAA;IACnB,SAAS,CAAC,EAAE,GAAG,EAAE,CAAA;IACjB,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;CAChB"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/decorators/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAGvD,eAAO,MAAM,cAAc,eAA8B,CAAA;AACzD,eAAO,MAAM,iBAAiB,eAAyC,CAAA;AACvE,eAAO,MAAM,eAAe,eAAuC,CAAA;AACnE,eAAO,MAAM,mBAAmB,eAAmC,CAAA;AACnE,eAAO,MAAM,cAAc,eAAsC,CAAA;AACjE,eAAO,MAAM,kBAAkB,eAA0C,CAAA;AACzE,eAAO,MAAM,cAAc,eAAsC,CAAA;AACjE,eAAO,MAAM,aAAa,eAAqC,CAAA;AAC/D,eAAO,MAAM,eAAe,eAAuC,CAAA;AACnE,eAAO,MAAM,eAAe,eAAuC,CAAA;AACnE,eAAO,MAAM,aAAa,eAAiC,CAAA;AAC3D,eAAO,MAAM,SAAS,eAAiC,CAAA;AAEvD,eAAO,MAAM,UAAU,eAAkC,CAAA;AACzD,eAAO,MAAM,kBAAkB,eAA0C,CAAA;AACzE,eAAO,MAAM,mBAAmB,eAA2C,CAAA;AAC3E,eAAO,MAAM,uBAAuB,eAEnC,CAAA;AACD,eAAO,MAAM,mBAAmB,eAA2C,CAAA;AAE3E,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;IACxC,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;IACf,SAAS,CAAC,EAAE,GAAG,EAAE,CAAA;IACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;IACZ,KAAK,CAAC,EAAE,GAAG,EAAE,CAAA;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;IACf,UAAU,CAAC,EAAE,GAAG,EAAE,CAAA;IAClB,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;IACf,MAAM,CAAC,EAAE,GAAG,EAAE,CAAA;IACd,YAAY,CAAC,EAAE,GAAG,EAAE,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC,CAAA;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC9B,IAAI,CAAC,EAAE,GAAG,CAAA;IACV,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;IACf,SAAS,CAAC,EAAE,GAAG,EAAE,CAAA;IACjB,YAAY,CAAC,EAAE,GAAG,CAAA;IAClB,WAAW,CAAC,EAAE,GAAG,CAAA;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;IACf,WAAW,CAAC,EAAE,GAAG,EAAE,CAAA;IACnB,SAAS,CAAC,EAAE,GAAG,EAAE,CAAA;IACjB,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;CAChB"}