a2bei4-utils 1.0.3 → 1.0.5

package/types/date.d.ts

@@ -19,60 +19,119 @@ declare function toDate(val: any): Date | null;
  */
 declare function randomDateInRange(date1: Date, date2: Date): Date;
 /**
- * 计算两个时间之间的剩余/已过时长（天-时-分-秒），返回带补零的展示对象。
- *
- * @param {string|number|Date} originalTime - 原始时间（可转 Date 的任意值）
- * @param {Date} [currentTime=new Date()] - 基准时间，默认当前
- * @returns {{days:number,hours:string,minutes:string,seconds:string}}
+ * 时间持续对象（完整版本，包含年月日时分秒毫秒）
+ * @typedef {Object} DurationObject
+ * @property {number} years - 年数
+ * @property {number} months - 月数（0-11）
+ * @property {number} days - 天数（0-29，取决于 monthDays）
+ * @property {number} hours - 小时数（0-23）
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
  */
-declare function calcTimeDifference(originalTime: string | number | Date, currentTime?: Date): {
-    days: number;
-    hours: string;
-    minutes: string;
-    seconds: string;
-};
 /**
- * 将总秒数格式化成人类可读的时间段文本。
- * 固定进制：1 年=365 天，1 月=30 天。
- *
- * @param {number} totalSeconds - 非负总秒数
- * @param {object} [options] - 格式化选项
- * @param {Partial<{year:string,month:string,day:string,hour:string,minute:string,second:string}>} [options.labels] - 各单位的自定义文本
- * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.maxUnit] - 最大输出单位
- * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.minUnit] - 最小输出单位
- * @param {boolean} [options.showZero] - 是否强制显示 0 秒
- * @returns {string} 拼接后的时长文本，如“1天 02小时 30分钟”
- * @throws {TypeError} 当 totalSeconds 为非数字或负数时抛出
- */
-declare function formatDuration(totalSeconds: number, options?: {
-    labels?: Partial<{
-        year: string;
-        month: string;
-        day: string;
-        hour: string;
-        minute: string;
-        second: string;
-    }> | undefined;
-    maxUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
-    minUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
-    showZero?: boolean | undefined;
-}): string;
+ * 时间持续对象（最大单位为天）
+ * @typedef {Object} DurationMaxDayObject
+ * @property {number} days - 天数
+ * @property {number} hours - 小时数（0-23）
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
+ */
+/**
+ * 时间持续对象（最大单位为小时）
+ * @typedef {Object} DurationMaxHourObject
+ * @property {number} hours - 小时数
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
+ */
 /**
- * 快捷调用 {@link formatDuration}，最大单位到“天”。
+ * 将毫秒转换为时间持续对象。
  *
- * @param {number} totalSeconds
- * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
- * @returns {string}
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @param {Object} [options] - 选项对象。
+ * @param {number} [options.yearDays=365] - 一年的天数。
+ * @param {number} [options.monthDays=30] - 一月的天数。
+ * @returns {DurationObject} 时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字
+ * @throws {RangeError} 当 milliseconds 为负数
+ * @throws {RangeError} 当 yearDays 或 monthDays 不是正整数
+ *
+ * @example
+ * // 基本用法
+ * millisecond2Duration(42070000500);
+ * // 返回: { years: 1, months: 4, days: 1, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ */
+declare function millisecond2Duration(milliseconds: number, options?: {
+    yearDays?: number | undefined;
+    monthDays?: number | undefined;
+}): DurationObject;
+/**
+ * 将毫秒转换为时间持续对象（最大单位为天）。
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @returns {DurationMaxDayObject} 包含天、小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+ * @throws {RangeError} 当 milliseconds 为负数时抛出
+ * @example
+ * // 返回 { days: 486, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ * millisecond2DurationMaxDay(42070000500);
  */
