ai-workflows 2.1.1 → 2.3.0

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AASvC;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAsB;IAC1D,MAAM,aAAa,GAAkB;QACnC,OAAO,EAAE,EAAE;QACX,OAAO,EAAE,EAAE;KACZ,CAAA;IAED,MAAM,UAAU,GAAG,CAAC,KAA8C,EAAE,EAAE;QACpE,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC;YACzB,GAAG,KAAK;YACR,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,yFAAyF;IACzF,MAAM,WAAW,GAAG,IAAI,KAAK,CAAC,EAAa,EAAE;QAC3C,GAAG;YACD,OAAO,IAAI,KAAK,CACd,EAAE,EACF;gBACE,GAAG;oBACD,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;gBACjB,CAAC;aACF,CACF,CAAA;QACH,CAAC;KACF,CAAC,CAAA;IAEF,4FAA4F;IAC5F,MAAM,cAAc,GAAG,IAAI,KAAK;IAC9B,6DAA6D;IAC7D,CAAC,CAAC,YAAoB,EAAE,QAAyB,EAAE,EAAE,GAAE,CAAC,CAAqB,EAC7E;QACE,GAAG;YACD,OAAO,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC,CAAA;QACvB,CAAC;QACD,KAAK,KAAI,CAAC;KACX,CACY,CAAA;IAEf,OAAO;QACL,KAAK,CAAC,KAAa,EAAE,IAAa;YAChC,mCAAmC;YACnC,IAAI,CAAC;gBACH,UAAU,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;gBAC3D,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;YAC5C,CAAC;YAAC,MAAM,CAAC;gBACP,0BAA0B;YAC5B,CAAC;QACH,CAAC;QAED,IAAI,CAAc,KAAa,EAAE,IAAO;YACtC,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,EAAE,CAAA;YACnC,UAAU,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YAChD,iEAAiE;YACjE,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,GAAI,IAAe,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;gBAC7E,SAAS,EAAE,CAAC,KAAK,CAAC,mCAAmC,KAAK,GAAG,EAAE,GAAG,CAAC,CAAA;YACrE,CAAC,CAAC,CAAA;YACF,OAAO,OAAO,CAAA;QAChB,CAAC;QAED,KAAK,CAAC,EAAE,CAAqC,MAAc,EAAE,KAAY;YACvE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;QACvD,CAAC;QAED,KAAK,CAAC,GAAG,CAAqC,MAAc,EAAE,KAAY;YACxE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAA;QACxD,CAAC;QAED,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,cAAc;QAErB,KAAK,EAAE,aAAa,CAAC,OAAO;QAE5B,QAAQ;YACN,yCAAyC;YACzC,OAAO;gBACL,GAAG,CAAC,aAAa,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,OAAO,EAAE,CAAC;gBAC9E,OAAO,EAAE,EAAE,GAAG,aAAa,CAAC,OAAO,EAAE;gBACrC,OAAO,EAAE,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC;aACpC,CAAA;QACH,CAAC;QAED,GAAG,CAAc,GAAW,EAAE,KAAQ;YACpC,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;QACpC,CAAC;QAED,GAAG,CAAc,GAAW;YAC1B,OAAO,aAAa,CAAC,OAAO,CAAC,GAAG,CAAkB,CAAA;QACpD,CAAC;QAED,GAAG,CAAC,OAAe,EAAE,IAAc;YACjC,UAAU,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;YACpE,SAAS,EAAE,CAAC,GAAG,CAAC,cAAc,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,CAAA;QACtD,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IAGnC,MAAM,aAAa,GAA4C,EAAE,CAAA;IAEjE,MAAM,GAAG,GAAG,qBAAqB,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,IAAa;YACrC,aAAa,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QACrC,CAAC;KACF,CAAC,CAAA;IAEF,OAAO;QACL,GAAG,GAAG;QACN,gBAAgB,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,aAAa,CAAC;KAC3C,CAAA;AACH,CAAC"}

