@warlock.js/scheduler 4.0.171 → 4.1.1

package/esm/job.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.mjs","names":[],"sources":["../../../../../@warlock.js/scheduler/src/job.ts"],"sourcesContent":["import dayjs, { type Dayjs } from \"dayjs\";\nimport isSameOrAfter from \"dayjs/plugin/isSameOrAfter.js\";\nimport timezone from \"dayjs/plugin/timezone.js\";\nimport utc from \"dayjs/plugin/utc.js\";\nimport { CronParser } from \"./cron-parser\";\nimport type { Day, JobIntervals, JobResult, RetryConfig, TimeType } from \"./types\";\n\ndayjs.extend(utc);\ndayjs.extend(timezone);\ndayjs.extend(isSameOrAfter);\n\nexport type JobCallback = (job: Job) => Promise<any>;\n\n/**\n * Days of week mapping (lowercase for consistency with Day type)\n */\nconst DAYS_OF_WEEK: Day[] = [\n  \"sunday\",\n  \"monday\",\n  \"tuesday\",\n  \"wednesday\",\n  \"thursday\",\n  \"friday\",\n  \"saturday\",\n];\n\n/**\n * Validate a `HH:mm` or `HH:mm:ss` string and return its parts.\n * Throws when the format is malformed or any part is out of range.\n */\nfunction parseTimeString(time: string): {\n  hour: number;\n  minute: number;\n  second: number;\n} {\n  if (!/^\\d{1,2}:\\d{2}(:\\d{2})?$/.test(time)) {\n    throw new Error(\"Invalid time format. Use HH:mm or HH:mm:ss.\");\n  }\n\n  const [hour, minute, second = 0] = time.split(\":\").map(Number);\n\n  if (hour < 0 || hour > 23) {\n    throw new Error(`Invalid hour in time \"${time}\". Must be between 0 and 23.`);\n  }\n\n  if (minute < 0 || minute > 59) {\n    throw new Error(`Invalid minute in time \"${time}\". Must be between 0 and 59.`);\n  }\n\n  if (second < 0 || second > 59) {\n    throw new Error(`Invalid second in time \"${time}\". Must be between 0 and 59.`);\n  }\n\n  return { hour, minute, second };\n}\n\n/**\n * Job class represents a scheduled task with configurable timing and execution options.\n *\n * @example\n * ```typescript\n * const job = new Job(\"cleanup\", async () => {\n *   await cleanupOldFiles();\n * })\n *   .everyDay()\n *   .at(\"03:00\")\n *   .inTimezone(\"America/New_York\")\n *   .preventOverlap()\n *   .retry(3, 1000);\n * ```\n */\nexport class Job {\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Private Properties\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Interval configuration for scheduling\n   */\n  private _intervals: JobIntervals = {};\n\n  /**\n   * Last execution timestamp.\n   *\n   * Updated after every run attempt — successful or failed — so the next-run\n   * calculation always advances even when a job throws. Use the `job:complete`\n   * / `job:error` events if you need to distinguish success from failure.\n   */\n  private _lastRun: Dayjs | null = null;\n\n  /**\n   * Whether the job is currently executing\n   */\n  private _isRunning = false;\n\n  /**\n   * Skip execution if job is already running\n   */\n  private _skipIfRunning = false;\n\n  /**\n   * Retry configuration\n   */\n  private _retryConfig: RetryConfig | null = null;\n\n  /**\n   * Timezone for scheduling (defaults to UTC)\n   */\n  private _timezone = \"UTC\";\n\n  /**\n   * Cron expression parser (mutually exclusive with interval config)\n   */\n  private _cronParser: CronParser | null = null;\n\n  /**\n   * All pending `waitForCompletion()` resolvers — drained on every run end.\n   */\n  private _completionResolvers: (() => void)[] = [];\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Public Properties\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Next scheduled execution time\n   */\n  public nextRun: Dayjs | null = null;\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Constructor\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Creates a new Job instance\n   *\n   * @param name - Unique identifier for the job\n   * @param callback - Function to execute when the job runs\n   */\n  public constructor(\n    public readonly name: string,\n    private readonly _callback: JobCallback,\n  ) {}\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Public Getters\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Returns true if the job is currently executing\n   */\n  public get isRunning(): boolean {\n    return this._isRunning;\n  }\n\n  /**\n   * Returns the last execution timestamp (success OR failure).\n   */\n  public get lastRun(): Dayjs | null {\n    return this._lastRun;\n  }\n\n  /**\n   * Returns the current interval configuration (readonly)\n   */\n  public get intervals(): Readonly<JobIntervals> {\n    return this._intervals;\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Interval Configuration Methods (Fluent API)\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Set a custom interval for job execution\n   *\n   * @param value - Number of time units (must be > 0)\n   * @param timeType - Type of time unit\n   * @returns this for chaining\n   * @throws Error if `value` is not a positive finite number\n   *\n   * @example\n   * ```typescript\n   * job.every(5, \"minute\"); // Run every 5 minutes\n   * job.every(2, \"hour\");   // Run every 2 hours\n   * ```\n   */\n  public every(value: number, timeType: TimeType): this {\n    if (!Number.isFinite(value) || value <= 0) {\n      throw new Error(\n        `Invalid interval value: ${value}. Must be a positive finite number.`,\n      );\n    }\n\n    this._intervals.every = { type: timeType, value };\n    this._determineNextRun();\n\n    return this;\n  }\n\n  /**\n   * Run job every second (use with caution - high frequency)\n   */\n  public everySecond(): this {\n    return this.every(1, \"second\");\n  }\n\n  /**\n   * Run job every specified number of seconds\n   */\n  public everySeconds(seconds: number): this {\n    return this.every(seconds, \"second\");\n  }\n\n  /**\n   * Run job every minute\n   */\n  public everyMinute(): this {\n    return this.every(1, \"minute\");\n  }\n\n  /**\n   * Run job every specified number of minutes\n   */\n  public everyMinutes(minutes: number): this {\n    return this.every(minutes, \"minute\");\n  }\n\n  /**\n   * Run job every hour\n   */\n  public everyHour(): this {\n    return this.every(1, \"hour\");\n  }\n\n  /**\n   * Run job every specified number of hours\n   */\n  public everyHours(hours: number): this {\n    return this.every(hours, \"hour\");\n  }\n\n  /**\n   * Run job every day at midnight\n   */\n  public everyDay(): this {\n    return this.every(1, \"day\");\n  }\n\n  /**\n   * Alias for everyDay()\n   */\n  public daily(): this {\n    return this.everyDay();\n  }\n\n  /**\n   * Run job twice a day (every 12 hours)\n   */\n  public twiceDaily(): this {\n    return this.every(12, \"hour\");\n  }\n\n  /**\n   * Run job every week\n   */\n  public everyWeek(): this {\n    return this.every(1, \"week\");\n  }\n\n  /**\n   * Alias for everyWeek()\n   */\n  public weekly(): this {\n    return this.everyWeek();\n  }\n\n  /**\n   * Run job every month\n   */\n  public everyMonth(): this {\n    return this.every(1, \"month\");\n  }\n\n  /**\n   * Alias for everyMonth()\n   */\n  public monthly(): this {\n    return this.everyMonth();\n  }\n\n  /**\n   * Run job every year\n   */\n  public everyYear(): this {\n    return this.every(1, \"year\");\n  }\n\n  /**\n   * Alias for everyYear()\n   */\n  public yearly(): this {\n    return this.everyYear();\n  }\n\n  /**\n   * Alias for everyMinute() - job runs continuously every minute\n   */\n  public always(): this {\n    return this.everyMinute();\n  }\n\n  /**\n   * Schedule job using a cron expression\n   *\n   * Supports standard 5-field cron syntax:\n   * ```\n   * ┌───────────── minute (0-59)\n   * │ ┌───────────── hour (0-23)\n   * │ │ ┌───────────── day of month (1-31)\n   * │ │ │ ┌───────────── month (1-12)\n   * │ │ │ │ ┌───────────── day of week (0-6, Sunday = 0)\n   * │ │ │ │ │\n   * * * * * *\n   * ```\n   *\n   * Supports:\n   * - '*' - any value\n   * - '5' - specific value\n   * - '1,3,5' - list of values\n   * - '1-5' - range of values\n   * - '*‍/5' - step values (every 5)\n   * - '1-10/2' - range with step\n   *\n   * @param expression - Standard 5-field cron expression\n   * @returns this for chaining\n   *\n   * @example\n   * ```typescript\n   * job.cron(\"0 9 * * 1-5\");   // 9 AM weekdays\n   * job.cron(\"*‍/5 * * * *\");   // Every 5 minutes\n   * job.cron(\"0 0 1 * *\");     // First day of month at midnight\n   * job.cron(\"0 *‍/2 * * *\");   // Every 2 hours\n   * ```\n   */\n  public cron(expression: string): this {\n    this._cronParser = new CronParser(expression);\n    // Clear interval config since cron takes precedence\n    this._intervals = {};\n    this._determineNextRun();\n    return this;\n  }\n\n  /**\n   * Get the cron expression if one is set\n   */\n  public get cronExpression(): string | null {\n    return this._cronParser?.expression ?? null;\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Day & Time Configuration Methods\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Schedule job on a specific day\n   *\n   * @param day - Day of week (string) or day of month (number 1-31)\n   * @returns this for chaining\n   *\n   * @example\n   * ```typescript\n   * job.on(\"monday\");  // Run on Mondays\n   * job.on(15);        // Run on the 15th of each month\n   * ```\n   */\n  public on(day: Day | number): this {\n    if (typeof day === \"number\" && (day < 1 || day > 31)) {\n      throw new Error(\"Invalid day of the month. Must be between 1 and 31.\");\n    }\n\n    this._intervals.day = day;\n\n    if (typeof day === \"number\") {\n      this._intervals.dayOfMonthMode = \"specific\";\n    }\n\n    this._determineNextRun();\n\n    return this;\n  }\n\n  /**\n   * Schedule job at a specific time\n   *\n   * @param time - Time in HH:mm or HH:mm:ss format\n   * @returns this for chaining\n   *\n   * @example\n   * ```typescript\n   * job.daily().at(\"09:00\");    // Run daily at 9 AM\n   * job.weekly().at(\"14:30\");   // Run weekly at 2:30 PM\n   * ```\n   */\n  public at(time: string): this {\n    parseTimeString(time);\n    this._intervals.time = time;\n    this._determineNextRun();\n\n    return this;\n  }\n\n  /**\n   * Run task at the beginning of the specified time period.\n   *\n   * - `\"day\"`   → 00:00 every day\n   * - `\"month\"` → 1st of every month at 00:00\n   * - `\"year\"`  → January 1st at 00:00 every year\n   *\n   * @param type - Time type (day, month, year)\n   */\n  public beginOf(type: TimeType): this {\n    switch (type) {\n      case \"day\":\n        this._intervals.every = { type: \"day\", value: 1 };\n        break;\n\n      case \"month\":\n        this._intervals.day = 1;\n        this._intervals.dayOfMonthMode = \"specific\";\n        this._intervals.every = { type: \"month\", value: 1 };\n        break;\n\n      case \"year\":\n        this._intervals.month = 1;\n        this._intervals.day = 1;\n        this._intervals.dayOfMonthMode = \"specific\";\n        this._intervals.every = { type: \"year\", value: 1 };\n        break;\n\n      default:\n        throw new Error(`Unsupported type for beginOf: ${type}`);\n    }\n\n    return this.at(\"00:00\");\n  }\n\n  /**\n   * Run task at the end of the specified time period.\n   *\n   * - `\"day\"`   → 23:59 every day\n   * - `\"month\"` → last day of every month at 23:59 (recomputed each cycle —\n   *   correct in February vs. March)\n   * - `\"year\"`  → December 31st at 23:59 every year\n   *\n   * @param type - Time type (day, month, year)\n   */\n  public endOf(type: TimeType): this {\n    switch (type) {\n      case \"day\":\n        this._intervals.every = { type: \"day\", value: 1 };\n        break;\n\n      case \"month\":\n        this._intervals.dayOfMonthMode = \"last\";\n        this._intervals.every = { type: \"month\", value: 1 };\n        break;\n\n      case \"year\":\n        this._intervals.month = 12;\n        this._intervals.day = 31;\n        this._intervals.dayOfMonthMode = \"specific\";\n        this._intervals.every = { type: \"year\", value: 1 };\n        break;\n\n      default:\n        throw new Error(`Unsupported type for endOf: ${type}`);\n    }\n\n    return this.at(\"23:59\");\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Timezone Configuration\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Set the timezone for this job's scheduling\n   *\n   * @param tz - IANA timezone string (e.g., \"America/New_York\", \"Europe/London\")\n   * @returns this for chaining\n   *\n   * @example\n   * ```typescript\n   * job.daily().at(\"09:00\").inTimezone(\"America/New_York\");\n   * ```\n   */\n  public inTimezone(tz: string): this {\n    this._timezone = tz;\n    this._determineNextRun();\n    return this;\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Execution Options\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Prevent overlapping executions of this job.\n   *\n   * When enabled, if the job is already running when it's scheduled to run again,\n   * the new execution will be skipped.\n   *\n   * @param skip - Whether to skip if already running (default: true)\n   * @returns this for chaining\n   */\n  public preventOverlap(skip = true): this {\n    this._skipIfRunning = skip;\n    return this;\n  }\n\n  /**\n   * Configure automatic retry on failure\n   *\n   * @param maxRetries - Maximum number of retry attempts (must be ≥ 0)\n   * @param delay - Delay between retries in milliseconds (must be ≥ 0)\n   * @param backoffMultiplier - Optional multiplier for exponential backoff (must be > 0)\n   * @returns this for chaining\n   *\n   * @example\n   * ```typescript\n   * job.retry(3, 1000);           // Retry 3 times with 1s delay\n   * job.retry(5, 1000, 2);        // Exponential backoff: 1s, 2s, 4s, 8s, 16s\n   * ```\n   */\n  public retry(maxRetries: number, delay = 1000, backoffMultiplier?: number): this {\n    if (!Number.isFinite(maxRetries) || maxRetries < 0) {\n      throw new Error(`Invalid maxRetries: ${maxRetries}. Must be ≥ 0.`);\n    }\n\n    if (!Number.isFinite(delay) || delay < 0) {\n      throw new Error(`Invalid retry delay: ${delay}. Must be ≥ 0.`);\n    }\n\n    if (\n      backoffMultiplier !== undefined &&\n      (!Number.isFinite(backoffMultiplier) || backoffMultiplier <= 0)\n    ) {\n      throw new Error(\n        `Invalid backoffMultiplier: ${backoffMultiplier}. Must be > 0.`,\n      );\n    }\n\n    this._retryConfig = {\n      maxRetries,\n      delay,\n      backoffMultiplier,\n    };\n\n    return this;\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Execution Control\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Terminate the job and clear all scheduling data\n   */\n  public terminate(): this {\n    this._intervals = {};\n    this._cronParser = null;\n    this.nextRun = null;\n    this._lastRun = null;\n    this._isRunning = false;\n    return this;\n  }\n\n  /**\n   * Prepare the job by calculating the next run time\n   * Called by the scheduler when starting\n   */\n  public prepare(): void {\n    this._determineNextRun();\n  }\n\n  /**\n   * Returns true if the job's `nextRun` has arrived, regardless of whether\n   * it is currently running. Used by the scheduler to decide whether a\n   * tick is \"due\" before checking overlap state.\n   */\n  public isDue(): boolean {\n    return this.nextRun !== null && this._now().isSameOrAfter(this.nextRun);\n  }\n\n  /**\n   * Determine if the job should run now.\n   *\n   * Combines `isDue()` with the overlap-prevention rule: when\n   * `preventOverlap()` is on and the job is already running, this returns\n   * false even if the next-run time has arrived.\n   *\n   * @returns true if the job should execute\n   */\n  public shouldRun(): boolean {\n    if (this._skipIfRunning && this._isRunning) {\n      return false;\n    }\n\n    return this.isDue();\n  }\n\n  /**\n   * Execute the job once.\n   *\n   * Always advances `lastRun` and recalculates `nextRun` (success OR failure)\n   * so a permanently failing job does not re-fire on every scheduler tick.\n   *\n   * @returns Promise resolving to the job result\n   */\n  public async run(): Promise<JobResult> {\n    const startTime = Date.now();\n\n    this._isRunning = true;\n\n    let result: JobResult;\n    let executedRetries = 0;\n\n    try {\n      const inner = await this._executeWithRetry();\n      executedRetries = inner.retries;\n\n      result = {\n        success: true,\n        duration: Date.now() - startTime,\n        retries: executedRetries,\n      };\n    } catch (error) {\n      result = {\n        success: false,\n        duration: Date.now() - startTime,\n        error,\n        retries: this._retryConfig?.maxRetries ?? 0,\n      };\n    } finally {\n      this._lastRun = this._now();\n      this._determineNextRun();\n      this._isRunning = false;\n\n      // Drain ALL pending waiters (waitForCompletion may be called more than once).\n      const resolvers = this._completionResolvers.splice(0);\n\n      for (const resolve of resolvers) {\n        resolve();\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Wait for the currently executing run to complete.\n   *\n   * Multiple concurrent waiters are all resolved when the run finishes.\n   * Useful for graceful shutdown.\n   *\n   * @returns Promise that resolves when the job completes\n   */\n  public waitForCompletion(): Promise<void> {\n    if (!this._isRunning) {\n      return Promise.resolve();\n    }\n\n    return new Promise(resolve => {\n      this._completionResolvers.push(resolve);\n    });\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Private Methods\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Get current time, respecting the configured timezone.\n   */\n  private _now(): Dayjs {\n    return dayjs().tz(this._timezone);\n  }\n\n  /**\n   * Execute the callback with retry logic\n   */\n  private async _executeWithRetry(): Promise<{ retries: number }> {\n    let lastError: unknown;\n    let attempts = 0;\n    const maxAttempts = (this._retryConfig?.maxRetries ?? 0) + 1;\n\n    while (attempts < maxAttempts) {\n      try {\n        await this._callback(this);\n        return { retries: attempts };\n      } catch (error) {\n        lastError = error;\n        attempts++;\n\n        if (attempts < maxAttempts && this._retryConfig) {\n          const delay = this._calculateRetryDelay(attempts);\n          await this._sleep(delay);\n        }\n      }\n    }\n\n    throw lastError;\n  }\n\n  /**\n   * Calculate retry delay with optional exponential backoff\n   */\n  private _calculateRetryDelay(attempt: number): number {\n    if (!this._retryConfig) return 0;\n\n    const { delay, backoffMultiplier } = this._retryConfig;\n\n    if (backoffMultiplier) {\n      return delay * Math.pow(backoffMultiplier, attempt - 1);\n    }\n\n    return delay;\n  }\n\n  /**\n   * Sleep for specified milliseconds\n   */\n  private _sleep(ms: number): Promise<void> {\n    return new Promise(resolve => setTimeout(resolve, ms));\n  }\n\n  /**\n   * Apply month / day-of-month / day-of-week / time constraints to a Dayjs.\n   *\n   * Re-applied after every interval advance inside `_determineNextRun` so\n   * dynamic constraints (`dayOfMonthMode: \"last\"` recomputed per month, month\n   * lock for `beginOf/endOf(\"year\")`) stay correct as the candidate moves\n   * forward.\n   */\n  private _applyConstraints(date: Dayjs): Dayjs {\n    let result = date;\n\n    if (this._intervals.month !== undefined) {\n      result = result.month(this._intervals.month - 1);\n    }\n\n    if (this._intervals.dayOfMonthMode === \"last\") {\n      result = result.date(result.daysInMonth());\n    } else if (this._intervals.day !== undefined) {\n      if (typeof this._intervals.day === \"number\") {\n        result = result.date(this._intervals.day);\n      } else {\n        const targetDay = DAYS_OF_WEEK.indexOf(this._intervals.day);\n\n        if (targetDay !== -1) {\n          result = result.day(targetDay);\n        }\n      }\n    }\n\n    if (this._intervals.time) {\n      const { hour, minute, second } = parseTimeString(this._intervals.time);\n      result = result.hour(hour).minute(minute).second(second).millisecond(0);\n    }\n\n    return result;\n  }\n\n  /**\n   * Calculate the next run time based on interval or cron configuration.\n   *\n   * Strategy: apply all constraints (month, day, time) ONCE before the\n   * advance loop, then advance by `every` until the candidate is in the\n   * future. Static constraints (numeric day, fixed month, fixed time)\n   * survive `dayjs.add()` automatically. The only dynamic constraint —\n   * `dayOfMonthMode: \"last\"` — is re-applied inside the loop so the\n   * candidate always lands on the *new* month's last day after each\n   * advance.\n   *\n   * Re-applying time/day inside the loop would deadlock: with\n   * `twiceDaily().at(\"06:00\")` we'd advance 06:00 → 18:00 → snap back to\n   * 06:00 → 18:00 → ... forever.\n   */\n  private _determineNextRun(): void {\n    if (this._cronParser) {\n      const now = this._now();\n      this.nextRun = this._cronParser.nextRun(now);\n      return;\n    }\n\n    const intervalValue = this._intervals.every?.value;\n    const intervalType = this._intervals.every?.type;\n    const hasInterval = !!(intervalValue && intervalType);\n\n    // After a previous run, jump ahead by EXACTLY one interval. Previously\n    // we used `lastRun + 1s` and relied on the advance loop to catch up,\n    // but that loop only triggers when the candidate is in the past — so\n    // for fast-completing callbacks the candidate stayed at `lastRun + 1s`,\n    // making `everySeconds(2)` fire every second. Honor the interval up\n    // front instead.\n    let date: Dayjs;\n\n    if (this._lastRun && hasInterval) {\n      date = this._lastRun.add(intervalValue!, intervalType);\n    } else if (this._lastRun) {\n      date = this._lastRun.add(1, \"second\");\n    } else {\n      date = this._now();\n    }\n\n    date = this._applyConstraints(date);\n\n    while (date.isBefore(this._now())) {\n      if (hasInterval) {\n        date = date.add(intervalValue!, intervalType);\n      } else {\n        date = date.add(1, \"day\");\n      }\n\n      if (this._intervals.dayOfMonthMode === \"last\") {\n        date = date.date(date.daysInMonth());\n      }\n    }\n\n    this.nextRun = date;\n  }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Factory Function\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Factory function to create a new Job instance\n *\n * @param name - Unique identifier for the job\n * @param callback - Function to execute when the job runs\n * @returns New Job instance\n *\n * @example\n * ```typescript\n * const cleanupJob = job(\"cleanup\", async () => {\n *   await db.deleteExpiredTokens();\n * }).daily().at(\"03:00\");\n * ```\n */\nexport function job(name: string, callback: JobCallback): Job {\n  return new Job(name, callback);\n}\n"],"mappings":"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"}

