@movk/core 0.0.3 → 0.0.5

package/dist/index.d.mts

@@ -1,37 +1,180 @@
 import { VNode, Ref } from 'vue';
 import { z } from 'zod/v4';
 
+/**
+ * 统一同步/异步返回类型
+ * @typeParam T - 类型
+ * @example
+ * // type T = string | Promise<string>
+ * // type R = ApiAwaitable<T>
+ * // 结果：R 为 string | Promise<string>
+ */
+type ApiAwaitable<T> = T | Promise<T>;
+/**
+ * 提取Promise类型
+ * @typeParam T - 类型
+ * @example
+ * // type T = Promise<string>
+ * // type R = ApiUnwrapPromise<T>
+ * // 结果：R 为 string
+ */
+type ApiUnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+/**
+ * 提取函数返回类型
+ * @typeParam TFn - 函数类型
+ * @example
+ * // type Fn = (x: number, y: string) => Promise<string>
+ * // type R = ApiAwaitedReturn<Fn>
+ * // 结果：R 为 string
+ */
+type ApiAwaitedReturn<TFn> = TFn extends (...args: any[]) => ApiAwaitable<infer R> ? R : never;
+
+type UnknownObject = Record<string, unknown>;
 type AnyObject = Record<string, any>;
+/**
+ * 依据键名从对象类型 `T` 中剔除键 `K`。
+ * @typeParam T - 源对象类型
+ * @typeParam K - 要剔除的键（必须来自 `keyof T`）
+ * @example
+ * // type User = { id: string; name: string; age: number }
+ * // type R = OmitByKey<User, 'age'>
+ * // 结果：R 为 { id: string; name: string }
+ */
 type OmitByKey<T, K extends keyof T> = {
     [P in keyof T as P extends K ? never : P]: T[P];
 };
+/**
+ * 依据键名从对象类型 `T` 中挑选键 `K`。
+ * @typeParam T - 源对象类型
+ * @typeParam K - 要保留的键（必须来自 `keyof T`）
+ * @example
+ * // type User = { id: string; name: string; age: number }
+ * // type R = PickByKey<User, 'id' | 'name'>
+ * // 结果：R 为 { id: string; name: string }
+ */
 type PickByKey<T, K extends keyof T> = {
     [P in keyof T as P extends K ? P : never]: T[P];
 };
+/**
+ * 基于映射表 `Mapping` 对对象类型 `T` 的键进行重命名。
+ * 未在映射表中的键保持原名；映射值为 `PropertyKey`（string/number/symbol）。
+ * @typeParam T - 源对象类型
+ * @typeParam Mapping - 旧键到新键名的映射
+ * @example
+ * // type Src = { a: number; b: string }
+ * // type R = RenameKeys<Src, { a: 'id' }>
+ * // 结果：R 为 { id: number; b: string }
+ */
 type RenameKeys<T, Mapping extends {
     [K in keyof T]?: PropertyKey;
 }> = {
     [K in keyof T as K extends keyof Mapping ? Exclude<Mapping[K], undefined> : K]: T[K];
 };
+/**
+ * 将对象类型 `T` 中的键 `K` 标记为必填（移除可选修饰）。
+ * @typeParam T - 源对象类型
+ * @typeParam K - 设为必填的键
+ * @example
+ * // type User = { id: string; name?: string }
+ * // type R = RequiredByKeys<User, 'name'>
+ * // 结果：R['name'] 为必填的 string
+ */
 type RequiredByKeys<T, K extends keyof T> = T & {
     [P in K]-?: T[P];
 };
+/**
+ * 将对象类型 `T` 中的键 `K` 标记为可选。
+ * @typeParam T - 源对象类型
+ * @typeParam K - 设为可选的键
+ * @example
+ * // type User = { id: string; name: string }
+ * // type R = PartialByKeys<User, 'name'>
+ * // 结果：R['name'] 为可选（可能为 undefined）
+ */
 type PartialByKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * 将对象类型 `T` 中的键 `K` 标记为只读（浅只读）。
