@nickyzj2023/utils 1.0.48 → 1.0.50

package/src/{hoc.ts → hoc/withCache.ts}

@@ -1,117 +1,117 @@
-type CacheEntry = {
-	value: any;
-	expiresAt: number; // 时间戳（毫秒）
-};
-
-export type SetTtl = (seconds: number) => void;
-
-/**
- * 创建一个带缓存的高阶函数
- *
- * @template Args 被包装函数的参数类型数组
- * @template Result 被包装函数的返回类型
- *
- * @param fn 需要被缓存的函数，参数里附带的 setTtl 方法用于根据具体情况改写过期时间
- * @param ttlSeconds 以秒为单位的过期时间，-1 表示永不过期，默认 -1，会被回调函数里的 setTtl() 覆盖
- *
- * @returns 返回包装后的函数，以及缓存相关的额外方法
- *
- * @example
- * // 异步函数示例
- * const fetchData = withCache(async function (url: string) {
- *   const data = await fetch(url).then((res) => res.json());
- *   this.setTtl(data.expiresIn); // 根据实际情况调整过期时间
- *   return data;
- * });
- *
- * await fetchData(urlA);
- * await fetchData(urlA); // 使用缓存结果
- * await fetchData(urlB);
- * await fetchData(urlB); // 使用缓存结果
- *
- * fetchData.clear(); // 清除缓存
- * await fetchData(urlA); // 重新请求
- * await fetchData(urlB); // 重新请求
- *
- * // 缓存过期前
- * await sleep();
- * fetchData.updateTtl(180);  // 更新 ttl 并为所有未过期的缓存续期
- * await fetchData(urlA); // 使用缓存结果
- * await fetchData(urlB); // 使用缓存结果
- */
-export const withCache = <Args extends any[], Result>(
-	fn: (this: { setTtl: SetTtl }, ...args: Args) => Result,
-	ttlSeconds = -1,
-) => {
-	const cache = new Map<string, CacheEntry>();
-
-	const wrapped = (...args: Args): Result => {
-		const key = JSON.stringify(args);
-		const now = Date.now();
-		const entry = cache.get(key);
-
-		// 命中缓存且未过期
-		if (entry && now < entry.expiresAt) {
-			return entry.value;
-		}
-
-		let expiresAt = ttlSeconds === -1 ? Infinity : now + ttlSeconds * 1000;
-
-		// 创建上下文，包含 setTtl 方法
-		const thisArg = {
-			setTtl: (ttl: number) => {
-				expiresAt = now + ttl * 1000;
-			},
-		};
-
-		const result = fn.apply(thisArg, args);
-
-		// 异步函数：缓存 Promise 的 resolved 值
-		if (result instanceof Promise) {
-			const promise = result.then((resolved) => {
-				cache.set(key, {
-					value: resolved,
-					expiresAt,
-				});
-				return resolved;
-			});
-
-			// 将 promise 先塞进去避免重复请求
-			cache.set(key, {
-				value: promise,
-				expiresAt,
-			});
-
-			return promise as Result;
-		}
-
-		// 同步函数缓存
-		cache.set(key, {
-			value: result,
-			expiresAt,
-		});
-
-		return result;
-	};
-
-	/** 手动清除缓存 */
-	wrapped.clear = () => cache.clear();
-
-	/** 更新 TTL，同时刷新所有未过期缓存的时间 */
-	wrapped.updateTtl = (seconds: number) => {
-		// 更新默认 TTL
-		ttlSeconds = seconds;
-
-		// 给未过期缓存续期
-		const now = Date.now();
-		const newExpiresAt = now + seconds * 1000;
-		for (const [key, entry] of cache.entries()) {
-			if (entry.expiresAt > now) {
-				entry.expiresAt = newExpiresAt;
-				cache.set(key, entry);
-			}
-		}
-	};
-
-	return wrapped;
-};
+type CacheEntry = {
+	value: any;
+	expiresAt: number; // 时间戳（毫秒）
+};
+
+export type SetTtl = (seconds: number) => void;
+
+/**
+ * 创建一个带缓存的高阶函数
+ *
+ * @template Args 被包装函数的参数类型数组
+ * @template Result 被包装函数的返回类型
+ *
+ * @param fn 需要被缓存的函数，参数里附带的 setTtl 方法用于根据具体情况改写过期时间
+ * @param ttlSeconds 以秒为单位的过期时间，-1 表示永不过期，默认 -1，会被回调函数里的 setTtl() 覆盖
+ *
+ * @returns 返回包装后的函数，以及缓存相关的额外方法
+ *
+ * @example
+ * // 异步函数示例
+ * const fetchData = withCache(async function (url: string) {
+ *   const data = await fetch(url).then((res) => res.json());
+ *   this.setTtl(data.expiresIn); // 根据实际情况调整过期时间
+ *   return data;
+ * });
+ *
+ * await fetchData(urlA);
+ * await fetchData(urlA); // 使用缓存结果
+ * await fetchData(urlB);
+ * await fetchData(urlB); // 使用缓存结果
+ *
+ * fetchData.clear(); // 清除缓存
+ * await fetchData(urlA); // 重新请求
+ * await fetchData(urlB); // 重新请求
+ *
+ * // 缓存过期前
+ * await sleep();
+ * fetchData.updateTtl(180);  // 更新 ttl 并为所有未过期的缓存续期
+ * await fetchData(urlA); // 使用缓存结果
+ * await fetchData(urlB); // 使用缓存结果
+ */
+export const withCache = <Args extends any[], Result>(
+	fn: (this: { setTtl: SetTtl }, ...args: Args) => Result,
+	ttlSeconds = -1,
+) => {
+	const cache = new Map<string, CacheEntry>();
+
+	const wrapped = (...args: Args): Result => {
+		const key = JSON.stringify(args);
+		const now = Date.now();
+		const entry = cache.get(key);
+
+		// 命中缓存且未过期
+		if (entry && now < entry.expiresAt) {
+			return entry.value;
+		}
+
+		let expiresAt = ttlSeconds === -1 ? Infinity : now + ttlSeconds * 1000;
+
+		// 创建上下文，包含 setTtl 方法
+		const thisArg = {
+			setTtl: (ttl: number) => {
+				expiresAt = now + ttl * 1000;
+			},
+		};
+
+		const result = fn.apply(thisArg, args);
+
+		// 异步函数：缓存 Promise 的 resolved 值
+		if (result instanceof Promise) {
+			const promise = result.then((resolved) => {
+				cache.set(key, {
+					value: resolved,
+					expiresAt,
+				});
+				return resolved;
+			});
+
+			// 将 promise 先塞进去避免重复请求
+			cache.set(key, {
+				value: promise,
+				expiresAt,
+			});
+
+			return promise as Result;
+		}
+
+		// 同步函数缓存
+		cache.set(key, {
+			value: result,
+			expiresAt,
+		});
+
+		return result;
+	};
+
+	/** 手动清除缓存 */
+	wrapped.clear = () => cache.clear();
+
+	/** 更新 TTL，同时刷新所有未过期缓存的时间 */
+	wrapped.updateTtl = (seconds: number) => {
+		// 更新默认 TTL
+		ttlSeconds = seconds;
+
+		// 给未过期缓存续期
+		const now = Date.now();
+		const newExpiresAt = now + seconds * 1000;
+		for (const [key, entry] of cache.entries()) {
+			if (entry.expiresAt > now) {
+				entry.expiresAt = newExpiresAt;
+				cache.set(key, entry);
+			}
+		}
+	};
+
+	return wrapped;
+};

