@movk/core 1.0.2 → 1.1.0

package/dist/index.d.mts

@@ -1,1790 +1,2339 @@
-import { MaybeRefOrGetter, VNode, Ref, Component, DefineComponent } from 'vue';
-import { z } from 'zod/v4';
+import { Ref, VNode, MaybeRefOrGetter, Component, DefineComponent } from 'vue';
+
+type StorageType = 'localStorage' | 'sessionStorage';
+interface StorageConfig<T = unknown> {
+    key: string;
+    defaultValue: T;
+    prefix: string;
+    storage: StorageType;
+}
+type StorageConfigInput<T = unknown> = Partial<Omit<StorageConfig<T>, 'key' | 'defaultValue'>> & {
+    key: string;
+    defaultValue: T;
+};
+interface AppStorageReturn<T> {
+    state: Ref<T>;
+    getItem: () => T;
+    setItem: (value: T) => void;
+    removeItem: () => void;
+}
+
+/**
+ * 应用存储管理的组合式函数，支持 localStorage 和 sessionStorage
+ *
+ * @category Composables
+ * @param config 存储配置对象
+ * @returns 存储管理对象，包含响应式状态和操作方法
+ * @example
+ * ```ts
+ * // 创建存储管理实例
+ * const { state, setItem, getItem, removeItem } = useAppStorage({
+ *   key: 'user-preferences',
+ *   defaultValue: {
+ *     theme: 'light',
+ *     language: 'zh-CN',
+ *     fontSize: 16
+ *   },
+ *   storage: 'localStorage',
+ *   prefix: 'app'
+ * })
+ *
+ * // 使用响应式状态
+ * console.log(state.value.theme) // 'light'
+ *
+ * // 更新设置
+ * setItem({
+ *   theme: 'dark',
+ *   language: 'en-US',
+ *   fontSize: 18
+ * })
+ * ```
+ */
+declare function useAppStorage<T = unknown>(config: StorageConfigInput<T>): AppStorageReturn<T>;
+
+/**
+ * 复制文本到剪贴板的组合式函数
+ *
+ * @category Composables
+ * @param text 要复制的文本内容
+ * @returns 复制是否成功的Promise
+ * @example
+ * ```ts
+ * // 复制简单文本
+ * const copyText = async () => {
+ *   const success = await useCopyCode('Hello, World!')
+ *   if (success) {
+ *     console.log('复制成功')
+ *   } else {
+ *     console.log('复制失败')
+ *   }
+ * }
+ *
+ * // 复制代码块
+ * const copyCodeBlock = async () => {
+ *   const code = `
+ *   function hello() {
+ *     console.log('Hello, World!')
+ *   }
+ *   `
+ *   const success = await useCopyCode(code)
+ *   if (success) {
+ *     // 显示复制成功提示
+ *     showNotification('代码已复制到剪贴板')
+ *   }
+ * }
+ *
+ * // 在点击事件中使用
+ * const handleCopy = () => {
+ *   useCopyCode(document.getElementById('code').textContent)
+ * }
+ * ```
+ */
+declare function useCopyCode(text: string): Promise<boolean>;
+
+/**
+ * 将SVG字符串转换为PNG格式的Blob对象
+ *
+ * @category File
+ * @param svg SVG字符串
+ * @returns PNG格式的Blob对象
+ * @throws 当SVG无效或转换失败时抛出错误
+ * @example
+ * ```ts
+ * const svgString = '<svg width="100" height="100"><circle cx="50" cy="50" r="40" fill="red"/></svg>'
+ *
+ * try {
+ *   const pngBlob = await convertSvgToPng(svgString)
+ *   const url = URL.createObjectURL(pngBlob)
+ *
+ *   // 用于下载或显示
+ *   const img = document.createElement('img')
+ *   img.src = url
+ *   document.body.appendChild(img)
+ * } catch (error) {
+ *   console.error('SVG转换失败:', error)
+ * }
+ * ```
+ */
+declare function convertSvgToPng(svg: string): Promise<Blob>;
+
+/**
+ * 从响应头中提取文件名
+ *
+ * @category File
+ * @param headers 响应头对象
+ * @param fallbackName 默认文件名
+ * @returns 提取的文件名
+ * @example
+ * ```ts
+ * // 从响应头中提取文件名
+ * const headers = new Headers({
+ *   'content-disposition': 'attachment; filename="report.pdf"'
+ * })
+ * const filename = extractFilename(headers, 'download')
+ * console.log(filename) // 'report.pdf'
+ *
+ * // 处理编码的文件名
+ * const encodedHeaders = new Headers({
+ *   'content-disposition': 'attachment; filename*=UTF-8\'\'%E6%8A%A5%E5%91%8A.pdf'
+ * })
+ * const encodedFilename = extractFilename(encodedHeaders)
+ * console.log(encodedFilename) // '报告.pdf'
+ * ```
+ */
+declare function extractFilename(headers?: Headers, fallbackName?: string): string;
+
+/**
+ * 格式化文件大小，将字节数转换为可读的文件大小字符串
+ *
+ * @category File
+ * @param bytes 文件大小（字节）
+ * @returns 格式化后的文件大小字符串
+ * @example
+ * ```ts
+ * console.log(formatFileSize(1024)) // '1 KB'
+ * console.log(formatFileSize(1536)) // '1.5 KB'
+ * console.log(formatFileSize(1048576)) // '1 MB'
+ * console.log(formatFileSize(1073741824)) // '1 GB'
+ *
+ * // 处理边界情况
+ * console.log(formatFileSize(0)) // '0 Bytes'
+ * console.log(formatFileSize(-100)) // '0 Bytes'
+ * ```
+ */
+declare function formatFileSize(bytes: number): string;
+
+/**
+ * 替换SVG文件中的currentColor为指定颜色
+ *
+ * @category File
+ * @param path SVG文件路径
+ * @param color 替换的颜色值，不提供则返回原始SVG
+ * @returns 处理后的SVG字符串
+ * @throws 当文件获取失败或SVG无效时抛出错误
+ * @example
+ * ```ts
+ * // 获取并替换SVG中的currentColor
+ * try {
+ *   const svgContent = await replaceCurrentColor('/icons/star.svg', '#ff0000')
+ *   const container = document.createElement('div')
+ *   container.innerHTML = svgContent
+ *   document.body.appendChild(container)
+ * } catch (error) {
+ *   console.error('SVG处理失败:', error)
+ * }
+ *
+ * // 只获取SVG内容，不替换颜色
+ * const originalSvg = await replaceCurrentColor('/icons/star.svg')
+ * ```
+ */
+declare function replaceCurrentColor(path: string, color?: string): Promise<string>;
+
+/**
+ * 触发浏览器下载文件
+ *
+ * @category File
+ * @param blob 文件数据
+ * @param filename 文件名
+ * @example
+ * ```ts
+ * // 下载文本文件
+ * const textBlob = new Blob(['Hello, World!'], { type: 'text/plain' })
+ * triggerDownload(textBlob, 'hello.txt')
+ *
+ * // 下载JSON数据
+ * const data = { name: 'John', age: 30 }
+ * const jsonBlob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' })
+ * triggerDownload(jsonBlob, 'data.json')
+ *
+ * // 下载图片
+ * const canvas = document.createElement('canvas')
+ * canvas.toBlob((blob) => {
+ *   if (blob) {
+ *     triggerDownload(blob, 'image.png')
+ *   }
+ * })
+ * ```
+ */
+declare function triggerDownload(blob: Blob, filename: string): void;
+
+/**
+ * 深拷贝任意 JavaScript 值。
+ *
+ * - 优先使用原生 `structuredClone`（若可用），覆盖 `Map`/`Set`/`TypedArray`/`ArrayBuffer` 等内建类型。
+ * - 对不支持 `structuredClone` 的环境，使用回退实现：
+ *   - 支持循环引用（`WeakMap` 记忆化）。
+ *   - 保留原型与属性描述符（含 getter/setter），复制 symbol 键。
+ *   - 内建类型专项处理：`Date`/`RegExp`/`Map`/`Set`/`ArrayBuffer`/`TypedArray`/`URL`/`Error`。
+ *
+ * @category Object
+ * @typeParam T 拷贝值的类型
+ * @param obj 要被深拷贝的值
+ * @param cache 内部使用的 `WeakMap`（循环引用记忆化），一般不需要传入
+ * @returns 新的深拷贝值，与输入值结构等价、引用独立
+ *
+ * @example
+ * ```ts
+ * 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, cache?: WeakMap<object, any>): T;
+
+type UnknownObject = Record<string, unknown>;
+type AnyObject = Record<string, any>;
+/**
+ * Vue 渲染相关文本/节点类型: 可为字符串、`VNode` 或返回 `VNode` 的函数。
+ * @example
+ * // 在渲染 API 中允许三种形态:
+ * // - '标题'
+ * // - h('div', '标题') 产生的 VNode
+ * // - () => 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> = NonNullable<T> extends Record<string, any> ? NonNullable<T> extends any[] ? false : NonNullable<T> extends (...args: any[]) => any ? false : NonNullable<T> extends Date ? false : true : false;
+
+/**
+ * 递归将对象类型 `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;
+};
+
+/**
+ * 深度控制类型，用于限制类型递归的深度
+ * 防止类型计算超出 TypeScript 的递归限制
+ */
+type Depth = [never, 0, 1, 2, 3, 4];
+/**
+ * 当 `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;
+/**
+ * 提取对象的嵌套键，支持点语法路径
+ *
+ * @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<NonNullable<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<NonNullable<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]: NonNullable<T[K]> extends any[] ? K : IsPlainObject<T[K]> extends true ? `${K}.${ArrayFieldKeys<NonNullable<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;
+
+/**
+ * 依据键名从对象类型 `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;
+
+/**
+ * 从对象中排除指定的键，返回新对象
+ *
+ * @category Object
+ * @param obj 源对象
+ * @param keys 要排除的键数组
+ * @returns 排除指定键后的新对象
+ * @example
+ * ```ts
+ * const user = {
+ *   id: 1,
+ *   name: 'John',
+ *   password: 'secret',
+ *   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>;
+
+/**
+ * 从对象中选择指定的键，返回新对象
+ *
+ * @category Object
+ * @param obj 源对象
+ * @param keys 要选择的键数组
+ * @returns 只包含指定键的新对象
+ * @example
+ * ```ts
+ * const user = {
+ *   id: 1,
+ *   name: 'John',
+ *   email: 'john@example.com',
+ *   password: 'secret',
+ *   createdAt: '2023-01-01',
+ *   updatedAt: '2023-01-15'
+ * }
+ *
+ * const publicInfo = pick(user, ['id', 'name', 'email'])
+ * console.log(publicInfo) // { id: 1, name: 'John', email: 'john@example.com' }
+ *
+ * const basicInfo = pick(user, ['id', 'name'])
+ * console.log(basicInfo) // { id: 1, name: 'John' }
+ * ```
+ */
+declare function pick<T extends AnyObject, K extends keyof T>(obj: T, keys: K[]): PickByKey<T, K>;
+
+/**
+ * 将对象按指定键分离为两个对象
+ *
+ * @category Object
+ * @param obj 源对象
+ * @param keys 要分离的键数组
+ * @returns 包含picked和omitted两个对象的结果
+ * @example
+ * ```ts
+ * const user = {
+ *   id: 1,
+ *   name: 'John',
+ *   email: 'john@example.com',
+ *   password: 'secret',
+ *   role: 'admin'
+ * }
+ *
+ * const { picked, omitted } = separate(user, ['id', 'name'])
+ * console.log(picked) // { id: 1, name: 'John' }
+ * console.log(omitted) // { email: 'john@example.com', password: 'secret', role: 'admin' }
+ *
+ * // 用于分离敏感信息
+ * const { picked: publicData, omitted: privateData } = separate(user, ['id', 'name', 'email'])
+ * ```
+ */
+declare function separate<T extends AnyObject, K extends keyof T>(obj: T, keys: K[]): {
+    picked: PickByKey<T, K>;
+    omitted: OmitByKey<T, K>;
+};
 
 /**
- * 统一同步/异步返回类型
- * @typeParam T - 类型
+ * 将对象按多分组键集合进行分离（浅层），返回各分组与 others
+ *
+ * - 键冲突策略：先到先得。若同一键出现在多个分组中，则归入第一个匹配到的分组
+ * - 仅处理对象自有的浅层键，不解析深层路径
+ * - 分组中包含不存在于对象的键将被忽略
+ *
+ * @category Object
+ * @param obj 源对象
+ * @param groups 分组映射，如 { a: ['x', 'y'], b: ['z'] }
+ * @returns 一个对象，包含每个分组的子对象以及 others（其余未被分组捕获的键）
  * @example
- * // type T = string | Promise<string>
- * // type R = ApiAwaitable<T>
- * // 结果：R 为 string | Promise<string>
+ * ```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' }
+ * ```
  */