package/dist/cron-parser.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Cron Expression Parser
+ *
+ * Parses standard 5-field cron expressions:
+ *   minute hour day-of-month month day-of-week
+ *
+ * Also supports optional 6-field expressions with seconds:
+ *   second minute hour day-of-month month day-of-week
+ *
+ * Supported syntax:
+ *   - Numbers: 0, 5, 15
+ *   - Ranges: 1-5, 9-17
+ *   - Lists: 1,3,5, Mon,Wed,Fri
+ *   - Steps: star/5, 0-30/5
+ *   - Wildcards: star (asterisk)
+ *   - Day names: Mon, Tue, Wed, Thu, Fri, Sat, Sun
+ *   - Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
+ */
+/**
+ * Parsed cron expression
+ */
+export interface ParsedCron {
+    /** Seconds (0-59) - optional, defaults to [0] */
+    seconds: number[];
+    /** Minutes (0-59) */
+    minutes: number[];
+    /** Hours (0-23) */
+    hours: number[];
+    /** Days of month (1-31) */
+    daysOfMonth: number[];
+    /** Months (1-12) */
+    months: number[];
+    /** Days of week (0-6, Sunday = 0) */
+    daysOfWeek: number[];
+    /** Whether day of month is a wildcard */
+    dayOfMonthWildcard: boolean;
+    /** Whether day of week is a wildcard */
+    dayOfWeekWildcard: boolean;
+}
+/**
+ * Parse a cron expression
+ *
+ * @param expression - Cron expression (5 or 6 fields)
+ * @returns ParsedCron object
+ * @throws Error if expression is invalid
+ */
+export declare function parseCron(expression: string): ParsedCron;
+/**
+ * Check if a date matches a parsed cron expression
+ */
+export declare function matchesCron(date: Date, cron: ParsedCron): boolean;
+/**
+ * Find the next date that matches a cron expression
+ *
+ * @param cron - Parsed cron expression
+ * @param from - Start date (defaults to now)
+ * @param maxIterations - Maximum iterations to prevent infinite loops
+ * @returns Next matching Date or null if not found within iterations
+ */
+export declare function getNextCronDate(cron: ParsedCron, from?: Date, maxIterations?: number): Date | null;
+/**
+ * Calculate milliseconds until the next cron occurrence
+ */
+export declare function getNextCronMs(cron: ParsedCron, from?: Date): number | null;
+//# sourceMappingURL=cron-parser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cron-parser.d.ts","sourceRoot":"","sources":["../src/cron-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,qBAAqB;IACrB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,mBAAmB;IACnB,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,2BAA2B;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,oBAAoB;IACpB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,qCAAqC;IACrC,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,yCAAyC;IACzC,kBAAkB,EAAE,OAAO,CAAA;IAC3B,wCAAwC;IACxC,iBAAiB,EAAE,OAAO,CAAA;CAC3B;AAwGD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CA4BxD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAkCjE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,IAAI,GAAE,IAAiB,EACvB,aAAa,GAAE,MAAsB,GACpC,IAAI,GAAG,IAAI,CA8Fb;AAcD;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAItF"}

package/dist/cron-parser.js