package/src/is/index.ts

@@ -0,0 +1,5 @@
+export { type Falsy, isFalsy } from "./isFalsy";
+export { isNil } from "./isNil";
+export { isObject } from "./isObject";
+export { isPrimitive, type Primitive } from "./isPrimitive";
+export { isTruthy } from "./isTruthy";

package/src/is/isFalsy.ts

@@ -0,0 +1,12 @@
+export type Falsy = false | 0 | -0 | 0n | "" | null | undefined;
+
+/**
+ * 检测传入的值是否为**假值**（false、0、''、null、undefined、NaN等）
+ *
+ * @example
+ * isFalsy(""); // true
+ * isFalsy(1); // false
+ */
+export const isFalsy = (value: any): value is Falsy => {
+	return !value;
+};

package/src/is/isNil.ts

@@ -0,0 +1,11 @@
+/**
+ * 检测传入的值是否为**空值**（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/is/isObject.ts

@@ -0,0 +1,10 @@
+/**
+ * 检测传入的值是否为**普通对象**
+ *
+ * @example
+ * const obj = { a: 1 };
+ * isObject(obj); // true
+ */
+export const isObject = (value: any): value is Record<string, any> => {
+	return value?.constructor === Object;
+};

package/src/is/isPrimitive.ts

@@ -0,0 +1,23 @@
+export type Primitive =
+	| number
+	| string
+	| boolean
+	| symbol
+	| bigint
+	| undefined
+	| null;
+
+/**
+ * 检测传入的值是否为**原始值**（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")
+	);
+};

package/src/is/isTruthy.ts

@@ -0,0 +1,10 @@
+/**
+ * 检测传入的值是否为**真值**
+ *
+ * @example
+ * isTruthy(1); // true
+ * isTruthy(""); // false
+ */
+export const isTruthy = (value: any): value is any => {
+	return !!value;
+};

package/src/lru-cache.ts

