npm - @cloudcome/utils-core - Versions diffs - 1.20.1 → 1.22.0 - Mend

@cloudcome/utils-core 1.20.1 → 1.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/dist/function.cjs CHANGED Viewed

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_type = require("./type.cjs");
+const require_promise = require("./promise.cjs");
 //#region src/function.ts
 /**
 * 一个空操作函数，不执行任何操作。
@@ -130,10 +131,42 @@ function fnOnce(fn) {
 		return result;
 	};
 }
+/**
+* 创建一个带重试能力的函数，失败时自动重试直到成功或耗尽次数。
+*
+* @param fn - 需要重试的函数。
+* @param options - 重试配置选项。
+* @returns 返回一个带重试能力的函数。
+*
+* @example
+* ```typescript
+* const fetchData = fnRetry(async () => {
+*   return await api.request('/data');
+* }, { maxAttempts: 3, delay: 1000 });
+*
+* // 第1次失败 → 等待1s → 第2次失败 → 等待1s → 第3次成功 → 返回结果
+* const result = await fetchData();
+* ```
+*/
+function fnRetry(fn, options = {}) {
+	const { maxAttempts = 3, delay = 0, retryWhen } = options;
+	return async function(...args) {
+		let lastError;
+		for (let attempt = 1; attempt <= maxAttempts; attempt++) try {
+			return await fn.apply(this, args);
+		} catch (error) {
+			lastError = error;
+			if (retryWhen && !retryWhen(error)) break;
+			if (attempt < maxAttempts && delay > 0) await require_promise.promiseDelay(delay);
+		}
+		throw lastError;
+	};
+}
 //#endregion
 exports.fnDebounce = fnDebounce;
 exports.fnNoop = fnNoop;
 exports.fnOnce = fnOnce;
+exports.fnRetry = fnRetry;
 exports.fnThrottle = fnThrottle;
 //# sourceMappingURL=function.cjs.map

