@movk/core 0.0.5 → 1.0.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { VNode, Ref } from 'vue';
+import { MaybeRefOrGetter, VNode, Ref, Component, DefineComponent } from 'vue';
 import { z } from 'zod/v4';
 
 /**
@@ -29,6 +29,37 @@ type ApiUnwrapPromise<T> = T extends Promise<infer U> ? U : T;
  */
 type ApiAwaitedReturn<TFn> = TFn extends (...args: any[]) => ApiAwaitable<infer R> ? R : never;
 
+/**
+ * 提供字符串字面量提示的同时允许任意字符串
+ * 在 IDE 中提供 T 类型的自动补全提示，但不限制只能使用这些值
+ *
+ * @example
+ * ```ts
+ * type Color = Suggest<'red' | 'blue' | 'green'>
+ *
+ * // IDE 会提示 'red', 'blue', 'green'，但也可以使用其他字符串
+ * const color1: Color = 'red'    // 有提示
+ * const color2: Color = 'yellow' // 也可以，虽然没有提示
+ * ```
+ */
+type Suggest<T extends string> = T | (string & {});
+/**
+ * 响应式值类型 - 基于 Vue 的 `MaybeRefOrGetter` 扩展，额外支持上下文回调
+ *
+ * @template T - 值类型
+ * @template CTX - 上下文类型（用于回调函数）
+ *
+ * @example
+ * ```ts
+ * const value: ReactiveValue<boolean> = ref(false)
+ * const getter: ReactiveValue<string> = () => name.value
+ * const computed: ReactiveValue<number> = computed(() => count.value)
+ * const withContext: ReactiveValue<boolean, Context> = (ctx) => ctx.value > 0
+ * ```
+ */
+type ReactiveValue<T, CTX = never> = [CTX] extends [never] ? MaybeRefOrGetter<T> : MaybeRefOrGetter<T> | ((ctx: CTX) => T);
+type StripNullable<T> = T extends null | undefined ? never : T;
+
 type UnknownObject = Record<string, unknown>;
 type AnyObject = Record<string, any>;
 /**
@@ -176,6 +207,125 @@ type GetObjectField<MaybeObject, Key extends string> = MaybeObject extends Recor
  * // - () => h('div', '标题') 的惰性渲染函数
  */
 type StringOrVNode = string | VNode | (() => VNode);
