@gravito/horizon 3.0.0 → 3.2.0

package/dist/index.js

@@ -1,128 +1,118 @@
 import "./chunk-MCKGQKYU.js";
 
 // src/SimpleCronParser.ts
-var SimpleCronParser = {
-  /**
-   * Check if a cron expression matches the given date.
-   * Only supports standard 5-field cron expressions.
-   *
-   * Fields: minute hour day-of-month month day-of-week
-   * Values:
-   *  - * (any)
-   *  - numbers (0-59, 1-31, 0-11, 0-7)
-   *  - ranges (1-5)
-   *  - lists (1,2,3)
-   *  - steps (*\/5, 1-10/2)
-   */
-  isDue(expression, timezone, date) {
-    const fields = expression.trim().split(/\s+/);
-    if (fields.length !== 5) {
-      throw new Error("SimpleCronParser only supports 5-field cron expressions");
-    }
-    let targetDate = date;
-    if (timezone && timezone !== "UTC") {
-      try {
-        const parts = new Intl.DateTimeFormat("en-US", {
-          timeZone: timezone,
-          year: "numeric",
-          month: "numeric",
-          day: "numeric",
-          hour: "numeric",
-          minute: "numeric",
-          second: "numeric",
-          hour12: false
-        }).formatToParts(date);
-        const partMap = {};
-        parts.forEach((p) => {
-          partMap[p.type] = p.value;
-        });
-        targetDate = new Date(
-          parseInt(partMap.year ?? "0", 10),
-          parseInt(partMap.month ?? "1", 10) - 1,
-          parseInt(partMap.day ?? "1", 10),
-          parseInt(partMap.hour ?? "0", 10) === 24 ? 0 : parseInt(partMap.hour ?? "0", 10),
-          parseInt(partMap.minute ?? "0", 10),
-          0
-        );
-      } catch (_e) {
-        throw new Error(`Invalid timezone: ${timezone}`);
-      }
-    } else if (timezone === "UTC") {
-      targetDate = new Date(
-        date.getUTCFullYear(),
-        date.getUTCMonth(),
-        date.getUTCDate(),
-        date.getUTCHours(),
-        date.getUTCMinutes(),
-        0
-      );
-    }
-    const [minute, hour, dayOfMonth, month, dayOfWeek] = fields;
-    if (minute === void 0 || hour === void 0 || dayOfMonth === void 0 || month === void 0 || dayOfWeek === void 0) {
-      throw new Error("Invalid cron expression");
+var SimpleCronParser = class {
+  /**
+   * Evaluates if a cron expression matches the specified date and timezone.
+   *
+   * @param expression - Standard 5-part cron expression.
+   * @param timezone - Target timezone for comparison (default: "UTC").
+   * @param date - Reference date to check (default: now).
+   * @returns True if the expression is due at the given minute.
+   * @throws {Error} If the expression is malformed or the timezone is invalid.
+   *
+   * @example
+   * ```typescript
+   * const isDue = SimpleCronParser.isDue('0 * * * *', 'Asia/Taipei');
+   * ```
+   */
+  static isDue(expression, timezone = "UTC", date = /* @__PURE__ */ new Date()) {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5) {
+      throw new Error(`Invalid cron expression: ${expression}`);
     }
-    const matchMinute = matchField(minute, targetDate.getMinutes(), 0, 59);
-    const matchHour = matchField(hour, targetDate.getHours(), 0, 23);
-    const matchDayOfMonth = matchField(dayOfMonth, targetDate.getDate(), 1, 31);
-    const matchMonth = matchField(month, targetDate.getMonth() + 1, 1, 12);
-    const matchDayOfWeek = matchField(dayOfWeek, targetDate.getDay(), 0, 7);
-    return matchMinute && matchHour && matchDayOfMonth && matchMonth && matchDayOfWeek;
-  }
-};
-function matchField(pattern, value, min, max) {
-  if (pattern === "*") {
-    return true;
+    const targetDate = this.getDateInTimezone(date, timezone);
+    const minutes = targetDate.getMinutes();
+    const hours = targetDate.getHours();
+    const dayOfMonth = targetDate.getDate();
+    const month = targetDate.getMonth() + 1;
+    const dayOfWeek = targetDate.getDay();
+    return this.match(parts[0], minutes, 0, 59) && this.match(parts[1], hours, 0, 23) && this.match(parts[2], dayOfMonth, 1, 31) && this.match(parts[3], month, 1, 12) && this.match(parts[4], dayOfWeek, 0, 6, true);
   }
-  if (pattern.includes("/")) {
-    const [range, stepStr] = pattern.split("/");
-    if (range === void 0 || stepStr === void 0) {
-      return false;
+  /**
+   * Internal pattern matching logic for individual cron fields.
+   *
+   * @param pattern - Cron sub-expression (e.g., "1-5").
+   * @param value - Extracted date component value.
+   * @param _min - Field minimum boundary.
+   * @param _max - Field maximum boundary.
+   * @param isDayOfWeek - Special handling for Sunday (0 and 7).
+   * @returns Boolean indicating a match.
+   *
+   * @internal
+   */
+  static match(pattern, value, _min, _max, isDayOfWeek = false) {
+    if (pattern === "*") {
+      return true;
     }
-    const step = parseInt(stepStr, 10);
-    if (range === "*") {
-      return (value - min) % step === 0;
+    if (pattern.includes(",")) {
+      return pattern.split(",").some((p) => this.match(p, value, _min, _max, isDayOfWeek));
     }
-    if (range.includes("-")) {
-      const [startStr, endStr] = range.split("-");
-      if (startStr === void 0 || endStr === void 0) {
-        return false;
-      }
-      const start = parseInt(startStr, 10);
-      const end = parseInt(endStr, 10);
-      if (value >= start && value <= end) {
-        return (value - start) % step === 0;
+    const stepMatch = pattern.match(/^(\*|\d+(-\d+)?)\/(\d+)$/);
+    if (stepMatch) {
+      const range = stepMatch[1];
+      const step = parseInt(stepMatch[3], 10);
+      if (range === "*") {
+        return value % step === 0;
       }
-      return false;
+      const [rMin, rMax] = range.split("-").map((n) => parseInt(n, 10));
+      return value >= rMin && value <= rMax && (value - rMin) % step === 0;
     }
-  }
-  if (pattern.includes(",")) {
-    const parts = pattern.split(",");
-    return parts.some((part) => matchField(part, value, min, max));
-  }
-  if (pattern.includes("-")) {
-    const [startStr, endStr] = pattern.split("-");
-    if (startStr === void 0 || endStr === void 0) {
-      return false;
+    if (pattern.includes("-")) {
+      const [rMin, rMax] = pattern.split("-").map((n) => parseInt(n, 10));
+      return value >= rMin && value <= rMax;
+    }
+    const patternVal = parseInt(pattern, 10);
+    if (isDayOfWeek && patternVal === 7 && value === 0) {
+      return true;
     }
-    const start = parseInt(startStr, 10);
-    const end = parseInt(endStr, 10);
-    return value >= start && value <= end;
+    return patternVal === value;
   }
-  const expected = parseInt(pattern, 10);
-  if (max === 7 && expected === 7 && value === 0) {
-    return true;
+  /**
+   * Resolves a Date object to the specified timezone.
+   *
+   * @param date - Source UTC date.
+   * @param timezone - Target timezone string.
+   * @returns Localized Date object.
+   * @throws {Error} If the timezone is invalid.
+   *
+   * @internal
+   */
+  static getDateInTimezone(date, timezone) {
+    try {
+      const tzDate = new Date(date.toLocaleString("en-US", { timeZone: timezone }));
+      if (Number.isNaN(tzDate.getTime())) {
+        throw new Error();
+      }
+      return tzDate;
+    } catch {
+      throw new Error(`Invalid timezone: ${timezone}`);
+    }
   }
-  return value === expected;
-}
+};
 
 // src/CronParser.ts
 var CronParser = class {
+  static cache = /* @__PURE__ */ new Map();
+  /** Cache duration in milliseconds (1 minute). */
+  static CACHE_TTL = 6e4;
+  /** Maximum number of unique expression/timezone combinations to store. */
+  static MAX_CACHE_SIZE = 500;
   /**
-   * Get the next execution date based on a cron expression.
+   * Calculates the next occurrence of a cron expression.
+   *
+   * Dynamically loads `cron-parser` to minimize initial bundle size and memory footprint.
+   *
+   * @param expression - Valid 5-part cron expression.
+   * @param timezone - Target timezone for evaluation (default: "UTC").
+   * @param currentDate - Reference time to calculate from (default: now).
+   * @returns Resolves to the next execution Date object.
+   * @throws {Error} If the expression format is invalid.
    *
-   * @param expression - Cron expression
-   * @param timezone - Timezone identifier
-   * @param currentDate - Reference date
+   * @example
+   * ```typescript
+   * const next = await CronParser.nextDate('0 0 * * *');
+   * ```
    */
   static async nextDate(expression, timezone = "UTC", currentDate = /* @__PURE__ */ new Date()) {
     try {
@@ -137,13 +127,47 @@ var CronParser = class {
     }
   }
   /**
-   * Check if the cron expression is due to run at the current time (minute precision).
+   * Determines if a task is due for execution at the specified time.
    *
-   * @param expression - Cron expression
-   * @param timezone - Timezone identifier
-   * @param currentDate - Reference date
+   * Uses minute-precision caching to optimize repeated evaluations within
+   * the same scheduling window. Implements LRU eviction to maintain memory efficiency.
+   *
+   * @param expression - Cron expression to evaluate.
+   * @param timezone - Execution timezone.
+   * @param currentDate - Reference time for the check.
+   * @returns True if the expression matches the reference time.
    */
   static async isDue(expression, timezone = "UTC", currentDate = /* @__PURE__ */ new Date()) {
+    const minuteKey = `${expression}:${timezone}:${Math.floor(currentDate.getTime() / 6e4)}`;
+    const now = Date.now();
+    const cached = this.cache.get(minuteKey);
+    if (cached) {
+      if (now - cached.timestamp < this.CACHE_TTL) {
+        this.cache.delete(minuteKey);
+        this.cache.set(minuteKey, cached);
+        return cached.result;
+      }
+      this.cache.delete(minuteKey);
+    }
+    const result = await this.computeIsDue(expression, timezone, currentDate);
+    this.cache.set(minuteKey, {
+      result,
+      timestamp: now
+    });
+    this.cleanupCache();
+    return result;
+  }
+  /**
+   * Internal logic for tiered cron evaluation.
+   *
+   * @param expression - Cron expression.
+   * @param timezone - Target timezone.
+   * @param currentDate - Current time.
+   * @returns Boolean indicating if the task is due.
+   *
+   * @internal
+   */
+  static async computeIsDue(expression, timezone, currentDate) {
     try {
       return SimpleCronParser.isDue(expression, timezone, currentDate);
     } catch (_e) {
@@ -161,6 +185,33 @@ var CronParser = class {
       return false;
     }
   }
+  /**
+   * Evicts the oldest entry from the cache when capacity is reached.
+   *
+   * @internal
+   */
+  static cleanupCache() {
+    if (this.cache.size <= this.MAX_CACHE_SIZE) {
+      return;
+    }
+    const iterator = this.cache.keys();
+    const oldestKey = iterator.next().value;
+    if (oldestKey) {
+      this.cache.delete(oldestKey);
+    }
+  }
+  /**
+   * Purges all entries from the internal cache.
+   * Useful for testing or when global timezone settings change.
+   */
+  static clearCache() {
+    this.cache.clear();
+  }
+  /**
+   * Compares two dates with minute precision.
+   *
+   * @internal
+   */
   static minuteMatches(date1, date2) {
     return date1.getFullYear() === date2.getFullYear() && date1.getMonth() === date2.getMonth() && date1.getDate() === date2.getDate() && date1.getHours() === date2.getHours() && date1.getMinutes() === date2.getMinutes();
   }
@@ -168,22 +219,55 @@ var CronParser = class {
 
 // src/locks/CacheLockStore.ts
 var CacheLockStore = class {
+  /**
+   * Initializes the store with a cache manager.
+   *
+   * @param cache - The Stasis cache instance.
+   * @param prefix - Key prefix to avoid collisions in the shared namespace.
+   */
   constructor(cache, prefix = "scheduler:lock:") {
     this.cache = cache;
     this.prefix = prefix;
   }
+  /**
+   * Computes the fully qualified cache key.
+   *
+   * @internal
+   */
   getKey(key) {
     return this.prefix + key;
   }
+  /**
+   * Atomic 'add' operation ensures only one node succeeds.
+   *
+   * @param key - Lock key.
+   * @param ttlSeconds - Expiration.
+   */
   async acquire(key, ttlSeconds) {
     return this.cache.add(this.getKey(key), "LOCKED", ttlSeconds);
   }
+  /**
+   * Removes the lock key from cache.
+   *
+   * @param key - Lock key.
+   */
   async release(key) {
     await this.cache.forget(this.getKey(key));
   }
+  /**
+   * Overwrites the lock key, effectively resetting the TTL.
+   *
+   * @param key - Lock key.
+   * @param ttlSeconds - New expiration.
+   */
   async forceAcquire(key, ttlSeconds) {
     await this.cache.put(this.getKey(key), "LOCKED", ttlSeconds);
   }
+  /**
+   * Validates if the lock key is present in the cache.
+   *
+   * @param key - Lock key.
+   */
   async exists(key) {
     return this.cache.has(this.getKey(key));
   }
@@ -191,7 +275,14 @@ var CacheLockStore = class {
 
 // src/locks/MemoryLockStore.ts
 var MemoryLockStore = class {
+  /** Map of lock keys to their expiration timestamps (ms). */
   locks = /* @__PURE__ */ new Map();
+  /**
+   * Acquires a local lock if the key is not already active.
+   *
+   * @param key - Lock identifier.
+   * @param ttlSeconds - Expiration duration.
+   */
   async acquire(key, ttlSeconds) {
     const NOW = Date.now();
     const expiresAt = this.locks.get(key);
@@ -201,12 +292,30 @@ var MemoryLockStore = class {
     this.locks.set(key, NOW + ttlSeconds * 1e3);
     return true;
   }
+  /**
+   * Deletes the lock from local memory.
+   *
+   * @param key - Lock identifier.
+   */
   async release(key) {
     this.locks.delete(key);
   }
+  /**
+   * Sets or overwrites a local lock.
+   *
+   * @param key - Lock identifier.
+   * @param ttlSeconds - Expiration.
+   */
   async forceAcquire(key, ttlSeconds) {
     this.locks.set(key, Date.now() + ttlSeconds * 1e3);
   }
+  /**
+   * Checks if a local lock is present and hasn't expired.
+   *
+   * Automatically purges expired locks upon checking.
+   *
+   * @param key - Lock identifier.
+   */
   async exists(key) {
     const expiresAt = this.locks.get(key);
     if (!expiresAt) {
@@ -223,6 +332,13 @@ var MemoryLockStore = class {
 // src/locks/LockManager.ts
 var LockManager = class {
   store;
+  /**
+   * Initializes the manager with a specific storage driver.
+   *
+   * @param driver - Strategy identifier or a custom `LockStore` implementation.
+   * @param context - Dependencies required by certain drivers (e.g., CacheManager).
+   * @throws {Error} If 'cache' driver is selected but no `CacheManager` is provided.
+   */
   constructor(driver, context) {
     if (typeof driver === "object") {
       this.store = driver;
@@ -237,15 +353,43 @@ var LockManager = class {
       this.store = new MemoryLockStore();
     }
   }
+  /**
+   * Attempts to acquire a lock. Fails if the key is already locked.
+   *
+   * @param key - Unique identifier for the lock.
+   * @param ttlSeconds - Time-to-live in seconds before the lock expires.
+   * @returns True if the lock was successfully acquired.
+   */
   async acquire(key, ttlSeconds) {
     return this.store.acquire(key, ttlSeconds);
   }
+  /**
+   * Explicitly releases a held lock.
+   *
+   * @param key - The lock identifier to remove.
+   * @returns Resolves when the lock is deleted.
+   */
   async release(key) {
     return this.store.release(key);
   }
+  /**
+   * Forcibly acquires or overwrites an existing lock.
+   *
+   * Used for execution locks where the latest attempt should take precedence
+   * if the previous one is deemed expired.
+   *
+   * @param key - Lock identifier.
+   * @param ttlSeconds - Expiration duration.
+   */
   async forceAcquire(key, ttlSeconds) {
     return this.store.forceAcquire(key, ttlSeconds);
   }
+  /**
+   * Checks if a specific lock currently exists and is not expired.
+   *
+   * @param key - Lock identifier.
+   * @returns True if the key is locked and active.
+   */
   async exists(key) {
     return this.store.exists(key);
   }
@@ -272,19 +416,55 @@ async function runProcess(command) {
   };
 }
 var Process = class {
+  /**
+   * Static alias for `runProcess`.
+   *
+   * @param command - Command to execute.
+   * @returns Process outcome.
+   */
   static async run(command) {
     return runProcess(command);
   }
 };
 
+// src/utils/validation.ts
+function parseTime(time) {
+  const timePattern = /^([0-2]\d):([0-5]\d)$/;
+  const match = time.match(timePattern);
+  if (!match) {
+    throw new Error(`Invalid time format: "${time}". Expected HH:mm (24-hour format, 00:00-23:59)`);
+  }
+  const hour = Number.parseInt(match[1], 10);
+  const minute = Number.parseInt(match[2], 10);
+  if (hour > 23) {
+    throw new Error(`Invalid time format: "${time}". Expected HH:mm (24-hour format, 00:00-23:59)`);
+  }
+  return { hour, minute };
+}
+function validateMinute(minute) {
+  if (!Number.isInteger(minute) || minute < 0 || minute > 59) {
+    throw new Error(`Invalid minute: ${minute}. Expected integer 0-59`);
+  }
+}
+function validateDayOfWeek(dayOfWeek) {
+  if (!Number.isInteger(dayOfWeek) || dayOfWeek < 0 || dayOfWeek > 6) {
+    throw new Error(`Invalid day of week: ${dayOfWeek}. Expected 0-6 (Sunday=0, Saturday=6)`);
+  }
+}
+function validateDayOfMonth(dayOfMonth) {
+  if (!Number.isInteger(dayOfMonth) || dayOfMonth < 1 || dayOfMonth > 31) {
+    throw new Error(`Invalid day of month: ${dayOfMonth}. Expected 1-31`);
+  }
+}
+
 // src/TaskSchedule.ts
 var TaskSchedule = class {
   task;
   /**
-   * Create a new TaskSchedule instance.
+   * Initializes a new schedule instance with default settings.
    *
-   * @param name - The unique name of the task.
-   * @param callback - The function to execute.
+   * @param name - Unique task name used for identification and locking.
+   * @param callback - Logic to execute on schedule.
    */
   constructor(name, callback) {
     this.task = {
@@ -298,168 +478,217 @@ var TaskSchedule = class {
       // 5 minutes default
       background: false,
       // Wait for task to finish by default
+      preventOverlapping: false,
+      overlappingExpiresAt: 3600,
+      // 1 hour default
       onSuccessCallbacks: [],
       onFailureCallbacks: []
     };
   }
   // --- Frequency Methods ---
   /**
-   * Set a custom cron expression.
+   * Configures a raw 5-part cron expression.
+   *
+   * @param expression - Cron string (e.g., "0 0 * * *").
+   * @returns The TaskSchedule instance for chaining.
+   * @throws {Error} If expression format is invalid or contains forbidden characters.
    *
-   * @param expression - Standard cron expression (e.g., "* * * * *")
-   * @returns The TaskSchedule instance.
+   * @example
+   * ```typescript
+   * schedule.cron('0 9-17 * * 1-5'); // 9-5 on weekdays
+   * ```
    */
   cron(expression) {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5) {
+      throw new Error(
+        `Invalid cron expression: "${expression}". Expected 5 parts (minute hour day month weekday), got ${parts.length}.`
+      );
+    }
+    const pattern = /^[0-9,\-/*?L#A-Za-z]+$/;
+    for (let i = 0; i < 5; i++) {
+      if (!pattern.test(parts[i])) {
+        throw new Error(
+          `Invalid cron expression: "${expression}". Part ${i + 1} ("${parts[i]}") contains invalid characters.`
+        );
+      }
+    }
     this.task.expression = expression;
     return this;
   }
   /**
-   * Run the task every minute.
+   * Schedules execution every minute.
    *
-   * @returns The TaskSchedule instance.
+   * @returns The TaskSchedule instance for chaining.
    */
   everyMinute() {
     return this.cron("* * * * *");
   }
   /**
-   * Run the task every 5 minutes.
+   * Schedules execution every five minutes.
    *
-   * @returns The TaskSchedule instance.
+   * @returns The TaskSchedule instance for chaining.
    */
   everyFiveMinutes() {
     return this.cron("*/5 * * * *");
   }
   /**
-   * Run the task every 10 minutes.
+   * Schedules execution every ten minutes.
    *
-   * @returns The TaskSchedule instance.
+   * @returns The TaskSchedule instance for chaining.
    */
   everyTenMinutes() {
     return this.cron("*/10 * * * *");
   }
   /**
-   * Run the task every 15 minutes.
+   * Schedules execution every fifteen minutes.
    *
-   * @returns The TaskSchedule instance.
+   * @returns The TaskSchedule instance for chaining.
    */
   everyFifteenMinutes() {
     return this.cron("*/15 * * * *");
   }
   /**
-   * Run the task every 30 minutes.
+   * Schedules execution every thirty minutes.
    *
-   * @returns The TaskSchedule instance.
+   * @returns The TaskSchedule instance for chaining.
    */
   everyThirtyMinutes() {
     return this.cron("0,30 * * * *");
   }
   /**
-   * Run the task hourly (at minute 0).
+   * Schedules execution hourly at the top of the hour.
    *
-   * @returns The TaskSchedule instance.
+   * @returns The TaskSchedule instance for chaining.
    */
   hourly() {
     return this.cron("0 * * * *");
   }
   /**
-   * Run the task hourly at a specific minute.
+   * Schedules execution hourly at a specific minute.
    *
-   * @param minute - Minute (0-59)
-   * @returns The TaskSchedule instance.
+   * @param minute - Target minute (0-59).
+   * @returns The TaskSchedule instance for chaining.
+   * @throws {Error} If minute is outside 0-59 range.
    */
   hourlyAt(minute) {
+    validateMinute(minute);
     return this.cron(`${minute} * * * *`);
   }
   /**
-   * Run the task daily at midnight (00:00).
+   * Schedules execution daily at midnight.
    *
-   * @returns The TaskSchedule instance.
+   * @returns The TaskSchedule instance for chaining.
    */
   daily() {
     return this.cron("0 0 * * *");
   }
   /**
-   * Run the task daily at a specific time.
+   * Schedules execution daily at a specific time.
+   *
+   * @param time - 24-hour time string in "HH:mm" format.
+   * @returns The TaskSchedule instance for chaining.
+   * @throws {Error} If time format is invalid or values are out of range.
    *
-   * @param time - Time in "HH:mm" format (24h)
-   * @returns The TaskSchedule instance.
+   * @example
+   * ```typescript
+   * schedule.dailyAt('14:30');
+   * ```
    */
   dailyAt(time) {
-    const [hour, minute] = time.split(":");
-    return this.cron(`${Number(minute)} ${Number(hour)} * * *`);
+    const { hour, minute } = parseTime(time);
+    return this.cron(`${minute} ${hour} * * *`);
   }
   /**
-   * Run the task weekly on Sunday at midnight.
+   * Schedules execution weekly on Sunday at midnight.
    *
-   * @returns The TaskSchedule instance.
+   * @returns The TaskSchedule instance for chaining.
    */
   weekly() {
     return this.cron("0 0 * * 0");
   }
   /**
-   * Run the task weekly on a specific day and time.
+   * Schedules execution weekly on a specific day and time.
+   *
+   * @param day - Day index (0-6, where 0 is Sunday).
+   * @param time - Optional 24-hour time string "HH:mm" (default "00:00").
+   * @returns The TaskSchedule instance for chaining.
+   * @throws {Error} If day index or time format is invalid.
    *
-   * @param day - Day of week (0-7, 0 or 7 is Sunday)
-   * @param time - Time in "HH:mm" format (default "00:00")
-   * @returns The TaskSchedule instance.
+   * @example
+   * ```typescript
+   * schedule.weeklyOn(1, '09:00'); // Mondays at 9 AM
+   * ```
    */
   weeklyOn(day, time = "00:00") {
-    const [hour, minute] = time.split(":");
-    return this.cron(`${Number(minute)} ${Number(hour)} * * ${day}`);
+    validateDayOfWeek(day);
+    const { hour, minute } = parseTime(time);
+    return this.cron(`${minute} ${hour} * * ${day}`);
   }
   /**
-   * Run the task monthly on the 1st day at midnight.
+   * Schedules execution monthly on the first day at midnight.
    *
-   * @returns The TaskSchedule instance.
+   * @returns The TaskSchedule instance for chaining.
    */
   monthly() {
     return this.cron("0 0 1 * *");
   }
   /**
-   * Run the task monthly on a specific day and time.
+   * Schedules execution monthly on a specific day and time.
    *
-   * @param day - Day of month (1-31)
-   * @param time - Time in "HH:mm" format (default "00:00")
-   * @returns The TaskSchedule instance.
+   * @param day - Day of month (1-31).
+   * @param time - Optional 24-hour time string "HH:mm" (default "00:00").
+   * @returns The TaskSchedule instance for chaining.
+   * @throws {Error} If day or time format is invalid.
    */
   monthlyOn(day, time = "00:00") {
-    const [hour, minute] = time.split(":");
-    return this.cron(`${Number(minute)} ${Number(hour)} ${day} * *`);
+    validateDayOfMonth(day);
+    const { hour, minute } = parseTime(time);
+    return this.cron(`${minute} ${hour} ${day} * *`);
   }
   // --- Constraints ---
   /**
-   * Set the timezone for the task execution.
+   * Specifies the timezone for evaluating schedule frequency.
    *
-   * @param timezone - Timezone identifier (e.g., "Asia/Taipei", "UTC")
-   * @returns The TaskSchedule instance.
+   * @param timezone - IANA timezone identifier (e.g., "America/New_York").
+   * @returns The TaskSchedule instance for chaining.
+   * @throws {Error} If the timezone identifier is not recognized by the system.
    */
   timezone(timezone) {
+    try {
+      (/* @__PURE__ */ new Date()).toLocaleString("en-US", { timeZone: timezone });
+    } catch {
+      throw new Error(
+        `Invalid timezone: "${timezone}". See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for valid values.`
+      );
+    }
     this.task.timezone = timezone;
     return this;
   }
   /**
-   * Set the time of execution for the current frequency.
-   * Useful when chaining with daily(), weekly(), etc.
+   * Modifies the execution time of the existing frequency.
+   * Typically used after frequency methods like daily() or weekly().
    *
-   * @param time - Time in "HH:mm" format
-   * @returns The TaskSchedule instance.
+   * @param time - 24-hour time string in "HH:mm" format.
+   * @returns The TaskSchedule instance for chaining.
+   * @throws {Error} If time format is invalid.
    */
   at(time) {
-    const [hour, minute] = time.split(":");
+    const { hour, minute } = parseTime(time);
     const parts = this.task.expression.split(" ");
     if (parts.length >= 5) {
-      parts[0] = String(Number(minute));
-      parts[1] = String(Number(hour));
+      parts[0] = String(minute);
+      parts[1] = String(hour);
       this.task.expression = parts.join(" ");
     }
     return this;
   }
   /**
-   * Ensure task runs on only one server at a time (Distributed Locking).
-   * Requires a configured LockStore (Cache or Redis).
+   * Enables distributed locking to ensure only one instance runs globally.
+   * Prevents duplicate execution when multiple servers are polling the same schedule.
    *
-   * @param lockTtlSeconds - Time in seconds to hold the lock (default 300)
-   * @returns The TaskSchedule instance.
+   * @param lockTtlSeconds - Duration in seconds to hold the window lock (default 300).
+   * @returns The TaskSchedule instance for chaining.
    */
   onOneServer(lockTtlSeconds = 300) {
     this.task.shouldRunOnOneServer = true;
@@ -467,41 +696,85 @@ var TaskSchedule = class {
     return this;
   }
   /**
-   * Alias for onOneServer.
-   * Prevents overlapping executions of the same task.
+   * Prevents a new task instance from starting if the previous one is still running.
    *
-   * @param expiresAt - Lock TTL in seconds
-   * @returns The TaskSchedule instance.
+   * Unlike `onOneServer()` which uses a time-window lock, this uses an execution lock
+   * to handle long-running tasks that might span multiple scheduling intervals.
+   *
+   * @param expiresAt - Max duration in seconds to keep the execution lock (default 3600).
+   * @returns The TaskSchedule instance for chaining.
+   *
+   * @example
+   * ```typescript
+   * // Prevents overlapping if the heavy operation takes > 1 minute
+   * scheduler.task('data-sync', heavySync)
+   *   .everyMinute()
+   *   .withoutOverlapping();
+   * ```
    */
-  withoutOverlapping(expiresAt = 300) {
-    return this.onOneServer(expiresAt);
+  withoutOverlapping(expiresAt = 3600) {
+    this.task.preventOverlapping = true;
+    this.task.overlappingExpiresAt = expiresAt;
+    return this;
   }
   /**
-   * Run task in background (do not wait for completion in the loop).
-   * Note: In Node.js non-blocking environment this is largely semantic,
-   * but affects how we handle error catching and lock release.
+   * Executes the task in background mode.
+   * The scheduler will not wait for this task to finish before proceeding to the next.
    *
-   * @returns The TaskSchedule instance.
+   * @returns The TaskSchedule instance for chaining.
    */
   runInBackground() {
     this.task.background = true;
     return this;
   }
   /**
-   * Restrict task execution to a specific node role.
+   * Restricts task execution to nodes with a specific role.
    *
-   * @param role - The required node role (e.g., 'api', 'worker')
-   * @returns The TaskSchedule instance.
+   * @param role - Target role identifier (e.g., "worker").
+   * @returns The TaskSchedule instance for chaining.
    */
   onNode(role) {
     this.task.nodeRole = role;
     return this;
   }
   /**
-   * Set the command string for exec tasks.
+   * Defines a maximum execution time for the task.
+   *
+   * @param ms - Timeout duration in milliseconds.
+   * @returns The TaskSchedule instance for chaining.
+   * @throws {Error} If timeout is not a positive number.
+   */
+  timeout(ms) {
+    if (ms <= 0) {
+      throw new Error("Timeout must be a positive number");
+    }
+    this.task.timeout = ms;
+    return this;
+  }
+  /**
+   * Configures automatic retry behavior for failed executions.
+   *
+   * @param attempts - Max number of retries (default 3).
+   * @param delayMs - Wait time between retries in milliseconds (default 1000).
+   * @returns The TaskSchedule instance for chaining.
+   * @throws {Error} If attempts or delay are negative.
+   */
+  retry(attempts = 3, delayMs = 1e3) {
+    if (attempts < 0) {
+      throw new Error("Retry attempts must be non-negative");
+    }
+    if (delayMs < 0) {
+      throw new Error("Retry delay must be non-negative");
+    }
+    this.task.retries = attempts;
+    this.task.retryDelay = delayMs;
+    return this;
+  }
+  /**
+   * Sets the shell command for execution-based tasks.
    *
    * @param command - The command string.
-   * @returns The TaskSchedule instance.
+   * @returns The TaskSchedule instance for chaining.
    * @internal
    */
   setCommand(command) {
@@ -510,39 +783,39 @@ var TaskSchedule = class {
   }
   // --- Hooks ---
   /**
-   * Register a callback to run on task success.
+   * Registers a callback to execute upon successful task completion.
    *
-   * @param callback - The callback function.
-   * @returns The TaskSchedule instance.
+   * @param callback - Function to run on success.
+   * @returns The TaskSchedule instance for chaining.
    */
   onSuccess(callback) {
     this.task.onSuccessCallbacks.push(callback);
     return this;
   }
   /**
-   * Register a callback to run on task failure.
+   * Registers a callback to execute when the task fails.
    *
-   * @param callback - The callback function.
-   * @returns The TaskSchedule instance.
+   * @param callback - Function to run on failure.
+   * @returns The TaskSchedule instance for chaining.
    */
   onFailure(callback) {
     this.task.onFailureCallbacks.push(callback);
     return this;
   }
   /**
-   * Set a description for the task (useful for listing).
+   * Attaches a human-readable description to the task.
    *
-   * @param _text - The description text.
-   * @returns The TaskSchedule instance.
+   * @param _text - Description text.
+   * @returns The TaskSchedule instance for chaining.
    */
   description(_text) {
     return this;
   }
   // --- Accessor ---
   /**
-   * Get the underlying task configuration.
+   * Returns the final task configuration.
    *
-   * @returns The ScheduledTask object.
+   * @returns The constructed ScheduledTask object.
    */
   getTask() {
     return this.task;
@@ -551,6 +824,14 @@ var TaskSchedule = class {
 
 // src/SchedulerManager.ts
 var SchedulerManager = class {
+  /**
+   * Initializes the scheduler engine.
+   *
+   * @param lockManager - Backend for distributed locking.
+   * @param logger - Optional logger for operational visibility.
+   * @param hooks - Optional manager for lifecycle event hooks.
+   * @param currentNodeRole - Role identifier for the local node (used for filtering).
+   */
   constructor(lockManager, logger, hooks, currentNodeRole) {
     this.lockManager = lockManager;
     this.logger = logger;
@@ -559,11 +840,18 @@ var SchedulerManager = class {
   }
   tasks = [];
   /**
-   * Define a new scheduled task.
+   * Registers a new callback-based scheduled task.
+   *
+   * @param name - Unique task name used for identification and locking.
+   * @param callback - Asynchronous function containing the task logic.
+   * @returns A fluent TaskSchedule instance for further configuration.
    *
-   * @param name - Unique name for the task
-   * @param callback - Function to execute
-   * @returns The newly created TaskSchedule.
+   * @example
+   * ```typescript
+   * scheduler.task('process-queues', async () => {
+   *   await queue.process();
+   * }).everyMinute();
+   * ```
    */
   task(name, callback) {
     const task = new TaskSchedule(name, callback);
@@ -571,11 +859,21 @@ var SchedulerManager = class {
     return task;
   }
   /**
-   * Define a new scheduled command execution task.
+   * Registers a shell command as a scheduled task.
    *
-   * @param name - Unique name for the task
-   * @param command - Shell command to execute
-   * @returns The newly created TaskSchedule.
+   * Executes the command via `sh -c` on matching nodes.
+   *
+   * @param name - Unique identifier for the command task.
+   * @param command - Raw shell command string.
+   * @returns A fluent TaskSchedule instance.
+   * @throws {Error} If the shell command returns a non-zero exit code during execution.
+   *
+   * @example
+   * ```typescript
+   * scheduler.exec('log-rotate', 'logrotate /etc/logrotate.conf')
+   *   .daily()
+   *   .onNode('worker');
+   * ```
    */
   exec(name, command) {
     const task = new TaskSchedule(name, async () => {
@@ -589,27 +887,29 @@ var SchedulerManager = class {
     return task;
   }
   /**
-   * Add a pre-configured task schedule object.
+   * Injects a pre-configured TaskSchedule instance into the registry.
    *
-   * @param schedule - The task schedule to add.
+   * @param schedule - Configured task schedule to register.
    */
   add(schedule) {
     this.tasks.push(schedule);
   }
   /**
-   * Get all registered task definitions.
+   * Exports all registered tasks for external inspection or serialization.
    *
-   * @returns An array of scheduled tasks.
+   * @returns An array of raw task configurations.
    */
   getTasks() {
     return this.tasks.map((t) => t.getTask());
   }
   /**
-   * Trigger the scheduler to check and run due tasks.
-   * This is typically called every minute by a system cron or worker loop.
+   * Main evaluation loop that triggers tasks due for execution.
+   *
+   * Should be invoked every minute by a system timer (systemd/cron) or daemon.
+   * Performs frequency checks, role filtering, and parallel execution.
    *
-   * @param date - The current reference date (default: now)
-   * @returns A promise that resolves when the scheduler run is complete.
+   * @param date - Reference time for cron evaluation (default: current time).
+   * @returns Resolves when all due tasks have been initiated.
    */
   async run(date = /* @__PURE__ */ new Date()) {
     await this.hooks?.doAction("scheduler:run:start", { date });
@@ -621,6 +921,14 @@ var SchedulerManager = class {
       }
     }
     if (dueTasks.length > 0) {
+      this.logger?.debug(`[Horizon] Found ${dueTasks.length} due task(s) to execute`, {
+        tasks: dueTasks.map((t) => ({
+          name: t.name,
+          expression: t.expression,
+          background: t.background,
+          oneServer: t.shouldRunOnOneServer
+        }))
+      });
     }
     for (const task of dueTasks) {
       this.runTask(task, date).catch((err) => {
@@ -630,21 +938,45 @@ var SchedulerManager = class {
     await this.hooks?.doAction("scheduler:run:complete", { date, dueCount: dueTasks.length });
   }
   /**
-   * Execute a specific task with locking logic.
+   * Executes an individual task after validating execution constraints.
+   *
+   * Evaluates node roles, overlapping prevention, and distributed time-window locks
+   * before initiating the actual task logic.
+   *
+   * @param task - Target task configuration.
+   * @param date - Reference time used for lock key generation.
    *
-   * @param task - The task to execute.
    * @internal
    */
   async runTask(task, date = /* @__PURE__ */ new Date()) {
     if (task.nodeRole && this.currentNodeRole && task.nodeRole !== this.currentNodeRole) {
       return;
     }
-    let acquiredLock = false;
+    const runningLockKey = `task:running:${task.name}`;
+    if (task.preventOverlapping) {
+      const isRunning = await this.lockManager.exists(runningLockKey);
+      if (isRunning) {
+        this.logger?.debug(
+          `[Horizon] Task "${task.name}" is still running, skipping this execution`
+        );
+        await this.hooks?.doAction("scheduler:task:skipped", {
+          name: task.name,
+          reason: "overlapping",
+          timestamp: date
+        });
+        return;
+      }
+      await this.lockManager.forceAcquire(runningLockKey, task.overlappingExpiresAt);
+    }
+    let acquiredTimeLock = false;
     const timestamp = `${date.getFullYear()}${(date.getMonth() + 1).toString().padStart(2, "0")}${date.getDate().toString().padStart(2, "0")}${date.getHours().toString().padStart(2, "0")}${date.getMinutes().toString().padStart(2, "0")}`;
-    const lockKey = `task:${task.name}:${timestamp}`;
+    const timeLockKey = `task:${task.name}:${timestamp}`;
     if (task.shouldRunOnOneServer) {
-      acquiredLock = await this.lockManager.acquire(lockKey, task.lockTtl);
-      if (!acquiredLock) {
+      acquiredTimeLock = await this.lockManager.acquire(timeLockKey, task.lockTtl);
+      if (!acquiredTimeLock) {
+        if (task.preventOverlapping) {
+          await this.lockManager.release(runningLockKey);
+        }
         return;
       }
     }
@@ -652,59 +984,118 @@ var SchedulerManager = class {
       if (task.background) {
         this.executeTask(task).catch((err) => {
           this.logger?.error(`Background task ${task.name} failed`, err);
+        }).finally(async () => {
+          if (task.preventOverlapping) {
+            await this.lockManager.release(runningLockKey);
+          }
         });
       } else {
         await this.executeTask(task);
+        if (task.preventOverlapping) {
+          await this.lockManager.release(runningLockKey);
+        }
       }
     } catch (err) {
-      if (acquiredLock) {
-        await this.lockManager.release(lockKey);
+      if (task.preventOverlapping) {
+        await this.lockManager.release(runningLockKey);
+      }
+      if (acquiredTimeLock) {
+        await this.lockManager.release(timeLockKey);
       }
       throw err;
     }
   }
   /**
-   * Execute the task callback and handle hooks.
+   * Internal wrapper for executing task logic with reliability controls.
+   *
+   * Handles timeouts, retries, and emits lifecycle hooks for monitoring.
    *
-   * @param task - The task to execute.
+   * @param task - The scheduled task to execute.
+   * @returns Resolves when the task (and its retries) completes or fails permanently.
+   *
+   * @internal
    */
   async executeTask(task) {
     const startTime = Date.now();
     await this.hooks?.doAction("scheduler:task:start", { name: task.name, startTime });
-    try {
-      await task.callback();
-      const duration = Date.now() - startTime;
-      await this.hooks?.doAction("scheduler:task:success", { name: task.name, duration });
-      for (const cb of task.onSuccessCallbacks) {
-        try {
-          await cb({ name: task.name });
-        } catch {
-        }
+    const timeout = task.timeout || 36e5;
+    const maxRetries = task.retries ?? 0;
+    const retryDelay = task.retryDelay ?? 1e3;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      if (attempt > 0) {
+        this.logger?.info(
+          `[Horizon] Retrying task "${task.name}" (attempt ${attempt}/${maxRetries})...`
+        );
+        await this.hooks?.doAction("scheduler:task:retry", {
+          name: task.name,
+          attempt,
+          maxRetries,
+          error: lastError,
+          delay: retryDelay
+        });
+        await new Promise((resolve) => setTimeout(resolve, retryDelay));
       }
-    } catch (err) {
-      const duration = Date.now() - startTime;
-      this.logger?.error(`Task ${task.name} failed`, err);
-      await this.hooks?.doAction("scheduler:task:failure", {
-        name: task.name,
-        error: err,
-        duration
+      let timeoutId;
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+          reject(new Error(`Task "${task.name}" timed out after ${timeout}ms`));
+        }, timeout);
       });
-      for (const cb of task.onFailureCallbacks) {
-        try {
-          await cb(err);
-        } catch {
+      try {
+        await Promise.race([task.callback(), timeoutPromise]);
+        const duration2 = Date.now() - startTime;
+        await this.hooks?.doAction("scheduler:task:success", {
+          name: task.name,
+          duration: duration2,
+          attempts: attempt + 1
+        });
+        for (const cb of task.onSuccessCallbacks) {
+          try {
+            await cb({ name: task.name });
+          } catch {
+          }
+        }
+        return;
+      } catch (err) {
+        lastError = err;
+        this.logger?.error(`Task ${task.name} failed (attempt ${attempt + 1})`, err);
+      } finally {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
         }
       }
     }
+    const duration = Date.now() - startTime;
+    await this.hooks?.doAction("scheduler:task:failure", {
+      name: task.name,
+      error: lastError,
+      duration,
+      attempts: maxRetries + 1
+    });
+    for (const cb of task.onFailureCallbacks) {
+      try {
+        await cb(lastError);
+      } catch {
+      }
+    }
   }
 };
 
 // src/OrbitHorizon.ts
 var OrbitHorizon = class {
   /**
-   * Install the Horizon Orbit into PlanetCore.
+   * Integrates the Horizon scheduler into the PlanetCore lifecycle.
+   *
+   * Orchestrates the initialization sequence:
+   * 1. Resolves lock backend (memory or cache-based).
+   * 2. Instantiates SchedulerManager with global dependencies (logger, hooks).
+   * 3. Registers the scheduler in the IoC container for CLI and global access.
+   * 4. Injects the scheduler into the request context via middleware.
+   *
+   * @param core - PlanetCore instance providing configuration and service container.
    *
-   * @param core - The PlanetCore instance.
+   * @throws {Error} If the cache driver is explicitly requested but `CacheManager` is unavailable.
    */
   install(core) {
     const config = core.config.get("scheduler", {});
@@ -713,7 +1104,7 @@ var OrbitHorizon = class {
     const nodeRole = config.nodeRole;
     let lockManager;
     if (lockDriver === "cache") {
-      const cacheManager = core.services.get("cache");
+      const cacheManager = core.container.make("cache");
       if (!cacheManager) {
         core.logger.warn(
           "[OrbitHorizon] Cache driver requested but cache service not found (ensure orbit-cache is loaded first). Falling back to Memory lock."
@@ -726,7 +1117,7 @@ var OrbitHorizon = class {
       lockManager = new LockManager("memory");
     }
     const scheduler = new SchedulerManager(lockManager, core.logger, core.hooks, nodeRole);
-    core.services.set(exposeAs, scheduler);
+    core.container.instance(exposeAs, scheduler);
     core.adapter.use("*", async (c, next) => {
       c.set("scheduler", scheduler);
       return await next();