+ * @typeParam T - 源对象类型
+ * @typeParam K - 设为只读的键
+ * @example
+ * // type User = { id: string; name: string }
+ * // type R = ReadonlyByKeys<User, 'id'>
+ * // 结果：R['id'] 不可被重新赋值
+ */
 type ReadonlyByKeys<T, K extends keyof T> = T & {
     readonly [P in K]: T[P];
 };
+/**
+ * 取消对象类型 `T` 中键 `K` 的只读限制，使其可写（浅层）。
+ * @typeParam T - 源对象类型
+ * @typeParam K - 取消只读的键
+ * @example
+ * // type User = { readonly id: string; name: string }
+ * // type R = MutableByKeys<User, 'id'>
+ * // 结果：R['id'] 变为可写
+ */
 type MutableByKeys<T, K extends keyof T> = {
     -readonly [P in K]: T[P];
 } & Omit<T, K>;
+/**
+ * 将联合类型 `U` 转换为交叉类型，用于合并联合成员的属性。
+ * @typeParam U - 联合类型
+ * @example
+ * // type U = { a: number } | { b: string }
+ * // type R = UnionToIntersection<U>
+ * // 结果：R 为 { a: number } & { b: string }
+ */
 type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? {
     [K in keyof I]: I[K];
 } : never;
+/**
+ * 若对象 `T` 在键 `K` 处的类型为元组，则提取其首个元素类型，否则为 `never`。
+ * @typeParam T - 具有元组属性的对象类型
+ * @typeParam K - 属性键
+ * @example
+ * // type Cfg = { params: [id: string, flag?: boolean] }
+ * // type R = FirstParam<Cfg, 'params'>
+ * // 结果：R 为 string
+ */
 type FirstParam<T, K extends keyof T> = T[K] extends [infer P, ...any[]] ? P : never;
+/**
+ * 从函数类型中提取首个参数类型；若 `T` 非函数类型，则为 `undefined`。
+ * @typeParam T - 函数类型
+ * @example
+ * // type Fn = (x: number, y: string) => void
+ * // type R = FirstParameter<Fn>
+ * // 结果：R 为 number；若 T 非函数，则为 undefined
+ */
 type FirstParameter<T> = T extends (arg: infer P, ...args: any[]) => any ? P : undefined;
+/**
+ * 递归将对象类型 `T` 的所有属性变为可选（深可选）。
+ * @typeParam T - 源对象类型
+ * @example
+ * // type Src = { a: { b: number } }
+ * // type R = DeepPartial<Src>
+ * // 结果：R 为 { a?: { b?: number | undefined } | undefined }
+ */
 type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P] | undefined;
 };
+/**
+ * 当 `MaybeObject` 为对象时，返回键 `Key` 对应的属性类型；否则为 `never`。
+ * @typeParam MaybeObject - 可能为对象的类型
+ * @typeParam Key - 目标键名（string）
+ * @example
+ * // type Obj = { id: number }
+ * // type R1 = GetObjectField<Obj, 'id'> // 结果：number
+ * // type R2 = GetObjectField<string, 'id'> // 结果：never
+ */
 type GetObjectField<MaybeObject, Key extends string> = MaybeObject extends Record<string, any> ? MaybeObject[Key] : never;