package/dist/function.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"function.cjs","names":[],"sources":["../src/function.ts"],"sourcesContent":["import { isNumber } from './type';\nimport type { AnyFunction } from './types';\n\n/*\n 一个空操作函数，不执行任何操作。\n \n @example\n * ```typescript\n * fnNoop(); // 不执行任何操作\n * ```\n /\nexport function fnNoop() {\n //\n}\n\n/\n 防抖函数的配置选项。\n /\nexport type DebounceOptions = {\n /\n 等待时间（毫秒）。\n /\n wait: number;\n /\n 是否在等待开始时立即执行一次\n * @default false\n /\n leading?: boolean;\n};\n\n/\n 创建一个防抖函数，该函数会在指定的等待时间后执行，如果在等待时间内再次调用，则重新计时。\n \n @param fn - 需要防抖的函数。\n * @param wait - 等待时间（毫秒）或包含 `wait` 和 `leading` 选项的对象。\n * @returns 返回一个防抖函数，该函数具有 `cancel` 方法，用于取消防抖操作。\n \n @example\n * ```typescript\n * const debouncedFn = fnDebounce(() => {\n * console.log('Debounced!');\n * }, 100);\n \n debouncedFn(); // 不会立即执行\n * debouncedFn(); // 重新计时\n * debouncedFn.cancel(); // 取消防抖操作\n * ```\n /\nexport function fnDebounce<F extends AnyFunction>(fn: F, wait: number \| DebounceOptions) {\n const options: DebounceOptions = isNumber(wait) ? { wait } : wait;\n let canceled = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let timer: any;\n let leading = false;\n\n const debounced = function (this: unknown, ...args: Parameters<F>) {\n if (canceled) return;\n\n // 第一次执行\n if (options.leading && !leading) {\n leading = true;\n fn.apply(this, args);\n return;\n }\n\n // 最后一次执行\n clearTimeout(timer);\n timer = setTimeout(() => {\n if (canceled) return;\n\n fn.apply(this, args);\n }, options.wait);\n };\n\n debounced.cancel = () => {\n clearTimeout(timer);\n canceled = true;\n };\n\n return debounced;\n}\n\nexport type ThrottleOptions = {\n /\n 等待时间（毫秒）。\n /\n wait: number;\n\n /\n 是否在第一次调用时立即执行\n * @default false\n /\n leading?: boolean;\n\n /\n 是否在调用结束后等待一段时间再执行\n * @default false\n /\n trailing?: boolean;\n};\n\n/\n 创建一个节流函数，该函数会在指定的等待时间内最多执行一次，如果在等待时间内再次调用，则忽略后续调用。\n \n @param fn - 需要节流的函数。\n * @param wait - 等待时间（毫秒）或包含 `wait`、`leading` 和 `trailing` 选项的对象。\n * @returns 返回一个节流函数，该函数具有 `cancel` 方法，用于取消节流操作。\n \n @example\n * ```typescript\n * const throttledFn = fnThrottle(() => {\n * console.log('Throttled!');\n * }, 100);\n \n throttledFn(); // 立即执行\n * throttledFn(); // 忽略\n * throttledFn.cancel(); // 取消节流操作\n * ```\n /\nexport function fnThrottle<F extends AnyFunction>(fn: F, wait: number \| ThrottleOptions) {\n const options = isNumber(wait) ? { wait } : wait;\n const waitFinal = options.wait;\n let lastTime = 0;\n let canceled = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let timer: any;\n\n const throttled = function (this: unknown, ...args: Parameters<F>) {\n if (canceled) return;\n\n const now = Date.now();\n let executed = false;\n\n // 第一次执行\n if (options.leading && lastTime === 0) {\n lastTime = now;\n fn.apply(this, args);\n executed = true;\n }\n\n // 中间控频执行\n else if (lastTime > 0 && now - lastTime >= waitFinal) {\n lastTime = now;\n fn.apply(this, args);\n executed = true;\n }\n\n // 首次计时\n else if (lastTime === 0) {\n lastTime = now;\n }\n\n // 最后一次执行，仅在本次未执行时才设置 trailing\n if (options.trailing && !executed) {\n clearTimeout(timer);\n timer = setTimeout(() => {\n fn.apply(this, args);\n }, waitFinal);\n }\n };\n\n throttled.cancel = () => {\n canceled = true;\n clearTimeout(timer);\n };\n\n return throttled;\n}\n\n/\n 创建一个只执行一次的函数，无论调用多少次，实际执行的函数体也只会执行一次。\n \n @param fn - 需要只执行一次的函数。\n * @returns 返回一个只执行一次的函数，该函数在第一次调用后会缓存结果并返回缓存的结果。\n \n @example\n * ```typescript\n * const onceFn = fnOnce(() => {\n * console.log('This will be logged only once.');\n * return 42;\n * });\n \n console.log(onceFn()); // 输出: This will be logged only once. 42\n * console.log(onceFn()); // 输出: 42\n * ```\n */\nexport function fnOnce<F extends AnyFunction>(fn: F) {\n let called = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let result: any;\n\n return function (this: unknown, ...args: Parameters<F>) {\n if (!called) {\n called = true;\n result = fn.apply(this, args);\n }\n\n return result;\n };\n}\n"],"mappings":"~~;;;;;;;;;;;AAWA~~,SAAgB,SAAS;;;;;;;;;;;;;;;;;;;AAqCzB,SAAgB,WAAkC,IAAO,MAAgC;CACvF,MAAM,UAA2B,aAAA,SAAS,KAAK,GAAG,EAAE,MAAM,GAAG;CAC7D,IAAI,WAAW;CAEf,IAAI;CACJ,IAAI,UAAU;CAEd,MAAM,YAAY,SAAyB,GAAG,MAAqB;EACjE,IAAI,UAAU;EAGd,IAAI,QAAQ,WAAW,CAAC,SAAS;GAC/B,UAAU;GACV,GAAG,MAAM,MAAM,KAAK;GACpB;;EAIF,aAAa,MAAM;EACnB,QAAQ,iBAAiB;GACvB,IAAI,UAAU;GAEd,GAAG,MAAM,MAAM,KAAK;KACnB,QAAQ,KAAK;;CAGlB,UAAU,eAAe;EACvB,aAAa,MAAM;EACnB,WAAW;;CAGb,OAAO;;;;;;;;;;;;;;;;;;;;AAwCT,SAAgB,WAAkC,IAAO,MAAgC;CACvF,MAAM,UAAU,aAAA,SAAS,KAAK,GAAG,EAAE,MAAM,GAAG;CAC5C,MAAM,YAAY,QAAQ;CAC1B,IAAI,WAAW;CACf,IAAI,WAAW;CAEf,IAAI;CAEJ,MAAM,YAAY,SAAyB,GAAG,MAAqB;EACjE,IAAI,UAAU;EAEd,MAAM,MAAM,KAAK,KAAK;EACtB,IAAI,WAAW;EAGf,IAAI,QAAQ,WAAW,aAAa,GAAG;GACrC,WAAW;GACX,GAAG,MAAM,MAAM,KAAK;GACpB,WAAW;SAIR,IAAI,WAAW,KAAK,MAAM,YAAY,WAAW;GACpD,WAAW;GACX,GAAG,MAAM,MAAM,KAAK;GACpB,WAAW;SAIR,IAAI,aAAa,GACpB,WAAW;EAIb,IAAI,QAAQ,YAAY,CAAC,UAAU;GACjC,aAAa,MAAM;GACnB,QAAQ,iBAAiB;IACvB,GAAG,MAAM,MAAM,KAAK;MACnB,UAAU;;;CAIjB,UAAU,eAAe;EACvB,WAAW;EACX,aAAa,MAAM;;CAGrB,OAAO;;;;;;;;;;;;;;;;;;;AAoBT,SAAgB,OAA8B,IAAO;CACnD,IAAI,SAAS;CAEb,IAAI;CAEJ,OAAO,SAAyB,GAAG,MAAqB;EACtD,IAAI,CAAC,QAAQ;GACX,SAAS;GACT,SAAS,GAAG,MAAM,MAAM,KAAK;;EAG/B,OAAO"}
1	+ {"version":3,"file":"function.cjs","names":[],"sources":["../src/function.ts"],"sourcesContent":["import { promiseDelay } from './promise';\nimport { isNumber } from './type';\nimport type { AnyFunction } from './types';\n\n/*\n 一个空操作函数，不执行任何操作。\n \n @example\n * ```typescript\n * fnNoop(); // 不执行任何操作\n * ```\n /\nexport function fnNoop() {\n //\n}\n\n/\n 防抖函数的配置选项。\n /\nexport type DebounceOptions = {\n /\n 等待时间（毫秒）。\n /\n wait: number;\n /\n 是否在等待开始时立即执行一次\n * @default false\n /\n leading?: boolean;\n};\n\n/\n 创建一个防抖函数，该函数会在指定的等待时间后执行，如果在等待时间内再次调用，则重新计时。\n \n @param fn - 需要防抖的函数。\n * @param wait - 等待时间（毫秒）或包含 `wait` 和 `leading` 选项的对象。\n * @returns 返回一个防抖函数，该函数具有 `cancel` 方法，用于取消防抖操作。\n \n @example\n * ```typescript\n * const debouncedFn = fnDebounce(() => {\n * console.log('Debounced!');\n * }, 100);\n \n debouncedFn(); // 不会立即执行\n * debouncedFn(); // 重新计时\n * debouncedFn.cancel(); // 取消防抖操作\n * ```\n /\nexport function fnDebounce<F extends AnyFunction>(fn: F, wait: number \| DebounceOptions) {\n const options: DebounceOptions = isNumber(wait) ? { wait } : wait;\n let canceled = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let timer: any;\n let leading = false;\n\n const debounced = function (this: unknown, ...args: Parameters<F>) {\n if (canceled) return;\n\n // 第一次执行\n if (options.leading && !leading) {\n leading = true;\n fn.apply(this, args);\n return;\n }\n\n // 最后一次执行\n clearTimeout(timer);\n timer = setTimeout(() => {\n if (canceled) return;\n\n fn.apply(this, args);\n }, options.wait);\n };\n\n debounced.cancel = () => {\n clearTimeout(timer);\n canceled = true;\n };\n\n return debounced;\n}\n\nexport type ThrottleOptions = {\n /\n 等待时间（毫秒）。\n /\n wait: number;\n\n /\n 是否在第一次调用时立即执行\n * @default false\n /\n leading?: boolean;\n\n /\n 是否在调用结束后等待一段时间再执行\n * @default false\n /\n trailing?: boolean;\n};\n\n/\n 创建一个节流函数，该函数会在指定的等待时间内最多执行一次，如果在等待时间内再次调用，则忽略后续调用。\n \n @param fn - 需要节流的函数。\n * @param wait - 等待时间（毫秒）或包含 `wait`、`leading` 和 `trailing` 选项的对象。\n * @returns 返回一个节流函数，该函数具有 `cancel` 方法，用于取消节流操作。\n \n @example\n * ```typescript\n * const throttledFn = fnThrottle(() => {\n * console.log('Throttled!');\n * }, 100);\n \n throttledFn(); // 立即执行\n * throttledFn(); // 忽略\n * throttledFn.cancel(); // 取消节流操作\n * ```\n /\nexport function fnThrottle<F extends AnyFunction>(fn: F, wait: number \| ThrottleOptions) {\n const options = isNumber(wait) ? { wait } : wait;\n const waitFinal = options.wait;\n let lastTime = 0;\n let canceled = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let timer: any;\n\n const throttled = function (this: unknown, ...args: Parameters<F>) {\n if (canceled) return;\n\n const now = Date.now();\n let executed = false;\n\n // 第一次执行\n if (options.leading && lastTime === 0) {\n lastTime = now;\n fn.apply(this, args);\n executed = true;\n }\n\n // 中间控频执行\n else if (lastTime > 0 && now - lastTime >= waitFinal) {\n lastTime = now;\n fn.apply(this, args);\n executed = true;\n }\n\n // 首次计时\n else if (lastTime === 0) {\n lastTime = now;\n }\n\n // 最后一次执行，仅在本次未执行时才设置 trailing\n if (options.trailing && !executed) {\n clearTimeout(timer);\n timer = setTimeout(() => {\n fn.apply(this, args);\n }, waitFinal);\n }\n };\n\n throttled.cancel = () => {\n canceled = true;\n clearTimeout(timer);\n };\n\n return throttled;\n}\n\n/\n 创建一个只执行一次的函数，无论调用多少次，实际执行的函数体也只会执行一次。\n \n @param fn - 需要只执行一次的函数。\n * @returns 返回一个只执行一次的函数，该函数在第一次调用后会缓存结果并返回缓存的结果。\n \n @example\n * ```typescript\n * const onceFn = fnOnce(() => {\n * console.log('This will be logged only once.');\n * return 42;\n * });\n \n console.log(onceFn()); // 输出: This will be logged only once. 42\n * console.log(onceFn()); // 输出: 42\n * ```\n /\nexport function fnOnce<F extends AnyFunction>(fn: F) {\n let called = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let result: any;\n\n return function (this: unknown, ...args: Parameters<F>) {\n if (!called) {\n called = true;\n result = fn.apply(this, args);\n }\n\n return result;\n };\n}\n\nexport type FnRetryOptions = {\n /\n 最大尝试次数\n /\n maxAttempts?: number;\n /\n 每次重试之间的延迟时间（毫秒）\n * @default 0\n /\n delay?: number;\n /\n 自定义重试条件，返回 true 时触发重试\n * @default 仅在抛出错误时重试\n /\n retryWhen?: (error: unknown) => boolean;\n};\n\n/\n 创建一个带重试能力的函数，失败时自动重试直到成功或耗尽次数。\n \n @param fn - 需要重试的函数。\n * @param options - 重试配置选项。\n * @returns 返回一个带重试能力的函数。\n \n @example\n * ```typescript\n * const fetchData = fnRetry(async () => {\n * return await api.request('/data');\n * }, { maxAttempts: 3, delay: 1000 });\n \n // 第1次失败 → 等待1s → 第2次失败 → 等待1s → 第3次成功 → 返回结果\n * const result = await fetchData();\n * ```\n */\nexport function fnRetry<F extends AnyFunction>(fn: F, options: FnRetryOptions = {}) {\n const { maxAttempts = 3, delay = 0, retryWhen } = options;\n\n return async function (this: unknown, ...args: Parameters<F>): Promise<Awaited<ReturnType<F>>> {\n let lastError: unknown;\n\n for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n try {\n return (await fn.apply(this, args)) as Awaited<ReturnType<F>>;\n } catch (error) {\n lastError = error;\n\n if (retryWhen && !retryWhen(error)) break;\n\n if (attempt < maxAttempts && delay > 0) {\n await promiseDelay(delay);\n }\n }\n }\n\n throw lastError;\n };\n}\n"],"mappings":";;;;;;;;;;;;AAYA,SAAgB,SAAS;;;;;;;;;;;;;;;;;;;AAqCzB,SAAgB,WAAkC,IAAO,MAAgC;CACvF,MAAM,UAA2B,aAAA,SAAS,KAAK,GAAG,EAAE,MAAM,GAAG;CAC7D,IAAI,WAAW;CAEf,IAAI;CACJ,IAAI,UAAU;CAEd,MAAM,YAAY,SAAyB,GAAG,MAAqB;EACjE,IAAI,UAAU;EAGd,IAAI,QAAQ,WAAW,CAAC,SAAS;GAC/B,UAAU;GACV,GAAG,MAAM,MAAM,KAAK;GACpB;;EAIF,aAAa,MAAM;EACnB,QAAQ,iBAAiB;GACvB,IAAI,UAAU;GAEd,GAAG,MAAM,MAAM,KAAK;KACnB,QAAQ,KAAK;;CAGlB,UAAU,eAAe;EACvB,aAAa,MAAM;EACnB,WAAW;;CAGb,OAAO;;;;;;;;;;;;;;;;;;;;AAwCT,SAAgB,WAAkC,IAAO,MAAgC;CACvF,MAAM,UAAU,aAAA,SAAS,KAAK,GAAG,EAAE,MAAM,GAAG;CAC5C,MAAM,YAAY,QAAQ;CAC1B,IAAI,WAAW;CACf,IAAI,WAAW;CAEf,IAAI;CAEJ,MAAM,YAAY,SAAyB,GAAG,MAAqB;EACjE,IAAI,UAAU;EAEd,MAAM,MAAM,KAAK,KAAK;EACtB,IAAI,WAAW;EAGf,IAAI,QAAQ,WAAW,aAAa,GAAG;GACrC,WAAW;GACX,GAAG,MAAM,MAAM,KAAK;GACpB,WAAW;SAIR,IAAI,WAAW,KAAK,MAAM,YAAY,WAAW;GACpD,WAAW;GACX,GAAG,MAAM,MAAM,KAAK;GACpB,WAAW;SAIR,IAAI,aAAa,GACpB,WAAW;EAIb,IAAI,QAAQ,YAAY,CAAC,UAAU;GACjC,aAAa,MAAM;GACnB,QAAQ,iBAAiB;IACvB,GAAG,MAAM,MAAM,KAAK;MACnB,UAAU;;;CAIjB,UAAU,eAAe;EACvB,WAAW;EACX,aAAa,MAAM;;CAGrB,OAAO;;;;;;;;;;;;;;;;;;;AAoBT,SAAgB,OAA8B,IAAO;CACnD,IAAI,SAAS;CAEb,IAAI;CAEJ,OAAO,SAAyB,GAAG,MAAqB;EACtD,IAAI,CAAC,QAAQ;GACX,SAAS;GACT,SAAS,GAAG,MAAM,MAAM,KAAK;;EAG/B,OAAO;;;;;;;;;;;;;;;;;;;;AAsCX,SAAgB,QAA+B,IAAO,UAA0B,EAAE,EAAE;CAClF,MAAM,EAAE,cAAc,GAAG,QAAQ,GAAG,cAAc;CAElD,OAAO,eAA+B,GAAG,MAAsD;EAC7F,IAAI;EAEJ,KAAK,IAAI,UAAU,GAAG,WAAW,aAAa,WAC5C,IAAI;GACF,OAAQ,MAAM,GAAG,MAAM,MAAM,KAAK;WAC3B,OAAO;GACd,YAAY;GAEZ,IAAI,aAAa,CAAC,UAAU,MAAM,EAAE;GAEpC,IAAI,UAAU,eAAe,QAAQ,GACnC,MAAM,gBAAA,aAAa,MAAM;;EAK/B,MAAM"}

