@warlock.js/scheduler 4.0.47 → 4.0.57

package/cjs/scheduler.d.ts

@@ -0,0 +1,182 @@
+import { Job, JobCallback } from "./job";
+import type { SchedulerEvents } from "./types";
+/**
+ * Type-safe event emitter interface for Scheduler events
+ */
+interface TypedEventEmitter<TEvents extends Record<string, unknown[]>> {
+    on<K extends keyof TEvents>(event: K, listener: (...args: TEvents[K]) => void): this;
+    once<K extends keyof TEvents>(event: K, listener: (...args: TEvents[K]) => void): this;
+    off<K extends keyof TEvents>(event: K, listener: (...args: TEvents[K]) => void): this;
+    emit<K extends keyof TEvents>(event: K, ...args: TEvents[K]): boolean;
+}
+declare const Scheduler_base: new () => TypedEventEmitter<SchedulerEvents>;
+/**
+ * Scheduler class manages and executes scheduled jobs.
+ *
+ * Features:
+ * - Event-based observability
+ * - Parallel or sequential job execution
+ * - Drift compensation for accurate timing
+ * - Graceful shutdown with job draining
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new Scheduler();
+ *
+ * scheduler.on('job:error', (jobName, error) => {
+ *   logger.error(`Job ${jobName} failed:`, error);
+ * });
+ *
+ * scheduler
+ *   .addJob(cleanupJob)
+ *   .addJob(reportJob)
+ *   .runInParallel(true)
+ *   .start();
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', () => scheduler.shutdown());
+ * ```
+ */
+export declare class Scheduler extends Scheduler_base implements TypedEventEmitter<SchedulerEvents> {
+    /**
+     * List of registered jobs
+     */
+    private _jobs;
+    /**
+     * Reference to the current timeout for stopping
+     */
+    private _timeoutId;
+    /**
+     * Tick interval in milliseconds (how often to check for due jobs)
+     */
+    private _tickInterval;
+    /**
+     * Whether to run due jobs in parallel
+     */
+    private _runInParallel;
+    /**
+     * Maximum concurrent jobs when running in parallel
+     */
+    private _maxConcurrency;
+    /**
+     * Flag indicating scheduler is shutting down
+     */
+    private _isShuttingDown;
+    /**
+     * Returns true if the scheduler is currently running
+     */
+    get isRunning(): boolean;
+    /**
+     * Returns the number of registered jobs
+     */
+    get jobCount(): number;
+    /**
+     * Add a job to the scheduler
+     *
+     * @param job - Job instance to schedule
+     * @returns this for chaining
+     */
+    addJob(job: Job): this;
+    /**
+     * Alias to create a new job directly and store it
+     */
+    newJob(name: string, jobCallback: JobCallback): Job;
+    /**
+     * Add multiple jobs to the scheduler
+     *
+     * @param jobs - Array of Job instances
+     * @returns this for chaining
+     */
+    addJobs(jobs: Job[]): this;
+    /**
+     * Remove a job from the scheduler by name
+     *
+     * @param jobName - Name of the job to remove
+     * @returns true if job was found and removed
+     */
+    removeJob(jobName: string): boolean;
+    /**
+     * Get a job by name
+     *
+     * @param jobName - Name of the job to find
+     * @returns Job instance or undefined
+     */
+    getJob(jobName: string): Job | undefined;
+    /**
+     * Get all registered jobs
+     *
+     * @returns Array of registered jobs (readonly)
+     */
+    list(): readonly Job[];
+    /**
+     * Set the tick interval (how often to check for due jobs)
+     *
+     * @param ms - Interval in milliseconds (minimum 100ms)
+     * @returns this for chaining
+     */
+    runEvery(ms: number): this;
+    /**
+     * Configure whether jobs should run in parallel
+     *
+     * @param parallel - Enable parallel execution
+     * @param maxConcurrency - Maximum concurrent jobs (default: 10)
+     * @returns this for chaining
+     */
+    runInParallel(parallel: boolean, maxConcurrency?: number): this;
+    /**
+     * Start the scheduler
+     *
+     * @throws Error if scheduler is already running
+     */
+    start(): void;
+    /**
+     * Stop the scheduler immediately
+     *
+     * Note: This does not wait for running jobs to complete.
+     * Use shutdown() for graceful termination.
+     */
+    stop(): void;
+    /**
+     * Gracefully shutdown the scheduler
+     *
+     * Stops scheduling new jobs and waits for currently running jobs to complete.
+     *
+     * @param timeout - Maximum time to wait for jobs (default: 30000ms)
+     * @returns Promise that resolves when shutdown is complete
+     */
+    shutdown(timeout?: number): Promise<void>;
+    /**
+     * Schedule the next tick
+     */
+    private _scheduleTick;
+    /**
+     * Execute a scheduler tick - check and run due jobs
+     */
+    private _tick;
+    /**
+     * Run jobs sequentially
+     */
+    private _runJobsSequentially;
+    /**
+     * Run jobs in parallel with concurrency limit
+     */
+    private _runJobsInParallel;
+    /**
+     * Run a single job and emit events
+     */
+    private _runJob;
+}
+/**
+ * Default scheduler instance for simple use cases
+ *
+ * @example
+ * ```typescript
+ * import { scheduler, job } from "@warlock.js/scheduler";
+ *
+ * scheduler.addJob(job("cleanup", cleanupFn).daily());
+ * scheduler.start();
+ * ```
+ */
+export declare const scheduler: Scheduler;
+export {};
+//# sourceMappingURL=scheduler.d.ts.map