+/**
+ * Vue 渲染相关文本/节点类型：可为字符串、`VNode` 或返回 `VNode` 的函数。
+ * @example
+ * // 在渲染 API 中允许三种形态：
+ * // - '标题'
+ * // - h('div', '标题') 产生的 VNode
+ * // - () => h('div', '标题') 的惰性渲染函数
+ */
 type StringOrVNode = string | VNode | (() => VNode);
 
 declare const StorageTypeSchema: z.ZodEnum<{
@@ -58,35 +201,6 @@ interface AppStorageReturn<T> {
     removeItem: () => void;
 }
 
-declare const _TreeNodeBaseSchema: z.ZodRecord<z.ZodString, z.ZodAny>;
-type TreeNodeBase = z.infer<typeof _TreeNodeBaseSchema>;
-type TreeNode<T extends TreeNodeBase = TreeNodeBase> = T & {
-    [K in TreeConfig['children']]: TreeNode<T>[];
-};
-declare const TreeConfigSchema: z.ZodObject<{
-    id: z.ZodDefault<z.ZodString>;
-    pid: z.ZodDefault<z.ZodString>;
-    children: z.ZodDefault<z.ZodString>;
-}, z.core.$strip>;
-type TreeConfig = z.infer<typeof TreeConfigSchema>;
-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 extends TreeNodeBase = TreeNodeBase> {
-    readonly node: TreeNode<T>;
-    readonly path: readonly TreeNode<T>[];
-    readonly depth: number;
-    readonly index: number;
-}
-type TreePredicate<T extends TreeNodeBase = TreeNodeBase> = (node: TreeNode<T>, depth: number, path: readonly TreeNode<T>[]) => boolean;
-type TreeTransformer<T extends TreeNodeBase = TreeNodeBase, R extends TreeNodeBase = TreeNodeBase> = (node: TreeNode<T>, depth: number, path: readonly TreeNode<T>[]) => R;
-type TreeVisitor<T extends TreeNodeBase = TreeNodeBase> = (node: TreeNode<T>, depth: number, path: readonly TreeNode<T>[]) => void | boolean;
-
 /**
  * 应用存储管理的组合式函数，支持localStorage和sessionStorage
  *
@@ -170,36 +284,32 @@ declare function useAppStorage<T = unknown>(config: StorageConfigInput<T>): AppS
  */
 declare function useCopyCode(text: string): Promise<boolean>;
 
-/**
- * 树形数据结构操作类，提供树形数据的各种操作方法
- *
- * @category Data Structures
- * @example
- * ```ts
- * // 从扁平数组创建树形结构
- * const flatList = [
- *   { id: '1', name: '根节点', pid: null },
- *   { id: '2', name: '子节点1', pid: '1' },
- *   { id: '3', name: '子节点2', pid: '1' },
- *   { id: '4', name: '孙节点', pid: '2' }
- * ]
- *
- * const tree = Tree.fromList(flatList)
- * console.log(tree) // 树形结构
- *
- * // 查找节点
- * const found = Tree.find(tree, (node) => node.name === '子节点1')
- *
- * // 过滤节点
- * const filtered = Tree.filter(tree, (node) => node.name.includes('子'))
- *
- * // 转换树形结构
- * const transformed = Tree.transform(tree, (node) => ({
- *   ...node,
- *   displayName: `[${node.name}]`
- * }))
- * ```
- */
+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;
@@ -229,7 +339,7 @@ declare class Tree {
      * console.log(tree) // 转换为树形结构
      * ```
      */
-    static fromList<T extends TreeNodeBase>(list: T[], config?: TreeConfigInput): TreeNode<T>[];
+    static fromList<T = any>(list: T[], config?: TreeConfigInput): TreeNode<T>[];
     /**
      * 将树形结构转换为扁平数组
      *
@@ -254,124 +364,328 @@ declare class Tree {
      * console.log(flatList) // [{ id: '1', name: '根节点' }, { id: '2', name: '子节点1' }, ...]
      * ```
      */
-    static toList<T extends TreeNodeBase>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): T[];
-    static estimateSize<T extends TreeNodeBase>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): number;
-    static find<T extends TreeNodeBase>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNodeResult<T> | undefined;
-    static findAll<T extends TreeNodeBase>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNodeResult<T>[];
-    static findById<T extends TreeNodeBase>(tree: TreeNode<T> | TreeNode<T>[], id: string, config?: TreeConfigInput): TreeNodeResult<T> | undefined;
-    static getStats<T extends TreeNodeBase>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): TreeStats;
-    static filter<T extends TreeNodeBase>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNode<T>[];
-    static transform<T extends TreeNodeBase, R extends TreeNodeBase>(tree: TreeNode<T> | TreeNode<T>[], transformer: TreeTransformer<T, R>, config?: TreeConfigInput): TreeNode<R>[];
-    static forEach<T extends TreeNodeBase>(tree: TreeNode<T> | TreeNode<T>[], visitor: TreeVisitor<T>, config?: TreeConfigInput): void;
-    static insertBefore<T extends TreeNodeBase>(tree: TreeNode<T>[], targetId: string, newNode: T, config?: TreeConfigInput): boolean;
-    static insertAfter<T extends TreeNodeBase>(tree: TreeNode<T>[], targetId: string, newNode: T, config?: TreeConfigInput): boolean;
-    static remove<T extends TreeNodeBase>(tree: TreeNode<T>[], targetId: string, config?: TreeConfigInput): TreeNode<T> | undefined;
-    static validate<T extends TreeNodeBase>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): {
+    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[];
     };
 }
 
