@nickyzj2023/utils 1.0.47 → 1.0.49

package/src/time/throttle.ts

@@ -0,0 +1,34 @@
+/**
+ * 节流函数 - 在指定时间间隔内最多执行一次调用
+ * @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);
+		}
+	};
+};

package/.github/workflows/docs.yml

@@ -1,39 +0,0 @@
-name: Generate Docs
-
-on:
-  push:
-    branches: [main, master]
-  pull_request:
-    branches: [main, master]
-
-jobs:
-  docs:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Generate docs
-        run: bun run docs
-
-      - name: Commit and push docs
-        if: github.event_name == 'push'
-        run: |
-          git config --local user.email "github-actions[bot]@users.noreply.github.com"
-          git config --local user.name "github-actions[bot]"
-          git add docs/
-          if git diff --staged --quiet; then
-            echo "No changes to commit"
-          else
-            git commit -m "docs: auto-generate documentation"
-            git push
-          fi

package/dist/is.d.ts

@@ -1,43 +0,0 @@
-export type Primitive = number | string | boolean | symbol | bigint | undefined | null;
-export type Falsy = false | 0 | -0 | 0n | "" | null | undefined;
-/**
- * 检测传入的值是否为**普通对象**
- *
- * @example
- * const obj = { a: 1 };
- * isObject(obj); // true
- */
-export declare const isObject: (value: any) => value is Record<string, any>;
-/**
- * 检测传入的值是否为**原始值**（number、string、boolean、symbol、bigint、undefined、null）
- *
- * @example
- * isPrimitive(1);  // true
- * isPrimitive([]); // false
- */
-export declare const isPrimitive: (value: any) => value is Primitive;
-/**
- * 检测传入的值是否为**假值**（false、0、''、null、undefined、NaN等）
- *
- * @example
- * isFalsy(""); // true
- * isFalsy(1); // false
- */
-export declare const isFalsy: (value: any) => value is Falsy;
-/**
- * 检测传入的值是否为**真值**
- *
- * @example
- * isTruthy(1); // true
- * isTruthy(""); // false
- */
-export declare const isTruthy: (value: any) => value is any;
-/**
- * 检测传入的值是否为**空值**（null、undefined）
- *
- * @example
- * isNil(null); // true
- * isNil(undefined); // true
- * isNil(1); // false
- */
-export declare const isNil: (value: any) => value is null | undefined;

package/dist/object.d.ts

@@ -1,50 +0,0 @@
-/**
- * 深度合并两个对象，规则如下：
- * 1. 原始值覆盖：如果两个值都是原始类型，则用后者覆盖;
- * 2. 数组拼接：如果两个值都是数组，则拼接为大数组；
- * 3. 对象递归合并：如果两个值都是对象，则进行递归深度合并；
- *
- * @template T 第一个对象
- * @template U 第二个对象
- * @param {T} obj1 要合并的第一个对象，相同字段会被 obj2 覆盖
- * @param {U} obj2 要合并的第二个对象
- */
-export declare const mergeObjects: <T extends Record<string, any>, U extends Record<string, any>>(obj1: T, obj2: U) => T & U;
-export type DeepMapKeys<T> = T extends Array<infer U> ? Array<DeepMapKeys<U>> : T extends object ? {
-    [key: string]: DeepMapKeys<T[keyof T]>;
-} : T;
-/**
- * 递归处理对象里的 key
- *
- * @remarks
- * 无法完整推导出类型，只能做到有递归，key 全为 string，value 为同层级的所有类型的联合
- *
- * @template T 要转换的对象
- *
- * @example
- * const obj = { a: { b: 1 } };
- * const result = mapKeys(obj, (key) => key.toUpperCase());
- * console.log(result); // { A: { B: 1 } }
- */
-export declare const mapKeys: <T>(obj: T, getNewKey: (key: string) => string) => DeepMapKeys<T>;
-export type DeepMapValues<T, R> = T extends Array<infer U> ? Array<DeepMapValues<U, R>> : T extends object ? {
-    [K in keyof T]: T[K] extends object ? DeepMapValues<T[K], R> : R;
-} : R;
-/**
- * 递归处理对象里的 value
- *
- * @remarks
- * 无法完整推导出类型，所有 value 最终都会变为 any
- *
- * @template T 要转换的对象
- * @template R 转换后的值类型，为 any，无法进一步推导
- *
- * @example
- * const obj = { a: 1, b: { c: 2 } };
- * const result = mapValues(obj, (value, key) => isPrimitive(value) ? value + 1 : value);
- * console.log(result); // { a: 2, b: { c: 3 } }
- */
-export declare const mapValues: <T, R = any>(obj: T, getNewValue: (value: any, key: string | number) => R, options?: {
-    /** 过滤函数，返回 true 表示保留该字段 */
-    filter?: (value: any, key: string | number) => boolean;
-}) => DeepMapValues<T, R>;

