@pmun/utils 0.2.3 → 0.3.1

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import { Dayjs, QUnitType, OpUnitType, ManipulateType } from 'dayjs';
  * @param array 原始数组
  * @param item 要移除的项
  * @returns 移除指定项后的新数组，不会修改原始数组
+ * @group Array
  * @example
  * ```ts
  * const numbers = [1, 2, 3, 4, 5]
@@ -25,6 +26,7 @@ declare function remove<T>(array: T[], item: T): T[];
  * 数组去重，移除数组中的重复元素
  * @param array 原始数组
  * @returns 去重后的新数组，保持原始顺序
+ * @group Array
  * @example
  * ```ts
  * const numbers = [1, 2, 2, 3, 3, 4, 5, 5]
@@ -41,6 +43,7 @@ declare function unique<T>(array: T[]): T[];
  * @param array 原始数组
  * @param size 每个块的大小，必须为正整数
  * @returns 二维数组，每个子数组最多包含 size 个元素
+ * @group Array
  * @example
  * ```ts
  * const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
@@ -56,6 +59,7 @@ declare function chunk<T>(array: T[], size: number): T[][];
  * 获取数组中的最后一个元素
  * @param array 数组
  * @returns 最后一个元素，如果数组为空则返回 undefined
+ * @group Array
  * @example
  * ```ts
  * const numbers = [1, 2, 3, 4, 5]
@@ -70,6 +74,7 @@ declare function last<T>(array: T[]): T | undefined;
  * 获取数组中的第一个元素
  * @param array 数组
  * @returns 第一个元素，如果数组为空则返回 undefined
+ * @group Array
  * @example
  * ```ts
  * const numbers = [1, 2, 3, 4, 5]
@@ -84,6 +89,7 @@ declare function first<T>(array: T[]): T | undefined;
  * 随机打乱数组元素顺序
  * @param array 原始数组
  * @returns 打乱后的新数组，不会修改原始数组
+ * @group Array
  * @example
  * ```ts
  * const numbers = [1, 2, 3, 4, 5]
@@ -97,6 +103,7 @@ declare function shuffle<T>(array: T[]): T[];
  * 从数组中随机选择一个元素
  * @param array 数组
  * @returns 随机选择的元素，如果数组为空则返回 undefined
+ * @group Array
  * @example
  * ```ts
  * const fruits = ['苹果', '香蕉', '橙子', '梨', '葡萄']
@@ -113,6 +120,7 @@ declare function sample<T>(array: T[]): T | undefined;
  * @param a 第一个数组
  * @param b 第二个数组
  * @returns 如果两个数组长度相同且对应位置的元素全部相等则返回 true，否则返回 false
+ * @group Array
  * @example
  * ```ts
  * isEqual([1, 2, 3], [1, 2, 3]) // true
@@ -131,6 +139,7 @@ declare function isEqual<T>(a: T[], b: T[]): boolean;
  * @param array 原始数组
  * @param keyFn 用于生成分组键的函数，接收数组元素并返回用作分组键的值
  * @returns 分组后的对象，键为分组键，值为对应的元素数组
+ * @group Array
  * @example
  * ```ts
  * const people = [
@@ -169,6 +178,7 @@ declare function groupBy<T, K extends string | number | symbol>(array: T[], keyF
  * @param config.valueKey - 选项值的字段名 (默认为 'value')
  * @returns 添加了"全部"选项的新数组
  *
+ * @group Array
  * @example
  * ```ts
  * // 基本用法