-/**
- * UnoCSS Flex布局预设，提供便捷的flex布局工具类
- *
- * @category Framework
- * @returns UnoCSS预设配置对象
- * @example
- * ```ts
- * // 在unocss.config.ts中使用
- * import { presetFlex } from '@movk/core'
- *
- * export default defineConfig({
- *   presets: [
- *     presetFlex(),
- *     // 其他预设...
- *   ]
- * })
- *
- * // 在HTML中使用生成的类名
- * <div class="flex-row-center-center">居中的flex容器</div>
- * <div class="flex-col-between-start">纵向分散对齐</div>
- * <div class="flex-center">完全居中</div>
- * <div class="flex-x-center">水平居中</div>
- * <div class="flex-y-center">垂直居中</div>
- * ```
- */
-declare function presetFlex(): {
-    name: string;
-    rules: ((RegExp | (([, d, j, a]: string[], { rawSelector }: {
-        rawSelector: string;
-    }) => Record<string, string>) | {
-        autocomplete: string;
-    })[] | (string | {
-        display: string;
-        'justify-content': string;
-        'align-items': string;
-    })[])[];
-    shortcuts: {
-        'flex-x-center': string;
-        'flex-y-center': string;
-        'inline-flex-x-center': string;
-        'inline-flex-y-center': string;
-    }[];
-};
-
-interface RuleContext {
-    rawSelector: string;
-}
-/**
- * UnoCSS 猫头鹰选择器预设，提供基于相邻兄弟选择器的间距和分隔符工具类
- *
- * @category Framework
- * @returns UnoCSS预设配置对象
- * @example
- * ```ts
- * // 在unocss.config.ts中使用
- * import { presetOwl } from '@movk/core'
- *
- * export default defineConfig({
- *   presets: [
- *     presetOwl(),
- *     // 其他预设...
- *   ]
- * })
- *
- * // 在HTML中使用生成的类名
- * <div class="owl-y-4">
- *   <div>项目1</div>
- *   <div>项目2</div>  <!-- 上边距 1rem -->
- *   <div>项目3</div>  <!-- 上边距 1rem -->
- * </div>
- *
- * <div class="owl-x-2">
- *   <span>按钮1</span>
- *   <span>按钮2</span>  <!-- 左边距 0.5rem -->
- *   <span>按钮3</span>  <!-- 左边距 0.5rem -->
- * </div>
- *
- * <div class="owl-divide-gray-200">
- *   <div>列表项1</div>
- *   <div>列表项2</div>  <!-- 上边框分隔线 -->
- *   <div>列表项3</div>  <!-- 上边框分隔线 -->
- * </div>
- * ```
- */
-declare function presetOwl(): {
-    name: string;
-    rules: (RegExp | (([, value]: string[], { rawSelector }: RuleContext) => string | undefined) | {
-        autocomplete: string;
-    })[][];
-    shortcuts: {
-        'owl-stack': string;
-        'owl-stack-tight': string;
-        'owl-stack-loose': string;
-        'owl-list': string;
-        'owl-list-tight': string;
-        'owl-nav': string;
-        'owl-card-stack': string;
-    }[];
-};
-
 /**
  * 数组去重，返回去除重复元素后的新数组
  *
@@ -789,10 +1103,6 @@ declare function omitUndefined<T extends AnyObject>(obj: T): Partial<T>;
  */
 declare function pick<T extends AnyObject, K extends keyof T>(obj: T, keys: K[]): PickByKey<T, K>;
 