-type ApiAwaitable<T> = T | Promise<T>;
+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]>;
+};
+
+type PathSegment = string | number;
+type PathSegments = PathSegment[];
+type PathInput = string | PathSegments;
 /**
- * 提取Promise类型
- * @typeParam T - 类型
+ * 将路径字符串解析为片段数组。
+ *
+ * - 支持点语法与方括号语法混用
+ * - 引号键支持单/双引号与反斜杠转义
+ * - 方括号内未引号的非负整数字面量解析为 number 段
+ * - 点语法中的纯数字段保持字符串(不转为索引)
+ *
+ * @category Path
+ * @param path 路径字符串或片段数组
+ * @returns 解析后的片段数组
  * @example
- * // type T = Promise<string>
- * // type R = ApiUnwrapPromise<T>
- * // 结果：R 为 string
+ * ```ts
+ * toPath('a.b[0].c') // ['a', 'b', 0, 'c']
+ * toPath("a['x.y']") // ['a', 'x.y']
+ * ```
  */
-type ApiUnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+declare function toPath(path: PathInput): PathSegments;
+
 /**
- * 提取函数返回类型
- * @typeParam TFn - 函数类型
+ * 读取对象指定路径的值。
+ *
+ * - 若取值结果为 undefined,则返回 defaultValue
+ * - 若取值结果为 null,则直接返回 null(不触发默认值)
+ * - 传入空路径时返回 object 本身
+ *
+ * @category Path
+ * @param object 源对象
+ * @param path 路径字符串或片段数组
+ * @param defaultValue 结果为 undefined 时返回的默认值
+ * @returns 读取到的值或默认值
  * @example
- * // type Fn = (x: number, y: string) => Promise<string>
- * // type R = ApiAwaitedReturn<Fn>
- * // 结果：R 为 string
+ * ```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 getPath<T, D = undefined>(object: T, path: PathInput, defaultValue?: D): unknown | D;
+
+/**
+ * 将片段数组序列化为路径字符串。
+ *
+ * 规则:
+ * - 合法标识符段使用点拼接(a.b.c)
+ * - 数字段转为索引([0])
+ * - 其它需要转义的键使用方括号引号(['x.y']),并转义 \\ 与 '\''
+ *
+ * @category Path
+ * @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 joinPath(segments: (string | number)[]): string;
+
+/**
+ * 在对象指定路径写入值。缺失路径会被自动创建:
+ * - 下一段为 number(索引)时创建数组
+ * - 下一段为 string(属性)时创建对象
+ *
+ * 若中途遇到非容器类型(如字符串/数值/布尔),会被替换为正确的容器以继续写入。
+ *
+ * @category Path
+ * @param object 目标对象(原地修改并返回同一引用)
+ * @param path 路径字符串或片段数组
+ * @param value 要写入的值
+ * @returns 原对象(已修改)
+ * @example
+ * ```ts
+ * 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;
+
+/**
+ * 生成字符串的简单哈希值
+ *
+ * @category Helpers
+ * @param str 待哈希的字符串
+ * @returns 32位哈希值转换为36进制字符串
+ * @example
+ * ```ts
+ * const hash1 = simpleHash('hello world')
+ * console.log(hash1) // 'nf5xd4'
+ *
+ * const hash2 = simpleHash('hello world')
+ * console.log(hash1 === hash2) // true，相同字符串产生相同哈希
+ *
+ * const hash3 = simpleHash('hello world!')
+ * console.log(hash1 === hash3) // false，不同字符串产生不同哈希
+ * ```
+ */
+declare function simpleHash(str: string): string;
+
+/**
+ * 生成随机UUID字符串
+ *
+ * @category Helpers
+ * @returns 符合UUID v4格式的随机字符串
+ * @example
+ * ```ts
+ * const id1 = getRandomUUID()
+ * console.log(id1) // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+ *
+ * const id2 = getRandomUUID()
+ * console.log(id2) // 'f47ac10b-58cc-4372-a567-0e02b2c3d480'
+ *
+ * // 用于生成唯一标识符
+ * const componentId = `component-${getRandomUUID()}`
+ * ```
+ */
+declare function getRandomUUID(): string;
+
+/**
+ * 将对象的键名转换为kebab-case格式
+ *
+ * @category Object
+ * @param obj 待转换的对象
+ * @param deep 是否深度转换嵌套对象，默认为false
+ * @returns 转换后的对象
+ * @example
+ * ```ts
+ * const obj = {
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   userInfo: {
+ *     birthDate: '1990-01-01',
+ *     phoneNumber: '123-456-7890'
+ *   }
+ * }
+ *
+ * const converted = convertToKebabCase(obj)
+ * console.log(converted)
+ * // {
+ * //   'first-name': 'John',
+ * //   'last-name': 'Doe',
+ * //   'user-info': { birthDate: '1990-01-01', phoneNumber: '123-456-7890' }
+ * // }
+ *
+ * const deepConverted = convertToKebabCase(obj, true)
+ * console.log(deepConverted)
+ * // {
+ * //   'first-name': 'John',
+ * //   'last-name': 'Doe',
+ * //   'user-info': { 'birth-date': '1990-01-01', 'phone-number': '123-456-7890' }
+ * // }
+ * ```
+ */
+declare function convertToKebabCase<T extends AnyObject>(obj: T, deep?: boolean): T;
+
+/**
+ * 将字符串转换为驼峰命名格式（第一个单词小写，后续单词首字母大写）。
+ *
+ * @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;
+
+/**
+ * 将字符串首字母大写，其余字母小写。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 首字母大写的字符串
+ * @example
+ * ```ts
+ * 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
+ * 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;
+
+/**
+ * 将字符串转换为小写格式，单词之间用空格分隔。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 小写格式的字符串
+ * @example
+ * ```ts
+ * lowerCase('firstName') // 'first name'
+ * lowerCase('First_Name') // 'first name'
+ * lowerCase('FIRST-NAME') // 'first name'
+ * lowerCase('XMLHttpRequest') // 'xml http request'
+ * ```
  */
-type ApiAwaitedReturn<TFn> = TFn extends (...args: any[]) => ApiAwaitable<infer R> ? R : never;
+declare function lowerCase(str: string): string;
 
 /**
- * 提供字符串字面量提示的同时允许任意字符串
- * 在 IDE 中提供 T 类型的自动补全提示，但不限制只能使用这些值
+ * 将字符串首字母小写，其余字母保持原样。
  *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 首字母小写的字符串
  * @example
  * ```ts
- * type Color = Suggest<'red' | 'blue' | 'green'>
- *
- * // IDE 会提示 'red', 'blue', 'green'，但也可以使用其他字符串
- * const color1: Color = 'red'    // 有提示
- * const color2: Color = 'yellow' // 也可以，虽然没有提示
+ * lowerFirst('Hello') // 'hello'
+ * lowerFirst('HELLO') // 'hELLO'
+ * lowerFirst('Hello World') // 'hello World'
  * ```
  */
-type Suggest<T extends string> = T | (string & {});
+declare function lowerFirst(str: string): string;
+
 /**
- * 响应式值类型 - 基于 Vue 的 `MaybeRefOrGetter` 扩展，额外支持上下文回调
- *
- * @template T - 值类型
- * @template CTX - 上下文类型（用于回调函数）
+ * 将字符串转换为帕斯卡命名格式（PascalCase，每个单词首字母大写）。
  *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 帕斯卡命名格式的字符串
  * @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
+ * pascalCase('firstName') // 'FirstName'
+ * pascalCase('first_name') // 'FirstName'
+ * pascalCase('first-name') // 'FirstName'
+ * pascalCase('XMLHttpRequest') // 'XmlHttpRequest'
  * ```
  */
-type ReactiveValue<T, CTX = never> = [CTX] extends [never] ? MaybeRefOrGetter<T> : MaybeRefOrGetter<T> | ((ctx: CTX) => T);
-type StripNullable<T> = T extends null | undefined ? never : T;
+declare function pascalCase(str: string): string;
 
-type UnknownObject = Record<string, unknown>;
-type AnyObject = Record<string, any>;
 /**
- * 依据键名从对象类型 `T` 中剔除键 `K`。
- * @typeParam T - 源对象类型
- * @typeParam K - 要剔除的键（必须来自 `keyof T`）
+ * 将字符串转换为下划线命名格式（snake_case）。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 下划线命名格式的字符串
  * @example
- * // type User = { id: string; name: string; age: number }
- * // type R = OmitByKey<User, 'age'>
- * // 结果：R 为 { id: string; name: string }
+ * ```ts
+ * snakeCase('firstName') // 'first_name'
+ * snakeCase('First Name') // 'first_name'
+ * snakeCase('first-name') // 'first_name'
+ * snakeCase('XMLHttpRequest') // 'xml_http_request'
+ * ```
  */
-type OmitByKey<T, K extends keyof T> = {
-    [P in keyof T as P extends K ? never : P]: T[P];
-};
+declare function snakeCase(str: string): string;
+
 /**
- * 依据键名从对象类型 `T` 中挑选键 `K`。
- * @typeParam T - 源对象类型
- * @typeParam K - 要保留的键（必须来自 `keyof T`）
+ * 将字符串转换为Start Case格式（每个单词首字母大写，用空格分隔）。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns Start Case格式的字符串
  * @example
- * // type User = { id: string; name: string; age: number }
- * // type R = PickByKey<User, 'id' | 'name'>
- * // 结果：R 为 { id: string; name: string }
+ * ```ts
+ * startCase('firstName') // 'First Name'
+ * startCase('first_name') // 'First Name'
+ * startCase('first-name') // 'First Name'
+ * startCase('XMLHttpRequest') // 'XML Http Request'
+ * ```
  */
-type PickByKey<T, K extends keyof T> = {
-    [P in keyof T as P extends K ? P : never]: T[P];
-};
+declare function startCase(str: string): string;
+
 /**
- * 基于映射表 `Mapping` 对对象类型 `T` 的键进行重命名。
- * 未在映射表中的键保持原名；映射值为 `PropertyKey`（string/number/symbol）。
- * @typeParam T - 源对象类型
- * @typeParam Mapping - 旧键到新键名的映射
+ * 将字符串转换为大写格式，单词之间用空格分隔。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 大写格式的字符串
  * @example
- * // type Src = { a: number; b: string }
- * // type R = RenameKeys<Src, { a: 'id' }>
- * // 结果：R 为 { id: number; b: string }
+ * ```ts
+ * upperCase('firstName') // 'FIRST NAME'
+ * upperCase('first_name') // 'FIRST NAME'
+ * upperCase('first-name') // 'FIRST NAME'
+ * upperCase('XMLHttpRequest') // 'XML HTTP REQUEST'
+ * ```
  */
-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];
-};
+declare function upperCase(str: string): string;
+
 /**
- * 将对象类型 `T` 中的键 `K` 标记为必填（移除可选修饰）。
- * @typeParam T - 源对象类型
- * @typeParam K - 设为必填的键
+ * 将字符串首字母大写，其余字母保持原样。
+ *
+ * @category String
+ * @param str 要转换的字符串
+ * @returns 首字母大写的字符串
  * @example
- * // type User = { id: string; name?: string }
- * // type R = RequiredByKeys<User, 'name'>
- * // 结果：R['name'] 为必填的 string
+ * ```ts
+ * upperFirst('hello') // 'Hello'
+ * upperFirst('hELLO') // 'HELLO'
+ * upperFirst('hello world') // 'Hello world'
+ * ```
  */
-type RequiredByKeys<T, K extends keyof T> = T & {
-    [P in K]-?: T[P];
-};
+declare function upperFirst(str: string): string;
+
 /**
- * 将对象类型 `T` 中的键 `K` 标记为可选。
- * @typeParam T - 源对象类型
- * @typeParam K - 设为可选的键
+ * 将字符串分解为单词数组。支持camelCase、snake_case、kebab-case等各种命名风格。
+ *
+ * @category String
+ * @param str 要分解的字符串
+ * @returns 单词数组
  * @example
- * // type User = { id: string; name: string }
- * // type R = PartialByKeys<User, 'name'>
- * // 结果：R['name'] 为可选（可能为 undefined）
+ * ```ts
+ * words('helloWorld') // ['hello', 'World']
+ * words('hello_world') // ['hello', 'world']
+ * words('hello-world') // ['hello', 'world']
+ * words('XMLHttpRequest') // ['XML', 'Http', 'Request']
+ * ```
  */
-type PartialByKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+declare function words(str: string): string[];
+
 /**
- * 将对象类型 `T` 中的键 `K` 标记为只读（浅只读）。
- * @typeParam T - 源对象类型
- * @typeParam K - 设为只读的键
- * @example
- * // type User = { id: string; name: string }
- * // type R = ReadonlyByKeys<User, 'id'>
- * // 结果：R['id'] 不可被重新赋值
+ * 树节点类型定义
+ *
+ * @template T 节点数据类型
  */
