@nickyzj2023/utils 1.0.47 → 1.0.49

package/src/{network.ts → network/fetcher.ts}

@@ -1,5 +1,5 @@
-import { isNil, isObject } from "./is";
-import { mergeObjects } from "./object";
+import { isNil, isObject } from "../is";
+import { mergeObjects } from "../object";
 
 // Bun 特有的 fetch 选项
 type BunFetchOptions = {
@@ -121,38 +121,3 @@ export const fetcher = (baseURL = "", baseOptions: RequestInit = {}) => {
 			myFetch<T>(url, { ...options, method: "DELETE" }),
 	};
 };
-
-/**
- * Go 语言风格的异步处理方式
- * @param promise 一个能被 await 的异步函数
- * @returns 如果成功，返回 [null, 异步函数结果]，否则返回 [Error, undefined]
- *
- * @example
- * const [error, response] = await to(fetcher().get<Blog>("/blogs/hello-world"));
- */
-export const to = async <T, E = Error>(
-	promise: Promise<T>,
-): Promise<[null, T] | [E, undefined]> => {
-	try {
-		return [null, await promise];
-	} catch (e) {
-		return [e as E, undefined];
-	}
-};
-
-/** 从 url 响应头获取真实链接 */
-export const getRealURL = async (originURL: string) => {
-	const [error, response] = await to(
-		fetch(originURL, {
-			method: "HEAD", // 用 HEAD 减少数据传输
-			redirect: "manual", // 手动处理重定向
-		}),
-	);
-
-	if (error) {
-		return originURL;
-	}
-
-	const location = response.headers.get("location");
-	return location || originURL;
-};

package/src/network/getRealURL.ts

@@ -0,0 +1,18 @@
+import { to } from "./to";
+
+/** 从 url 响应头获取真实链接 */
+export const getRealURL = async (originURL: string) => {
+	const [error, response] = await to(
+		fetch(originURL, {
+			method: "HEAD", // 用 HEAD 减少数据传输
+			redirect: "manual", // 手动处理重定向
+		}),
+	);
+
+	if (error) {
+		return originURL;
+	}
+
+	const location = response.headers.get("location");
+	return location || originURL;
+};

package/src/network/image.ts