-interface SeparateResult<T extends AnyObject, K extends keyof T> {
-    picked: PickByKey<T, K>;
-    omitted: OmitByKey<T, K>;
-}
 /**
  * 将对象按指定键分离为两个对象
  *
@@ -818,7 +1128,35 @@ interface SeparateResult<T extends AnyObject, K extends keyof T> {
  * const { picked: publicData, omitted: privateData } = separate(user, ['id', 'name', 'email'])
  * ```
  */
-declare function separate<T extends AnyObject, K extends keyof T>(obj: T, keys: K[]): SeparateResult<T, K>;
+declare function separate<T extends AnyObject, K extends keyof T>(obj: T, keys: K[]): {
+    picked: PickByKey<T, K>;
+    omitted: OmitByKey<T, K>;
+};
+/**
+ * 将对象按多分组键集合进行分离（浅层），返回各分组与 others
+ *
+ * - 键冲突策略：先到先得。若同一键出现在多个分组中，则归入第一个匹配到的分组
+ * - 仅处理对象自有的浅层键，不解析深层路径
+ * - 分组中包含不存在于对象的键将被忽略
+ *
+ * @category Object
+ * @param obj 源对象
+ * @param groups 分组映射，如 { a: ['x', 'y'], b: ['z'] }
+ * @returns 一个对象，包含每个分组的子对象以及 others（其余未被分组捕获的键）
+ * @example
+ * ```ts
+ * const options = { id: 1, name: 'John', email: 'a@b.com', role: 'admin' }
+ * const { a, b, others } = separateMany(options, { a: ['id'], b: ['name'] as const })
+ * // a: { id: 1 }
+ * // b: { name: 'John' }
+ * // others: { email: 'a@b.com', role: 'admin' }
+ * ```
+ */
+declare function separateMany<T extends AnyObject, M extends Record<string, readonly (keyof T)[]>>(obj: T, groups: M): {
+    [P in keyof M]: PickByKey<T, M[P][number]>;
+} & {
+    others: OmitByKey<T, M[keyof M][number]>;
+};
 
 /**
  * 将字符串首字母大写
@@ -1001,5 +1339,5 @@ declare function isFunction(value: any): value is (...args: any[]) => any;
  */
 declare function isEmpty(value: any): boolean;
 
-export { StorageTypeSchema, Tree, TreeConfigSchema, TreeStatsSchema, camelToKebab, capitalize, chunk, convertSvgToPng, convertToKebabCase, createStorageConfigSchema, debounce, deepClone, extractFilename, flatten, formatFileSize, getRandomUUID, isArray, isEmpty, isFunction, isNumber, isObject, isString, kebabToCamel, omit, omitUndefined, pick, presetFlex, presetOwl, replaceCurrentColor, separate, simpleHash, sleep, sleepWithCancel, throttle, triggerDownload, unique, useAppStorage, useCopyCode };
-export type { AnyObject, AppStorageReturn, DeepPartial, FirstParam, FirstParameter, GetObjectField, MutableByKeys, OmitByKey, PartialByKeys, PickByKey, ReadonlyByKeys, RenameKeys, RequiredByKeys, StorageConfig, StorageConfigInput, StorageType, StringOrVNode, TreeConfig, TreeConfigInput, TreeNode, TreeNodeBase, TreeNodeResult, TreePredicate, TreeStats, TreeTransformer, TreeVisitor, UnionToIntersection };
+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 };