@aiao/utils 0.0.5 → 0.0.7

package/dist/indexing/fractional-indexing.d.ts

@@ -1,22 +1,61 @@
 /**
- * 因为原来库编译有问题，拷贝 https://github.com/rocicorp/fractional-indexing 并且 js 转成 ts
+ * 分数索引（Fractional Indexing）实现
+ * 基于 https://github.com/rocicorp/fractional-indexing
+ *
+ * 分数索引是一种用于生成排序键的技术，可以在任意两个已存在的键之间插入新的键
+ * 常用于实现列表项的任意位置插入排序，如协同编辑中的项目排序
+ *
+ * @example
+ * // 基础用法
+ * const key1 = generateKeyBetween(null, null); // 'a0'
+ * const key2 = generateKeyBetween(key1, null); // 'a1'
+ * const key3 = generateKeyBetween(key1, key2); // 'a0V'
+ *
+ * @example
+ * // 在列表中插入项目
+ * const items = ['a0', 'a2'];
+ * const newKey = generateKeyBetween('a0', 'a2'); // 'a1'
+ * // 现在可以插入到 'a0' 和 'a2' 之间
  */
 export declare const BASE_62_DIGITS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+type OrderKey = string | null | undefined;
 /**
  * 在两个排序键之间生成一个新的排序键
- * @param a 起始键（null表示开始）
- * @param b 结束键（null表示结尾）
- * @param digits 数字字符集，默认为BASE_62
+ * 用于在有序列表中插入新项目，支持任意位置插入
+ *
+ * @param a - 起始键（null表示列表开始）
+ * @param b - 结束键（null表示列表结尾）
+ * @param digits - 数字字符集，默认为BASE_62_DIGITS
  * @returns 新生成的排序键
+ * @throws 当参数无效或无法生成键时抛出错误
+ * @example
+ * // 在列表开始插入
+ * const firstKey = generateKeyBetween(null, 'a1'); // 'a0V'
+ *
+ * @example
+ * // 在列表结尾插入
+ * const lastKey = generateKeyBetween('a1', null); // 'a2'
+ *
+ * @example
+ * // 在两个键之间插入
+ * const middleKey = generateKeyBetween('a1', 'a2'); // 'a1V'
  */
-export declare function generateKeyBetween(a: string | null | undefined, b: string | null | undefined, digits?: string): string;
+export declare function generateKeyBetween(a: OrderKey, b: OrderKey, digits?: string): string;
 /**
  * 在两个排序键之间生成n个排序键
- * @param a 起始键
- * @param b 结束键
- * @param n 生成键的数量
- * @param digits 数字字符集
- * @returns 生成的排序键数组
+ * 用于批量插入多个项目到有序列表中
+ *
+ * @param a - 起始键（null表示列表开始）
+ * @param b - 结束键（null表示列表结尾）
+ * @param n - 要生成的键的数量
+ * @param digits - 数字字符集，默认为BASE_62_DIGITS
+ * @returns 生成的排序键数组，按顺序排列
+ * @throws 当参数无效时抛出错误
+ * @example
+ * // 生成3个键插入到两个现有键之间
+ * const keys = generateKeysBetween('a1', 'a2', 3);
+ * // 返回: ['a1V', 'a1l', 'a1v']
  */
-export declare function generateKeysBetween(a: string | null | undefined, b: string | null | undefined, n: number, digits?: string): string[];
+export declare function generateKeysBetween(a: OrderKey, b: OrderKey, n: number, digits?: string): string[];
+export {};
 //# sourceMappingURL=fractional-indexing.d.ts.map