@@ -0,0 +1,294 @@
+/**
+ * Cron Expression Parser
+ *
+ * Parses standard 5-field cron expressions:
+ *   minute hour day-of-month month day-of-week
+ *
+ * Also supports optional 6-field expressions with seconds:
+ *   second minute hour day-of-month month day-of-week
+ *
+ * Supported syntax:
+ *   - Numbers: 0, 5, 15
+ *   - Ranges: 1-5, 9-17
+ *   - Lists: 1,3,5, Mon,Wed,Fri
+ *   - Steps: star/5, 0-30/5
+ *   - Wildcards: star (asterisk)
+ *   - Day names: Mon, Tue, Wed, Thu, Fri, Sat, Sun
+ *   - Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
+ */
+/**
+ * Day name to number mapping (Sunday = 0)
+ */
+const DAY_NAMES = {
+    sun: 0,
+    mon: 1,
+    tue: 2,
+    wed: 3,
+    thu: 4,
+    fri: 5,
+    sat: 6,
+};
+/**
+ * Month name to number mapping (January = 1)
+ */
+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,
+};
+/**
+ * Parse a single cron field value
+ */
+function parseFieldValue(value, min, max, names) {
+    // Check for named value (e.g., Mon, Jan)
+    if (names) {
+        const lower = value.toLowerCase();
+        if (lower in names) {
+            return names[lower];
+        }
+    }
+    const num = parseInt(value, 10);
+    if (isNaN(num) || num < min || num > max) {
+        throw new Error(`Invalid cron field value: ${value} (expected ${min}-${max})`);
+    }
+    return num;
+}
+/**
+ * Parse a single cron field
+ * Examples: "0", "*", "1-5", "* /15" (no space), "1,3,5"
+ */
+function parseField(field, min, max, names) {
+    const values = new Set();
+    // Split by comma for lists
+    const parts = field.split(',');
+    for (const part of parts) {
+        // Check for step (e.g., */5 or 0-30/5)
+        const stepMatch = part.match(/^(.+)\/(\d+)$/);
+        const step = stepMatch ? parseInt(stepMatch[2], 10) : 1;
+        const range = stepMatch ? stepMatch[1] : part;
+        let start;
+        let end;
+        if (range === '*') {
+            start = min;
+            end = max;
+        }
+        else if (range.includes('-')) {
+            // Range (e.g., 1-5)
+            const [rangeStart, rangeEnd] = range.split('-');
+            start = parseFieldValue(rangeStart, min, max, names);
+            end = parseFieldValue(rangeEnd, min, max, names);
+        }
+        else {
+            // Single value
+            start = parseFieldValue(range, min, max, names);
+            end = start;
+        }
+        // Generate values with step
+        for (let i = start; i <= end; i += step) {
+            values.add(i);
+        }
+    }
+    return Array.from(values).sort((a, b) => a - b);
+}
+/**
+ * Parse a cron expression
+ *
+ * @param expression - Cron expression (5 or 6 fields)
+ * @returns ParsedCron object
+ * @throws Error if expression is invalid
+ */
+export function parseCron(expression) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length < 5 || fields.length > 6) {
+        throw new Error(`Invalid cron expression: expected 5 or 6 fields, got ${fields.length}`);
+    }
+    // Determine if we have seconds field
+    const hasSeconds = fields.length === 6;
+    const offset = hasSeconds ? 0 : -1;
+    const secondsField = hasSeconds ? fields[0] : '0';
+    const minutesField = fields[offset + 1];
+    const hoursField = fields[offset + 2];
+    const daysOfMonthField = fields[offset + 3];
+    const monthsField = fields[offset + 4];
+    const daysOfWeekField = fields[offset + 5];
+    return {
+        seconds: parseField(secondsField, 0, 59),
+        minutes: parseField(minutesField, 0, 59),
+        hours: parseField(hoursField, 0, 23),
+        daysOfMonth: parseField(daysOfMonthField, 1, 31),
+        months: parseField(monthsField, 1, 12, MONTH_NAMES),
+        daysOfWeek: parseField(daysOfWeekField, 0, 6, DAY_NAMES),
+        dayOfMonthWildcard: daysOfMonthField === '*',
+        dayOfWeekWildcard: daysOfWeekField === '*',
+    };
+}
+/**
+ * Check if a date matches a parsed cron expression
+ */
+export function matchesCron(date, cron) {
+    const second = date.getSeconds();
+    const minute = date.getMinutes();
+    const hour = date.getHours();
+    const dayOfMonth = date.getDate();
+    const month = date.getMonth() + 1; // JavaScript months are 0-indexed
+    const dayOfWeek = date.getDay();
+    // Check basic fields
+    if (!cron.seconds.includes(second))
+        return false;
+    if (!cron.minutes.includes(minute))
+        return false;
+    if (!cron.hours.includes(hour))
+        return false;
+    if (!cron.months.includes(month))
+        return false;
+    // Handle day matching (special cron semantics)
+    // If both day-of-month and day-of-week are specified (not wildcards),
+    // either one matching is sufficient (OR logic)
+    // If only one is specified, that one must match
+    const domMatches = cron.daysOfMonth.includes(dayOfMonth);
+    const dowMatches = cron.daysOfWeek.includes(dayOfWeek);
+    if (cron.dayOfMonthWildcard && cron.dayOfWeekWildcard) {
+        // Both wildcards - any day matches
+        return true;
+    }
+    else if (cron.dayOfMonthWildcard) {
+        // Only day-of-week specified
+        return dowMatches;
+    }
+    else if (cron.dayOfWeekWildcard) {
+        // Only day-of-month specified
+        return domMatches;
+    }
+    else {
+        // Both specified - OR logic (standard cron behavior)
+        return domMatches || dowMatches;
+    }
+}
+/**
+ * Find the next date that matches a cron expression
+ *
+ * @param cron - Parsed cron expression
+ * @param from - Start date (defaults to now)
+ * @param maxIterations - Maximum iterations to prevent infinite loops
+ * @returns Next matching Date or null if not found within iterations
+ */
+export function getNextCronDate(cron, from = new Date(), maxIterations = 366 * 24 * 60 // ~1 year of minutes
+) {
+    // Start from the next second
+    const next = new Date(from.getTime());
+    next.setMilliseconds(0);
+    next.setSeconds(next.getSeconds() + 1);
+    let iterations = 0;
+    while (iterations < maxIterations) {
+        iterations++;
+        // Check if current time matches
+        if (matchesCron(next, cron)) {
+            return next;
+        }
+        // Advance to next possible match
+        // Start by advancing the smallest unit that doesn't match
+        // Check seconds
+        if (!cron.seconds.includes(next.getSeconds())) {
+            const nextSecond = findNextValue(next.getSeconds(), cron.seconds);
+            if (nextSecond !== null) {
+                next.setSeconds(nextSecond);
+            }
+            else {
+                // Roll over to next minute
+                next.setSeconds(cron.seconds[0]);
+                next.setMinutes(next.getMinutes() + 1);
+            }
+            continue;
+        }
+        // Check minutes
+        if (!cron.minutes.includes(next.getMinutes())) {
+            const nextMinute = findNextValue(next.getMinutes(), cron.minutes);
+            if (nextMinute !== null) {
+                next.setMinutes(nextMinute);
+                next.setSeconds(cron.seconds[0]);
+            }
+            else {
+                // Roll over to next hour
+                next.setMinutes(cron.minutes[0]);
+                next.setSeconds(cron.seconds[0]);
+                next.setHours(next.getHours() + 1);
+            }
+            continue;
+        }
+        // Check hours
+        if (!cron.hours.includes(next.getHours())) {
+            const nextHour = findNextValue(next.getHours(), cron.hours);
+            if (nextHour !== null) {
+                next.setHours(nextHour);
+                next.setMinutes(cron.minutes[0]);
+                next.setSeconds(cron.seconds[0]);
+            }
+            else {
+                // Roll over to next day
+                next.setHours(cron.hours[0]);
+                next.setMinutes(cron.minutes[0]);
+                next.setSeconds(cron.seconds[0]);
+                next.setDate(next.getDate() + 1);
+            }
+            continue;
+        }
+        // Check month
+        if (!cron.months.includes(next.getMonth() + 1)) {
+            const nextMonth = findNextValue(next.getMonth() + 1, cron.months);
+            if (nextMonth !== null) {
+                next.setMonth(nextMonth - 1);
+                next.setDate(1);
+                next.setHours(cron.hours[0]);
+                next.setMinutes(cron.minutes[0]);
+                next.setSeconds(cron.seconds[0]);
+            }
+            else {
+                // Roll over to next year
+                next.setFullYear(next.getFullYear() + 1);
+                next.setMonth(cron.months[0] - 1);
+                next.setDate(1);
+                next.setHours(cron.hours[0]);
+                next.setMinutes(cron.minutes[0]);
+                next.setSeconds(cron.seconds[0]);
+            }
+            continue;
+        }
+        // Day checks are complex due to OR semantics
+        // Just advance by one day and re-check
+        next.setDate(next.getDate() + 1);
+        next.setHours(cron.hours[0]);
+        next.setMinutes(cron.minutes[0]);
+        next.setSeconds(cron.seconds[0]);
+    }
+    return null;
+}
+/**
+ * Find the next value in a sorted array that is greater than the current value
+ */
+function findNextValue(current, values) {
+    for (const value of values) {
+        if (value > current) {
+            return value;
+        }
+    }
+    return null;
+}
+/**
+ * Calculate milliseconds until the next cron occurrence
+ */
+export function getNextCronMs(cron, from = new Date()) {
+    const next = getNextCronDate(cron, from);
+    if (!next)
+        return null;
+    return next.getTime() - from.getTime();
+}
+//# sourceMappingURL=cron-parser.js.map

