pen-it 1.0.3 → 1.0.5

package/README.md

@@ -1,8 +1,6 @@
 # pen-it
 
-> 前端常用工具函数，笔笔记下，随手即用
-
-一个轻量级的前端工具函数库，涵盖类型判断、日期格式化、数字格式化、字符串处理、存储操作、深拷贝、数组操作、Cookie 操作、浏览器 API 等常用场景。
+用笔锚定记忆中的前端常用工具函数，一个轻量级的前端实用程序库，支持类型检查、日期/数字格式化、字符串操作、数据存储、深度克隆、数组操作、Cookie 以及浏览器 API
 
 ## 安装
 
@@ -504,4 +502,24 @@ import { isArray, formatFull, deepClone, unique } from 'pen-it'
 
   ```ts
   const off = onScroll(y => console.log(y))
+  ```
+
+---
+
+### 防抖与节流 — `control`
+
+- **`debounce(fn, delay?, options?)`** — 防抖，停止调用 delay 毫秒后才执行。
+
+  ```ts
+  const fn = debounce((val: string) => console.log(val), 500)
+  fn('a'); fn('b'); fn('c')
+  // => 'c'
+  ```
+
+- **`throttle(fn, interval?, options?)`** — 节流，固定间隔内最多执行一次。
+
+  ```ts
+  const fn = throttle((val: string) => console.log(val), 500)
+  fn('a'); fn('b'); fn('c')
+  // => 'a'，500ms 后输出 'c'
   ```

package/dist/control/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 防抖 —— 在事件被触发 n 秒后再执行，如果 n 秒内再次触发则重新计时
+ * @param fn - 需要防抖的函数
+ * @param delay - 延迟时间（毫秒），默认 300
+ * @param options.leading - 首次调用是否立即执行，默认 false
+ * @param options.trailing - 停止调用后是否延迟执行，默认 true
+ * @returns 防抖后的函数，附带 cancel 方法
+ * @example
+ * const fn = debounce((val: string) => console.log(val), 500)
+ * fn("a"); fn("b"); fn("c")
+ * // => "c"
+ */
+export declare const debounce: <T extends (...args: any[]) => any>(fn: T, delay?: number, { leading, trailing }?: {
+    leading?: boolean;
+    trailing?: boolean;
+}) => ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+/**
+ * 节流 —— 固定间隔内最多执行一次，超出频率的调用被忽略
+ * @param fn - 需要节流的函数
+ * @param interval - 间隔时间（毫秒），默认 300
+ * @param options.leading - 首次调用是否立即执行，默认 true
+ * @param options.trailing - 最后一次调用后是否尾部执行，默认 true
+ * @returns 节流后的函数，附带 cancel 方法
+ * @example
+ * const fn = throttle((val: string) => console.log(val), 500)
+ * fn("a"); fn("b"); fn("c")
+ * // => "a"，500ms 后输出 "c"
+ */
+export declare const throttle: <T extends (...args: any[]) => any>(fn: T, interval?: number, { leading, trailing }?: {
+    leading?: boolean;
+    trailing?: boolean;
+}) => ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};

package/dist/index.cjs

@@ -1020,11 +1020,98 @@ const onScroll = (callback) => {
 	return () => window.removeEventListener("scroll", handler);
 };
 //#endregion