package/cjs/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACzC,OAAO,KAAK,EAAa,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1D;;GAEG;AACH,UAAU,iBAAiB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IACnE,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACrF,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACvF,GAAG,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACtF,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;CACvE;wCA8BoC,kBAAkB,eAAe,CAAC;AA5BvE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,SACX,SAAQ,cACR,YAAW,iBAAiB,CAAC,eAAe,CAAC;IAM7C;;OAEG;IACH,OAAO,CAAC,KAAK,CAAa;IAE1B;;OAEG;IACH,OAAO,CAAC,UAAU,CAA+B;IAEjD;;OAEG;IACH,OAAO,CAAC,aAAa,CAAQ;IAE7B;;OAEG;IACH,OAAO,CAAC,cAAc,CAAS;IAE/B;;OAEG;IACH,OAAO,CAAC,eAAe,CAAM;IAE7B;;OAEG;IACH,OAAO,CAAC,eAAe,CAAS;IAMhC;;OAEG;IACH,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED;;OAEG;IACH,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAMD;;;;;OAKG;IACI,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI;IAK7B;;OAEG;IACI,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW;IAMpD;;;;;OAKG;IACI,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAKjC;;;;;OAKG;IACI,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAS1C;;;;;OAKG;IACI,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS;IAI/C;;;;OAIG;IACI,IAAI,IAAI,SAAS,GAAG,EAAE;IAI7B;;;;;OAKG;IACI,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQjC;;;;;;OAMG;IACI,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,cAAc,SAAK,GAAG,IAAI;IAUlE;;;;OAIG;IACI,KAAK,IAAI,IAAI;IAoBpB;;;;;OAKG;IACI,IAAI,IAAI,IAAI;IASnB;;;;;;;OAOG;IACU,QAAQ,CAAC,OAAO,SAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBrD;;OAEG;IACH,OAAO,CAAC,aAAa;IAiBrB;;OAEG;YACW,KAAK;IAyBnB;;OAEG;YACW,oBAAoB;IAOlC;;OAEG;YACW,kBAAkB;IAchC;;OAEG;YACW,OAAO;CAatB;AAMD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,WAAkB,CAAC"}

package/cjs/scheduler.js

