@sybz-components/utils 0.0.11 → 0.0.12

package/dist/base.cjs

@@ -3,7 +3,7 @@
 require('vue');
 require('consola');
 require('es-toolkit');
-const format = require('./shared/utils.D_mBxLLy.cjs');
+const format = require('./shared/utils.DUIw9c4e.cjs');
 require('element-plus');
 require('./is.cjs');
 

package/dist/base.d.cts

@@ -455,19 +455,47 @@ declare function toLine(text: string, connect?: string): string;
  */
 declare function processWidth(initValue: WidthInput, isBase: true): string;
 declare function processWidth(initValue: WidthInput, isBase?: false): WidthStyleResult | {};
+interface ThrottleOptions {
+    /**
+     * 是否在首次调用时立即执行，默认 `true`。
+     */
+    leading?: boolean;
+    /**
+     * 是否在节流周期结束时执行最后一次调用，默认 `true`。
+     */
+    trailing?: boolean;
+}
+type ThrottleOptionsInput = boolean | ThrottleOptions;
+type ThrottledFunction<T extends Func> = ((...args: Parameters<T>) => ReturnType<T> | undefined) & {
+    cancel: () => void;
+    flush: () => ReturnType<T> | undefined;
+};
 /**
  * 创建节流函数。
  *
  * @param fn 需要节流执行的函数。
  * @param delay 节流间隔，单位毫秒，默认 `1000`。
- * @returns 节流后的函数。
+ * @param options 节流选项。传 `false` 等同于 `{ leading: false }`。
+ * @param resultCallback 每次真正执行后触发的结果回调。
+ * @returns 带 `cancel()` / `flush()` 方法的节流函数。
  *
  * @example
  * const onResize = throttle(() => {
  *   console.log('resize')
  * }, 300)
+ *
+ * @example
+ * const save = throttle(saveDraft, 1000, { leading: false, trailing: true })
+ *
+ * @example
+ * const track = throttle(trackPosition, 200, { trailing: false }, (result) => {
+ *   console.log(result)
+ * })
+ *
+ * track.cancel()
+ * track.flush()
  */
-declare function throttle<T extends Func>(fn: T, delay?: number): (...args: Parameters<T>) => void;
+declare function throttle<T extends Func>(fn: T, delay?: number, options?: ThrottleOptionsInput, resultCallback?: (result: ReturnType<T>) => void): ThrottledFunction<T>;
 /**
  * 统一处理 Promise 或任务函数执行结果。
  *
@@ -513,6 +541,13 @@ type DebouncedFunction<T extends Func> = ((...args: Parameters<T>) => Promise<Aw
  * }, 300)
  *
  * await search('sybz')
+ *
+ * @example
+ * const submit = debounce(saveForm, 500, true, (result) => {
+ *   console.log(result)
+ * })
+ *
+ * submit.cancel()
  */
 declare function debounce<T extends Func>(func: T, delay?: number, immediate?: boolean, resultCallback?: (result: ReturnType<T>) => void): DebouncedFunction<T>;
 /**

package/dist/base.d.mts

@@ -455,19 +455,47 @@ declare function toLine(text: string, connect?: string): string;
  */
 declare function processWidth(initValue: WidthInput, isBase: true): string;
 declare function processWidth(initValue: WidthInput, isBase?: false): WidthStyleResult | {};
+interface ThrottleOptions {
+    /**
+     * 是否在首次调用时立即执行，默认 `true`。
+     */
+    leading?: boolean;
+    /**
+     * 是否在节流周期结束时执行最后一次调用，默认 `true`。
+     */
+    trailing?: boolean;
+}
+type ThrottleOptionsInput = boolean | ThrottleOptions;
+type ThrottledFunction<T extends Func> = ((...args: Parameters<T>) => ReturnType<T> | undefined) & {
+    cancel: () => void;
+    flush: () => ReturnType<T> | undefined;
+};
 /**
  * 创建节流函数。
  *
  * @param fn 需要节流执行的函数。
  * @param delay 节流间隔，单位毫秒，默认 `1000`。
- * @returns 节流后的函数。
+ * @param options 节流选项。传 `false` 等同于 `{ leading: false }`。
+ * @param resultCallback 每次真正执行后触发的结果回调。
+ * @returns 带 `cancel()` / `flush()` 方法的节流函数。
  *
  * @example
  * const onResize = throttle(() => {
  *   console.log('resize')
  * }, 300)
+ *
+ * @example
+ * const save = throttle(saveDraft, 1000, { leading: false, trailing: true })
+ *
+ * @example
+ * const track = throttle(trackPosition, 200, { trailing: false }, (result) => {
+ *   console.log(result)
+ * })
+ *
+ * track.cancel()
+ * track.flush()
  */