-type ReadonlyByKeys<T, K extends keyof T> = T & {
-    readonly [P in K]: T[P];
+type TreeNode<T = any> = T & {
+    children?: TreeNode<T>[];
+    [key: string]: any;
 };
 /**
- * 取消对象类型 `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;
+interface TreeConfig {
+    id: string;
+    pid: string;
+    children: string;
+}
 /**
- * 若对象 `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;
+type TreeConfigInput = Partial<TreeConfig>;
 /**
- * 从函数类型中提取首个参数类型；若 `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;
+interface TreeStats {
+    total: number;
+    leaves: number;
+    depth: number;
+    branches: number;
+}
 /**
- * 递归将对象类型 `T` 的所有属性变为可选（深可选）。
- * @typeParam T - 源对象类型
- * @example
- * // type Src = { a: { b: number } }
- * // type R = DeepPartial<Src>
- * // 结果：R 为 { a?: { b?: number | undefined } | undefined }
+ * 树节点谓词函数类型
+ *
+ * @template T 节点数据类型
+ * @param params 包含节点信息的对象参数
+ * @param params.node 当前节点
+ * @param params.depth 节点深度（从0开始）
+ * @param params.path 从根节点到当前节点的路径数组
+ * @param params.index 节点在同级节点中的索引
+ * @returns 是否满足条件
  */
-type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P] | undefined;
-};
+type TreePredicate<T = any> = (params: {
+    node: TreeNode<T>;
+    depth: number;
+    path: readonly TreeNode<T>[];
+    index: number;
+}) => boolean;
 /**
- * 当 `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
+ * 树节点转换函数类型
+ *
+ * @template T 源节点数据类型
+ * @template R 目标节点数据类型
+ * @param params 包含节点信息的对象参数
+ * @param params.node 当前节点
+ * @param params.depth 节点深度（从0开始）
+ * @param params.path 从根节点到当前节点的路径数组
+ * @param params.index 节点在同级节点中的索引
+ * @returns 转换后的节点数据
  */
-type GetObjectField<MaybeObject, Key extends string> = MaybeObject extends Record<string, any> ? MaybeObject[Key] : never;
+type TreeTransformer<T = any, R = any> = (params: {
+    node: TreeNode<T>;
+    depth: number;
+    path: readonly TreeNode<T>[];
+    index: number;
+}) => R;
 /**
- * Vue 渲染相关文本/节点类型：可为字符串、`VNode` 或返回 `VNode` 的函数。
- * @example
- * // 在渲染 API 中允许三种形态：
- * // - '标题'
- * // - h('div', '标题') 产生的 VNode
- * // - () => h('div', '标题') 的惰性渲染函数
+ * 树节点访问函数类型
+ *
+ * @template T 节点数据类型
+ * @param params 包含节点信息的对象参数
+ * @param params.node 当前节点
+ * @param params.depth 节点深度（从0开始）
+ * @param params.path 从根节点到当前节点的路径数组
+ * @param params.index 节点在同级节点中的索引
+ * @returns 返回false可以终止遍历或跳过子节点
  */
-type StringOrVNode = string | VNode | (() => VNode);
+type TreeVisitor<T = any> = (params: {
+    node: TreeNode<T>;
+    depth: number;
+    path: readonly TreeNode<T>[];
+    index: number;
+}) => void | boolean;
+
 /**
- * 合并两个对象类型，U 中的属性会覆盖 T 中的属性
+ * 从扁平数组创建树形结构
  *
+ * @category Tree
+ * @param list 扁平数组数据
+ * @param config 树形配置选项
+ * @returns 树形结构数组
  * @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 }
+ * 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 = fromList(flatData, {
+ *   id: 'id',
+ *   pid: 'parentId',
+ *   children: 'children'
+ * })
+ *
+ * console.log(tree) // 转换为树形结构
  * ```
  */
-type Merge<T, U> = Omit<T, keyof U> & U;
+declare function fromList<T = any>(list: T[], config?: TreeConfigInput): TreeNode<T>[];
 /**
- * 判断类型 T 是否为纯对象类型
- * 纯对象是指普通的对象字面量，排除数组、函数、Date 等特殊对象类型
+ * 将树形结构转换为扁平数组
+ *
+ * @category Tree
+ * @param tree 树形结构（单个节点或节点数组）
+ * @param config 树形配置选项
+ * @returns 扁平数组
  * @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
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: '根节点',
+ *     children: [
+ *       { id: '2', name: '子节点1', children: [] },
+ *       { id: '3', name: '子节点2', children: [] }
+ *     ]
+ *   }
+ * ]
+ *
+ * const flatList = toList(tree)
+ * console.log(flatList) // [{ id: '1', name: '根节点' }, { id: '2', name: '子节点1' }, ...]
  * ```
  */
-type IsPlainObject<T> = NonNullable<T> extends Record<string, any> ? NonNullable<T> extends any[] ? false : NonNullable<T> extends (...args: any[]) => any ? false : NonNullable<T> extends Date ? false : true : false;
-/**
- * 深度控制类型，用于限制类型递归的深度
- * 防止类型计算超出 TypeScript 的递归限制
- */
-type Depth = [never, 0, 1, 2, 3, 4];
+declare function toList<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): T[];
 /**
- * 提取对象的嵌套键，支持点语法路径
+ * 估算树形结构的节点数量
  *
- * @template T 源对象类型
- * @template D 递归深度，默认为2
+ * @category Tree
+ * @param tree 树形结构（单个节点或节点数组）
+ * @param config 树形配置选项
+ * @returns 节点总数量
  * @example
  * ```ts
- * type User = {
- *   name: string
- *   address: {
- *     city: string
- *     country: string
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: '根节点',
+ *     children: [
+ *       { id: '2', name: '子节点1', children: [] },
+ *       { id: '3', name: '子节点2', children: [] }
+ *     ]
  *   }
- * }
- * type Keys = NestedKeys<User> // 'name' | 'address' | 'address.city' | 'address.country'
+ * ]
+ *
+ * const size = estimateSize(tree)
+ * console.log(size) // 3
  * ```
  */
-type NestedKeys<T, D extends number = 2> = [D] extends [never] ? never : {
-    [K in keyof T & string]: IsPlainObject<T[K]> extends true ? K | `${K}.${NestedKeys<NonNullable<T[K]>, Depth[D]>}` : K;
-}[keyof T & string];
+declare function estimateSize<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): number;
+
 /**
- * 提取对象中所有纯对象字段的键（包括嵌套的），支持点语法路径
+ * 在指定节点前插入新节点
  *
- * @template T 源对象类型
- * @template D 递归深度，默认为2
+ * @category Tree
+ * @param tree 树形结构数组
+ * @param targetId 目标节点的ID
+ * @param newNode 要插入的新节点数据
+ * @param config 树形配置选项
+ * @returns 是否成功插入
  * @example
  * ```ts
- * type User = {
- *   name: string
- *   age: number
- *   address: {
- *     city: string
- *     location: {
- *       lat: number
- *       lng: number
- *     }
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: '节点1',
+ *     children: [
+ *       { id: '2', name: '节点2', children: [] }
+ *     ]
  *   }
- * }
- * type ObjectKeys = ObjectFieldKeys<User> // 'address' | 'address.location'
+ * ]
+ *
+ * const success = insertBefore(tree, '2', { id: '1.5', name: '新节点' })
+ * console.log(success) // true
  * ```
  */
-type ObjectFieldKeys<T, D extends number = 2> = [D] extends [never] ? never : {
-    [K in keyof T & string]: IsPlainObject<T[K]> extends true ? K | `${K}.${ObjectFieldKeys<NonNullable<T[K]>, Depth[D]>}` : never;
-}[keyof T & string];
+declare function insertBefore<T = any>(tree: TreeNode<T>[], targetId: string, newNode: T, config?: TreeConfigInput): boolean;
 /**
- * 提取对象中所有非对象字段的键
- * 排除纯对象字段，只保留原始类型字段的键
+ * 在指定节点后插入新节点
  *
- * @template T 源对象类型
+ * @category Tree
+ * @param tree 树形结构数组
+ * @param targetId 目标节点的ID
+ * @param newNode 要插入的新节点数据
+ * @param config 树形配置选项
+ * @returns 是否成功插入
  * @example
  * ```ts
- * type User = {
- *   name: string
- *   age: number
- *   address: {
- *     city: string
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: '节点1',
+ *     children: [
+ *       { id: '2', name: '节点2', children: [] }
+ *     ]
  *   }
- * }
- * type NonObjectKeys = NonObjectFieldKeys<User> // 'name' | 'age' | 'address.city'
+ * ]
+ *
+ * const success = insertAfter(tree, '2', { id: '3', name: '新节点' })
+ * console.log(success) // true
  * ```
  */
-type NonObjectFieldKeys<T> = Exclude<NestedKeys<T>, ObjectFieldKeys<T>>;
+declare function insertAfter<T = any>(tree: TreeNode<T>[], targetId: string, newNode: T, config?: TreeConfigInput): boolean;
 /**
- * 提取对象中所有数组字段的键（包括嵌套的），支持点语法路径
+ * 从树中删除指定节点
  *
- * @template T 源对象类型
- * @template D 递归深度，默认为2
+ * @category Tree
+ * @param tree 树形结构数组
+ * @param targetId 要删除的节点ID
+ * @param config 树形配置选项
+ * @returns 被删除的节点，未找到时返回undefined
  * @example
  * ```ts
- * type User = {
- *   name: string
- *   tags: string[]
- *   posts: Array<{ title: string }>
- *   profile: {
- *     hobbies: string[]
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: '根节点',
+ *     children: [
+ *       { id: '2', name: '子节点', children: [] }
+ *     ]
  *   }
- * }
- * type ArrayKeys = ArrayFieldKeys<User> // 'tags' | 'posts' | 'profile.hobbies'
+ * ]
+ *
+ * const removed = remove(tree, '2')
+ * console.log(removed?.name) // '子节点'
  * ```
  */
-type ArrayFieldKeys<T, D extends number = 2> = [D] extends [never] ? never : {
-    [K in keyof T & string]: NonNullable<T[K]> extends any[] ? K : IsPlainObject<T[K]> extends true ? `${K}.${ArrayFieldKeys<NonNullable<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";
-    sessionStorage: "sessionStorage";
-}>;
-type StorageType = z.infer<typeof StorageTypeSchema>;
-declare function createStorageConfigSchema<T = unknown>(schema: z.ZodType<T>): z.ZodObject<{
-    key: z.ZodString;
-    schema: z.ZodCustom<z.ZodType<T, unknown, z.core.$ZodTypeInternals<T, unknown>>, z.ZodType<T, unknown, z.core.$ZodTypeInternals<T, unknown>>>;
-    defaultValue: z.ZodCustom<T, T>;
-    prefix: z.ZodDefault<z.ZodString>;
-    storage: z.ZodDefault<z.ZodEnum<{
-        localStorage: "localStorage";
-        sessionStorage: "sessionStorage";
-    }>>;
-}, z.core.$strip>;
-type StorageConfig<T = unknown> = z.infer<ReturnType<typeof createStorageConfigSchema<T>>>;
-type StorageConfigInput<T = unknown> = z.input<ReturnType<typeof createStorageConfigSchema<T>>>;
-interface AppStorageReturn<T> {
-    state: Ref<T>;
-    getItem: () => T;
-    setItem: (value: T) => void;
-    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> : {};
+declare function remove<T = any>(tree: TreeNode<T>[], targetId: string, config?: TreeConfigInput): TreeNode<T> | undefined;
 
 /**
- * 应用存储管理的组合式函数，支持localStorage和sessionStorage
+ * 查找树中第一个满足条件的节点
  *
- * @category Composables
- * @param config 存储配置对象
- * @returns 存储管理对象，包含响应式状态和操作方法
+ * @category Tree
+ * @param tree 树形结构（单个节点或节点数组）
+ * @param predicate 查找条件函数
+ * @param config 树形配置选项
+ * @returns 匹配的节点；未找到时返回undefined
  * @example
  * ```ts
- * import { z } from 'zod/v4'
- *
- * // 定义用户偏好设置的schema
- * const userPrefsSchema = z.object({
- *   theme: z.enum(['light', 'dark']),
- *   language: z.string(),
- *   fontSize: z.number().min(12).max(24)
- * })
- *
- * // 创建存储管理实例
- * const { state, setItem, getItem, removeItem } = useAppStorage({
- *   key: 'user-preferences',
- *   defaultValue: {
- *     theme: 'light',
- *     language: 'zh-CN',
- *     fontSize: 16
- *   },
- *   schema: userPrefsSchema,
- *   storage: 'localStorage',
- *   prefix: 'app'
- * })
- *
- * // 使用响应式状态
- * console.log(state.value.theme) // 'light'
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: '部门1',
+ *     children: [
+ *       { id: '2', name: '部门1-1', children: [] }
+ *     ]
+ *   }
+ * ]
  *