+//#region src/control/index.ts
+/**
+* 防抖 —— 在事件被触发 n 秒后再执行，如果 n 秒内再次触发则重新计时
+* @param fn - 需要防抖的函数
+* @param delay - 延迟时间（毫秒），默认 300
+* @param options.leading - 首次调用是否立即执行，默认 false
+* @param options.trailing - 停止调用后是否延迟执行，默认 true
+* @returns 防抖后的函数，附带 cancel 方法
+* @example
+* const fn = debounce((val: string) => console.log(val), 500)
+* fn("a"); fn("b"); fn("c")
+* // => "c"
+*/
+const debounce = (fn, delay = 300, { leading = false, trailing = true } = {}) => {
+	let timer = null;
+	let lastArgs = null;
+	let shouldTrail = trailing;
+	const debounced = (...args) => {
+		lastArgs = args;
+		if (timer !== null) {
+			clearTimeout(timer);
+			shouldTrail = trailing;
+		} else if (leading) {
+			fn(...args);
+			shouldTrail = false;
+		}
+		timer = setTimeout(() => {
+			if (shouldTrail && lastArgs) fn(...lastArgs);
+			timer = lastArgs = null;
+			shouldTrail = trailing;
+		}, delay);
+	};
+	debounced.cancel = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = lastArgs = null;
+		}
+		shouldTrail = trailing;
+	};
+	return debounced;
+};
+/**
+* 节流 —— 固定间隔内最多执行一次，超出频率的调用被忽略
+* @param fn - 需要节流的函数
+* @param interval - 间隔时间（毫秒），默认 300
+* @param options.leading - 首次调用是否立即执行，默认 true
+* @param options.trailing - 最后一次调用后是否尾部执行，默认 true
+* @returns 节流后的函数，附带 cancel 方法
+* @example
+* const fn = throttle((val: string) => console.log(val), 500)
+* fn("a"); fn("b"); fn("c")
+* // => "a"，500ms 后输出 "c"
+*/
+const throttle = (fn, interval = 300, { leading = true, trailing = true } = {}) => {
+	let timer = null;
+	let lastTime = 0;
+	let pendingArgs = null;
+	const throttled = (...args) => {
+		const now = Date.now();
+		if (!lastTime && !leading) lastTime = now;
+		const remaining = interval - (now - lastTime);
+		pendingArgs = args;
+		if (remaining <= 0) {
+			if (timer) {
+				clearTimeout(timer);
+				timer = null;
+			}
+			fn(...args);
+			lastTime = now;
+			pendingArgs = null;
+		} else if (trailing && !timer) timer = setTimeout(() => {
+			timer = null;
+			lastTime = leading ? Date.now() : 0;
+			if (pendingArgs) fn(...pendingArgs);
+			pendingArgs = null;
+		}, remaining);
+	};
+	throttled.cancel = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = pendingArgs = null;
+		}
+	};
+	return throttled;
+};
+//#endregion
 exports.camelToKebab = camelToKebab;
 exports.capitalize = capitalize;
 exports.compactCN = compactCN;
 exports.compactEN = compactEN;
 exports.copyToClipboard = copyToClipboard;
+exports.debounce = debounce;
 exports.deepClone = deepClone;
 exports.deepCloneWithJSON = deepCloneWithJSON;
 exports.delCookie = delCookie;
@@ -1086,6 +1173,7 @@ exports.sortByKey = sortByKey;
 exports.sortNumAsc = sortNumAsc;
 exports.sortNumDesc = sortNumDesc;
 exports.spacePhone = spacePhone;
+exports.throttle = throttle;
 exports.toArray = toArray;
 exports.toCamel = toCamel;
 exports.toQueryString = toQueryString;

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from './copy';
 export * from './array';
 export * from './cookie';
 export * from './browser';
+export * from './control';

package/dist/index.js

@@ -1019,4 +1019,90 @@ const onScroll = (callback) => {
 	return () => window.removeEventListener("scroll", handler);
 };
 //#endregion