package/esm/scheduler.d.mts

@@ -0,0 +1,193 @@
+import { SchedulerEvents } from "./types.mjs";
+import { Job, JobCallback } from "./job.mjs";
+
+//#region ../../@warlock.js/scheduler/src/scheduler.d.ts
+/**
+ * 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());
+ * ```
+ */
+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.
+   *
+   * If the scheduler is already running, every newly-added job is prepared
+   * (its initial `nextRun` is computed) so it begins firing on the next tick.
+   *
+   * @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.
+   *
+   * No-op if the scheduler isn't running. Does not wait for in-flight jobs —
+   * 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.
+   *
+   * Drift-compensated: after each tick, the next delay is `tickInterval -
+   * elapsed-tick-time` (clamped to 0). A tick that takes 600 ms on a 1 000 ms
+   * interval will be followed by a 400 ms delay so the *period* between tick
+   * starts averages `tickInterval` instead of `tickInterval + work-time`.
+   */
+  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();
+ * ```
+ */
+declare const scheduler: Scheduler;
+//#endregion
+export { Scheduler, scheduler };
+//# sourceMappingURL=scheduler.d.mts.map

package/esm/scheduler.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.mts","names":[],"sources":["../../../../../@warlock.js/scheduler/src/scheduler.ts"],"mappings":";;;;;;AAE0D;UAKhD,iBAAA,iBAAkC,MAAA;EAC1C,EAAA,iBAAmB,OAAA,EAAS,KAAA,EAAO,CAAA,EAAG,QAAA,MAAc,IAAA,EAAM,OAAA,CAAQ,CAAA;EAClE,IAAA,iBAAqB,OAAA,EAAS,KAAA,EAAO,CAAA,EAAG,QAAA,MAAc,IAAA,EAAM,OAAA,CAAQ,CAAA;EACpE,GAAA,iBAAoB,OAAA,EAAS,KAAA,EAAO,CAAA,EAAG,QAAA,MAAc,IAAA,EAAM,OAAA,CAAQ,CAAA;EACnE,IAAA,iBAAqB,OAAA,EAAS,KAAA,EAAO,CAAA,KAAM,IAAA,EAAM,OAAA,CAAQ,CAAA;AAAA;AAAA,cAAC,cAAA,YA+BvB,iBAAiB,CAAC,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAD1C,SAAA,SACH,cAAA,YACG,iBAAA,CAAkB,eAAA;EAlCQ;;;EAAA,QA2C7B,KAAA;EA3C4D;;;EAAA,QAgD5D,UAAA;EA/CY;;;EAAA,QAoDZ,aAAA;EApDmD;;;EAAA,QAyDnD,cAAA;EAxDH;;;EAAA,QA6DG,eAAA;EA7DmC;;;EAAA,QAkEnC,eAAA;EAlEkD;AAAA;;EAAA,IA2E/C,SAAA,CAAA;EA5CwB;AAAiC;AADtE;EACqC,IAmDxB,QAAA,CAAA;;;;;;;EAcJ,MAAA,CAAO,GAAA,EAAK,GAAA;EAwEK;;;EA3DjB,MAAA,CAAO,IAAA,UAAc,WAAA,EAAa,WAAA,GAAW,GAAA;EA7ExB;;;;;;;;;EA4FrB,OAAA,CAAQ,IAAA,EAAM,GAAA;EA1Db;;;;;;EA4ED,SAAA,CAAU,OAAA;EAjCH;;;;;;EAkDP,MAAA,CAAO,OAAA,WAAkB,GAAA;EAjBzB;;;;;EA0BA,IAAA,CAAA,YAAiB,GAAA;EAAA;;;;;;EAUjB,QAAA,CAAS,EAAA;EAwDT;;;;;;;EAxCA,aAAA,CAAc,QAAA,WAAmB,cAAA;EA2J1B;;AAAO;AA8BvB;;EA1KS,KAAA,CAAA;EA0K+B;AAAA;;;;;EAjJ/B,IAAA,CAAA;;;;;;;;;EAiBM,QAAA,CAAS,OAAA,YAAkB,OAAA;;;;;;;;;UA0BhC,aAAA;;;;UAkBM,KAAA;;;;UA4BA,oBAAA;;;;UAUA,kBAAA;;;;UAgBA,OAAA;AAAA;;;;;;;;;;;;cA8BH,SAAA,EAAS,SAAkB"}

package/esm/scheduler.mjs

@@ -0,0 +1,261 @@
+import { Job } from "./job.mjs";
+import { EventEmitter } from "node:events";
+
+//#region ../../@warlock.js/scheduler/src/scheduler.ts
+/**
+* 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());
+* ```
+*/
+var Scheduler = class extends EventEmitter {
+	constructor(..._args) {
+		super(..._args);
+		this._jobs = [];
+		this._timeoutId = null;
+		this._tickInterval = 1e3;
+		this._runInParallel = false;
+		this._maxConcurrency = 10;
+		this._isShuttingDown = false;
+	}
+	/**
+	* 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;
+	}
+	/**
+	* Add a job to the scheduler
+	*
+	* @param job - Job instance to schedule
+	* @returns this for chaining
+	*/
+	addJob(job) {
+		this._jobs.push(job);
+		if (this.isRunning) job.prepare();
+		return this;
+	}
+	/**
+	* Alias to create a new job directly and store it
+	*/
+	newJob(name, jobCallback) {
+		const job = new Job(name, jobCallback);
+		this.addJob(job);
+		return job;
+	}
+	/**
+	* Add multiple jobs to the scheduler.
+	*
+	* If the scheduler is already running, every newly-added job is prepared
+	* (its initial `nextRun` is computed) so it begins firing on the next tick.
+	*
+	* @param jobs - Array of Job instances
+	* @returns this for chaining
+	*/
+	addJobs(jobs) {
+		this._jobs.push(...jobs);
+		if (this.isRunning) for (const job of jobs) job.prepare();
+		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;
+	}
+	/**
+	* 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 job of this._jobs) job.prepare();
+		this._isShuttingDown = false;
+		this._scheduleTick(this._tickInterval);
+		this.emit("scheduler:started");
+	}
+	/**
+	* Stop the scheduler immediately.
+	*
+	* No-op if the scheduler isn't running. Does not wait for in-flight jobs —
+	* use `shutdown()` for graceful termination.
+	*/
+	stop() {
+		if (!this._timeoutId) return;
+		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))]);
+	}
+	/**
+	* Schedule the next tick.
+	*
+	* Drift-compensated: after each tick, the next delay is `tickInterval -
+	* elapsed-tick-time` (clamped to 0). A tick that takes 600 ms on a 1 000 ms
+	* interval will be followed by a 400 ms delay so the *period* between tick
+	* starts averages `tickInterval` instead of `tickInterval + work-time`.
+	*/
+	_scheduleTick(delay) {
+		if (this._isShuttingDown) return;
+		this._timeoutId = setTimeout(async () => {
+			const tickStart = Date.now();
+			await this._tick();
+			const elapsed = Date.now() - tickStart;
+			const nextDelay = Math.max(this._tickInterval - elapsed, 0);
+			this._scheduleTick(nextDelay);
+		}, delay);
+	}
+	/**
+	* Execute a scheduler tick - check and run due jobs
+	*/
+	async _tick() {
+		this.emit("scheduler:tick", /* @__PURE__ */ new Date());
+		const dueJobs = this._jobs.filter((job) => {
+			if (!job.isDue()) return false;
+			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) {
+		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 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();
+
+//#endregion
+export { Scheduler, scheduler };
+//# sourceMappingURL=scheduler.mjs.map

package/esm/scheduler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.mjs","names":[],"sources":["../../../../../@warlock.js/scheduler/src/scheduler.ts"],"sourcesContent":["import { EventEmitter } from \"node:events\";\nimport { Job, JobCallback } from \"./job\";\nimport type { JobResult, SchedulerEvents } from \"./types\";\n\n/**\n * Type-safe event emitter interface for Scheduler events\n */\ninterface TypedEventEmitter<TEvents extends Record<string, unknown[]>> {\n  on<K extends keyof TEvents>(event: K, listener: (...args: TEvents[K]) => void): this;\n  once<K extends keyof TEvents>(event: K, listener: (...args: TEvents[K]) => void): this;\n  off<K extends keyof TEvents>(event: K, listener: (...args: TEvents[K]) => void): this;\n  emit<K extends keyof TEvents>(event: K, ...args: TEvents[K]): boolean;\n}\n\n/**\n * Scheduler class manages and executes scheduled jobs.\n *\n * Features:\n * - Event-based observability\n * - Parallel or sequential job execution\n * - Drift compensation for accurate timing\n * - Graceful shutdown with job draining\n *\n * @example\n * ```typescript\n * const scheduler = new Scheduler();\n *\n * scheduler.on('job:error', (jobName, error) => {\n *   logger.error(`Job ${jobName} failed:`, error);\n * });\n *\n * scheduler\n *   .addJob(cleanupJob)\n *   .addJob(reportJob)\n *   .runInParallel(true)\n *   .start();\n *\n * // Graceful shutdown\n * process.on('SIGTERM', () => scheduler.shutdown());\n * ```\n */\nexport class Scheduler\n  extends (EventEmitter as new () => TypedEventEmitter<SchedulerEvents>)\n  implements TypedEventEmitter<SchedulerEvents>\n{\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Private Properties\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * List of registered jobs\n   */\n  private _jobs: Job[] = [];\n\n  /**\n   * Reference to the current timeout for stopping\n   */\n  private _timeoutId: NodeJS.Timeout | null = null;\n\n  /**\n   * Tick interval in milliseconds (how often to check for due jobs)\n   */\n  private _tickInterval = 1000;\n\n  /**\n   * Whether to run due jobs in parallel\n   */\n  private _runInParallel = false;\n\n  /**\n   * Maximum concurrent jobs when running in parallel\n   */\n  private _maxConcurrency = 10;\n\n  /**\n   * Flag indicating scheduler is shutting down\n   */\n  private _isShuttingDown = false;\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Public Getters\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Returns true if the scheduler is currently running\n   */\n  public get isRunning(): boolean {\n    return this._timeoutId !== null;\n  }\n\n  /**\n   * Returns the number of registered jobs\n   */\n  public get jobCount(): number {\n    return this._jobs.length;\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Configuration Methods (Fluent API)\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Add a job to the scheduler\n   *\n   * @param job - Job instance to schedule\n   * @returns this for chaining\n   */\n  public addJob(job: Job): this {\n    this._jobs.push(job);\n\n    if (this.isRunning) {\n      job.prepare();\n    }\n\n    return this;\n  }\n\n  /**\n   * Alias to create a new job directly and store it\n   */\n  public newJob(name: string, jobCallback: JobCallback) {\n    const job = new Job(name, jobCallback);\n    this.addJob(job);\n    return job;\n  }\n\n  /**\n   * Add multiple jobs to the scheduler.\n   *\n   * If the scheduler is already running, every newly-added job is prepared\n   * (its initial `nextRun` is computed) so it begins firing on the next tick.\n   *\n   * @param jobs - Array of Job instances\n   * @returns this for chaining\n   */\n  public addJobs(jobs: Job[]): this {\n    this._jobs.push(...jobs);\n\n    if (this.isRunning) {\n      for (const job of jobs) {\n        job.prepare();\n      }\n    }\n\n    return this;\n  }\n\n  /**\n   * Remove a job from the scheduler by name\n   *\n   * @param jobName - Name of the job to remove\n   * @returns true if job was found and removed\n   */\n  public removeJob(jobName: string): boolean {\n    const index = this._jobs.findIndex(j => j.name === jobName);\n\n    if (index !== -1) {\n      this._jobs.splice(index, 1);\n      return true;\n    }\n\n    return false;\n  }\n\n  /**\n   * Get a job by name\n   *\n   * @param jobName - Name of the job to find\n   * @returns Job instance or undefined\n   */\n  public getJob(jobName: string): Job | undefined {\n    return this._jobs.find(j => j.name === jobName);\n  }\n\n  /**\n   * Get all registered jobs\n   *\n   * @returns Array of registered jobs (readonly)\n   */\n  public list(): readonly Job[] {\n    return this._jobs;\n  }\n\n  /**\n   * Set the tick interval (how often to check for due jobs)\n   *\n   * @param ms - Interval in milliseconds (minimum 100ms)\n   * @returns this for chaining\n   */\n  public runEvery(ms: number): this {\n    if (ms < 100) {\n      throw new Error(\"Tick interval must be at least 100ms\");\n    }\n\n    this._tickInterval = ms;\n    return this;\n  }\n\n  /**\n   * Configure whether jobs should run in parallel\n   *\n   * @param parallel - Enable parallel execution\n   * @param maxConcurrency - Maximum concurrent jobs (default: 10)\n   * @returns this for chaining\n   */\n  public runInParallel(parallel: boolean, maxConcurrency = 10): this {\n    this._runInParallel = parallel;\n    this._maxConcurrency = maxConcurrency;\n    return this;\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Lifecycle Methods\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Start the scheduler\n   *\n   * @throws Error if scheduler is already running\n   */\n  public start(): void {\n    if (this.isRunning) {\n      throw new Error(\"Scheduler is already running.\");\n    }\n\n    if (this._jobs.length === 0) {\n      throw new Error(\"Cannot start scheduler with no jobs.\");\n    }\n\n    for (const job of this._jobs) {\n      job.prepare();\n    }\n\n    this._isShuttingDown = false;\n    this._scheduleTick(this._tickInterval);\n\n    this.emit(\"scheduler:started\");\n  }\n\n  /**\n   * Stop the scheduler immediately.\n   *\n   * No-op if the scheduler isn't running. Does not wait for in-flight jobs —\n   * use `shutdown()` for graceful termination.\n   */\n  public stop(): void {\n    if (!this._timeoutId) return;\n\n    clearTimeout(this._timeoutId);\n    this._timeoutId = null;\n\n    this.emit(\"scheduler:stopped\");\n  }\n\n  /**\n   * Gracefully shutdown the scheduler\n   *\n   * Stops scheduling new jobs and waits for currently running jobs to complete.\n   *\n   * @param timeout - Maximum time to wait for jobs (default: 30000ms)\n   * @returns Promise that resolves when shutdown is complete\n   */\n  public async shutdown(timeout = 30000): Promise<void> {\n    this._isShuttingDown = true;\n    this.stop();\n\n    const runningJobs = this._jobs.filter(j => j.isRunning);\n\n    if (runningJobs.length > 0) {\n      await Promise.race([\n        Promise.all(runningJobs.map(j => j.waitForCompletion())),\n        new Promise<void>(resolve => setTimeout(resolve, timeout)),\n      ]);\n    }\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────────\n  // Private Methods\n  // ─────────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Schedule the next tick.\n   *\n   * Drift-compensated: after each tick, the next delay is `tickInterval -\n   * elapsed-tick-time` (clamped to 0). A tick that takes 600 ms on a 1 000 ms\n   * interval will be followed by a 400 ms delay so the *period* between tick\n   * starts averages `tickInterval` instead of `tickInterval + work-time`.\n   */\n  private _scheduleTick(delay: number): void {\n    if (this._isShuttingDown) return;\n\n    this._timeoutId = setTimeout(async () => {\n      const tickStart = Date.now();\n\n      await this._tick();\n\n      const elapsed = Date.now() - tickStart;\n      const nextDelay = Math.max(this._tickInterval - elapsed, 0);\n\n      this._scheduleTick(nextDelay);\n    }, delay);\n  }\n\n  /**\n   * Execute a scheduler tick - check and run due jobs\n   */\n  private async _tick(): Promise<void> {\n    this.emit(\"scheduler:tick\", new Date());\n\n    const dueJobs = this._jobs.filter(job => {\n      // Time-based readiness only; running state is checked below so a\n      // `job:skip` event fires whenever overlap blocks a due run.\n      if (!job.isDue()) return false;\n\n      if (job.isRunning) {\n        this.emit(\"job:skip\", job.name, \"Job is already running\");\n        return false;\n      }\n\n      return true;\n    });\n\n    if (dueJobs.length === 0) return;\n\n    if (this._runInParallel) {\n      await this._runJobsInParallel(dueJobs);\n    } else {\n      await this._runJobsSequentially(dueJobs);\n    }\n  }\n\n  /**\n   * Run jobs sequentially\n   */\n  private async _runJobsSequentially(jobs: Job[]): Promise<void> {\n    for (const job of jobs) {\n      if (this._isShuttingDown) break;\n      await this._runJob(job);\n    }\n  }\n\n  /**\n   * Run jobs in parallel with concurrency limit\n   */\n  private async _runJobsInParallel(jobs: Job[]): Promise<void> {\n    const batches: Job[][] = [];\n\n    for (let i = 0; i < jobs.length; i += this._maxConcurrency) {\n      batches.push(jobs.slice(i, i + this._maxConcurrency));\n    }\n\n    for (const batch of batches) {\n      if (this._isShuttingDown) break;\n      await Promise.allSettled(batch.map(job => this._runJob(job)));\n    }\n  }\n\n  /**\n   * Run a single job and emit events\n   */\n  private async _runJob(job: Job): Promise<JobResult> {\n    this.emit(\"job:start\", job.name);\n\n    const result = await job.run();\n\n    if (result.success) {\n      this.emit(\"job:complete\", job.name, result);\n    } else {\n      this.emit(\"job:error\", job.name, result.error);\n    }\n\n    return result;\n  }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Default Export\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Default scheduler instance for simple use cases\n *\n * @example\n * ```typescript\n * import { scheduler, job } from \"@warlock.js/scheduler\";\n *\n * scheduler.addJob(job(\"cleanup\", cleanupFn).daily());\n * scheduler.start();\n * ```\n */\nexport const scheduler = new Scheduler();\n"],"mappings":"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"}

package/esm/types.d.mts

@@ -0,0 +1,70 @@
+//#region ../../@warlock.js/scheduler/src/types.d.ts
+/**
+ * Time unit types for scheduling intervals
+ */
+type TimeType = "second" | "minute" | "hour" | "day" | "week" | "month" | "year";
+/**
+ * Days of the week (lowercase for consistency)
+ */
+type Day = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
+/**
+ * How the day-of-month constraint is interpreted.
+ *
+ * - `"specific"` — `day` is a fixed day number (1–31).
+ * - `"last"` — recompute each cycle as the last day of the current month
+ *   (so `endOf("month")` is correct in February vs. March).
+ */
+type DayOfMonthMode = "specific" | "last";
+/**
+ * Job interval configuration
+ */
+type JobIntervals = {
+  /** Day of week (string) or day of month (1–31) */day?: Day | number;
+  /**
+   * Day-of-month interpretation. Defaults to `"specific"` when `day` is a
+   * number. `"last"` overrides `day` and resolves to `daysInMonth()` per cycle.
+   */
+  dayOfMonthMode?: DayOfMonthMode; /** Month constraint (1–12). Used by `beginOf`/`endOf` of `"year"`. */
+  month?: number; /** Time of day in HH:mm or HH:mm:ss format */
+  time?: string; /** Recurring interval configuration */
+  every?: {
+    type?: TimeType;
+    value?: number;
+  };
+};
+/**
+ * Result of a job execution
+ */
+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
+ */
+type JobStatus = "idle" | "running" | "completed" | "failed";
+/**
+ * Retry configuration for jobs
+ */
+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
+ */
+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];
+};
+//#endregion
+export { Day, JobIntervals, JobResult, JobStatus, RetryConfig, SchedulerEvents, TimeType };
+//# sourceMappingURL=types.d.mts.map