@@ -0,0 +1,202 @@
+/**
+ * 将 ArrayBuffer 转换为 base64 字符串
+ * 兼容浏览器、Bun 和 Node.js
+ */
+const arrayBufferToBase64 = (buffer: ArrayBuffer): string => {
+	const bytes = new Uint8Array(buffer);
+	let binary = "";
+	for (let i = 0; i < bytes.byteLength; i++) {
+		binary += String.fromCharCode(bytes[i]!);
+	}
+	return btoa(binary);
+};
+
+/**
+ * 尝试动态导入 sharp 模块
+ * 用于检测用户项目中是否安装了 sharp
+ */
+const tryImportSharp = async () => {
+	try {
+		// 动态导入 sharp，避免在浏览器环境中报错
+		// 使用 new Function 避免 TypeScript 编译时解析该模块（sharp 是可选依赖）
+		const dynamicImport = new Function(
+			"modulePath",
+			"return import(modulePath)",
+		);
+		const sharpModule = await dynamicImport("sharp");
+		return sharpModule.default || sharpModule;
+	} catch {
+		return null;
+	}
+};
+
+/**
+ * 使用 sharp 压缩图片
+ */
+const compressWithSharp = async (
+	sharp: any,
+	arrayBuffer: ArrayBuffer,
+	mime: string,
+	quality: number,
+): Promise<string> => {
+	const buffer = Buffer.from(arrayBuffer);
+	let sharpInstance = sharp(buffer);
+
+	// 根据 MIME 类型设置压缩选项
+	if (mime === "image/jpeg") {
+		sharpInstance = sharpInstance.jpeg({ quality: Math.round(quality * 100) });
+	} else if (mime === "image/png") {
+		// PNG 使用 compressionLevel (0-9)，将 quality (0-1) 映射到 compressionLevel
+		const compressionLevel = Math.round((1 - quality) * 9);
+		sharpInstance = sharpInstance.png({ compressionLevel });
+	}
+
+	const compressedBuffer = await sharpInstance.toBuffer();
+	return `data:${mime};base64,${compressedBuffer.toString("base64")}`;
+};
+
+/**
+ * 图片压缩选项
+ */
+export type ImageCompressionOptions = {
+	/** 压缩比率，默认 0.92 */
+	quality?: number;
+	/**
+	 * 自定义压缩函数，用于覆盖默认压缩行为
+	 * @param arrayBuffer 图片的 ArrayBuffer 数据
+	 * @param mime 图片的 MIME 类型
+	 * @param quality 压缩质量
+	 * @returns 压缩后的 base64 字符串
+	 */
+	compressor?: (
+		arrayBuffer: ArrayBuffer,
+		mime: string,
+		quality: number,
+	) => Promise<string> | string;
+	/**
+	 * 自定义 fetch 函数，用于使用自己封装的请求库读取图片
+	 * 必须返回符合 Web 标准的 Response 对象
+	 * @param url 图片地址
+	 * @returns Promise<Response>
+	 */
+	fetcher?: (url: string) => Promise<Response>;
+};
+
+/**
+ * 图片地址转 base64 数据
+ *
+ * @param imageUrl 图片地址
+ * @param options 可选配置
+ * @param options.quality 压缩比率，默认 0.92
+ * @param options.compressor 自定义压缩函数，用于覆盖默认压缩行为
+ *
+ * @example
+ * // 基本用法（浏览器自动使用 Canvas 压缩，Node.js/Bun 自动检测并使用 sharp）
+ * imageUrlToBase64("https://example.com/image.jpg");
+ *
+ * @example
+ * // 使用自定义 fetch 函数（如 axios 封装）
+ * imageUrlToBase64("https://example.com/image.jpg", {
+ *   fetcher: async (url) => {
+ *     // 使用 axios 或其他请求库，但必须返回 Response 对象
+ *     const response = await axios.get(url, { responseType: 'arraybuffer' });
+ *     return new Response(response.data, {
+ *       status: response.status,
+ *       statusText: response.statusText,
+ *       headers: response.headers
+ *     });
+ *   }
+ * });
+ *
+ * @example
+ * // 使用自定义压缩函数覆盖默认行为
+ * imageUrlToBase64("https://example.com/image.jpg", {
+ *   quality: 0.8,
+ *   compressor: async (buffer, mime, quality) => {
+ *     // 自定义压缩逻辑
+ *     return `data:${mime};base64,...`;
+ *   }
+ * });
+ */
+export const imageUrlToBase64 = async (
+	imageUrl: string,
+	options: ImageCompressionOptions = {},
+): Promise<string> => {
+	const { quality = 0.92, compressor, fetcher = fetch } = options;
+
+	if (!imageUrl.startsWith("http")) {
+		throw new Error("图片地址必须以http或https开头");
+	}
+
+	// 使用自定义 fetch 获取图片数据
+	const response = await fetcher(imageUrl);
+	if (!response.ok) {
+		throw new Error(`获取图片失败: ${response.statusText}`);
+	}
+
+	const mime = response.headers.get("Content-Type") || "image/jpeg";
+	const arrayBuffer = await response.arrayBuffer();
+
+	// 对于非 JPEG/PNG 图片，直接返回 base64，不做压缩
+	if (mime !== "image/jpeg" && mime !== "image/png") {
+		const base64 = arrayBufferToBase64(arrayBuffer);
+		return `data:${mime};base64,${base64}`;
+	}
+
+	// 如果提供了自定义压缩函数，优先使用它
+	if (compressor) {
+		return await compressor(arrayBuffer, mime, quality);
+	}
+
+	// 浏览器环境：使用 OffscreenCanvas 压缩
+	if (typeof OffscreenCanvas !== "undefined") {
+		let bitmap: ImageBitmap | null = null;
+
+		try {
+			const blob = new Blob([arrayBuffer], { type: mime });
+			bitmap = await createImageBitmap(blob);
+
+			const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+			const ctx = canvas.getContext("2d");
+			if (!ctx) {
+				throw new Error("无法获取 OffscreenCanvas context");
+			}
+
+			ctx.drawImage(bitmap, 0, 0);
+			bitmap.close();
+			bitmap = null;
+
+			// OffscreenCanvas 使用 convertToBlob 获取压缩后的图片
+			const compressedBlob = await canvas.convertToBlob({
+				type: mime,
+				quality: quality,
+			});
+
+			// 将 Blob 转换为 base64
+			const compressedArrayBuffer = await compressedBlob.arrayBuffer();
+			const base64 = arrayBufferToBase64(compressedArrayBuffer);
+			return `data:${mime};base64,${base64}`;
+		} catch {
+			// OffscreenCanvas 压缩失败，返回原始 base64
+			bitmap?.close();
+			const base64 = arrayBufferToBase64(arrayBuffer);
+			return `data:${mime};base64,${base64}`;
+		}
+	}
+
+	// Node.js/Bun 环境：尝试使用 sharp 进行压缩
+	const sharp = await tryImportSharp();
+	if (sharp) {
+		try {
+			return await compressWithSharp(sharp, arrayBuffer, mime, quality);
+		} catch {
+			// sharp 压缩失败，返回原始 base64
+			const base64 = arrayBufferToBase64(arrayBuffer);
+			return `data:${mime};base64,${base64}`;
+		}
+	}
+
+	// 没有可用的压缩方式，直接返回原始 base64
+	const base64 = arrayBufferToBase64(arrayBuffer);
+	return `data:${mime};base64,${base64}`;
+};

package/src/network/index.ts

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

package/src/network/to.ts