-declare function throttle<T extends Func>(fn: T, delay?: number): (...args: Parameters<T>) => void;
+declare function throttle<T extends Func>(fn: T, delay?: number, options?: ThrottleOptionsInput, resultCallback?: (result: ReturnType<T>) => void): ThrottledFunction<T>;
 /**
  * 统一处理 Promise 或任务函数执行结果。
  *
@@ -513,6 +541,13 @@ type DebouncedFunction<T extends Func> = ((...args: Parameters<T>) => Promise<Aw
  * }, 300)
  *
  * await search('sybz')
+ *
+ * @example
+ * const submit = debounce(saveForm, 500, true, (result) => {
+ *   console.log(result)
+ * })
+ *
+ * submit.cancel()
  */
 declare function debounce<T extends Func>(func: T, delay?: number, immediate?: boolean, resultCallback?: (result: ReturnType<T>) => void): DebouncedFunction<T>;
 /**

package/dist/base.d.ts

@@ -455,19 +455,47 @@ declare function toLine(text: string, connect?: string): string;
  */
 declare function processWidth(initValue: WidthInput, isBase: true): string;
 declare function processWidth(initValue: WidthInput, isBase?: false): WidthStyleResult | {};
+interface ThrottleOptions {
+    /**
+     * 是否在首次调用时立即执行，默认 `true`。
+     */
+    leading?: boolean;
+    /**
+     * 是否在节流周期结束时执行最后一次调用，默认 `true`。
+     */
+    trailing?: boolean;
+}
+type ThrottleOptionsInput = boolean | ThrottleOptions;
+type ThrottledFunction<T extends Func> = ((...args: Parameters<T>) => ReturnType<T> | undefined) & {
+    cancel: () => void;
+    flush: () => ReturnType<T> | undefined;
+};
 /**
  * 创建节流函数。
  *
  * @param fn 需要节流执行的函数。
  * @param delay 节流间隔，单位毫秒，默认 `1000`。
- * @returns 节流后的函数。
+ * @param options 节流选项。传 `false` 等同于 `{ leading: false }`。
+ * @param resultCallback 每次真正执行后触发的结果回调。
+ * @returns 带 `cancel()` / `flush()` 方法的节流函数。
  *
  * @example
  * const onResize = throttle(() => {
  *   console.log('resize')
  * }, 300)
+ *
+ * @example
+ * const save = throttle(saveDraft, 1000, { leading: false, trailing: true })
+ *
+ * @example
+ * const track = throttle(trackPosition, 200, { trailing: false }, (result) => {
+ *   console.log(result)
+ * })
+ *
+ * track.cancel()
+ * track.flush()
  */
