@lee-zg/melange 1.0.0

package/dist/utils/index.d.ts

@@ -0,0 +1,1179 @@
+import { A as AnyFunction } from '../types-BtOUCLB-.js';
+
+/**
+ * @fileoverview 对象操作工具
+ * @module melange/utils/object
+ * @description 提供深度克隆、合并和
+ * 安全操作 JavaScript 对象的工具。
+ */
+/**
+ * 创建对象的深度克隆。
+ * 处理嵌套对象、数组、日期和其他内置类型。
+ *
+ * @description
+ * 此函数创建输入的真实深度副本，意味着嵌套
+ * 对象也会被克隆而不是引用。它处理循环
+ * 引用和特殊对象类型。
+ *
+ * @example
+ * ```typescript
+ * const original = { a: 1, b: { c: 2 } };
+ * const clone = deepClone(original);
+ *
+ * clone.b.c = 3;
+ * console.log(original.b.c); // 2 (未改变)
+ * ```
+ *
+ * @template T - 要克隆的值的类型
+ * @param value - 要克隆的值
+ * @returns 值的深度副本
+ */
+declare function deepClone<T>(value: T): T;
+/**
+ * 深度合并多个对象为一个。
+ * 后面的对象会覆盖前面对象的冲突键。
+ *
+ * @example
+ * ```typescript
+ * const base = { a: 1, b: { c: 2, d: 3 } };
+ * const override = { b: { c: 4 } };
+ * const merged = deepMerge(base, override);
+ * // { a: 1, b: { c: 4, d: 3 } }
+ * ```
+ *
+ * @template T - 合并对象的类型
+ * @param objects - 要合并的对象
+ * @returns 合并后的对象
+ */
+declare function deepMerge<T extends object>(...objects: Partial<T>[]): T;
+/**
+ * 从对象中选择指定属性。
+ *
+ * @example
+ * ```typescript
+ * const user = { id: 1, name: 'John', email: 'john@example.com' };
+ * const partial = pick(user, ['id', 'name']);
+ * // { id: 1, name: 'John' }
+ * ```
+ *
+ * @template T - 对象类型
+ * @template K - 要选择的键
+ * @param obj - 源对象
+ * @param keys - 要选择的键
+ * @returns 只包含指定键的新对象
+ */
+declare function pick<T extends object, K extends keyof T>(obj: T, keys: readonly K[]): Pick<T, K>;
+/**
+ * 从对象中省略指定属性。
+ *
+ * @example
+ * ```typescript
+ * const user = { id: 1, name: 'John', password: 'secret' };
+ * const safe = omit(user, ['password']);
+ * // { id: 1, name: 'John' }
+ * ```
+ *
+ * @template T - 对象类型
+ * @template K - 要省略的键
+ * @param obj - 源对象
+ * @param keys - 要省略的键
+ * @returns 不包含指定键的新对象
+ */
+declare function omit<T extends object, K extends keyof T>(obj: T, keys: readonly K[]): Omit<T, K>;
+/**
+ * 使用路径字符串或数组获取嵌套属性值。
+ *
+ * @example
+ * ```typescript
+ * const obj = { a: { b: { c: 42 } } };
+ * get(obj, 'a.b.c'); // 42
+ * get(obj, ['a', 'b', 'c']); // 42
+ * get(obj, 'a.x.y', 'default'); // 'default'
+ * ```
+ *
+ * @template T - 默认值类型
+ * @param obj - 要获取的对象
+ * @param path - 属性路径
+ * @param defaultValue - 路径不存在时的默认值
+ * @returns 路径处的值或默认值
+ */
+declare function get<T = unknown>(obj: unknown, path: string | readonly string[], defaultValue?: T): T;
+/**
+ * 使用路径字符串或数组设置嵌套属性值。
+ * 根据需要创建中间对象。
+ *
+ * @example
+ * ```typescript
+ * const obj = { a: { b: 1 } };
+ * set(obj, 'a.c.d', 42);
+ * // { a: { b: 1, c: { d: 42 } } }
+ * ```
+ *
+ * @template T - 对象类型
+ * @param obj - 要修改的对象
+ * @param path - 属性路径
+ * @param value - 要设置的值
+ * @returns 修改后的对象
+ */
+declare function set<T extends object>(obj: T, path: string | readonly string[], value: unknown): T;
+/**
+ * 检查对象是否具有嵌套属性。
+ *
+ * @example
+ * ```typescript
+ * const obj = { a: { b: { c: 42 } } };
+ * has(obj, 'a.b.c'); // true
+ * has(obj, 'a.x');   // false
+ * ```
+ *
+ * @param obj - 要检查的对象
+ * @param path - 要检查的路径
+ * @returns 如果路径存在则返回 true
+ */
+declare function has(obj: unknown, path: string | readonly string[]): boolean;
+/**
+ * 检查值是否为普通对象（非数组、null 或其他类型）。
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是普通对象则返回 true
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 从键值对创建对象。
+ *
+ * @example
+ * ```typescript
+ * fromEntries([['a', 1], ['b', 2]]);
+ * // { a: 1, b: 2 }
+ * ```
+ *
+ * @template K - 键类型
+ * @template V - 值类型
+ * @param entries - 键值对数组
+ * @returns 从条目创建的对象
+ */
+declare function fromEntries<K extends string | number | symbol, V>(entries: readonly (readonly [K, V])[]): Record<K, V>;
+/**
+ * 映射对象值同时保留键。
+ *
+ * @example
+ * ```typescript
+ * const prices = { apple: 1, banana: 2 };
+ * const doubled = mapValues(prices, v => v * 2);
+ * // { apple: 2, banana: 4 }
+ * ```
+ *
+ * @template T - 原始值类型
+ * @template U - 映射值类型
+ * @param obj - 要映射的对象
+ * @param fn - 映射函数
+ * @returns 具有映射值的对象
+ */
+declare function mapValues<T, U>(obj: Record<string, T>, fn: (value: T, key: string) => U): Record<string, U>;
+/**
+ * 基于谓词过滤对象条目。
+ *
+ * @example
+ * ```typescript
+ * const prices = { apple: 1, banana: 2, cherry: 3 };
+ * const expensive = filterObject(prices, v => v > 1);
+ * // { banana: 2, cherry: 3 }
+ * ```
+ *
+ * @template T - 值类型
+ * @param obj - 要过滤的对象
+ * @param predicate - 过滤函数
+ * @returns 过滤后的对象
+ */
+declare function filterObject<T>(obj: Record<string, T>, predicate: (value: T, key: string) => boolean): Record<string, T>;
+
+/**
+ * @fileoverview 数组操作工具
+ * @module melange/utils/array
+ * @description 提供操作数组的工具，包括
+ * 分块、扁平化、分组和排序。
+ */
+/**
+ * 将数组拆分为指定大小的块。
+ *
+ * @example
+ * ```typescript
+ * chunk([1, 2, 3, 4, 5], 2);
+ * // [[1, 2], [3, 4], [5]]
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @param array - 要分块的数组
+ * @param size - 块大小
+ * @returns 块数组
+ */
+declare function chunk<T>(array: readonly T[], size: number): T[][];
+/**
+ * 将嵌套数组扁平化一级。
+ *
+ * @example
+ * ```typescript
+ * flatten([[1, 2], [3, 4], [5]]);
+ * // [1, 2, 3, 4, 5]
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @param array - 要扁平化的嵌套数组
+ * @returns 扁平化后的数组
+ */
+declare function flatten<T>(array: readonly (T | readonly T[])[]): T[];
+/**
+ * 深度扁平化嵌套数组。
+ *
+ * @example
+ * ```typescript
+ * flattenDeep([1, [2, [3, [4, 5]]]]);
+ * // [1, 2, 3, 4, 5]
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @param array - 要扁平化的嵌套数组
+ * @returns 深度扁平化后的数组
+ */
+declare function flattenDeep<T>(array: readonly unknown[]): T[];
+/**
+ * 返回数组中的唯一元素。
+ *
+ * @example
+ * ```typescript
+ * unique([1, 2, 2, 3, 3, 3]);
+ * // [1, 2, 3]
+ *
+ * const users = [{ id: 1 }, { id: 2 }, { id: 1 }];
+ * unique(users, u => u.id);
+ * // [{ id: 1 }, { id: 2 }]
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @template K - 唯一性的键类型
+ * @param array - 要去重的数组
+ * @param keyFn - 提取比较键的可选函数
+ * @returns 包含唯一元素的数组
+ */
+declare function unique<T, K = T>(array: readonly T[], keyFn?: (item: T) => K): T[];
+/**
+ * 按键对数组元素进行分组。
+ *
+ * @example
+ * ```typescript
+ * const users = [
+ *   { name: 'Alice', age: 25 },
+ *   { name: 'Bob', age: 30 },
+ *   { name: 'Charlie', age: 25 }
+ * ];
+ *
+ * groupBy(users, u => u.age);
+ * // {
+ * //   25: [{ name: 'Alice', age: 25 }, { name: 'Charlie', age: 25 }],
+ * //   30: [{ name: 'Bob', age: 30 }]
+ * // }
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @template K - 分组键类型
+ * @param array - 要分组的数组
+ * @param keyFn - 提取分组键的函数
+ * @returns 包含分组元素的对象
+ */
+declare function groupBy<T, K extends string | number | symbol>(array: readonly T[], keyFn: (item: T) => K): Record<K, T[]>;
+/**
+ * 按键对数组进行排序，返回新的排序数组。
+ *
+ * @example
+ * ```typescript
+ * const users = [
+ *   { name: 'Charlie', age: 25 },
+ *   { name: 'Alice', age: 30 },
+ *   { name: 'Bob', age: 20 }
+ * ];
+ *
+ * sortBy(users, u => u.age);
+ * // 按年龄升序排列
+ *
+ * sortBy(users, u => u.name, 'desc');
+ * // 按姓名降序排列
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @template K - 排序键类型
+ * @param array - 要排序的数组
+ * @param keyFn - 提取排序键的函数
+ * @param order - 排序顺序: 'asc' 或 'desc'
+ * @returns 新的排序数组
+ */
+declare function sortBy<T, K extends string | number>(array: readonly T[], keyFn: (item: T) => K, order?: 'asc' | 'desc'): T[];
+/**
+ * 根据谓词将数组分区为两个数组。
+ *
+ * @example
+ * ```typescript
+ * const [evens, odds] = partition([1, 2, 3, 4, 5], n => n % 2 === 0);
+ * // evens = [2, 4], odds = [1, 3, 5]
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @param array - 要分区的数组
+ * @param predicate - 分区谓词
+ * @returns [匹配, 不匹配] 数组的元组
+ */
+declare function partition<T>(array: readonly T[], predicate: (item: T) => boolean): [T[], T[]];
+/**
+ * 将多个数组压缩在一起。
+ *
+ * @example
+ * ```typescript
+ * zip([1, 2, 3], ['a', 'b', 'c']);
+ * // [[1, 'a'], [2, 'b'], [3, 'c']]
+ *
+ * zip([1, 2], ['a', 'b', 'c']);
+ * // [[1, 'a'], [2, 'b']]
+ * ```
+ *
+ * @template T - 第一个数组元素类型
+ * @template U - 第二个数组元素类型
+ * @param arr1 - 第一个数组
+ * @param arr2 - 第二个数组
+ * @returns 元组数组
+ */
+declare function zip<T, U>(arr1: readonly T[], arr2: readonly U[]): Array<[T, U]>;
+/**
+ * 返回数组的第一个元素，如果为空则返回 undefined。
+ *
+ * @example
+ * ```typescript
+ * first([1, 2, 3]); // 1
+ * first([]);        // undefined
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @param array - 数组
+ * @returns 第一个元素或 undefined
+ */
+declare function first<T>(array: readonly T[]): T | undefined;
+/**
+ * 返回数组的最后一个元素，如果为空则返回 undefined。
+ *
+ * @example
+ * ```typescript
+ * last([1, 2, 3]); // 3
+ * last([]);        // undefined
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @param array - 数组
+ * @returns 最后一个元素或 undefined
+ */
+declare function last<T>(array: readonly T[]): T | undefined;
+/**
+ * 从数组中返回随机元素。
+ *
+ * @example
+ * ```typescript
+ * sample([1, 2, 3, 4, 5]); // 随机元素
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @param array - 数组
+ * @returns 随机元素，如果为空则返回 undefined
+ */
+declare function sample<T>(array: readonly T[]): T | undefined;
+/**
+ * 随机打乱数组（Fisher-Yates 算法），返回新数组。
+ *
+ * @example
+ * ```typescript
+ * shuffle([1, 2, 3, 4, 5]); // 随机打乱
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @param array - 要打乱的数组
+ * @returns 新的打乱数组
+ */
+declare function shuffle<T>(array: readonly T[]): T[];
+/**
+ * 创建从开始到结束（不包含）的数字数组。
+ *
+ * @example
+ * ```typescript
+ * range(5);       // [0, 1, 2, 3, 4]
+ * range(1, 5);    // [1, 2, 3, 4]
+ * range(0, 10, 2); // [0, 2, 4, 6, 8]
+ * ```
+ *
+ * @param startOrEnd - 如果只有这一个参数，则为结束值；否则为开始值
+ * @param end - 结束值（不包含）
+ * @param step - 数字之间的步长
+ * @returns 数字数组
+ */
+declare function range(startOrEnd: number, end?: number, step?: number): number[];
+/**
+ * 返回两个数组的交集。
+ *
+ * @example
+ * ```typescript
+ * intersection([1, 2, 3], [2, 3, 4]); // [2, 3]
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @param arr1 - 第一个数组
+ * @param arr2 - 第二个数组
+ * @returns 两个数组中存在的元素
+ */
+declare function intersection<T>(arr1: readonly T[], arr2: readonly T[]): T[];
+/**
+ * 返回两个数组的差集（在 arr1 中但不在 arr2 中的元素）。
+ *
+ * @example
+ * ```typescript
+ * difference([1, 2, 3], [2, 3, 4]); // [1]
+ * ```
+ *
+ * @template T - 数组元素类型
+ * @param arr1 - 第一个数组
+ * @param arr2 - 第二个数组
+ * @returns 在 arr1 中但不在 arr2 中的元素
+ */
+declare function difference<T>(arr1: readonly T[], arr2: readonly T[]): T[];
+
+/**
+ * @fileoverview 字符串操作工具
+ * @module melange/utils/string
+ * @description 提供字符串操作工具，包括
+ * 大小写转换、截断和格式化。
+ */
+/**
+ * 将字符串的第一个字母大写。
+ *
+ * @example
+ * ```typescript
+ * capitalize('hello'); // 'Hello'
+ * capitalize('HELLO'); // 'HELLO'
+ * ```
+ *
+ * @param str - 要大写的字符串
+ * @returns 大写后的字符串
+ */
+declare function capitalize(str: string): string;
+/**
+ * 将字符串转换为驼峰命名法。
+ *
+ * @example
+ * ```typescript
+ * camelCase('hello world');   // 'helloWorld'
+ * camelCase('hello-world');   // 'helloWorld'
+ * camelCase('hello_world');   // 'helloWorld'
+ * camelCase('HelloWorld');    // 'helloWorld'
+ * ```
+ *
+ * @param str - 要转换的字符串
+ * @returns 驼峰命名法字符串
+ */
+declare function camelCase(str: string): string;
+/**
+ * 将字符串转换为帕斯卡命名法。
+ *
+ * @example
+ * ```typescript
+ * pascalCase('hello world');   // 'HelloWorld'
+ * pascalCase('hello-world');   // 'HelloWorld'
+ * pascalCase('hello_world');   // 'HelloWorld'
+ * ```
+ *
+ * @param str - 要转换的字符串
+ * @returns 帕斯卡命名法字符串
+ */
+declare function pascalCase(str: string): string;
+/**
+ * 将字符串转换为蛇形命名法。
+ *
+ * @example
+ * ```typescript
+ * snakeCase('helloWorld');  // 'hello_world'
+ * snakeCase('HelloWorld');  // 'hello_world'
+ * snakeCase('hello-world'); // 'hello_world'
+ * ```
+ *
+ * @param str - 要转换的字符串
+ * @returns 蛇形命名法字符串
+ */
+declare function snakeCase(str: string): string;
+/**
+ * 将字符串转换为烤肉串命名法。
+ *
+ * @example
+ * ```typescript
+ * kebabCase('helloWorld');  // 'hello-world'
+ * kebabCase('HelloWorld');  // 'hello-world'
+ * kebabCase('hello_world'); // 'hello-world'
+ * ```
+ *
+ * @param str - 要转换的字符串
+ * @returns 烤肉串命名法字符串
+ */
+declare function kebabCase(str: string): string;
+/**
+ * 将字符串转换为常量命名法。
+ *
+ * @example
+ * ```typescript
+ * constantCase('helloWorld');  // 'HELLO_WORLD'
+ * constantCase('hello-world'); // 'HELLO_WORLD'
+ * ```
+ *
+ * @param str - 要转换的字符串
+ * @returns 常量命名法字符串
+ */
+declare function constantCase(str: string): string;
+/**
+ * 将字符串截断到最大长度，必要时添加省略号。
+ *
+ * @example
+ * ```typescript
+ * truncate('Hello, World!', 10);       // 'Hello, ...'
+ * truncate('Hello', 10);               // 'Hello'
+ * truncate('Hello, World!', 10, '…');  // 'Hello, Wo…'
+ * ```
+ *
+ * @param str - 要截断的字符串
+ * @param maxLength - 最大长度
+ * @param suffix - 要添加的后缀（默认：'...'）
+ * @returns 截断后的字符串
+ */
+declare function truncate(str: string, maxLength: number, suffix?: string): string;
+/**
+ * 在字符串左侧填充到最小长度。
+ *
+ * @example
+ * ```typescript
+ * padStart('5', 3, '0');  // '005'
+ * padStart('42', 3, '0'); // '042'
+ * ```
+ *
+ * @param str - 要填充的字符串
+ * @param length - 目标长度
+ * @param padChar - 填充字符
+ * @returns 填充后的字符串
+ */
+declare function padStart(str: string, length: number, padChar?: string): string;
+/**
+ * 在字符串右侧填充到最小长度。
+ *
+ * @example
+ * ```typescript
+ * padEnd('5', 3, '0');  // '500'
+ * padEnd('42', 3, '0'); // '420'
+ * ```
+ *
+ * @param str - 要填充的字符串
+ * @param length - 目标长度
+ * @param padChar - 填充字符
+ * @returns 填充后的字符串
+ */
+declare function padEnd(str: string, length: number, padChar?: string): string;
+/**
+ * 删除前导和尾随空白并折叠多个空格。
+ *
+ * @example
+ * ```typescript
+ * collapseWhitespace('  hello   world  '); // 'hello world'
+ * ```
+ *
+ * @param str - 要清理的字符串
+ * @returns 清理后的字符串
+ */
+declare function collapseWhitespace(str: string): string;
+/**
+ * 转义特殊字符以在 HTML 中使用。
+ *
+ * @example
+ * ```typescript
+ * escapeHtml('<script>alert("xss")</script>');
+ * // '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+ * ```
+ *
+ * @param str - 要转义的字符串
+ * @returns 转义后的字符串
+ */
+declare function escapeHtml(str: string): string;
+/**
+ * 反转义 HTML 实体。
+ *
+ * @example
+ * ```typescript
+ * unescapeHtml('&lt;div&gt;Hello&lt;/div&gt;');
+ * // '<div>Hello</div>'
+ * ```
+ *
+ * @param str - 要反转义的字符串
+ * @returns 反转义后的字符串
+ */
+declare function unescapeHtml(str: string): string;
+/**
+ * 生成指定长度的随机字符串。
+ *
+ * @example
+ * ```typescript
+ * randomString(10);        // 'a1b2c3d4e5'
+ * randomString(8, 'abc');  // 'abcabcab'
+ * ```
+ *
+ * @param length - 要生成的字符串长度
+ * @param chars - 要使用的字符（默认：字母数字）
+ * @returns 随机字符串
+ */
+declare function randomString(length: number, chars?: string): string;
+/**
+ * 从字符串中提取单词。
+ *
+ * @example
+ * ```typescript
+ * words('helloWorld');    // ['hello', 'World']
+ * words('hello-world');   // ['hello', 'world']
+ * words('hello_world');   // ['hello', 'world']
+ * ```
+ *
+ * @param str - 要提取单词的字符串
+ * @returns 单词数组
+ */
+declare function words(str: string): string[];
+/**
+ * 将字符串转换为标题大小写。
+ *
+ * @example
+ * ```typescript
+ * titleCase('hello world'); // 'Hello World'
+ * titleCase('the quick brown fox'); // 'The Quick Brown Fox'
+ * ```
+ *
+ * @param str - 要转换的字符串
+ * @returns 标题大小写字符串
+ */
+declare function titleCase(str: string): string;
+/**
+ * 反转字符串。
+ *
+ * @example
+ * ```typescript
+ * reverse('hello'); // 'olleh'
+ * ```
+ *
+ * @param str - 要反转的字符串
+ * @returns 反转后的字符串
+ */
+declare function reverse(str: string): string;
+/**
+ * 计算子字符串的出现次数。
+ *
+ * @example
+ * ```typescript
+ * countOccurrences('hello hello hello', 'hello'); // 3
+ * ```
+ *
+ * @param str - 要搜索的字符串
+ * @param substr - 要计数的子字符串
+ * @returns 出现次数
+ */
+declare function countOccurrences(str: string, substr: string): number;
+
+/**
+ * @fileoverview 计时和速率限制工具
+ * @module melange/utils/timing
+ * @description 提供防抖、节流、延迟、
+ * 重试和超时处理的工具。
+ */
+
+/**
+ * 创建函数的防抖版本。
+ * 防抖函数会延迟调用，直到自上次调用防抖函数以来经过了 `wait` 毫秒。
+ *
+ * @description
+ * 防抖对于限制用户输入事件（如在搜索框中打字）的速率很有用，
+ * 您希望等到用户停止打字后再进行 API 调用。
+ *
+ * @example
+ * ```typescript
+ * const search = debounce((query: string) => {
+ *   console.log('搜索中:', query);
+ * }, 300);
+ *
+ * search('h');
+ * search('he');
+ * search('hel');
+ * search('hell');
+ * search('hello');
+ * // 只在 300ms 无调用后记录 '搜索中: hello'
+ * ```
+ *
+ * @template T - 函数类型
+ * @param fn - 要防抖的函数
+ * @param wait - 等待的毫秒数
+ * @param options - 可选配置
+ * @returns 函数的防抖版本
+ */
+declare function debounce<T extends AnyFunction>(fn: T, wait: number, options?: {
+    leading?: boolean;
+    trailing?: boolean;
+}): T & {
+    cancel: () => void;
+    flush: () => void;
+};
+/**
+ * 创建函数的节流版本。
+ * 节流函数每 `limit` 毫秒最多调用一次。
+ *
+ * @description
+ * 节流对于限制频繁触发的事件（如滚动或调整大小事件）的速率很有用，
+ * 您希望确保处理程序以一致的速率运行。
+ *
+ * @example
+ * ```typescript
+ * const onScroll = throttle(() => {
+ *   console.log('滚动位置:', window.scrollY);
+ * }, 100);
+ *
+ * window.addEventListener('scroll', onScroll);
+ * // 滚动期间最多每 100ms 记录一次
+ * ```
+ *
+ * @template T - 函数类型
+ * @param fn - 要节流的函数
+ * @param limit - 调用之间的最小时间
+ * @returns 函数的节流版本
+ */
+declare function throttle<T extends AnyFunction>(fn: T, limit: number): T & {
+    cancel: () => void;
+};
+/**
+ * 创建在指定延迟后解决的承诺。
+ *
+ * @example
+ * ```typescript
+ * console.log('开始');
+ * await delay(1000);
+ * console.log('1秒后');
+ *
+ * // 带值
+ * const result = await delay(1000, 'hello');
+ * console.log(result); // 'hello'
+ * ```
+ *
+ * @template T - 值类型
+ * @param ms - 延迟毫秒数
+ * @param value - 解决时的可选值
+ * @returns 在延迟后解决的承诺
+ */
+declare function delay<T = void>(ms: number, value?: T): Promise<T>;
+/**
+ * 重试异步函数直到成功或达到最大重试次数。
+ *
+ * @example
+ * ```typescript
+ * const result = await retry(
+ *   () => fetch('/api/data').then(r => r.json()),
+ *   {
+ *     maxRetries: 3,
+ *     delay: 1000,
+ *     backoff: 'exponential'
+ *   }
+ * );
+ * ```
+ *
+ * @template T - 返回类型
+ * @param fn - 要重试的异步函数
+ * @param options - 重试选项
+ * @returns 函数的结果
+ * @throws 如果所有重试都失败，则抛出最后一个错误
+ */
+declare function retry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    delay?: number;
+    backoff?: 'none' | 'linear' | 'exponential';
+    onRetry?: (error: unknown, attempt: number) => void;
+}): Promise<T>;
+/**
+ * 用超时包装承诺。
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await timeout(fetch('/api/data'), 5000);
+ * } catch (error) {
+ *   if (error.message.includes('timed out')) {
+ *     console.log('请求耗时太长');
+ *   }
+ * }
+ * ```
+ *
+ * @template T - 承诺结果类型
+ * @param promise - 要包装的承诺
+ * @param ms - 超时毫秒数
+ * @param errorMessage - 可选的自定义错误消息
+ * @returns 如果超过超时时间则拒绝的承诺
+ */
+declare function timeout<T>(promise: Promise<T>, ms: number, errorMessage?: string): Promise<T>;
+/**
+ * 创建可以从外部解决或拒绝的延迟承诺。
+ *
+ * @example
+ * ```typescript
+ * const deferred = createDeferred<string>();
+ *
+ * setTimeout(() => {
+ *   deferred.resolve('Hello!');
+ * }, 1000);
+ *
+ * const result = await deferred.promise; // 'Hello!'
+ * ```
+ *
+ * @template T - 承诺结果类型
+ * @returns 带有 promise、resolve 和 reject 的延迟对象
+ */
+declare function createDeferred<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason?: unknown) => void;
+};
+/**
+ * 以并发限制运行多个异步函数。
+ *
+ * @example
+ * ```typescript
+ * const urls = ['url1', 'url2', 'url3', 'url4', 'url5'];
+ *
+ * const results = await parallel(
+ *   urls.map(url => () => fetch(url)),
+ *   { concurrency: 2 }
+ * );
+ * ```
+ *
+ * @template T - 结果类型
+ * @param tasks - 异步任务函数数组
+ * @param options - 配置选项
+ * @returns 结果数组
+ */
+declare function parallel<T>(tasks: Array<() => Promise<T>>, options?: {
+    concurrency?: number;
+}): Promise<T[]>;
+/**
+ * 顺序运行任务，一个接一个。
+ *
+ * @example
+ * ```typescript
+ * const results = await sequence([
+ *   () => fetch('/api/step1'),
+ *   () => fetch('/api/step2'),
+ *   () => fetch('/api/step3'),
+ * ]);
+ * ```
+ *
+ * @template T - 结果类型
+ * @param tasks - 异步任务函数数组
+ * @returns 结果数组
+ */
+declare function sequence<T>(tasks: Array<() => Promise<T>>): Promise<T[]>;
+
+/**
+ * @fileoverview 类型检查和验证工具
+ * @module melange/utils/guards
+ * @description 提供类型守卫和验证函数用于
+ * 运行时类型检查。
+ */
+/**
+ * 检查值是否为字符串。
+ *
+ * @example
+ * ```typescript
+ * isString('hello'); // true
+ * isString(123);     // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是字符串则返回 true
+ */
+declare function isString(value: unknown): value is string;
+/**
+ * 检查值是否为数字（且不是 NaN）。
+ *
+ * @example
+ * ```typescript
+ * isNumber(123);      // true
+ * isNumber(NaN);      // false
+ * isNumber('123');    // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是有限数字则返回 true
+ */
+declare function isNumber(value: unknown): value is number;
+/**
+ * 检查值是否为布尔值。
+ *
+ * @example
+ * ```typescript
+ * isBoolean(true);    // true
+ * isBoolean(false);   // true
+ * isBoolean(0);       // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是布尔值则返回 true
+ */
+declare function isBoolean(value: unknown): value is boolean;
+/**
+ * 检查值是否为对象（非 null 或数组）。
+ *
+ * @example
+ * ```typescript
+ * isObject({});       // true
+ * isObject([]);       // false
+ * isObject(null);     // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是普通对象则返回 true
+ */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 检查值是否为数组。
+ *
+ * @example
+ * ```typescript
+ * isArray([]);       // true
+ * isArray([1, 2]);   // true
+ * isArray({});       // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是数组则返回 true
+ */
+declare function isArray(value: unknown): value is unknown[];
+/**
+ * 检查值是否为函数。
+ *
+ * @example
+ * ```typescript
+ * isFunction(() => {});           // true
+ * isFunction(function() {});      // true
+ * isFunction(async () => {});     // true
+ * isFunction({});                 // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是函数则返回 true
+ */
+declare function isFunction(value: unknown): value is (...args: unknown[]) => unknown;
+/**
+ * 检查值是否为 null 或 undefined。
+ *
+ * @example
+ * ```typescript
+ * isNil(null);      // true
+ * isNil(undefined); // true
+ * isNil(0);         // false
+ * isNil('');        // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是 null 或 undefined 则返回 true
+ */
+declare function isNil(value: unknown): value is null | undefined;
+/**
+ * 检查值是否不为 null 或 undefined。
+ *
+ * @example
+ * ```typescript
+ * isNotNil(0);         // true
+ * isNotNil('');        // true
+ * isNotNil(null);      // false
+ * isNotNil(undefined); // false
+ * ```
+ *
+ * @template T - 值类型
+ * @param value - 要检查的值
+ * @returns 如果值不是 null 或 undefined 则返回 true
+ */
+declare function isNotNil<T>(value: T | null | undefined): value is T;
+/**
+ * 检查值是否为"空"。
+ * 空值：null, undefined, '', [], {}, Map(0), Set(0)
+ *
+ * @example
+ * ```typescript
+ * isEmpty('');        // true
+ * isEmpty([]);        // true
+ * isEmpty({});        // true
+ * isEmpty(null);      // true
+ * isEmpty(0);         // false
+ * isEmpty('hello');   // false
+ * isEmpty([1]);       // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值为空则返回 true
+ */
+declare function isEmpty(value: unknown): boolean;
+/**
+ * 检查值是否不为"空"。
+ *
+ * @example
+ * ```typescript
+ * isNotEmpty('hello');  // true
+ * isNotEmpty([1, 2]);   // true
+ * isNotEmpty('');       // false
+ * isNotEmpty([]);       // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值不为空则返回 true
+ */
+declare function isNotEmpty(value: unknown): boolean;
+/**
+ * 检查值是否为有效的 Date 对象。
+ *
+ * @example
+ * ```typescript
+ * isDate(new Date());           // true
+ * isDate(new Date('invalid'));  // false
+ * isDate('2023-01-01');         // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是有效日期则返回 true
+ */
+declare function isDate(value: unknown): value is Date;
+/**
+ * 检查值是否为 Promise。
+ *
+ * @example
+ * ```typescript
+ * isPromise(Promise.resolve()); // true
+ * isPromise(async () => {});    // false (函数，不是 promise)
+ * isPromise({ then: () => {} }); // true (thenable)
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是 Promise 或 thenable 则返回 true
+ */
+declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
+/**
+ * 检查值是否为 Symbol。
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是 Symbol 则返回 true
+ */
+declare function isSymbol(value: unknown): value is symbol;
+/**
+ * 检查值是否为 BigInt。
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是 BigInt 则返回 true
+ */
+declare function isBigInt(value: unknown): value is bigint;
+/**
+ * 检查值是否为有效的电子邮件地址。
+ *
+ * @example
+ * ```typescript
+ * isEmail('user@example.com');   // true
+ * isEmail('user@');              // false
+ * isEmail('not-an-email');       // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是有效邮箱则返回 true
+ */
+declare function isEmail(value: unknown): boolean;
+/**
+ * 检查值是否为有效的 UUID v4。
+ *
+ * @example
+ * ```typescript
+ * isUUID('550e8400-e29b-41d4-a716-446655440000'); // true
+ * isUUID('not-a-uuid'); // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是有效 UUID 则返回 true
+ */
+declare function isUUID(value: unknown): boolean;
+/**
+ * 检查值是否为有效的 URL。
+ *
+ * @example
+ * ```typescript
+ * isURL('https://example.com');     // true
+ * isURL('http://localhost:3000');   // true
+ * isURL('not-a-url');               // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是有效 URL 则返回 true
+ */
+declare function isURL(value: unknown): boolean;
+/**
+ * 检查值是否为整数。
+ *
+ * @example
+ * ```typescript
+ * isInteger(42);     // true
+ * isInteger(42.0);   // true
+ * isInteger(42.5);   // false
+ * isInteger('42');   // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是整数则返回 true
+ */
+declare function isInteger(value: unknown): value is number;
+/**
+ * 检查值是否为正数。
+ *
+ * @example
+ * ```typescript
+ * isPositive(1);    // true
+ * isPositive(0);    // false
+ * isPositive(-1);   // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是正数则返回 true
+ */
+declare function isPositive(value: unknown): value is number;
+/**
+ * 检查值是否为负数。
+ *
+ * @example
+ * ```typescript
+ * isNegative(-1);   // true
+ * isNegative(0);    // false
+ * isNegative(1);    // false
+ * ```
+ *
+ * @param value - 要检查的值
+ * @returns 如果值是负数则返回 true
+ */
+declare function isNegative(value: unknown): value is number;
+/**
+ * 检查值是否在范围内（包含边界）。
+ *
+ * @example
+ * ```typescript
+ * isInRange(5, 1, 10);   // true
+ * isInRange(0, 1, 10);   // false
+ * isInRange(1, 1, 10);   // true
+ * isInRange(10, 1, 10);  // true
+ * ```
+ *
+ * @param value - 要检查的值
+ * @param min - 最小值
+ * @param max - 最大值
+ * @returns 如果值在范围内则返回 true
+ */
+declare function isInRange(value: unknown, min: number, max: number): value is number;
+
+export { camelCase, capitalize, chunk, collapseWhitespace, constantCase, countOccurrences, createDeferred, debounce, deepClone, deepMerge, delay, difference, escapeHtml, filterObject, first, flatten, flattenDeep, fromEntries, get, groupBy, has, intersection, isArray, isBigInt, isBoolean, isDate, isEmail, isEmpty, isFunction, isInRange, isInteger, isNegative, isNil, isNotEmpty, isNotNil, isNumber, isObject, isPlainObject, isPositive, isPromise, isString, isSymbol, isURL, isUUID, kebabCase, last, mapValues, omit, padEnd, padStart, parallel, partition, pascalCase, pick, randomString, range, retry, reverse, sample, sequence, set, shuffle, snakeCase, sortBy, throttle, timeout, titleCase, truncate, unescapeHtml, unique, words, zip };