- * // 更新设置
- * setItem({
- *   theme: 'dark',
- *   language: 'en-US',
- *   fontSize: 18
- * })
+ * const result = find(tree, ({ node }) => node.name === '部门1-1')
+ * console.log(result?.id) // '2'
  * ```
  */
-declare function useAppStorage<T = unknown>(config: StorageConfigInput<T>): AppStorageReturn<T>;
-
+declare function find<T = any>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNode<T> | undefined;
 /**
- * 复制文本到剪贴板的组合式函数
+ * 查找树中所有满足条件的节点
  *
- * @category Composables
- * @param text 要复制的文本内容
- * @returns 复制是否成功的Promise
+ * @category Tree
+ * @param tree 树形结构（单个节点或节点数组）
+ * @param predicate 查找条件函数
+ * @param config 树形配置选项
+ * @returns 所有匹配的节点数组
  * @example
  * ```ts
- * // 复制简单文本
- * const copyText = async () => {
- *   const success = await useCopyCode('Hello, World!')
- *   if (success) {
- *     console.log('复制成功')
- *   } else {
- *     console.log('复制失败')
- *   }
- * }
- *
- * // 复制代码块
- * const copyCodeBlock = async () => {
- *   const code = `
- *   function hello() {
- *     console.log('Hello, World!')
- *   }
- *   `
- *   const success = await useCopyCode(code)
- *   if (success) {
- *     // 显示复制成功提示
- *     showNotification('代码已复制到剪贴板')
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     type: 'folder',
+ *     name: '根目录',
+ *     children: [
+ *       { id: '2', type: 'file', name: '文件1', children: [] },
+ *       { id: '3', type: 'file', name: '文件2', children: [] }
+ *     ]
  *   }
- * }
+ * ]
  *
- * // 在点击事件中使用
- * const handleCopy = () => {
- *   useCopyCode(document.getElementById('code').textContent)
- * }
+ * const files = findAll(tree, ({ node }) => node.type === 'file')
+ * console.log(files.length) // 2
  * ```
  */
-declare function useCopyCode(text: string): Promise<boolean>;
-
+declare function findAll<T = any>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNode<T>[];
 /**
- * 数组去重，返回去除重复元素后的新数组
+ * 根据ID查找树中的节点
  *
- * @category Array
- * @param arr 待去重的数组
- * @returns 去重后的新数组
+ * @category Tree
+ * @param tree 树形结构（单个节点或节点数组）
+ * @param id 要查找的节点ID
+ * @param config 树形配置选项
+ * @returns 匹配的节点；未找到时返回undefined
  * @example
  * ```ts
- * const numbers = [1, 2, 2, 3, 3, 4]
- * const uniqueNumbers = unique(numbers)
- * console.log(uniqueNumbers) // [1, 2, 3, 4]
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: '根节点',
+ *     children: [
+ *       { id: '2', name: '子节点', children: [] }
+ *     ]
+ *   }
+ * ]
  *
- * const strings = ['a', 'b', 'a', 'c']
- * const uniqueStrings = unique(strings)
- * console.log(uniqueStrings) // ['a', 'b', 'c']
+ * const result = findById(tree, '2')
+ * console.log(result?.name) // '子节点'
  * ```
  */
-declare function unique<T>(arr: T[]): T[];
+declare function findById<T = any>(tree: TreeNode<T> | TreeNode<T>[], id: string, config?: TreeConfigInput): TreeNode<T> | undefined;
+
 /**
- * 将数组分割成指定大小的块
+ * 过滤树形结构，保留满足条件的节点及其祖先和后代
  *
- * @category Array
- * @param arr 待分割的数组
- * @param size 每个块的大小
- * @returns 分割后的二维数组
+ * @category Tree
+ * @param tree 树形结构（单个节点或节点数组）
+ * @param predicate 过滤条件函数，接收对象参数 {node, depth, path, index}
+ * @param config 树形配置选项
+ * @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 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 names = ['Alice', 'Bob', 'Charlie', 'David', 'Eve']
- * const pairs = chunk(names, 2)
- * console.log(pairs) // [['Alice', 'Bob'], ['Charlie', 'David'], ['Eve']]
+ * const filtered = filter(tree, ({ node }) => node.type === 'file')
+ * // 返回包含所有文件节点及其父级路径的树结构
  * ```
  */
-declare function chunk<T>(arr: T[], size: number): T[][];
+declare function filter<T = any>(tree: TreeNode<T> | TreeNode<T>[], predicate: TreePredicate<T>, config?: TreeConfigInput): TreeNode<T>[];
 /**
- * 数组扁平化，将嵌套数组展平到指定深度
+ * 转换树形结构，将每个节点转换为新的结构
  *
- * @category Array
- * @param arr 待扁平化的数组
- * @param depth 扁平化深度，默认为1
- * @returns 扁平化后的数组
+ * @category Tree
+ * @param tree 树形结构（单个节点或节点数组）
+ * @param transformer 节点转换函数，接收对象参数 {node, depth, path, index}
+ * @param config 树形配置选项
+ * @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 tree = [
+ *   {
+ *     id: '1',
+ *     name: '部门1',
+ *     children: [
+ *       { id: '2', name: '部门1-1', children: [] }
+ *     ]
+ *   }
+ * ]
  *
- * const flat2 = flatten(nested, 2)
- * console.log(flat2) // [1, 2, 3, 4, 5, 6]
+ * const transformed = transform(tree, ({ node, depth }) => ({
+ *   key: node.id,
+ *   title: node.name,
+ *   level: depth
+ * }))
+ * // 转换为新的数据结构
  * ```
  */
-declare function flatten<T>(arr: T[], depth?: number): any[];
+declare function transform<T = any, R = any>(tree: TreeNode<T> | TreeNode<T>[], transformer: TreeTransformer<T, R>, config?: TreeConfigInput): TreeNode<R>[];
 
 /**
- * 防抖函数，在指定时间内多次触发只执行最后一次
+ * 遍历树形结构的每个节点
  *
- * @category Async
- * @param func 需要防抖的函数
- * @param wait 防抖延迟时间（毫秒）
- * @returns 防抖处理后的函数
+ * @category Tree
+ * @param tree 树形结构（单个节点或节点数组）
+ * @param visitor 访问者函数，接收对象参数 {node, depth, path, index}，返回false可以跳过子节点的遍历
+ * @param config 树形配置选项
  * @example
  * ```ts
- * const debouncedSearch = debounce((query: string) => {
- *   console.log('搜索:', query)
- * }, 300)
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: '根节点',
+ *     children: [
+ *       { id: '2', name: '子节点', children: [] }
+ *     ]
+ *   }
+ * ]
  *
- * // 连续调用，只有最后一次会执行
- * debouncedSearch('a')
- * debouncedSearch('ab')
- * debouncedSearch('abc') // 只有这次会在300ms后执行
+ * forEach(tree, ({ node, depth }) => {
+ *   console.log(`${' '.repeat(depth * 2)}${node.name}`)
+ *   // 输出缩进的树结构
+ * })
  * ```
  */
-declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
+declare function forEach<T = any>(tree: TreeNode<T> | TreeNode<T>[], visitor: TreeVisitor<T>, config?: TreeConfigInput): void;
 
 /**
- * 延迟执行函数，返回一个在指定时间后resolve的Promise
+ * 获取树形结构的统计信息
  *
- * @category Async
- * @param ms 延迟时间（毫秒）
- * @returns 延迟Promise
+ * @category Tree
+ * @param tree 树形结构（单个节点或节点数组）
+ * @param config 树形配置选项
+ * @returns 树的统计信息，包含总节点数、叶子节点数、最大深度和分支节点数
  * @example
  * ```ts
- * // 延迟1秒后继续执行
- * await sleep(1000)
- * console.log('1秒后执行')
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: '根节点',
+ *     children: [
+ *       { id: '2', name: '子节点1', children: [] },
+ *       { id: '3', name: '子节点2', children: [
+ *         { id: '4', name: '孙节点', children: [] }
+ *       ] }
+ *     ]
+ *   }
+ * ]
  *
- * // 在异步函数中使用
- * async function delayedOperation() {
- *   console.log('开始')
- *   await sleep(500)
- *   console.log('500ms后执行')
- * }
+ * const stats = getStats(tree)
+ * console.log(stats) // { total: 4, leaves: 2, depth: 3, branches: 2 }
  * ```
  */
-declare function sleep(ms: number): Promise<void>;
+declare function getStats<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): TreeStats;
 /**
- * 可取消的延迟函数，返回Promise和取消函数
+ * 验证树形结构的有效性
  *
- * @category Async
- * @param ms 延迟时间（毫秒）
- * @returns 包含Promise和取消函数的对象
+ * @category Tree
+ * @param tree 树形结构（单个节点或节点数组）
+ * @param config 树形配置选项
+ * @returns 验证结果，包含是否有效和错误信息数组
  * @example
  * ```ts
- * const { promise, cancel } = sleepWithCancel(5000)
- *
- * // 在另一个地方取消延迟
- * setTimeout(() => {
- *   cancel() // 取消延迟
- * }, 2000)
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: '根节点',
+ *     children: [
+ *       { id: '2', name: '子节点', children: [] }
+ *     ]
+ *   }
+ * ]
  *
- * try {
- *   await promise
- *   console.log('5秒后执行')
- * } catch (error) {
- *   console.log('延迟被取消')
- * }
+ * const result = validate(tree)
+ * console.log(result.isValid) // true
+ * console.log(result.errors) // []
  * ```
  */
