chanjs 2.7.4 → 2.7.5

package/schedule/schedule.js

@@ -1,491 +0,0 @@
-/**
- * 轻量级定时任务调度器
- *
- * ============================================================
- * 使用方法
- * ============================================================
- *
- * 零依赖、单进程内调度。基于 setTimeout + 递归调度实现。
- * 适合 Web 应用内的周期性任务（清理、统计、轮询、健康检查）。
- *
- * 1. 固定间隔（最常用）
- *    import { schedule } from 'chanjs/helper/schedule.js';
- *    schedule.every('clean-log', 5 * 60 * 1000, async () => {
- *      await cleanOldLogs();
- *    });
- *
- * 2. Cron 表达式（5 字段：分 时 日 月 周）
- *    schedule.cron('daily-report', '0 2 * * *', async () => {
- *      await sendDailyReport();   // 每天凌晨 2 点
- *    });
- *
- * 3. 一次性延迟
- *    schedule.delay('warmup', 10 * 1000, async () => {
- *      await warmUpCache();
- *    });
- *
- * 4. 任务控制
- *    schedule.stop('clean-log');     // 停止
- *    schedule.start('clean-log');    // 启动
- *    schedule.remove('clean-log');   // 移除
- *    schedule.list();                // 查看所有任务
- *
- * 5. 优雅停机
- *    process.on('SIGTERM', () => schedule.shutdown());
- *
- * ============================================================
- *
- * 设计要点：
- * 1. 错误隔离：单任务异常不影响其他任务，记录错误后继续下次调度
- * 2. 防重叠：同一任务上一次未完成不会启动下一次（避免积压）
- * 3. 漂移修正：固定间隔模式按"上次完成时间 + 间隔"调度，避免误差累积
- * 4. 优雅停机：shutdown() 清理所有定时器，未完成的任务标记后不重启
- * 5. Cron 解析：5 字段标准语法，支持 * / - , 四种操作符
- *
- * Cron 字段说明：
- *   字段       允许值       允许的特殊字符
- *   分钟       0-59         星号 / 减号 逗号
- *   小时       0-23         星号 / 减号 逗号
- *   日         1-31         星号 / 减号 逗号
- *   月         1-12         星号 / 减号 逗号
- *   周         0-6 (0=周日) 星号 / 减号 逗号
- *
- * Cron 示例（实际使用时把"星号"替换为 *）：
- *   星号/5 * * * *     每 5 分钟
- *   0 星号 * * *         每小时整点
- *   0 2 * * *           每天凌晨 2 点
- *   0 0 * * 1           每周一凌晨
- *   0 0 1 * *           每月 1 号凌晨
- *   0 0,30 9-17 * *     工作时间每半点
- */
-
-/**
- * Cron 字段定义：[字段名, 最小值, 最大值]
- * @private
- */
-const CRON_FIELDS = [
-  ['minute', 0, 59],
-  ['hour', 0, 23],
-  ['dayOfMonth', 1, 31],
-  ['month', 1, 12],
-  ['dayOfWeek', 0, 6],  // 0=周日
-];
-
-/**
- * 解析 Cron 单个字段，返回允许值集合
- * 支持：*  /  -  ,
- * @param {string} field - 字段表达式
- * @param {number} min - 最小值
- * @param {number} max - 最大值
- * @returns {Set<number>} 允许值集合
- * @private
- */
-function parseCronField(field, min, max) {
-  const result = new Set();
-  const parts = field.split(',').map(s => s.trim());
-
-  for (const part of parts) {
-    // */n → 每 n 个单位
-    if (part.startsWith('*/')) {
-      const step = parseInt(part.slice(2), 10);
-      if (!step || step <= 0) throw new Error(`Cron 步长无效: ${part}`);
-      for (let i = min; i <= max; i += step) result.add(i);
-    }
-    // a-b → 区间
-    else if (part.includes('-')) {
-      const [startStr, endStr] = part.split('-');
-      const start = parseInt(startStr, 10);
-      const end = parseInt(endStr, 10);
-      if (isNaN(start) || isNaN(end) || start > end) {
-        throw new Error(`Cron 区间无效: ${part}`);
-      }
-      for (let i = start; i <= end; i++) result.add(i);
-    }
-    // * → 全部
-    else if (part === '*') {
-      for (let i = min; i <= max; i++) result.add(i);
-    }
-    // 单值
-    else {
-      const val = parseInt(part, 10);
-      if (isNaN(val)) throw new Error(`Cron 值无效: ${part}`);
-      if (val < min || val > max) throw new Error(`Cron 值超出范围: ${part} (${min}-${max})`);
-      result.add(val);
-    }
-  }
-
-  return result;
-}
-
-/**
- * 解析 Cron 表达式
- * @param {string} expr - 5 字段 cron 表达式
- * @returns {Object} { minute:Set, hour:Set, dayOfMonth:Set, month:Set, dayOfWeek:Set }
- * @private
- */
-function parseCronExpression(expr) {
-  const fields = expr.trim().split(/\s+/);
-  if (fields.length !== 5) {
-    throw new Error(`Cron 表达式必须是 5 个字段: "${expr}"`);
-  }
-
-  const parsed = {};
-  for (let i = 0; i < 5; i++) {
-    const [name, min, max] = CRON_FIELDS[i];
-    parsed[name] = parseCronField(fields[i], min, max);
-  }
-  return parsed;
-}
-
-/**
- * 计算下次执行时间
- * 从 from 的下一分钟开始，逐分钟递增，找到第一个匹配的时间
- * 最长搜索 4 年（覆盖闰年周期）或最多 10000 次迭代，找不到返回 null
- * @param {Object} cron - parseCronExpression 返回值
- * @param {Date} from - 起始时间
- * @returns {Date|null} 下次执行时间
- * @private
- */
-function nextCronTime(cron, from = new Date()) {
-  const next = new Date(from);
-  next.setSeconds(0, 0);  // 重置到当前分钟开始
-  next.setMinutes(next.getMinutes() + 1);  // 下一分钟开始
-
-  // 搜索上限：4 年（覆盖闰年）
-  const limit = new Date(from);
-  limit.setFullYear(limit.getFullYear() + 4);
-
-  // 最大迭代次数限制，避免某些边界 cron 表达式导致 CPU 突刺
-  // 4 年 ≈ 2,107,680 分钟，10000 次迭代约等于一周扫描范围，正常 cron 都能匹配到
-  const MAX_ITERATIONS = 10000;
-  let iterations = 0;
-
-  while (next.getTime() < limit.getTime() && iterations < MAX_ITERATIONS) {
-    iterations++;
-    // 注意：JS getMonth() 返回 0-11，cron month 是 1-12
-    // 注意：JS getDay() 返回 0-6（0=周日），cron dow 也是 0-6
-    if (
-      cron.month.has(next.getMonth() + 1) &&
-      cron.dayOfMonth.has(next.getDate()) &&
-      cron.dayOfWeek.has(next.getDay()) &&
-      cron.hour.has(next.getHours()) &&
-      cron.minute.has(next.getMinutes())
-    ) {
-      return next;
-    }
-    next.setMinutes(next.getMinutes() + 1);
-  }
-
-  if (iterations >= MAX_ITERATIONS) {
-    console.warn(`[Schedule] nextCronTime 已达最大迭代次数 ${MAX_ITERATIONS}，可能 cron 表达式不合理`);
-  }
-
-  return null;
-}
-
-/**
- * 定时任务调度器
- * @class Schedule
- */
-class Schedule {
-  constructor() {
-    /** @type {Map<string, Object>} 任务表 name -> task */
-    this._tasks = new Map();
-    /** 是否已 shutdown（shutdown 后不再接受新任务） */
-    this._shuttingDown = false;
-  }
-
-  /**
-   * 添加任务（底层方法）
-   * @param {string} name - 任务名（唯一）
-   * @param {Object} options - 任务配置
-   * @param {Function} options.fn - 任务函数
-   * @param {string} [options.type] - 类型：'every' | 'cron' | 'delay'
-   * @param {number} [options.intervalMs] - every 模式的间隔毫秒
-   * @param {string} [options.cron] - cron 表达式
-   * @param {number} [options.delayMs] - delay 模式的延迟毫秒
-   * @param {boolean} [options.runOnInit=false] - 是否立即执行一次
-   * @param {boolean} [options.autoStart=true] - 是否自动启动
-   * @returns {Object} 任务对象
-   */
-  add(name, options) {
-    if (this._shuttingDown) {
-      throw new Error('[Schedule] 已 shutdown，无法添加任务');
-    }
-    if (this._tasks.has(name)) {
-      throw new Error(`[Schedule] 任务已存在: ${name}`);
-    }
-    if (typeof options.fn !== 'function') {
-      throw new Error(`[Schedule] fn 必须是函数: ${name}`);
-    }
-
-    const task = {
-      name,
-      fn: options.fn,
-      type: options.type,
-      intervalMs: options.intervalMs,
-      cron: options.cron ? parseCronExpression(options.cron) : null,
-      cronExpr: options.cron || null,
-      delayMs: options.delayMs,
-      runOnInit: options.runOnInit || false,
-      // 运行时状态
-      running: false,           // 是否正在执行
-      timer: null,             // setTimeout 句柄
-      lastRun: null,           // 上次执行时间
-      nextRun: null,           // 下次执行时间
-      lastError: null,         // 上次错误
-      runCount: 0,             // 累计执行次数
-      errorCount: 0,           // 累计错误次数
-      started: false,          // 是否已启动
-    };
-
-    this._tasks.set(name, task);
-
-    if (options.autoStart !== false) {
-      this._startTask(task);
-    }
-
-    return task;
-  }
-
-  /**
-   * 固定间隔任务
-   * @param {string} name - 任务名
-   * @param {number} intervalMs - 间隔毫秒
-   * @param {Function} fn - 任务函数
-   * @param {Object} [options] - 额外选项（runOnInit / autoStart）
-   */
-  every(name, intervalMs, fn, options = {}) {
-    if (!intervalMs || intervalMs <= 0) {
-      throw new Error(`[Schedule] intervalMs 必须大于 0: ${name}`);
-    }
-    return this.add(name, { ...options, type: 'every', intervalMs, fn });
-  }
-
-  /**
-   * Cron 表达式任务
-   * @param {string} name - 任务名
-   * @param {string} expression - 5 字段 cron 表达式
-   * @param {Function} fn - 任务函数
-   * @param {Object} [options] - 额外选项（runOnInit / autoStart）
-   */
-  cron(name, expression, fn, options = {}) {
-    return this.add(name, { ...options, type: 'cron', cron: expression, fn });
-  }
-
-  /**
-   * 一次性延迟任务
-   * @param {string} name - 任务名
-   * @param {number} delayMs - 延迟毫秒
-   * @param {Function} fn - 任务函数
-   */
-  delay(name, delayMs, fn) {
-    if (!delayMs || delayMs <= 0) {
-      throw new Error(`[Schedule] delayMs 必须大于 0: ${name}`);
-    }
-    return this.add(name, { type: 'delay', delayMs, fn, autoStart: true });
-  }
-
-  /**
-   * 启动任务
-   * @param {string} name - 任务名
-   * @returns {boolean} 是否成功启动
-   */
-  start(name) {
-    const task = this._tasks.get(name);
-    if (!task) return false;
-    if (task.started) return false;
-    this._startTask(task);
-    return true;
-  }
-
-  /**
-   * 启动所有任务
-   */
-  startAll() {
-    for (const task of this._tasks.values()) {
-      if (!task.started) this._startTask(task);
-    }
-  }
-
-  /**
-   * 启动单个任务（内部）
-   * @private
-   */
-  _startTask(task) {
-    if (task.started || this._shuttingDown) return;
-    task.started = true;
-
-    // 立即执行一次
-    if (task.runOnInit) {
-      this._run(task);
-    }
-
-    this._scheduleNext(task);
-  }
-
-  /**
-   * 调度下次执行
-   * @private
-   */
-  _scheduleNext(task) {
-    if (!task.started || this._shuttingDown) return;
-
-    let delay;
-    if (task.type === 'every') {
-      delay = task.intervalMs;
-      task.nextRun = new Date(Date.now() + delay);
-    } else if (task.type === 'cron') {
-      const nextTime = nextCronTime(task.cron, task.lastRun || new Date());
-      if (!nextTime) {
-        console.warn(`[Schedule] 任务 ${task.name} 在 4 年内找不到下次执行时间，已停止`);
-        return;
-      }
-      delay = nextTime.getTime() - Date.now();
-      task.nextRun = nextTime;
-    } else if (task.type === 'delay') {
-      delay = task.delayMs;
-      task.nextRun = new Date(Date.now() + delay);
-    } else {
-      return;
-    }
-
-    // 防御：delay 过小（<0）会导致立即触发，可能死循环
-    if (delay < 0) delay = 0;
-
-    task.timer = setTimeout(() => {
-      this._run(task).then(() => {
-        // delay 类型是一次性，执行完不再调度
-        if (task.type !== 'delay') {
-          this._scheduleNext(task);
-        } else {
-          task.started = false;
-        }
-      });
-    }, delay);
-  }
-
-  /**
-   * 执行任务（错误隔离 + 防重叠）
-   * @private
-   */
-  async _run(task) {
-    // 防重叠：上次还没执行完
-    if (task.running) {
-      console.warn(`[Schedule] 任务 ${task.name} 上次未完成，跳过本次执行`);
-      return;
-    }
-
-    task.running = true;
-    task.lastRun = new Date();
-    task.runCount++;
-
-    try {
-      await task.fn();
-      task.lastError = null;
-    } catch (err) {
-      task.lastError = err;
-      task.errorCount++;
-      // 错误隔离：打印日志但不中断后续调度
-      console.error(`[Schedule] 任务 ${task.name} 执行失败:`, err.message);
-    } finally {
-      task.running = false;
-    }
-  }
-
-  /**
-   * 停止任务（保留任务，可再启动）
-   * @param {string} name - 任务名
-   * @returns {boolean} 是否成功停止
-   */
-  stop(name) {
-    const task = this._tasks.get(name);
-    if (!task) return false;
-    if (task.timer) {
-      clearTimeout(task.timer);
-      task.timer = null;
-    }
-    task.started = false;
-    task.nextRun = null;
-    return true;
-  }
-
-  /**
-   * 停止所有任务
-   */
-  stopAll() {
-    for (const name of this._tasks.keys()) {
-      this.stop(name);
-    }
-  }
-
-  /**
-   * 移除任务
-   * @param {string} name - 任务名
-   * @returns {boolean} 是否成功移除
-   */
-  remove(name) {
-    const task = this._tasks.get(name);
-    if (!task) return false;
-    this.stop(name);
-    return this._tasks.delete(name);
-  }
-
-  /**
-   * 任务是否存在
-   */
-  has(name) {
-    return this._tasks.has(name);
-  }
-
-  /**
-   * 获取单个任务状态
-   */
-  get(name) {
-    const task = this._tasks.get(name);
-    if (!task) return null;
-    return this._taskStatus(task);
-  }
-
-  /**
-   * 获取所有任务状态
-   */
-  list() {
-    return Array.from(this._tasks.values()).map(t => this._taskStatus(t));
-  }
-
-  /**
-   * 生成任务状态对象
-   * @private
-   */
-  _taskStatus(task) {
-    return {
-      name: task.name,
-      type: task.type,
-      cron: task.cronExpr,
-      intervalMs: task.intervalMs,
-      delayMs: task.delayMs,
-      started: task.started,
-      running: task.running,
-      lastRun: task.lastRun,
-      nextRun: task.nextRun,
-      lastError: task.lastError?.message || null,
-      runCount: task.runCount,
-      errorCount: task.errorCount,
-    };
-  }
-
-  /**
-   * 优雅停机：停止所有任务，拒绝后续添加
-   */
-  shutdown() {
-    this._shuttingDown = true;
-    this.stopAll();
-    console.log(`[Schedule] 已关闭所有定时任务（共 ${this._tasks.size} 个）`);
-  }
-}
-
-// 全局单例
-export const schedule = new Schedule();
-export { Schedule };
-export default Schedule;