@warlock.js/scheduler 4.0.31 → 4.0.41

package/cjs/index.js

@@ -1 +1,977 @@
-'use strict';var cronParser=require('./cron-parser.js'),job=require('./job.js'),scheduler=require('./scheduler.js');exports.CronParser=cronParser.CronParser;exports.parseCron=cronParser.parseCron;exports.Job=job.Job;exports.job=job.job;exports.Scheduler=scheduler.Scheduler;exports.scheduler=scheduler.scheduler;//# sourceMappingURL=index.js.map
+'use strict';
+
+var dayjs2 = require('dayjs');
+var timezone = require('dayjs/plugin/timezone.js');
+var utc = require('dayjs/plugin/utc.js');
+var events = require('events');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var dayjs2__default = /*#__PURE__*/_interopDefault(dayjs2);
+var timezone__default = /*#__PURE__*/_interopDefault(timezone);
+var utc__default = /*#__PURE__*/_interopDefault(utc);
+
+// ../../warlock.js/scheduler/src/cron-parser.ts
+var CronParser = class {
+  /**
+   * Creates a new CronParser instance
+   *
+   * @param expression - Standard 5-field cron expression
+   * @throws Error if expression is invalid
+   */
+  constructor(_expression) {
+    this._expression = _expression;
+    this._fields = this._parse(_expression);
+  }
+  _fields;
+  /**
+   * Get the parsed cron fields
+   */
+  get fields() {
+    return this._fields;
+  }
+  /**
+   * Get the original expression
+   */
+  get expression() {
+    return this._expression;
+  }
+  /**
+   * Calculate the next run time from a given date
+   *
+   * @param from - Starting date (defaults to now)
+   * @returns Next run time as Dayjs
+   */
+  nextRun(from = dayjs2__default.default()) {
+    let date = from.add(1, "minute").second(0).millisecond(0);
+    const maxIterations = 366 * 24 * 60;
+    let iterations = 0;
+    while (iterations < maxIterations) {
+      iterations++;
+      if (!this._fields.months.includes(date.month() + 1)) {
+        date = date.add(1, "month").date(1).hour(0).minute(0);
+        continue;
+      }
+      if (!this._fields.daysOfMonth.includes(date.date())) {
+        date = date.add(1, "day").hour(0).minute(0);
+        continue;
+      }
+      if (!this._fields.daysOfWeek.includes(date.day())) {
+        date = date.add(1, "day").hour(0).minute(0);
+        continue;
+      }
+      if (!this._fields.hours.includes(date.hour())) {
+        date = date.add(1, "hour").minute(0);
+        continue;
+      }
+      if (!this._fields.minutes.includes(date.minute())) {
+        date = date.add(1, "minute");
+        continue;
+      }
+      return date;
+    }
+    throw new Error(`Could not find next run time for cron expression: ${this._expression}`);
+  }
+  /**
+   * Check if a given date matches the cron expression
+   *
+   * @param date - Date to check
+   * @returns true if the date matches
+   */
+  matches(date) {
+    return this._fields.minutes.includes(date.minute()) && this._fields.hours.includes(date.hour()) && this._fields.daysOfMonth.includes(date.date()) && this._fields.months.includes(date.month() + 1) && this._fields.daysOfWeek.includes(date.day());
+  }
+  /**
+   * Parse a cron expression into fields
+   */
+  _parse(expression) {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5) {
+      throw new Error(
+        `Invalid cron expression: "${expression}". Expected 5 fields (minute hour day month weekday).`
+      );
+    }
+    const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
+    return {
+      minutes: this._parseField(minute, 0, 59),
+      hours: this._parseField(hour, 0, 23),
+      daysOfMonth: this._parseField(dayOfMonth, 1, 31),
+      months: this._parseField(month, 1, 12),
+      daysOfWeek: this._parseField(dayOfWeek, 0, 6)
+    };
+  }
+  /**
+   * 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
+   */
+  _parseField(field, min, max) {
+    const values = /* @__PURE__ */ new Set();
+    const parts = field.split(",");
+    for (const part of parts) {
+      const [range, stepStr] = part.split("/");
+      const step = stepStr ? parseInt(stepStr, 10) : 1;
+      if (isNaN(step) || step < 1) {
+        throw new Error(`Invalid step value in cron field: "${field}"`);
+      }
+      let rangeStart;
+      let rangeEnd;
+      if (range === "*") {
+        rangeStart = min;
+        rangeEnd = max;
+      } else if (range.includes("-")) {
+        const [startStr, endStr] = range.split("-");
+        rangeStart = parseInt(startStr, 10);
+        rangeEnd = parseInt(endStr, 10);
+        if (isNaN(rangeStart) || isNaN(rangeEnd)) {
+          throw new Error(`Invalid range in cron field: "${field}"`);
+        }
+        if (rangeStart < min || rangeEnd > max || rangeStart > rangeEnd) {
+          throw new Error(`Range out of bounds in cron field: "${field}" (valid: ${min}-${max})`);
+        }
+      } else {
+        const value = parseInt(range, 10);
+        if (isNaN(value)) {
+          throw new Error(`Invalid value in cron field: "${field}"`);
+        }
+        if (value < min || value > max) {
+          throw new Error(`Value out of bounds in cron field: "${field}" (valid: ${min}-${max})`);
+        }
+        rangeStart = value;
+        rangeEnd = value;
+      }
+      for (let i = rangeStart; i <= rangeEnd; i += step) {
+        values.add(i);
+      }
+    }
+    return Array.from(values).sort((a, b) => a - b);
+  }
+};
+function parseCron(expression) {
+  return new CronParser(expression);
+}
+dayjs2__default.default.extend(utc__default.default);
+dayjs2__default.default.extend(timezone__default.default);
+var DAYS_OF_WEEK = [
+  "sunday",
+  "monday",
+  "tuesday",
+  "wednesday",
+  "thursday",
+  "friday",
+  "saturday"
+];
+var Job = class {
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Constructor
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Creates a new Job instance
+   *
+   * @param name - Unique identifier for the job
+   * @param callback - Function to execute when the job runs
+   */
+  constructor(name, _callback) {
+    this.name = name;
+    this._callback = _callback;
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Private Properties
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Interval configuration for scheduling
+   */
+  _intervals = {};
+  /**
+   * Last execution timestamp
+   */
+  _lastRun = null;
+  /**
+   * Whether the job is currently executing
+   */
+  _isRunning = false;
+  /**
+   * Skip execution if job is already running
+   */
+  _skipIfRunning = false;
+  /**
+   * Retry configuration
+   */
+  _retryConfig = null;
+  /**
+   * Timezone for scheduling (defaults to system timezone)
+   */
+  _timezone = null;
+  /**
+   * Cron expression parser (mutually exclusive with interval config)
+   */
+  _cronParser = null;
+  /**
+   * Promise resolver for completion waiting
+   */
+  _completionResolver = null;
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Public Properties
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Next scheduled execution time
+   */
+  nextRun = null;
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Public Getters
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Returns true if the job is currently executing
+   */
+  get isRunning() {
+    return this._isRunning;
+  }
+  /**
+   * Returns the last execution timestamp
+   */
+  get lastRun() {
+    return this._lastRun;
+  }
+  /**
+   * Returns the current interval configuration (readonly)
+   */
+  get intervals() {
+    return this._intervals;
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Interval Configuration Methods (Fluent API)
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Set a custom interval for job execution
+   *
+   * @param value - Number of time units
+   * @param timeType - Type of time unit
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * job.every(5, "minute"); // Run every 5 minutes
+   * job.every(2, "hour");   // Run every 2 hours
+   * ```
+   */
+  every(value, timeType) {
+    this._intervals.every = { type: timeType, value };
+    return this;
+  }
+  /**
+   * Run job every second (use with caution - high frequency)
+   */
+  everySecond() {
+    return this.every(1, "second");
+  }
+  /**
+   * Run job every specified number of seconds
+   */
+  everySeconds(seconds) {
+    return this.every(seconds, "second");
+  }
+  /**
+   * Run job every minute
+   */
+  everyMinute() {
+    return this.every(1, "minute");
+  }
+  /**
+   * Run job every specified number of minutes
+   */
+  everyMinutes(minutes) {
+    return this.every(minutes, "minute");
+  }
+  /**
+   * Run job every hour
+   */
+  everyHour() {
+    return this.every(1, "hour");
+  }
+  /**
+   * Run job every specified number of hours
+   */
+  everyHours(hours) {
+    return this.every(hours, "hour");
+  }
+  /**
+   * Run job every day at midnight
+   */
+  everyDay() {
+    return this.every(1, "day");
+  }
+  /**
+   * Alias for everyDay()
+   */
+  daily() {
+    return this.everyDay();
+  }
+  /**
+   * Run job twice a day (every 12 hours)
+   */
+  twiceDaily() {
+    return this.every(12, "hour");
+  }
+  /**
+   * Run job every week
+   */
+  everyWeek() {
+    return this.every(1, "week");
+  }
+  /**
+   * Alias for everyWeek()
+   */
+  weekly() {
+    return this.everyWeek();
+  }
+  /**
+   * Run job every month
+   */
+  everyMonth() {
+    return this.every(1, "month");
+  }
+  /**
+   * Alias for everyMonth()
+   */
+  monthly() {
+    return this.everyMonth();
+  }
+  /**
+   * Run job every year
+   */
+  everyYear() {
+    return this.every(1, "year");
+  }
+  /**
+   * Alias for everyYear()
+   */
+  yearly() {
+    return this.everyYear();
+  }
+  /**
+   * Alias for everyMinute() - job runs continuously every minute
+   */
+  always() {
+    return this.everyMinute();
+  }
+  /**
+   * Schedule job using a cron expression
+   *
+   * Supports standard 5-field cron syntax:
+   * ```
+   * ┌───────────── 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
+   * - 'x/5' - step values (every 5)
+   * - '1-10/2' - range with step
+   *
+   * @param expression - Standard 5-field cron expression
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * job.cron("0 9 * * 1-5");   // 9 AM weekdays
+   * job.cron("x/5 * * * *");   // Every 5 minutes
+   * job.cron("0 0 1 * *");     // First day of month at midnight
+   * job.cron("0 x/2 * * *");   // Every 2 hours
+   * ```
+   */
+  cron(expression) {
+    this._cronParser = new CronParser(expression);
+    this._intervals = {};
+    return this;
+  }
+  /**
+   * Get the cron expression if one is set
+   */
+  get cronExpression() {
+    return this._cronParser?.expression ?? null;
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Day & Time Configuration Methods
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Schedule job on a specific day
+   *
+   * @param day - Day of week (string) or day of month (number 1-31)
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * job.on("monday");  // Run on Mondays
+   * job.on(15);        // Run on the 15th of each month
+   * ```
+   */
+  on(day) {
+    if (typeof day === "number" && (day < 1 || day > 31)) {
+      throw new Error("Invalid day of the month. Must be between 1 and 31.");
+    }
+    this._intervals.day = day;
+    return this;
+  }
+  /**
+   * Schedule job at a specific time
+   *
+   * @param time - Time in HH:mm or HH:mm:ss format
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * job.daily().at("09:00");    // Run daily at 9 AM
+   * job.weekly().at("14:30");   // Run weekly at 2:30 PM
+   * ```
+   */
+  at(time) {
+    if (!/^\d{1,2}:\d{2}(:\d{2})?$/.test(time)) {
+      throw new Error("Invalid time format. Use HH:mm or HH:mm:ss.");
+    }
+    this._intervals.time = time;
+    return this;
+  }
+  /**
+   * Run task at the beginning of the specified time period
+   *
+   * @param type - Time type (day, month, year)
+   */
+  beginOf(type) {
+    const time = "00:00";
+    switch (type) {
+      case "day":
+        break;
+      case "month":
+        this.on(1);
+        break;
+      case "year":
+        this.on(1);
+        this.every(1, "year");
+        break;
+      default:
+        throw new Error(`Unsupported type for beginOf: ${type}`);
+    }
+    return this.at(time);
+  }
+  /**
+   * Run task at the end of the specified time period
+   *
+   * @param type - Time type (day, month, year)
+   */
+  endOf(type) {
+    const now = this._now();
+    const time = "23:59";
+    switch (type) {
+      case "day":
+        break;
+      case "month":
+        this.on(now.endOf("month").date());
+        break;
+      case "year":
+        this.on(31);
+        this.every(1, "year");
+        break;
+      default:
+        throw new Error(`Unsupported type for endOf: ${type}`);
+    }
+    return this.at(time);
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Timezone Configuration
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Set the timezone for this job's scheduling
+   *
+   * @param tz - IANA timezone string (e.g., "America/New_York", "Europe/London")
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * job.daily().at("09:00").inTimezone("America/New_York");
+   * ```
+   */
+  inTimezone(tz) {
+    this._timezone = tz;
+    return this;
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Execution Options
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Prevent overlapping executions of this job
+   *
+   * When enabled, if the job is already running when it's scheduled to run again,
+   * the new execution will be skipped.
+   *
+   * @param skip - Whether to skip if already running (default: true)
+   * @returns this for chaining
+   */
+  preventOverlap(skip = true) {
+    this._skipIfRunning = skip;
+    return this;
+  }
+  /**
+   * Configure automatic retry on failure
+   *
+   * @param maxRetries - Maximum number of retry attempts
+   * @param delay - Delay between retries in milliseconds
+   * @param backoffMultiplier - Optional multiplier for exponential backoff
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * job.retry(3, 1000);           // Retry 3 times with 1s delay
+   * job.retry(5, 1000, 2);        // Exponential backoff: 1s, 2s, 4s, 8s, 16s
+   * ```
+   */
+  retry(maxRetries, delay = 1e3, backoffMultiplier) {
+    this._retryConfig = {
+      maxRetries,
+      delay,
+      backoffMultiplier
+    };
+    return this;
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Execution Control
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Terminate the job and clear all scheduling data
+   */
+  terminate() {
+    this._intervals = {};
+    this.nextRun = null;
+    this._lastRun = null;
+    this._isRunning = false;
+    return this;
+  }
+  /**
+   * Prepare the job by calculating the next run time
+   * Called by the scheduler when starting
+   */
+  prepare() {
+    this._determineNextRun();
+  }
+  /**
+   * Determine if the job should run now
+   *
+   * @returns true if the job should execute
+   */
+  shouldRun() {
+    if (this._skipIfRunning && this._isRunning) {
+      return false;
+    }
+    return this.nextRun !== null && this._now().isAfter(this.nextRun);
+  }
+  /**
+   * Execute the job
+   *
+   * @returns Promise resolving to the job result
+   */
+  async run() {
+    const startTime = Date.now();
+    this._isRunning = true;
+    try {
+      const result = await this._executeWithRetry();
+      this._lastRun = this._now();
+      this._determineNextRun();
+      return {
+        success: true,
+        duration: Date.now() - startTime,
+        retries: result.retries || 0
+      };
+    } catch (error) {
+      return {
+        success: false,
+        duration: Date.now() - startTime,
+        error,
+        retries: this._retryConfig?.maxRetries ?? 0
+      };
+    } finally {
+      this._isRunning = false;
+      if (this._completionResolver) {
+        this._completionResolver();
+        this._completionResolver = null;
+      }
+    }
+  }
+  /**
+   * Wait for the job to complete
+   * Useful for graceful shutdown
+   *
+   * @returns Promise that resolves when the job completes
+   */
+  waitForCompletion() {
+    if (!this._isRunning) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this._completionResolver = resolve;
+    });
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Private Methods
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Get current time, respecting timezone if set
+   */
+  _now() {
+    return this._timezone ? dayjs2__default.default().tz(this._timezone) : dayjs2__default.default();
+  }
+  /**
+   * Execute the callback with retry logic
+   */
+  async _executeWithRetry() {
+    let lastError;
+    let attempts = 0;
+    const maxAttempts = (this._retryConfig?.maxRetries ?? 0) + 1;
+    while (attempts < maxAttempts) {
+      try {
+        await this._callback(this);
+        return { retries: attempts };
+      } catch (error) {
+        lastError = error;
+        attempts++;
+        if (attempts < maxAttempts && this._retryConfig) {
+          const delay = this._calculateRetryDelay(attempts);
+          await this._sleep(delay);
+        }
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Calculate retry delay with optional exponential backoff
+   */
+  _calculateRetryDelay(attempt) {
+    if (!this._retryConfig) return 0;
+    const { delay, backoffMultiplier } = this._retryConfig;
+    if (backoffMultiplier) {
+      return delay * Math.pow(backoffMultiplier, attempt - 1);
+    }
+    return delay;
+  }
+  /**
+   * Sleep for specified milliseconds
+   */
+  _sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Calculate the next run time based on interval or cron configuration
+   */
+  _determineNextRun() {
+    if (this._cronParser) {
+      const now = this._now();
+      this.nextRun = this._cronParser.nextRun(now);
+      return;
+    }
+    let date = this._lastRun ? this._lastRun.add(1, "second") : this._now();
+    if (this._intervals.every?.value && this._intervals.every?.type) {
+      date = date.add(this._intervals.every.value, this._intervals.every.type);
+    }
+    if (this._intervals.day !== void 0) {
+      if (typeof this._intervals.day === "number") {
+        date = date.date(this._intervals.day);
+      } else {
+        const targetDay = DAYS_OF_WEEK.indexOf(this._intervals.day);
+        if (targetDay !== -1) {
+          date = date.day(targetDay);
+        }
+      }
+    }
+    if (this._intervals.time) {
+      const parts = this._intervals.time.split(":").map(Number);
+      const [hour, minute, second = 0] = parts;
+      date = date.hour(hour).minute(minute).second(second).millisecond(0);
+    }
+    while (date.isBefore(this._now())) {
+      if (this._intervals.every?.value && this._intervals.every?.type) {
+        date = date.add(this._intervals.every.value, this._intervals.every.type);
+      } else {
+        date = date.add(1, "day");
+      }
+    }
+    this.nextRun = date;
+  }
+};
+function job(name, callback) {
+  return new Job(name, callback);
+}
+var Scheduler = class 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 = 1e3;
+  /**
+   * 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(job2) {
+    this._jobs.push(job2);
+    return this;
+  }
+  /**
+   * Alias to create a new job directly and store it
+   */
+  newJob(name, jobCallback) {
+    const job2 = new Job(name, jobCallback);
+    this.addJob(job2);
+    return job2;
+  }
+  /**
+   * 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.");
+    }
+    for (const job2 of this._jobs) {
+      job2.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 = 3e4) {
+    this._isShuttingDown = true;
+    this.stop();
+    const runningJobs = this._jobs.filter((j) => j.isRunning);
+    if (runningJobs.length > 0) {
+      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();
+    this._timeoutId = setTimeout(async () => {
+      await this._tick();
+      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", /* @__PURE__ */ new Date());
+    const dueJobs = this._jobs.filter((job2) => {
+      if (!job2.shouldRun()) return false;
+      if (job2.isRunning) {
+        this.emit("job:skip", job2.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 job2 of jobs) {
+      if (this._isShuttingDown) break;
+      await this._runJob(job2);
+    }
+  }
+  /**
+   * Run jobs in parallel with concurrency limit
+   */
+  async _runJobsInParallel(jobs) {
+    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((job2) => this._runJob(job2)));
+    }
+  }
+  /**
+   * Run a single job and emit events
+   */
+  async _runJob(job2) {
+    this.emit("job:start", job2.name);
+    const result = await job2.run();
+    if (result.success) {
+      this.emit("job:complete", job2.name, result);
+    } else {
+      this.emit("job:error", job2.name, result.error);
+    }
+    return result;
+  }
+};
+var scheduler = new Scheduler();
+
+exports.CronParser = CronParser;
+exports.Job = Job;
+exports.Scheduler = Scheduler;
+exports.job = job;
+exports.parseCron = parseCron;
+exports.scheduler = scheduler;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map