-declare function sleepWithCancel(ms: number): {
-    promise: Promise<void>;
-    cancel: () => void;
+declare function validate<T = any>(tree: TreeNode<T> | TreeNode<T>[], config?: TreeConfigInput): {
+    isValid: boolean;
+    errors: string[];
 };
 
 /**
- * 节流函数，在指定时间内多次触发只执行第一次
+ * 树形数据结构操作工具类
  *
- * @category Async
- * @param func 需要节流的函数
- * @param limit 节流时间间隔（毫秒）
- * @returns 节流处理后的函数
- * @example
- * ```ts
- * const throttledScroll = throttle((event: Event) => {
- *   console.log('滚动事件处理')
- * }, 100)
+ * 提供了一系列操作树形数据的静态方法，包括：
+ * - 查找：find, findAll, findById
+ * - 转换：fromList, toList, transform
+ * - 过滤：filter
+ * - 遍历：forEach
+ * - 统计：estimateSize, getStats
+ * - 修改：insertBefore, insertAfter, remove
+ * - 验证：validate
  *
- * // 监听滚动事件，每100ms最多执行一次
- * window.addEventListener('scroll', throttledScroll)
- * ```
- */
-declare function throttle<T extends (...args: any[]) => any>(func: T, limit: number): (...args: Parameters<T>) => void;
-
-/**
- * 将SVG字符串转换为PNG格式的Blob对象
+ * 所有使用谓词函数或访问函数的方法都采用对象解构参数格式：
+ * `({ node, depth, path, index }) => boolean`
  *
- * @category File
- * @param svg SVG字符串
- * @returns PNG格式的Blob对象
- * @throws 当SVG无效或转换失败时抛出错误
  * @example
  * ```ts
- * const svgString = '<svg width="100" height="100"><circle cx="50" cy="50" r="40" fill="red"/></svg>'
+ * // 1. 从扁平数组创建树形结构
+ * const departments = [
+ *   { id: '1', name: '技术部', parentId: null },
+ *   { id: '2', name: '前端组', parentId: '1' },
+ *   { id: '3', name: '后端组', parentId: '1' },
+ *   { id: '4', name: 'UI 组', parentId: '2' },
+ *   { id: '5', name: '测试组', parentId: '2' }
+ * ]
  *
- * try {
- *   const pngBlob = await convertSvgToPng(svgString)
- *   const url = URL.createObjectURL(pngBlob)
+ * const tree = Tree.fromList(departments, {
+ *   id: 'id',
+ *   pid: 'parentId',
+ *   children: 'children'
+ * })
  *
- *   // 用于下载或显示
- *   const img = document.createElement('img')
- *   img.src = url
- *   document.body.appendChild(img)
- * } catch (error) {
- *   console.error('SVG转换失败:', error)
+ * // 2. 查找节点
+ * const frontend = Tree.find(tree, ({ node }) => node.name === '前端组')
+ * console.log(frontend) // { id: '2', name: '前端组', children: [...] }
+ *
+ * const uiNode = Tree.findById(tree, '4')
+ * console.log(uiNode) // { id: '4', name: 'UI 组', ... }
+ *
+ * // 3. 查找所有叶子节点
+ * const leaves = Tree.findAll(tree, ({ node }) => {
+ *   return !node.children || node.children.length === 0
+ * })
+ * console.log(leaves) // [{ id: '4', ... }, { id: '5', ... }, { id: '3', ... }]
+ *
+ * // 4. 过滤节点（保留匹配节点及其祖先）
+ * const filtered = Tree.filter(tree, ({ node }) => node.name.includes('组'))
+ * // 返回包含所有 "组" 节点及其父级路径的树结构
+ *
+ * // 5. 转换节点结构
+ * const menuTree = Tree.transform(tree, ({ node, depth }) => ({
+ *   key: node.id,
+ *   label: node.name,
+ *   level: depth,
+ *   indent: depth * 20
+ * }))
+ *
+ * // 6. 遍历所有节点
+ * Tree.forEach(tree, ({ node, depth, path }) => {
+ *   const indent = '  '.repeat(depth)
+ *   const breadcrumb = path.map(n => n.name).join(' > ')
+ *   console.log(`${indent}${node.name} (路径: ${breadcrumb})`)
+ * })
+ *
+ * // 7. 修改树结构
+ * Tree.insertBefore(tree, '3', { id: '6', name: '运维组' })
+ * Tree.insertAfter(tree, '2', { id: '7', name: '移动组' })
+ * const removed = Tree.remove(tree, '5')
+ *
+ * // 8. 获取统计信息
+ * const stats = Tree.getStats(tree)
+ * console.log(stats)
+ * // { total: 5, leaves: 3, depth: 3, branches: 2 }
+ *
+ * // 9. 验证树结构
+ * const validation = Tree.validate(tree)
+ * if (!validation.isValid) {
+ *   console.error('树结构错误:', validation.errors)
  * }
+ *
+ * // 10. 转换回扁平数组
+ * const flatList = Tree.toList(tree)
+ * console.log(flatList) // [{ id: '1', name: '技术部' }, ...]
  * ```
  */
-declare function convertSvgToPng(svg: string): Promise<Blob>;
+declare class Tree {
+    static fromList: typeof fromList;
+    static toList: typeof toList;
+    static estimateSize: typeof estimateSize;
+    static find: typeof find;
+    static findAll: typeof findAll;
+    static findById: typeof findById;
+    static insertBefore: typeof insertBefore;
+    static insertAfter: typeof insertAfter;
+    static remove: typeof remove;
+    static filter: typeof filter;
+    static transform: typeof transform;
+    static forEach: typeof forEach;
+    static getStats: typeof getStats;
+    static validate: typeof validate;
+}
 
 /**
- * 从响应头中提取文件名
+ * 统一同步/异步返回类型
+ * @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;
+
+/**
+ * 提供字符串字面量提示的同时允许任意字符串
+ * 在 IDE 中提供 T 类型的自动补全提示，但不限制只能使用这些值
  *
- * @category File
- * @param headers 响应头对象
- * @param fallbackName 默认文件名
- * @returns 提取的文件名
  * @example
  * ```ts
- * // 从响应头中提取文件名
- * const headers = new Headers({
- *   'content-disposition': 'attachment; filename="report.pdf"'
- * })
- * const filename = extractFilename(headers, 'download')
- * console.log(filename) // 'report.pdf'
+ * type Color = Suggest<'red' | 'blue' | 'green'>
  *
- * // 处理编码的文件名
- * const encodedHeaders = new Headers({
- *   'content-disposition': 'attachment; filename*=UTF-8\'\'%E6%8A%A5%E5%91%8A.pdf'
- * })
- * const encodedFilename = extractFilename(encodedHeaders)
- * console.log(encodedFilename) // '报告.pdf'
+ * // IDE 会提示 'red', 'blue', 'green'，但也可以使用其他字符串
+ * const color1: Color = 'red'    // 有提示
+ * const color2: Color = 'yellow' // 也可以，虽然没有提示
  * ```
  */
-declare function extractFilename(headers?: Headers, fallbackName?: string): string;
+type Suggest<T extends string> = T | (string & {});
 /**
- * 触发浏览器下载文件
+ * 响应式值类型 - 基于 Vue 的 `MaybeRefOrGetter` 扩展，额外支持上下文回调
+ *
+ * @template T - 值类型
+ * @template CTX - 上下文类型（用于回调函数）
  *
- * @category File
- * @param blob 文件数据
- * @param filename 文件名
  * @example
  * ```ts
- * // 下载文本文件
- * const textBlob = new Blob(['Hello, World!'], { type: 'text/plain' })
- * triggerDownload(textBlob, 'hello.txt')
- *
- * // 下载JSON数据
- * const data = { name: 'John', age: 30 }
- * const jsonBlob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' })
- * triggerDownload(jsonBlob, 'data.json')
- *
- * // 下载图片
- * const canvas = document.createElement('canvas')
- * canvas.toBlob((blob) => {
- *   if (blob) {
- *     triggerDownload(blob, 'image.png')
- *   }
- * })
+ * 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
  * ```
  */
-declare function triggerDownload(blob: Blob, filename: string): void;
+type ReactiveValue<T, CTX = never> = [CTX] extends [never] ? MaybeRefOrGetter<T> : MaybeRefOrGetter<T> | ((ctx: CTX) => T);
+type StripNullable<T> = T extends null | undefined ? never : T;
+
+interface ParsedUrl {
+    /** 完整的原始 URL */
+    href: string;
+    /** 协议 (http:, https:, etc.) */
+    protocol: string;
+    /** 主机名 + 端口 */
+    host: string;
+    /** 主机名 */
+    hostname: string;
+    /** 端口号 */
+    port: string;
+    /** 路径部分 */
+    pathname: string;
+    /** 查询字符串 (包含 ?) */
+    search: string;
+    /** 哈希部分 (包含 #) */
+    hash: string;
+    /** 用户认证信息 (user:pass) */
+    auth: string;
+    /** 源 (protocol + host) */
+    origin: string;
+}
+/**
+ * 查询参数值类型
+ */
+type QueryParamValue = string | number | boolean | null | undefined;
+/**
+ * 查询参数对象类型
+ */
+type QueryParams = Record<string, QueryParamValue | QueryParamValue[]>;
 
 /**
- * 格式化文件大小，将字节数转换为可读的文件大小字符串
+ * 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> : {};
+
+/**
+ * 将数组分割成指定大小的块
  *
- * @category File
- * @param bytes 文件大小（字节）
- * @returns 格式化后的文件大小字符串
+ * @category Array
+ * @param arr 待分割的数组
+ * @param size 每个块的大小
+ * @returns 分割后的二维数组
  * @example
  * ```ts
- * console.log(formatFileSize(1024)) // '1 KB'
- * console.log(formatFileSize(1536)) // '1.5 KB'
- * console.log(formatFileSize(1048576)) // '1 MB'
- * console.log(formatFileSize(1073741824)) // '1 GB'
+ * 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]]
  *
- * // 处理边界情况
- * console.log(formatFileSize(0)) // '0 Bytes'
- * console.log(formatFileSize(-100)) // '0 Bytes'
+ * const names = ['Alice', 'Bob', 'Charlie', 'David', 'Eve']
+ * const pairs = chunk(names, 2)
+ * console.log(pairs) // [['Alice', 'Bob'], ['Charlie', 'David'], ['Eve']]
  * ```
  */
-declare function formatFileSize(bytes: number): string;
+declare function chunk<T>(arr: T[], size: number): T[][];
 
 /**
- * 替换SVG文件中的currentColor为指定颜色
+ * 数组扁平化，将嵌套数组展平到指定深度
  *
- * @category File
- * @param path SVG文件路径
- * @param color 替换的颜色值，不提供则返回原始SVG
- * @returns 处理后的SVG字符串
- * @throws 当文件获取失败或SVG无效时抛出错误
+ * @category Array
+ * @param arr 待扁平化的数组
+ * @param depth 扁平化深度，默认为1
+ * @returns 扁平化后的数组
  * @example
  * ```ts
- * // 获取并替换SVG中的currentColor
- * try {
- *   const svgContent = await replaceCurrentColor('/icons/star.svg', '#ff0000')
- *   const container = document.createElement('div')
- *   container.innerHTML = svgContent
- *   document.body.appendChild(container)
- * } catch (error) {
- *   console.error('SVG处理失败:', error)
- * }
+ * const nested = [1, [2, 3], [4, [5, 6]]]
+ * const flat1 = flatten(nested)
+ * console.log(flat1) // [1, 2, 3, 4, [5, 6]]
  *
- * // 只获取SVG内容，不替换颜色
- * const originalSvg = await replaceCurrentColor('/icons/star.svg')
+ * const flat2 = flatten(nested, 2)
+ * console.log(flat2) // [1, 2, 3, 4, 5, 6]
  * ```
  */
-declare function replaceCurrentColor(path: string, color?: string): Promise<string>;
+declare function flatten<T>(arr: T[], depth?: number): any[];
 
 /**
- * 将对象的键名转换为kebab-case格式
+ * 数组去重，返回去除重复元素后的新数组
  *
- * @category Object
- * @param obj 待转换的对象
- * @param deep 是否深度转换嵌套对象，默认为false
- * @returns 转换后的对象
+ * @category Array
+ * @param arr 待去重的数组
+ * @returns 去重后的新数组
  * @example
  * ```ts
- * const obj = {
- *   firstName: 'John',
- *   lastName: 'Doe',
- *   userInfo: {
- *     birthDate: '1990-01-01',
- *     phoneNumber: '123-456-7890'
- *   }
- * }
- *
- * const converted = convertToKebabCase(obj)
- * console.log(converted)
- * // {
- * //   'first-name': 'John',
- * //   'last-name': 'Doe',
- * //   'user-info': { birthDate: '1990-01-01', phoneNumber: '123-456-7890' }
- * // }
+ * const numbers = [1, 2, 2, 3, 3, 4]
+ * const uniqueNumbers = unique(numbers)
+ * console.log(uniqueNumbers) // [1, 2, 3, 4]
  *
- * const deepConverted = convertToKebabCase(obj, true)
- * console.log(deepConverted)
- * // {
- * //   'first-name': 'John',
- * //   'last-name': 'Doe',
- * //   'user-info': { 'birth-date': '1990-01-01', 'phone-number': '123-456-7890' }
- * // }
+ * const strings = ['a', 'b', 'a', 'c']
+ * const uniqueStrings = unique(strings)
+ * console.log(uniqueStrings) // ['a', 'b', 'c']
  * ```
  */
-declare function convertToKebabCase<T extends AnyObject>(obj: T, deep?: boolean): T;
+declare function unique<T>(arr: T[]): T[];
 
 /**
- * 深拷贝任意 JavaScript 值。
- *
- * - 优先使用原生 `structuredClone`（若可用），覆盖 `Map`/`Set`/`TypedArray`/`ArrayBuffer` 等内建类型。
- * - 对不支持 `structuredClone` 的环境，使用回退实现：
- *   - 支持循环引用（`WeakMap` 记忆化）。
- *   - 保留原型与属性描述符（含 getter/setter），复制 symbol 键。
- *   - 内建类型专项处理：`Date`/`RegExp`/`Map`/`Set`/`ArrayBuffer`/`TypedArray`/`URL`/`Error`。
- *
- * @category Object
- * @typeParam T 拷贝值的类型
- * @param obj 要被深拷贝的值
- * @param cache 内部使用的 `WeakMap`（循环引用记忆化），一般不需要传入
- * @returns 新的深拷贝值，与输入值结构等价、引用独立
+ * 防抖函数，在指定时间内多次触发只执行最后一次
  *
+ * @category Async
+ * @param func 需要防抖的函数
+ * @param wait 防抖延迟时间（毫秒）
+ * @returns 防抖处理后的函数
  * @example
  * ```ts
- * 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
- * ```
+ * const debouncedSearch = debounce((query: string) => {
+ *   console.log('搜索:', query)
+ * }, 300)
  *
- * @remarks
- * 若对象包含不可克隆资源（如带有原生句柄的自定义对象），请在外层进行自定义序列化逻辑或为该类型添加专用分支。
+ * // 连续调用，只有最后一次会执行
+ * debouncedSearch('a')
+ * debouncedSearch('ab')
+ * debouncedSearch('abc') // 只有这次会在300ms后执行
+ * ```
  */
-declare function deepClone<T>(obj: T, cache?: WeakMap<object, any>): T;
+declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
 
 /**
- * 从对象中排除指定的键，返回新对象
+ * 延迟执行函数，返回一个在指定时间后resolve的Promise
  *
- * @category Object
- * @param obj 源对象
- * @param keys 要排除的键数组
- * @returns 排除指定键后的新对象
+ * @category Async
+ * @param ms 延迟时间（毫秒）
+ * @returns 延迟Promise
  * @example
  * ```ts
- * const user = {
- *   id: 1,
- *   name: 'John',
- *   password: 'secret',
- *   email: 'john@example.com'
- * }
- *
- * const publicUser = omit(user, ['password'])
- * console.log(publicUser) // { id: 1, name: 'John', email: 'john@example.com' }
+ * // 延迟1秒后继续执行
+ * await sleep(1000)
+ * console.log('1秒后执行')
  *
- * const basicInfo = omit(user, ['password', 'email'])
- * console.log(basicInfo) // { id: 1, name: 'John' }
+ * // 在异步函数中使用
+ * async function delayedOperation() {
+ *   console.log('开始')
+ *   await sleep(500)
+ *   console.log('500ms后执行')
+ * }
  * ```
  */
-declare function omit<T extends AnyObject, K extends keyof T>(obj: T, keys: K[]): OmitByKey<T, K>;
+declare function sleep(ms: number): Promise<void>;
+
 /**
- * 从对象中排除值为undefined的键
+ * 可取消的延迟函数，返回Promise和取消函数
  *
- * @category Object
- * @param obj 源对象
- * @returns 排除undefined值后的新对象
+ * @category Async
+ * @param ms 延迟时间（毫秒）
+ * @returns 包含Promise和取消函数的对象
  * @example
  * ```ts
- * const data = {
- *   name: 'John',
- *   age: undefined,
- *   city: 'New York',
- *   country: undefined
- * }
+ * const { promise, cancel } = sleepWithCancel(5000)
  *
- * const cleaned = omitUndefined(data)
- * console.log(cleaned) // { name: 'John', city: 'New York' }
+ * // 在另一个地方取消延迟
+ * setTimeout(() => {
+ *   cancel() // 取消延迟
+ * }, 2000)
  *
- * // 用于API请求前清理数据
- * const requestData = omitUndefined({
- *   title: 'Post Title',
- *   content: 'Post content',
- *   tags: undefined,
- *   published: true
- * })
+ * try {
+ *   await promise
+ *   console.log('5秒后执行')
+ * } catch (error) {
+ *   console.log('延迟被取消')
+ * }
  * ```
  */
-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 数组。
+declare function sleepWithCancel(ms: number): {
+    promise: Promise<void>;
+    cancel: () => void;
+};
+
+/**
+ * 节流函数，在指定时间内多次触发只执行第一次
  *
- * @category Validator
- * @param value - 待检查的值
- * @returns 是否为有效容器（对象或数组）
+ * @category Async
+ * @param func 需要节流的函数
+ * @param limit 节流时间间隔（毫秒）
+ * @returns 节流处理后的函数
  * @example
  * ```ts
- * isValidContainer({})              // true
- * isValidContainer([])              // true
- * isValidContainer(new Proxy({}, {})) // true
- * isValidContainer(null)            // false
- * isValidContainer('string')        // false
- * isValidContainer(123)             // false
+ * const throttledScroll = throttle((event: Event) => {
+ *   console.log('滚动事件处理')
+ * }, 100)
+ *
+ * // 监听滚动事件，每100ms最多执行一次
+ * window.addEventListener('scroll', throttledScroll)
  * ```
  */
-declare function isValidContainer(value: any): boolean;
+declare function throttle<T extends (...args: any[]) => any>(func: T, limit: number): (...args: Parameters<T>) => void;
+
 /**
- * 将路径字符串解析为片段数组。
- *
- * - 支持点语法与方括号语法混用
- * - 引号键支持单/双引号与反斜杠转义
- * - 方括号内未引号的非负整数字面量解析为 number 段
- * - 点语法中的纯数字段保持字符串（不转为索引）
+ * 解析 URL 字符串为结构化对象
  *
- * @category Object
- * @param path 路径字符串或片段数组
- * @returns 解析后的片段数组
+ * @category URL
+ * @param url 要解析的 URL 字符串
+ * @param base 可选的基础 URL，用于解析相对路径
+ * @returns 解析后的 URL 对象，解析失败返回 null
  * @example
  * ```ts
- * toPath('a.b[0].c') // ['a', 'b', 0, 'c']
- * toPath("a['x.y']") // ['a', 'x.y']
+ * parseUrl('https://example.com:8080/path?query=1#hash')
+ * // {
+ * //   href: 'https://example.com:8080/path?query=1#hash',
+ * //   protocol: 'https:',
+ * //   host: 'example.com:8080',
+ * //   hostname: 'example.com',
+ * //   port: '8080',
+ * //   pathname: '/path',
+ * //   search: '?query=1',
+ * //   hash: '#hash',
+ * //   auth: '',
+ * //   origin: 'https://example.com:8080'
+ * // }
+ *
+ * parseUrl('/path', 'https://example.com')
+ * // 解析相对 URL
  * ```
  */
-declare function toPath(path: PathInput): PathSegments;
+declare function parseUrl(url: string, base?: string): ParsedUrl | null;
 /**
- * 读取对象指定路径的值。
+ * 检查字符串是否为有效的 URL
  *
- * - 若取值结果为 undefined，则返回 defaultValue
- * - 若取值结果为 null，则直接返回 null（不触发默认值）
- * - 传入空路径时返回 object 本身
- *
- * @category Object
- * @param object 源对象
- * @param path 路径字符串或片段数组
- * @param defaultValue 结果为 undefined 时返回的默认值
- * @returns 读取到的值或默认值
+ * @category URL
+ * @param url 要检查的字符串
+ * @returns 是否为有效 URL
  * @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 本身
+ * isValidUrl('https://example.com') // true
+ * isValidUrl('not a url') // false
+ * isValidUrl('ftp://files.example.com') // true
  * ```
  */
-declare function getPath<T, D = undefined>(object: T, path: PathInput, defaultValue?: D): unknown | D;
+declare function isValidUrl(url: string): boolean;
 /**
- * 在对象指定路径写入值。缺失路径会被自动创建：
- * - 下一段为 number（索引）时创建数组
- * - 下一段为 string（属性）时创建对象
+ * 检查 URL 是否为绝对路径
  *
- * 若中途遇到非容器类型（如字符串/数值/布尔），会被替换为正确的容器以继续写入。
- *
- * @category Object
- * @param object 目标对象（原地修改并返回同一引用）
- * @param path 路径字符串或片段数组
- * @param value 要写入的值
- * @returns 原对象（已修改）
+ * @category URL
+ * @param url 要检查的 URL
+ * @returns 是否为绝对路径
  * @example
  * ```ts
- * 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
+ * isAbsoluteUrl('https://example.com') // true
+ * isAbsoluteUrl('/path/to/page') // false
+ * isAbsoluteUrl('//example.com/path') // true (protocol-relative)
  * ```
  */
-declare function setPath<T extends Record<string, any>>(object: T, path: PathInput, value: unknown): T;
+declare function isAbsoluteUrl(url: string): boolean;
 /**
- * 将片段数组序列化为路径字符串。
+ * 检查 URL 是否为相对路径
  *
- * 规则：
- * - 合法标识符段使用点拼接（a.b.c）
- * - 数字段转为索引（[0]）
- * - 其它需要转义的键使用方括号引号（['x.y']），并转义 \\ 与 '\''
- *
- * @category Object
- * @param segments 路径片段数组
- * @returns 路径字符串
+ * @category URL
+ * @param url 要检查的 URL
+ * @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']
+ * isRelativeUrl('/path/to/page') // true
+ * isRelativeUrl('./page') // true
+ * isRelativeUrl('../page') // true
+ * isRelativeUrl('https://example.com') // false
  * ```
  */
-declare function joinPath(segments: (string | number)[]): string;
-
+declare function isRelativeUrl(url: string): boolean;
 /**
- * 从对象中选择指定的键，返回新对象
+ * 获取 URL 的域名部分
  *
- * @category Object
- * @param obj 源对象
- * @param keys 要选择的键数组
- * @returns 只包含指定键的新对象
+ * @category URL
+ * @param url URL 字符串
+ * @returns 域名，解析失败返回空字符串
  * @example
  * ```ts
- * const user = {
- *   id: 1,
- *   name: 'John',
- *   email: 'john@example.com',
- *   password: 'secret',
- *   createdAt: '2023-01-01',
- *   updatedAt: '2023-01-15'
- * }
- *
- * const publicInfo = pick(user, ['id', 'name', 'email'])
- * console.log(publicInfo) // { id: 1, name: 'John', email: 'john@example.com' }
- *
- * const basicInfo = pick(user, ['id', 'name'])
- * console.log(basicInfo) // { id: 1, name: 'John' }
+ * getDomain('https://sub.example.com/path') // 'sub.example.com'
+ * getDomain('https://example.com:8080') // 'example.com'
  * ```
  */
-declare function pick<T extends AnyObject, K extends keyof T>(obj: T, keys: K[]): PickByKey<T, K>;
-
+declare function getDomain(url: string): string;
 /**
- * 将对象按指定键分离为两个对象
+ * 获取 URL 的根域名（顶级域名 + 二级域名）
  *
- * @category Object
- * @param obj 源对象
- * @param keys 要分离的键数组
- * @returns 包含picked和omitted两个对象的结果
+ * @category URL
+ * @param url URL 字符串
+ * @returns 根域名，解析失败返回空字符串
  * @example
  * ```ts
- * const user = {
- *   id: 1,
- *   name: 'John',
- *   email: 'john@example.com',
- *   password: 'secret',
- *   role: 'admin'
- * }
- *
- * const { picked, omitted } = separate(user, ['id', 'name'])
- * console.log(picked) // { id: 1, name: 'John' }
- * console.log(omitted) // { email: 'john@example.com', password: 'secret', role: 'admin' }
- *
- * // 用于分离敏感信息
- * const { picked: publicData, omitted: privateData } = separate(user, ['id', 'name', 'email'])
+ * getRootDomain('https://sub.example.com') // 'example.com'
+ * getRootDomain('https://a.b.example.co.uk') // 'example.co.uk'
  * ```
  */
-declare function separate<T extends AnyObject, K extends keyof T>(obj: T, keys: K[]): {
-    picked: PickByKey<T, K>;
-    omitted: OmitByKey<T, K>;
-};
+declare function getRootDomain(url: string): string;
 /**
- * 将对象按多分组键集合进行分离（浅层），返回各分组与 others
- *
- * - 键冲突策略：先到先得。若同一键出现在多个分组中，则归入第一个匹配到的分组
- * - 仅处理对象自有的浅层键，不解析深层路径
- * - 分组中包含不存在于对象的键将被忽略
+ * 获取 URL 的文件扩展名
  *
- * @category Object
- * @param obj 源对象
- * @param groups 分组映射，如 { a: ['x', 'y'], b: ['z'] }
- * @returns 一个对象，包含每个分组的子对象以及 others（其余未被分组捕获的键）
+ * @category URL
+ * @param url URL 字符串
+ * @returns 文件扩展名（不含点），无扩展名返回空字符串
  * @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' }
+ * getUrlExtension('https://example.com/file.pdf') // 'pdf'
+ * getUrlExtension('https://example.com/file.tar.gz') // 'gz'
+ * getUrlExtension('https://example.com/path/') // ''
  * ```
  */
-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]>;
-};
-
+declare function getUrlExtension(url: string): string;
 /**
- * 将字符串转换为Start Case格式（每个单词首字母大写，用空格分隔）。
+ * 获取 URL 的文件名
  *
- * @category String
- * @param str 要转换的字符串
- * @returns Start Case格式的字符串
+ * @category URL
+ * @param url URL 字符串
+ * @param includeExtension 是否包含扩展名，默认 true
+ * @returns 文件名
  * @example
  * ```ts
- * startCase('firstName') // 'First Name'
- * startCase('first_name') // 'First Name'
- * startCase('first-name') // 'First Name'
- * startCase('XMLHttpRequest') // 'XML Http Request'
+ * getUrlFilename('https://example.com/path/file.pdf') // 'file.pdf'
+ * getUrlFilename('https://example.com/path/file.pdf', false) // 'file'
+ * getUrlFilename('https://example.com/path/') // ''
  * ```
  */