package/dist/indexing/fractional-indexing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fractional-indexing.d.ts","sourceRoot":"","sources":["../../src/indexing/fractional-indexing.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,cAAc,mEAAmE,CAAC;AAyL/F;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC5B,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC5B,MAAM,SAAiB,GACtB,MAAM,CAoDR;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC5B,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC5B,CAAC,EAAE,MAAM,EACT,MAAM,SAAiB,GACtB,MAAM,EAAE,CA6BV"}
+{"version":3,"file":"fractional-indexing.d.ts","sourceRoot":"","sources":["../../src/indexing/fractional-indexing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,cAAc,mEAAmE,CAAC;AAE/F,KAAK,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AA0M1C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,SAAiB,GAAG,MAAM,CA0D5F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,SAAiB,GAAG,MAAM,EAAE,CAkC1G"}

package/dist/number/canBeNumber.d.ts

@@ -25,8 +25,8 @@
  * canBeNumber(Infinity);   // 返回 false（无穷大不能转换为有限数字）
  * @example
  * canBeNumber(-Infinity);  // 返回 false（负无穷大不能转换为有限数字）
- * @note 与isNumber()不同，该函数检查的是值是否可以被转换为数字，而非值本身是否是数字类型
- * @note 对于BigInt类型值（如123n），会返回false，因为parseFloat无法处理BigInt
+ * **Note:** 与isNumber()不同，该函数检查的是值是否可以被转换为数字，而非值本身是否是数字类型
+ * **Note:** 对于BigInt类型值（如123n），会返回false，因为parseFloat无法处理BigInt
  */
 export declare const canBeNumber: (value: number | string) => boolean;
 //# sourceMappingURL=canBeNumber.d.ts.map

package/dist/number/numberStep.d.ts

@@ -13,8 +13,8 @@
  * numberStep(3.2, 2); // 返回 4（2的2倍）
  * @example
  * numberStep(0.5, 1); // 返回 1（1的1倍）
- * @note 实现原理：value除以step后向上取整，再乘以step
- * @warning step必须为正数，否则可能导致非预期结果或除以零错误
+ * **Note:** 实现原理：value除以step后向上取整，再乘以step
+ * **Warning:** step必须为正数，否则可能导致非预期结果或除以零错误
  */
 export declare const numberStep: (value: number, step: number) => number;
 //# sourceMappingURL=numberStep.d.ts.map

package/dist/number/numberStepScreenSize.d.ts

@@ -1,2 +1,15 @@
+/**
+ * 根据设备像素比调整数值后，按步长取整
+ * 主要用于处理不同DPI屏幕下的尺寸计算，确保在高分辨率屏幕上保持合适的步长
+ * @param value - 原始数值
+ * @param step - 步长间隔，默认80
+ * @param devicePixelRatio - 设备像素比，默认1，用于高DPI屏幕调整
+ * @returns 调整后的数值
+ * @example
+ * numberStepScreenSize(100, 50, 2); // 返回 200（100*2=200，向上取整到50的倍数）
+ * numberStepScreenSize(75, 50, 1);  // 返回 100（75向上取整到50的倍数）
+ * **Note:** 先将value乘以devicePixelRatio，再应用numberStep逻辑
+ * **Note:** 适用于响应式设计中的尺寸计算
+ */
 export declare const numberStepScreenSize: (value: number, step?: number, devicePixelRatio?: number) => number;
 //# sourceMappingURL=numberStepScreenSize.d.ts.map

package/dist/number/numberStepScreenSize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"numberStepScreenSize.d.ts","sourceRoot":"","sources":["../../src/number/numberStepScreenSize.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,EAAE,aAAS,EAAE,yBAAoB,WACvC,CAAC"}
+{"version":3,"file":"numberStepScreenSize.d.ts","sourceRoot":"","sources":["../../src/number/numberStepScreenSize.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,EAAE,aAAS,EAAE,yBAAoB,WACvC,CAAC"}

package/dist/number/numberStrip.d.ts

@@ -14,9 +14,9 @@
  * numberStrip(12345.6789, 6);   // 返回 12345.7（6位有效数字）
  * @example
  * numberStrip(0.0000012345);     // 返回 0.0000012345
- * @note 有效数字位数(precision)控制整体数字精度，而非仅小数部分
- * @note 默认精度12位适用于大多数场景，可根据需要调整，但不应超过21位
- * @note 内部使用Number.toPrecision()实现，然后通过parseFloat()转换回数字
+ * **Note:** 有效数字位数(precision)控制整体数字精度，而非仅小数部分
+ * **Note:** 默认精度12位适用于大多数场景，可根据需要调整，但不应超过21位
+ * **Note:** 内部使用Number.toPrecision()实现，然后通过parseFloat()转换回数字
  */
 export declare const numberStrip: (value: number, precision?: number) => number;
 //# sourceMappingURL=numberStrip.d.ts.map

package/dist/number/toInt.d.ts

@@ -1,17 +1,23 @@
 /**
- * 将值转换为整数
- * @param value - 要转换的值
- * @returns 转换后的整数，如果无法转换则返回NaN
+ * 将值转换为整数，使用向下取整（正数）和向上取整（负数）的策略
+ * @param value - 要转换的值，可以是数字或字符串
+ * @returns 转换后的整数，转换失败返回 NaN
  * @example
  * toInt('123'); // 返回 123
  * @example
- * toInt(123.45); // 返回 123
+ * toInt(123.45); // 返回 123（向下取整）
  * @example
- * toInt('-123.45'); // 返回 -123
+ * toInt('-123.45'); // 返回 -123（向上取整，-123.45 -> -123）
  * @example
- * toInt('abc'); // 返回 NaN
+ * toInt('123.9'); // 返回 123（向下取整）
+ * @example
+ * toInt('-123.1'); // 返回 -123（向上取整）
+ * @example
+ * toInt('abc'); // 返回 NaN（无法转换为数字）
  * @example
  * toInt(null); // 返回 NaN
+ * **Note:** 对于正数使用 Math.floor()，对于负数使用 Math.ceil()
+ * **Note:** 这与 parseInt() 的行为不同，后者总是向零取整
  */
 export declare const toInt: (value: number | string) => number;
 //# sourceMappingURL=toInt.d.ts.map

package/dist/number/toInt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toInt.d.ts","sourceRoot":"","sources":["../../src/number/toInt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,GAAG,MAAM,KAAG,MAK9C,CAAC"}
+{"version":3,"file":"toInt.d.ts","sourceRoot":"","sources":["../../src/number/toInt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,GAAG,MAAM,KAAG,MAK9C,CAAC"}

package/dist/number/tryToNumber.d.ts

@@ -1,16 +1,25 @@
 /**
- * 尝试将值转换为数字
- * 如果值可以转换为有效数字则返回数字，否则返回原值
- * @param value - 要转换的值
- * @returns 转换后的数字或原值
+ * 安全地将值转换为数字，只在能转换为有效数字时才转换
+ * 如果无法转换为有效数字（NaN、无穷大等），则返回原值不变
+ * @param value - 要尝试转换的值
+ * @returns 转换后的数字（如果成功）或原值（如果失败）
  * @example
- * tryToNumber('123'); // 返回 123
+ * tryToNumber('123'); // 返回 123（字符串数字转换为数字）
  * @example
- * tryToNumber('abc'); // 返回 'abc'
+ * tryToNumber('123.45'); // 返回 123.45（浮点数字符串）
  * @example
- * tryToNumber(true); // 返回 true
+ * tryToNumber('abc'); // 返回 'abc'（无法转换为数字，返回原值）
  * @example
- * tryToNumber(null); // 返回 null
+ * tryToNumber(true); // 返回 true（布尔值不转换）
+ * @example
+ * tryToNumber(null); // 返回 null（null不转换）
+ * @example
+ * tryToNumber(''); // 返回 ''（空字符串不转换）
+ * @example
+ * tryToNumber('Infinity'); // 返回 'Infinity'（无穷大字符串不转换）
+ * **Note:** 使用 canBeNumber 检查是否可以转换为数字
+ * **Note:** 即使通过了 canBeNumber 检查，仍会验证转换结果是否为有效数字
+ * **Note:** 对于无法转换的值，始终返回原值，不抛出错误
  */
 export declare const tryToNumber: (value: any) => number | typeof value;
 //# sourceMappingURL=tryToNumber.d.ts.map

package/dist/number/tryToNumber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tryToNumber.d.ts","sourceRoot":"","sources":["../../src/number/tryToNumber.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,GAAG,KAAG,MAAM,GAAG,OAAO,KAcxD,CAAC"}
+{"version":3,"file":"tryToNumber.d.ts","sourceRoot":"","sources":["../../src/number/tryToNumber.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,GAAG,KAAG,MAAM,GAAG,OAAO,KAcxD,CAAC"}

package/dist/object/deepFreeze.d.ts

@@ -1,6 +1,22 @@
 import { ReadonlyDeep } from 'type-fest';
 /**
- * 深度冻结对象
+ * 深度冻结对象及其所有嵌套属性，使其不可修改
+ * 递归遍历对象的所有属性，对每个对象和函数属性调用 Object.freeze()
+ * @template T - 对象类型
+ * @param target - 要深度冻结的对象
+ * @returns 深度冻结后的只读对象
+ * @example
+ * const obj = { a: { b: 1 } };
+ * const frozen = deepFreeze(obj);
+ * frozen.a.b = 2; // 抛出错误，对象已被冻结
+ * @example
+ * const arr = [1, { nested: 2 }];
+ * const frozenArr = deepFreeze(arr);
+ * frozenArr[1].nested = 3; // 抛出错误，嵌套对象也被冻结
+ * **Note:** 原始类型（string、number、boolean等）和 null 值不会被冻结
+ * **Note:** 函数对象也会被冻结，防止修改其属性
+ * **Note:** 如果对象已经被冻结，会直接返回原对象
+ * **Note:** 使用 type-fest 的 ReadonlyDeep 类型确保类型安全
  */
 export declare const deepFreeze: <T extends object>(target: T) => ReadonlyDeep<T>;
 //# sourceMappingURL=deepFreeze.d.ts.map

package/dist/object/deepFreeze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deepFreeze.d.ts","sourceRoot":"","sources":["../../src/object/deepFreeze.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGzC;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,KAAG,YAAY,CAAC,CAAC,CAQtE,CAAC"}
+{"version":3,"file":"deepFreeze.d.ts","sourceRoot":"","sources":["../../src/object/deepFreeze.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGzC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,KAAG,YAAY,CAAC,CAAC,CAQtE,CAAC"}

package/dist/object/flattenPathObjectToPlainObject.d.ts

@@ -1,8 +1,19 @@
 /**
- * 转换 扁平的路径对象到普通对象
- * @param value
+ * 将扁平的路径对象转换为嵌套的普通对象
+ * 支持点号路径（如 'a.b.c'）和数组路径（如 'a[0].b'）
+ * @param value - 扁平路径对象，键为路径字符串，值为对应值
+ * @returns 转换后的嵌套对象
  * @example
- * { 'a.a': 1 } => { a: { a: 1 }}
+ * flattenPathObjectToPlainObject({ 'a.b': 1, 'a.c': 2 });
+ * // 返回 { a: { b: 1, c: 2 } }
+ * @example
+ * flattenPathObjectToPlainObject({ 'users[0].name': 'Alice', 'users[1].name': 'Bob' });
+ * // 返回 { users: [{ name: 'Alice' }, { name: 'Bob' }] }
+ * @example
+ * flattenPathObjectToPlainObject({ 'config.db.host': 'localhost', 'config.db.port': 5432 });
+ * // 返回 { config: { db: { host: 'localhost', port: 5432 } } }
+ * **Note:** 对于包含数组索引的路径使用 set() 函数，其他路径使用 setWith() 函数
+ * **Note:** 空对象返回空对象，不会抛出错误
  */
 export declare const flattenPathObjectToPlainObject: (value: Record<string, any>) => {};
 //# sourceMappingURL=flattenPathObjectToPlainObject.d.ts.map

package/dist/object/flattenPathObjectToPlainObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flattenPathObjectToPlainObject.d.ts","sourceRoot":"","sources":["../../src/object/flattenPathObjectToPlainObject.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OAWxE,CAAC"}
+{"version":3,"file":"flattenPathObjectToPlainObject.d.ts","sourceRoot":"","sources":["../../src/object/flattenPathObjectToPlainObject.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,8BAA8B,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OAWxE,CAAC"}

package/dist/object/get.d.ts

@@ -17,8 +17,8 @@
  * get([{ name: 'test' }], '[0].name'); // 返回 'test'（数组访问）
  * @example
  * get({ a: [{ b: 'value' }] }, 'a,0,b'); // 返回 'value'（逗号分隔路径）
- * @note 路径解析支持多种分隔符：逗号(,)、方括号([])和点(.)
- * @note 如果对象在路径的任何环节为null/undefined，将返回默认值
+ * **Note:** 路径解析支持多种分隔符：逗号(,)、方括号([])和点(.)
+ * **Note:** 如果对象在路径的任何环节为null/undefined，将返回默认值
  */
 export declare const get: <T = any>(obj: any, path: string, defaultValue?: any) => T;
 //# sourceMappingURL=get.d.ts.map

package/dist/object/has.d.ts

@@ -14,8 +14,8 @@
  * has({ a: {} }, 'a.b'); // 返回 false（属性不存在）
  * @example
  * has(null, 'a'); // 返回 false（对象为null）
- * @note 使用Object.hasOwnProperty检查属性，不考虑继承属性
- * @note 支持任意深度的嵌套属性检查
+ * **Note:** 使用Object.hasOwnProperty检查属性，不考虑继承属性
+ * **Note:** 支持任意深度的嵌套属性检查
  */
 export declare const has: (obj: any, key: string) => boolean;
 //# sourceMappingURL=has.d.ts.map

package/dist/object/isEqual.d.ts

@@ -18,9 +18,9 @@
  * isEqual(/abc/i, /abc/i); // 返回 true（正则表达式比较）
  * @example
  * isEqual(new Uint8Array([1,2]), new Uint8Array([1,2])); // 返回 true（Uint8Array比较）
- * @note 比较对象时会检查构造函数和自有属性，不考虑原型链上的属性
- * @note 循环引用对象可能导致无限递归
- * @note 函数不支持比较函数、Promise等引用类型的内部状态
+ * **Note:** 比较对象时会检查构造函数和自有属性，不考虑原型链上的属性
+ * **Note:** 循环引用对象可能导致无限递归
+ * **Note:** 函数不支持比较函数、Promise等引用类型的内部状态
  */
 export declare const isEqual: (a: any, b: any) => boolean;
 //# sourceMappingURL=isEqual.d.ts.map

package/dist/object/omit.d.ts

@@ -18,8 +18,8 @@
  * omit({ a: 1 }, []); // 返回 { a: 1 }（排除空数组）
  * @example
  * omit(null, ['a']); // 返回 {}（输入为null）
- * @note 函数会创建源对象的浅拷贝，原对象不会被修改
- * @note 只排除自有属性，继承属性不受影响
+ * **Note:** 函数会创建源对象的浅拷贝，原对象不会被修改
+ * **Note:** 只排除自有属性，继承属性不受影响
  */
 export declare const omit: <T extends Record<string, any>, Keys extends keyof T>(obj: T, keys: Keys[]) => Omit<T, Keys>;
 //# sourceMappingURL=omit.d.ts.map

package/dist/object/omitBy.d.ts

@@ -1,8 +1,8 @@
 /**
  * 创建一个新对象，通过方法除了指定的属性
- * @param obj
- * @param keys
- * @returns
+ * @param object 源对象
+ * @param fn 判断函数，返回 true 时排除该属性
+ * @returns 新对象
  */
 export declare function omitBy<T extends Record<string, any>>(object: T, fn: (value: any, key: string) => boolean): T;
 //# sourceMappingURL=omitBy.d.ts.map

package/dist/object/pick.d.ts

@@ -18,8 +18,8 @@
  * pick(null, ['a', 'b']); // 返回 {}
  * @example
  * pick({ a: 1 }, ['b']); // 返回 {}（属性不存在）
- * @note 只选取对象的自有属性，不包括继承的属性
- * @note 对于不存在的属性，会被忽略而不会出现在结果中
+ * **Note:** 只选取对象的自有属性，不包括继承的属性
+ * **Note:** 对于不存在的属性，会被忽略而不会出现在结果中
  */
 export declare function pick<T extends object, Keys extends keyof T>(obj: T, keys: Keys[]): Pick<T, Keys>;
 //# sourceMappingURL=pick.d.ts.map

package/dist/object/plainObjectToFlattenPathObject.d.ts

@@ -1,9 +1,15 @@
 /**
  * 扁平化对象
- * @param object
- * @returns
- * in { a: { a: [0, 1] } }
- * out { 'a.a[0]': 0, 'a.a[1]': 1 }
+ * @param object 待扁平化的对象
+ * @returns 扁平化后的键值对对象
+ * @example
+ * ```ts
+ * // 输入
+ * { a: { a: [0, 1] } }
+ *
+ * // 输出
+ * { 'a.a[0]': 0, 'a.a[1]': 1 }
+ * ```
  */
 export declare function plainObjectToFlattenPathObject(object: object): Record<string, any>;
 //# sourceMappingURL=plainObjectToFlattenPathObject.d.ts.map

package/dist/object/plainObjectToFlattenPathObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plainObjectToFlattenPathObject.d.ts","sourceRoot":"","sources":["../../src/object/plainObjectToFlattenPathObject.ts"],"names":[],"mappings":"AAmBA;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAElF"}
+{"version":3,"file":"plainObjectToFlattenPathObject.d.ts","sourceRoot":"","sources":["../../src/object/plainObjectToFlattenPathObject.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAElF"}

package/dist/object/set.d.ts

@@ -20,9 +20,9 @@ export declare function setBase(object: Record<string, any>, path: string, value
  * @example
  * set({ a: 1 }, 'a.b', 2);
  * // 返回 { a: { b: 2 } }（覆盖原属性值）
- * @note 函数会原地修改输入对象，而非创建新对象
- * @note 路径中的数字索引会创建数组，其他情况创建普通对象
- * @note 空路径段（如'a..b'）会被忽略
+ * **Note:** 函数会原地修改输入对象，而非创建新对象
+ * **Note:** 路径中的数字索引会创建数组，其他情况创建普通对象
+ * **Note:** 空路径段（如'a..b'）会被忽略
  */
 export declare function set(object: Record<string, any>, path: string, value: any): Record<string, any>;
 //# sourceMappingURL=set.d.ts.map

package/dist/object/setWith.d.ts

@@ -3,7 +3,6 @@
  * 如果 fun 返回 undefined 将会有它的处理方法代替。
  * customFun 会传入3个参数：(nsValue, key, nsObject)
  *
- * @export
  * @param object
  * @param path
  * @param value

package/dist/object/setWith.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setWith.d.ts","sourceRoot":"","sources":["../../src/object/setWith.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,EACV,SAAS,EAAE,CAAC,YAAY,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,GAAG,GACjE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAGrB"}
+{"version":3,"file":"setWith.d.ts","sourceRoot":"","sources":["../../src/object/setWith.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,EACV,SAAS,EAAE,CAAC,YAAY,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,GAAG,GACjE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAGrB"}

package/dist/object/toPlainObject.d.ts

@@ -1,2 +1,21 @@
+/**
+ * 将任意值转换为普通对象，只保留自有属性
+ * 通过遍历对象的可枚举属性，创建一个新的普通对象
+ * @param value - 要转换的值
+ * @returns 包含所有自有属性的普通对象
+ * @example
+ * const obj = Object.create({ inherited: 'value' });
+ * obj.own = 'own value';
+ * toPlainObject(obj); // 返回 { own: 'own value' }（只保留自有属性）
+ * @example
+ * toPlainObject('string'); // 返回 {}（字符串没有自有属性）
+ * @example
+ * toPlainObject(null); // 返回 {}（null/undefined 返回空对象）
+ * @example
+ * toPlainObject([1, 2, 3]); // 返回 { '0': 1, '1': 2, '2': 3 }（数组转换为对象）
+ * **Note:** 使用 Object.prototype.hasOwnProperty 确保只复制自有属性
+ * **Note:** 对于非对象值，返回空对象
+ * **Note:** 不会复制原型链上的属性
+ */
 export declare const toPlainObject: (value: any) => Record<string, any>;
 //# sourceMappingURL=toPlainObject.d.ts.map

package/dist/object/toPlainObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toPlainObject.d.ts","sourceRoot":"","sources":["../../src/object/toPlainObject.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,GAAI,OAAO,GAAG,KAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAQ5D,CAAC"}
+{"version":3,"file":"toPlainObject.d.ts","sourceRoot":"","sources":["../../src/object/toPlainObject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,GAAG,KAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAQ5D,CAAC"}

package/dist/object/zipObject.d.ts

@@ -1,10 +1,27 @@
 /**
- * 创建一个对象，将映射指定键值
- *
+ * 创建一个对象，将键数组和值数组/函数配对组合
+ * 支持多种值来源：固定值、值数组或值生成函数
+ * @template K - 键的类型，必须是字符串、数字或符号
+ * @template V - 值的类型
+ * @param keys - 键数组
+ * @param values - 值来源，可以是：
+ *   - 固定值：所有键都使用相同的值
+ *   - 值数组：按索引对应键赋值
+ *   - 值生成函数：根据键和索引动态生成值
+ * @returns 组合后的对象
  * @example
- * const zipped = zipObject(['a', 'b'], [1, 2]) // { a: 1, b: 2 }
- * const zipped = zipObject(['a', 'b'], (k, i) => k + i) // { a: 'a0', b: 'b1' }
- * const zipped = zipObject(['a', 'b'], 1) // { a: 1, b: 1 }
+ * zipObject(['a', 'b'], [1, 2]); // 返回 { a: 1, b: 2 }
+ * @example
+ * zipObject(['a', 'b'], (key, idx) => key + idx); // 返回 { a: 'a0', b: 'b1' }
+ * @example
+ * zipObject(['a', 'b'], 'default'); // 返回 { a: 'default', b: 'default' }
+ * @example
+ * zipObject([], [1, 2]); // 返回 {}（空键数组）
+ * @example
+ * zipObject(['x', 'y'], [10]); // 返回 { x: 10, y: undefined }（值数组长度不足）
+ * **Note:** 如果值数组长度小于键数组，多余的键值为 undefined
+ * **Note:** 如果值生成函数抛出错误，会传播该错误
+ * **Note:** 空键数组返回空对象
  */
 export declare function zipObject<K extends string | number | symbol, V>(keys: K[], values: V | ((key: K, idx: number) => V) | V[]): Record<K, V>;
 //# sourceMappingURL=zipObject.d.ts.map

package/dist/object/zipObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zipObject.d.ts","sourceRoot":"","sources":["../../src/object/zipObject.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,EAC7D,IAAI,EAAE,CAAC,EAAE,EACT,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,GAC7C,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAiBd"}
+{"version":3,"file":"zipObject.d.ts","sourceRoot":"","sources":["../../src/object/zipObject.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,EAC7D,IAAI,EAAE,CAAC,EAAE,EACT,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,GAC7C,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAiBd"}

package/dist/platform/is-browser.d.ts

@@ -1,5 +1,18 @@
 /**
- * 是否是浏览器
+ * 检测当前运行环境是否为浏览器环境
+ * 通过检查全局 window 对象是否存在来判断
+ *
+ * **Constant:**  {boolean} IS_BROWSER - 是否运行在浏览器环境中
+ * @example
+ * if (IS_BROWSER) {
+ *   // 浏览器环境下的代码
+ *   console.log('在浏览器中运行');
+ * } else {
+ *   // Node.js 或其他环境
+ *   console.log('不在浏览器中运行');
+ * }
+ * **Note:** 该检测基于 window 对象的存在性，在某些特殊环境中可能不准确
+ * **Note:** 在 SSR (服务端渲染) 环境中，此值在服务端为 false，在客户端为 true
  */
 export declare const IS_BROWSER: boolean;
 //# sourceMappingURL=is-browser.d.ts.map

package/dist/platform/is-browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is-browser.d.ts","sourceRoot":"","sources":["../../src/platform/is-browser.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,OAAoC,CAAC"}
+{"version":3,"file":"is-browser.d.ts","sourceRoot":"","sources":["../../src/platform/is-browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,EAAE,OAAoC,CAAC"}

package/dist/random/randomArrayItem.d.ts

@@ -1,2 +1,19 @@
-export declare const randomArrayItem: (array: any[]) => any;
+/**
+ * 从数组中随机选择一个元素
+ * 使用 Math.random() 生成随机索引，返回对应位置的元素
+ * @template T - 数组元素的类型
+ * @param array - 要从中选择元素的数组
+ * @returns 随机选择的数组元素
+ * @throws {TypeError} 当输入不是数组时抛出错误
+ * @example
+ * randomArrayItem([1, 2, 3, 4, 5]); // 返回数组中的随机一个数字
+ * @example
+ * randomArrayItem(['a', 'b', 'c']); // 返回 'a'、'b' 或 'c' 中的一个
+ * @example
+ * randomArrayItem([]); // 返回 undefined（空数组）
+ * **Note:** 使用 Math.floor() 和 Math.random() 实现随机选择
+ * **Note:** 对于空数组返回 undefined
+ * **Note:** 每个元素被选择的概率相等
+ */
+export declare const randomArrayItem: <T>(array: T[]) => T;
 //# sourceMappingURL=randomArrayItem.d.ts.map

package/dist/random/randomArrayItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"randomArrayItem.d.ts","sourceRoot":"","sources":["../../src/random/randomArrayItem.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,eAAe,GAAI,OAAO,GAAG,EAAE,QAAoD,CAAC"}
+{"version":3,"file":"randomArrayItem.d.ts","sourceRoot":"","sources":["../../src/random/randomArrayItem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,KAAG,CAAoD,CAAC"}

package/dist/random/randomFloat.d.ts

@@ -1,2 +1,18 @@
+/**
+ * 生成指定范围内的随机浮点数
+ * 使用 Math.random() 生成 0 到 1 之间的随机数，然后映射到指定范围
+ * @param min - 最小值（包含），默认为 Number.MIN_SAFE_INTEGER
+ * @param max - 最大值（不包含），默认为 Number.MAX_SAFE_INTEGER
+ * @returns 指定范围内的随机浮点数
+ * @example
+ * randomFloat(0, 10); // 返回 0 到 10 之间的随机浮点数，如 3.14159
+ * @example
+ * randomFloat(-5, 5); // 返回 -5 到 5 之间的随机浮点数
+ * @example
+ * randomFloat(); // 返回任意安全的浮点数
+ * **Note:** 结果范围是 [min, max)，即包含最小值但不包含最大值
+ * **Note:** 使用 Math.random()，分布是均匀的
+ * **Note:** 如果 min >= max，返回结果可能不符合预期
+ */
 export declare const randomFloat: (min?: number, max?: number) => number;
 //# sourceMappingURL=randomFloat.d.ts.map

package/dist/random/randomFloat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"randomFloat.d.ts","sourceRoot":"","sources":["../../src/random/randomFloat.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,WAAW,GAAI,MAAK,MAAgC,EAAE,MAAK,MAAgC,WACrE,CAAC"}
+{"version":3,"file":"randomFloat.d.ts","sourceRoot":"","sources":["../../src/random/randomFloat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,GAAI,MAAK,MAAgC,EAAE,MAAK,MAAgC,WACrE,CAAC"}

package/dist/random/randomInt.d.ts

@@ -1,8 +1,18 @@
 /**
- * 随机整数
- *
- * @param [min=Number.MIN_SAFE_INTEGER]
- * @param [max=Number.MAX_SAFE_INTEGER]
+ * 生成指定范围内的随机整数
+ * 使用 Math.random() 生成随机数，然后使用 Math.floor() 向下取整
+ * @param min - 最小值（包含），默认为 Number.MIN_SAFE_INTEGER
+ * @param max - 最大值（包含），默认为 Number.MAX_SAFE_INTEGER
+ * @returns 指定范围内的随机整数
+ * @example
+ * randomInt(1, 10); // 返回 1 到 10 之间的随机整数，如 5
+ * @example
+ * randomInt(0, 1); // 返回 0 或 1
+ * @example
+ * randomInt(-5, 5); // 返回 -5 到 5 之间的随机整数
+ * **Note:** 结果范围是 [min, max]，即包含最小值和最大值
+ * **Note:** 使用 Math.floor() 确保返回整数
+ * **Note:** 如果 min > max，返回结果可能不符合预期
  */
 export declare function randomInt(min?: number, max?: number): number;
 //# sourceMappingURL=randomInt.d.ts.map

package/dist/random/randomInt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"randomInt.d.ts","sourceRoot":"","sources":["../../src/random/randomInt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,GAAE,MAAgC,EAAE,GAAG,GAAE,MAAgC,UAErG"}
+{"version":3,"file":"randomInt.d.ts","sourceRoot":"","sources":["../../src/random/randomInt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,GAAG,GAAE,MAAgC,EAAE,GAAG,GAAE,MAAgC,UAErG"}

package/dist/random/randomString.d.ts

@@ -6,5 +6,21 @@ export declare const UPPER_LETTERS: string;
 export declare const LETTERS: string;
 export declare const SAFE_URL = "_-";
 export declare const URL_ALL: string;
+/**
+ * 生成指定长度和字符集的随机字符串
+ * 使用 Web Crypto API 的 crypto.getRandomValues() 生成加密安全的随机数
+ * @param size - 字符串长度，默认 16
+ * @param alphabet - 可选字符集，默认包含数字、大小写字母和 URL 安全字符
+ * @returns 指定长度和字符集的随机字符串
+ * @example
+ * randomString(8); // 返回 8 位随机字符串，如 'aB3kL9mP'
+ * @example
+ * randomString(4, '0123456789'); // 返回 4 位数字字符串，如 '1847'
+ * @example
+ * randomString(12, 'abcdef'); // 返回 12 位小写字母字符串，如 'abcdefabcdef'
+ * **Note:** 使用 crypto.getRandomValues() 生成加密安全的随机数
+ * **Note:** 通过位运算优化性能，避免模运算
+ * **Note:** 默认字符集包含 URL 安全的字符，适合用作 ID 或令牌
+ */
 export declare const randomString: (size?: number, alphabet?: string) => string;
 //# sourceMappingURL=randomString.d.ts.map

package/dist/random/randomString.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"randomString.d.ts","sourceRoot":"","sources":["../../src/random/randomString.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,IAAI,MAAM,CAAC;AACxB,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAC/C,eAAO,MAAM,OAAO,QAA6B,CAAC;AAGlD,eAAO,MAAM,aAAa,+BAA+B,CAAC;AAC1D,eAAO,MAAM,aAAa,QAA8B,CAAC;AACzD,eAAO,MAAM,OAAO,QAAgC,CAAC;AAGrD,eAAO,MAAM,QAAQ,OAAO,CAAC;AAC7B,eAAO,MAAM,OAAO,QAA+B,CAAC;AAEpD,eAAO,MAAM,YAAY,GAAI,OAAM,MAAW,EAAE,WAAU,MAAgB,WAMzE,CAAC"}
+{"version":3,"file":"randomString.d.ts","sourceRoot":"","sources":["../../src/random/randomString.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,IAAI,MAAM,CAAC;AACxB,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAC/C,eAAO,MAAM,OAAO,QAA6B,CAAC;AAGlD,eAAO,MAAM,aAAa,+BAA+B,CAAC;AAC1D,eAAO,MAAM,aAAa,QAA8B,CAAC;AACzD,eAAO,MAAM,OAAO,QAAgC,CAAC;AAGrD,eAAO,MAAM,QAAQ,OAAO,CAAC;AAC7B,eAAO,MAAM,OAAO,QAA+B,CAAC;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,GAAI,OAAM,MAAW,EAAE,WAAU,MAAgB,WAMzE,CAAC"}