package/dist/cron-parser.js.map

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

package/dist/cron-scheduler.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Cron Scheduler
+ *
+ * Provides scheduling functionality for cron expressions using accurate
+ * time-based scheduling rather than polling.
+ *
+ * Uses a self-adjusting timer approach:
+ * 1. Calculate time until next cron occurrence
+ * 2. Set a timeout for that duration
+ * 3. Execute handler and schedule next occurrence
+ *
+ * This is more accurate and efficient than setInterval polling.
+ */
+import { type ParsedCron } from './cron-parser.js';
+/**
+ * Scheduled job handle
+ */
+export interface CronJob {
+    /** Unique job ID */
+    id: string;
+    /** Original cron expression */
+    expression: string;
+    /** Parsed cron data */
+    cron: ParsedCron;
+    /** Handler function */
+    handler: () => void | Promise<void>;
+    /** Current timer reference */
+    timer: NodeJS.Timeout | null;
+    /** Next scheduled run time */
+    nextRun: Date | null;
+    /** Whether the job is running */
+    running: boolean;
+    /** Whether the job is stopped */
+    stopped: boolean;
+    /** Error handler */
+    onError?: (error: Error) => void;
+}
+/**
+ * Create a cron job
+ *
+ * @param expression - Cron expression (5 or 6 fields)
+ * @param handler - Function to execute on each occurrence
+ * @param options - Optional configuration
+ * @returns CronJob handle for managing the job
+ *
+ * @example
+ * ```ts
+ * // Run every hour at minute 0
+ * const job = createCronJob('0 * * * *', () => {
+ *   console.log('Hourly task')
+ * })
+ *
+ * // Run Monday at 9am
+ * const monday9am = createCronJob('0 9 * * 1', async () => {
+ *   await sendReport()
+ * })
+ *
+ * // Stop the job
+ * job.stop()
+ * ```
+ */
+export declare function createCronJob(expression: string, handler: () => void | Promise<void>, options?: {
+    id?: string;
+    onError?: (error: Error) => void;
+    startImmediately?: boolean;
+}): CronJob;
+/**
+ * Stop a cron job
+ */
+export declare function stopCronJob(job: CronJob): void;
+/**
+ * Start a stopped cron job
+ */
+export declare function startCronJob(job: CronJob): void;
+/**
+ * Get all active cron jobs
+ */
+export declare function getActiveCronJobs(): CronJob[];
+/**
+ * Stop all active cron jobs
+ */
+export declare function stopAllCronJobs(): void;
+/**
+ * Get the count of active cron jobs
+ */
+export declare function getActiveCronJobCount(): number;
+/**
+ * Cron job registry object for external access
+ */
+export declare const cronJobRegistry: {
+    create: typeof createCronJob;
+    stop: typeof stopCronJob;
+    start: typeof startCronJob;
+    getActive: typeof getActiveCronJobs;
+    getActiveCount: typeof getActiveCronJobCount;
+    stopAll: typeof stopAllCronJobs;
+};
+/**
+ * Schedule type for cron-based intervals
+ * Used to convert schedule intervals to cron jobs
+ */
+export interface CronScheduleOptions {
+    /** Unique identifier for the schedule */
+    id?: string;
+    /** Error handler */
+    onError?: (error: Error) => void;
+}
+/**
+ * Create a schedule from a cron expression or well-known pattern
+ *
+ * @param expression - Cron expression or known pattern name
+ * @param handler - Function to execute
+ * @param options - Optional configuration
+ * @returns CronJob handle
+ */
+export declare function schedule(expression: string, handler: () => void | Promise<void>, options?: CronScheduleOptions): CronJob;
+//# sourceMappingURL=cron-scheduler.d.ts.map