-declare function startCase(str: string): string;
+declare function getUrlFilename(url: string, includeExtension?: boolean): string;
+
 /**
- * 将字符串转换为驼峰命名格式（第一个单词小写，后续单词首字母大写）。
+ * 解析 URL 查询字符串为对象
  *
- * @category String
- * @param str 要转换的字符串
- * @returns 驼峰命名格式的字符串
+ * @category URL
+ * @param search 查询字符串（可带或不带 ?）
+ * @returns 解析后的查询参数对象
  * @example
  * ```ts
- * camelCase('First Name') // 'firstName'
- * camelCase('first_name') // 'firstName'
- * camelCase('first-name') // 'firstName'
- * camelCase('XMLHttpRequest') // 'xmlHttpRequest'
+ * parseQuery('?name=John&age=30')
+ * // { name: 'John', age: '30' }
+ *
+ * parseQuery('tags=a&tags=b&tags=c')
+ * // { tags: ['a', 'b', 'c'] }
+ *
+ * parseQuery('encoded=%E4%B8%AD%E6%96%87')
+ * // { encoded: '中文' }
  * ```
  */
-declare function camelCase(str: string): string;
+declare function parseQuery(search: string): Record<string, string | string[]>;
 /**
- * 将字符串转换为短横线命名格式（kebab-case）。
+ * 将对象序列化为查询字符串
  *
- * @category String
- * @param str 要转换的字符串
- * @returns 短横线命名格式的字符串
+ * @category URL
+ * @param params 查询参数对象
+ * @param options 序列化选项
+ * @param options.skipNull 跳过 null 和 undefined 值
+ * @param options.skipEmpty 跳过空字符串
+ * @param options.arrayFormat 数组格式: 'repeat' (默认), 'bracket', 'index', 'comma'
+ * @returns 查询字符串（不含 ?）
  * @example
  * ```ts
- * kebabCase('firstName') // 'first-name'
- * kebabCase('First Name') // 'first-name'
- * kebabCase('first_name') // 'first-name'
- * kebabCase('XMLHttpRequest') // 'xml-http-request'
+ * stringifyQuery({ name: 'John', age: 30 })
+ * // 'name=John&age=30'
+ *
+ * stringifyQuery({ tags: ['a', 'b', 'c'] })
+ * // 'tags=a&tags=b&tags=c'
+ *
+ * stringifyQuery({ name: '中文' })
+ * // 'name=%E4%B8%AD%E6%96%87'
+ *
+ * stringifyQuery({ a: null, b: undefined, c: '' }, { skipNull: true, skipEmpty: true })
+ * // ''
  * ```
  */