package/dist/time.d.ts

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

package/src/is.ts

@@ -1,70 +0,0 @@
-export type Primitive =
-	| number
-	| string
-	| boolean
-	| symbol
-	| bigint
-	| undefined
-	| null;
-
-export type Falsy = false | 0 | -0 | 0n | "" | null | undefined;
-
-/**
- * 检测传入的值是否为**普通对象**
- *
- * @example
- * const obj = { a: 1 };
- * isObject(obj); // true
- */
-export const isObject = (value: any): value is Record<string, any> => {
-	return value?.constructor === Object;
-};
-
-/**
- * 检测传入的值是否为**原始值**（number、string、boolean、symbol、bigint、undefined、null）
- *
- * @example
- * isPrimitive(1);  // true
- * isPrimitive([]); // false
- */
-export const isPrimitive = (value: any): value is Primitive => {
-	return (
-		value === null ||
-		value === undefined ||
-		(typeof value !== "object" && typeof value !== "function")
-	);
-};
-
-/**
- * 检测传入的值是否为**假值**（false、0、''、null、undefined、NaN等）
- *
- * @example
- * isFalsy(""); // true
- * isFalsy(1); // false
- */
-export const isFalsy = (value: any): value is Falsy => {
-	return !value;
-};
-
-/**
- * 检测传入的值是否为**真值**
- *
- * @example
- * isTruthy(1); // true
- * isTruthy(""); // false
- */
-export const isTruthy = (value: any): value is any => {
-	return !!value;
-};
-
-/**
- * 检测传入的值是否为**空值**（null、undefined）
- *
- * @example
- * isNil(null); // true
- * isNil(undefined); // true
- * isNil(1); // false
- */
-export const isNil = (value: any): value is null | undefined => {
-	return value === null || value === undefined;
-};

package/src/object.ts