-declare function throttle<T extends Func>(fn: T, delay?: number): (...args: Parameters<T>) => void;
+declare function throttle<T extends Func>(fn: T, delay?: number, options?: ThrottleOptionsInput, resultCallback?: (result: ReturnType<T>) => void): ThrottledFunction<T>;
 /**
  * 统一处理 Promise 或任务函数执行结果。
  *
@@ -513,6 +541,13 @@ type DebouncedFunction<T extends Func> = ((...args: Parameters<T>) => Promise<Aw
  * }, 300)
  *
  * await search('sybz')
+ *
+ * @example
+ * const submit = debounce(saveForm, 500, true, (result) => {
+ *   console.log(result)
+ * })
+ *
+ * submit.cancel()
  */
 declare function debounce<T extends Func>(func: T, delay?: number, immediate?: boolean, resultCallback?: (result: ReturnType<T>) => void): DebouncedFunction<T>;
 /**

package/dist/base.mjs

@@ -1,6 +1,6 @@
 import 'vue';
 import 'consola';
 import 'es-toolkit';
-export { $ as $toast, c as clearStorage, a as clone, b as confirm, d as copy, e as debounce, f as delay, g as getStorage, h as getType, i as getUtilsBuildTime, j as getVariable, k as isEmpty, l as log, m as merge, n as mockValue, p as processWidth, r as random, s as setStorage, t as test, o as throttle, q as toLine, u as tryCatch, v as validate, w as validateForm, x as validateOnSubmit } from './shared/utils.CCqAduBt.mjs';
+export { $ as $toast, c as clearStorage, a as clone, b as confirm, d as copy, e as debounce, f as delay, g as getStorage, h as getType, i as getUtilsBuildTime, j as getVariable, k as isEmpty, l as log, m as merge, n as mockValue, p as processWidth, r as random, s as setStorage, t as test, o as throttle, q as toLine, u as tryCatch, v as validate, w as validateForm, x as validateOnSubmit } from './shared/utils.CTnx12Vx.mjs';
 import 'element-plus';
 import './is.mjs';

package/dist/format.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-const format = require('./shared/utils.D_mBxLLy.cjs');
+const format = require('./shared/utils.DUIw9c4e.cjs');
 require('./is.cjs');
 require('consola');
 require('vue');

package/dist/format.mjs

@@ -1,4 +1,4 @@
-export { y as formatBytes, z as formatBytesConvert, A as formatDurationTime, B as formatImg, C as formatTextToHtml, D as formatThousands, E as formatTime, F as formatToFixed } from './shared/utils.CCqAduBt.mjs';
+export { y as formatBytes, z as formatBytesConvert, A as formatDurationTime, B as formatImg, C as formatTextToHtml, D as formatThousands, E as formatTime, F as formatToFixed } from './shared/utils.CTnx12Vx.mjs';
 import './is.mjs';
 import 'consola';
 import 'vue';

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-const format = require('./shared/utils.D_mBxLLy.cjs');
+const format = require('./shared/utils.DUIw9c4e.cjs');
 const day = require('./day.cjs');
 const is = require('./is.cjs');
 const ws = require('./ws.cjs');

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { $ as $toast, c as clearStorage, a as clone, b as confirm, d as copy, e as debounce, f as delay, y as formatBytes, z as formatBytesConvert, A as formatDurationTime, B as formatImg, C as formatTextToHtml, D as formatThousands, E as formatTime, F as formatToFixed, g as getStorage, h as getType, i as getUtilsBuildTime, j as getVariable, k as isEmpty, l as log, m as merge, n as mockValue, p as processWidth, r as random, s as setStorage, t as test, o as throttle, q as toLine, u as tryCatch, v as validate, w as validateForm, x as validateOnSubmit } from './shared/utils.CCqAduBt.mjs';
+export { $ as $toast, c as clearStorage, a as clone, b as confirm, d as copy, e as debounce, f as delay, y as formatBytes, z as formatBytesConvert, A as formatDurationTime, B as formatImg, C as formatTextToHtml, D as formatThousands, E as formatTime, F as formatToFixed, g as getStorage, h as getType, i as getUtilsBuildTime, j as getVariable, k as isEmpty, l as log, m as merge, n as mockValue, p as processWidth, r as random, s as setStorage, t as test, o as throttle, q as toLine, u as tryCatch, v as validate, w as validateForm, x as validateOnSubmit } from './shared/utils.CTnx12Vx.mjs';
 export { diffDate, diffDateFromCurrent, formatDate, formatDateToDay, formatDateToMinute } from './day.mjs';
 export { isArray, isBoolean, isComponent, isDate, isEmptyObject, isFunction, isIOS, isMap, isNumber, isObject, isPlainObject, isPromise, isRegExp, isSVGElement, isSet, isString, isStringNumber, isSymbol, isUrl, objectToString, toRawType, toTypeString } from './is.mjs';
 export { WS } from './ws.mjs';

package/dist/shared/{utils.CCqAduBt.mjs → utils.CTnx12Vx.mjs}

@@ -814,23 +814,79 @@ function processWidth(initValue, isBase = false) {
   }
   return isBase ? res : { width: res };
 }
-function throttle(fn, delay2 = 1e3) {
-  let last = 0;
+const normalizeThrottleOptions = (options = {}) => {
+  const normalized = typeof options === "boolean" ? { leading: options } : options;
+  return {
+    leading: normalized.leading !== false,
+    trailing: normalized.trailing !== false
+  };
+};
+function throttle(fn, delay2 = 1e3, options = {}, resultCallback) {
+  const { leading, trailing } = normalizeThrottleOptions(options);
   let timer = void 0;
-  return function(...args) {
-    let context = this;
-    let now = +/* @__PURE__ */ new Date();
-    if (now - last < delay2) {
+  let previous;
+  let lastArgs;
+  let lastThis;
+  let result;
+  const cancel = () => {
+    if (timer) {
       clearTimeout(timer);
-      timer = setTimeout(function() {
-        last = now;
-        fn.apply(context, args);
-      }, delay2);
-    } else {
-      last = now;
-      fn.apply(context, args);
+      timer = void 0;
+    }
+    previous = void 0;
+    lastArgs = void 0;
+    lastThis = void 0;
+  };
+  const invoke = () => {
+    if (!lastArgs) return result;
+    previous = Date.now();
+    const args = lastArgs;
+    const context = lastThis;
+    lastArgs = void 0;
+    lastThis = void 0;
+    result = fn.apply(context, args);
+    resultCallback?.(result);
+    return result;
+  };
+  const flush = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = void 0;
     }
+    return invoke();
+  };
+  const throttled = function(...args) {
+    const now = Date.now();
+    lastArgs = args;
+    lastThis = this;
+    if (previous === void 0) {
+      if (leading) {
+        return invoke();
+      }
+      previous = now;
+    }
+    const remaining = delay2 - (now - previous);
+    if (remaining <= 0 || remaining > delay2) {
+      if (timer) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      return invoke();
+    }
+    if (!timer && trailing) {
+      timer = setTimeout(() => {
+        timer = void 0;
+        if (!leading) {
+          previous = void 0;
+        }
+        invoke();
+      }, remaining);
+    }
+    return result;
   };