package/dist/cron-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron-scheduler.d.ts","sourceRoot":"","sources":["../src/cron-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAA8B,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAG9E;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,oBAAoB;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,uBAAuB;IACvB,IAAI,EAAE,UAAU,CAAA;IAChB,uBAAuB;IACvB,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;IAC5B,8BAA8B;IAC9B,OAAO,EAAE,IAAI,GAAG,IAAI,CAAA;IACpB,iCAAiC;IACjC,OAAO,EAAE,OAAO,CAAA;IAChB,iCAAiC;IACjC,OAAO,EAAE,OAAO,CAAA;IAChB,oBAAoB;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;CACjC;AAYD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EACnC,OAAO,GAAE;IACP,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAChC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CACtB,GACL,OAAO,CAwBT;AA6CD;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAQ9C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAI/C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,EAAE,CAE7C;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAItC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;CAO3B,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,oBAAoB;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EACnC,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAMT"}

package/dist/cron-scheduler.js

@@ -0,0 +1,176 @@
+/**
+ * Cron Scheduler
+ *
+ * Provides scheduling functionality for cron expressions using accurate
+ * time-based scheduling rather than polling.
+ *
+ * Uses a self-adjusting timer approach:
+ * 1. Calculate time until next cron occurrence
+ * 2. Set a timeout for that duration
+ * 3. Execute handler and schedule next occurrence
+ *
+ * This is more accurate and efficient than setInterval polling.
+ */
+import { parseCron, getNextCronDate } from './cron-parser.js';
+import { getLogger } from './logger.js';
+/**
+ * Job counter for unique IDs
+ */
+let jobCounter = 0;
+/**
+ * Active cron jobs
+ */
+const activeJobs = new Map();
+/**
+ * Create a cron job
+ *
+ * @param expression - Cron expression (5 or 6 fields)
+ * @param handler - Function to execute on each occurrence
+ * @param options - Optional configuration
+ * @returns CronJob handle for managing the job
+ *
+ * @example
+ * ```ts
+ * // Run every hour at minute 0
+ * const job = createCronJob('0 * * * *', () => {
+ *   console.log('Hourly task')
+ * })
+ *
+ * // Run Monday at 9am
+ * const monday9am = createCronJob('0 9 * * 1', async () => {
+ *   await sendReport()
+ * })
+ *
+ * // Stop the job
+ * job.stop()
+ * ```
+ */
+export function createCronJob(expression, handler, options = {}) {
+    const cron = parseCron(expression);
+    const id = options.id ?? `cron-job-${++jobCounter}`;
+    const job = {
+        id,
+        expression,
+        cron,
+        handler,
+        timer: null,
+        nextRun: null,
+        running: false,
+        stopped: false,
+        ...(options.onError !== undefined && { onError: options.onError }),
+    };
+    activeJobs.set(id, job);
+    // Start immediately by default
+    if (options.startImmediately !== false) {
+        scheduleNext(job);
+    }
+    return job;
+}
+/**
+ * Schedule the next execution of a cron job
+ */
+function scheduleNext(job) {
+    if (job.stopped)
+        return;
+    const now = new Date();
+    const nextRun = getNextCronDate(job.cron, now);
+    if (!nextRun) {
+        getLogger().warn(`[cron] Could not calculate next run for job ${job.id}`);
+        return;
+    }
+    job.nextRun = nextRun;
+    const delay = nextRun.getTime() - now.getTime();
+    // Clear any existing timer
+    if (job.timer) {
+        clearTimeout(job.timer);
+    }
+    // Schedule next execution
+    job.timer = setTimeout(async () => {
+        if (job.stopped)
+            return;
+        job.running = true;
+        try {
+            await job.handler();
+        }
+        catch (error) {
+            if (job.onError) {
+                job.onError(error instanceof Error ? error : new Error(String(error)));
+            }
+            else {
+                getLogger().error(`[cron] Error in job ${job.id}:`, error);
+            }
+        }
+        finally {
+            job.running = false;
+            // Schedule next occurrence
+            scheduleNext(job);
+        }
+    }, delay);
+}
+/**
+ * Stop a cron job
+ */
+export function stopCronJob(job) {
+    job.stopped = true;
+    if (job.timer) {
+        clearTimeout(job.timer);
+        job.timer = null;
+    }
+    job.nextRun = null;
+    activeJobs.delete(job.id);
+}
+/**
+ * Start a stopped cron job
+ */
+export function startCronJob(job) {
+    job.stopped = false;
+    scheduleNext(job);
+    activeJobs.set(job.id, job);
+}
+/**
+ * Get all active cron jobs
+ */
+export function getActiveCronJobs() {
+    return Array.from(activeJobs.values());
+}
+/**
+ * Stop all active cron jobs
+ */
+export function stopAllCronJobs() {
+    for (const job of activeJobs.values()) {
+        stopCronJob(job);
+    }
+}
+/**
+ * Get the count of active cron jobs
+ */
+export function getActiveCronJobCount() {
+    return activeJobs.size;
+}
+/**
+ * Cron job registry object for external access
+ */
+export const cronJobRegistry = {
+    create: createCronJob,
+    stop: stopCronJob,
+    start: startCronJob,
+    getActive: getActiveCronJobs,
+    getActiveCount: getActiveCronJobCount,
+    stopAll: stopAllCronJobs,
+};
+/**
+ * Create a schedule from a cron expression or well-known pattern
+ *
+ * @param expression - Cron expression or known pattern name
+ * @param handler - Function to execute
+ * @param options - Optional configuration
+ * @returns CronJob handle
+ */
+export function schedule(expression, handler, options = {}) {
+    return createCronJob(expression, handler, {
+        ...(options.id !== undefined && { id: options.id }),
+        ...(options.onError !== undefined && { onError: options.onError }),
+        startImmediately: true,
+    });
+}
+//# sourceMappingURL=cron-scheduler.js.map