@nickyzj2023/utils 1.0.41 → 1.0.42

package/package.json

@@ -1,26 +1,26 @@
 {
-  "name": "@nickyzj2023/utils",
-  "version": "1.0.41",
-  "type": "module",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "docs": "typedoc src/index.ts --plugin typedoc-material-theme",
-    "build": "bun build --target=bun --outdir ./dist --minify ./src/index.ts && tsc && bun run docs"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.13",
-    "@types/bun": "^1.3.8",
-    "typedoc": "^0.28.16"
-  },
-  "peerDependencies": {
-    "typescript": "^5.9.3"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Nickyzj628/utils.git"
-  },
-  "dependencies": {
-    "typedoc-material-theme": "^1.4.1"
-  }
+	"name": "@nickyzj2023/utils",
+	"version": "1.0.42",
+	"type": "module",
+	"module": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"scripts": {
+		"docs": "typedoc src/index.ts --plugin typedoc-material-theme",
+		"build": "bun build --target=bun --outdir ./dist --minify ./src/index.ts && tsc && bun run docs"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.14",
+		"@types/bun": "^1.3.8",
+		"typedoc": "^0.28.16"
+	},
+	"peerDependencies": {
+		"typescript": "^5.9.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Nickyzj628/utils.git"
+	},
+	"dependencies": {
+		"typedoc-material-theme": "^1.4.1"
+	}
 }

package/src/time.ts

@@ -9,3 +9,73 @@ export const sleep = async (time = 150) => {
 		setTimeout(resolve, time);
 	});
 };
+
+/**
+ * 防抖：在指定时间内只执行最后一次调用
+ * @param fn 要防抖的函数
+ * @param delay 延迟时间，默认 300ms
+ *
+ * @remarks
+ * 连续触发时，只有最后一次会执行。适合用于搜索框输入、窗口大小调整等场景。
+ * 例如：用户输入"hello"过程中，不会触发搜索，只有停下来时才执行。
+ *
+ * 防抖 vs 节流：
+ * - 防抖：等待触发停止后才执行（最后一次）
+ * - 节流：按固定节奏执行（每隔多久执行一次）
+ *
+ * @example
+ * const search = debounce((keyword: string) => {
+ *   console.log('搜索:', keyword);
+ * });
+ * search('hello'); // 300ms 后执行
+ */
+export const debounce = <T extends (...args: any[]) => any>(
+	fn: T,
+	delay = 300,
+) => {
+	let timer: ReturnType<typeof setTimeout> | null = null;
+
+	return (...args: Parameters<T>) => {
+		if (timer) {
+			clearTimeout(timer);
+		}
+		timer = setTimeout(() => {
+			fn(...args);
+		}, delay);
+	};
+};
+
+/**
+ * 节流函数 - 在指定时间间隔内最多执行一次调用
+ * @param fn 要节流的函数
+ * @param delay 间隔时间，默认 300ms
+ *
+ * @remarks
+ * 节流：连续触发时，按照固定间隔执行。适合用于滚动、拖拽等高频触发场景。
+ * 例如：滚动页面时，每300ms最多执行一次回调，而不是每次滚动都执行。
+ *
+ * 防抖 vs 节流：
+ * - 防抖：等待触发停止后才执行（最后一次）
+ * - 节流：按固定节奏执行（每隔多久执行一次）
+ *
+ * @example
+ * const handleScroll = throttle(() => {
+ *   console.log('滚动位置:', window.scrollY);
+ * }, 200);
+ * window.addEventListener('scroll', handleScroll);
+ */
+export const throttle = <T extends (...args: any[]) => any>(
+	fn: T,
+	delay = 300,
+) => {
+	let timer: ReturnType<typeof setTimeout> | null = null;
+
+	return function (this: any, ...args: Parameters<T>) {
+		if (!timer) {
+			timer = setTimeout(() => {
+				timer = null;
+				fn.apply(this, args);
+			}, delay);
+		}
+	};
+};