@@ -214,6 +224,7 @@ declare function appendUniversalOption<T extends Record<string, any>, V = any>(o
  * @param deleteOldKeys - 是否删除旧属性（默认 `true`）
  * @returns 处理后的树形结构数组
  *
+ * @group Array
  * @example
  * const tree = [
  *   { id: 1, name: 'Node 1', children: [...] }
@@ -230,6 +241,7 @@ declare function renameTreeNodes(tree: any[], renameMap: Record<string, string>,
  * @param childKey - 子节点的键名（默认为 `'children'`）
  * @returns 转换后的树形结构数组
  *
+ * @group Array
  * @example
  * // 重命名 `name` 为 `label`，并添加 `isLeaf` 属性
  * const transformedTree = transformTree(tree, (node, children) => ({
@@ -248,7 +260,7 @@ type KeysMatching<T, V> = {
  * @param arr - 原始数组
  * @param key - 数组对象键
  * @returns 对应键的对象
- *
+ * @group Array
  * @example
  * ```ts
  * const arr = [{ key: 'tom', name: '汤姆' }, { key: 'jack', name: '杰克' }]
@@ -260,11 +272,44 @@ type KeysMatching<T, V> = {
  * ```
  */
 declare function arrayToObject<T>(arr: T[], key: KeysMatching<T, string | number>): Record<string, T>;
+/**
+ * 替换数组数据中指定字段的 `&nbsp;` 为不换行空格
+ *
+ * @param {Array<Record<string, any>>} arr - 数组
+ * @param {string} key - 需要处理的字段名
+ * @returns {Array<Record<string, any>>} 处理后的数据数组
+ *
+ * @group String
+ * @example
+ * ```ts
+ * // 基本用法
+ * const data = [
+ *   { name: 'John&nbsp;Doe', age: 30 },
+ *   { name: 'Jane&nbsp;&nbsp;Smith', age: 25 }
+ * ]
+ * const result = arrayReplaceNBSP(data, 'name')
+ * // 结果: [
+ * //   { name: 'John Doe', age: 30 },
+ * //   { name: 'Jane  Smith', age: 25 }
+ * // ]
+ *
+ * // 空数组情况
+ * const emptyData = []
+ * const result = arrayReplaceNBSP(emptyData, 'name')
+ * // 结果: []
+ * ```
+ */
+declare function arrayReplaceNBSP<T extends Record<string, string | number | boolean | object>>(arr: T[], key: string): T[];
 
+/**
+ * 表示日期的各种类型，可以是日期对象、日期字符串或时间戳
+ */
+type DateLike = Date | string | number;
 /**
  * 创建 dayjs 对象
  * @param date 日期参数，可以是日期对象、时间戳或日期字符串
  * @returns dayjs 对象
+ * @group Date
  * @example
  * ```ts
  * createDate() // 当前日期时间
@@ -272,12 +317,41 @@ declare function arrayToObject<T>(arr: T[], key: KeysMatching<T, string | number
  * createDate(1684123456000) // 时间戳
  * ```
  */
-declare function createDate(date?: string | number | Date | Dayjs): Dayjs;
+declare function createDate(date?: DateLike | Dayjs): Dayjs;
+/**
+ * 判断时间戳是否为毫秒级时间戳
+ * @param value 要检查的值
+ * @returns 如果是毫秒级时间戳则返回 true，否则返回 false
+ * @group Date
+ * @example
+ * ```ts
+ * isMillisecondTimestamp(1673740800000) // true，13位数字
+ * isMillisecondTimestamp(1673740800) // false，10位数字，秒级时间戳
+ * isMillisecondTimestamp('1673740800000') // false, 字符串不是时间戳
+ * isMillisecondTimestamp(new Date()) // false，日期对象不是时间戳
+ * ```
+ */
+declare function isMillisecondTimestamp(value: unknown): boolean;
+/**
+ * 转换为 dayjs 可接收的参数格式
+ * @param value 日期参数，可以是日期对象、时间戳（秒或毫秒）或日期字符串
+ * @returns 转换后的参数，如果是秒级时间戳则转为毫秒级，其他类型保持不变
+ * @group Date
+ * @example
+ * ```ts
+ * convertToDayjsParam(1673740800) // 1673740800000，秒转为毫秒
+ * convertToDayjsParam(1673740800000) // 1673740800000，毫秒保持不变
+ * convertToDayjsParam(new Date()) // Date对象，保持不变
+ * convertToDayjsParam('2023-01-15') // '2023-01-15'，字符串保持不变
+ * ```
+ */
+declare function convertToDayjsParam(value: DateLike): DateLike;
 /**
  * 格式化日期为指定格式的字符串
  * @param date 日期对象、时间戳或日期字符串
- * @param format 格式字符串，支持的占位符请参考 dayjs 文档
+ * @param format 格式字符串，支持的占位符请参考 [dayjs 文档](https://day.js.org/docs/zh-CN/durations/format#%E6%94%AF%E6%8C%81%E7%9A%84%E6%A0%BC%E5%BC%8F%E5%8C%96%E5%8D%A0%E4%BD%8D%E7%AC%A6%E5%88%97%E8%A1%A8)
  * @returns 格式化后的日期字符串
+ * @group Date
  * @example
  * ```ts
  * formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss') // "2023-05-16 14:30:45"
@@ -285,10 +359,24 @@ declare function createDate(date?: string | number | Date | Dayjs): Dayjs;
  * formatDate(1684123456000, 'MM/DD/YYYY') // "05/15/2023"
  * ```
  */
-declare function formatDate(date: Date | string | number, format?: string): string;
+declare function formatDate(date: DateLike, format?: string): string;
+/**
+ * 将日期格式化为完整的时间字符串（YYYY-MM-DD HH:mm:ss）
+ * @param date 日期对象、时间戳或日期字符串
+ * @returns 格式为 YYYY-MM-DD HH:mm:ss 的日期时间字符串
+ * @group Date
+ * @example
+ * ```ts
+ * formatFullTime(new Date()) // "2023-05-16 14:30:45"
+ * formatFullTime('2023-05-15') // "2023-05-15 00:00:00"
+ * formatFullTime(1684123456) // "2023-05-15 10:30:56"（秒级时间戳会被自动转换）
+ * ```
+ */
+declare function formatFullTime(date: DateLike): string;
 /**
  * 获取当前日期时间的时间戳
  * @returns 当前时间戳（毫秒）
+ * @group Date
  * @example
  * ```ts
  * now() // 例如: 1684123456789
@@ -300,6 +388,7 @@ declare function now(): number;
  * @param dateStr 日期字符串
  * @returns 日期对象
  * @throws 如果日期格式无效，抛出 TypeError
+ * @group Date
  * @example
  * ```ts
  * parseDate('2023-05-15') // Date 对象: Mon May 15 2023 00:00:00
@@ -314,6 +403,7 @@ declare function parseDate(dateStr: string): Date;
  * @param date2 第二个日期
  * @param unit 计量单位，默认为 'day'，可以是 'year', 'month', 'week', 'day', 'hour', 'minute', 'second', 'millisecond'
  * @returns 两个日期之间的差值，正数表示 date1 晚于 date2，负数表示 date1 早于 date2
+ * @group Date
  * @example
  * ```ts
  * diff('2023-05-15', '2023-05-10') // 5（相差5天）
@@ -321,13 +411,14 @@ declare function parseDate(dateStr: string): Date;
  * diff('2023-05-15 08:00', '2023-05-15 06:00', 'hour') // 2（相差2小时）
  * ```
  */
-declare function diff(date1: Date | string | number, date2: Date | string | number, unit?: QUnitType | OpUnitType): number;
+declare function diff(date1: DateLike, date2: DateLike, unit?: QUnitType | OpUnitType): number;
 /**
  * 向日期添加指定时间
  * @param date 原始日期
  * @param amount 要添加的数量，可以为负数
  * @param unit 时间单位，默认为 'day'，可以是 'year', 'month', 'week', 'day', 'hour', 'minute', 'second', 'millisecond'
  * @returns 添加后的新日期对象
+ * @group Date
  * @example
  * ```ts
  * add(new Date('2023-05-15'), 2, 'day') // Date 对象: Wed May 17 2023
@@ -335,24 +426,26 @@ declare function diff(date1: Date | string | number, date2: Date | string | numb
  * add('2023-05-15 12:00', 30, 'minute') // Date 对象: Mon May 15 2023 12:30:00
  * ```
  */
-declare function add(date: Date | string | number, amount: number, unit?: ManipulateType): Date;
+declare function add(date: DateLike, amount: number, unit?: ManipulateType): Date;
 /**
  * 向日期添加指定天数
  * @param date 原始日期
  * @param days 要添加的天数（可以为负数）
  * @returns 添加天数后的新日期对象
+ * @group Date
  * @example
  * ```ts
  * addDays(new Date('2023-05-15'), 5) // Date 对象: Sat May 20 2023
  * addDays('2023-05-15', -3) // Date 对象: Fri May 12 2023
  * ```
  */
-declare function addDays(date: Date | string | number, days: number): Date;
+declare function addDays(date: DateLike, days: number): Date;
 /**
  * 向日期添加指定月数
  * @param date 原始日期
  * @param months 要添加的月数（可以为负数）
  * @returns 添加月数后的新日期对象
+ * @group Date
  * @example
  * ```ts
  * addMonths(new Date('2023-05-15'), 2) // Date 对象: Sat Jul 15 2023
@@ -360,12 +453,13 @@ declare function addDays(date: Date | string | number, days: number): Date;
  * addMonths('2023-01-15', -3) // Date 对象: Wed Oct 15 2022
  * ```
  */
-declare function addMonths(date: Date | string | number, months: number): Date;
+declare function addMonths(date: DateLike, months: number): Date;
 /**
  * 向日期添加指定年数
  * @param date 原始日期
  * @param years 要添加的年数（可以为负数）
  * @returns 添加年数后的新日期对象
+ * @group Date
  * @example
  * ```ts
  * addYears(new Date('2023-05-15'), 1) // Date 对象: Wed May 15 2024
@@ -373,12 +467,13 @@ declare function addMonths(date: Date | string | number, months: number): Date;
  * addYears('2024-02-29', 1) // Date 对象: Fri Feb 28 2025（注意闰年自动调整）
  * ```
  */
-declare function addYears(date: Date | string | number, years: number): Date;
+declare function addYears(date: DateLike, years: number): Date;
 /**
  * 获取指定日期是一周中的第几天
  * @param date 日期
  * @param startOnMonday 是否从周一开始计算（默认为 false，即从周日开始）
  * @returns 一周中的第几天（0-6），周日为 0，周六为 6；如果 startOnMonday 为 true，则周一为 0，周日为 6
+ * @group Date
  * @example
  * ```ts
  * getDayOfWeek(new Date('2023-05-15')) // 1（周一，从周日开始算是第1天）
@@ -387,13 +482,14 @@ declare function addYears(date: Date | string | number, years: number): Date;
  * getDayOfWeek('2023-05-14', true) // 6（周日，从周一开始算是第6天）
  * ```
  */
-declare function getDayOfWeek(date: Date | string | number, startOnMonday?: boolean): number;
+declare function getDayOfWeek(date: DateLike, startOnMonday?: boolean): number;
 /**
  * 检查日期是否在指定范围内
  * @param date 要检查的日期
  * @param startDate 范围起始日期
  * @param endDate 范围结束日期
  * @returns 如果日期在指定范围内（不包括边界）则返回 true，否则返回 false
+ * @group Date
  * @example
  * ```ts
  * isDateInRange('2023-05-15', '2023-05-10', '2023-05-20') // true
@@ -401,12 +497,13 @@ declare function getDayOfWeek(date: Date | string | number, startOnMonday?: bool
  * isDateInRange('2023-05-15', '2023-05-10', '2023-05-15') // false（不包括结束日期）
  * ```
  */
-declare function isDateInRange(date: Date | string | number, startDate: Date | string | number, endDate: Date | string | number): boolean;
+declare function isDateInRange(date: DateLike, startDate: DateLike, endDate: DateLike): boolean;
 /**
  * 获取指定月份的天数
  * @param year 年份
  * @param month 月份（0-11），0 表示一月，11 表示十二月
  * @returns 该月的天数
+ * @group Date
  * @example
  * ```ts
  * getDaysInMonth(2023, 1) // 28（2023年2月有28天）
@@ -420,19 +517,21 @@ declare function getDaysInMonth(year: number, month: number): number;
  * @param date 日期
  * @param baseDate 基准日期，默认为当前时间
  * @returns 相对时间描述，如"几分钟前"、"几天后"等
+ * @group Date
  * @example
  * ```ts
  * fromNow(new Date(Date.now() - 5 * 60 * 1000)) // "5分钟前"
- * fromNow(new Date(Date.now() + 24 * 60 * 60 * 1000)) // "1天后"
+ * fromNow(new Date(Date.now() + 24 * 60 * 60 * 1000)) // "1天内"
  * fromNow('2023-01-01', '2023-01-05') // "4天前"
  * ```
  */
-declare function fromNow(date: Date | string | number, baseDate?: Date | string | number): string;
+declare function fromNow(date: DateLike, baseDate?: DateLike): string;
 /**
  * 获取日期的开始时间
  * @param date 日期
  * @param unit 单位，可以是 'year', 'month', 'week', 'day', 'hour', 'minute', 'second'
  * @returns 单位开始时间的日期对象
+ * @group Date
  * @example
  * ```ts
  * startOf(new Date('2023-05-15 15:30:45'), 'day') // Date 对象: Mon May 15 2023 00:00:00
@@ -440,12 +539,13 @@ declare function fromNow(date: Date | string | number, baseDate?: Date | string
  * startOf('2023-05-15 15:30:45', 'hour') // Date 对象: Mon May 15 2023 15:00:00
  * ```
  */
-declare function startOf(date: Date | string | number, unit: OpUnitType): Date;
+declare function startOf(date: DateLike, unit: OpUnitType): Date;
 /**
  * 获取日期的结束时间
  * @param date 日期
  * @param unit 单位，可以是 'year', 'month', 'week', 'day', 'hour', 'minute', 'second'
  * @returns 单位结束时间的日期对象
+ * @group Date
  * @example
  * ```ts
  * endOf(new Date('2023-05-15 15:30:45'), 'day') // Date 对象: Mon May 15 2023 23:59:59.999
@@ -453,11 +553,12 @@ declare function startOf(date: Date | string | number, unit: OpUnitType): Date;
  * endOf('2023-05-15 15:30:45', 'hour') // Date 对象: Mon May 15 2023 15:59:59.999
  * ```
  */
-declare function endOf(date: Date | string | number, unit: OpUnitType): Date;
+declare function endOf(date: DateLike, unit: OpUnitType): Date;
 /**
  * 格式化日期为人类友好的格式
  * @param date 日期
  * @returns 人类友好的日期描述，如"今天 HH:mm"、"昨天 HH:mm"、"明天 HH:mm"或"YYYY-MM-DD HH:mm"
+ * @group Date
  * @example
  * ```ts
  * formatHumanReadable(new Date()) // "今天 15:30"
@@ -466,7 +567,7 @@ declare function endOf(date: Date | string | number, unit: OpUnitType): Date;
  * formatHumanReadable('2023-01-01') // "2023-01-01 00:00"
  * ```
  */
-declare function formatHumanReadable(date: Date | string | number): string;
+declare function formatHumanReadable(date: DateLike): string;
 
 /**
  * @module 类型检查
@@ -476,6 +577,7 @@ declare function formatHumanReadable(date: Date | string | number): string;
  * 检查值是否为字符串类型
  * @param val 要检查的值
  * @returns 如果是字符串则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isString('hello') // true
@@ -488,6 +590,7 @@ declare function isString(val: unknown): val is string;
  * 检查值是否为数字类型
  * @param val 要检查的值
  * @returns 如果是数字则返回 true，否则返回 false（NaN 会返回 false）
+ * @group Is
  * @example
  * ```ts
  * isNumber(123) // true
@@ -502,6 +605,7 @@ declare function isNumber(val: unknown): val is number;
  * 检查值是否为布尔类型
  * @param val 要检查的值
  * @returns 如果是布尔值则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isBoolean(true) // true
@@ -516,6 +620,7 @@ declare function isBoolean(val: unknown): val is boolean;
  * 检查值是否为函数类型
  * @param val 要检查的值
  * @returns 如果是函数则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isFunction(() => {}) // true
@@ -530,6 +635,7 @@ declare function isFunction(val: unknown): val is ((...args: any[]) => any);
  * 检查值是否为对象类型（不包括 null）
  * @param val 要检查的值
  * @returns 如果是对象则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isObject({}) // true
@@ -545,6 +651,7 @@ declare function isObject(val: unknown): val is Record<any, any>;
  * 检查值是否为数组类型
  * @param val 要检查的值
  * @returns 如果是数组则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isArray([]) // true
@@ -559,6 +666,7 @@ declare function isArray(val: unknown): val is any[];
  * 检查值是否为日期类型
  * @param val 要检查的值
  * @returns 如果是日期对象则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isDate(new Date()) // true
@@ -571,6 +679,7 @@ declare function isDate(val: unknown): val is Date;
  * 检查值是否为正则表达式
  * @param val 要检查的值
  * @returns 如果是正则表达式则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isRegExp(/abc/) // true
@@ -584,6 +693,7 @@ declare function isRegExp(val: unknown): val is RegExp;
  * 检查值是否为 Promise
  * @param val 要检查的值
  * @returns 如果是 Promise 则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isPromise(Promise.resolve()) // true
@@ -598,6 +708,7 @@ declare function isPromise<T = any>(val: unknown): val is Promise<T>;
  * 检查值是否为 Map
  * @param val 要检查的值
  * @returns 如果是 Map 则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isMap(new Map()) // true
@@ -610,6 +721,7 @@ declare function isMap<K = any, V = any>(val: unknown): val is Map<K, V>;
  * 检查值是否为 Set
  * @param val 要检查的值
  * @returns 如果是 Set 则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isSet(new Set()) // true
@@ -622,6 +734,7 @@ declare function isSet<T = any>(val: unknown): val is Set<T>;
  * 检查值是否为 Symbol
  * @param val 要检查的值
  * @returns 如果是 Symbol 则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isSymbol(Symbol('foo')) // true
@@ -634,6 +747,7 @@ declare function isSymbol(val: unknown): val is symbol;
  * 检查值是否为原始类型（string、number、boolean、symbol、bigint、null、undefined）
  * @param val 要检查的值
  * @returns 如果是原始类型则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isPrimitive('hello') // true
@@ -653,6 +767,7 @@ declare function isPrimitive(val: unknown): boolean;
  * 检查值是否为 undefined
  * @param val 要检查的值
  * @returns 如果是 undefined 则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isUndefined(undefined) // true
@@ -666,6 +781,7 @@ declare function isUndefined(val: unknown): val is undefined;
  * 检查值是否为 null
  * @param val 要检查的值
  * @returns 如果是 null 则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isNull(null) // true
@@ -679,6 +795,7 @@ declare function isNull(val: unknown): val is null;
  * 检查值是否为 null 或 undefined
  * @param val 要检查的值
  * @returns 如果是 null 或 undefined 则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isNullOrUndefined(null) // true
@@ -693,6 +810,7 @@ declare function isNullOrUndefined(val: unknown): val is null | undefined;
  * 检查对象是否为空对象（没有自身可枚举属性）
  * @param val 要检查的值
  * @returns 如果是空对象则返回 true，否则返回 false；如果不是对象类型则返回 false
+ * @group Is
  * @example
  * ```ts
  * isEmptyObject({}) // true
@@ -708,6 +826,7 @@ declare function isEmptyObject(val: unknown): boolean;
  * 检查值是否为空（null、undefined、空字符串、空数组或空对象）
  * @param val 要检查的值
  * @returns 如果是空值则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isEmpty(null) // true
@@ -726,6 +845,7 @@ declare function isEmpty(val: unknown): boolean;
  * 检查值是否为 NaN
  * @param value 要检查的值
  * @returns 如果值是 NaN 则返回 true，否则返回 false
+ * @group Is
  * @example
  * ```ts
  * isNaN(NaN) // true
@@ -742,6 +862,7 @@ declare function isNaN(value: unknown): boolean;
  * @param {unknown} value - 要检查的值
  * @returns {boolean} 如果值是普通对象则返回 true，否则返回 false
  *
+ * @group Is
  * @example
  * ```ts
  * isPlainObject({}) // true
@@ -762,6 +883,7 @@ declare function isPlainObject(value: unknown): value is Record<string, any>;
  * @param num 要处理的数字
  * @param precision 小数位数，默认为0（整数）
  * @returns 四舍五入后的数字
+ * @group Number
  * @example
  * ```ts
  * round(3.1415) // 3
@@ -776,6 +898,7 @@ declare function round(num: number, precision?: number): number;
  * @param num 要格式化的数字
  * @param locale 区域设置，默认为浏览器默认区域
  * @returns 格式化后的字符串
+ * @group Number
  * @example
  * ```ts
  * formatThousands(1234567) // '1,234,567'（根据浏览器默认区域可能有所不同）
@@ -793,6 +916,7 @@ declare function formatThousands(num: number, locale?: string): string;
  * @param options.minimumFractionDigits 最小小数位数，默认为 2
  * @param options.maximumFractionDigits 最大小数位数，默认为 2
  * @returns 格式化后的货币字符串
+ * @group Number
  * @example
  * ```ts
  * formatCurrency(1234.56) // '¥1,234.56'
@@ -813,6 +937,7 @@ declare function formatCurrency(value: number, options?: {
  * @param min 最小值
  * @param max 最大值
  * @returns 在指定范围内的数字：如果小于最小值返回最小值，如果大于最大值返回最大值
+ * @group Number
  * @example
  * ```ts
  * clamp(5, 0, 10) // 5 - 在范围内，保持不变
@@ -826,6 +951,7 @@ declare function clamp(num: number, min: number, max: number): number;
  * @param min 最小值（包含）
  * @param max 最大值（包含）
  * @returns 指定范围内的随机整数
+ * @group Number
  * @example
  * ```ts
  * randomInt(1, 10) // 返回 1 到 10 之间的随机整数，包括 1 和 10
@@ -838,6 +964,7 @@ declare function randomInt(min: number, max: number): number;
  * 检查一个数字是否为偶数
  * @param num 要检查的数字
  * @returns 如果是偶数则返回 true，否则返回 false
+ * @group Number
  * @example
  * ```ts
  * isEven(2) // true
@@ -851,6 +978,7 @@ declare function isEven(num: number): boolean;
  * 检查一个数字是否为奇数
  * @param num 要检查的数字
  * @returns 如果是奇数则返回 true，否则返回 false
+ * @group Number
  * @example
  * ```ts
  * isOdd(3) // true
@@ -866,6 +994,7 @@ declare function isOdd(num: number): boolean;
  * @param total 总值
  * @param precision 结果保留的小数位数，默认为2
  * @returns 百分比值，如果总值为零则返回 0
+ * @group Number
  * @example
  * ```ts
  * percentage(25, 100) // 25
@@ -880,6 +1009,7 @@ declare function percentage(value: number, total: number, precision?: number): n
  * @param num 要转换的数值
  * @param fractionDigits 小数位数，默认为2
  * @returns 转换后的字符串，如果值大于等于10000则转为"万"单位
+ * @group Number
  * @example
  * ```ts
  * formatNumberWithTenThousand(1234) // '1234'
@@ -900,7 +1030,7 @@ declare function formatNumberWithTenThousand(num: number, fractionDigits?: numbe
  * @param {object} obj - 需要检查的对象
  * @param {string | symbol} prop - 需要检查的属性键
  * @returns {boolean} 如果对象具有该自有属性，则返回 true，否则返回 false
- *
+ * @group Object
  * @example
  * ```ts
  * const obj = { name: 'Tom', age: 25 }
@@ -913,6 +1043,7 @@ declare function hasOwnProp(obj: object, prop: string | symbol): boolean;
  * 深拷贝对象，支持基本类型、数组、对象、日期和正则表达式
  * @param obj 要拷贝的对象
  * @returns 深拷贝后的对象，与原对象完全独立
+ * @group Object
  * @example
  * ```ts
  * const original = { a: 1, b: { c: 2 }, d: [1, 2, 3], e: new Date() }
@@ -933,6 +1064,7 @@ declare function deepClone<T>(obj: T): T;
  * @param path 属性路径，如 'user.address.street'
  * @param defaultValue 默认值，当路径不存在时返回
  * @returns 路径对应的值，如果路径不存在则返回默认值
+ * @group Object
  * @example
  * ```ts
  * const obj = { user: { profile: { name: 'Tom', age: 25 }, roles: ['admin'] } }
@@ -950,10 +1082,13 @@ declare function get<T = any>(obj: Record<string, any>, path: string, defaultVal
  * @param obj 原始对象
  * @param keys 要选择的键数组
  * @returns 包含指定键的新对象
+ * @group Object
  * @example
  * ```ts
+ * @group Object
  * const user = { id: 1, name: 'Tom', age: 25, email: 'tom@example.com' }
  *
+ * @group Object
  * pick(user, ['name', 'email']) // { name: 'Tom', email: 'tom@example.com' }
  * pick(user, ['name', 'gender']) // { name: 'Tom' }（不存在的键会被忽略）
  * pick(user, []) // {}（空数组返回空对象）
@@ -965,6 +1100,7 @@ declare function pick<T extends Record<string, any>, K extends keyof T>(obj: T,
  * @param obj 原始对象
  * @param keys 要排除的键数组
  * @returns 不包含指定键的新对象
+ * @group Object
  * @example
  * ```ts
  * const user = { id: 1, name: 'Tom', age: 25, password: '123456' }
@@ -979,6 +1115,7 @@ declare function omit<T extends Record<string, any>, K extends keyof T>(obj: T,
  * 将对象转换为 URL 查询字符串
  * @param obj 要转换的对象
  * @returns 格式化后的查询字符串（不包含前导?）
+ * @group Object
  * @example
  * ```ts
  * objectToQueryString({ name: 'Tom', age: 25 }) // 'name=Tom&age=25'
@@ -992,6 +1129,7 @@ declare function objectToQueryString(obj: Record<string, any>): string;
  * 合并多个对象，后面的对象的属性会覆盖前面的
  * @param objects 要合并的对象数组
  * @returns 合并后的新对象
+ * @group Object
  * @example
  * ```ts
  * merge({ a: 1 }, { b: 2 }) // { a: 1, b: 2 }
@@ -1005,6 +1143,7 @@ declare function merge<T extends Record<string, any>>(...objects: T[]): T;
  * 深度合并多个对象，会递归合并嵌套对象
  * @param objects 要合并的对象数组
  * @returns 深度合并后的新对象
+ * @group Object
  * @example
  * ```ts
  * deepMerge({ a: { x: 1 } }, { a: { y: 2 } }) // { a: { x: 1, y: 2 } }
@@ -1020,6 +1159,7 @@ declare function deepMerge(...objects: Record<string, any>[]): Record<string, an
  * @param keysArray 要保留的键名数组
  * @param keyMapping 可选的键名映射对象，格式为 { 原键名: 新键名 }
  * @returns 返回一个新对象，其中只包含原对象中匹配的键值对，并根据映射重命名键
+ * @group Object
  * @example
  * ```ts
  * const originalObject = { name: "John", age: 30, gender: "male", country: "USA" }
@@ -1036,7 +1176,7 @@ declare function filterObjectByKeys(originalObject: Record<string, any>, keysArr
  *
  * @param {number} ms - 需要延迟的毫秒数
  * @returns {Promise<void>} 返回一个在指定时间后resolve的Promise
- *
+ * @group Promise
  * @example
  * ```ts
  * // 延迟2秒
@@ -1060,6 +1200,7 @@ declare function delay(ms: number): Promise<void>;
  * 将字符串首字母转为大写
  * @param str 输入字符串
  * @returns 首字母大写后的字符串
+ * @group String
  * @example
  * ```ts
  * capitalize('hello') // 'Hello'
@@ -1072,6 +1213,7 @@ declare function capitalize(str: string): string;
  * 将驼峰命名转换为短横线命名（kebab-case）
  * @param str 驼峰命名的字符串
  * @returns 短横线命名的字符串
+ * @group String
  * @example
  * ```ts
  * camelToKebab('helloWorld') // 'hello-world'
@@ -1085,6 +1227,7 @@ declare function camelToKebab(str: string): string;
  * 将短横线命名（kebab-case）转换为驼峰命名（camelCase）
  * @param str 短横线命名的字符串
  * @returns 驼峰命名的字符串
+ * @group String
  * @example
  * ```ts
  * kebabToCamel('hello-world') // 'helloWorld'
@@ -1100,6 +1243,7 @@ declare function kebabToCamel(str: string): string;
  * @param length 截取的最大长度，默认为 50
  * @param ellipsis 省略号字符，默认为'...'
  * @returns 截取后的字符串，如果原字符串长度小于等于截取长度，则返回原字符串
+ * @group String
  * @example
  * ```ts
  * truncate('这是一个很长的字符串', 5) // '这是...'
@@ -1113,6 +1257,7 @@ declare function truncate(str: string, length?: number, ellipsis?: string): stri
  * @param length 字符串长度
  * @param chars 可选的字符集，默认包含大小写字母和数字
  * @returns 生成的随机字符串
+ * @group String
  * @example
  * ```ts
  * randomString(5) // 例如: 'aB9cD'
@@ -1125,6 +1270,7 @@ declare function randomString(length: number, chars?: string): string;
  * 将字符串中的 HTML 特殊字符转义，防止 XSS 攻击
  * @param html 包含 HTML 的字符串
  * @returns 转义后的安全字符串
+ * @group String
  * @example
  * ```ts
  * escapeHtml('<div>Hello & World</div>') // '&lt;div&gt;Hello &amp; World&lt;/div&gt;'
@@ -1136,6 +1282,7 @@ declare function escapeHtml(html: string): string;
  * 检查字符串是否为有效的 URL
  * @param url 要检查的 URL 字符串
  * @returns 如果是有效的 URL 则返回 true，否则返回 false
+ * @group String
  * @example
  * ```ts
  * isValidUrl('https://example.com') // true
@@ -1149,9 +1296,12 @@ declare function isValidUrl(url: string): boolean;
  * 检查字符串是否为有效的电子邮件地址
  * @param email 要检查的电子邮件地址
  * @returns 如果是有效的电子邮件地址则返回 true，否则返回 false
+ * @group String
  * @example
  * ```ts
+ * @group String
  * isValidEmail('user@example.com') // true
+ * @group String
  * isValidEmail('user.name+tag@example.co.uk') // true
  * isValidEmail('invalid@email') // false，缺少顶级域名
  * isValidEmail('not an email') // false
@@ -1162,6 +1312,7 @@ declare function isValidEmail(email: string): boolean;
  * 检查字符串是否为空或只包含空白字符
  * @param str 要检查的字符串
  * @returns 如果字符串为空或只包含空白字符，则返回 true
+ * @group String
  * @example
  * ```ts
  * isEmptyString('') // true
@@ -1175,6 +1326,7 @@ declare function isEmptyString(str: string): boolean;
  * 确保值具有 rpx 单位，主要用于小程序/uni-app 样式处理
  * @param val 需要转化的值，可以是数字或字符串
  * @returns 转化后带有 rpx 单位的字符串，如果输入不是数字则原样返回
+ * @group String
  * @example
  * ```ts
  * ensureRpxUnit(100) // '100rpx'
@@ -1185,45 +1337,21 @@ declare function isEmptyString(str: string): boolean;
  */
 declare function ensureRpxUnit(val: string | number): string;
 /**
- * 替换表格数据中指定字段的 &nbsp; 为不换行空格
+ * 替换字符串中的 `&nbsp;` 为不换行空格
  *
- * @param {Array<Record<string, any>>} tableData - 表格数据数组或Vue ref
- * @param {string} key - 需要处理的字段名
- * @returns {Array<Record<string, any>>} 处理后的表格数据数组
+ * @param {string} str - 字符串
+ * @returns {string} 处理后的字符串
  *
+ * @group String
  * @example
  * ```ts
  * // 基本用法
- * const data = [
- *   { name: 'John&nbsp;Doe', age: 30 },
- *   { name: 'Jane&nbsp;&nbsp;Smith', age: 25 }
- * ]
- * const result = replaceNBSP(data, 'name')
- * // 结果: [
- * //   { name: 'John  Doe', age: 30 },
- * //   { name: 'Jane    Smith', age: 25 }
- * // ]
- *
- * // 使用ref包装的数据 (在Vue中使用)
- * const refData = ref([
- *   { desc: 'Product&nbsp;Info', price: 99 },
- *   { desc: 'Service&nbsp;&nbsp;Details', price: 50 }
- * ])
- * const result = replaceNBSP(refData, 'desc')
- * // 结果: [
- * //   { desc: 'Product  Info', price: 99 },
- * //   { desc: 'Service    Details', price: 50 }
- * // ]
- *
- * // 空数组情况
- * const emptyData = []
- * const result = replaceNBSP(emptyData, 'name')
- * // 结果: []
+ * replaceNBSP('John&nbsp;Doe') // 'John Doe'
+ * replaceNBSP('Jane&nbsp;&nbsp;Smith') // 'Jane  Smith'
+ * replaceNBSP('Smith') // 'Smith'
  * ```
  */
-declare function replaceNBSP<T extends Record<string, string | number | boolean | object>>(tableData: T[] | {
-    value: T[];
-}, key: string): T[];
+declare function replaceNBSP(str?: string): string;
 
 /**
  * 将对象转换为URL查询字符串
@@ -1231,7 +1359,7 @@ declare function replaceNBSP<T extends Record<string, string | number | boolean
  * @deprecated 请使用 objectToQueryString 函数代替，它在 object 模块中。该函数将在下一个主要版本中移除。
  * @param {Record<string, any>} params - 需要转换的对象
  * @returns {string} 转换后的查询字符串，如果有参数则以?开头
- *
+ * @group Url
  * @example
  * ```ts
  * // 基本用法
@@ -1253,4 +1381,4 @@ declare function replaceNBSP<T extends Record<string, string | number | boolean
  */
 declare function getQueryStringify(params: Record<string, any> | null | undefined): string;
 
-export { add, addDays, addMonths, addYears, appendUniversalOption, arrayToObject, camelToKebab, capitalize, chunk, clamp, createDate, deepClone, deepMerge, delay, diff, endOf, ensureRpxUnit, escapeHtml, filterObjectByKeys, first, formatCurrency, formatDate, formatHumanReadable, formatNumberWithTenThousand, formatThousands, fromNow, get, getDayOfWeek, getDaysInMonth, getQueryStringify, groupBy, hasOwnProp, isArray, isBoolean, isDate, isDateInRange, isEmpty, isEmptyObject, isEmptyString, isEqual, isEven, isFunction, isMap, isNaN, isNull, isNullOrUndefined, isNumber, isObject, isOdd, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isString, isSymbol, isUndefined, isValidEmail, isValidUrl, kebabToCamel, last, merge, now, objectToQueryString, omit, parseDate, percentage, pick, randomInt, randomString, remove, renameTreeNodes, replaceNBSP, round, sample, shuffle, startOf, transformTree, truncate, unique };
+export { type DateLike, add, addDays, addMonths, addYears, appendUniversalOption, arrayReplaceNBSP, arrayToObject, camelToKebab, capitalize, chunk, clamp, convertToDayjsParam, createDate, deepClone, deepMerge, delay, diff, endOf, ensureRpxUnit, escapeHtml, filterObjectByKeys, first, formatCurrency, formatDate, formatFullTime, formatHumanReadable, formatNumberWithTenThousand, formatThousands, fromNow, get, getDayOfWeek, getDaysInMonth, getQueryStringify, groupBy, hasOwnProp, isArray, isBoolean, isDate, isDateInRange, isEmpty, isEmptyObject, isEmptyString, isEqual, isEven, isFunction, isMap, isMillisecondTimestamp, isNaN, isNull, isNullOrUndefined, isNumber, isObject, isOdd, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isString, isSymbol, isUndefined, isValidEmail, isValidUrl, kebabToCamel, last, merge, now, objectToQueryString, omit, parseDate, percentage, pick, randomInt, randomString, remove, renameTreeNodes, replaceNBSP, round, sample, shuffle, startOf, transformTree, truncate, unique };