package/esm/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../@warlock.js/scheduler/src/types.ts"],"mappings":";;AAGA;;KAAY,QAAA;;AAAQ;AAKpB;KAAY,GAAA;;;AAAG;AAgBf;;;;KAAY,cAAA;AAKZ;;;AAAA,KAAY,YAAA;EAOO,kDALjB,GAAA,GAAM,GAAA;EAYW;;;;EAPjB,cAAA,GAAiB,cAAA,EAAA;EAEjB,KAAA,WAEA;EAAA,IAAA,WAGE;EADF,KAAA;IACE,IAAA,GAAO,QAAA;IACP,KAAA;EAAA;AAAA;;;;KAOQ,SAAA;EAIV,6CAFA,OAAA,WAMA;EAJA,QAAA,UAIO;EAFP,KAAA,YAQmB;EANnB,OAAA;AAAA;AAMmB;AAKrB;;AALqB,KAAT,SAAA;;;;KAKA,WAAA;EAMO,uCAJjB,UAAA,UAUU;EARV,KAAA;EAEA,iBAAA;AAAA;;;;KAMU,eAAA;EACV,WAAA,GAAc,OAAA;EACd,cAAA,GAAiB,OAAA,UAAiB,MAAA,EAAQ,SAAA;EAC1C,WAAA,GAAc,OAAA,UAAiB,KAAA;EAC/B,UAAA,GAAa,OAAA,UAAiB,MAAA;EAC9B,mBAAA;EACA,mBAAA;EACA,gBAAA,GAAmB,SAAA,EAAW,IAAI;AAAA"}