@nickyzj2023/utils 1.0.55 → 1.0.57

package/src/is/is-nil.ts

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

@@ -1,10 +0,0 @@
-/**
- * 检测传入的值是否为**普通对象**
- *
- * @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/is-primitive.ts

@@ -1,23 +0,0 @@
-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/network/fetcher.ts

@@ -1,124 +0,0 @@
-import { log } from "../dom";
-import { isNil, isObject } from "../is";
-import { mergeObjects } from "../object";
-
-// Bun 特有的 fetch 选项
-export type BunFetchOptions = {
-	/** 代理服务器配置（仅 Bun 支持） */
-	proxy?: string;
-};
-
-// 合并标准 RequestInit 和 Bun 特有的选项
-export type RequestInit = globalThis.RequestInit &
-	BunFetchOptions & {
-		params?: Record<string, any>;
-		parser?: (response: Response) => Promise<any>;
-	};
-
-/**
- * 基于 Fetch API 的请求客户端
- * @param baseURL 接口前缀
- * @param baseOptions 客户端级别的请求体，后续调用时传递相同参数会覆盖上去
- *
- * @remarks
- * 特性：
- * - 合并实例、调用时的相同请求体
- * - 在 params 里传递对象，自动转换为 queryString
- * - 在 body 里传递对象，自动 JSON.stringify
- * - 可选择使用 to() 转换请求结果为 [Error, Response]
- * - 可选择使用 withCache() 缓存请求结果
- * - 支持 proxy 选项（仅在 Bun 环境有效）
- *
- * @example
- *
- * // 用法1：直接发送请求
- * const res = await fetcher().get<Blog>("https://nickyzj.run:3030/blogs/hello-world");
- *
- * // 用法2：创建实例
- * const api = fetcher("https://nickyzj.run:3030", { headers: { Authorization: "Bearer token" } });
- * const res = await api.get<Blog>("/blogs/hello-world", { headers: {...}, params: { page: 1 } });  // 与实例相同的 headers 会覆盖上去，params 会转成 ?page=1 跟到 url 后面
- *
- * // 用法3：使用代理（仅 Bun 环境）
- * const api = fetcher("https://api.example.com", {
- *   proxy: "http://127.0.0.1:7890"
- * });
- *
- * // 安全处理请求结果
- * const [error, data] = await to(api.get<Blog>("/blogs/hello-world"));
- * if (error) {
- *   console.error(error);
- *   return;
- * }
- * console.log(data);
- *
- * // 缓存请求结果
- * const getBlogs = withCache(api.get);
- * await getBlogs("/blogs");
- * await sleep();
- * await getBlogs("/blogs");  // 不发请求，使用缓存
- */
-export const fetcher = (baseURL = "", baseOptions: RequestInit = {}) => {
-	const myFetch = async <T>(path: string, requestOptions: RequestInit = {}) => {
-		// 构建完整 URL
-		const url = new URL(baseURL ? `${baseURL}${path}` : path);
-
-		// 合并 options
-		const { params, parser, ...options } = mergeObjects(
-			baseOptions,
-			requestOptions,
-		);
-
-		// 转换 params 为查询字符串
-		if (isObject(params)) {
-			Object.entries(params).forEach(([key, value]) => {
-				if (isNil(value)) {
-					return;
-				}
-				url.searchParams.append(key, value.toString());
-			});
-		}
-
-		// 转换 body 为字符串
-		if (isObject(options.body) || Array.isArray(options.body)) {
-			options.body = JSON.stringify(options.body);
-			options.headers = {
-				...options.headers,
-				"Content-Type": "application/json",
-			};
-		}
-
-		// 发送请求
-		const response = await fetch(url, options);
-		if (!response.ok) {
-			// 如果后端给了报错详情，则先解析再抛出
-			const contentType = response.headers.get("Content-Type");
-			if (contentType?.startsWith("application/json")) {
-				throw await response.json();
-			}
-			throw new Error(response.statusText);
-		}
-
-		const data = await (parser?.(response) ?? response.json());
-		return data as T;
-	};
-
-	return {
-		get: <T>(url: string, options?: Omit<RequestInit, "method">) =>
-			myFetch<T>(url, { ...options, method: "GET" }),
-
-		post: <T>(
-			url: string,
-			body: any,
-			options?: Omit<RequestInit, "method" | "body">,
-		) => myFetch<T>(url, { ...options, method: "POST", body }),
-
-		put: <T>(
-			url: string,
-			body: any,
-			options?: Omit<RequestInit, "method" | "body">,
-		) => myFetch<T>(url, { ...options, method: "PUT", body }),
-
-		delete: <T>(url: string, options?: Omit<RequestInit, "method" | "body">) =>
-			myFetch<T>(url, { ...options, method: "DELETE" }),
-	};
-};

package/src/network/get-real-url.ts

@@ -1,18 +0,0 @@
-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

@@ -1,202 +0,0 @@
-/**
- * 将 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

@@ -1,4 +0,0 @@
-export * from "./fetcher";
-export * from "./get-real-url";
-export * from "./image";
-export * from "./to";

package/src/network/to.ts

@@ -1,17 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-export * from "./random-int";

package/src/number/random-int.ts

@@ -1,9 +0,0 @@
-/**
- * 在指定闭区间内生成随机整数
- *
- * @example
- * randomInt(1, 10);    // 1 <= x <= 10
- */
-export const randomInt = (min: number, max: number) => {
-	return Math.floor(Math.random() * (max - min + 1)) + min;
-};

package/src/object/index.ts

@@ -1,3 +0,0 @@
-export * from "./map-keys";
-export * from "./map-values";
-export * from "./merge-objects";

package/src/object/map-keys.ts

@@ -1,50 +0,0 @@
-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/map-values.ts

@@ -1,77 +0,0 @@
-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/merge-objects.ts

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

package/src/string/case.ts

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