-export { camelToKebab, capitalize, compactCN, compactEN, copyToClipboard, deepClone, deepCloneWithJSON, delCookie, downloadFile, exportJSON, firstLower, firstUpper, formatFull, formatFullReplace, formatNum, formatRmb, formatWeek, formatYMD, getCookie, getUrlParam, getUrlParams, is, isArray, isAsyncFunction, isBoolean, isDate, isDef, isElement, isEmpty, isEmptySv, isEqual, isFloat, isFunction, isHexColor, isIOS, isInt, isNull, isNullOrUnDef, isNumber, isObject, isPC, isPrimitive, isPromise, isString, isSymbol, isUnDef, isValidEmail, isWindow, kebabToCamel, localClear, localGet, localRm, localSet, maskPhone, onScroll, percentCN, reverse, scrollToBottom, scrollToTop, setCookie, shallowClone, signed, sortByKey, sortNumAsc, sortNumDesc, spacePhone, toArray, toCamel, toQueryString, trimAll, truncate, truncateByWords, unique, uniqueByKey };
+//#region src/control/index.ts
+/**
+* 防抖 —— 在事件被触发 n 秒后再执行，如果 n 秒内再次触发则重新计时
+* @param fn - 需要防抖的函数
+* @param delay - 延迟时间（毫秒），默认 300
+* @param options.leading - 首次调用是否立即执行，默认 false
+* @param options.trailing - 停止调用后是否延迟执行，默认 true
+* @returns 防抖后的函数，附带 cancel 方法
+* @example
+* const fn = debounce((val: string) => console.log(val), 500)
+* fn("a"); fn("b"); fn("c")
+* // => "c"
+*/
+const debounce = (fn, delay = 300, { leading = false, trailing = true } = {}) => {
+	let timer = null;
+	let lastArgs = null;
+	let shouldTrail = trailing;
+	const debounced = (...args) => {
+		lastArgs = args;
+		if (timer !== null) {
+			clearTimeout(timer);
+			shouldTrail = trailing;
+		} else if (leading) {
+			fn(...args);
+			shouldTrail = false;
+		}
+		timer = setTimeout(() => {
+			if (shouldTrail && lastArgs) fn(...lastArgs);
+			timer = lastArgs = null;
+			shouldTrail = trailing;
+		}, delay);
+	};
+	debounced.cancel = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = lastArgs = null;
+		}
+		shouldTrail = trailing;
+	};
+	return debounced;
+};
+/**
+* 节流 —— 固定间隔内最多执行一次，超出频率的调用被忽略
+* @param fn - 需要节流的函数
+* @param interval - 间隔时间（毫秒），默认 300
+* @param options.leading - 首次调用是否立即执行，默认 true
+* @param options.trailing - 最后一次调用后是否尾部执行，默认 true
+* @returns 节流后的函数，附带 cancel 方法
+* @example
+* const fn = throttle((val: string) => console.log(val), 500)
+* fn("a"); fn("b"); fn("c")
+* // => "a"，500ms 后输出 "c"
+*/
+const throttle = (fn, interval = 300, { leading = true, trailing = true } = {}) => {
+	let timer = null;
+	let lastTime = 0;
+	let pendingArgs = null;
+	const throttled = (...args) => {
+		const now = Date.now();
+		if (!lastTime && !leading) lastTime = now;
+		const remaining = interval - (now - lastTime);
+		pendingArgs = args;
+		if (remaining <= 0) {
+			if (timer) {
+				clearTimeout(timer);
+				timer = null;
+			}
+			fn(...args);
+			lastTime = now;
+			pendingArgs = null;
+		} else if (trailing && !timer) timer = setTimeout(() => {
+			timer = null;
+			lastTime = leading ? Date.now() : 0;
+			if (pendingArgs) fn(...pendingArgs);
+			pendingArgs = null;
+		}, remaining);
+	};
+	throttled.cancel = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = pendingArgs = null;
+		}
+	};
+	return throttled;
+};
+//#endregion
+export { camelToKebab, capitalize, compactCN, compactEN, copyToClipboard, debounce, deepClone, deepCloneWithJSON, delCookie, downloadFile, exportJSON, firstLower, firstUpper, formatFull, formatFullReplace, formatNum, formatRmb, formatWeek, formatYMD, getCookie, getUrlParam, getUrlParams, is, isArray, isAsyncFunction, isBoolean, isDate, isDef, isElement, isEmpty, isEmptySv, isEqual, isFloat, isFunction, isHexColor, isIOS, isInt, isNull, isNullOrUnDef, isNumber, isObject, isPC, isPrimitive, isPromise, isString, isSymbol, isUnDef, isValidEmail, isWindow, kebabToCamel, localClear, localGet, localRm, localSet, maskPhone, onScroll, percentCN, reverse, scrollToBottom, scrollToTop, setCookie, shallowClone, signed, sortByKey, sortNumAsc, sortNumDesc, spacePhone, throttle, toArray, toCamel, toQueryString, trimAll, truncate, truncateByWords, unique, uniqueByKey };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pen-it",
-  "version": "1.0.3",
-  "description": "用笔锚定记忆中的前端常用工具函数 — A lightweight frontend utility library for type checking, date/number formatting, string manipulation, storage, deep clone, array operations, cookies, and browser APIs",
+  "version": "1.0.5",
+  "description": "用笔锚定记忆中的前端常用工具函数，一个轻量级的前端实用程序库，支持类型检查、日期/数字格式化、字符串操作、数据存储、深度克隆、数组操作、Cookie 以及浏览器 API",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",