+/**
+ * 合并两个对象类型，U 中的属性会覆盖 T 中的属性
+ *
+ * @example
+ * ```ts
+ * type T = { a: number, c: string }
+ * type U = { a: string, b: boolean }
+ * type M = Merge<T, U> // { a: string, b: boolean, c: string }
+ * ```
+ */
+type Merge<T, U> = Omit<T, keyof U> & U;
+/**
+ * 判断类型 T 是否为纯对象类型
+ * 纯对象是指普通的对象字面量，排除数组、函数、Date 等特殊对象类型
+ * @example
+ * ```ts
+ * type Test1 = IsPlainObject<{ a: number }> // true
+ * type Test2 = IsPlainObject<string[]>      // false
+ * type Test3 = IsPlainObject<() => void>    // false
+ * type Test4 = IsPlainObject<Date>          // false
+ * type Test5 = IsPlainObject<string>        // false
+ * type Test6 = IsPlainObject<null>          // false
+ * ```
+ */
+type IsPlainObject<T> = (T extends null | undefined ? never : T) extends Record<string, any> ? (T extends null | undefined ? never : T) extends any[] ? false : (T extends null | undefined ? never : T) extends (...args: any[]) => any ? false : (T extends null | undefined ? never : T) extends Date ? false : true : false;
+/**
+ * 深度控制类型，用于限制类型递归的深度
+ * 防止类型计算超出 TypeScript 的递归限制
+ */
+type Depth = [never, 0, 1, 2, 3, 4];
+/**
+ * 提取对象的嵌套键，支持点语法路径
+ *
+ * @template T 源对象类型
+ * @template D 递归深度，默认为2
+ * @example
+ * ```ts
+ * type User = {
+ *   name: string
+ *   address: {
+ *     city: string
+ *     country: string
+ *   }
+ * }
+ * type Keys = NestedKeys<User> // 'name' | 'address' | 'address.city' | 'address.country'
+ * ```
+ */
+type NestedKeys<T, D extends number = 2> = [D] extends [never] ? never : {
+    [K in keyof T & string]: IsPlainObject<T[K]> extends true ? K | `${K}.${NestedKeys<T[K] extends null | undefined ? never : T[K], Depth[D]>}` : K;
+}[keyof T & string];
+/**
+ * 提取对象中所有纯对象字段的键（包括嵌套的），支持点语法路径
+ *
+ * @template T 源对象类型
+ * @template D 递归深度，默认为2
+ * @example
+ * ```ts
+ * type User = {
+ *   name: string
+ *   age: number
+ *   address: {
+ *     city: string
+ *     location: {
+ *       lat: number
+ *       lng: number
+ *     }
+ *   }
+ * }
+ * type ObjectKeys = ObjectFieldKeys<User> // 'address' | 'address.location'
+ * ```
+ */
+type ObjectFieldKeys<T, D extends number = 2> = [D] extends [never] ? never : {
+    [K in keyof T & string]: IsPlainObject<T[K]> extends true ? K | `${K}.${ObjectFieldKeys<T[K] extends null | undefined ? never : T[K], Depth[D]>}` : never;
+}[keyof T & string];
+/**
+ * 提取对象中所有非对象字段的键
+ * 排除纯对象字段，只保留原始类型字段的键
+ *
+ * @template T 源对象类型
+ * @example
+ * ```ts
+ * type User = {
+ *   name: string
+ *   age: number
+ *   address: {
+ *     city: string
+ *   }
+ * }
+ * type NonObjectKeys = NonObjectFieldKeys<User> // 'name' | 'age' | 'address.city'
+ * ```
+ */
+type NonObjectFieldKeys<T> = Exclude<NestedKeys<T>, ObjectFieldKeys<T>>;
+/**
+ * 提取对象中所有数组字段的键（包括嵌套的），支持点语法路径
+ *
+ * @template T 源对象类型
+ * @template D 递归深度，默认为2
+ * @example
+ * ```ts
+ * type User = {
+ *   name: string
+ *   tags: string[]
+ *   posts: Array<{ title: string }>
+ *   profile: {
+ *     hobbies: string[]
+ *   }
+ * }
+ * type ArrayKeys = ArrayFieldKeys<User> // 'tags' | 'posts' | 'profile.hobbies'
+ * ```
+ */
+type ArrayFieldKeys<T, D extends number = 2> = [D] extends [never] ? never : {
+    [K in keyof T & string]: (T[K] extends null | undefined ? never : T[K]) extends any[] ? K : IsPlainObject<T[K]> extends true ? `${K}.${ArrayFieldKeys<T[K] extends null | undefined ? never : T[K], Depth[D]>}` : never;
+}[keyof T & string];
+/**
+ * 根据路径字符串提取对象属性的类型，支持点语法和嵌套对象
+ * @example GetFieldValue<User, 'tags'> // string[]
+ * @example GetFieldValue<User, 'profile.bio'> // string
+ */
+type GetFieldValue<T, P extends string> = P extends keyof T ? T[P] : P extends `${infer K}.${infer Rest}` ? K extends keyof T ? T[K] extends undefined ? undefined : GetFieldValue<NonNullable<T[K]>, Rest> : unknown : unknown;
 
 declare const StorageTypeSchema: z.ZodEnum<{
     localStorage: "localStorage";
@@ -201,6 +351,38 @@ interface AppStorageReturn<T> {
     removeItem: () => void;
 }
 
+/**
+ * vue-component-type-helpers
+ * Copy from https://github.com/vuejs/language-tools/tree/master/packages/component-type-helpers
+ */
+type IsComponent = StringOrVNode | Component | DefineComponent | ((...args: any[]) => any);
+type ComponentType<T> = T extends new (...args: any) => {} ? 1 : T extends (...args: any) => any ? 2 : 0;
+type ComponentProps<T> = T extends new (...args: any) => {
+    $props: infer P;
+} ? NonNullable<P> : T extends (props: infer P, ...args: any) => any ? P : {};
+type ComponentSlots<T> = T extends new (...args: any) => {
+    $slots: infer S;
+} ? NonNullable<S> : T extends (props: any, ctx: {
+    slots: infer S;
+    attrs: any;
+    emit: any;
+}, ...args: any) => any ? NonNullable<S> : {};
+type ComponentAttrs<T> = T extends new (...args: any) => {
+    $attrs: infer A;
+} ? NonNullable<A> : T extends (props: any, ctx: {
+    slots: any;
+    attrs: infer A;
+    emit: any;
+}, ...args: any) => any ? NonNullable<A> : {};
+type ComponentEmit<T> = T extends new (...args: any) => {
+    $emit: infer E;
+} ? NonNullable<E> : T extends (props: any, ctx: {
+    slots: any;
+    attrs: any;
+    emit: infer E;
+}, ...args: any) => any ? NonNullable<E> : {};
+type ComponentExposed<T> = T extends new (...args: any) => infer E ? E : T extends (props: any, ctx: any, expose: (exposed: infer E) => any, ...args: any) => any ? NonNullable<E> : {};
+
 /**
  * 应用存储管理的组合式函数，支持localStorage和sessionStorage
  *
@@ -284,532 +466,130 @@ declare function useAppStorage<T = unknown>(config: StorageConfigInput<T>): AppS
  */
 declare function useCopyCode(text: string): Promise<boolean>;
 
-type TreeNode<T = any> = T & {
-    children?: TreeNode<T>[];
-    [key: string]: any;
-};
-declare const TreeConfigSchema: z.ZodObject<{
-    id: z.ZodDefault<z.ZodString>;
-    pid: z.ZodDefault<z.ZodString>;
-    children: z.ZodDefault<z.ZodString>;
-}, z.core.$strip>;
-type TreeConfigInput = z.input<typeof TreeConfigSchema>;
-declare const _TreeStatsSchema: z.ZodObject<{
-    total: z.ZodNumber;
-    leaves: z.ZodNumber;
-    depth: z.ZodNumber;
-    branches: z.ZodNumber;
-}, z.core.$strip>;
-type TreeStats = z.infer<typeof _TreeStatsSchema>;
-interface TreeNodeResult<T = any> {
-    readonly node: TreeNode<T>;
-    readonly path: readonly TreeNode<T>[];
-    readonly depth: number;
-    readonly index: number;
-}
-type TreePredicate<T = any> = (node: TreeNode<T>, depth: number, path: readonly TreeNode<T>[]) => boolean;
-type TreeTransformer<T = any, R = any> = (node: TreeNode<T>, depth: number, path: readonly TreeNode<T>[]) => R;
-type TreeVisitor<T = any> = (node: TreeNode<T>, depth: number, path: readonly TreeNode<T>[]) => void | boolean;
-declare class Tree {
-    private static dfsGenerator;
-    private static bfsGenerator;
-    private static selectStrategy;
-    /**
-     * 从扁平数组创建树形结构
-     *
-     * @category Data Structures
-     * @param list 扁平数组数据
-     * @param config 树形配置选项
-     * @returns 树形结构数组
-     * @example
-     * ```ts
-     * const flatData = [
-     *   { id: '1', name: '部门1', parentId: null },
-     *   { id: '2', name: '部门1-1', parentId: '1' },
-     *   { id: '3', name: '部门1-2', parentId: '1' },
-     *   { id: '4', name: '部门1-1-1', parentId: '2' }
-     * ]
-     *
-     * const tree = Tree.fromList(flatData, {
-     *   id: 'id',
-     *   pid: 'parentId',
-     *   children: 'children'
-     * })
-     *
-     * console.log(tree) // 转换为树形结构
-     * ```
-     */
-    static fromList<T = any>(list: T[], config?: TreeConfigInput): TreeNode<T>[];
-    /**
-     * 将树形结构转换为扁平数组
-     *
-     * @category Data Structures
-     * @param tree 树形结构（单个节点或节点数组）
-     * @param config 树形配置选项
-     * @returns 扁平数组
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     name: '根节点',
-     *     children: [
-     *       { id: '2', name: '子节点1', children: [] },
-     *       { id: '3', name: '子节点2', children: [] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const flatList = Tree.toList(tree)
-     * console.log(flatList) // [{ id: '1', name: '根节点' }, { id: '2', name: '子节点1' }, ...]
-     * ```
-     */
-    static toList<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): T[];
-    /**
-     * 估算树形结构的节点数量
-     *
-     * @category Data Structures
-     * @param tree 树形结构（单个节点或节点数组）
-     * @param config 树形配置选项
-     * @returns 节点总数量
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     name: '根节点',
-     *     children: [
-     *       { id: '2', name: '子节点1', children: [] },
-     *       { id: '3', name: '子节点2', children: [] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const size = Tree.estimateSize(tree)
-     * console.log(size) // 3
-     * ```
-     */
-    static estimateSize<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): number;
-    /**
-     * 查找树中第一个满足条件的节点
-     *
-     * @category Data Structures
-     * @param tree 树形结构（单个节点或节点数组）
-     * @param predicate 查找条件函数
-     * @param config 树形配置选项
-     * @returns 匹配的节点结果，包含节点、路径、深度和索引信息；未找到时返回undefined
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     name: '部门1',
-     *     children: [
-     *       { id: '2', name: '部门1-1', children: [] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const result = Tree.find(tree, (node) => node.name === '部门1-1')
-     * console.log(result?.node.id) // '2'
-     * console.log(result?.depth) // 1
-     * ```
-     */
-    static find<T = any>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNodeResult<T> | undefined;
-    /**
-     * 查找树中所有满足条件的节点
-     *
-     * @category Data Structures
-     * @param tree 树形结构（单个节点或节点数组）
-     * @param predicate 查找条件函数
-     * @param config 树形配置选项
-     * @returns 所有匹配的节点结果数组，每个结果包含节点、路径、深度和索引信息
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     type: 'folder',
-     *     name: '根目录',
-     *     children: [
-     *       { id: '2', type: 'file', name: '文件1', children: [] },
-     *       { id: '3', type: 'file', name: '文件2', children: [] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const files = Tree.findAll(tree, (node) => node.type === 'file')
-     * console.log(files.length) // 2
-     * ```
-     */
-    static findAll<T = any>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNodeResult<T>[];
-    /**
-     * 根据ID查找树中的节点
-     *
-     * @category Data Structures
-     * @param tree 树形结构（单个节点或节点数组）
-     * @param id 要查找的节点ID
-     * @param config 树形配置选项
-     * @returns 匹配的节点结果，包含节点、路径、深度和索引信息；未找到时返回undefined
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     name: '根节点',
-     *     children: [
-     *       { id: '2', name: '子节点', children: [] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const result = Tree.findById(tree, '2')
-     * console.log(result?.node.name) // '子节点'
-     * ```
-     */
-    static findById<T = any>(tree: TreeNode<T> | TreeNode<T>[], id: string, config?: TreeConfigInput): TreeNodeResult<T> | undefined;
-    /**
-     * 获取树形结构的统计信息
-     *
-     * @category Data Structures
-     * @param tree 树形结构（单个节点或节点数组）
-     * @param config 树形配置选项
-     * @returns 树的统计信息，包含总节点数、叶子节点数、最大深度和分支节点数
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     name: '根节点',
-     *     children: [
-     *       { id: '2', name: '子节点1', children: [] },
-     *       { id: '3', name: '子节点2', children: [
-     *         { id: '4', name: '孙节点', children: [] }
-     *       ] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const stats = Tree.getStats(tree)
-     * console.log(stats) // { total: 4, leaves: 2, depth: 3, branches: 2 }
-     * ```
-     */
-    static getStats<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): TreeStats;
-    /**
-     * 过滤树形结构，保留满足条件的节点及其祖先和后代
-     *
-     * @category Data Structures
-     * @param tree 树形结构（单个节点或节点数组）
-     * @param predicate 过滤条件函数
-     * @param config 树形配置选项
-     * @returns 过滤后的树形结构数组
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     type: 'folder',
-     *     name: '根目录',
-     *     children: [
-     *       { id: '2', type: 'file', name: '文档.txt', children: [] },
-     *       { id: '3', type: 'folder', name: '子目录', children: [
-     *         { id: '4', type: 'file', name: '图片.jpg', children: [] }
-     *       ] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const filtered = Tree.filter(tree, (node) => node.type === 'file')
-     * // 返回包含所有文件节点及其父级路径的树结构
-     * ```
-     */
-    static filter<T = any>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNode<T>[];
-    /**
-     * 转换树形结构，将每个节点转换为新的结构
-     *
-     * @category Data Structures
-     * @param tree 树形结构（单个节点或节点数组）
-     * @param transformer 节点转换函数
-     * @param config 树形配置选项
-     * @returns 转换后的树形结构数组
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     name: '部门1',
-     *     children: [
-     *       { id: '2', name: '部门1-1', children: [] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const transformed = Tree.transform(tree, (node, depth) => ({
-     *   key: node.id,
-     *   title: node.name,
-     *   level: depth
-     * }))
-     * // 转换为新的数据结构
-     * ```
-     */
-    static transform<T = any, R = any>(tree: TreeNode<T> | TreeNode<T>[], transformer: TreeTransformer<T, R>, config?: TreeConfigInput): TreeNode<R>[];
-    /**
-     * 遍历树形结构的每个节点
-     *
-     * @category Data Structures
-     * @param tree 树形结构（单个节点或节点数组）
-     * @param visitor 访问者函数，返回false可以跳过子节点的遍历
-     * @param config 树形配置选项
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     name: '根节点',
-     *     children: [
-     *       { id: '2', name: '子节点', children: [] }
-     *     ]
-     *   }
-     * ]
-     *
-     * Tree.forEach(tree, (node, depth) => {
-     *   console.log(`${' '.repeat(depth * 2)}${node.name}`)
-     *   // 输出缩进的树结构
-     * })
-     * ```
-     */
-    static forEach<T = any>(tree: TreeNode<T> | TreeNode<T>[], visitor: TreeVisitor<T>, config?: TreeConfigInput): void;
-    /**
-     * 在指定节点前插入新节点
-     *
-     * @category Data Structures
-     * @param tree 树形结构数组
-     * @param targetId 目标节点的ID
-     * @param newNode 要插入的新节点数据
-     * @param config 树形配置选项
-     * @returns 是否成功插入
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     name: '节点1',
-     *     children: [
-     *       { id: '2', name: '节点2', children: [] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const success = Tree.insertBefore(tree, '2', { id: '1.5', name: '新节点' })
-     * console.log(success) // true
-     * ```
-     */
-    static insertBefore<T = any>(tree: TreeNode<T>[], targetId: string, newNode: T, config?: TreeConfigInput): boolean;
-    /**
-     * 在指定节点后插入新节点
-     *
-     * @category Data Structures
-     * @param tree 树形结构数组
-     * @param targetId 目标节点的ID
-     * @param newNode 要插入的新节点数据
-     * @param config 树形配置选项
-     * @returns 是否成功插入
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     name: '节点1',
-     *     children: [
-     *       { id: '2', name: '节点2', children: [] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const success = Tree.insertAfter(tree, '2', { id: '3', name: '新节点' })
-     * console.log(success) // true
-     * ```
-     */
-    static insertAfter<T = any>(tree: TreeNode<T>[], targetId: string, newNode: T, config?: TreeConfigInput): boolean;
-    /**
-     * 从树中删除指定节点
-     *
-     * @category Data Structures
-     * @param tree 树形结构数组
-     * @param targetId 要删除的节点ID
-     * @param config 树形配置选项
-     * @returns 被删除的节点，未找到时返回undefined
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     name: '根节点',
-     *     children: [
-     *       { id: '2', name: '子节点', children: [] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const removed = Tree.remove(tree, '2')
-     * console.log(removed?.name) // '子节点'
-     * ```
-     */
-    static remove<T = any>(tree: TreeNode<T>[], targetId: string, config?: TreeConfigInput): TreeNode<T> | undefined;
-    /**
-     * 验证树形结构的有效性
-     *
-     * @category Data Structures
-     * @param tree 树形结构（单个节点或节点数组）
-     * @param config 树形配置选项
-     * @returns 验证结果，包含是否有效和错误信息数组
-     * @example
-     * ```ts
-     * const tree = [
-     *   {
-     *     id: '1',
-     *     name: '根节点',
-     *     children: [
-     *       { id: '2', name: '子节点', children: [] }
-     *     ]
-     *   }
-     * ]
-     *
-     * const result = Tree.validate(tree)
-     * console.log(result.isValid) // true
-     * console.log(result.errors) // []
-     * ```
-     */
-    static validate<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): {
-        isValid: boolean;
-        errors: string[];
-    };
-}
-
-/**
- * 数组去重，返回去除重复元素后的新数组
- *
- * @category Array
- * @param arr 待去重的数组
- * @returns 去重后的新数组
- * @example
- * ```ts
- * const numbers = [1, 2, 2, 3, 3, 4]
- * const uniqueNumbers = unique(numbers)
- * console.log(uniqueNumbers) // [1, 2, 3, 4]
- *
- * const strings = ['a', 'b', 'a', 'c']
- * const uniqueStrings = unique(strings)
- * console.log(uniqueStrings) // ['a', 'b', 'c']
- * ```
- */
-declare function unique<T>(arr: T[]): T[];
-/**
- * 将数组分割成指定大小的块
- *
- * @category Array
- * @param arr 待分割的数组
- * @param size 每个块的大小
- * @returns 分割后的二维数组
- * @example
- * ```ts
- * const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9]
- * const chunks = chunk(numbers, 3)
- * console.log(chunks) // [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
- *
- * const names = ['Alice', 'Bob', 'Charlie', 'David', 'Eve']
- * const pairs = chunk(names, 2)
- * console.log(pairs) // [['Alice', 'Bob'], ['Charlie', 'David'], ['Eve']]
- * ```
- */
-declare function chunk<T>(arr: T[], size: number): T[][];
-/**
- * 数组扁平化，将嵌套数组展平到指定深度
- *
- * @category Array
- * @param arr 待扁平化的数组
- * @param depth 扁平化深度，默认为1
- * @returns 扁平化后的数组
- * @example
- * ```ts
- * const nested = [1, [2, 3], [4, [5, 6]]]
- * const flat1 = flatten(nested)
- * console.log(flat1) // [1, 2, 3, 4, [5, 6]]
- *
- * const flat2 = flatten(nested, 2)
- * console.log(flat2) // [1, 2, 3, 4, 5, 6]
- * ```
- */
-declare function flatten<T>(arr: T[], depth?: number): any[];
-
-/**
- * 防抖函数，在指定时间内多次触发只执行最后一次
- *
- * @category Async
- * @param func 需要防抖的函数
- * @param wait 防抖延迟时间（毫秒）
- * @returns 防抖处理后的函数
- * @example
- * ```ts
- * const debouncedSearch = debounce((query: string) => {
- *   console.log('搜索:', query)
- * }, 300)
- *
- * // 连续调用，只有最后一次会执行
- * debouncedSearch('a')
- * debouncedSearch('ab')
- * debouncedSearch('abc') // 只有这次会在300ms后执行
- * ```
- */
-declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
-
-/**
- * 延迟执行函数，返回一个在指定时间后resolve的Promise
- *
- * @category Async
- * @param ms 延迟时间（毫秒）
- * @returns 延迟Promise
- * @example
- * ```ts
- * // 延迟1秒后继续执行
- * await sleep(1000)
- * console.log('1秒后执行')
- *
- * // 在异步函数中使用
- * async function delayedOperation() {
- *   console.log('开始')
- *   await sleep(500)
- *   console.log('500ms后执行')
- * }
- * ```
- */
-declare function sleep(ms: number): Promise<void>;
-/**
- * 可取消的延迟函数，返回Promise和取消函数
- *
- * @category Async
- * @param ms 延迟时间（毫秒）
- * @returns 包含Promise和取消函数的对象
- * @example
- * ```ts
- * const { promise, cancel } = sleepWithCancel(5000)
- *
- * // 在另一个地方取消延迟
- * setTimeout(() => {
- *   cancel() // 取消延迟
- * }, 2000)
- *
- * try {
- *   await promise
- *   console.log('5秒后执行')
- * } catch (error) {
- *   console.log('延迟被取消')
- * }
- * ```
- */
-declare function sleepWithCancel(ms: number): {
-    promise: Promise<void>;
-    cancel: () => void;
+/**
+ * 数组去重，返回去除重复元素后的新数组
+ *
+ * @category Array
+ * @param arr 待去重的数组
+ * @returns 去重后的新数组
+ * @example
+ * ```ts
+ * const numbers = [1, 2, 2, 3, 3, 4]
+ * const uniqueNumbers = unique(numbers)
+ * console.log(uniqueNumbers) // [1, 2, 3, 4]
+ *
+ * const strings = ['a', 'b', 'a', 'c']
+ * const uniqueStrings = unique(strings)
+ * console.log(uniqueStrings) // ['a', 'b', 'c']
+ * ```
+ */
+declare function unique<T>(arr: T[]): T[];
+/**
+ * 将数组分割成指定大小的块
+ *
+ * @category Array
+ * @param arr 待分割的数组
+ * @param size 每个块的大小
+ * @returns 分割后的二维数组
+ * @example
+ * ```ts
+ * const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+ * const chunks = chunk(numbers, 3)
+ * console.log(chunks) // [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
+ *
+ * const names = ['Alice', 'Bob', 'Charlie', 'David', 'Eve']
+ * const pairs = chunk(names, 2)
+ * console.log(pairs) // [['Alice', 'Bob'], ['Charlie', 'David'], ['Eve']]
+ * ```
+ */
+declare function chunk<T>(arr: T[], size: number): T[][];
+/**
+ * 数组扁平化，将嵌套数组展平到指定深度
+ *
+ * @category Array
+ * @param arr 待扁平化的数组
+ * @param depth 扁平化深度，默认为1
+ * @returns 扁平化后的数组
+ * @example
+ * ```ts
+ * const nested = [1, [2, 3], [4, [5, 6]]]
+ * const flat1 = flatten(nested)
+ * console.log(flat1) // [1, 2, 3, 4, [5, 6]]
+ *
+ * const flat2 = flatten(nested, 2)
+ * console.log(flat2) // [1, 2, 3, 4, 5, 6]
+ * ```
+ */
+declare function flatten<T>(arr: T[], depth?: number): any[];
+
+/**
+ * 防抖函数，在指定时间内多次触发只执行最后一次
+ *
+ * @category Async
+ * @param func 需要防抖的函数
+ * @param wait 防抖延迟时间（毫秒）
+ * @returns 防抖处理后的函数
+ * @example
+ * ```ts
+ * const debouncedSearch = debounce((query: string) => {
+ *   console.log('搜索:', query)
+ * }, 300)
+ *
+ * // 连续调用，只有最后一次会执行
+ * debouncedSearch('a')
+ * debouncedSearch('ab')
+ * debouncedSearch('abc') // 只有这次会在300ms后执行
+ * ```
+ */
+declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
+
+/**
+ * 延迟执行函数，返回一个在指定时间后resolve的Promise
+ *
+ * @category Async
+ * @param ms 延迟时间（毫秒）
+ * @returns 延迟Promise
+ * @example
+ * ```ts
+ * // 延迟1秒后继续执行
+ * await sleep(1000)
+ * console.log('1秒后执行')
+ *
+ * // 在异步函数中使用
+ * async function delayedOperation() {
+ *   console.log('开始')
+ *   await sleep(500)
+ *   console.log('500ms后执行')
+ * }
+ * ```
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * 可取消的延迟函数，返回Promise和取消函数
+ *
+ * @category Async
+ * @param ms 延迟时间（毫秒）
+ * @returns 包含Promise和取消函数的对象
+ * @example
+ * ```ts
+ * const { promise, cancel } = sleepWithCancel(5000)
+ *
+ * // 在另一个地方取消延迟
+ * setTimeout(() => {
+ *   cancel() // 取消延迟
+ * }, 2000)
+ *
+ * try {
+ *   await promise
+ *   console.log('5秒后执行')
+ * } catch (error) {
+ *   console.log('延迟被取消')
+ * }
+ * ```
+ */
+declare function sleepWithCancel(ms: number): {
+    promise: Promise<void>;
+    cancel: () => void;
 };
 
 /**
@@ -994,34 +774,34 @@ declare function replaceCurrentColor(path: string, color?: string): Promise<stri
 declare function convertToKebabCase<T extends AnyObject>(obj: T, deep?: boolean): T;
 
 /**
- * 深度克隆对象，创建完全独立的副本
+ * 深拷贝任意 JavaScript 值。
+ *
+ * - 优先使用原生 `structuredClone`（若可用），覆盖 `Map`/`Set`/`TypedArray`/`ArrayBuffer` 等内建类型。
+ * - 对不支持 `structuredClone` 的环境，使用回退实现：
+ *   - 支持循环引用（`WeakMap` 记忆化）。
+ *   - 保留原型与属性描述符（含 getter/setter），复制 symbol 键。
+ *   - 内建类型专项处理：`Date`/`RegExp`/`Map`/`Set`/`ArrayBuffer`/`TypedArray`/`URL`/`Error`。
  *
  * @category Object
- * @param obj 待克隆的对象
- * @returns 深度克隆后的对象
+ * @typeParam T 拷贝值的类型
+ * @param obj 要被深拷贝的值
+ * @param cache 内部使用的 `WeakMap`（循环引用记忆化），一般不需要传入
+ * @returns 新的深拷贝值，与输入值结构等价、引用独立
+ *
  * @example
  * ```ts
- * const original = {
- *   name: 'John',
- *   age: 30,
- *   address: {
- *     city: 'New York',
- *     zip: '10001'
- *   },
- *   hobbies: ['reading', 'coding']
- * }
- *
- * const cloned = deepClone(original)
- * cloned.address.city = 'Los Angeles'
- * cloned.hobbies.push('gaming')
- *
- * console.log(original.address.city) // 'New York' (未改变)
- * console.log(original.hobbies.length) // 2 (未改变)
- * console.log(cloned.address.city) // 'Los Angeles'
- * console.log(cloned.hobbies.length) // 3
+ * const source = { a: 1, d: new Date(), m: new Map([[1, { x: 2 }]]) }
+ * const cloned = deepClone(source)
+ * cloned !== source // true
+ * cloned.d !== source.d // true
+ * cloned.m !== source.m // true
+ * cloned.m.get(1) !== source.m.get(1) // true
  * ```
+ *
+ * @remarks
+ * 若对象包含不可克隆资源（如带有原生句柄的自定义对象），请在外层进行自定义序列化逻辑或为该类型添加专用分支。
  */
-declare function deepClone<T>(obj: T): T;
+declare function deepClone<T>(obj: T, cache?: WeakMap<object, any>): T;
 
 /**
  * 从对象中排除指定的键，返回新对象
@@ -1039,42 +819,157 @@ declare function deepClone<T>(obj: T): T;
  *   email: 'john@example.com'
  * }
  *
- * const publicUser = omit(user, ['password'])
- * console.log(publicUser) // { id: 1, name: 'John', email: 'john@example.com' }
+ * const publicUser = omit(user, ['password'])
+ * console.log(publicUser) // { id: 1, name: 'John', email: 'john@example.com' }
+ *
+ * const basicInfo = omit(user, ['password', 'email'])
+ * console.log(basicInfo) // { id: 1, name: 'John' }
+ * ```
+ */
+declare function omit<T extends AnyObject, K extends keyof T>(obj: T, keys: K[]): OmitByKey<T, K>;
+/**
+ * 从对象中排除值为undefined的键
+ *
+ * @category Object
+ * @param obj 源对象
+ * @returns 排除undefined值后的新对象
+ * @example
+ * ```ts
+ * const data = {
+ *   name: 'John',
+ *   age: undefined,
+ *   city: 'New York',
+ *   country: undefined
+ * }
+ *
+ * const cleaned = omitUndefined(data)
+ * console.log(cleaned) // { name: 'John', city: 'New York' }
+ *
+ * // 用于API请求前清理数据
+ * const requestData = omitUndefined({
+ *   title: 'Post Title',
+ *   content: 'Post content',
+ *   tags: undefined,
+ *   published: true
+ * })
+ * ```
+ */
+declare function omitUndefined<T extends AnyObject>(obj: T): Partial<T>;
+
+type PathSegment = string | number;
+type PathSegments = PathSegment[];
+type PathInput = string | PathSegments;
+/**
+ * 检查值是否为有效的容器类型（对象或数组）
+ *
+ * - isObject: 仅检查纯对象，排除数组
+ * - isValidContainer: 检查所有可作为容器的类型（对象 + 数组）
+ *
+ * 支持 Vue 3 的 Proxy 对象和 Proxy 数组。
+ *
+ * @category Validator
+ * @param value - 待检查的值
+ * @returns 是否为有效容器（对象或数组）
+ * @example
+ * ```ts
+ * isValidContainer({})              // true
+ * isValidContainer([])              // true
+ * isValidContainer(new Proxy({}, {})) // true
+ * isValidContainer(null)            // false
+ * isValidContainer('string')        // false
+ * isValidContainer(123)             // false
+ * ```
+ */
+declare function isValidContainer(value: any): boolean;
+/**
+ * 将路径字符串解析为片段数组。
+ *
+ * - 支持点语法与方括号语法混用
+ * - 引号键支持单/双引号与反斜杠转义
+ * - 方括号内未引号的非负整数字面量解析为 number 段
+ * - 点语法中的纯数字段保持字符串（不转为索引）
+ *
+ * @category Object
+ * @param path 路径字符串或片段数组
+ * @returns 解析后的片段数组
+ * @example
+ * ```ts
+ * toPath('a.b[0].c') // ['a', 'b', 0, 'c']
+ * toPath("a['x.y']") // ['a', 'x.y']
+ * ```
+ */
+declare function toPath(path: PathInput): PathSegments;
+/**
+ * 读取对象指定路径的值。
+ *
+ * - 若取值结果为 undefined，则返回 defaultValue
+ * - 若取值结果为 null，则直接返回 null（不触发默认值）
+ * - 传入空路径时返回 object 本身
  *
- * const basicInfo = omit(user, ['password', 'email'])
- * console.log(basicInfo) // { id: 1, name: 'John' }
+ * @category Object
+ * @param object 源对象
+ * @param path 路径字符串或片段数组
+ * @param defaultValue 结果为 undefined 时返回的默认值
+ * @returns 读取到的值或默认值
+ * @example
+ * ```ts
+ * const obj = { a: { b: { c: 1, d: undefined }, e: null }, arr: [{ x: 9 }] }
+ * getPath(obj, 'a.b.c') // 1
+ * getPath(obj, 'a.b.d', 42) // 42（d 为 undefined，使用默认值）
+ * getPath(obj, 'a.e', 100) // null（null 不触发默认值）
+ * getPath(obj, 'arr[0].x') // 9
+ * getPath(obj, '') // 返回 obj 本身
  * ```
  */
-declare function omit<T extends AnyObject, K extends keyof T>(obj: T, keys: K[]): OmitByKey<T, K>;
+declare function getPath<T, D = undefined>(object: T, path: PathInput, defaultValue?: D): unknown | D;
 /**
- * 从对象中排除值为undefined的键
+ * 在对象指定路径写入值。缺失路径会被自动创建：
+ * - 下一段为 number（索引）时创建数组
+ * - 下一段为 string（属性）时创建对象
+ *
+ * 若中途遇到非容器类型（如字符串/数值/布尔），会被替换为正确的容器以继续写入。
  *
  * @category Object
- * @param obj 源对象
- * @returns 排除undefined值后的新对象
+ * @param object 目标对象（原地修改并返回同一引用）
+ * @param path 路径字符串或片段数组
+ * @param value 要写入的值
+ * @returns 原对象（已修改）
  * @example
  * ```ts
- * const data = {
- *   name: 'John',
- *   age: undefined,
- *   city: 'New York',
- *   country: undefined
- * }
+ * const obj: any = {}
+ * setPath(obj, 'a.b[0].c', 7)
+ * // obj => { a: { b: [{ c: 7 }] } }
+ *
+ * setPath(obj, 'a.b[2].d', 8)
+ * // 数组自动扩容到长度 3
+ * // obj.a.b[2] => { d: 8 }
+ *
+ * setPath(obj, 'a.0.b', 1) // 点语法数字键保持为字符串键
+ * // obj => { a: { 0: { b: 1 } } }
+ * setPath(obj, 'a[0].b', 2) // 索引用方括号
+ * // obj.a[0].b => 2
+ * ```
+ */
+declare function setPath<T extends Record<string, any>>(object: T, path: PathInput, value: unknown): T;
+/**
+ * 将片段数组序列化为路径字符串。
  *
- * const cleaned = omitUndefined(data)
- * console.log(cleaned) // { name: 'John', city: 'New York' }
+ * 规则：
+ * - 合法标识符段使用点拼接（a.b.c）
+ * - 数字段转为索引（[0]）
+ * - 其它需要转义的键使用方括号引号（['x.y']），并转义 \\ 与 '\''
  *
- * // 用于API请求前清理数据
- * const requestData = omitUndefined({
- *   title: 'Post Title',
- *   content: 'Post content',
- *   tags: undefined,
- *   published: true
- * })
+ * @category Object
+ * @param segments 路径片段数组
+ * @returns 路径字符串
+ * @example
+ * ```ts
+ * const p = joinPath(['a', 'x.y', 0, 'space key'])
+ * // p: "a['x.y'][0]['space key']"
+ * // 与解析往返：toPath(p) => ['a', 'x.y', 0, 'space key']
  * ```
  */
-declare function omitUndefined<T extends AnyObject>(obj: T): Partial<T>;
+declare function joinPath(segments: (string | number)[]): string;
 
 /**
  * 从对象中选择指定的键，返回新对象
@@ -1159,50 +1054,677 @@ declare function separateMany<T extends AnyObject, M extends Record<string, read
 };
 
 /**
- * 将字符串首字母大写
+ * 将字符串转换为Start Case格式（每个单词首字母大写，用空格分隔）。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns Start Case格式的字符串
+ * @example
+ * ```ts
+ * startCase('firstName') // 'First Name'
+ * startCase('first_name') // 'First Name'
+ * startCase('first-name') // 'First Name'
+ * startCase('XMLHttpRequest') // 'XML Http Request'
+ * ```
+ */
+declare function startCase(str: string): string;
+/**
+ * 将字符串转换为驼峰命名格式（第一个单词小写，后续单词首字母大写）。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 驼峰命名格式的字符串
+ * @example
+ * ```ts
+ * camelCase('First Name') // 'firstName'
+ * camelCase('first_name') // 'firstName'
+ * camelCase('first-name') // 'firstName'
+ * camelCase('XMLHttpRequest') // 'xmlHttpRequest'
+ * ```
+ */
+declare function camelCase(str: string): string;
+/**
+ * 将字符串转换为短横线命名格式（kebab-case）。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 短横线命名格式的字符串
+ * @example
+ * ```ts
+ * kebabCase('firstName') // 'first-name'
+ * kebabCase('First Name') // 'first-name'
+ * kebabCase('first_name') // 'first-name'
+ * kebabCase('XMLHttpRequest') // 'xml-http-request'
+ * ```
+ */
+declare function kebabCase(str: string): string;
+/**
+ * 将字符串转换为下划线命名格式（snake_case）。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 下划线命名格式的字符串
+ * @example
+ * ```ts
+ * snakeCase('firstName') // 'first_name'
+ * snakeCase('First Name') // 'first_name'
+ * snakeCase('first-name') // 'first_name'
+ * snakeCase('XMLHttpRequest') // 'xml_http_request'
+ * ```
+ */
+declare function snakeCase(str: string): string;
+/**
+ * 将字符串转换为帕斯卡命名格式（PascalCase，每个单词首字母大写）。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 帕斯卡命名格式的字符串
+ * @example
+ * ```ts
+ * pascalCase('firstName') // 'FirstName'
+ * pascalCase('first_name') // 'FirstName'
+ * pascalCase('first-name') // 'FirstName'
+ * pascalCase('XMLHttpRequest') // 'XmlHttpRequest'
+ * ```
+ */
+declare function pascalCase(str: string): string;
+/**
+ * 将字符串首字母大写，其余字母小写。
  *
  * @category String
- * @param str 待处理的字符串
+ * @param str 要转换的字符串
  * @returns 首字母大写的字符串
  * @example
  * ```ts
- * console.log(capitalize('hello')) // 'Hello'
- * console.log(capitalize('WORLD')) // 'WORLD'
- * console.log(capitalize('')) // ''
- * console.log(capitalize('a')) // 'A'
+ * capitalize('hello') // 'Hello'
+ * capitalize('HELLO') // 'Hello'
+ * capitalize('hello world') // 'Hello world'
  * ```
  */
 declare function capitalize(str: string): string;
 /**
- * 将驼峰命名转换为kebab-case
+ * 将字符串首字母大写，其余字母保持原样。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 首字母大写的字符串
+ * @example
+ * ```ts
+ * upperFirst('hello') // 'Hello'
+ * upperFirst('hELLO') // 'HELLO'
+ * upperFirst('hello world') // 'Hello world'
+ * ```
+ */
+declare function upperFirst(str: string): string;
+/**
+ * 将字符串首字母小写，其余字母保持原样。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 首字母小写的字符串
+ * @example
+ * ```ts
+ * lowerFirst('Hello') // 'hello'
+ * lowerFirst('HELLO') // 'hELLO'
+ * lowerFirst('Hello World') // 'hello World'
+ * ```
+ */
+declare function lowerFirst(str: string): string;
+/**
+ * 将字符串转换为大写格式，单词之间用空格分隔。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 大写格式的字符串
+ * @example
+ * ```ts
+ * upperCase('firstName') // 'FIRST NAME'
+ * upperCase('first_name') // 'FIRST NAME'
+ * upperCase('first-name') // 'FIRST NAME'
+ * upperCase('XMLHttpRequest') // 'XML HTTP REQUEST'
+ * ```
+ */
+declare function upperCase(str: string): string;
+/**
+ * 将字符串转换为小写格式，单词之间用空格分隔。
  *
  * @category String
- * @param str 驼峰命名的字符串
- * @returns kebab-case格式的字符串
+ * @param str 要转换的字符串
+ * @returns 小写格式的字符串
  * @example
  * ```ts
- * console.log(camelToKebab('helloWorld')) // 'hello-world'
- * console.log(camelToKebab('firstName')) // 'first-name'
- * console.log(camelToKebab('XMLHttpRequest')) // 'x-m-l-http-request'
- * console.log(camelToKebab('hello')) // 'hello'
+ * lowerCase('firstName') // 'first name'
+ * lowerCase('First_Name') // 'first name'
+ * lowerCase('FIRST-NAME') // 'first name'
+ * lowerCase('XMLHttpRequest') // 'xml http request'
  * ```
  */
-declare function camelToKebab(str: string): string;
+declare function lowerCase(str: string): string;
+/**
+ * 将驼峰命名转换为kebab-case
+ * @deprecated Use `kebabCase` instead
+ */
+declare const camelToKebab: typeof kebabCase;
 /**
  * 将kebab-case转换为驼峰命名
+ * @deprecated Use `camelCase` instead
+ */
+declare const kebabToCamel: typeof camelCase;
+
+/**
+ * 将字符串分解为单词数组。支持camelCase、snake_case、kebab-case等各种命名风格。
  *
  * @category String
- * @param str kebab-case格式的字符串
- * @returns 驼峰命名的字符串
+ * @param str 要分解的字符串
+ * @returns 单词数组
+ * @example
+ * ```ts
+ * words('helloWorld') // ['hello', 'World']
+ * words('hello_world') // ['hello', 'world']
+ * words('hello-world') // ['hello', 'world']
+ * words('XMLHttpRequest') // ['XML', 'Http', 'Request']
+ * ```
+ */
+declare function words(str: string): string[];
+
+/**
+ * 树节点类型定义
+ *
+ * @template T 节点数据类型
+ */
+type TreeNode<T = any> = T & {
+    children?: TreeNode<T>[];
+    [key: string]: any;
+};
+declare const TreeConfigSchema: z.ZodObject<{
+    id: z.ZodDefault<z.ZodString>;
+    pid: z.ZodDefault<z.ZodString>;
+    children: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 树形配置输入类型
+ */
+type TreeConfigInput = z.input<typeof TreeConfigSchema>;
+declare const _TreeStatsSchema: z.ZodObject<{
+    total: z.ZodNumber;
+    leaves: z.ZodNumber;
+    depth: z.ZodNumber;
+    branches: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * 树统计信息类型
+ */
+type TreeStats = z.infer<typeof _TreeStatsSchema>;
+/**
+ * 树节点谓词函数类型
+ *
+ * @template T 节点数据类型
+ * @param params 包含节点信息的对象参数
+ * @param params.node 当前节点
+ * @param params.depth 节点深度（从0开始）
+ * @param params.path 从根节点到当前节点的路径数组
+ * @param params.index 节点在同级节点中的索引
+ * @returns 是否满足条件
+ */
+type TreePredicate<T = any> = (params: {
+    node: TreeNode<T>;
+    depth: number;
+    path: readonly TreeNode<T>[];
+    index: number;
+}) => boolean;
+/**
+ * 树节点转换函数类型
+ *
+ * @template T 源节点数据类型
+ * @template R 目标节点数据类型
+ * @param params 包含节点信息的对象参数
+ * @param params.node 当前节点
+ * @param params.depth 节点深度（从0开始）
+ * @param params.path 从根节点到当前节点的路径数组
+ * @param params.index 节点在同级节点中的索引
+ * @returns 转换后的节点数据
+ */
+type TreeTransformer<T = any, R = any> = (params: {
+    node: TreeNode<T>;
+    depth: number;
+    path: readonly TreeNode<T>[];
+    index: number;
+}) => R;
+/**
+ * 树节点访问函数类型
+ *
+ * @template T 节点数据类型
+ * @param params 包含节点信息的对象参数
+ * @param params.node 当前节点
+ * @param params.depth 节点深度（从0开始）
+ * @param params.path 从根节点到当前节点的路径数组
+ * @param params.index 节点在同级节点中的索引
+ * @returns 返回false可以终止遍历或跳过子节点
+ */
+type TreeVisitor<T = any> = (params: {
+    node: TreeNode<T>;
+    depth: number;
+    path: readonly TreeNode<T>[];
+    index: number;
+}) => void | boolean;
+/**
+ * 树形数据结构操作工具类
+ *
+ * 提供了一系列操作树形数据的静态方法，包括：
+ * - 查找：find, findAll, findById
+ * - 转换：fromList, toList, transform
+ * - 过滤：filter
+ * - 遍历：forEach
+ * - 统计：estimateSize, getStats
+ * - 修改：insertBefore, insertAfter, remove
+ * - 验证：validate
+ *
+ * 所有使用谓词函数或访问函数的方法都采用对象解构参数格式：
+ * `({ node, depth, path, index }) => boolean`
+ *
  * @example
  * ```ts
- * console.log(kebabToCamel('hello-world')) // 'helloWorld'
- * console.log(kebabToCamel('first-name')) // 'firstName'
- * console.log(kebabToCamel('background-color')) // 'backgroundColor'
- * console.log(kebabToCamel('hello')) // 'hello'
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: '根节点',
+ *     children: [
+ *       { id: '2', name: '子节点1', children: [] },
+ *       { id: '3', name: '子节点2', children: [] }
+ *     ]
+ *   }
+ * ]
+ *
+ * // 查找节点
+ * const node = Tree.find(tree, ({ node }) => node.name === '子节点1')
+ *
+ * // 遍历所有节点
+ * Tree.forEach(tree, ({ node, depth }) => {
+ *   console.log(`${'  '.repeat(depth)}${node.name}`)
+ * })
+ *
+ * // 转换节点结构
+ * const transformed = Tree.transform(tree, ({ node, depth }) => ({
+ *   key: node.id,
+ *   title: node.name,
+ *   level: depth
+ * }))
  * ```
  */
-declare function kebabToCamel(str: string): string;
+declare class Tree {
+    private static dfsGenerator;
+    private static bfsGenerator;
+    private static selectStrategy;
+    /**
+     * 从扁平数组创建树形结构
+     *
+     * @category Data Structures
+     * @param list 扁平数组数据
+     * @param config 树形配置选项
+     * @returns 树形结构数组
+     * @example
+     * ```ts
+     * const flatData = [
+     *   { id: '1', name: '部门1', parentId: null },
+     *   { id: '2', name: '部门1-1', parentId: '1' },
+     *   { id: '3', name: '部门1-2', parentId: '1' },
+     *   { id: '4', name: '部门1-1-1', parentId: '2' }
+     * ]
+     *
+     * const tree = Tree.fromList(flatData, {
+     *   id: 'id',
+     *   pid: 'parentId',
+     *   children: 'children'
+     * })
+     *
+     * console.log(tree) // 转换为树形结构
+     * ```
+     */
+    static fromList<T = any>(list: T[], config?: TreeConfigInput): TreeNode<T>[];
+    /**
+     * 将树形结构转换为扁平数组
+     *
+     * @category Data Structures
+     * @param tree 树形结构（单个节点或节点数组）
+     * @param config 树形配置选项
+     * @returns 扁平数组
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     name: '根节点',
+     *     children: [
+     *       { id: '2', name: '子节点1', children: [] },
+     *       { id: '3', name: '子节点2', children: [] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const flatList = Tree.toList(tree)
+     * console.log(flatList) // [{ id: '1', name: '根节点' }, { id: '2', name: '子节点1' }, ...]
+     * ```
+     */
+    static toList<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): T[];
+    /**
+     * 估算树形结构的节点数量
+     *
+     * @category Data Structures
+     * @param tree 树形结构（单个节点或节点数组）
+     * @param config 树形配置选项
+     * @returns 节点总数量
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     name: '根节点',
+     *     children: [
+     *       { id: '2', name: '子节点1', children: [] },
+     *       { id: '3', name: '子节点2', children: [] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const size = Tree.estimateSize(tree)
+     * console.log(size) // 3
+     * ```
+     */
+    static estimateSize<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): number;
+    /**
+     * 查找树中第一个满足条件的节点
+     *
+     * @category Data Structures
+     * @param tree 树形结构（单个节点或节点数组）
+     * @param predicate 查找条件函数
+     * @param config 树形配置选项
+     * @returns 匹配的节点；未找到时返回undefined
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     name: '部门1',
+     *     children: [
+     *       { id: '2', name: '部门1-1', children: [] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const result = Tree.find(tree, ({ node }) => node.name === '部门1-1')
+     * console.log(result?.id) // '2'
+     * ```
+     */
+    static find<T = any>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNode<T> | undefined;
+    /**
+     * 查找树中所有满足条件的节点
+     *
+     * @category Data Structures
+     * @param tree 树形结构（单个节点或节点数组）
+     * @param predicate 查找条件函数
+     * @param config 树形配置选项
+     * @returns 所有匹配的节点数组
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     type: 'folder',
+     *     name: '根目录',
+     *     children: [
+     *       { id: '2', type: 'file', name: '文件1', children: [] },
+     *       { id: '3', type: 'file', name: '文件2', children: [] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const files = Tree.findAll(tree, ({ node }) => node.type === 'file')
+     * console.log(files.length) // 2
+     * ```
+     */
+    static findAll<T = any>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNode<T>[];
+    /**
+     * 根据ID查找树中的节点
+     *
+     * @category Data Structures
+     * @param tree 树形结构（单个节点或节点数组）
+     * @param id 要查找的节点ID
+     * @param config 树形配置选项
+     * @returns 匹配的节点；未找到时返回undefined
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     name: '根节点',
+     *     children: [
+     *       { id: '2', name: '子节点', children: [] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const result = Tree.findById(tree, '2')
+     * console.log(result?.name) // '子节点'
+     * ```
+     */
+    static findById<T = any>(tree: TreeNode<T> | TreeNode<T>[], id: string, config?: TreeConfigInput): TreeNode<T> | undefined;
+    /**
+     * 获取树形结构的统计信息
+     *
+     * @category Data Structures
+     * @param tree 树形结构（单个节点或节点数组）
+     * @param config 树形配置选项
+     * @returns 树的统计信息，包含总节点数、叶子节点数、最大深度和分支节点数
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     name: '根节点',
+     *     children: [
+     *       { id: '2', name: '子节点1', children: [] },
+     *       { id: '3', name: '子节点2', children: [
+     *         { id: '4', name: '孙节点', children: [] }
+     *       ] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const stats = Tree.getStats(tree)
+     * console.log(stats) // { total: 4, leaves: 2, depth: 3, branches: 2 }
+     * ```
+     */
+    static getStats<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): TreeStats;
+    /**
+     * 过滤树形结构，保留满足条件的节点及其祖先和后代
+     *
+     * @category Data Structures
+     * @param tree 树形结构（单个节点或节点数组）
+     * @param predicate 过滤条件函数，接收对象参数 {node, depth, path, index}
+     * @param config 树形配置选项
+     * @returns 过滤后的树形结构数组
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     type: 'folder',
+     *     name: '根目录',
+     *     children: [
+     *       { id: '2', type: 'file', name: '文档.txt', children: [] },
+     *       { id: '3', type: 'folder', name: '子目录', children: [
+     *         { id: '4', type: 'file', name: '图片.jpg', children: [] }
+     *       ] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const filtered = Tree.filter(tree, ({ node }) => node.type === 'file')
+     * // 返回包含所有文件节点及其父级路径的树结构
+     * ```
+     */
+    static filter<T = any>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNode<T>[];
+    /**
+     * 转换树形结构，将每个节点转换为新的结构
+     *
+     * @category Data Structures
+     * @param tree 树形结构（单个节点或节点数组）
+     * @param transformer 节点转换函数，接收对象参数 {node, depth, path, index}
+     * @param config 树形配置选项
+     * @returns 转换后的树形结构数组
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     name: '部门1',
+     *     children: [
+     *       { id: '2', name: '部门1-1', children: [] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const transformed = Tree.transform(tree, ({ node, depth }) => ({
+     *   key: node.id,
+     *   title: node.name,
+     *   level: depth
+     * }))
+     * // 转换为新的数据结构
+     * ```
+     */
+    static transform<T = any, R = any>(tree: TreeNode<T> | TreeNode<T>[], transformer: TreeTransformer<T, R>, config?: TreeConfigInput): TreeNode<R>[];
+    /**
+     * 遍历树形结构的每个节点
+     *
+     * @category Data Structures
+     * @param tree 树形结构（单个节点或节点数组）
+     * @param visitor 访问者函数，接收对象参数 {node, depth, path, index}，返回false可以跳过子节点的遍历
+     * @param config 树形配置选项
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     name: '根节点',
+     *     children: [
+     *       { id: '2', name: '子节点', children: [] }
+     *     ]
+     *   }
+     * ]
+     *
+     * Tree.forEach(tree, ({ node, depth }) => {
+     *   console.log(`${' '.repeat(depth * 2)}${node.name}`)
+     *   // 输出缩进的树结构
+     * })
+     * ```
+     */
+    static forEach<T = any>(tree: TreeNode<T> | TreeNode<T>[], visitor: TreeVisitor<T>, config?: TreeConfigInput): void;
+    /**
+     * 在指定节点前插入新节点
+     *
+     * @category Data Structures
+     * @param tree 树形结构数组
+     * @param targetId 目标节点的ID
+     * @param newNode 要插入的新节点数据
+     * @param config 树形配置选项
+     * @returns 是否成功插入
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     name: '节点1',
+     *     children: [
+     *       { id: '2', name: '节点2', children: [] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const success = Tree.insertBefore(tree, '2', { id: '1.5', name: '新节点' })
+     * console.log(success) // true
+     * ```
+     */
+    static insertBefore<T = any>(tree: TreeNode<T>[], targetId: string, newNode: T, config?: TreeConfigInput): boolean;
+    /**
+     * 在指定节点后插入新节点
+     *
+     * @category Data Structures
+     * @param tree 树形结构数组
+     * @param targetId 目标节点的ID
+     * @param newNode 要插入的新节点数据
+     * @param config 树形配置选项
+     * @returns 是否成功插入
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     name: '节点1',
+     *     children: [
+     *       { id: '2', name: '节点2', children: [] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const success = Tree.insertAfter(tree, '2', { id: '3', name: '新节点' })
+     * console.log(success) // true
+     * ```
+     */
+    static insertAfter<T = any>(tree: TreeNode<T>[], targetId: string, newNode: T, config?: TreeConfigInput): boolean;
+    /**
+     * 从树中删除指定节点
+     *
+     * @category Data Structures
+     * @param tree 树形结构数组
+     * @param targetId 要删除的节点ID
+     * @param config 树形配置选项
+     * @returns 被删除的节点，未找到时返回undefined
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     name: '根节点',
+     *     children: [
+     *       { id: '2', name: '子节点', children: [] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const removed = Tree.remove(tree, '2')
+     * console.log(removed?.name) // '子节点'
+     * ```
+     */
+    static remove<T = any>(tree: TreeNode<T>[], targetId: string, config?: TreeConfigInput): TreeNode<T> | undefined;
+    /**
+     * 验证树形结构的有效性
+     *
+     * @category Data Structures
+     * @param tree 树形结构（单个节点或节点数组）
+     * @param config 树形配置选项
+     * @returns 验证结果，包含是否有效和错误信息数组
+     * @example
+     * ```ts
+     * const tree = [
+     *   {
+     *     id: '1',
+     *     name: '根节点',
+     *     children: [
+     *       { id: '2', name: '子节点', children: [] }
+     *     ]
+     *   }
+     * ]
+     *
+     * const result = Tree.validate(tree)
+     * console.log(result.isValid) // true
+     * console.log(result.errors) // []
+     * ```
+     */
+    static validate<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): {
+        isValid: boolean;
+        errors: string[];
+    };
+}
 
 /**
  * 生成字符串的简单哈希值
@@ -1338,6 +1860,21 @@ declare function isFunction(value: any): value is (...args: any[]) => any;
  * ```
  */
 declare function isEmpty(value: any): boolean;