package/dist/function.d.ts CHANGED Viewed

@@ -100,3 +100,37 @@ export declare function fnThrottle<F extends AnyFunction>(fn: F, wait: number |
  * ```
  */
 export declare function fnOnce<F extends AnyFunction>(fn: F): (this: unknown, ...args: Parameters<F>) => any;
+export type FnRetryOptions = {
+    /**
+     * 最大尝试次数
+     */
+    maxAttempts?: number;
+    /**
+     * 每次重试之间的延迟时间（毫秒）
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * 自定义重试条件，返回 true 时触发重试
+     * @default 仅在抛出错误时重试
+     */
+    retryWhen?: (error: unknown) => boolean;
+};
+/**
+ * 创建一个带重试能力的函数，失败时自动重试直到成功或耗尽次数。
+ *
+ * @param fn - 需要重试的函数。
+ * @param options - 重试配置选项。
+ * @returns 返回一个带重试能力的函数。
+ *
+ * @example
+ * ```typescript
+ * const fetchData = fnRetry(async () => {
+ *   return await api.request('/data');
+ * }, { maxAttempts: 3, delay: 1000 });
+ *
+ * // 第1次失败 → 等待1s → 第2次失败 → 等待1s → 第3次成功 → 返回结果
+ * const result = await fetchData();
+ * ```
+ */
+export declare function fnRetry<F extends AnyFunction>(fn: F, options?: FnRetryOptions): (this: unknown, ...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;

package/dist/function.mjs CHANGED Viewed

@@ -1,4 +1,5 @@
 import { isNumber } from "./type.mjs";
+import { promiseDelay } from "./promise.mjs";
 //#region src/function.ts
 /**
 * 一个空操作函数，不执行任何操作。
@@ -129,7 +130,38 @@ function fnOnce(fn) {
 		return result;
 	};
 }
+/**
+* 创建一个带重试能力的函数，失败时自动重试直到成功或耗尽次数。
+*
+* @param fn - 需要重试的函数。
+* @param options - 重试配置选项。
+* @returns 返回一个带重试能力的函数。
+*
+* @example
+* ```typescript
+* const fetchData = fnRetry(async () => {
+*   return await api.request('/data');
+* }, { maxAttempts: 3, delay: 1000 });
+*
+* // 第1次失败 → 等待1s → 第2次失败 → 等待1s → 第3次成功 → 返回结果
+* const result = await fetchData();
+* ```
+*/
+function fnRetry(fn, options = {}) {
+	const { maxAttempts = 3, delay = 0, retryWhen } = options;
+	return async function(...args) {
+		let lastError;
+		for (let attempt = 1; attempt <= maxAttempts; attempt++) try {
+			return await fn.apply(this, args);
+		} catch (error) {
+			lastError = error;
+			if (retryWhen && !retryWhen(error)) break;
+			if (attempt < maxAttempts && delay > 0) await promiseDelay(delay);
+		}
+		throw lastError;
+	};
+}
 //#endregion
-export { fnDebounce, fnNoop, fnOnce, fnThrottle };
+export { fnDebounce, fnNoop, fnOnce, fnRetry, fnThrottle };
 //# sourceMappingURL=function.mjs.map

package/dist/function.mjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"function.mjs","names":[],"sources":["../src/function.ts"],"sourcesContent":["import { isNumber } from './type';\nimport type { AnyFunction } from './types';\n\n/*\n 一个空操作函数，不执行任何操作。\n \n @example\n * ```typescript\n * fnNoop(); // 不执行任何操作\n * ```\n /\nexport function fnNoop() {\n //\n}\n\n/\n 防抖函数的配置选项。\n /\nexport type DebounceOptions = {\n /\n 等待时间（毫秒）。\n /\n wait: number;\n /\n 是否在等待开始时立即执行一次\n * @default false\n /\n leading?: boolean;\n};\n\n/\n 创建一个防抖函数，该函数会在指定的等待时间后执行，如果在等待时间内再次调用，则重新计时。\n \n @param fn - 需要防抖的函数。\n * @param wait - 等待时间（毫秒）或包含 `wait` 和 `leading` 选项的对象。\n * @returns 返回一个防抖函数，该函数具有 `cancel` 方法，用于取消防抖操作。\n \n @example\n * ```typescript\n * const debouncedFn = fnDebounce(() => {\n * console.log('Debounced!');\n * }, 100);\n \n debouncedFn(); // 不会立即执行\n * debouncedFn(); // 重新计时\n * debouncedFn.cancel(); // 取消防抖操作\n * ```\n /\nexport function fnDebounce<F extends AnyFunction>(fn: F, wait: number \| DebounceOptions) {\n const options: DebounceOptions = isNumber(wait) ? { wait } : wait;\n let canceled = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let timer: any;\n let leading = false;\n\n const debounced = function (this: unknown, ...args: Parameters<F>) {\n if (canceled) return;\n\n // 第一次执行\n if (options.leading && !leading) {\n leading = true;\n fn.apply(this, args);\n return;\n }\n\n // 最后一次执行\n clearTimeout(timer);\n timer = setTimeout(() => {\n if (canceled) return;\n\n fn.apply(this, args);\n }, options.wait);\n };\n\n debounced.cancel = () => {\n clearTimeout(timer);\n canceled = true;\n };\n\n return debounced;\n}\n\nexport type ThrottleOptions = {\n /\n 等待时间（毫秒）。\n /\n wait: number;\n\n /\n 是否在第一次调用时立即执行\n * @default false\n /\n leading?: boolean;\n\n /\n 是否在调用结束后等待一段时间再执行\n * @default false\n /\n trailing?: boolean;\n};\n\n/\n 创建一个节流函数，该函数会在指定的等待时间内最多执行一次，如果在等待时间内再次调用，则忽略后续调用。\n \n @param fn - 需要节流的函数。\n * @param wait - 等待时间（毫秒）或包含 `wait`、`leading` 和 `trailing` 选项的对象。\n * @returns 返回一个节流函数，该函数具有 `cancel` 方法，用于取消节流操作。\n \n @example\n * ```typescript\n * const throttledFn = fnThrottle(() => {\n * console.log('Throttled!');\n * }, 100);\n \n throttledFn(); // 立即执行\n * throttledFn(); // 忽略\n * throttledFn.cancel(); // 取消节流操作\n * ```\n /\nexport function fnThrottle<F extends AnyFunction>(fn: F, wait: number \| ThrottleOptions) {\n const options = isNumber(wait) ? { wait } : wait;\n const waitFinal = options.wait;\n let lastTime = 0;\n let canceled = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let timer: any;\n\n const throttled = function (this: unknown, ...args: Parameters<F>) {\n if (canceled) return;\n\n const now = Date.now();\n let executed = false;\n\n // 第一次执行\n if (options.leading && lastTime === 0) {\n lastTime = now;\n fn.apply(this, args);\n executed = true;\n }\n\n // 中间控频执行\n else if (lastTime > 0 && now - lastTime >= waitFinal) {\n lastTime = now;\n fn.apply(this, args);\n executed = true;\n }\n\n // 首次计时\n else if (lastTime === 0) {\n lastTime = now;\n }\n\n // 最后一次执行，仅在本次未执行时才设置 trailing\n if (options.trailing && !executed) {\n clearTimeout(timer);\n timer = setTimeout(() => {\n fn.apply(this, args);\n }, waitFinal);\n }\n };\n\n throttled.cancel = () => {\n canceled = true;\n clearTimeout(timer);\n };\n\n return throttled;\n}\n\n/\n 创建一个只执行一次的函数，无论调用多少次，实际执行的函数体也只会执行一次。\n \n @param fn - 需要只执行一次的函数。\n * @returns 返回一个只执行一次的函数，该函数在第一次调用后会缓存结果并返回缓存的结果。\n \n @example\n * ```typescript\n * const onceFn = fnOnce(() => {\n * console.log('This will be logged only once.');\n * return 42;\n * });\n \n console.log(onceFn()); // 输出: This will be logged only once. 42\n * console.log(onceFn()); // 输出: 42\n * ```\n */\nexport function fnOnce<F extends AnyFunction>(fn: F) {\n let called = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let result: any;\n\n return function (this: unknown, ...args: Parameters<F>) {\n if (!called) {\n called = true;\n result = fn.apply(this, args);\n }\n\n return result;\n };\n}\n"],"mappings":"~~;;;;;;;;;;AAWA~~,SAAgB,SAAS;;;;;;;;;;;;;;;;;;;AAqCzB,SAAgB,WAAkC,IAAO,MAAgC;CACvF,MAAM,UAA2B,SAAS,KAAK,GAAG,EAAE,MAAM,GAAG;CAC7D,IAAI,WAAW;CAEf,IAAI;CACJ,IAAI,UAAU;CAEd,MAAM,YAAY,SAAyB,GAAG,MAAqB;EACjE,IAAI,UAAU;EAGd,IAAI,QAAQ,WAAW,CAAC,SAAS;GAC/B,UAAU;GACV,GAAG,MAAM,MAAM,KAAK;GACpB;;EAIF,aAAa,MAAM;EACnB,QAAQ,iBAAiB;GACvB,IAAI,UAAU;GAEd,GAAG,MAAM,MAAM,KAAK;KACnB,QAAQ,KAAK;;CAGlB,UAAU,eAAe;EACvB,aAAa,MAAM;EACnB,WAAW;;CAGb,OAAO;;;;;;;;;;;;;;;;;;;;AAwCT,SAAgB,WAAkC,IAAO,MAAgC;CACvF,MAAM,UAAU,SAAS,KAAK,GAAG,EAAE,MAAM,GAAG;CAC5C,MAAM,YAAY,QAAQ;CAC1B,IAAI,WAAW;CACf,IAAI,WAAW;CAEf,IAAI;CAEJ,MAAM,YAAY,SAAyB,GAAG,MAAqB;EACjE,IAAI,UAAU;EAEd,MAAM,MAAM,KAAK,KAAK;EACtB,IAAI,WAAW;EAGf,IAAI,QAAQ,WAAW,aAAa,GAAG;GACrC,WAAW;GACX,GAAG,MAAM,MAAM,KAAK;GACpB,WAAW;SAIR,IAAI,WAAW,KAAK,MAAM,YAAY,WAAW;GACpD,WAAW;GACX,GAAG,MAAM,MAAM,KAAK;GACpB,WAAW;SAIR,IAAI,aAAa,GACpB,WAAW;EAIb,IAAI,QAAQ,YAAY,CAAC,UAAU;GACjC,aAAa,MAAM;GACnB,QAAQ,iBAAiB;IACvB,GAAG,MAAM,MAAM,KAAK;MACnB,UAAU;;;CAIjB,UAAU,eAAe;EACvB,WAAW;EACX,aAAa,MAAM;;CAGrB,OAAO;;;;;;;;;;;;;;;;;;;AAoBT,SAAgB,OAA8B,IAAO;CACnD,IAAI,SAAS;CAEb,IAAI;CAEJ,OAAO,SAAyB,GAAG,MAAqB;EACtD,IAAI,CAAC,QAAQ;GACX,SAAS;GACT,SAAS,GAAG,MAAM,MAAM,KAAK;;EAG/B,OAAO"}
1	+ {"version":3,"file":"function.mjs","names":[],"sources":["../src/function.ts"],"sourcesContent":["import { promiseDelay } from './promise';\nimport { isNumber } from './type';\nimport type { AnyFunction } from './types';\n\n/*\n 一个空操作函数，不执行任何操作。\n \n @example\n * ```typescript\n * fnNoop(); // 不执行任何操作\n * ```\n /\nexport function fnNoop() {\n //\n}\n\n/\n 防抖函数的配置选项。\n /\nexport type DebounceOptions = {\n /\n 等待时间（毫秒）。\n /\n wait: number;\n /\n 是否在等待开始时立即执行一次\n * @default false\n /\n leading?: boolean;\n};\n\n/\n 创建一个防抖函数，该函数会在指定的等待时间后执行，如果在等待时间内再次调用，则重新计时。\n \n @param fn - 需要防抖的函数。\n * @param wait - 等待时间（毫秒）或包含 `wait` 和 `leading` 选项的对象。\n * @returns 返回一个防抖函数，该函数具有 `cancel` 方法，用于取消防抖操作。\n \n @example\n * ```typescript\n * const debouncedFn = fnDebounce(() => {\n * console.log('Debounced!');\n * }, 100);\n \n debouncedFn(); // 不会立即执行\n * debouncedFn(); // 重新计时\n * debouncedFn.cancel(); // 取消防抖操作\n * ```\n /\nexport function fnDebounce<F extends AnyFunction>(fn: F, wait: number \| DebounceOptions) {\n const options: DebounceOptions = isNumber(wait) ? { wait } : wait;\n let canceled = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let timer: any;\n let leading = false;\n\n const debounced = function (this: unknown, ...args: Parameters<F>) {\n if (canceled) return;\n\n // 第一次执行\n if (options.leading && !leading) {\n leading = true;\n fn.apply(this, args);\n return;\n }\n\n // 最后一次执行\n clearTimeout(timer);\n timer = setTimeout(() => {\n if (canceled) return;\n\n fn.apply(this, args);\n }, options.wait);\n };\n\n debounced.cancel = () => {\n clearTimeout(timer);\n canceled = true;\n };\n\n return debounced;\n}\n\nexport type ThrottleOptions = {\n /\n 等待时间（毫秒）。\n /\n wait: number;\n\n /\n 是否在第一次调用时立即执行\n * @default false\n /\n leading?: boolean;\n\n /\n 是否在调用结束后等待一段时间再执行\n * @default false\n /\n trailing?: boolean;\n};\n\n/\n 创建一个节流函数，该函数会在指定的等待时间内最多执行一次，如果在等待时间内再次调用，则忽略后续调用。\n \n @param fn - 需要节流的函数。\n * @param wait - 等待时间（毫秒）或包含 `wait`、`leading` 和 `trailing` 选项的对象。\n * @returns 返回一个节流函数，该函数具有 `cancel` 方法，用于取消节流操作。\n \n @example\n * ```typescript\n * const throttledFn = fnThrottle(() => {\n * console.log('Throttled!');\n * }, 100);\n \n throttledFn(); // 立即执行\n * throttledFn(); // 忽略\n * throttledFn.cancel(); // 取消节流操作\n * ```\n /\nexport function fnThrottle<F extends AnyFunction>(fn: F, wait: number \| ThrottleOptions) {\n const options = isNumber(wait) ? { wait } : wait;\n const waitFinal = options.wait;\n let lastTime = 0;\n let canceled = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let timer: any;\n\n const throttled = function (this: unknown, ...args: Parameters<F>) {\n if (canceled) return;\n\n const now = Date.now();\n let executed = false;\n\n // 第一次执行\n if (options.leading && lastTime === 0) {\n lastTime = now;\n fn.apply(this, args);\n executed = true;\n }\n\n // 中间控频执行\n else if (lastTime > 0 && now - lastTime >= waitFinal) {\n lastTime = now;\n fn.apply(this, args);\n executed = true;\n }\n\n // 首次计时\n else if (lastTime === 0) {\n lastTime = now;\n }\n\n // 最后一次执行，仅在本次未执行时才设置 trailing\n if (options.trailing && !executed) {\n clearTimeout(timer);\n timer = setTimeout(() => {\n fn.apply(this, args);\n }, waitFinal);\n }\n };\n\n throttled.cancel = () => {\n canceled = true;\n clearTimeout(timer);\n };\n\n return throttled;\n}\n\n/\n 创建一个只执行一次的函数，无论调用多少次，实际执行的函数体也只会执行一次。\n \n @param fn - 需要只执行一次的函数。\n * @returns 返回一个只执行一次的函数，该函数在第一次调用后会缓存结果并返回缓存的结果。\n \n @example\n * ```typescript\n * const onceFn = fnOnce(() => {\n * console.log('This will be logged only once.');\n * return 42;\n * });\n \n console.log(onceFn()); // 输出: This will be logged only once. 42\n * console.log(onceFn()); // 输出: 42\n * ```\n /\nexport function fnOnce<F extends AnyFunction>(fn: F) {\n let called = false;\n // biome-ignore lint/suspicious/noExplicitAny: 内部使用\n let result: any;\n\n return function (this: unknown, ...args: Parameters<F>) {\n if (!called) {\n called = true;\n result = fn.apply(this, args);\n }\n\n return result;\n };\n}\n\nexport type FnRetryOptions = {\n /\n 最大尝试次数\n /\n maxAttempts?: number;\n /\n 每次重试之间的延迟时间（毫秒）\n * @default 0\n /\n delay?: number;\n /\n 自定义重试条件，返回 true 时触发重试\n * @default 仅在抛出错误时重试\n /\n retryWhen?: (error: unknown) => boolean;\n};\n\n/\n 创建一个带重试能力的函数，失败时自动重试直到成功或耗尽次数。\n \n @param fn - 需要重试的函数。\n * @param options - 重试配置选项。\n * @returns 返回一个带重试能力的函数。\n \n @example\n * ```typescript\n * const fetchData = fnRetry(async () => {\n * return await api.request('/data');\n * }, { maxAttempts: 3, delay: 1000 });\n \n // 第1次失败 → 等待1s → 第2次失败 → 等待1s → 第3次成功 → 返回结果\n * const result = await fetchData();\n * ```\n */\nexport function fnRetry<F extends AnyFunction>(fn: F, options: FnRetryOptions = {}) {\n const { maxAttempts = 3, delay = 0, retryWhen } = options;\n\n return async function (this: unknown, ...args: Parameters<F>): Promise<Awaited<ReturnType<F>>> {\n let lastError: unknown;\n\n for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n try {\n return (await fn.apply(this, args)) as Awaited<ReturnType<F>>;\n } catch (error) {\n lastError = error;\n\n if (retryWhen && !retryWhen(error)) break;\n\n if (attempt < maxAttempts && delay > 0) {\n await promiseDelay(delay);\n }\n }\n }\n\n throw lastError;\n };\n}\n"],"mappings":";;;;;;;;;;;AAYA,SAAgB,SAAS;;;;;;;;;;;;;;;;;;;AAqCzB,SAAgB,WAAkC,IAAO,MAAgC;CACvF,MAAM,UAA2B,SAAS,KAAK,GAAG,EAAE,MAAM,GAAG;CAC7D,IAAI,WAAW;CAEf,IAAI;CACJ,IAAI,UAAU;CAEd,MAAM,YAAY,SAAyB,GAAG,MAAqB;EACjE,IAAI,UAAU;EAGd,IAAI,QAAQ,WAAW,CAAC,SAAS;GAC/B,UAAU;GACV,GAAG,MAAM,MAAM,KAAK;GACpB;;EAIF,aAAa,MAAM;EACnB,QAAQ,iBAAiB;GACvB,IAAI,UAAU;GAEd,GAAG,MAAM,MAAM,KAAK;KACnB,QAAQ,KAAK;;CAGlB,UAAU,eAAe;EACvB,aAAa,MAAM;EACnB,WAAW;;CAGb,OAAO;;;;;;;;;;;;;;;;;;;;AAwCT,SAAgB,WAAkC,IAAO,MAAgC;CACvF,MAAM,UAAU,SAAS,KAAK,GAAG,EAAE,MAAM,GAAG;CAC5C,MAAM,YAAY,QAAQ;CAC1B,IAAI,WAAW;CACf,IAAI,WAAW;CAEf,IAAI;CAEJ,MAAM,YAAY,SAAyB,GAAG,MAAqB;EACjE,IAAI,UAAU;EAEd,MAAM,MAAM,KAAK,KAAK;EACtB,IAAI,WAAW;EAGf,IAAI,QAAQ,WAAW,aAAa,GAAG;GACrC,WAAW;GACX,GAAG,MAAM,MAAM,KAAK;GACpB,WAAW;SAIR,IAAI,WAAW,KAAK,MAAM,YAAY,WAAW;GACpD,WAAW;GACX,GAAG,MAAM,MAAM,KAAK;GACpB,WAAW;SAIR,IAAI,aAAa,GACpB,WAAW;EAIb,IAAI,QAAQ,YAAY,CAAC,UAAU;GACjC,aAAa,MAAM;GACnB,QAAQ,iBAAiB;IACvB,GAAG,MAAM,MAAM,KAAK;MACnB,UAAU;;;CAIjB,UAAU,eAAe;EACvB,WAAW;EACX,aAAa,MAAM;;CAGrB,OAAO;;;;;;;;;;;;;;;;;;;AAoBT,SAAgB,OAA8B,IAAO;CACnD,IAAI,SAAS;CAEb,IAAI;CAEJ,OAAO,SAAyB,GAAG,MAAqB;EACtD,IAAI,CAAC,QAAQ;GACX,SAAS;GACT,SAAS,GAAG,MAAM,MAAM,KAAK;;EAG/B,OAAO;;;;;;;;;;;;;;;;;;;;AAsCX,SAAgB,QAA+B,IAAO,UAA0B,EAAE,EAAE;CAClF,MAAM,EAAE,cAAc,GAAG,QAAQ,GAAG,cAAc;CAElD,OAAO,eAA+B,GAAG,MAAsD;EAC7F,IAAI;EAEJ,KAAK,IAAI,UAAU,GAAG,WAAW,aAAa,WAC5C,IAAI;GACF,OAAQ,MAAM,GAAG,MAAM,MAAM,KAAK;WAC3B,OAAO;GACd,YAAY;GAEZ,IAAI,aAAa,CAAC,UAAU,MAAM,EAAE;GAEpC,IAAI,UAAU,eAAe,QAAQ,GACnC,MAAM,aAAa,MAAM;;EAK/B,MAAM"}

package/dist/index.cjs CHANGED Viewed

@@ -3,7 +3,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 /**
 * `@cloudcome/utils-core` 版本号
 */
-var VERSION = "1.20.1";
+var VERSION = "1.22.0";
 //#endregion
 exports.VERSION = VERSION;

package/dist/index.mjs CHANGED Viewed

@@ -2,7 +2,7 @@
 /**
 * `@cloudcome/utils-core` 版本号
 */
-var VERSION = "1.20.1";
+var VERSION = "1.22.0";
 //#endregion
 export { VERSION };

package/dist/timer.cjs CHANGED Viewed

@@ -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 CHANGED Viewed

	@@ -1 +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 { canStart, canStop, canPause, canResume, start, stop, pause, resume, execute } = 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,EAAE,UAAU,SAAS,UAAU,WAAW,OAAO,MAAM,OAAO,QAAQ,YAAY,~~cAAc~~,~~SAAS~~;~~EAC7G~~,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~~"}
1	+ {"version":3,"file":"timer.cjs","names":[],"sources":["../src/timer.ts"],"sourcesContent":["/*\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>) => 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 /\n runner: (state: TimerState<NoInfer<Awaited<T>>>) => 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,\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":";;AAsGA,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,OAA6C,MAAM;EAC1D,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;;;;;;;;;;;;;;;;;;;;;;;;AAqDH,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;;EAEzC;EACA;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 CHANGED Viewed

@@ -1,7 +1,7 @@
 /**
- * 定时器状态接口
+ * 定时器状态基础接口
  */
-export type TimerState = {
+export type TimerStateBase = {
     /**
      * 执行次数
      */
@@ -39,58 +39,162 @@ 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;
     /**
-     * 是否在定时器开始时立即执行回调
+     * 执行函数，每次定时器触发时调用，接收完整的定时器状态
+     */
+    runner: (state: TimerState<NoInfer<Awaited<T>>>) => 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 CHANGED Viewed

@@ -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 CHANGED Viewed

	@@ -1 +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 { canStart, canStop, canPause, canResume, start, stop, pause, resume, execute } = 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,EAAE,UAAU,SAAS,UAAU,WAAW,OAAO,MAAM,OAAO,QAAQ,YAAY,~~cAAc~~,~~SAAS~~;~~EAC7G~~,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~~"}
1	+ {"version":3,"file":"timer.mjs","names":[],"sources":["../src/timer.ts"],"sourcesContent":["/*\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>) => 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 /\n runner: (state: TimerState<NoInfer<Awaited<T>>>) => 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,\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":";AAsGA,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,OAA6C,MAAM;EAC1D,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;;;;;;;;;;;;;;;;;;;;;;;;AAqDH,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;;EAEzC;EACA;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/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cloudcome/utils-core",
-  "version": "1.20.1",
+  "version": "1.22.0",
   "description": "cloudcome core utils",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",