@@ -1,50 +1,50 @@
-/**
- * 简易 LRU 缓存
- * @example
- * const cache = new LRUCache<string, number>(2);
- * cache.set("a", 1);
- * cache.set("b", 2);
- * cache.set("c", 3);    // 缓存已满，a 被淘汰
- * cache.get("a");    // undefined
- */
-class LRUCache<K, V> {
-	private cache: Map<K, V>;
-	private maxSize: number;
-
-	constructor(maxSize = 10) {
-		this.cache = new Map();
-		this.maxSize = maxSize;
-	}
-
-	get(key: K): V | undefined {
-		const value = this.cache.get(key);
-		if (!value) {
-			return undefined;
-		}
-		// 重置缓存顺序
-		this.cache.delete(key);
-		this.cache.set(key, value);
-		return value;
-	}
-
-	set(key: K, value: V) {
-		// 刷新缓存
-		if (this.cache.has(key)) {
-			this.cache.delete(key);
-		}
-		// 删除最旧的缓存
-		else if (this.cache.size >= this.maxSize) {
-			const oldestKey = [...this.cache.keys()][0];
-			if (oldestKey) {
-				this.cache.delete(oldestKey);
-			}
-		}
-		this.cache.set(key, value);
-	}
-
-	has(key: K) {
-		return this.cache.has(key);
-	}
-}
-
-export default LRUCache;
+/**
+ * 简易 LRU 缓存
+ * @example
+ * const cache = new LRUCache<string, number>(2);
+ * cache.set("a", 1);
+ * cache.set("b", 2);
+ * cache.set("c", 3);    // 缓存已满，a 被淘汰
+ * cache.get("a");    // undefined
+ */
+class LRUCache<K, V> {
+	private cache: Map<K, V>;
+	private maxSize: number;
+
+	constructor(maxSize = 10) {
+		this.cache = new Map();
+		this.maxSize = maxSize;
+	}
+
+	get(key: K): V | undefined {
+		if (!this.cache.has(key)) {
+			return undefined;
+		}
+		const value = this.cache.get(key)!;
+		// 重置缓存顺序
+		this.cache.delete(key);
+		this.cache.set(key, value);
+		return value;
+	}
+
+	set(key: K, value: V) {
+		// 刷新缓存
+		if (this.cache.has(key)) {
+			this.cache.delete(key);
+		}
+		// 删除最旧的缓存
+		else if (this.cache.size >= this.maxSize) {
+			const oldestKey = [...this.cache.keys()][0];
+			if (oldestKey) {
+				this.cache.delete(oldestKey);
+			}
+		}
+		this.cache.set(key, value);
+	}
+
+	has(key: K) {
+		return this.cache.has(key);
+	}
+}
+
+export default LRUCache;

package/src/network/fetcher.ts

@@ -2,7 +2,7 @@ import { isNil, isObject } from "../is";
 import { mergeObjects } from "../object";
 
 // Bun 特有的 fetch 选项
-type BunFetchOptions = {
+export type BunFetchOptions = {
 	/** 代理服务器配置（仅 Bun 支持） */
 	proxy?: string;
 };

package/src/network/index.ts

@@ -1,4 +1,4 @@
-export { fetcher, type RequestInit } from "./fetcher";
+export { type BunFetchOptions, fetcher, type RequestInit } from "./fetcher";
 export { getRealURL } from "./getRealURL";
 export { type ImageCompressionOptions, imageUrlToBase64 } from "./image";
 export { to } from "./to";

package/src/number/index.ts

@@ -0,0 +1 @@
+export { randomInt } from "./randomInt";

package/src/object/index.ts

@@ -0,0 +1,3 @@
+export { type DeepMapKeys, mapKeys } from "./mapKeys";
+export { type DeepMapValues, mapValues } from "./mapValues";
+export { mergeObjects } from "./mergeObjects";

package/src/object/mapKeys.ts

@@ -0,0 +1,50 @@
+import { isObject } from "../is";
+
+// 这里的 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;
+};

package/src/object/mapValues.ts

@@ -0,0 +1,77 @@
+import { isObject } from "../is";
+
+// 这里的 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;
+};

package/src/object/mergeObjects.ts

@@ -0,0 +1,50 @@
+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;
+};

package/src/time/debounce.ts

@@ -0,0 +1,34 @@
+/**
+ * 防抖：在指定时间内只执行最后一次调用
+ * @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);
+	};
+};

package/src/time/index.ts

@@ -0,0 +1,3 @@
+export { debounce } from "./debounce";
+export { sleep } from "./sleep";
+export { throttle } from "./throttle";

package/src/time/sleep.ts

@@ -0,0 +1,11 @@
+/**
+ * 延迟一段时间再执行后续代码
+ * @param time 延迟时间，默认 150ms
+ * @example
+ * await sleep(1000); // 等待 1 秒执行后续代码
+ */
+export const sleep = async (time = 150) => {
+	return new Promise((resolve) => {
+		setTimeout(resolve, time);
+	});
+};