+/**
+ * 判断值是否为纯对象（不包括数组、函数、日期等）
+ *
+ * @category Object
+ * @param value 要检查的值
+ * @returns 是否为纯对象
+ * @example
+ * ```ts
+ * isPlainObject({}) // true
+ * isPlainObject([]) // false
+ * isPlainObject(new Date()) // false
+ * isPlainObject(() => {}) // false
+ * ```
+ */
+declare function isPlainObject(value: unknown): value is Record<string, any>;
 
-export { StorageTypeSchema, Tree, camelToKebab, capitalize, chunk, convertSvgToPng, convertToKebabCase, createStorageConfigSchema, debounce, deepClone, extractFilename, flatten, formatFileSize, getRandomUUID, isArray, isEmpty, isFunction, isNumber, isObject, isString, kebabToCamel, omit, omitUndefined, pick, replaceCurrentColor, separate, separateMany, simpleHash, sleep, sleepWithCancel, throttle, triggerDownload, unique, useAppStorage, useCopyCode };
-export type { AnyObject, ApiAwaitable, ApiAwaitedReturn, ApiUnwrapPromise, AppStorageReturn, DeepPartial, FirstParam, FirstParameter, GetObjectField, MutableByKeys, OmitByKey, PartialByKeys, PickByKey, ReadonlyByKeys, RenameKeys, RequiredByKeys, StorageConfig, StorageConfigInput, StorageType, StringOrVNode, UnionToIntersection, UnknownObject };
+export { StorageTypeSchema, Tree, camelCase, camelToKebab, capitalize, chunk, convertSvgToPng, convertToKebabCase, createStorageConfigSchema, debounce, deepClone, extractFilename, flatten, formatFileSize, getPath, getRandomUUID, isArray, isEmpty, isFunction, isNumber, isObject, isPlainObject, isString, isValidContainer, joinPath, kebabCase, kebabToCamel, lowerCase, lowerFirst, omit, omitUndefined, pascalCase, pick, replaceCurrentColor, separate, separateMany, setPath, simpleHash, sleep, sleepWithCancel, snakeCase, startCase, throttle, toPath, triggerDownload, unique, upperCase, upperFirst, useAppStorage, useCopyCode, words };
+export type { AnyObject, ApiAwaitable, ApiAwaitedReturn, ApiUnwrapPromise, AppStorageReturn, ArrayFieldKeys, ComponentAttrs, ComponentEmit, ComponentExposed, ComponentProps, ComponentSlots, ComponentType, DeepPartial, FirstParam, FirstParameter, GetFieldValue, GetObjectField, IsComponent, IsPlainObject, Merge, MutableByKeys, NestedKeys, NonObjectFieldKeys, ObjectFieldKeys, OmitByKey, PartialByKeys, PickByKey, ReactiveValue, ReadonlyByKeys, RenameKeys, RequiredByKeys, StorageConfig, StorageConfigInput, StorageType, StringOrVNode, StripNullable, Suggest, UnionToIntersection, UnknownObject };