@@ -1,179 +0,0 @@
-import { isObject, isPrimitive } from "./is";
-
-/**
- * 深度合并两个对象，规则如下：
- * 1. 原始值覆盖：如果两个值都是原始类型，则用后者覆盖;
- * 2. 数组拼接：如果两个值都是数组，则拼接为大数组；
- * 3. 对象递归合并：如果两个值都是对象，则进行递归深度合并；
- *
- * @template T 第一个对象
- * @template U 第二个对象
- * @param {T} obj1 要合并的第一个对象，相同字段会被 obj2 覆盖
- * @param {U} obj2 要合并的第二个对象
- */
-export const mergeObjects = <
-	T extends Record<string, any>,
-	U extends Record<string, any>,
->(
-	obj1: T,
-	obj2: U,
-) => {
-	const result: Record<string, any> = { ...obj1 };
-
-	for (const key of Object.keys(obj2)) {
-		const val1 = result[key];
-		const val2 = obj2[key];
-
-		// 如果都是原始值，则用后者覆盖
-		if (isPrimitive(val1) && isPrimitive(val2)) {
-			result[key] = val2;
-			continue;
-		}
-
-		// 如果都是数组，则拼接为大数组
-		if (Array.isArray(val1) && Array.isArray(val2)) {
-			result[key] = val1.concat(val2);
-			continue;
-		}
-
-		// 如果都是对象，则深度递归合并
-		if (isObject(val1) && isObject(val2)) {
-			result[key] = mergeObjects(val1, val2);
-			continue;
-		}
-
-		// 其他情况用后者覆盖
-		result[key] = val2;
-	}
-
-	return result as T & U;
-};
-
-// --- mapKeys ---
-
-// 这里的 DeepMapKeys 只能承诺 key 是 string，无法推断出 key 的具体字面量变化
-// 因为 TS 不支持根据任意函数反推 Key 的字面量类型
-export type DeepMapKeys<T> =
-	T extends Array<infer U>
-		? Array<DeepMapKeys<U>>
-		: T extends object
-			? { [key: string]: DeepMapKeys<T[keyof T]> }
-			: T;
-
-/**
- * 递归处理对象里的 key
- *
- * @remarks
- * 无法完整推导出类型，只能做到有递归，key 全为 string，value 为同层级的所有类型的联合
- *
- * @template T 要转换的对象
- *
- * @example
- * const obj = { a: { b: 1 } };
- * const result = mapKeys(obj, (key) => key.toUpperCase());
- * console.log(result); // { A: { B: 1 } }
- */
-export const mapKeys = <T>(
-	obj: T,
-	getNewKey: (key: string) => string,
-): DeepMapKeys<T> => {
-	// 递归处理数组
-	if (Array.isArray(obj)) {
-		return obj.map((item) => mapKeys(item, getNewKey)) as any;
-	}
-
-	// 处理普通对象
-	if (isObject(obj)) {
-		const keys = Object.keys(obj);
-		return keys.reduce(
-			(result, key) => {
-				const newKey = getNewKey(key);
-				const value = (obj as any)[key];
-				result[newKey] = mapKeys(value, getNewKey);
-				return result;
-			},
-			{} as Record<string, any>,
-		) as DeepMapKeys<T>;
-	}
-
-	// 处理非数组/对象
-	return obj as any;
-};
-
-// --- mapValues ---
-
-// 这里的 DeepMapValues 尝试保留 key，但将 value 类型替换为 R
-// 注意：如果原 value 是对象，我们递归处理结构，而不是把整个对象变成 R
-export type DeepMapValues<T, R> =
-	T extends Array<infer U>
-		? Array<DeepMapValues<U, R>>
-		: T extends object
-			? { [K in keyof T]: T[K] extends object ? DeepMapValues<T[K], R> : R }
-			: R;
-
-/**
- * 递归处理对象里的 value
- *
- * @remarks
- * 无法完整推导出类型，所有 value 最终都会变为 any
- *
- * @template T 要转换的对象
- * @template R 转换后的值类型，为 any，无法进一步推导
- *
- * @example
- * const obj = { a: 1, b: { c: 2 } };
- * const result = mapValues(obj, (value, key) => isPrimitive(value) ? value + 1 : value);
- * console.log(result); // { a: 2, b: { c: 3 } }
- */
-export const mapValues = <T, R = any>(
-	obj: T,
-	getNewValue: (value: any, key: string | number) => R,
-	options?: {
-		/** 过滤函数，返回 true 表示保留该字段 */
-		filter?: (value: any, key: string | number) => boolean;
-	},
-): DeepMapValues<T, R> => {
-	const { filter } = options ?? {};
-
-	// 处理数组
-	if (Array.isArray(obj)) {
-		const mappedArray = obj.map((item, index) => {
-			// 如果元素是对象，则递归处理
-			if (isObject(item)) {
-				return mapValues(item, getNewValue, options);
-			}
-			// 如果元素是原始值，则直接应用 getNewValue（此时 key 为数组下标）
-			return getNewValue(item, index);
-		});
-		// 如果有过滤器，则过滤一遍元素
-		if (filter) {
-			return mappedArray.filter((item, index) => filter(item, index)) as any;
-		}
-		return mappedArray as any;
-	}
-
-	// 处理普通对象
-	if (isObject(obj)) {
-		const keys = Object.keys(obj);
-		return keys.reduce((result, key) => {
-			const value = (obj as any)[key];
-			let newValue: any;
-			// 如果值为对象或数组，则递归处理
-			if (isObject(value) || Array.isArray(value)) {
-				newValue = mapValues(value, getNewValue, options);
-			}
-			// 否则直接应用 getNewValue
-			else {
-				newValue = getNewValue(value, key);
-			}
-			// 如果存在过滤器，则看情况保留该字段
-			if (!filter || filter(newValue, key)) {
-				result[key] = newValue;
-			}
-			return result;
-		}, {} as any) as DeepMapValues<T, R>;
-	}
-
-	// 处理非数组/对象
-	return obj as any;
-};