-declare function formatDurationMaxDay(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+declare function millisecond2DurationMaxDay(milliseconds: number): DurationMaxDayObject;
 /**
- * 快捷调用 {@link formatDuration}，最大单位到“小时”。
+ * 将毫秒转换为时间持续对象（最大单位为小时）。
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+ * @throws {RangeError} 当 milliseconds 为负数时抛出
+ * @example
+ * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+ * millisecond2DurationMaxHour(42070000500);
+ */
+declare function millisecond2DurationMaxHour(milliseconds: number): DurationMaxHourObject;
+/**
+ * 将秒转换为时间持续对象。
+ *
+ * @param {number} seconds - 秒数（非负整数）
+ * @param {Object} [options] - 选项对象。
+ * @param {number} [options.yearDays=365] - 一年的天数。
+ * @param {number} [options.monthDays=30] - 一月的天数。
+ * @returns {DurationObject} 时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字
+ * @throws {RangeError} 当 seconds 为负数
+ * @throws {RangeError} 当 yearDays 或 monthDays 不是正整数
  *
- * @param {number} totalSeconds
- * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
- * @returns {string}
+ * @example
+ * // 基本用法
+ * second2Duration(42070000.5);
+ * // 返回: { years: 1, months: 4, days: 1, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
  */
-declare function formatDurationMaxHour(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+declare function second2Duration(seconds: number, options?: {
+    yearDays?: number | undefined;
+    monthDays?: number | undefined;
+}): DurationObject;
+/**
+ * 将秒转换为时间持续对象（最大单位为天）。
+ * @param {number} seconds - 秒数（非负整数）
+ * @returns {DurationMaxDayObject} 包含天、小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字时抛出
+ * @throws {RangeError} 当 seconds 为负数时抛出
+ * @example
+ * // 返回 { days: 486, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ * second2DurationMaxDay(42070000.5);
+ */
+declare function second2DurationMaxDay(seconds: number): DurationMaxDayObject;
+/**
+ * 将秒转换为时间持续对象（最大单位为小时）。
+ * @param {number} seconds - 秒数（非负整数）
+ * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字时抛出
+ * @throws {RangeError} 当 seconds 为负数时抛出
+ * @example
+ * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+ * second2DurationMaxHour(42070000.5);
+ */
+declare function second2DurationMaxHour(seconds: number): DurationMaxHourObject;
 /**
  * 根据小时数返回对应的时间段名称。
  *
@@ -132,5 +191,85 @@ declare function formatTimeForLocale(timestamp: number, locales?: {
     } | undefined;
     weekDays?: string[] | undefined;
 }): string;
+/**
+ * 时间持续对象（完整版本，包含年月日时分秒毫秒）
+ */
+type DurationObject = {
+    /**
+     * - 年数
+     */
+    years: number;
+    /**
+     * - 月数（0-11）
+     */
+    months: number;
+    /**
+     * - 天数（0-29，取决于 monthDays）
+     */
+    days: number;
+    /**
+     * - 小时数（0-23）
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
+/**
+ * 时间持续对象（最大单位为天）
+ */
+type DurationMaxDayObject = {
+    /**
+     * - 天数
+     */
+    days: number;
+    /**
+     * - 小时数（0-23）
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
+/**
+ * 时间持续对象（最大单位为小时）
+ */
+type DurationMaxHourObject = {
+    /**
+     * - 小时数
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
 
-export { calcTimeDifference, formatDuration, formatDurationMaxDay, formatDurationMaxHour, formatTimeForLocale, getTimePeriodName, randomDateInRange, toDate };
+export { formatTimeForLocale, getTimePeriodName, millisecond2Duration, millisecond2DurationMaxDay, millisecond2DurationMaxHour, randomDateInRange, second2Duration, second2DurationMaxDay, second2DurationMaxHour, toDate };
+export type { DurationMaxDayObject, DurationMaxHourObject, DurationObject };

package/types/index.d.ts

@@ -1,3 +1,64 @@
+/**
+ * 处理数据库菜单项，生成 UI 菜单树和路由配置。
+ *
+ * @param {Array<Object>} menuItems - 原始菜单项数组，树形结构
+ * @param {Object} [options] - 配置选项
+ * @param {string} [options.idKey='id'] - 数据源 ID 键名
+ * @param {string} [options.codeKey='code'] - 数据源编码键名, 用于拼接路由名称和路由路径
+ * @param {string} [options.labelKey='text'] - 数据源标签键名
+ * @param {string} [options.childrenKey='children'] - 数据源子节点键名
+ * @param {string} [options.extendKey='extend'] - 数据源扩展对象键名
+ * @param {string} [options.menuIdKey='key'] - 输出菜单 ID 键名
+ * @param {string} [options.menuLabelKey='label'] - 输出菜单标签键名
+ * @param {string} [options.menuChildrenKey='children'] - 输出菜单子节点键名
+ * @param {string} [options.menuExtendKey='extend'] - 输出菜单扩展对象键名
+ * @param {string} [options.routeNameKey='name'] - 路由名称键名
+ * @param {string} [options.routePathKey='path'] - 路由路径键名
+ * @param {string} [options.routeMetaKey='meta'] - 路由元数据键名
+ * @param {Function} [options.handleNodeItem] - 节点处理钩子，参数：(nodeSimple) => void
+ * @param {Function} [options.handleMenuItem] - 菜单项处理钩子，参数：(uiMenuItem, nodeSimple) => void
+ * @param {Function} [options.handleRouteItem] - 路由项处理钩子，参数：(routeItem, nodeSimple) => void
+ *
+ * @returns {Object} 处理结果
+ * @returns {Array<Object>} returns.uiMenuItems - UI 菜单树形结构数组
+ * @returns {Array<Object>} returns.routeItems - 扁平化路由配置数组
+ * @returns {Map<string, Object>} returns.nodeMap - 节点 ID 到节点数据的映射表
+ *
+ * @example
+ * const menuItems = [
+ *   { id: '1', code: 'system', text: '系统管理', children: [
+ *     { id: '1-1', code: 'user', text: '用户管理' }
+ *   ]}
+ * ];
+ *
+ * const result = handleDbMenuItems(menuItems, {
+ *   handleRouteItem: (route, node) => {
+ *     route.component = () => import(`./views/${node.code}.vue`);
+ *   }
+ * });
+ *
+ * // result.uiMenuItems: [{ key: '1', label: '系统管理', children: [...] }]
+ * // result.routeItems: [{ name: 'system.user', path: '/system/user', meta: { id: '1-1' } }]
+ * // result.nodeMap: Map { '1' => {...}, '1-1' => {...} }
+ */
+declare function handleDbMenuItems(menuItems: Array<Object>, options?: {
+    idKey?: string | undefined;
+    codeKey?: string | undefined;
+    labelKey?: string | undefined;
+    childrenKey?: string | undefined;
+    extendKey?: string | undefined;
+    menuIdKey?: string | undefined;
+    menuLabelKey?: string | undefined;
+    menuChildrenKey?: string | undefined;
+    menuExtendKey?: string | undefined;
+    routeNameKey?: string | undefined;
+    routePathKey?: string | undefined;
+    routeMetaKey?: string | undefined;
+    handleNodeItem?: Function | undefined;
+    handleMenuItem?: Function | undefined;
+    handleRouteItem?: Function | undefined;
+}): Object;
+
 /**
  * 基于 `setTimeout` 的“间隔循环”定时器。
  * 每次任务执行完成后才计算下一次间隔，避免任务堆积。
@@ -464,60 +525,119 @@ declare function toDate(val: any): Date | null;
  */
 declare function randomDateInRange(date1: Date, date2: Date): Date;
 /**
- * 计算两个时间之间的剩余/已过时长（天-时-分-秒），返回带补零的展示对象。
+ * 时间持续对象（完整版本，包含年月日时分秒毫秒）
+ * @typedef {Object} DurationObject
+ * @property {number} years - 年数
+ * @property {number} months - 月数（0-11）
+ * @property {number} days - 天数（0-29，取决于 monthDays）
+ * @property {number} hours - 小时数（0-23）
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
+ */
+/**
+ * 时间持续对象（最大单位为天）
+ * @typedef {Object} DurationMaxDayObject
+ * @property {number} days - 天数
+ * @property {number} hours - 小时数（0-23）
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
+ */
+/**
+ * 时间持续对象（最大单位为小时）
+ * @typedef {Object} DurationMaxHourObject
+ * @property {number} hours - 小时数
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
+ */
+/**
+ * 将毫秒转换为时间持续对象。
+ *
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @param {Object} [options] - 选项对象。
+ * @param {number} [options.yearDays=365] - 一年的天数。
+ * @param {number} [options.monthDays=30] - 一月的天数。
+ * @returns {DurationObject} 时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字
+ * @throws {RangeError} 当 milliseconds 为负数
+ * @throws {RangeError} 当 yearDays 或 monthDays 不是正整数
  *
- * @param {string|number|Date} originalTime - 原始时间（可转 Date 的任意值）
- * @param {Date} [currentTime=new Date()] - 基准时间，默认当前
- * @returns {{days:number,hours:string,minutes:string,seconds:string}}
+ * @example
+ * // 基本用法
+ * millisecond2Duration(42070000500);
+ * // 返回: { years: 1, months: 4, days: 1, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ */
+declare function millisecond2Duration(milliseconds: number, options?: {
+    yearDays?: number | undefined;
+    monthDays?: number | undefined;
+}): DurationObject;
+/**
+ * 将毫秒转换为时间持续对象（最大单位为天）。
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @returns {DurationMaxDayObject} 包含天、小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+ * @throws {RangeError} 当 milliseconds 为负数时抛出
+ * @example
+ * // 返回 { days: 486, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ * millisecond2DurationMaxDay(42070000500);
  */
-declare function calcTimeDifference(originalTime: string | number | Date, currentTime?: Date): {
-    days: number;
-    hours: string;
-    minutes: string;
-    seconds: string;
-};
+declare function millisecond2DurationMaxDay(milliseconds: number): DurationMaxDayObject;
 /**
- * 将总秒数格式化成人类可读的时间段文本。
- * 固定进制：1 年=365 天，1 月=30 天。
- *
- * @param {number} totalSeconds - 非负总秒数
- * @param {object} [options] - 格式化选项
- * @param {Partial<{year:string,month:string,day:string,hour:string,minute:string,second:string}>} [options.labels] - 各单位的自定义文本
- * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.maxUnit] - 最大输出单位
- * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.minUnit] - 最小输出单位
- * @param {boolean} [options.showZero] - 是否强制显示 0 秒
- * @returns {string} 拼接后的时长文本，如“1天 02小时 30分钟”
- * @throws {TypeError} 当 totalSeconds 为非数字或负数时抛出
- */
-declare function formatDuration(totalSeconds: number, options?: {
-    labels?: Partial<{
-        year: string;
-        month: string;
-        day: string;
-        hour: string;
-        minute: string;
-        second: string;
-    }> | undefined;
-    maxUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
-    minUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
-    showZero?: boolean | undefined;
-}): string;
+ * 将毫秒转换为时间持续对象（最大单位为小时）。
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+ * @throws {RangeError} 当 milliseconds 为负数时抛出
+ * @example
+ * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+ * millisecond2DurationMaxHour(42070000500);
+ */
+declare function millisecond2DurationMaxHour(milliseconds: number): DurationMaxHourObject;
 /**
- * 快捷调用 {@link formatDuration}，最大单位到“天”。
+ * 将秒转换为时间持续对象。
  *
- * @param {number} totalSeconds
- * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
- * @returns {string}
+ * @param {number} seconds - 秒数（非负整数）
+ * @param {Object} [options] - 选项对象。
+ * @param {number} [options.yearDays=365] - 一年的天数。
+ * @param {number} [options.monthDays=30] - 一月的天数。
+ * @returns {DurationObject} 时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字
+ * @throws {RangeError} 当 seconds 为负数
+ * @throws {RangeError} 当 yearDays 或 monthDays 不是正整数
+ *
+ * @example
+ * // 基本用法
+ * second2Duration(42070000.5);
+ * // 返回: { years: 1, months: 4, days: 1, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ */
+declare function second2Duration(seconds: number, options?: {
+    yearDays?: number | undefined;
+    monthDays?: number | undefined;
+}): DurationObject;
+/**
+ * 将秒转换为时间持续对象（最大单位为天）。
+ * @param {number} seconds - 秒数（非负整数）
+ * @returns {DurationMaxDayObject} 包含天、小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字时抛出
+ * @throws {RangeError} 当 seconds 为负数时抛出
+ * @example
+ * // 返回 { days: 486, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ * second2DurationMaxDay(42070000.5);
  */
-declare function formatDurationMaxDay(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+declare function second2DurationMaxDay(seconds: number): DurationMaxDayObject;
 /**
- * 快捷调用 {@link formatDuration}，最大单位到“小时”。
- *
- * @param {number} totalSeconds
- * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
- * @returns {string}
+ * 将秒转换为时间持续对象（最大单位为小时）。
+ * @param {number} seconds - 秒数（非负整数）
+ * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字时抛出
+ * @throws {RangeError} 当 seconds 为负数时抛出
+ * @example
+ * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+ * second2DurationMaxHour(42070000.5);
  */
-declare function formatDurationMaxHour(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+declare function second2DurationMaxHour(seconds: number): DurationMaxHourObject;
 /**
  * 根据小时数返回对应的时间段名称。
  *
@@ -577,6 +697,85 @@ declare function formatTimeForLocale(timestamp: number, locales?: {
     } | undefined;
     weekDays?: string[] | undefined;
 }): string;
+/**
+ * 时间持续对象（完整版本，包含年月日时分秒毫秒）
+ */
+type DurationObject = {
+    /**
+     * - 年数
+     */
+    years: number;
+    /**
+     * - 月数（0-11）
+     */
+    months: number;
+    /**
+     * - 天数（0-29，取决于 monthDays）
+     */
+    days: number;
+    /**
+     * - 小时数（0-23）
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
+/**
+ * 时间持续对象（最大单位为天）
+ */
+type DurationMaxDayObject = {
+    /**
+     * - 天数
+     */
+    days: number;
+    /**
+     * - 小时数（0-23）
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
+/**
+ * 时间持续对象（最大单位为小时）
+ */
+type DurationMaxHourObject = {
+    /**
+     * - 小时数
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
 
 /**
  * 通过动态创建 `<a>` 标签触发浏览器下载。
@@ -743,6 +942,18 @@ declare function flatCompleteTree2NestedTree<T>(nodes: T[], parentId?: number |
     parentKey?: string | undefined;
     childrenKey?: string | undefined;
 }): (T & { [k in typeof childrenKey]: T[]; })[];
+/**
+ * 在嵌套树中按 `id` 递归查找节点，并返回其指定属性值。
+ *
+ * @template T extends Record<PropertyKey, any>
+ * @param {string | number} id - 要查找的 id
+ * @param {T[]} arr - 嵌套树森林
+ * @param {string} [resultKey='name'] - 需要返回的字段
+ * @param {string} [idKey='id'] - 主键字段
+ * @param {string} [childrenKey='children'] - 子节点字段
+ * @returns {any} 找到的值；未找到返回 `undefined`
+ */
+declare function findObjAttrValueById<T>(id: string | number, arr: T[], resultKey?: string, idKey?: string, childrenKey?: string): any;
 /**
  * 从服务端返回的已选 id 数组里，提取出
  * 1. 叶子节点
@@ -759,6 +970,6 @@ declare function extractFullyCheckedKeys(treeData: any[], selectedKeys: any[], i
     checked: string[];
     halfChecked: string[];
 };
-declare function findObjAttrValueById<T>(id: string | number, arr: T[], resultKey?: string, idKey?: string, childrenKey?: string): any;
+declare function findTreeNodeById<T>(id: string | number, arr: T[], idKey?: string, childrenKey?: string): any;
 
-export { AudioStreamResampler, IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, WebSocketManager, assignExisting, calcTimeDifference, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, extractFullyCheckedKeys, fetchOrDownloadByUrl, findObjAttrValueById, flatCompleteTree2NestedTree, formatDuration, formatDurationMaxDay, formatDurationMaxHour, formatTimeForLocale, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getTimePeriodName, getViewportSize, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, moveItem, nestedTree2IdMap, pcmToWavBlob, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, shuffle, throttle, toDate };
+export { AudioStreamResampler, IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, WebSocketManager, assignExisting, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, extractFullyCheckedKeys, fetchOrDownloadByUrl, findObjAttrValueById, findTreeNodeById, flatCompleteTree2NestedTree, formatTimeForLocale, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getTimePeriodName, getViewportSize, handleDbMenuItems, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, millisecond2Duration, millisecond2DurationMaxDay, millisecond2DurationMaxHour, moveItem, nestedTree2IdMap, pcmToWavBlob, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, second2Duration, second2DurationMaxDay, second2DurationMaxHour, shuffle, throttle, toDate };

package/types/menu.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 处理数据库菜单项，生成 UI 菜单树和路由配置。
+ *
+ * @param {Array<Object>} menuItems - 原始菜单项数组，树形结构
+ * @param {Object} [options] - 配置选项
+ * @param {string} [options.idKey='id'] - 数据源 ID 键名
+ * @param {string} [options.codeKey='code'] - 数据源编码键名, 用于拼接路由名称和路由路径
+ * @param {string} [options.labelKey='text'] - 数据源标签键名
+ * @param {string} [options.childrenKey='children'] - 数据源子节点键名
+ * @param {string} [options.extendKey='extend'] - 数据源扩展对象键名
+ * @param {string} [options.menuIdKey='key'] - 输出菜单 ID 键名
+ * @param {string} [options.menuLabelKey='label'] - 输出菜单标签键名
+ * @param {string} [options.menuChildrenKey='children'] - 输出菜单子节点键名
+ * @param {string} [options.menuExtendKey='extend'] - 输出菜单扩展对象键名
+ * @param {string} [options.routeNameKey='name'] - 路由名称键名
+ * @param {string} [options.routePathKey='path'] - 路由路径键名
+ * @param {string} [options.routeMetaKey='meta'] - 路由元数据键名
+ * @param {Function} [options.handleNodeItem] - 节点处理钩子，参数：(nodeSimple) => void
+ * @param {Function} [options.handleMenuItem] - 菜单项处理钩子，参数：(uiMenuItem, nodeSimple) => void
+ * @param {Function} [options.handleRouteItem] - 路由项处理钩子，参数：(routeItem, nodeSimple) => void
+ *
+ * @returns {Object} 处理结果
+ * @returns {Array<Object>} returns.uiMenuItems - UI 菜单树形结构数组
+ * @returns {Array<Object>} returns.routeItems - 扁平化路由配置数组
+ * @returns {Map<string, Object>} returns.nodeMap - 节点 ID 到节点数据的映射表
+ *
+ * @example
+ * const menuItems = [
+ *   { id: '1', code: 'system', text: '系统管理', children: [
+ *     { id: '1-1', code: 'user', text: '用户管理' }
+ *   ]}
+ * ];
+ *
+ * const result = handleDbMenuItems(menuItems, {
+ *   handleRouteItem: (route, node) => {
+ *     route.component = () => import(`./views/${node.code}.vue`);
+ *   }
+ * });
+ *
+ * // result.uiMenuItems: [{ key: '1', label: '系统管理', children: [...] }]
+ * // result.routeItems: [{ name: 'system.user', path: '/system/user', meta: { id: '1-1' } }]
+ * // result.nodeMap: Map { '1' => {...}, '1-1' => {...} }
+ */
+declare function handleDbMenuItems(menuItems: Array<Object>, options?: {
+    idKey?: string | undefined;
+    codeKey?: string | undefined;
+    labelKey?: string | undefined;
+    childrenKey?: string | undefined;
+    extendKey?: string | undefined;
+    menuIdKey?: string | undefined;
+    menuLabelKey?: string | undefined;
+    menuChildrenKey?: string | undefined;
+    menuExtendKey?: string | undefined;
+    routeNameKey?: string | undefined;
+    routePathKey?: string | undefined;
+    routeMetaKey?: string | undefined;
+    handleNodeItem?: Function | undefined;
+    handleMenuItem?: Function | undefined;
+    handleRouteItem?: Function | undefined;
+}): Object;
+
+export { handleDbMenuItems };