@@ -0,0 +1,17 @@
+/**
+ * Go 语言风格的异步处理方式
+ * @param promise 一个能被 await 的异步函数
+ * @returns 如果成功，返回 [null, 异步函数结果]，否则返回 [Error, undefined]
+ *
+ * @example
+ * const [error, response] = await to(fetcher().get<Blog>("/blogs/hello-world"));
+ */
+export const to = async <T, E = Error>(
+	promise: Promise<T>,
+): Promise<[null, T] | [E, undefined]> => {
+	try {
+		return [null, await promise];
+	} catch (e) {
+		return [e as E, undefined];
+	}
+};

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/string/case.ts

@@ -0,0 +1,71 @@
+export type SnakeToCamel<S extends string> =
+	S extends `${infer Before}_${infer After}`
+		? After extends `${infer First}${infer Rest}`
+			? `${Before}${Uppercase<First>}${SnakeToCamel<Rest>}`
+			: Before
+		: S;
+
+/**
+ * 下划线命名法转为驼峰命名法
+ *
+ * @example
+ * snakeToCamel("user_name") // "userName"
+ */
+export const snakeToCamel = <S extends string>(str: S): SnakeToCamel<S> => {
+	return str.replace(/_([a-zA-Z])/g, (match, pattern) =>
+		pattern.toUpperCase(),
+	) as SnakeToCamel<S>;
+};
+
+export type CamelToSnake<S extends string> =
+	S extends `${infer First}${infer Rest}`
+		? Rest extends Uncapitalize<Rest>
+			? `${Lowercase<First>}${CamelToSnake<Rest>}`
+			: `${Lowercase<First>}_${CamelToSnake<Rest>}`
+		: Lowercase<S>;
+
+/**
+ * 驼峰命名法转为下划线命名法
+ *
+ * @example
+ * camelToSnake("shouldComponentUpdate") // "should_component_update"
+ */
+export const camelToSnake = <S extends string>(str: S): CamelToSnake<S> => {
+	return str.replace(
+		/([A-Z])/g,
+		(match, pattern) => `_${pattern.toLowerCase()}`,
+	) as CamelToSnake<S>;
+};
+
+export type Capitalize<S extends string> = S extends `${infer P1}${infer Rest}`
+	? P1 extends Capitalize<P1>
+		? S
+		: `${Uppercase<P1>}${Rest}`
+	: S;
+
+/**
+ * 字符串首字母大写
+ *
+ * @example
+ * capitalize("hello") // "Hello"
+ */
+export const capitalize = <S extends string>(s: S): Capitalize<S> => {
+	return (s.charAt(0).toUpperCase() + s.slice(1)) as Capitalize<S>;
+};
+
+export type Decapitalize<S extends string> =
+	S extends `${infer P1}${infer Rest}`
+		? P1 extends Lowercase<P1>
+			? P1
+			: `${Lowercase<P1>}${Rest}`
+		: S;
+
+/**
+ * 字符串首字母小写
+ *
+ * @example
+ * decapitalize("Hello") // "hello"
+ */
+export const decapitalize = <S extends string>(s: S): Decapitalize<S> => {
+	return (s.charAt(0).toLowerCase() + s.slice(1)) as Decapitalize<S>;
+};

package/src/string/compact.ts

@@ -0,0 +1,56 @@
+/**
+ * 将字符串压缩为单行精简格式
+ *
+ * @example
+ * // "Hello, world."
+ * compactStr(`
+ *   Hello,
+ *        world!
+ * `, {
+ *  disableNewLineReplace: false,
+ * });
+ */
+export const compactStr = (
+	text: string = "",
+	options?: {
+		/** 最大保留长度，设为 0 或 Infinity 则不截断，默认 Infinity */
+		maxLength?: number;
+		/** 是否将换行符替换为字面量 \n，默认开启 */
+		disableNewLineReplace?: boolean;
+		/** 是否合并连续的空格/制表符为一个空格，默认开启 */
+		disableWhitespaceCollapse?: boolean;
+		/** 截断后的后缀，默认为 "..." */
+		omission?: string;
+	},
+): string => {
+	if (!text) return "";
+
+	const {
+		maxLength = Infinity,
+		disableNewLineReplace = false,
+		disableWhitespaceCollapse = false,
+		omission = "...",
+	} = options ?? {};
+
+	let result = text;
+
+	// 处理换行符
+	if (!disableNewLineReplace) {
+		result = result.replace(/\r?\n/g, "\\n");
+	} else {
+		result = result.replace(/\r?\n/g, " ");
+	}
+
+	// 合并连续空格
+	if (!disableWhitespaceCollapse) {
+		result = result.replace(/\s+/g, " ");
+	}
+	result = result.trim();
+
+	// 截断多出来的文字
+	if (maxLength > 0 && result.length > maxLength) {
+		return result.slice(0, maxLength) + omission;
+	}
+
+	return result;
+};

package/src/string/index.ts

@@ -0,0 +1,12 @@
+export {
+	type CamelToSnake,
+	type Capitalize,
+	camelToSnake,
+	capitalize,
+	type Decapitalize,
+	decapitalize,
+	type SnakeToCamel,
+	snakeToCamel,
+} from "./case";
+
+export { compactStr } from "./compact";

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);
+	});
+};