@cloudcome/utils-core 1.20.0 → 1.21.0

package/dist/timer.cjs

@@ -5,13 +5,29 @@ var STATUS_START = 1;
 var STATUS_PAUSE = 2;
 var STATUS_STOP = 3;
 /**
-* 创建间隔定时器核心函数
+* 创建可控制的间隔定时器核心函数
 *
-* @param nextTime - 用于安排下一次执行的函数
-* @param effect - 每次执行的回调函数，接收定时器状态和可选的next函数
-* @returns 返回包含控制方法的对象
+* @example
+* ```typescript
+* // 无 condition，state.data 为 null
+* makeInterval({
+*   dispatcher: (dispatch) => setTimeout(dispatch, 1000),
+*   runner: (state) => console.log(state.times),
+* })
+*
+* // 有 condition，T 自动推断为 number
+* makeInterval({
+*   dispatcher: (dispatch) => setTimeout(dispatch, 1000),
+*   condition: (state) => state.times,
+*   runner: (state) => state.data.toFixed(2),
+* })
+* ```
+*
+* @param options - 配置选项
+* @returns 定时器控制方法集合
 */
-function makeInterval(nextTime, effect) {
+function makeInterval(options) {
+	const { dispatcher, runner, condition, leading, trailing } = options;
 	let startAt = 0;
 	let lastAt = 0;
 	let stopAt = 0;
@@ -20,14 +36,14 @@ function makeInterval(nextTime, effect) {
 	let times = 0;
 	let status = STATUS_READY;
 	let runningTime = 0;
-	const execute = () => {
+	const execute = async () => {
 		if (status >= STATUS_PAUSE) return;
 		const now = Date.now();
 		const intervalTime = lastAt > 0 ? now - lastAt : 0;
 		runningTime += intervalTime;
 		lastAt = now;
 		const state = {
-			times: ++times,
+			times,
 			startAt,
 			stopAt,
 			pauseAt,
@@ -35,32 +51,38 @@ function makeInterval(nextTime, effect) {
 			currentAt: now,
 			elapsedTime: startAt > 0 ? now - startAt : 0,
 			runningTime,
-			intervalTime
+			intervalTime,
+			data: null
 		};
-		if (effect.length === 2) effect(state, () => {
-			nextTime(execute);
-		});
-		else {
-			effect(state);
-			nextTime(execute);
+		if (condition) try {
+			state.data = await condition(state);
+		} catch {
+			dispatcher(execute);
+			return;
 		}
+		state.times = ++times;
+		await runner(state);
+		dispatcher(execute);
 	};
 	const canStart = () => status === STATUS_READY;
 	const start = () => {
 		if (!canStart()) return;
 		status = STATUS_START;
 		startAt = Date.now();
-		execute();
+		if (leading === false) dispatcher(execute);
+		else execute();
 	};
 	const canStop = () => status === STATUS_START;
 	const stop = () => {
 		if (!canStop()) return;
+		if (trailing) execute();
 		status = STATUS_STOP;
 		stopAt = Date.now();
 	};
 	const canPause = () => status === STATUS_START;
 	const pause = () => {
 		if (!canPause()) return;
+		if (trailing) execute();
 		status = STATUS_PAUSE;
 		pauseAt = Date.now();
 	};
@@ -85,45 +107,67 @@ function makeInterval(nextTime, effect) {
 	};
 }
 /**
-* 创建一个基于 `setTimeout` 的间隔定时器
+* 创建基于 setTimeout 的间隔定时器
+*
+* @example
+* ```typescript
+* // 无 condition
+* timerInterval({
+*   interval: 1000,
+*   runner: (state) => console.log(state.times),
+* })
+*
+* // 有 condition，T 自动推断为 number
+* timerInterval({
+*   interval: 1000,
+*   condition: (state) => state.times,
+*   runner: (state) => state.data.toFixed(2),
+* })
+* ```
 *
-* @param callback - 每次间隔执行的回调函数，接收定时器状态和可选的 `next` 函数
-* @param interval - 间隔时间，单位为毫秒
 * @param options - 配置选项
-* @returns {TimerHandler}
+* @returns 定时器控制方法集合
 */
-function timeInterval(callback, interval, options) {
+function timerInterval(options) {
+	const { runner, interval, condition, leading, trailing } = options;
 	let timeId;
-	const { canStart, canStop, canPause, canResume, start, stop, pause, resume, execute } = makeInterval((call) => {
-		timeId = setTimeout(call, interval);
-	}, callback);
+	const { canStart, canStop, canPause, canResume, start, stop, pause, resume, execute } = makeInterval({
+		dispatcher: (dispatch) => {
+			timeId = setTimeout(dispatch, interval);
+		},
+		runner,
+		condition,
+		leading: leading ?? false,
+		trailing
+	});
 	return {
 		start() {
 			if (!canStart()) return;
-			if (options?.leading) start();
-			else timeId = setTimeout(start, interval);
+			start();
 		},
 		stop() {
 			if (!canStop()) return;
-			if (options?.trailing) execute();
-			clearTimeout(timeId);
 			stop();
+			clearTimeout(timeId);
 		},
 		pause() {
 			if (!canPause()) return;
-			if (options?.trailing) execute();
-			clearTimeout(timeId);
 			pause();
+			clearTimeout(timeId);
 		},
 		resume(immediate) {
 			if (!canResume()) return;
-			if (immediate || options?.leading) resume();
-			else timeId = setTimeout(resume, interval);
+			if (immediate || leading) resume();
+			else timeId = setTimeout(() => resume(), interval);
+		},
+		execute() {
+			clearTimeout(timeId);
+			execute();
 		}
 	};
 }
 //#endregion
 exports.makeInterval = makeInterval;
-exports.timeInterval = timeInterval;
+exports.timerInterval = timerInterval;
 
 //# sourceMappingURL=timer.cjs.map

package/dist/timer.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"timer.cjs","names":[],"sources":["../src/timer.ts"],"sourcesContent":["/**\n * 定时器状态接口\n */\nexport type TimerState = {\n  /**\n   * 执行次数\n   */\n  times: number;\n  /**\n   * 开始时间戳\n   */\n  startAt: number;\n  /**\n   * 停止时间戳\n   */\n  stopAt: number;\n  /**\n   * 暂停时间戳\n   */\n  pauseAt: number;\n  /**\n   * 恢复时间戳\n   */\n  resumeAt: number;\n  /**\n   * 当前时间戳\n   */\n  currentAt: number;\n  /**\n   * 总耗时（包括暂停时间）\n   */\n  elapsedTime: number;\n  /**\n   * 实际运行时间（不包括暂停时间）\n   */\n  runningTime: number;\n  /**\n   * 当前间隔时间\n   */\n  intervalTime: number;\n};\n\nexport type TimerHandler = {\n  /**\n   * 开始\n   */\n  start: () => void;\n  /**\n   * 暂停\n   */\n  pause: () => void;\n  /**\n   * 恢复\n   */\n  resume: (immediate?: boolean) => void;\n  /**\n   * 停止\n   */\n  stop: () => void;\n};\n\nconst STATUS_READY = 0;\nconst STATUS_START = 1;\nconst STATUS_PAUSE = 2;\nconst STATUS_STOP = 3;\n\n/**\n * 创建间隔定时器核心函数\n *\n * @param nextTime - 用于安排下一次执行的函数\n * @param effect - 每次执行的回调函数，接收定时器状态和可选的next函数\n * @returns 返回包含控制方法的对象\n */\nexport function makeInterval(\n  nextTime: (call: () => void) => void,\n  effect: (timer: TimerState, next?: () => void) => unknown,\n) {\n  let startAt = 0;\n  let lastAt = 0;\n  let stopAt = 0;\n  let pauseAt = 0;\n  let resumeAt = 0;\n  let times = 0;\n  let status = STATUS_READY;\n  let runningTime = 0;\n\n  const execute = () => {\n    if (status >= STATUS_PAUSE) return;\n\n    const now = Date.now();\n    const intervalTime = lastAt > 0 ? now - lastAt : 0;\n    runningTime += intervalTime;\n    lastAt = now;\n    const state: TimerState = {\n      times: ++times,\n      startAt,\n      stopAt,\n      pauseAt,\n      resumeAt,\n      currentAt: now,\n      elapsedTime: startAt > 0 ? now - startAt : 0,\n      runningTime,\n      intervalTime,\n    };\n\n    if (effect.length === 2) {\n      effect(state, () => {\n        nextTime(execute);\n      });\n    } else {\n      effect(state);\n      nextTime(execute);\n    }\n  };\n\n  const canStart = () => status === STATUS_READY;\n  const start = () => {\n    if (!canStart()) return;\n    status = STATUS_START;\n    startAt = Date.now();\n    execute();\n  };\n\n  const canStop = () => status === STATUS_START;\n  const stop = () => {\n    if (!canStop()) return;\n    status = STATUS_STOP;\n    stopAt = Date.now();\n  };\n\n  const canPause = () => status === STATUS_START;\n  const pause = () => {\n    if (!canPause()) return;\n    status = STATUS_PAUSE;\n    pauseAt = Date.now();\n  };\n\n  const canResume = () => status === STATUS_PAUSE;\n  const resume = () => {\n    if (!canResume()) return;\n    status = STATUS_START;\n    resumeAt = Date.now();\n    lastAt = resumeAt;\n    execute();\n  };\n\n  return {\n    canStart,\n    canStop,\n    canPause,\n    canResume,\n    start,\n    stop,\n    pause,\n    resume,\n    execute,\n  };\n}\n\nexport type TimerOptions = {\n  /**\n   * 是否在定时器开始时立即执行回调\n   */\n  leading?: boolean;\n  /**\n   * 是否在定时器停止时执行最后一次回调\n   */\n  trailing?: boolean;\n};\n\n/**\n * 创建一个基于 `setTimeout` 的间隔定时器\n *\n * @param callback - 每次间隔执行的回调函数，接收定时器状态和可选的 `next` 函数\n * @param interval - 间隔时间，单位为毫秒\n * @param options - 配置选项\n * @returns {TimerHandler}\n */\nexport function timeInterval(\n  callback: (state: TimerState, next?: () => void) => unknown,\n  interval: number,\n  options?: TimerOptions,\n): TimerHandler {\n  let timeId: number | NodeJS.Timeout;\n  const {\n    canStart,\n    canStop,\n    canPause,\n    canResume,\n    start,\n    stop,\n    pause,\n    resume,\n    execute,\n  } = makeInterval((call) => {\n    timeId = setTimeout(call, interval);\n  }, callback);\n\n  return {\n    start() {\n      if (!canStart()) return;\n\n      if (options?.leading) {\n        start();\n      } else {\n        timeId = setTimeout(start, interval);\n      }\n    },\n\n    stop() {\n      if (!canStop()) return;\n      if (options?.trailing) execute();\n\n      clearTimeout(timeId);\n      stop();\n    },\n\n    pause() {\n      if (!canPause()) return;\n      if (options?.trailing) execute();\n\n      clearTimeout(timeId);\n      pause();\n    },\n\n    resume(immediate?: boolean) {\n      if (!canResume()) return;\n\n      if (immediate || options?.leading) {\n        resume();\n      } else {\n        timeId = setTimeout(resume, interval);\n      }\n    },\n  };\n}\n"],"mappings":";;AA6DA,IAAM,eAAe;AACrB,IAAM,eAAe;AACrB,IAAM,eAAe;AACrB,IAAM,cAAc;;;;;;;;AASpB,SAAgB,aACd,UACA,QACA;CACA,IAAI,UAAU;CACd,IAAI,SAAS;CACb,IAAI,SAAS;CACb,IAAI,UAAU;CACd,IAAI,WAAW;CACf,IAAI,QAAQ;CACZ,IAAI,SAAS;CACb,IAAI,cAAc;CAElB,MAAM,gBAAgB;EACpB,IAAI,UAAU,cAAc;EAE5B,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,eAAe,SAAS,IAAI,MAAM,SAAS;EACjD,eAAe;EACf,SAAS;EACT,MAAM,QAAoB;GACxB,OAAO,EAAE;GACT;GACA;GACA;GACA;GACA,WAAW;GACX,aAAa,UAAU,IAAI,MAAM,UAAU;GAC3C;GACA;GACD;EAED,IAAI,OAAO,WAAW,GACpB,OAAO,aAAa;GAClB,SAAS,QAAQ;IACjB;OACG;GACL,OAAO,MAAM;GACb,SAAS,QAAQ;;;CAIrB,MAAM,iBAAiB,WAAW;CAClC,MAAM,cAAc;EAClB,IAAI,CAAC,UAAU,EAAE;EACjB,SAAS;EACT,UAAU,KAAK,KAAK;EACpB,SAAS;;CAGX,MAAM,gBAAgB,WAAW;CACjC,MAAM,aAAa;EACjB,IAAI,CAAC,SAAS,EAAE;EAChB,SAAS;EACT,SAAS,KAAK,KAAK;;CAGrB,MAAM,iBAAiB,WAAW;CAClC,MAAM,cAAc;EAClB,IAAI,CAAC,UAAU,EAAE;EACjB,SAAS;EACT,UAAU,KAAK,KAAK;;CAGtB,MAAM,kBAAkB,WAAW;CACnC,MAAM,eAAe;EACnB,IAAI,CAAC,WAAW,EAAE;EAClB,SAAS;EACT,WAAW,KAAK,KAAK;EACrB,SAAS;EACT,SAAS;;CAGX,OAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD;;;;;;;;;;AAsBH,SAAgB,aACd,UACA,UACA,SACc;CACd,IAAI;CACJ,MAAM,EACJ,UACA,SACA,UACA,WACA,OACA,MACA,OACA,QACA,YACE,cAAc,SAAS;EACzB,SAAS,WAAW,MAAM,SAAS;IAClC,SAAS;CAEZ,OAAO;EACL,QAAQ;GACN,IAAI,CAAC,UAAU,EAAE;GAEjB,IAAI,SAAS,SACX,OAAO;QAEP,SAAS,WAAW,OAAO,SAAS;;EAIxC,OAAO;GACL,IAAI,CAAC,SAAS,EAAE;GAChB,IAAI,SAAS,UAAU,SAAS;GAEhC,aAAa,OAAO;GACpB,MAAM;;EAGR,QAAQ;GACN,IAAI,CAAC,UAAU,EAAE;GACjB,IAAI,SAAS,UAAU,SAAS;GAEhC,aAAa,OAAO;GACpB,OAAO;;EAGT,OAAO,WAAqB;GAC1B,IAAI,CAAC,WAAW,EAAE;GAElB,IAAI,aAAa,SAAS,SACxB,QAAQ;QAER,SAAS,WAAW,QAAQ,SAAS;;EAG1C"}
+{"version":3,"file":"timer.cjs","names":[],"sources":["../src/timer.ts"],"sourcesContent":["import type { MaybePromise } from './types';\n\n/**\n * 定时器状态基础接口\n */\nexport type TimerStateBase = {\n  /**\n   * 执行次数\n   */\n  times: number;\n  /**\n   * 开始时间戳\n   */\n  startAt: number;\n  /**\n   * 停止时间戳\n   */\n  stopAt: number;\n  /**\n   * 暂停时间戳\n   */\n  pauseAt: number;\n  /**\n   * 恢复时间戳\n   */\n  resumeAt: number;\n  /**\n   * 当前时间戳\n   */\n  currentAt: number;\n  /**\n   * 总耗时（包括暂停时间）\n   */\n  elapsedTime: number;\n  /**\n   * 实际运行时间（不包括暂停时间）\n   */\n  runningTime: number;\n  /**\n   * 当前间隔时间\n   */\n  intervalTime: number;\n};\n\n/**\n * 定时器状态接口\n * @template T - condition 函数返回值类型，默认为 unknown\n */\nexport type TimerState<T = unknown> = TimerStateBase & {\n  /**\n   * condition 函数返回值，未传入 condition 时为 null\n   */\n  data: T;\n};\n\n/**\n * 定时器控制方法集合\n */\nexport type TimerHandler = {\n  /**\n   * 启动定时器\n   */\n  start: () => void;\n  /**\n   * 暂停定时器\n   */\n  pause: () => void;\n  /**\n   * 恢复定时器\n   * @param immediate - 是否立即执行一次\n   */\n  resume: (immediate?: boolean) => void;\n  /**\n   * 停止定时器\n   */\n  stop: () => void;\n  /**\n   * 清除上一次定时器，立即执行，并开始下一次定时器\n   */\n  execute: () => void;\n};\n\n/**\n * 间隔定时器控制方法集合，包含状态查询方法\n */\nexport type IntervalHandler = TimerHandler & {\n  /**\n   * 是否可以启动（处于 READY 状态）\n   */\n  canStart: () => boolean;\n  /**\n   * 是否可以停止（处于 START 状态）\n   */\n  canStop: () => boolean;\n  /**\n   * 是否可以暂停（处于 START 状态）\n   */\n  canPause: () => boolean;\n  /**\n   * 是否可以恢复（处于 PAUSE 状态）\n   */\n  canResume: () => boolean;\n};\n\nconst STATUS_READY = 0;\nconst STATUS_START = 1;\nconst STATUS_PAUSE = 2;\nconst STATUS_STOP = 3;\n\n/**\n * makeInterval 配置选项\n * @template T - condition 函数返回值类型\n */\nexport type MakeIntervalOptions<T> = {\n  /**\n   * 调度器函数，用于安排下一次执行\n   */\n  dispatcher: (dispatch: () => void) => unknown;\n  /**\n   * 条件函数，每次执行前调用，返回值存入 state.data\n   * 使用 MaybePromise 支持同步或异步条件判断\n   * 抛错时跳过本次 runner 执行，继续下一次调度\n   */\n  condition?: (state: TimerStateBase) => T;\n  /**\n   * 执行函数，每次定时器触发时调用，接收完整的定时器状态\n   * 使用 NoInfer<T> 阻断对该参数的泛型推断，确保 T 仅从 condition 返回值推断\n   */\n  runner: (timer: TimerState<NoInfer<Awaited<T>>>) => unknown;\n  /**\n   * 是否在定时器启动时立即执行一次，默认为 true\n   */\n  leading?: boolean;\n  /**\n   * 是否在定时器停止或暂停时额外执行一次（trailing edge）\n   */\n  trailing?: boolean;\n};\n\n/**\n * 创建可控制的间隔定时器核心函数\n *\n * @example\n * ```typescript\n * // 无 condition，state.data 为 null\n * makeInterval({\n *   dispatcher: (dispatch) => setTimeout(dispatch, 1000),\n *   runner: (state) => console.log(state.times),\n * })\n *\n * // 有 condition，T 自动推断为 number\n * makeInterval({\n *   dispatcher: (dispatch) => setTimeout(dispatch, 1000),\n *   condition: (state) => state.times,\n *   runner: (state) => state.data.toFixed(2),\n * })\n * ```\n *\n * @param options - 配置选项\n * @returns 定时器控制方法集合\n */\nexport function makeInterval<T = null>(options: MakeIntervalOptions<T>): IntervalHandler {\n  const { dispatcher, runner, condition, leading, trailing } = options;\n  let startAt = 0;\n  let lastAt = 0;\n  let stopAt = 0;\n  let pauseAt = 0;\n  let resumeAt = 0;\n  let times = 0;\n  let status = STATUS_READY;\n  let runningTime = 0;\n\n  const execute = async () => {\n    if (status >= STATUS_PAUSE) return;\n\n    const now = Date.now();\n    const intervalTime = lastAt > 0 ? now - lastAt : 0;\n    runningTime += intervalTime;\n    lastAt = now;\n    const state: TimerState<T> = {\n      times,\n      startAt,\n      stopAt,\n      pauseAt,\n      resumeAt,\n      currentAt: now,\n      elapsedTime: startAt > 0 ? now - startAt : 0,\n      runningTime,\n      intervalTime,\n      data: null as T,\n    };\n\n    if (condition) {\n      try {\n        state.data = await condition(state);\n      } catch {\n        dispatcher(execute);\n        return;\n      }\n    }\n\n    state.times = ++times;\n\n    await (runner as (timer: TimerState<T>) => MaybePromise<unknown>)(state);\n    dispatcher(execute);\n  };\n\n  const canStart = () => status === STATUS_READY;\n  const start = () => {\n    if (!canStart()) return;\n    status = STATUS_START;\n    startAt = Date.now();\n    if (leading === false) {\n      dispatcher(execute);\n    } else {\n      execute();\n    }\n  };\n\n  const canStop = () => status === STATUS_START;\n  const stop = () => {\n    if (!canStop()) return;\n    if (trailing) execute();\n    status = STATUS_STOP;\n    stopAt = Date.now();\n  };\n\n  const canPause = () => status === STATUS_START;\n  const pause = () => {\n    if (!canPause()) return;\n    if (trailing) execute();\n    status = STATUS_PAUSE;\n    pauseAt = Date.now();\n  };\n\n  const canResume = () => status === STATUS_PAUSE;\n  const resume = () => {\n    if (!canResume()) return;\n    status = STATUS_START;\n    resumeAt = Date.now();\n    lastAt = resumeAt;\n    execute();\n  };\n\n  return {\n    canStart,\n    canStop,\n    canPause,\n    canResume,\n    start,\n    stop,\n    pause,\n    resume,\n    execute,\n  };\n}\n\n/**\n * timerInterval 配置选项\n * @template T - condition 函数返回值类型\n */\nexport type TimerIntervalOptions<T> = {\n  /**\n   * 间隔时间，单位为毫秒\n   */\n  interval: number;\n  /**\n   * 条件函数，每次执行前调用，返回值存入 state.data\n   * 抛错时跳过本次 runner 执行，继续下一次调度\n   */\n  condition?: (state: TimerStateBase) => T;\n  /**\n   * 执行函数，每次定时器触发时调用，接收完整的定时器状态\n   * @param next - 可选的手动触发下一次调度的函数\n   */\n  runner: (state: TimerState<NoInfer<Awaited<T>>>, next?: () => void) => unknown;\n  /**\n   * 是否在定时器启动时立即执行一次，默认为 false\n   */\n  leading?: boolean;\n  /**\n   * 是否在定时器停止或暂停时额外执行一次（trailing edge）\n   */\n  trailing?: boolean;\n};\n\n/**\n * 创建基于 setTimeout 的间隔定时器\n *\n * @example\n * ```typescript\n * // 无 condition\n * timerInterval({\n *   interval: 1000,\n *   runner: (state) => console.log(state.times),\n * })\n *\n * // 有 condition，T 自动推断为 number\n * timerInterval({\n *   interval: 1000,\n *   condition: (state) => state.times,\n *   runner: (state) => state.data.toFixed(2),\n * })\n * ```\n *\n * @param options - 配置选项\n * @returns 定时器控制方法集合\n */\nexport function timerInterval<T = null>(options: TimerIntervalOptions<T>): TimerHandler {\n  const { runner, interval, condition, leading, trailing } = options;\n  let timeId: number | NodeJS.Timeout;\n  const { canStart, canStop, canPause, canResume, start, stop, pause, resume, execute } = makeInterval({\n    dispatcher: (dispatch) => {\n      timeId = setTimeout(dispatch, interval);\n    },\n    runner: runner as (timer: TimerState<T>) => MaybePromise<unknown>,\n    condition,\n    leading: leading ?? false,\n    trailing,\n  });\n\n  return {\n    start() {\n      if (!canStart()) return;\n      start();\n    },\n\n    stop() {\n      if (!canStop()) return;\n      stop();\n      clearTimeout(timeId);\n    },\n\n    pause() {\n      if (!canPause()) return;\n      pause();\n      clearTimeout(timeId);\n    },\n\n    resume(immediate?: boolean) {\n      if (!canResume()) return;\n      if (immediate || leading) {\n        resume();\n      } else {\n        timeId = setTimeout(() => resume(), interval);\n      }\n    },\n\n    execute() {\n      clearTimeout(timeId);\n      execute();\n    },\n  };\n}\n"],"mappings":";;AAwGA,IAAM,eAAe;AACrB,IAAM,eAAe;AACrB,IAAM,eAAe;AACrB,IAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;AAsDpB,SAAgB,aAAuB,SAAkD;CACvF,MAAM,EAAE,YAAY,QAAQ,WAAW,SAAS,aAAa;CAC7D,IAAI,UAAU;CACd,IAAI,SAAS;CACb,IAAI,SAAS;CACb,IAAI,UAAU;CACd,IAAI,WAAW;CACf,IAAI,QAAQ;CACZ,IAAI,SAAS;CACb,IAAI,cAAc;CAElB,MAAM,UAAU,YAAY;EAC1B,IAAI,UAAU,cAAc;EAE5B,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,eAAe,SAAS,IAAI,MAAM,SAAS;EACjD,eAAe;EACf,SAAS;EACT,MAAM,QAAuB;GAC3B;GACA;GACA;GACA;GACA;GACA,WAAW;GACX,aAAa,UAAU,IAAI,MAAM,UAAU;GAC3C;GACA;GACA,MAAM;GACP;EAED,IAAI,WACF,IAAI;GACF,MAAM,OAAO,MAAM,UAAU,MAAM;UAC7B;GACN,WAAW,QAAQ;GACnB;;EAIJ,MAAM,QAAQ,EAAE;EAEhB,MAAO,OAA2D,MAAM;EACxE,WAAW,QAAQ;;CAGrB,MAAM,iBAAiB,WAAW;CAClC,MAAM,cAAc;EAClB,IAAI,CAAC,UAAU,EAAE;EACjB,SAAS;EACT,UAAU,KAAK,KAAK;EACpB,IAAI,YAAY,OACd,WAAW,QAAQ;OAEnB,SAAS;;CAIb,MAAM,gBAAgB,WAAW;CACjC,MAAM,aAAa;EACjB,IAAI,CAAC,SAAS,EAAE;EAChB,IAAI,UAAU,SAAS;EACvB,SAAS;EACT,SAAS,KAAK,KAAK;;CAGrB,MAAM,iBAAiB,WAAW;CAClC,MAAM,cAAc;EAClB,IAAI,CAAC,UAAU,EAAE;EACjB,IAAI,UAAU,SAAS;EACvB,SAAS;EACT,UAAU,KAAK,KAAK;;CAGtB,MAAM,kBAAkB,WAAW;CACnC,MAAM,eAAe;EACnB,IAAI,CAAC,WAAW,EAAE;EAClB,SAAS;EACT,WAAW,KAAK,KAAK;EACrB,SAAS;EACT,SAAS;;CAGX,OAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD;;;;;;;;;;;;;;;;;;;;;;;;AAsDH,SAAgB,cAAwB,SAAgD;CACtF,MAAM,EAAE,QAAQ,UAAU,WAAW,SAAS,aAAa;CAC3D,IAAI;CACJ,MAAM,EAAE,UAAU,SAAS,UAAU,WAAW,OAAO,MAAM,OAAO,QAAQ,YAAY,aAAa;EACnG,aAAa,aAAa;GACxB,SAAS,WAAW,UAAU,SAAS;;EAEjC;EACR;EACA,SAAS,WAAW;EACpB;EACD,CAAC;CAEF,OAAO;EACL,QAAQ;GACN,IAAI,CAAC,UAAU,EAAE;GACjB,OAAO;;EAGT,OAAO;GACL,IAAI,CAAC,SAAS,EAAE;GAChB,MAAM;GACN,aAAa,OAAO;;EAGtB,QAAQ;GACN,IAAI,CAAC,UAAU,EAAE;GACjB,OAAO;GACP,aAAa,OAAO;;EAGtB,OAAO,WAAqB;GAC1B,IAAI,CAAC,WAAW,EAAE;GAClB,IAAI,aAAa,SACf,QAAQ;QAER,SAAS,iBAAiB,QAAQ,EAAE,SAAS;;EAIjD,UAAU;GACR,aAAa,OAAO;GACpB,SAAS;;EAEZ"}

package/dist/timer.d.ts

@@ -1,7 +1,7 @@
 /**
- * 定时器状态接口
+ * 定时器状态基础接口
  */
-export type TimerState = {
+export type TimerStateBase = {
     /**
      * 执行次数
      */
@@ -39,58 +39,163 @@ export type TimerState = {
      */
     intervalTime: number;
 };
+/**
+ * 定时器状态接口
+ * @template T - condition 函数返回值类型，默认为 unknown
+ */
+export type TimerState<T = unknown> = TimerStateBase & {
+    /**
+     * condition 函数返回值，未传入 condition 时为 null
+     */
+    data: T;
+};
+/**
+ * 定时器控制方法集合
+ */
 export type TimerHandler = {
     /**
-     * 开始
+     * 启动定时器
      */
     start: () => void;
     /**
-     * 暂停
+     * 暂停定时器
      */
     pause: () => void;
     /**
-     * 恢复
+     * 恢复定时器
+     * @param immediate - 是否立即执行一次
      */
     resume: (immediate?: boolean) => void;
     /**
-     * 停止
+     * 停止定时器
      */
     stop: () => void;
+    /**
+     * 清除上一次定时器，立即执行，并开始下一次定时器
+     */
+    execute: () => void;
 };
 /**
- * 创建间隔定时器核心函数
- *
- * @param nextTime - 用于安排下一次执行的函数
- * @param effect - 每次执行的回调函数，接收定时器状态和可选的next函数
- * @returns 返回包含控制方法的对象
+ * 间隔定时器控制方法集合，包含状态查询方法
  */
-export declare function makeInterval(nextTime: (call: () => void) => void, effect: (timer: TimerState, next?: () => void) => unknown): {
+export type IntervalHandler = TimerHandler & {
+    /**
+     * 是否可以启动（处于 READY 状态）
+     */
     canStart: () => boolean;
+    /**
+     * 是否可以停止（处于 START 状态）
+     */
     canStop: () => boolean;
+    /**
+     * 是否可以暂停（处于 START 状态）
+     */
     canPause: () => boolean;
+    /**
+     * 是否可以恢复（处于 PAUSE 状态）
+     */
     canResume: () => boolean;
-    start: () => void;
-    stop: () => void;
-    pause: () => void;
-    resume: () => void;
-    execute: () => void;
 };
-export type TimerOptions = {
+/**
+ * makeInterval 配置选项
+ * @template T - condition 函数返回值类型
+ */
+export type MakeIntervalOptions<T> = {
+    /**
+     * 调度器函数，用于安排下一次执行
+     */
+    dispatcher: (dispatch: () => void) => unknown;
+    /**
+     * 条件函数，每次执行前调用，返回值存入 state.data
+     * 使用 MaybePromise 支持同步或异步条件判断
+     * 抛错时跳过本次 runner 执行，继续下一次调度
+     */
+    condition?: (state: TimerStateBase) => T;
+    /**
+     * 执行函数，每次定时器触发时调用，接收完整的定时器状态
+     * 使用 NoInfer<T> 阻断对该参数的泛型推断，确保 T 仅从 condition 返回值推断
+     */
+    runner: (timer: TimerState<NoInfer<Awaited<T>>>) => unknown;
+    /**
+     * 是否在定时器启动时立即执行一次，默认为 true
+     */
+    leading?: boolean;
+    /**
+     * 是否在定时器停止或暂停时额外执行一次（trailing edge）
+     */
+    trailing?: boolean;
+};
+/**
+ * 创建可控制的间隔定时器核心函数
+ *
+ * @example
+ * ```typescript
+ * // 无 condition，state.data 为 null
+ * makeInterval({
+ *   dispatcher: (dispatch) => setTimeout(dispatch, 1000),
+ *   runner: (state) => console.log(state.times),
+ * })
+ *
+ * // 有 condition，T 自动推断为 number
+ * makeInterval({
+ *   dispatcher: (dispatch) => setTimeout(dispatch, 1000),
+ *   condition: (state) => state.times,
+ *   runner: (state) => state.data.toFixed(2),
+ * })
+ * ```
+ *
+ * @param options - 配置选项
+ * @returns 定时器控制方法集合
+ */
+export declare function makeInterval<T = null>(options: MakeIntervalOptions<T>): IntervalHandler;
+/**
+ * timerInterval 配置选项
+ * @template T - condition 函数返回值类型
+ */
+export type TimerIntervalOptions<T> = {
+    /**
+     * 间隔时间，单位为毫秒
+     */
+    interval: number;
+    /**
+     * 条件函数，每次执行前调用，返回值存入 state.data
+     * 抛错时跳过本次 runner 执行，继续下一次调度
+     */
+    condition?: (state: TimerStateBase) => T;
     /**
-     * 是否在定时器开始时立即执行回调
+     * 执行函数，每次定时器触发时调用，接收完整的定时器状态
+     * @param next - 可选的手动触发下一次调度的函数
+     */
+    runner: (state: TimerState<NoInfer<Awaited<T>>>, next?: () => void) => unknown;
+    /**
+     * 是否在定时器启动时立即执行一次，默认为 false
      */
     leading?: boolean;
     /**
-     * 是否在定时器停止时执行最后一次回调
+     * 是否在定时器停止或暂停时额外执行一次（trailing edge）
      */
     trailing?: boolean;
 };
 /**
- * 创建一个基于 `setTimeout` 的间隔定时器
+ * 创建基于 setTimeout 的间隔定时器
+ *
+ * @example
+ * ```typescript
+ * // 无 condition
+ * timerInterval({
+ *   interval: 1000,
+ *   runner: (state) => console.log(state.times),
+ * })
+ *
+ * // 有 condition，T 自动推断为 number
+ * timerInterval({
+ *   interval: 1000,
+ *   condition: (state) => state.times,
+ *   runner: (state) => state.data.toFixed(2),
+ * })
+ * ```
  *
- * @param callback - 每次间隔执行的回调函数，接收定时器状态和可选的 `next` 函数
- * @param interval - 间隔时间，单位为毫秒
  * @param options - 配置选项
- * @returns {TimerHandler}
+ * @returns 定时器控制方法集合
  */
-export declare function timeInterval(callback: (state: TimerState, next?: () => void) => unknown, interval: number, options?: TimerOptions): TimerHandler;
+export declare function timerInterval<T = null>(options: TimerIntervalOptions<T>): TimerHandler;

package/dist/timer.mjs

@@ -4,13 +4,29 @@ var STATUS_START = 1;
 var STATUS_PAUSE = 2;
 var STATUS_STOP = 3;
 /**
-* 创建间隔定时器核心函数
+* 创建可控制的间隔定时器核心函数
 *
-* @param nextTime - 用于安排下一次执行的函数
-* @param effect - 每次执行的回调函数，接收定时器状态和可选的next函数
-* @returns 返回包含控制方法的对象
+* @example
+* ```typescript
+* // 无 condition，state.data 为 null
+* makeInterval({
+*   dispatcher: (dispatch) => setTimeout(dispatch, 1000),
+*   runner: (state) => console.log(state.times),
+* })
+*
+* // 有 condition，T 自动推断为 number
+* makeInterval({
+*   dispatcher: (dispatch) => setTimeout(dispatch, 1000),
+*   condition: (state) => state.times,
+*   runner: (state) => state.data.toFixed(2),
+* })
+* ```
+*
+* @param options - 配置选项
+* @returns 定时器控制方法集合
 */
-function makeInterval(nextTime, effect) {
+function makeInterval(options) {
+	const { dispatcher, runner, condition, leading, trailing } = options;
 	let startAt = 0;
 	let lastAt = 0;
 	let stopAt = 0;
@@ -19,14 +35,14 @@ function makeInterval(nextTime, effect) {
 	let times = 0;
 	let status = STATUS_READY;
 	let runningTime = 0;
-	const execute = () => {
+	const execute = async () => {
 		if (status >= STATUS_PAUSE) return;
 		const now = Date.now();
 		const intervalTime = lastAt > 0 ? now - lastAt : 0;
 		runningTime += intervalTime;
 		lastAt = now;
 		const state = {
-			times: ++times,
+			times,
 			startAt,
 			stopAt,
 			pauseAt,
@@ -34,32 +50,38 @@ function makeInterval(nextTime, effect) {
 			currentAt: now,
 			elapsedTime: startAt > 0 ? now - startAt : 0,
 			runningTime,
-			intervalTime
+			intervalTime,
+			data: null
 		};
-		if (effect.length === 2) effect(state, () => {
-			nextTime(execute);
-		});
-		else {
-			effect(state);
-			nextTime(execute);
+		if (condition) try {
+			state.data = await condition(state);
+		} catch {
+			dispatcher(execute);
+			return;
 		}
+		state.times = ++times;
+		await runner(state);
+		dispatcher(execute);
 	};
 	const canStart = () => status === STATUS_READY;
 	const start = () => {
 		if (!canStart()) return;
 		status = STATUS_START;
 		startAt = Date.now();
-		execute();
+		if (leading === false) dispatcher(execute);
+		else execute();
 	};
 	const canStop = () => status === STATUS_START;
 	const stop = () => {
 		if (!canStop()) return;
+		if (trailing) execute();
 		status = STATUS_STOP;
 		stopAt = Date.now();
 	};
 	const canPause = () => status === STATUS_START;
 	const pause = () => {
 		if (!canPause()) return;
+		if (trailing) execute();
 		status = STATUS_PAUSE;
 		pauseAt = Date.now();
 	};
@@ -84,44 +106,66 @@ function makeInterval(nextTime, effect) {
 	};
 }
 /**
-* 创建一个基于 `setTimeout` 的间隔定时器
+* 创建基于 setTimeout 的间隔定时器
+*
+* @example
+* ```typescript
+* // 无 condition
+* timerInterval({
+*   interval: 1000,
+*   runner: (state) => console.log(state.times),
+* })
+*
+* // 有 condition，T 自动推断为 number
+* timerInterval({
+*   interval: 1000,
+*   condition: (state) => state.times,
+*   runner: (state) => state.data.toFixed(2),
+* })
+* ```
 *
-* @param callback - 每次间隔执行的回调函数，接收定时器状态和可选的 `next` 函数
-* @param interval - 间隔时间，单位为毫秒
 * @param options - 配置选项
-* @returns {TimerHandler}
+* @returns 定时器控制方法集合
 */
-function timeInterval(callback, interval, options) {
+function timerInterval(options) {
+	const { runner, interval, condition, leading, trailing } = options;
 	let timeId;
-	const { canStart, canStop, canPause, canResume, start, stop, pause, resume, execute } = makeInterval((call) => {
-		timeId = setTimeout(call, interval);
-	}, callback);
+	const { canStart, canStop, canPause, canResume, start, stop, pause, resume, execute } = makeInterval({
+		dispatcher: (dispatch) => {
+			timeId = setTimeout(dispatch, interval);
+		},
+		runner,
+		condition,
+		leading: leading ?? false,
+		trailing
+	});
 	return {
 		start() {
 			if (!canStart()) return;
-			if (options?.leading) start();
-			else timeId = setTimeout(start, interval);
+			start();
 		},
 		stop() {
 			if (!canStop()) return;
-			if (options?.trailing) execute();
-			clearTimeout(timeId);
 			stop();
+			clearTimeout(timeId);
 		},
 		pause() {
 			if (!canPause()) return;
-			if (options?.trailing) execute();
-			clearTimeout(timeId);
 			pause();
+			clearTimeout(timeId);
 		},
 		resume(immediate) {
 			if (!canResume()) return;
-			if (immediate || options?.leading) resume();
-			else timeId = setTimeout(resume, interval);
+			if (immediate || leading) resume();
+			else timeId = setTimeout(() => resume(), interval);
+		},
+		execute() {
+			clearTimeout(timeId);
+			execute();
 		}
 	};
 }
 //#endregion
-export { makeInterval, timeInterval };
+export { makeInterval, timerInterval };
 
 //# sourceMappingURL=timer.mjs.map

package/dist/timer.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"timer.mjs","names":[],"sources":["../src/timer.ts"],"sourcesContent":["/**\n * 定时器状态接口\n */\nexport type TimerState = {\n  /**\n   * 执行次数\n   */\n  times: number;\n  /**\n   * 开始时间戳\n   */\n  startAt: number;\n  /**\n   * 停止时间戳\n   */\n  stopAt: number;\n  /**\n   * 暂停时间戳\n   */\n  pauseAt: number;\n  /**\n   * 恢复时间戳\n   */\n  resumeAt: number;\n  /**\n   * 当前时间戳\n   */\n  currentAt: number;\n  /**\n   * 总耗时（包括暂停时间）\n   */\n  elapsedTime: number;\n  /**\n   * 实际运行时间（不包括暂停时间）\n   */\n  runningTime: number;\n  /**\n   * 当前间隔时间\n   */\n  intervalTime: number;\n};\n\nexport type TimerHandler = {\n  /**\n   * 开始\n   */\n  start: () => void;\n  /**\n   * 暂停\n   */\n  pause: () => void;\n  /**\n   * 恢复\n   */\n  resume: (immediate?: boolean) => void;\n  /**\n   * 停止\n   */\n  stop: () => void;\n};\n\nconst STATUS_READY = 0;\nconst STATUS_START = 1;\nconst STATUS_PAUSE = 2;\nconst STATUS_STOP = 3;\n\n/**\n * 创建间隔定时器核心函数\n *\n * @param nextTime - 用于安排下一次执行的函数\n * @param effect - 每次执行的回调函数，接收定时器状态和可选的next函数\n * @returns 返回包含控制方法的对象\n */\nexport function makeInterval(\n  nextTime: (call: () => void) => void,\n  effect: (timer: TimerState, next?: () => void) => unknown,\n) {\n  let startAt = 0;\n  let lastAt = 0;\n  let stopAt = 0;\n  let pauseAt = 0;\n  let resumeAt = 0;\n  let times = 0;\n  let status = STATUS_READY;\n  let runningTime = 0;\n\n  const execute = () => {\n    if (status >= STATUS_PAUSE) return;\n\n    const now = Date.now();\n    const intervalTime = lastAt > 0 ? now - lastAt : 0;\n    runningTime += intervalTime;\n    lastAt = now;\n    const state: TimerState = {\n      times: ++times,\n      startAt,\n      stopAt,\n      pauseAt,\n      resumeAt,\n      currentAt: now,\n      elapsedTime: startAt > 0 ? now - startAt : 0,\n      runningTime,\n      intervalTime,\n    };\n\n    if (effect.length === 2) {\n      effect(state, () => {\n        nextTime(execute);\n      });\n    } else {\n      effect(state);\n      nextTime(execute);\n    }\n  };\n\n  const canStart = () => status === STATUS_READY;\n  const start = () => {\n    if (!canStart()) return;\n    status = STATUS_START;\n    startAt = Date.now();\n    execute();\n  };\n\n  const canStop = () => status === STATUS_START;\n  const stop = () => {\n    if (!canStop()) return;\n    status = STATUS_STOP;\n    stopAt = Date.now();\n  };\n\n  const canPause = () => status === STATUS_START;\n  const pause = () => {\n    if (!canPause()) return;\n    status = STATUS_PAUSE;\n    pauseAt = Date.now();\n  };\n\n  const canResume = () => status === STATUS_PAUSE;\n  const resume = () => {\n    if (!canResume()) return;\n    status = STATUS_START;\n    resumeAt = Date.now();\n    lastAt = resumeAt;\n    execute();\n  };\n\n  return {\n    canStart,\n    canStop,\n    canPause,\n    canResume,\n    start,\n    stop,\n    pause,\n    resume,\n    execute,\n  };\n}\n\nexport type TimerOptions = {\n  /**\n   * 是否在定时器开始时立即执行回调\n   */\n  leading?: boolean;\n  /**\n   * 是否在定时器停止时执行最后一次回调\n   */\n  trailing?: boolean;\n};\n\n/**\n * 创建一个基于 `setTimeout` 的间隔定时器\n *\n * @param callback - 每次间隔执行的回调函数，接收定时器状态和可选的 `next` 函数\n * @param interval - 间隔时间，单位为毫秒\n * @param options - 配置选项\n * @returns {TimerHandler}\n */\nexport function timeInterval(\n  callback: (state: TimerState, next?: () => void) => unknown,\n  interval: number,\n  options?: TimerOptions,\n): TimerHandler {\n  let timeId: number | NodeJS.Timeout;\n  const {\n    canStart,\n    canStop,\n    canPause,\n    canResume,\n    start,\n    stop,\n    pause,\n    resume,\n    execute,\n  } = makeInterval((call) => {\n    timeId = setTimeout(call, interval);\n  }, callback);\n\n  return {\n    start() {\n      if (!canStart()) return;\n\n      if (options?.leading) {\n        start();\n      } else {\n        timeId = setTimeout(start, interval);\n      }\n    },\n\n    stop() {\n      if (!canStop()) return;\n      if (options?.trailing) execute();\n\n      clearTimeout(timeId);\n      stop();\n    },\n\n    pause() {\n      if (!canPause()) return;\n      if (options?.trailing) execute();\n\n      clearTimeout(timeId);\n      pause();\n    },\n\n    resume(immediate?: boolean) {\n      if (!canResume()) return;\n\n      if (immediate || options?.leading) {\n        resume();\n      } else {\n        timeId = setTimeout(resume, interval);\n      }\n    },\n  };\n}\n"],"mappings":";AA6DA,IAAM,eAAe;AACrB,IAAM,eAAe;AACrB,IAAM,eAAe;AACrB,IAAM,cAAc;;;;;;;;AASpB,SAAgB,aACd,UACA,QACA;CACA,IAAI,UAAU;CACd,IAAI,SAAS;CACb,IAAI,SAAS;CACb,IAAI,UAAU;CACd,IAAI,WAAW;CACf,IAAI,QAAQ;CACZ,IAAI,SAAS;CACb,IAAI,cAAc;CAElB,MAAM,gBAAgB;EACpB,IAAI,UAAU,cAAc;EAE5B,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,eAAe,SAAS,IAAI,MAAM,SAAS;EACjD,eAAe;EACf,SAAS;EACT,MAAM,QAAoB;GACxB,OAAO,EAAE;GACT;GACA;GACA;GACA;GACA,WAAW;GACX,aAAa,UAAU,IAAI,MAAM,UAAU;GAC3C;GACA;GACD;EAED,IAAI,OAAO,WAAW,GACpB,OAAO,aAAa;GAClB,SAAS,QAAQ;IACjB;OACG;GACL,OAAO,MAAM;GACb,SAAS,QAAQ;;;CAIrB,MAAM,iBAAiB,WAAW;CAClC,MAAM,cAAc;EAClB,IAAI,CAAC,UAAU,EAAE;EACjB,SAAS;EACT,UAAU,KAAK,KAAK;EACpB,SAAS;;CAGX,MAAM,gBAAgB,WAAW;CACjC,MAAM,aAAa;EACjB,IAAI,CAAC,SAAS,EAAE;EAChB,SAAS;EACT,SAAS,KAAK,KAAK;;CAGrB,MAAM,iBAAiB,WAAW;CAClC,MAAM,cAAc;EAClB,IAAI,CAAC,UAAU,EAAE;EACjB,SAAS;EACT,UAAU,KAAK,KAAK;;CAGtB,MAAM,kBAAkB,WAAW;CACnC,MAAM,eAAe;EACnB,IAAI,CAAC,WAAW,EAAE;EAClB,SAAS;EACT,WAAW,KAAK,KAAK;EACrB,SAAS;EACT,SAAS;;CAGX,OAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD;;;;;;;;;;AAsBH,SAAgB,aACd,UACA,UACA,SACc;CACd,IAAI;CACJ,MAAM,EACJ,UACA,SACA,UACA,WACA,OACA,MACA,OACA,QACA,YACE,cAAc,SAAS;EACzB,SAAS,WAAW,MAAM,SAAS;IAClC,SAAS;CAEZ,OAAO;EACL,QAAQ;GACN,IAAI,CAAC,UAAU,EAAE;GAEjB,IAAI,SAAS,SACX,OAAO;QAEP,SAAS,WAAW,OAAO,SAAS;;EAIxC,OAAO;GACL,IAAI,CAAC,SAAS,EAAE;GAChB,IAAI,SAAS,UAAU,SAAS;GAEhC,aAAa,OAAO;GACpB,MAAM;;EAGR,QAAQ;GACN,IAAI,CAAC,UAAU,EAAE;GACjB,IAAI,SAAS,UAAU,SAAS;GAEhC,aAAa,OAAO;GACpB,OAAO;;EAGT,OAAO,WAAqB;GAC1B,IAAI,CAAC,WAAW,EAAE;GAElB,IAAI,aAAa,SAAS,SACxB,QAAQ;QAER,SAAS,WAAW,QAAQ,SAAS;;EAG1C"}
+{"version":3,"file":"timer.mjs","names":[],"sources":["../src/timer.ts"],"sourcesContent":["import type { MaybePromise } from './types';\n\n/**\n * 定时器状态基础接口\n */\nexport type TimerStateBase = {\n  /**\n   * 执行次数\n   */\n  times: number;\n  /**\n   * 开始时间戳\n   */\n  startAt: number;\n  /**\n   * 停止时间戳\n   */\n  stopAt: number;\n  /**\n   * 暂停时间戳\n   */\n  pauseAt: number;\n  /**\n   * 恢复时间戳\n   */\n  resumeAt: number;\n  /**\n   * 当前时间戳\n   */\n  currentAt: number;\n  /**\n   * 总耗时（包括暂停时间）\n   */\n  elapsedTime: number;\n  /**\n   * 实际运行时间（不包括暂停时间）\n   */\n  runningTime: number;\n  /**\n   * 当前间隔时间\n   */\n  intervalTime: number;\n};\n\n/**\n * 定时器状态接口\n * @template T - condition 函数返回值类型，默认为 unknown\n */\nexport type TimerState<T = unknown> = TimerStateBase & {\n  /**\n   * condition 函数返回值，未传入 condition 时为 null\n   */\n  data: T;\n};\n\n/**\n * 定时器控制方法集合\n */\nexport type TimerHandler = {\n  /**\n   * 启动定时器\n   */\n  start: () => void;\n  /**\n   * 暂停定时器\n   */\n  pause: () => void;\n  /**\n   * 恢复定时器\n   * @param immediate - 是否立即执行一次\n   */\n  resume: (immediate?: boolean) => void;\n  /**\n   * 停止定时器\n   */\n  stop: () => void;\n  /**\n   * 清除上一次定时器，立即执行，并开始下一次定时器\n   */\n  execute: () => void;\n};\n\n/**\n * 间隔定时器控制方法集合，包含状态查询方法\n */\nexport type IntervalHandler = TimerHandler & {\n  /**\n   * 是否可以启动（处于 READY 状态）\n   */\n  canStart: () => boolean;\n  /**\n   * 是否可以停止（处于 START 状态）\n   */\n  canStop: () => boolean;\n  /**\n   * 是否可以暂停（处于 START 状态）\n   */\n  canPause: () => boolean;\n  /**\n   * 是否可以恢复（处于 PAUSE 状态）\n   */\n  canResume: () => boolean;\n};\n\nconst STATUS_READY = 0;\nconst STATUS_START = 1;\nconst STATUS_PAUSE = 2;\nconst STATUS_STOP = 3;\n\n/**\n * makeInterval 配置选项\n * @template T - condition 函数返回值类型\n */\nexport type MakeIntervalOptions<T> = {\n  /**\n   * 调度器函数，用于安排下一次执行\n   */\n  dispatcher: (dispatch: () => void) => unknown;\n  /**\n   * 条件函数，每次执行前调用，返回值存入 state.data\n   * 使用 MaybePromise 支持同步或异步条件判断\n   * 抛错时跳过本次 runner 执行，继续下一次调度\n   */\n  condition?: (state: TimerStateBase) => T;\n  /**\n   * 执行函数，每次定时器触发时调用，接收完整的定时器状态\n   * 使用 NoInfer<T> 阻断对该参数的泛型推断，确保 T 仅从 condition 返回值推断\n   */\n  runner: (timer: TimerState<NoInfer<Awaited<T>>>) => unknown;\n  /**\n   * 是否在定时器启动时立即执行一次，默认为 true\n   */\n  leading?: boolean;\n  /**\n   * 是否在定时器停止或暂停时额外执行一次（trailing edge）\n   */\n  trailing?: boolean;\n};\n\n/**\n * 创建可控制的间隔定时器核心函数\n *\n * @example\n * ```typescript\n * // 无 condition，state.data 为 null\n * makeInterval({\n *   dispatcher: (dispatch) => setTimeout(dispatch, 1000),\n *   runner: (state) => console.log(state.times),\n * })\n *\n * // 有 condition，T 自动推断为 number\n * makeInterval({\n *   dispatcher: (dispatch) => setTimeout(dispatch, 1000),\n *   condition: (state) => state.times,\n *   runner: (state) => state.data.toFixed(2),\n * })\n * ```\n *\n * @param options - 配置选项\n * @returns 定时器控制方法集合\n */\nexport function makeInterval<T = null>(options: MakeIntervalOptions<T>): IntervalHandler {\n  const { dispatcher, runner, condition, leading, trailing } = options;\n  let startAt = 0;\n  let lastAt = 0;\n  let stopAt = 0;\n  let pauseAt = 0;\n  let resumeAt = 0;\n  let times = 0;\n  let status = STATUS_READY;\n  let runningTime = 0;\n\n  const execute = async () => {\n    if (status >= STATUS_PAUSE) return;\n\n    const now = Date.now();\n    const intervalTime = lastAt > 0 ? now - lastAt : 0;\n    runningTime += intervalTime;\n    lastAt = now;\n    const state: TimerState<T> = {\n      times,\n      startAt,\n      stopAt,\n      pauseAt,\n      resumeAt,\n      currentAt: now,\n      elapsedTime: startAt > 0 ? now - startAt : 0,\n      runningTime,\n      intervalTime,\n      data: null as T,\n    };\n\n    if (condition) {\n      try {\n        state.data = await condition(state);\n      } catch {\n        dispatcher(execute);\n        return;\n      }\n    }\n\n    state.times = ++times;\n\n    await (runner as (timer: TimerState<T>) => MaybePromise<unknown>)(state);\n    dispatcher(execute);\n  };\n\n  const canStart = () => status === STATUS_READY;\n  const start = () => {\n    if (!canStart()) return;\n    status = STATUS_START;\n    startAt = Date.now();\n    if (leading === false) {\n      dispatcher(execute);\n    } else {\n      execute();\n    }\n  };\n\n  const canStop = () => status === STATUS_START;\n  const stop = () => {\n    if (!canStop()) return;\n    if (trailing) execute();\n    status = STATUS_STOP;\n    stopAt = Date.now();\n  };\n\n  const canPause = () => status === STATUS_START;\n  const pause = () => {\n    if (!canPause()) return;\n    if (trailing) execute();\n    status = STATUS_PAUSE;\n    pauseAt = Date.now();\n  };\n\n  const canResume = () => status === STATUS_PAUSE;\n  const resume = () => {\n    if (!canResume()) return;\n    status = STATUS_START;\n    resumeAt = Date.now();\n    lastAt = resumeAt;\n    execute();\n  };\n\n  return {\n    canStart,\n    canStop,\n    canPause,\n    canResume,\n    start,\n    stop,\n    pause,\n    resume,\n    execute,\n  };\n}\n\n/**\n * timerInterval 配置选项\n * @template T - condition 函数返回值类型\n */\nexport type TimerIntervalOptions<T> = {\n  /**\n   * 间隔时间，单位为毫秒\n   */\n  interval: number;\n  /**\n   * 条件函数，每次执行前调用，返回值存入 state.data\n   * 抛错时跳过本次 runner 执行，继续下一次调度\n   */\n  condition?: (state: TimerStateBase) => T;\n  /**\n   * 执行函数，每次定时器触发时调用，接收完整的定时器状态\n   * @param next - 可选的手动触发下一次调度的函数\n   */\n  runner: (state: TimerState<NoInfer<Awaited<T>>>, next?: () => void) => unknown;\n  /**\n   * 是否在定时器启动时立即执行一次，默认为 false\n   */\n  leading?: boolean;\n  /**\n   * 是否在定时器停止或暂停时额外执行一次（trailing edge）\n   */\n  trailing?: boolean;\n};\n\n/**\n * 创建基于 setTimeout 的间隔定时器\n *\n * @example\n * ```typescript\n * // 无 condition\n * timerInterval({\n *   interval: 1000,\n *   runner: (state) => console.log(state.times),\n * })\n *\n * // 有 condition，T 自动推断为 number\n * timerInterval({\n *   interval: 1000,\n *   condition: (state) => state.times,\n *   runner: (state) => state.data.toFixed(2),\n * })\n * ```\n *\n * @param options - 配置选项\n * @returns 定时器控制方法集合\n */\nexport function timerInterval<T = null>(options: TimerIntervalOptions<T>): TimerHandler {\n  const { runner, interval, condition, leading, trailing } = options;\n  let timeId: number | NodeJS.Timeout;\n  const { canStart, canStop, canPause, canResume, start, stop, pause, resume, execute } = makeInterval({\n    dispatcher: (dispatch) => {\n      timeId = setTimeout(dispatch, interval);\n    },\n    runner: runner as (timer: TimerState<T>) => MaybePromise<unknown>,\n    condition,\n    leading: leading ?? false,\n    trailing,\n  });\n\n  return {\n    start() {\n      if (!canStart()) return;\n      start();\n    },\n\n    stop() {\n      if (!canStop()) return;\n      stop();\n      clearTimeout(timeId);\n    },\n\n    pause() {\n      if (!canPause()) return;\n      pause();\n      clearTimeout(timeId);\n    },\n\n    resume(immediate?: boolean) {\n      if (!canResume()) return;\n      if (immediate || leading) {\n        resume();\n      } else {\n        timeId = setTimeout(() => resume(), interval);\n      }\n    },\n\n    execute() {\n      clearTimeout(timeId);\n      execute();\n    },\n  };\n}\n"],"mappings":";AAwGA,IAAM,eAAe;AACrB,IAAM,eAAe;AACrB,IAAM,eAAe;AACrB,IAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;AAsDpB,SAAgB,aAAuB,SAAkD;CACvF,MAAM,EAAE,YAAY,QAAQ,WAAW,SAAS,aAAa;CAC7D,IAAI,UAAU;CACd,IAAI,SAAS;CACb,IAAI,SAAS;CACb,IAAI,UAAU;CACd,IAAI,WAAW;CACf,IAAI,QAAQ;CACZ,IAAI,SAAS;CACb,IAAI,cAAc;CAElB,MAAM,UAAU,YAAY;EAC1B,IAAI,UAAU,cAAc;EAE5B,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,eAAe,SAAS,IAAI,MAAM,SAAS;EACjD,eAAe;EACf,SAAS;EACT,MAAM,QAAuB;GAC3B;GACA;GACA;GACA;GACA;GACA,WAAW;GACX,aAAa,UAAU,IAAI,MAAM,UAAU;GAC3C;GACA;GACA,MAAM;GACP;EAED,IAAI,WACF,IAAI;GACF,MAAM,OAAO,MAAM,UAAU,MAAM;UAC7B;GACN,WAAW,QAAQ;GACnB;;EAIJ,MAAM,QAAQ,EAAE;EAEhB,MAAO,OAA2D,MAAM;EACxE,WAAW,QAAQ;;CAGrB,MAAM,iBAAiB,WAAW;CAClC,MAAM,cAAc;EAClB,IAAI,CAAC,UAAU,EAAE;EACjB,SAAS;EACT,UAAU,KAAK,KAAK;EACpB,IAAI,YAAY,OACd,WAAW,QAAQ;OAEnB,SAAS;;CAIb,MAAM,gBAAgB,WAAW;CACjC,MAAM,aAAa;EACjB,IAAI,CAAC,SAAS,EAAE;EAChB,IAAI,UAAU,SAAS;EACvB,SAAS;EACT,SAAS,KAAK,KAAK;;CAGrB,MAAM,iBAAiB,WAAW;CAClC,MAAM,cAAc;EAClB,IAAI,CAAC,UAAU,EAAE;EACjB,IAAI,UAAU,SAAS;EACvB,SAAS;EACT,UAAU,KAAK,KAAK;;CAGtB,MAAM,kBAAkB,WAAW;CACnC,MAAM,eAAe;EACnB,IAAI,CAAC,WAAW,EAAE;EAClB,SAAS;EACT,WAAW,KAAK,KAAK;EACrB,SAAS;EACT,SAAS;;CAGX,OAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD;;;;;;;;;;;;;;;;;;;;;;;;AAsDH,SAAgB,cAAwB,SAAgD;CACtF,MAAM,EAAE,QAAQ,UAAU,WAAW,SAAS,aAAa;CAC3D,IAAI;CACJ,MAAM,EAAE,UAAU,SAAS,UAAU,WAAW,OAAO,MAAM,OAAO,QAAQ,YAAY,aAAa;EACnG,aAAa,aAAa;GACxB,SAAS,WAAW,UAAU,SAAS;;EAEjC;EACR;EACA,SAAS,WAAW;EACpB;EACD,CAAC;CAEF,OAAO;EACL,QAAQ;GACN,IAAI,CAAC,UAAU,EAAE;GACjB,OAAO;;EAGT,OAAO;GACL,IAAI,CAAC,SAAS,EAAE;GAChB,MAAM;GACN,aAAa,OAAO;;EAGtB,QAAQ;GACN,IAAI,CAAC,UAAU,EAAE;GACjB,OAAO;GACP,aAAa,OAAO;;EAGtB,OAAO,WAAqB;GAC1B,IAAI,CAAC,WAAW,EAAE;GAClB,IAAI,aAAa,SACf,QAAQ;QAER,SAAS,iBAAiB,QAAQ,EAAE,SAAS;;EAIjD,UAAU;GACR,aAAa,OAAO;GACpB,SAAS;;EAEZ"}