-declare function kebabCase(str: string): string;
+declare function stringifyQuery(params: QueryParams, options?: {
+    /** 跳过 null 和 undefined 值 */
+    skipNull?: boolean;
+    /** 跳过空字符串 */
+    skipEmpty?: boolean;
+    /** 数组格式: 'repeat' (默认), 'bracket', 'index', 'comma' */
+    arrayFormat?: 'repeat' | 'bracket' | 'index' | 'comma';
+}): string;
 /**
- * 将字符串转换为下划线命名格式（snake_case）。
+ * 从 URL 获取指定查询参数的值
  *
- * @category String
- * @param str 要转换的字符串
- * @returns 下划线命名格式的字符串
+ * @category URL
+ * @param url URL 字符串
+ * @param key 参数名
+ * @returns 参数值，不存在返回 null
  * @example
  * ```ts
- * snakeCase('firstName') // 'first_name'
- * snakeCase('First Name') // 'first_name'
- * snakeCase('first-name') // 'first_name'
- * snakeCase('XMLHttpRequest') // 'xml_http_request'
+ * getQueryParam('https://example.com?name=John&age=30', 'name')
+ * // 'John'
+ *
+ * getQueryParam('https://example.com?tags=a&tags=b', 'tags')
+ * // 'a' (返回第一个值)
+ *
+ * getQueryParam('https://example.com', 'name')
+ * // null
  * ```
  */
-declare function snakeCase(str: string): string;
+declare function getQueryParam(url: string, key: string): string | null;
 /**
- * 将字符串转换为帕斯卡命名格式（PascalCase，每个单词首字母大写）。
+ * 从 URL 获取所有指定查询参数的值（用于多值参数）
  *
- * @category String
- * @param str 要转换的字符串
- * @returns 帕斯卡命名格式的字符串
+ * @category URL
+ * @param url URL 字符串
+ * @param key 参数名
+ * @returns 参数值数组
  * @example
  * ```ts
- * pascalCase('firstName') // 'FirstName'
- * pascalCase('first_name') // 'FirstName'
- * pascalCase('first-name') // 'FirstName'
- * pascalCase('XMLHttpRequest') // 'XmlHttpRequest'
+ * getQueryParams('https://example.com?tags=a&tags=b&tags=c', 'tags')
+ * // ['a', 'b', 'c']
+ *
+ * getQueryParams('https://example.com?name=John', 'name')
+ * // ['John']
+ *
+ * getQueryParams('https://example.com', 'name')
+ * // []
  * ```
  */
-declare function pascalCase(str: string): string;
+declare function getQueryParams(url: string, key: string): string[];
 /**
- * 将字符串首字母大写，其余字母小写。
+ * 设置 URL 的查询参数
  *
- * @category String
- * @param str 要转换的字符串
- * @returns 首字母大写的字符串
+ * @category URL
+ * @param url URL 字符串
+ * @param key 参数名
+ * @param value 参数值
+ * @returns 新的 URL 字符串
  * @example
  * ```ts
- * capitalize('hello') // 'Hello'
- * capitalize('HELLO') // 'Hello'
- * capitalize('hello world') // 'Hello world'
+ * setQueryParam('https://example.com', 'page', 1)
+ * // 'https://example.com?page=1'
+ *
+ * setQueryParam('https://example.com?page=1', 'page', 2)
+ * // 'https://example.com?page=2'
+ *
+ * setQueryParam('https://example.com?page=1', 'sort', 'name')
+ * // 'https://example.com?page=1&sort=name'
  * ```
  */
-declare function capitalize(str: string): string;
+declare function setQueryParam(url: string, key: string, value: QueryParamValue): string;
 /**
- * 将字符串首字母大写，其余字母保持原样。
+ * 批量设置 URL 的查询参数
  *
- * @category String
- * @param str 要转换的字符串
- * @returns 首字母大写的字符串
+ * @category URL
+ * @param url URL 字符串
+ * @param params 要设置的参数对象
+ * @returns 新的 URL 字符串
  * @example
  * ```ts
- * upperFirst('hello') // 'Hello'
- * upperFirst('hELLO') // 'HELLO'
- * upperFirst('hello world') // 'Hello world'
+ * setQueryParams('https://example.com', { page: 1, limit: 10 })
+ * // 'https://example.com?page=1&limit=10'
+ *
+ * setQueryParams('https://example.com?page=1', { page: 2, sort: 'name' })
+ * // 'https://example.com?page=2&sort=name'
  * ```
  */
-declare function upperFirst(str: string): string;
+declare function setQueryParams(url: string, params: QueryParams): string;
 /**
- * 将字符串首字母小写，其余字母保持原样。
+ * 追加查询参数（不覆盖已有同名参数）
  *
- * @category String
- * @param str 要转换的字符串
- * @returns 首字母小写的字符串
+ * @category URL
+ * @param url URL 字符串
+ * @param key 参数名
+ * @param value 参数值
+ * @returns 新的 URL 字符串
  * @example
  * ```ts
- * lowerFirst('Hello') // 'hello'
- * lowerFirst('HELLO') // 'hELLO'
- * lowerFirst('Hello World') // 'hello World'
+ * appendQueryParam('https://example.com?tag=a', 'tag', 'b')
+ * // 'https://example.com?tag=a&tag=b'
  * ```
  */
-declare function lowerFirst(str: string): string;
+declare function appendQueryParam(url: string, key: string, value: QueryParamValue): string;
 /**
- * 将字符串转换为大写格式，单词之间用空格分隔。
+ * 删除 URL 的指定查询参数
  *
- * @category String
- * @param str 要转换的字符串
- * @returns 大写格式的字符串
+ * @category URL
+ * @param url URL 字符串
+ * @param key 要删除的参数名
+ * @returns 新的 URL 字符串
  * @example
  * ```ts
- * upperCase('firstName') // 'FIRST NAME'
- * upperCase('first_name') // 'FIRST NAME'
- * upperCase('first-name') // 'FIRST NAME'
- * upperCase('XMLHttpRequest') // 'XML HTTP REQUEST'
+ * removeQueryParam('https://example.com?page=1&sort=name', 'page')
+ * // 'https://example.com?sort=name'
+ *
+ * removeQueryParam('https://example.com?page=1', 'page')
+ * // 'https://example.com'
  * ```
  */
-declare function upperCase(str: string): string;
+declare function removeQueryParam(url: string, key: string): string;
 /**
- * 将字符串转换为小写格式，单词之间用空格分隔。
+ * 检查 URL 是否包含指定查询参数
  *
- * @category String
- * @param str 要转换的字符串
- * @returns 小写格式的字符串
+ * @category URL
+ * @param url URL 字符串
+ * @param key 参数名
+ * @returns 是否包含该参数
  * @example
  * ```ts
- * lowerCase('firstName') // 'first name'
- * lowerCase('First_Name') // 'first name'
- * lowerCase('FIRST-NAME') // 'first name'
- * lowerCase('XMLHttpRequest') // 'xml http request'
+ * hasQueryParam('https://example.com?page=1', 'page') // true
+ * hasQueryParam('https://example.com?page=1', 'sort') // false
+ * hasQueryParam('https://example.com?flag', 'flag') // true (无值参数)
  * ```
  */
-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;
+declare function hasQueryParam(url: string, key: string): boolean;
 
 /**
- * 将字符串分解为单词数组。支持camelCase、snake_case、kebab-case等各种命名风格。
+ * 连接 URL 路径片段
  *
- * @category String
- * @param str 要分解的字符串
- * @returns 单词数组
+ * @category URL
+ * @param parts URL 片段
+ * @returns 连接后的 URL
  * @example
  * ```ts
- * words('helloWorld') // ['hello', 'World']
- * words('hello_world') // ['hello', 'world']
- * words('hello-world') // ['hello', 'world']
- * words('XMLHttpRequest') // ['XML', 'Http', 'Request']
+ * joinUrl('https://example.com', 'api', 'users')
+ * // 'https://example.com/api/users'
+ *
+ * joinUrl('https://example.com/', '/api/', '/users/')
+ * // 'https://example.com/api/users/'
+ *
+ * joinUrl('/api', 'users', '123')
+ * // '/api/users/123'
  * ```
  */
-declare function words(str: string): string[];
-
+declare function joinUrl(...parts: string[]): string;
 /**
- * 树节点类型定义
+ * 规范化 URL 路径（移除多余斜杠、处理 . 和 ..）
  *
- * @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>;
-/**
- * 树形配置输入类型
+ * @category URL
+ * @param url URL 字符串
+ * @returns 规范化后的 URL
+ * @example
+ * ```ts
+ * normalizeUrl('https://example.com//api///users/')
+ * // 'https://example.com/api/users/'
+ *
+ * normalizeUrl('https://example.com/api/../users')
+ * // 'https://example.com/users'
+ *
+ * normalizeUrl('/api/./users/../posts')
+ * // '/api/posts'
+ * ```
  */
-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>;
+declare function normalizeUrl(url: string): string;
 /**
- * 树统计信息类型
+ * 移除 URL 的尾部斜杠
+ *
+ * @category URL
+ * @param url URL 字符串
+ * @returns 移除尾部斜杠后的 URL
+ * @example
+ * ```ts
+ * removeTrailingSlash('https://example.com/') // 'https://example.com'
+ * removeTrailingSlash('https://example.com/path/') // 'https://example.com/path'
+ * removeTrailingSlash('https://example.com') // 'https://example.com'
+ * ```
  */
-type TreeStats = z.infer<typeof _TreeStatsSchema>;
+declare function removeTrailingSlash(url: string): string;
 /**
- * 树节点谓词函数类型
+ * 确保 URL 以斜杠结尾
  *
- * @template T 节点数据类型
- * @param params 包含节点信息的对象参数
- * @param params.node 当前节点
- * @param params.depth 节点深度（从0开始）
- * @param params.path 从根节点到当前节点的路径数组
- * @param params.index 节点在同级节点中的索引
- * @returns 是否满足条件
+ * @category URL
+ * @param url URL 字符串
+ * @returns 带尾部斜杠的 URL
+ * @example
+ * ```ts
+ * ensureTrailingSlash('https://example.com') // 'https://example.com/'
+ * ensureTrailingSlash('https://example.com/path') // 'https://example.com/path/'
+ * ensureTrailingSlash('https://example.com/') // 'https://example.com/'
+ * ```
  */
-type TreePredicate<T = any> = (params: {
-    node: TreeNode<T>;
-    depth: number;
-    path: readonly TreeNode<T>[];
-    index: number;
-}) => boolean;
+declare function ensureTrailingSlash(url: string): string;
 /**
- * 树节点转换函数类型
+ * 移除 URL 的开头斜杠
  *
- * @template T 源节点数据类型
- * @template R 目标节点数据类型
- * @param params 包含节点信息的对象参数
- * @param params.node 当前节点
- * @param params.depth 节点深度（从0开始）
- * @param params.path 从根节点到当前节点的路径数组
- * @param params.index 节点在同级节点中的索引
- * @returns 转换后的节点数据
+ * @category URL
+ * @param url URL 或路径字符串
+ * @returns 移除开头斜杠后的字符串
+ * @example
+ * ```ts
+ * removeLeadingSlash('/path/to/page') // 'path/to/page'
+ * removeLeadingSlash('///path') // 'path'
+ * removeLeadingSlash('path') // 'path'
+ * ```
  */
