@nickyzj2023/utils 1.0.48 → 1.0.50

package/AGENTS.md

@@ -4,17 +4,16 @@ This file contains essential information for AI coding agents working on this pr
 
 ## Project Overview
 
-这是一个前端工具库（Frontend Utility Library），提供常用的 TypeScript/JavaScript 工具函数，帮助开发者简化日常开发任务。项目使用 Bun 作为运行时和构建工具，发布到 npm 仓库 `@nickyzj2023/utils`。
+这是一个前端工具库（Frontend Utility Library），提供常用的 TypeScript/JavaScript 工具函数，帮助开发者简化日常开发任务。项目使用 Bun 作为运行时和包管理器，发布到 npm 仓库 `@nickyzj2023/utils`。
 
 ## Technology Stack
 
 - **Runtime**: [Bun](https://bun.com) v1.3.2+ - 快速的 JavaScript 运行时和包管理器
 - **Language**: TypeScript 5.9.3+
-- **Build Tool**: Bun 内置打包器
+- **Build Tool**: Bun 内置打包器 + TypeScript 编译器
 - **Linting/Formatting**: Biome 2.3.14
 - **Documentation**: TypeDoc 0.28.16 + Material Theme
-- **Dependencies**:
-  - `sharp` (^0.34.5) - 图片处理库，用于 `imageUrlToBase64` 功能
+- **Dependencies**: 零运行时依赖，仅开发依赖
 
 ## Project Structure
 
@@ -22,21 +21,52 @@ This file contains essential information for AI coding agents working on this pr
 .
 ├── src/                    # 源代码目录
 │   ├── index.ts           # 入口文件，导出所有模块
-│   ├── dom.ts             # DOM 相关工具（timeLog）
-│   ├── function.ts        # 函数控制工具（loopUntil）
-│   ├── hoc.ts             # 高阶函数（withCache）
-│   ├── is.ts              # 类型判断工具（isObject, isPrimitive, isFalsy, isTruthy, isNil）
-│   ├── lru-cache.ts       # LRU 缓存实现
-│   ├── network.ts         # 网络请求工具（fetcher, to, getRealURL）
-│   ├── number.ts          # 数字工具（randomInt）
-│   ├── object.ts          # 对象操作工具（mergeObjects, mapKeys, mapValues）
-│   ├── string.ts          # 字符串工具（snakeToCamel, camelToSnake, capitalize, decapitalize, imageUrlToBase64, compactStr）
-│   └── time.ts            # 时间控制工具（sleep, debounce, throttle）
+│   ├── dom/               # DOM 相关工具
+│   │   ├── index.ts       # 模块导出
+│   │   └── timeLog.ts     # 带时间的 console.log
+│   ├── function/          # 函数控制工具
+│   │   ├── index.ts       # 模块导出
+│   │   └── loopUntil.ts   # 循环执行直到满足条件
+│   ├── hoc/               # 高阶函数
+│   │   ├── index.ts       # 模块导出
+│   │   └── withCache.ts   # 带缓存的高阶函数
+│   ├── is/                # 类型判断工具
+│   │   ├── index.ts       # 模块导出
+│   │   ├── isFalsy.ts     # 假值判断
+│   │   ├── isNil.ts       # 空值判断
+│   │   ├── isObject.ts    # 普通对象判断
+│   │   ├── isPrimitive.ts # 原始值判断
+│   │   └── isTruthy.ts    # 真值判断
+│   ├── network/           # 网络请求工具
+│   │   ├── index.ts       # 模块导出
+│   │   ├── fetcher.ts     # 基于 Fetch API 的请求客户端
+│   │   ├── getRealURL.ts  # 从响应头获取真实链接
+│   │   ├── image.ts       # 图片 URL 转 Base64
+│   │   └── to.ts          # Go 语言风格的异步处理
+│   ├── number/            # 数字工具
+│   │   ├── index.ts       # 模块导出
+│   │   └── randomInt.ts   # 生成随机整数
+│   ├── object/            # 对象操作工具
+│   │   ├── index.ts       # 模块导出
+│   │   ├── mapKeys.ts     # 递归处理对象 key
+│   │   ├── mapValues.ts   # 递归处理对象 value
+│   │   └── mergeObjects.ts # 深度合并对象
+│   ├── string/            # 字符串处理工具
+│   │   ├── index.ts       # 模块导出
+│   │   ├── case.ts        # 命名法转换（snake/camel/capitalize）
+│   │   └── compact.ts     # 字符串压缩为单行
+│   ├── time/              # 时间控制工具
+│   │   ├── index.ts       # 模块导出
+│   │   ├── debounce.ts    # 防抖函数
+│   │   ├── sleep.ts       # 延迟执行
+│   │   └── throttle.ts    # 节流函数
+│   └── lru-cache.ts       # LRU 缓存实现（默认导出）
 ├── dist/                  # 构建输出目录（包含 .js 和 .d.ts 文件）
 ├── docs/                  # TypeDoc 生成的文档网站
 ├── package.json           # 包配置
 ├── tsconfig.json          # TypeScript 配置
 ├── biome.json             # Biome 代码规范配置
+├── bun.lock               # Bun 锁定文件
 └── .gitignore             # Git 忽略规则
 ```
 
@@ -51,7 +81,7 @@ bun run docs
 ```
 
 构建流程：
-1. `bun build --target=bun --outdir ./dist --minify ./src/index.ts` - 使用 Bun 打包并压缩
+1. `bun build --target=bun --outdir ./dist --minify ./src/index.ts --packages external` - 使用 Bun 打包并压缩
 2. `tsc` - 生成 TypeScript 类型声明文件（.d.ts）
 3. `typedoc src/index.ts --plugin typedoc-material-theme` - 生成 API 文档
 
@@ -82,19 +112,24 @@ bun run docs
 
 ## Module Organization
 
-项目按功能领域划分模块：
+项目按功能领域划分模块，每个模块是一个子目录：
 
 | 模块 | 功能描述 | 主要导出 |
 |------|---------|---------|
 | `is` | 类型判断 | `isObject`, `isPrimitive`, `isFalsy`, `isTruthy`, `isNil`, `Primitive`, `Falsy` |
-| `network` | 网络请求 | `fetcher`, `to`, `getRealURL`, `RequestInit` |
+| `network` | 网络请求 | `fetcher`, `to`, `getRealURL`, `imageUrlToBase64`, `RequestInit`, `ImageCompressionOptions` |
 | `object` | 对象操作 | `mergeObjects`, `mapKeys`, `mapValues`, `DeepMapKeys`, `DeepMapValues` |
-| `string` | 字符串处理 | `snakeToCamel`, `camelToSnake`, `capitalize`, `decapitalize`, `imageUrlToBase64`, `compactStr` |
+| `string` | 字符串处理 | `snakeToCamel`, `camelToSnake`, `capitalize`, `decapitalize`, `compactStr` |
 | `time` | 时间控制 | `sleep`, `debounce`, `throttle` |
 | `function` | 函数控制 | `loopUntil` |
 | `hoc` | 高阶函数 | `withCache`, `SetTtl` |
 | `lru-cache` | 缓存实现 | `LRUCache`（默认导出） |
 | `dom` | DOM 工具 | `timeLog` |
+| `number` | 数字工具 | `randomInt` |
+
+每个模块目录结构：
+- `index.ts` - 集中导出该模块的所有功能
+- 具体实现文件（如 `sleep.ts`, `debounce.ts` 等）
 
 ## Testing
 
@@ -112,8 +147,8 @@ bun run docs
 ## Security Considerations
 
 1. **敏感信息**: `.npmrc` 文件包含 npm 认证令牌，已在 `.gitignore` 中配置忽略
-2. **依赖安全**: `sharp` 是原生依赖，需要确保其安全性
-3. **网络请求**: `fetcher` 函数会解析 JSON 错误响应，注意潜在的安全风险
+2. **网络请求**: `fetcher` 函数会解析 JSON 错误响应，注意潜在的安全风险
+3. **动态导入**: `imageUrlToBase64` 使用动态导入尝试加载 `sharp`，避免在浏览器环境报错
 
 ## Development Workflow
 
@@ -127,5 +162,6 @@ bun run docs
 
 - 项目使用 ES Module（`"type": "module"`），不支持 CommonJS
 - 构建目标为 Bun 运行时（`--target=bun`）
-- `imageUrlToBase64` 功能依赖 `sharp` 库，需要 Node.js/Bun 原生环境支持
-- `fetcher` 函数基于 Fetch API，在 Bun 环境下使用 `BunFetchRequestInit` 类型
+- `imageUrlToBase64` 功能在浏览器环境使用 OffscreenCanvas 压缩，在 Node.js/Bun 环境尝试使用 sharp（可选依赖）
+- `fetcher` 函数基于 Fetch API，在 Bun 环境下支持 `proxy` 选项
+- 所有工具函数均为纯函数，无副作用

package/dist/dom/index.d.ts

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

package/dist/dom/timeLog.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 附带时间的 console.log
+ * @param args
+ *
+ * @example
+ * timeLog("Hello", "World"); // 14:30:00 Hello World
+ */
+export declare const timeLog: (...args: any[]) => void;

package/dist/function/index.d.ts

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

package/dist/function/loopUntil.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 循环执行函数，直到符合停止条件
+ *
+ * @example
+ * // 循环请求大语言模型，直到其不再调用工具
+ * loopUntil(
+ *   async () => {
+ *     const completion = await chatCompletions();
+ *     completion.tool_calls?.forEach(chooseAndHandleTool)
+ *     return completion;
+ *   },
+ *   {
+ *     shouldStop: (completion) => !completion.tool_calls,
+ *   },
+ * ),
+ */
+export declare const loopUntil: <T>(fn: (count: number) => Promise<T>, options?: {
+    /** 最大循环次数，默认 5 次 */
+    maxRetries?: number;
+    /** 停止循环条件，默认立即停止 */
+    shouldStop?: (result: T) => boolean;
+}) => Promise<T>;

package/dist/hoc/index.d.ts

@@ -0,0 +1 @@
+export { type SetTtl, withCache } from "./withCache";

package/dist/hoc/withCache.d.ts

@@ -0,0 +1,42 @@
+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 declare const withCache: <Args extends any[], Result>(fn: (this: {
+    setTtl: SetTtl;
+}, ...args: Args) => Result, ttlSeconds?: number) => {
+    (...args: Args): Result;
+    clear(): void;
+    updateTtl(seconds: number): void;
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./dom";
+export * from "./function";
+export * from "./hoc";
+export * from "./is";
+export * from "./network";
+export * from "./number";
+export * from "./object";
+export * from "./string";
+export * from "./time";

package/dist/index.js

@@ -0,0 +1,2 @@
+// @bun
+var m=(...x)=>{console.log(`${new Date().toLocaleTimeString()}`,...x)};var O=async(x,z)=>{let{maxRetries:T=5,shouldStop:E=()=>!0}=z??{};for(let P=0;P<T;P++){let C=await x(P);if(E(C))return C}throw Error(`\u8D85\u8FC7\u4E86\u6700\u5927\u5FAA\u73AF\u6B21\u6570\uFF08${T}\uFF09\u4E14\u672A\u6EE1\u8DB3\u505C\u6B62\u6267\u884C\u6761\u4EF6`)};var R=(x,z=-1)=>{let T=new Map,E=(...P)=>{let C=JSON.stringify(P),D=Date.now(),G=T.get(C);if(G&&D<G.expiresAt)return G.value;let M=z===-1?1/0:D+z*1000,J={setTtl:(H)=>{M=D+H*1000}},Y=x.apply(J,P);if(Y instanceof Promise){let H=Y.then((Q)=>{return T.set(C,{value:Q,expiresAt:M}),Q});return T.set(C,{value:H,expiresAt:M}),H}return T.set(C,{value:Y,expiresAt:M}),Y};return E.clear=()=>T.clear(),E.updateTtl=(P)=>{z=P;let C=Date.now(),D=C+P*1000;for(let[G,M]of T.entries())if(M.expiresAt>C)M.expiresAt=D,T.set(G,M)},E};var q=(x)=>{return!x};var _=(x)=>{return x===null||x===void 0};var $=(x)=>{return x?.constructor===Object};var X=(x)=>{return x===null||x===void 0||typeof x!=="object"&&typeof x!=="function"};var K=(x)=>{return!!x};var d=(x,z)=>{if(Array.isArray(x))return x.map((T)=>d(T,z));if($(x))return Object.keys(x).reduce((E,P)=>{let C=z(P),D=x[P];return E[C]=d(D,z),E},{});return x};var o=(x,z,T)=>{let{filter:E}=T??{};if(Array.isArray(x)){let P=x.map((C,D)=>{if($(C))return o(C,z,T);return z(C,D)});if(E)return P.filter((C,D)=>E(C,D));return P}if($(x))return Object.keys(x).reduce((C,D)=>{let G=x[D],M;if($(G)||Array.isArray(G))M=o(G,z,T);else M=z(G,D);if(!E||E(M,D))C[D]=M;return C},{});return x};var Z=(x,z)=>{let T={...x};for(let E of Object.keys(z)){let P=T[E],C=z[E];if(X(P)&&X(C)){T[E]=C;continue}if(Array.isArray(P)&&Array.isArray(C)){T[E]=P.concat(C);continue}if($(P)&&$(C)){T[E]=Z(P,C);continue}T[E]=C}return T};var c=(x="",z={})=>{let T=async(E,P={})=>{let C=new URL(x?`${x}${E}`:E),{params:D,parser:G,...M}=Z(z,P);if($(D))Object.entries(D).forEach(([H,Q])=>{if(_(Q))return;C.searchParams.append(H,Q.toString())});if($(M.body))M.body=JSON.stringify(M.body),M.headers={...M.headers,"Content-Type":"application/json"};let J=await fetch(C,M);if(!J.ok){if(J.headers.get("Content-Type")?.startsWith("application/json"))throw await J.json();throw Error(J.statusText)}return await(G?.(J)??J.json())};return{get:(E,P)=>T(E,{...P,method:"GET"}),post:(E,P,C)=>T(E,{...C,method:"POST",body:P}),put:(E,P,C)=>T(E,{...C,method:"PUT",body:P}),delete:(E,P)=>T(E,{...P,method:"DELETE"})}};var I=async(x)=>{try{return[null,await x]}catch(z){return[z,void 0]}};var A=async(x)=>{let[z,T]=await I(fetch(x,{method:"HEAD",redirect:"manual"}));if(z)return x;return T.headers.get("location")||x};var W=(x)=>{let z=new Uint8Array(x),T="";for(let E=0;E<z.byteLength;E++)T+=String.fromCharCode(z[E]);return btoa(T)},L=async()=>{try{let z=await Function("modulePath","return import(modulePath)")("sharp");return z.default||z}catch{return null}},n=async(x,z,T,E)=>{let P=Buffer.from(z),C=x(P);if(T==="image/jpeg")C=C.jpeg({quality:Math.round(E*100)});else if(T==="image/png"){let G=Math.round((1-E)*9);C=C.png({compressionLevel:G})}let D=await C.toBuffer();return`data:${T};base64,${D.toString("base64")}`},U=async(x,z={})=>{let{quality:T=0.92,compressor:E,fetcher:P=fetch}=z;if(!x.startsWith("http"))throw Error("\u56FE\u7247\u5730\u5740\u5FC5\u987B\u4EE5http\u6216https\u5F00\u5934");let C=await P(x);if(!C.ok)throw Error(`\u83B7\u53D6\u56FE\u7247\u5931\u8D25: ${C.statusText}`);let D=C.headers.get("Content-Type")||"image/jpeg",G=await C.arrayBuffer();if(D!=="image/jpeg"&&D!=="image/png"){let Y=W(G);return`data:${D};base64,${Y}`}if(E)return await E(G,D,T);if(typeof OffscreenCanvas<"u"){let Y=null;try{let H=new Blob([G],{type:D});Y=await createImageBitmap(H);let Q=new OffscreenCanvas(Y.width,Y.height),S=Q.getContext("2d");if(!S)throw Error("\u65E0\u6CD5\u83B7\u53D6 OffscreenCanvas context");S.drawImage(Y,0,0),Y.close(),Y=null;let f=await(await Q.convertToBlob({type:D,quality:T})).arrayBuffer(),F=W(f);return`data:${D};base64,${F}`}catch{Y?.close();let H=W(G);return`data:${D};base64,${H}`}}let M=await L();if(M)try{return await n(M,G,D,T)}catch{let Y=W(G);return`data:${D};base64,${Y}`}let J=W(G);return`data:${D};base64,${J}`};var V=(x,z)=>{return Math.floor(Math.random()*(z-x+1))+x};var h=(x)=>{return x.replace(/_([a-zA-Z])/g,(z,T)=>T.toUpperCase())},N=(x)=>{return x.replace(/([A-Z])/g,(z,T)=>`_${T.toLowerCase()}`)},w=(x)=>{return x.charAt(0).toUpperCase()+x.slice(1)},g=(x)=>{return x.charAt(0).toLowerCase()+x.slice(1)};var B=(x="",z)=>{if(!x)return"";let{maxLength:T=1/0,disableNewLineReplace:E=!1,disableWhitespaceCollapse:P=!1,omission:C="..."}=z??{},D=x;if(!E)D=D.replace(/\r?\n/g,"\\n");else D=D.replace(/\r?\n/g," ");if(!P)D=D.replace(/\s+/g," ");if(D=D.trim(),T>0&&D.length>T)return D.slice(0,T)+C;return D};var p=(x,z=300)=>{let T=null;return(...E)=>{if(T)clearTimeout(T);T=setTimeout(()=>{x(...E)},z)}};var k=async(x=150)=>{return new Promise((z)=>{setTimeout(z,x)})};var r=(x,z=300)=>{let T=null;return function(...E){if(!T)T=setTimeout(()=>{T=null,x.apply(this,E)},z)}};export{R as withCache,I as to,m as timeLog,r as throttle,h as snakeToCamel,k as sleep,V as randomInt,Z as mergeObjects,o as mapValues,d as mapKeys,O as loopUntil,K as isTruthy,X as isPrimitive,$ as isObject,_ as isNil,q as isFalsy,U as imageUrlToBase64,A as getRealURL,c as fetcher,g as decapitalize,p as debounce,B as compactStr,w as capitalize,N as camelToSnake};

package/dist/is/index.d.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/dist/is/isFalsy.d.ts

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

package/dist/is/isNil.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 检测传入的值是否为**空值**（null、undefined）
+ *
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(1); // false
+ */
+export declare const isNil: (value: any) => value is null | undefined;

package/dist/is/isObject.d.ts

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

package/dist/is/isPrimitive.d.ts

@@ -0,0 +1,9 @@
+export type Primitive = number | string | boolean | symbol | bigint | undefined | null;
+/**
+ * 检测传入的值是否为**原始值**（number、string、boolean、symbol、bigint、undefined、null）
+ *
+ * @example
+ * isPrimitive(1);  // true
+ * isPrimitive([]); // false
+ */
+export declare const isPrimitive: (value: any) => value is Primitive;

package/dist/is/isTruthy.d.ts

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

package/dist/lru-cache.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 简易 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
+ */
+declare class LRUCache<K, V> {
+    private cache;
+    private maxSize;
+    constructor(maxSize?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+}
+export default LRUCache;

package/dist/network/fetcher.d.ts

@@ -0,0 +1,56 @@
+export type BunFetchOptions = {
+    /** 代理服务器配置（仅 Bun 支持） */
+    proxy?: string;
+};
+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 declare const fetcher: (baseURL?: string, baseOptions?: RequestInit) => {
+    get: <T>(url: string, options?: Omit<RequestInit, "method">) => Promise<T>;
+    post: <T>(url: string, body: any, options?: Omit<RequestInit, "method" | "body">) => Promise<T>;
+    put: <T>(url: string, body: any, options?: Omit<RequestInit, "method" | "body">) => Promise<T>;
+    delete: <T>(url: string, options?: Omit<RequestInit, "method" | "body">) => Promise<T>;
+};

package/dist/network/getRealURL.d.ts

@@ -0,0 +1,2 @@
+/** 从 url 响应头获取真实链接 */
+export declare const getRealURL: (originURL: string) => Promise<string>;

package/dist/network/image.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 图片压缩选项
+ */
+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 declare const imageUrlToBase64: (imageUrl: string, options?: ImageCompressionOptions) => Promise<string>;

package/dist/network/index.d.ts

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

package/dist/network/to.d.ts

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

package/dist/number/index.d.ts

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

package/dist/number/randomInt.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 在指定闭区间内生成随机整数
+ *
+ * @example
+ * randomInt(1, 10);    // 1 <= x <= 10
+ */
+export declare const randomInt: (min: number, max: number) => number;

package/dist/object/index.d.ts

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

package/dist/object/mapKeys.d.ts

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

package/dist/object/mapValues.d.ts

@@ -0,0 +1,21 @@
+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/object/mergeObjects.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 深度合并两个对象，规则如下：
+ * 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;

package/dist/string/case.d.ts

@@ -0,0 +1,32 @@
+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 declare const snakeToCamel: <S extends string>(str: S) => 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 declare const camelToSnake: <S extends string>(str: S) => 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 declare const capitalize: <S extends string>(s: S) => 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 declare const decapitalize: <S extends string>(s: S) => Decapitalize<S>;

package/dist/string/compact.d.ts

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

package/dist/string/index.d.ts

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

package/dist/time/debounce.d.ts

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

package/dist/time/index.d.ts

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

package/dist/time/sleep.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 延迟一段时间再执行后续代码
+ * @param time 延迟时间，默认 150ms
+ * @example
+ * await sleep(1000); // 等待 1 秒执行后续代码
+ */
+export declare const sleep: (time?: number) => Promise<unknown>;