@guren/server 0.2.0-alpha.7 → 1.0.0-rc.9

package/dist/scheduling/index.js

@@ -0,0 +1,836 @@
+// src/scheduling/CronParser.ts
+function parseField(field, min, max) {
+  const values = /* @__PURE__ */ new Set();
+  const parts = field.split(",");
+  for (const part of parts) {
+    const stepMatch = part.match(/^(.+)\/(\d+)$/);
+    let range;
+    let step = 1;
+    if (stepMatch) {
+      range = stepMatch[1];
+      step = parseInt(stepMatch[2], 10);
+    } else {
+      range = part;
+    }
+    if (range === "*") {
+      for (let i = min; i <= max; i += step) {
+        values.add(i);
+      }
+      continue;
+    }
+    const rangeMatch = range.match(/^(\d+)-(\d+)$/);
+    if (rangeMatch) {
+      const start = parseInt(rangeMatch[1], 10);
+      const end = parseInt(rangeMatch[2], 10);
+      for (let i = start; i <= end; i += step) {
+        if (i >= min && i <= max) {
+          values.add(i);
+        }
+      }
+      continue;
+    }
+    const value = parseInt(range, 10);
+    if (!isNaN(value) && value >= min && value <= max) {
+      values.add(value);
+    }
+  }
+  return Array.from(values).sort((a, b) => a - b);
+}
+function parseCron(expression) {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`Invalid cron expression: ${expression}. Expected 5 fields.`);
+  }
+  return {
+    minute: parseField(parts[0], 0, 59),
+    hour: parseField(parts[1], 0, 23),
+    dayOfMonth: parseField(parts[2], 1, 31),
+    month: parseField(parts[3], 1, 12),
+    dayOfWeek: parseField(parts[4], 0, 6)
+    // 0 = Sunday
+  };
+}
+function matchesCron(date, cron) {
+  const minute = date.getMinutes();
+  const hour = date.getHours();
+  const dayOfMonth = date.getDate();
+  const month = date.getMonth() + 1;
+  const dayOfWeek = date.getDay();
+  return cron.minute.includes(minute) && cron.hour.includes(hour) && cron.dayOfMonth.includes(dayOfMonth) && cron.month.includes(month) && cron.dayOfWeek.includes(dayOfWeek);
+}
+function getNextOccurrence(expression, from = /* @__PURE__ */ new Date()) {
+  const cron = parseCron(expression);
+  const next = new Date(from);
+  next.setSeconds(0);
+  next.setMilliseconds(0);
+  next.setMinutes(next.getMinutes() + 1);
+  const maxIterations = 525600;
+  let iterations = 0;
+  while (iterations < maxIterations) {
+    if (matchesCron(next, cron)) {
+      return next;
+    }
+    next.setMinutes(next.getMinutes() + 1);
+    iterations++;
+  }
+  throw new Error(`Could not find next occurrence for: ${expression}`);
+}
+function isDue(expression, date = /* @__PURE__ */ new Date()) {
+  const cron = parseCron(expression);
+  return matchesCron(date, cron);
+}
+function getNextOccurrences(expression, count, from = /* @__PURE__ */ new Date()) {
+  const occurrences = [];
+  let current = from;
+  for (let i = 0; i < count; i++) {
+    const next = getNextOccurrence(expression, current);
+    occurrences.push(next);
+    current = next;
+  }
+  return occurrences;
+}
+function toTimezone(date, timezone) {
+  const options = {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  };
+  const formatter = new Intl.DateTimeFormat("en-US", options);
+  const parts = formatter.formatToParts(date);
+  const get = (type) => parts.find((p) => p.type === type)?.value ?? "0";
+  const year = parseInt(get("year"), 10);
+  const month = parseInt(get("month"), 10) - 1;
+  const day = parseInt(get("day"), 10);
+  const hour = parseInt(get("hour"), 10);
+  const minute = parseInt(get("minute"), 10);
+  const second = parseInt(get("second"), 10);
+  return new Date(year, month, day, hour, minute, second);
+}
+function isDueInTimezone(expression, timezone, date = /* @__PURE__ */ new Date()) {
+  const localDate = toTimezone(date, timezone);
+  return isDue(expression, localDate);
+}
+
+// src/scheduling/ScheduledTask.ts
+var ScheduledTask = class {
+  definition;
+  lastRun = null;
+  isRunning = false;
+  constructor(definition) {
+    this.definition = definition;
+  }
+  /**
+   * Get the task name.
+   */
+  getName() {
+    return this.definition.name ?? "anonymous";
+  }
+  /**
+   * Get the cron expression.
+   */
+  getExpression() {
+    return this.definition.expression;
+  }
+  /**
+   * Get the timezone.
+   */
+  getTimezone() {
+    return this.definition.timezone;
+  }
+  /**
+   * Check if the task is due.
+   */
+  isDue(date = /* @__PURE__ */ new Date()) {
+    if (this.definition.timezone) {
+      return isDueInTimezone(this.definition.expression, this.definition.timezone, date);
+    }
+    return isDue(this.definition.expression, date);
+  }
+  /**
+   * Check if the task should run based on conditions.
+   * Note: Overlap checking is handled separately in run() to prevent race conditions.
+   */
+  async shouldRun() {
+    if (this.definition.when) {
+      const result = await this.definition.when();
+      if (!result) {
+        return false;
+      }
+    }
+    if (this.definition.skip) {
+      const result = await this.definition.skip();
+      if (result) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Run the task.
+   */
+  async run() {
+    if (this.definition.withoutOverlapping) {
+      if (this.isRunning) {
+        return;
+      }
+      this.isRunning = true;
+    }
+    if (!await this.shouldRun()) {
+      if (this.definition.withoutOverlapping) {
+        this.isRunning = false;
+      }
+      return;
+    }
+    if (!this.definition.withoutOverlapping) {
+      this.isRunning = true;
+    }
+    let error = null;
+    try {
+      if (this.definition.before) {
+        await this.definition.before();
+      }
+      await this.definition.callback();
+      this.lastRun = /* @__PURE__ */ new Date();
+      if (this.definition.onSuccess) {
+        await this.definition.onSuccess();
+      }
+    } catch (err) {
+      error = err instanceof Error ? err : new Error(String(err));
+      if (this.definition.onFailure) {
+        await this.definition.onFailure(error);
+      }
+    } finally {
+      this.isRunning = false;
+      if (this.definition.after) {
+        await this.definition.after();
+      }
+    }
+    if (error) {
+      throw error;
+    }
+  }
+  /**
+   * Get the last run time.
+   */
+  getLastRun() {
+    return this.lastRun;
+  }
+  /**
+   * Check if the task is currently running.
+   */
+  isCurrentlyRunning() {
+    return this.isRunning;
+  }
+  /**
+   * Get the task definition.
+   */
+  getDefinition() {
+    return { ...this.definition };
+  }
+};
+
+// src/scheduling/Schedule.ts
+var PendingSchedule = class {
+  constructor(callback) {
+    this.callback = callback;
+  }
+  expression = "* * * * *";
+  timezone;
+  taskName;
+  withoutOverlapping = false;
+  overlapExpiresAt;
+  onOneServer = false;
+  whenCallback;
+  skipCallback;
+  beforeCallback;
+  afterCallback;
+  successCallback;
+  failureCallback;
+  // ===== Frequency Methods =====
+  /**
+   * Run every minute.
+   */
+  everyMinute() {
+    this.expression = "* * * * *";
+    return this;
+  }
+  /**
+   * Run every two minutes.
+   */
+  everyTwoMinutes() {
+    this.expression = "*/2 * * * *";
+    return this;
+  }
+  /**
+   * Run every three minutes.
+   */
+  everyThreeMinutes() {
+    this.expression = "*/3 * * * *";
+    return this;
+  }
+  /**
+   * Run every four minutes.
+   */
+  everyFourMinutes() {
+    this.expression = "*/4 * * * *";
+    return this;
+  }
+  /**
+   * Run every five minutes.
+   */
+  everyFiveMinutes() {
+    this.expression = "*/5 * * * *";
+    return this;
+  }
+  /**
+   * Run every ten minutes.
+   */
+  everyTenMinutes() {
+    this.expression = "*/10 * * * *";
+    return this;
+  }
+  /**
+   * Run every fifteen minutes.
+   */
+  everyFifteenMinutes() {
+    this.expression = "*/15 * * * *";
+    return this;
+  }
+  /**
+   * Run every thirty minutes.
+   */
+  everyThirtyMinutes() {
+    this.expression = "*/30 * * * *";
+    return this;
+  }
+  /**
+   * Run hourly.
+   */
+  hourly() {
+    this.expression = "0 * * * *";
+    return this;
+  }
+  /**
+   * Run hourly at a specific minute.
+   */
+  hourlyAt(minute) {
+    this.expression = `${minute} * * * *`;
+    return this;
+  }
+  /**
+   * Run every two hours.
+   */
+  everyTwoHours() {
+    this.expression = "0 */2 * * *";
+    return this;
+  }
+  /**
+   * Run every three hours.
+   */
+  everyThreeHours() {
+    this.expression = "0 */3 * * *";
+    return this;
+  }
+  /**
+   * Run every four hours.
+   */
+  everyFourHours() {
+    this.expression = "0 */4 * * *";
+    return this;
+  }
+  /**
+   * Run every six hours.
+   */
+  everySixHours() {
+    this.expression = "0 */6 * * *";
+    return this;
+  }
+  /**
+   * Run daily at midnight.
+   */
+  daily() {
+    this.expression = "0 0 * * *";
+    return this;
+  }
+  /**
+   * Run daily at a specific time.
+   * @param time Time in HH:MM format
+   */
+  dailyAt(time) {
+    const [hour, minute] = time.split(":").map((n) => parseInt(n, 10));
+    this.expression = `${minute ?? 0} ${hour ?? 0} * * *`;
+    return this;
+  }
+  /**
+   * Alias for dailyAt.
+   */
+  at(time) {
+    return this.dailyAt(time);
+  }
+  /**
+   * Run twice daily.
+   */
+  twiceDaily(firstHour = 1, secondHour = 13) {
+    this.expression = `0 ${firstHour},${secondHour} * * *`;
+    return this;
+  }
+  /**
+   * Run weekly on Sunday at midnight.
+   */
+  weekly() {
+    this.expression = "0 0 * * 0";
+    return this;
+  }
+  /**
+   * Run weekly on a specific day at a specific time.
+   * @param day Day of week (0 = Sunday, 6 = Saturday)
+   * @param time Time in HH:MM format
+   */
+  weeklyOn(day, time = "00:00") {
+    const [hour, minute] = time.split(":").map((n) => parseInt(n, 10));
+    this.expression = `${minute ?? 0} ${hour ?? 0} * * ${day}`;
+    return this;
+  }
+  // Day of week shortcuts
+  sundays() {
+    const parts = this.expression.split(" ");
+    parts[4] = "0";
+    this.expression = parts.join(" ");
+    return this;
+  }
+  mondays() {
+    const parts = this.expression.split(" ");
+    parts[4] = "1";
+    this.expression = parts.join(" ");
+    return this;
+  }
+  tuesdays() {
+    const parts = this.expression.split(" ");
+    parts[4] = "2";
+    this.expression = parts.join(" ");
+    return this;
+  }
+  wednesdays() {
+    const parts = this.expression.split(" ");
+    parts[4] = "3";
+    this.expression = parts.join(" ");
+    return this;
+  }
+  thursdays() {
+    const parts = this.expression.split(" ");
+    parts[4] = "4";
+    this.expression = parts.join(" ");
+    return this;
+  }
+  fridays() {
+    const parts = this.expression.split(" ");
+    parts[4] = "5";
+    this.expression = parts.join(" ");
+    return this;
+  }
+  saturdays() {
+    const parts = this.expression.split(" ");
+    parts[4] = "6";
+    this.expression = parts.join(" ");
+    return this;
+  }
+  /**
+   * Run on weekdays (Monday-Friday).
+   */
+  weekdays() {
+    const parts = this.expression.split(" ");
+    parts[4] = "1-5";
+    this.expression = parts.join(" ");
+    return this;
+  }
+  /**
+   * Run on weekends (Saturday-Sunday).
+   */
+  weekends() {
+    const parts = this.expression.split(" ");
+    parts[4] = "0,6";
+    this.expression = parts.join(" ");
+    return this;
+  }
+  /**
+   * Run monthly on the first day at midnight.
+   */
+  monthly() {
+    this.expression = "0 0 1 * *";
+    return this;
+  }
+  /**
+   * Run monthly on a specific day at a specific time.
+   */
+  monthlyOn(day, time = "00:00") {
+    const [hour, minute] = time.split(":").map((n) => parseInt(n, 10));
+    this.expression = `${minute ?? 0} ${hour ?? 0} ${day} * *`;
+    return this;
+  }
+  /**
+   * Run on the last day of the month.
+   */
+  lastDayOfMonth(time = "00:00") {
+    const [hour, minute] = time.split(":").map((n) => parseInt(n, 10));
+    this.expression = `${minute ?? 0} ${hour ?? 0} 28-31 * *`;
+    return this;
+  }
+  /**
+   * Run quarterly.
+   */
+  quarterly() {
+    this.expression = "0 0 1 1,4,7,10 *";
+    return this;
+  }
+  /**
+   * Run yearly on January 1st at midnight.
+   */
+  yearly() {
+    this.expression = "0 0 1 1 *";
+    return this;
+  }
+  /**
+   * Run yearly on a specific date.
+   */
+  yearlyOn(month, day, time = "00:00") {
+    const [hour, minute] = time.split(":").map((n) => parseInt(n, 10));
+    this.expression = `${minute ?? 0} ${hour ?? 0} ${day} ${month} *`;
+    return this;
+  }
+  /**
+   * Set a custom cron expression.
+   */
+  cron(expression) {
+    this.expression = expression;
+    return this;
+  }
+  // ===== Configuration Methods =====
+  /**
+   * Set the task name.
+   */
+  name(name) {
+    this.taskName = name;
+    return this;
+  }
+  /**
+   * Set the timezone.
+   */
+  tz(timezone) {
+    this.timezone = timezone;
+    return this;
+  }
+  /**
+   * Alias for tz().
+   */
+  setTimezone(timezone) {
+    return this.tz(timezone);
+  }
+  /**
+   * Prevent overlapping executions.
+   */
+  preventOverlapping(expiresAt) {
+    this.withoutOverlapping = true;
+    this.overlapExpiresAt = expiresAt;
+    return this;
+  }
+  /**
+   * Alias for preventOverlapping().
+   */
+  withoutOverlaps(expiresAt) {
+    return this.preventOverlapping(expiresAt);
+  }
+  /**
+   * Only run on one server.
+   */
+  runOnOneServer() {
+    this.onOneServer = true;
+    return this;
+  }
+  /**
+   * Set a condition for running.
+   */
+  when(callback) {
+    this.whenCallback = callback;
+    return this;
+  }
+  /**
+   * Set a condition to skip execution.
+   */
+  skip(callback) {
+    this.skipCallback = callback;
+    return this;
+  }
+  /**
+   * Set a before callback.
+   */
+  before(callback) {
+    this.beforeCallback = callback;
+    return this;
+  }
+  /**
+   * Set an after callback.
+   */
+  after(callback) {
+    this.afterCallback = callback;
+    return this;
+  }
+  /**
+   * Set a success callback.
+   */
+  onSuccess(callback) {
+    this.successCallback = callback;
+    return this;
+  }
+  /**
+   * Set a failure callback.
+   */
+  onFailure(callback) {
+    this.failureCallback = callback;
+    return this;
+  }
+  // ===== Build Method =====
+  /**
+   * Build the task definition.
+   */
+  build() {
+    return {
+      name: this.taskName,
+      expression: this.expression,
+      timezone: this.timezone,
+      callback: this.callback,
+      withoutOverlapping: this.withoutOverlapping,
+      overlapExpiresAt: this.overlapExpiresAt,
+      onOneServer: this.onOneServer,
+      when: this.whenCallback,
+      skip: this.skipCallback,
+      before: this.beforeCallback,
+      after: this.afterCallback,
+      onSuccess: this.successCallback,
+      onFailure: this.failureCallback
+    };
+  }
+  /**
+   * Build as a ScheduledTask.
+   */
+  toTask() {
+    return new ScheduledTask(this.build());
+  }
+};
+var Schedule = class {
+  tasks = [];
+  /**
+   * Schedule a callback.
+   */
+  call(callback) {
+    const pending = new PendingSchedule(callback);
+    this.tasks.push(pending);
+    return pending;
+  }
+  /**
+   * Schedule a job.
+   */
+  job(jobClass, payload) {
+    return this.call(async () => {
+      await jobClass.dispatch(payload);
+    });
+  }
+  /**
+   * Schedule a shell command.
+   */
+  command(cmd) {
+    return this.call(async () => {
+      const { exec } = await import("child_process");
+      const { promisify } = await import("util");
+      const execAsync = promisify(exec);
+      await execAsync(cmd);
+    });
+  }
+  /**
+   * Get all pending schedules.
+   */
+  getPendingSchedules() {
+    return [...this.tasks];
+  }
+  /**
+   * Build all tasks.
+   */
+  buildTasks() {
+    return this.tasks.map((pending) => pending.toTask());
+  }
+};
+
+// src/scheduling/Scheduler.ts
+var Scheduler = class {
+  tasks = [];
+  options;
+  interval = null;
+  isRunning = false;
+  lastCheck = null;
+  constructor(options = {}) {
+    this.options = {
+      timezone: options.timezone ?? "UTC",
+      checkInterval: options.checkInterval ?? 6e4,
+      logger: options.logger ?? (() => {
+      })
+    };
+  }
+  /**
+   * Define schedules using a callback.
+   */
+  schedule(definer) {
+    const schedule = new Schedule();
+    definer(schedule);
+    this.tasks.push(...schedule.buildTasks());
+  }
+  /**
+   * Add a pre-built task.
+   */
+  addTask(task) {
+    this.tasks.push(task);
+  }
+  /**
+   * Get all scheduled tasks.
+   */
+  getTasks() {
+    return [...this.tasks];
+  }
+  /**
+   * Get tasks that are due now.
+   */
+  getDueTasks(date = /* @__PURE__ */ new Date()) {
+    return this.tasks.filter((task) => task.isDue(date));
+  }
+  /**
+   * Run all due tasks.
+   */
+  async runDueTasks(date = /* @__PURE__ */ new Date()) {
+    const dueTasks = this.getDueTasks(date);
+    for (const task of dueTasks) {
+      this.options.logger(`Running task: ${task.getName()}`);
+      try {
+        await task.run();
+        this.options.logger(`Task completed: ${task.getName()}`);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.options.logger(`Task failed: ${task.getName()} - ${message}`);
+      }
+    }
+  }
+  /**
+   * Start the scheduler.
+   */
+  start() {
+    if (this.isRunning) {
+      return;
+    }
+    this.isRunning = true;
+    this.options.logger("Scheduler started");
+    this.tick();
+    this.interval = setInterval(() => {
+      this.tick();
+    }, this.options.checkInterval);
+    if (this.interval.unref) {
+      this.interval.unref();
+    }
+  }
+  /**
+   * Stop the scheduler.
+   */
+  stop() {
+    if (!this.isRunning) {
+      return;
+    }
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+    this.isRunning = false;
+    this.options.logger("Scheduler stopped");
+  }
+  /**
+   * Check and run due tasks.
+   */
+  tick() {
+    const now = /* @__PURE__ */ new Date();
+    if (this.lastCheck) {
+      const lastMinute = Math.floor(this.lastCheck.getTime() / 6e4);
+      const currentMinute = Math.floor(now.getTime() / 6e4);
+      if (lastMinute === currentMinute) {
+        return;
+      }
+    }
+    this.lastCheck = now;
+    this.runDueTasks(now).catch((error) => {
+      this.options.logger(`Scheduler error: ${error}`);
+    });
+  }
+  /**
+   * Check if the scheduler is running.
+   */
+  getIsRunning() {
+    return this.isRunning;
+  }
+  /**
+   * Get the check interval.
+   */
+  getCheckInterval() {
+    return this.options.checkInterval;
+  }
+  /**
+   * Get the default timezone.
+   */
+  getTimezone() {
+    return this.options.timezone;
+  }
+  /**
+   * Clear all tasks.
+   */
+  clear() {
+    this.tasks = [];
+  }
+  /**
+   * Get the number of tasks.
+   */
+  count() {
+    return this.tasks.length;
+  }
+  /**
+   * Get task by name.
+   */
+  getTask(name) {
+    return this.tasks.find((task) => task.getName() === name);
+  }
+  /**
+   * Remove a task by name.
+   */
+  removeTask(name) {
+    const index = this.tasks.findIndex((task) => task.getName() === name);
+    if (index !== -1) {
+      this.tasks.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+};
+function createScheduler(options) {
+  return new Scheduler(options);
+}
+export {
+  PendingSchedule,
+  Schedule,
+  ScheduledTask,
+  Scheduler,
+  createScheduler,
+  getNextOccurrence,
+  getNextOccurrences,
+  isDue,
+  isDueInTimezone,
+  matchesCron,
+  parseCron,
+  toTimezone
+};