-type TreeTransformer<T = any, R = any> = (params: {
-    node: TreeNode<T>;
-    depth: number;
-    path: readonly TreeNode<T>[];
-    index: number;
-}) => R;
+declare function removeLeadingSlash(url: string): string;
 /**
- * 树节点访问函数类型
+ * 确保路径以斜杠开头
  *
- * @template T 节点数据类型
- * @param params 包含节点信息的对象参数
- * @param params.node 当前节点
- * @param params.depth 节点深度（从0开始）
- * @param params.path 从根节点到当前节点的路径数组
- * @param params.index 节点在同级节点中的索引
- * @returns 返回false可以终止遍历或跳过子节点
+ * @category URL
+ * @param path 路径字符串
+ * @returns 带开头斜杠的路径
+ * @example
+ * ```ts
+ * ensureLeadingSlash('path/to/page') // '/path/to/page'
+ * ensureLeadingSlash('/path') // '/path'
+ * ```
  */
-type TreeVisitor<T = any> = (params: {
-    node: TreeNode<T>;
-    depth: number;
-    path: readonly TreeNode<T>[];
-    index: number;
-}) => void | boolean;
+declare function ensureLeadingSlash(path: string): string;
 /**
- * 树形数据结构操作工具类
- *
- * 提供了一系列操作树形数据的静态方法，包括：
- * - 查找：find, findAll, findById
- * - 转换：fromList, toList, transform
- * - 过滤：filter
- * - 遍历：forEach
- * - 统计：estimateSize, getStats
- * - 修改：insertBefore, insertAfter, remove
- * - 验证：validate
- *
- * 所有使用谓词函数或访问函数的方法都采用对象解构参数格式：
- * `({ node, depth, path, index }) => boolean`
+ * 构建完整 URL
  *
+ * @category URL
+ * @param base 基础 URL
+ * @param path 路径部分
+ * @param query 查询参数
+ * @param hash 哈希部分
+ * @returns 完整 URL
  * @example
  * ```ts
- * 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')
+ * buildUrl('https://example.com', '/api/users', { page: 1, limit: 10 })
+ * // 'https://example.com/api/users?page=1&limit=10'
  *
- * // 遍历所有节点
- * Tree.forEach(tree, ({ node, depth }) => {
- *   console.log(`${'  '.repeat(depth)}${node.name}`)
- * })
+ * buildUrl('https://example.com', '/page', null, 'section')
+ * // 'https://example.com/page#section'
  *
- * // 转换节点结构
- * const transformed = Tree.transform(tree, ({ node, depth }) => ({
- *   key: node.id,
- *   title: node.name,
- *   level: depth
- * }))
+ * buildUrl('https://example.com', '/api', { ids: [1, 2, 3] })
+ * // 'https://example.com/api?ids=1&ids=2&ids=3'
  * ```
  */
-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[];
-    };
-}
-
+declare function buildUrl(base: string, path?: string, query?: QueryParams | null, hash?: string): string;
 /**
- * 生成字符串的简单哈希值
+ * 解码 URL 组件（安全版本，失败返回原字符串）
  *
- * @category Utilities
- * @param str 待哈希的字符串
- * @returns 32位哈希值转换为36进制字符串
+ * @category URL
+ * @param str 要解码的字符串
+ * @returns 解码后的字符串
  * @example
  * ```ts
- * const hash1 = simpleHash('hello world')
- * console.log(hash1) // 'nf5xd4'
+ * safeDecodeURIComponent('%E4%B8%AD%E6%96%87') // '中文'
+ * safeDecodeURIComponent('hello%20world') // 'hello world'
+ * safeDecodeURIComponent('%invalid%') // '%invalid%'
+ * ```
+ */
+declare function safeDecodeURIComponent(str: string): string;
+/**
+ * 编码 URL 组件（安全版本）
  *
- * const hash2 = simpleHash('hello world')
- * console.log(hash1 === hash2) // true，相同字符串产生相同哈希
+ * @category URL
+ * @param str 要编码的字符串
+ * @returns 编码后的字符串
+ * @example
+ * ```ts
+ * safeEncodeURIComponent('中文') // '%E4%B8%AD%E6%96%87'
+ * safeEncodeURIComponent('hello world') // 'hello%20world'
+ * ```
+ */
+declare function safeEncodeURIComponent(str: string): string;
+/**
+ * 检查两个 URL 是否同源
  *
- * const hash3 = simpleHash('hello world!')
- * console.log(hash1 === hash3) // false，不同字符串产生不同哈希
+ * @category URL
+ * @param url1 第一个 URL
+ * @param url2 第二个 URL
+ * @returns 是否同源
+ * @example
+ * ```ts
+ * isSameOrigin('https://example.com/a', 'https://example.com/b') // true
+ * isSameOrigin('https://example.com', 'https://sub.example.com') // false
+ * isSameOrigin('https://example.com', 'http://example.com') // false
  * ```
  */
-declare function simpleHash(str: string): string;
-
+declare function isSameOrigin(url1: string, url2: string): boolean;
 /**
- * 生成随机UUID字符串
+ * 将相对 URL 转换为绝对 URL
  *
- * @category Utilities
- * @returns 符合UUID v4格式的随机字符串
+ * @category URL
+ * @param relativeUrl 相对 URL
+ * @param baseUrl 基础 URL
+ * @returns 绝对 URL，转换失败返回原字符串
  * @example
  * ```ts
- * const id1 = getRandomUUID()
- * console.log(id1) // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+ * toAbsoluteUrl('/path', 'https://example.com')
+ * // 'https://example.com/path'
  *
- * const id2 = getRandomUUID()
- * console.log(id2) // 'f47ac10b-58cc-4372-a567-0e02b2c3d480'
+ * toAbsoluteUrl('../other', 'https://example.com/api/users')
+ * // 'https://example.com/api/other'
  *
- * // 用于生成唯一标识符
- * const componentId = `component-${getRandomUUID()}`
+ * toAbsoluteUrl('https://other.com', 'https://example.com')
+ * // 'https://other.com' (已是绝对URL，不变)
  * ```
  */
-declare function getRandomUUID(): string;
-
+declare function toAbsoluteUrl(relativeUrl: string, baseUrl: string): string;
 /**
- * 检查值是否为对象类型
+ * 获取两个 URL 之间的相对路径
  *
- * @category Validator
- * @param value 待检查的值
- * @returns 是否为对象类型
+ * @category URL
+ * @param from 起始 URL
+ * @param to 目标 URL
+ * @returns 相对路径
  * @example
  * ```ts
- * console.log(isObject({})) // true
- * console.log(isObject({ name: 'John' })) // true
- * console.log(isObject([])) // false
- * console.log(isObject(null)) // false
- * console.log(isObject('string')) // false
+ * getRelativePath('https://example.com/a/b', 'https://example.com/a/c')
+ * // '../c'
+ *
+ * getRelativePath('https://example.com/a', 'https://example.com/a/b/c')
+ * // 'b/c'
  * ```
  */
-declare function isObject(value: any): value is AnyObject;
+declare function getRelativePath(from: string, to: string): string;
+
 /**
  * 检查值是否为数组类型
  *
- * @category Validator
+ * @category Validators
  * @param value 待检查的值
  * @returns 是否为数组类型
  * @example
@@ -1796,40 +2345,31 @@ declare function isObject(value: any): value is AnyObject;
  * ```
  */
 declare function isArray(value: any): value is any[];
+
 /**
- * 检查值是否为字符串类型
- *
- * @category Validator
- * @param value 待检查的值
- * @returns 是否为字符串类型
- * @example
- * ```ts
- * console.log(isString('hello')) // true
- * console.log(isString('')) // true
- * console.log(isString(123)) // false
- * console.log(isString(null)) // false
- * ```
- */
-declare function isString(value: any): value is string;
-/**
- * 检查值是否为有效数字类型
+ * 检查值是否为空（null、undefined、空字符串、空数组、空对象）
  *
- * @category Validator
+ * @category Validators
  * @param value 待检查的值
- * @returns 是否为有效数字类型
+ * @returns 是否为空值
  * @example
  * ```ts
- * console.log(isNumber(123)) // true
- * console.log(isNumber(0)) // true
- * console.log(isNumber(NaN)) // false
- * console.log(isNumber('123')) // false
+ * console.log(isEmpty(null)) // true
+ * console.log(isEmpty(undefined)) // true
+ * console.log(isEmpty('')) // true
+ * console.log(isEmpty([])) // true
+ * console.log(isEmpty({})) // true
+ * console.log(isEmpty([1, 2])) // false
+ * console.log(isEmpty({ name: 'John' })) // false
+ * console.log(isEmpty('hello')) // false
  * ```
  */
-declare function isNumber(value: any): value is number;
+declare function isEmpty(value: any): boolean;
+
 /**
  * 检查值是否为函数类型
  *
- * @category Validator
+ * @category Validators
  * @param value 待检查的值
  * @returns 是否为函数类型
  * @example
@@ -1841,29 +2381,44 @@ declare function isNumber(value: any): value is number;
  * ```
  */
 declare function isFunction(value: any): value is (...args: any[]) => any;
+
 /**
- * 检查值是否为空（null、undefined、空字符串、空数组、空对象）
+ * 检查值是否为有效数字类型
  *
- * @category Validator
+ * @category Validators
  * @param value 待检查的值
- * @returns 是否为空值
+ * @returns 是否为有效数字类型
  * @example
  * ```ts
- * console.log(isEmpty(null)) // true
- * console.log(isEmpty(undefined)) // true
- * console.log(isEmpty('')) // true
- * console.log(isEmpty([])) // true
- * console.log(isEmpty({})) // true
- * console.log(isEmpty([1, 2])) // false
- * console.log(isEmpty({ name: 'John' })) // false
- * console.log(isEmpty('hello')) // false
+ * console.log(isNumber(123)) // true
+ * console.log(isNumber(0)) // true
+ * console.log(isNumber(NaN)) // false
+ * console.log(isNumber('123')) // false
  * ```
  */
-declare function isEmpty(value: any): boolean;
+declare function isNumber(value: any): value is number;
+
+/**
+ * 检查值是否为对象类型
+ *
+ * @category Validators
+ * @param value 待检查的值
+ * @returns 是否为对象类型
+ * @example
+ * ```ts
+ * console.log(isObject({})) // true
+ * console.log(isObject({ name: 'John' })) // true
+ * console.log(isObject([])) // false
+ * console.log(isObject(null)) // false
+ * console.log(isObject('string')) // false
+ * ```
+ */
+declare function isObject(value: any): value is AnyObject;
+
 /**
  * 判断值是否为纯对象（不包括数组、函数、日期等）
  *
- * @category Object
+ * @category Validators
  * @param value 要检查的值
  * @returns 是否为纯对象
  * @example
@@ -1876,5 +2431,44 @@ declare function isEmpty(value: any): boolean;
  */
 declare function isPlainObject(value: unknown): value is Record<string, any>;
 
-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 };
+/**
+ * 检查值是否为字符串类型
+ *
+ * @category Validators
+ * @param value 待检查的值
+ * @returns 是否为字符串类型
+ * @example
+ * ```ts
+ * console.log(isString('hello')) // true
+ * console.log(isString('')) // true
+ * console.log(isString(123)) // false
+ * console.log(isString(null)) // false
+ * ```
+ */
+declare function isString(value: any): value is string;
+
+/**
+ * 检查值是否为有效的容器类型（对象或数组）
+ *
+ * - isObject: 仅检查纯对象，排除数组
+ * - isValidContainer: 检查所有可作为容器的类型（对象 + 数组）
+ *
+ * 支持 Vue 3 的 Proxy 对象和 Proxy 数组。
+ *
+ * @category Validators
+ * @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;
+
+export { Tree, appendQueryParam, buildUrl, camelCase, capitalize, chunk, convertSvgToPng, convertToKebabCase, debounce, deepClone, ensureLeadingSlash, ensureTrailingSlash, extractFilename, flatten, formatFileSize, getDomain, getPath, getQueryParam, getQueryParams, getRandomUUID, getRelativePath, getRootDomain, getUrlExtension, getUrlFilename, hasQueryParam, isAbsoluteUrl, isArray, isEmpty, isFunction, isNumber, isObject, isPlainObject, isRelativeUrl, isSameOrigin, isString, isValidContainer, isValidUrl, joinPath, joinUrl, kebabCase, lowerCase, lowerFirst, normalizeUrl, omit, omitUndefined, parseQuery, parseUrl, pascalCase, pick, removeLeadingSlash, removeQueryParam, removeTrailingSlash, replaceCurrentColor, safeDecodeURIComponent, safeEncodeURIComponent, separate, separateMany, setPath, setQueryParam, setQueryParams, simpleHash, sleep, sleepWithCancel, snakeCase, startCase, stringifyQuery, throttle, toAbsoluteUrl, 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, ParsedUrl, PartialByKeys, PathInput, PathSegment, PathSegments, PickByKey, QueryParamValue, QueryParams, ReactiveValue, ReadonlyByKeys, RenameKeys, RequiredByKeys, StorageConfig, StorageConfigInput, StorageType, StringOrVNode, StripNullable, Suggest, TreeConfig, TreeConfigInput, TreeNode, TreePredicate, TreeStats, TreeTransformer, TreeVisitor, UnionToIntersection, UnknownObject };