@@ -0,0 +1,313 @@
+'use strict';var events=require('events'),job=require('./job.js');/**
+ * Scheduler class manages and executes scheduled jobs.
+ *
+ * Features:
+ * - Event-based observability
+ * - Parallel or sequential job execution
+ * - Drift compensation for accurate timing
+ * - Graceful shutdown with job draining
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new Scheduler();
+ *
+ * scheduler.on('job:error', (jobName, error) => {
+ *   logger.error(`Job ${jobName} failed:`, error);
+ * });
+ *
+ * scheduler
+ *   .addJob(cleanupJob)
+ *   .addJob(reportJob)
+ *   .runInParallel(true)
+ *   .start();
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', () => scheduler.shutdown());
+ * ```
+ */
+class Scheduler extends events.EventEmitter {
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Private Properties
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * List of registered jobs
+     */
+    _jobs = [];
+    /**
+     * Reference to the current timeout for stopping
+     */
+    _timeoutId = null;
+    /**
+     * Tick interval in milliseconds (how often to check for due jobs)
+     */
+    _tickInterval = 1000;
+    /**
+     * Whether to run due jobs in parallel
+     */
+    _runInParallel = false;
+    /**
+     * Maximum concurrent jobs when running in parallel
+     */
+    _maxConcurrency = 10;
+    /**
+     * Flag indicating scheduler is shutting down
+     */
+    _isShuttingDown = false;
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Public Getters
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Returns true if the scheduler is currently running
+     */
+    get isRunning() {
+        return this._timeoutId !== null;
+    }
+    /**
+     * Returns the number of registered jobs
+     */
+    get jobCount() {
+        return this._jobs.length;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Configuration Methods (Fluent API)
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Add a job to the scheduler
+     *
+     * @param job - Job instance to schedule
+     * @returns this for chaining
+     */
+    addJob(job) {
+        this._jobs.push(job);
+        return this;
+    }
+    /**
+     * Alias to create a new job directly and store it
+     */
+    newJob(name, jobCallback) {
+        const job$1 = new job.Job(name, jobCallback);
+        this.addJob(job$1);
+        return job$1;
+    }
+    /**
+     * Add multiple jobs to the scheduler
+     *
+     * @param jobs - Array of Job instances
+     * @returns this for chaining
+     */
+    addJobs(jobs) {
+        this._jobs.push(...jobs);
+        return this;
+    }
+    /**
+     * Remove a job from the scheduler by name
+     *
+     * @param jobName - Name of the job to remove
+     * @returns true if job was found and removed
+     */
+    removeJob(jobName) {
+        const index = this._jobs.findIndex((j) => j.name === jobName);
+        if (index !== -1) {
+            this._jobs.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get a job by name
+     *
+     * @param jobName - Name of the job to find
+     * @returns Job instance or undefined
+     */
+    getJob(jobName) {
+        return this._jobs.find((j) => j.name === jobName);
+    }
+    /**
+     * Get all registered jobs
+     *
+     * @returns Array of registered jobs (readonly)
+     */
+    list() {
+        return this._jobs;
+    }
+    /**
+     * Set the tick interval (how often to check for due jobs)
+     *
+     * @param ms - Interval in milliseconds (minimum 100ms)
+     * @returns this for chaining
+     */
+    runEvery(ms) {
+        if (ms < 100) {
+            throw new Error("Tick interval must be at least 100ms");
+        }
+        this._tickInterval = ms;
+        return this;
+    }
+    /**
+     * Configure whether jobs should run in parallel
+     *
+     * @param parallel - Enable parallel execution
+     * @param maxConcurrency - Maximum concurrent jobs (default: 10)
+     * @returns this for chaining
+     */
+    runInParallel(parallel, maxConcurrency = 10) {
+        this._runInParallel = parallel;
+        this._maxConcurrency = maxConcurrency;
+        return this;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Lifecycle Methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Start the scheduler
+     *
+     * @throws Error if scheduler is already running
+     */
+    start() {
+        if (this.isRunning) {
+            throw new Error("Scheduler is already running.");
+        }
+        if (this._jobs.length === 0) {
+            throw new Error("Cannot start scheduler with no jobs.");
+        }
+        // Prepare all jobs (calculate initial next run times)
+        for (const job of this._jobs) {
+            job.prepare();
+        }
+        this._isShuttingDown = false;
+        this._scheduleTick();
+        this.emit("scheduler:started");
+    }
+    /**
+     * Stop the scheduler immediately
+     *
+     * Note: This does not wait for running jobs to complete.
+     * Use shutdown() for graceful termination.
+     */
+    stop() {
+        if (this._timeoutId) {
+            clearTimeout(this._timeoutId);
+            this._timeoutId = null;
+        }
+        this.emit("scheduler:stopped");
+    }
+    /**
+     * Gracefully shutdown the scheduler
+     *
+     * Stops scheduling new jobs and waits for currently running jobs to complete.
+     *
+     * @param timeout - Maximum time to wait for jobs (default: 30000ms)
+     * @returns Promise that resolves when shutdown is complete
+     */
+    async shutdown(timeout = 30000) {
+        this._isShuttingDown = true;
+        this.stop();
+        // Get all currently running jobs
+        const runningJobs = this._jobs.filter((j) => j.isRunning);
+        if (runningJobs.length > 0) {
+            // Wait for jobs to complete or timeout
+            await Promise.race([
+                Promise.all(runningJobs.map((j) => j.waitForCompletion())),
+                new Promise((resolve) => setTimeout(resolve, timeout)),
+            ]);
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Private Methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Schedule the next tick
+     */
+    _scheduleTick() {
+        if (this._isShuttingDown)
+            return;
+        const startTime = Date.now();
+        // Use setImmediate for first tick to allow event handlers to be registered
+        this._timeoutId = setTimeout(async () => {
+            await this._tick();
+            // Calculate time spent and adjust next tick for drift compensation
+            const elapsed = Date.now() - startTime;
+            Math.max(this._tickInterval - elapsed, 0);
+            this._scheduleTick();
+        }, this._tickInterval);
+    }
+    /**
+     * Execute a scheduler tick - check and run due jobs
+     */
+    async _tick() {
+        this.emit("scheduler:tick", new Date());
+        // Find jobs that should run
+        const dueJobs = this._jobs.filter((job) => {
+            if (!job.shouldRun())
+                return false;
+            // Skip if overlap prevention is enabled and job is running
+            if (job.isRunning) {
+                this.emit("job:skip", job.name, "Job is already running");
+                return false;
+            }
+            return true;
+        });
+        if (dueJobs.length === 0)
+            return;
+        if (this._runInParallel) {
+            await this._runJobsInParallel(dueJobs);
+        }
+        else {
+            await this._runJobsSequentially(dueJobs);
+        }
+    }
+    /**
+     * Run jobs sequentially
+     */
+    async _runJobsSequentially(jobs) {
+        for (const job of jobs) {
+            if (this._isShuttingDown)
+                break;
+            await this._runJob(job);
+        }
+    }
+    /**
+     * Run jobs in parallel with concurrency limit
+     */
+    async _runJobsInParallel(jobs) {
+        // Simple batching for concurrency control
+        const batches = [];
+        for (let i = 0; i < jobs.length; i += this._maxConcurrency) {
+            batches.push(jobs.slice(i, i + this._maxConcurrency));
+        }
+        for (const batch of batches) {
+            if (this._isShuttingDown)
+                break;
+            await Promise.allSettled(batch.map((job) => this._runJob(job)));
+        }
+    }
+    /**
+     * Run a single job and emit events
+     */
+    async _runJob(job) {
+        this.emit("job:start", job.name);
+        const result = await job.run();
+        if (result.success) {
+            this.emit("job:complete", job.name, result);
+        }
+        else {
+            this.emit("job:error", job.name, result.error);
+        }
+        return result;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Default Export
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Default scheduler instance for simple use cases
+ *
+ * @example
+ * ```typescript
+ * import { scheduler, job } from "@warlock.js/scheduler";
+ *
+ * scheduler.addJob(job("cleanup", cleanupFn).daily());
+ * scheduler.start();
+ * ```
+ */
+const scheduler = new Scheduler();exports.Scheduler=Scheduler;exports.scheduler=scheduler;//# sourceMappingURL=scheduler.js.map

package/cjs/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sources":["../src/scheduler.ts"],"sourcesContent":[null],"names":["EventEmitter","job","Job"],"mappings":"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"}

package/cjs/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Time unit types for scheduling intervals
+ */
+export type TimeType = "second" | "minute" | "hour" | "day" | "week" | "month" | "year";
+/**
+ * Days of the week (lowercase for consistency)
+ */
+export type Day = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
+/**
+ * Job interval configuration
+ */
+export type JobIntervals = {
+    /** Day of week or day of month */
+    day?: Day | number;
+    /** Time of day in HH:mm format */
+    time?: string;
+    /** Recurring interval configuration */
+    every?: {
+        type?: TimeType;
+        value?: number;
+    };
+};
+/**
+ * Result of a job execution
+ */
+export type JobResult = {
+    /** Whether the job completed successfully */
+    success: boolean;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Error if the job failed */
+    error?: unknown;
+    /** Number of retry attempts made */
+    retries?: number;
+};
+/**
+ * Job execution status
+ */
+export type JobStatus = "idle" | "running" | "completed" | "failed";
+/**
+ * Retry configuration for jobs
+ */
+export type RetryConfig = {
+    /** Maximum number of retry attempts */
+    maxRetries: number;
+    /** Delay between retries in milliseconds */
+    delay: number;
+    /** Backoff multiplier for exponential backoff */
+    backoffMultiplier?: number;
+};
+/**
+ * Scheduler event types for observability
+ */
+export type SchedulerEvents = {
+    "job:start": [jobName: string];
+    "job:complete": [jobName: string, result: JobResult];
+    "job:error": [jobName: string, error: unknown];
+    "job:skip": [jobName: string, reason: string];
+    "scheduler:started": [];
+    "scheduler:stopped": [];
+    "scheduler:tick": [timestamp: Date];
+};
+//# sourceMappingURL=types.d.ts.map

package/cjs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAExF;;GAEG;AACH,MAAM,MAAM,GAAG,GACX,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,GACR,UAAU,CAAC;AAEf;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,kCAAkC;IAClC,GAAG,CAAC,EAAE,GAAG,GAAG,MAAM,CAAC;IACnB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,QAAQ,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/B,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IACrD,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC/C,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,mBAAmB,EAAE,EAAE,CAAC;IACxB,mBAAmB,EAAE,EAAE,CAAC;IACxB,gBAAgB,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;CACrC,CAAC"}

package/cjs/utils.d.ts

@@ -0,0 +1,3 @@
+import { Day } from "./types";
+export declare function parseWeekDayNumber(day: Day): number;
+//# sourceMappingURL=utils.d.ts.map

package/cjs/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAE9B,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,GAAG,UAU1C"}

package/esm/cron-parser.d.ts

@@ -0,0 +1,98 @@
+import { type Dayjs } from "dayjs";
+/**
+ * Parsed cron expression fields
+ */
+export type CronFields = {
+    /** 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[];
+};
+/**
+ * Cron expression parser
+ *
+ * Supports standard 5-field cron expressions:
+ * ```
+ * ┌───────────── minute (0-59)
+ * │ ┌───────────── hour (0-23)
+ * │ │ ┌───────────── day of month (1-31)
+ * │ │ │ ┌───────────── month (1-12)
+ * │ │ │ │ ┌───────────── day of week (0-6, Sunday = 0)
+ * │ │ │ │ │
+ * * * * * *
+ * ```
+ *
+ * Supports:
+ * - `*` - any value
+ * - `5` - specific value
+ * - `1,3,5` - list of values
+ * - `1-5` - range of values
+ * - `* /5` - step values (every 5)
+ * - `1-10/2` - range with step
+ *
+ * @example
+ * ```typescript
+ * const parser = new CronParser("0 9 * * 1-5"); // 9 AM weekdays
+ * const nextRun = parser.nextRun();
+ * ```
+ */
+export declare class CronParser {
+    private readonly _expression;
+    private readonly _fields;
+    /**
+     * Creates a new CronParser instance
+     *
+     * @param expression - Standard 5-field cron expression
+     * @throws Error if expression is invalid
+     */
+    constructor(_expression: string);
+    /**
+     * Get the parsed cron fields
+     */
+    get fields(): Readonly<CronFields>;
+    /**
+     * Get the original expression
+     */
+    get expression(): string;
+    /**
+     * Calculate the next run time from a given date
+     *
+     * @param from - Starting date (defaults to now)
+     * @returns Next run time as Dayjs
+     */
+    nextRun(from?: Dayjs): Dayjs;
+    /**
+     * Check if a given date matches the cron expression
+     *
+     * @param date - Date to check
+     * @returns true if the date matches
+     */
+    matches(date: Dayjs): boolean;
+    /**
+     * Parse a cron expression into fields
+     */
+    private _parse;
+    /**
+     * Parse a single cron field
+     *
+     * @param field - Field value (e.g., "*", "5", "1-5", "* /2", "1,3,5")
+     * @param min - Minimum allowed value
+     * @param max - Maximum allowed value
+     * @returns Array of matching values
+     */
+    private _parseField;
+}
+/**
+ * Parse a cron expression string
+ *
+ * @param expression - Cron expression (5 fields)
+ * @returns CronParser instance
+ */
+export declare function parseCron(expression: string): CronParser;
+//# sourceMappingURL=cron-parser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cron-parser.d.ts","sourceRoot":"","sources":["../src/cron-parser.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,KAAK,EAAE,MAAM,OAAO,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,qBAAqB;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mBAAmB;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,oBAAoB;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,qCAAqC;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,UAAU;IASF,OAAO,CAAC,QAAQ,CAAC,WAAW;IAR/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IAErC;;;;;OAKG;gBACiC,WAAW,EAAE,MAAM;IAIvD;;OAEG;IACH,IAAW,MAAM,IAAI,QAAQ,CAAC,UAAU,CAAC,CAExC;IAED;;OAEG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED;;;;;OAKG;IACI,OAAO,CAAC,IAAI,GAAE,KAAe,GAAG,KAAK;IA+C5C;;;;;OAKG;IACI,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO;IAUpC;;OAEG;IACH,OAAO,CAAC,MAAM;IAoBd;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;CA2DpB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAExD"}