+  throttled.cancel = cancel;
+  throttled.flush = flush;
+  return throttled;
 }
 async function tryCatch(task, sendLoading) {
   const updateLoading = (value) => {
@@ -978,7 +1034,7 @@ function getVariable(propertyName, fallback = "") {
 const DEFAULT_BUILD_TIME_FALLBACK = "\u672A\u6CE8\u5165";
 function getUtilsBuildTime(fallback = DEFAULT_BUILD_TIME_FALLBACK) {
   {
-    return "2026-07-02 11:57:59";
+    return "2026-07-02 16:09:23";
   }
 }
 function test() {

package/dist/shared/{utils.D_mBxLLy.cjs → utils.DUIw9c4e.cjs}

@@ -190,7 +190,7 @@ function formatImg(photoName, addPath = "", { basePath = "assets/images" } = {})
   const addLastSlash = addPath.endsWith("/") || !addPath ? addPath : `${addPath}/`;
   const addLastBasePathSlash = basePath.endsWith("/") || !basePath ? basePath : `${basePath}/`;
   const mergeSrc = `${addLastSlash}${photoName}`;
-  return new URL(`../${addLastBasePathSlash}${mergeSrc}`, (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('shared/utils.D_mBxLLy.cjs', document.baseURI).href))).href;
+  return new URL(`../${addLastBasePathSlash}${mergeSrc}`, (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('shared/utils.DUIw9c4e.cjs', document.baseURI).href))).href;
 }
 function formatToFixed(value, options) {
   if (typeof options === "number") {
@@ -817,23 +817,79 @@ function processWidth(initValue, isBase = false) {
   }
   return isBase ? res : { width: res };
 }
-function throttle(fn, delay2 = 1e3) {
-  let last = 0;
+const normalizeThrottleOptions = (options = {}) => {
+  const normalized = typeof options === "boolean" ? { leading: options } : options;
+  return {
+    leading: normalized.leading !== false,
+    trailing: normalized.trailing !== false
+  };
+};
+function throttle(fn, delay2 = 1e3, options = {}, resultCallback) {
+  const { leading, trailing } = normalizeThrottleOptions(options);
   let timer = void 0;
-  return function(...args) {
-    let context = this;
-    let now = +/* @__PURE__ */ new Date();
-    if (now - last < delay2) {
+  let previous;
+  let lastArgs;
+  let lastThis;
+  let result;
+  const cancel = () => {
+    if (timer) {
       clearTimeout(timer);
-      timer = setTimeout(function() {
-        last = now;
-        fn.apply(context, args);
-      }, delay2);
-    } else {
-      last = now;
-      fn.apply(context, args);
+      timer = void 0;
+    }
+    previous = void 0;
+    lastArgs = void 0;
+    lastThis = void 0;
+  };
+  const invoke = () => {
+    if (!lastArgs) return result;
+    previous = Date.now();
+    const args = lastArgs;
+    const context = lastThis;
+    lastArgs = void 0;
+    lastThis = void 0;
+    result = fn.apply(context, args);
+    resultCallback?.(result);
+    return result;
+  };
+  const flush = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = void 0;
     }
+    return invoke();
+  };
+  const throttled = function(...args) {
+    const now = Date.now();
+    lastArgs = args;
+    lastThis = this;
+    if (previous === void 0) {
+      if (leading) {
+        return invoke();
+      }
+      previous = now;
+    }
+    const remaining = delay2 - (now - previous);
+    if (remaining <= 0 || remaining > delay2) {
+      if (timer) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      return invoke();
+    }
+    if (!timer && trailing) {
+      timer = setTimeout(() => {
+        timer = void 0;
+        if (!leading) {
+          previous = void 0;
+        }
+        invoke();
+      }, remaining);
+    }
+    return result;
   };
+  throttled.cancel = cancel;
+  throttled.flush = flush;
+  return throttled;
 }
 async function tryCatch(task, sendLoading) {
   const updateLoading = (value) => {
@@ -981,7 +1037,7 @@ function getVariable(propertyName, fallback = "") {
 const DEFAULT_BUILD_TIME_FALLBACK = "\u672A\u6CE8\u5165";
 function getUtilsBuildTime(fallback = DEFAULT_BUILD_TIME_FALLBACK) {
   {
-    return "2026-07-02 11:57:59";
+    return "2026-07-02 16:09:23";
   }
 }
 function test() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sybz-components/utils",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "utils of sybz-components",
   "license": "MIT",
   "type": "commonjs",