@jiakun-zhao/utils 1.4.2 → 1.4.3

package/dist/index.d.mts

@@ -1,10 +1,55 @@
 //#region src/addons/assert.d.ts
+/**
+ * 断言函数，当条件为 false 时抛出错误
+ * @param condition - 断言条件
+ * @param message - 错误信息
+ * @example
+ * ```ts
+ * assert(true, '不会抛出错误') // 正常执行
+ * assert(false, '会抛出错误') // 抛出 Error: 会抛出错误
+ * ```
+ */
 declare function assert(condition: boolean, message: string): asserts condition;
 //#endregion
 //#region src/addons/deep-equal.d.ts
+/**
+ * 深度比较两个值是否相等
+ * 支持 Array、Object、RegExp、Date 等类型的比较
+ * @param a - 第一个值
+ * @param b - 第二个值
+ * @returns 是否深度相等
+ * @example
+ * ```ts
+ * isDeepEqual(1, 1) // true
+ * isDeepEqual({}, {}) // true
+ * isDeepEqual('foo', 'foo') // true
+ * isDeepEqual([1, 2, 3], [1, 2, 3]) // true
+ * isDeepEqual(isDeepEqual, isDeepEqual) // true
+ * isDeepEqual(/foo/, /foo/) // true
+ * isDeepEqual(null, null) // true
+ * isDeepEqual(Number.NaN, Number.NaN) // true
+ * isDeepEqual([], []) // true
+ * isDeepEqual([{ a: 1 }, [{ b: { c: [1] } }]], [{ a: 1 }, [{ b: { c: [1] } }]]) // true
+ * isDeepEqual(1, '1') // false
+ * isDeepEqual(null, undefined) // false
+ * isDeepEqual({ a: 1, b: [2, 3] }, { a: 1, b: [2, 5] }) // false
+ * isDeepEqual(/foo/i, /bar/g) // false
+ * ```
+ */
 declare function isDeepEqual(a: any, b: any): boolean;
 //#endregion
 //#region src/addons/http-status-code.d.ts
+/**
+ * HTTP 状态码及其对应的描述信息
+ * 包含了所有标准的 HTTP 状态码
+ * @example
+ * ```ts
+ * status[200] // 'OK'
+ * status[404] // 'Not Found'
+ * status[500] // 'Internal Server Error'
+ * status[418] // "I'm a Teapot"
+ * ```
+ */
 declare const status: {
   readonly 100: "Continue";
   readonly 101: "Switching Protocols";
@@ -70,73 +115,648 @@ declare const status: {
   readonly 510: "Not Extended";
   readonly 511: "Network Authentication Required";
 };
+/**
+ * 根据 HTTP 状态码获取对应的描述信息
+ * @param code - HTTP 状态码
+ * @returns 状态码描述
+ * @example
+ * ```ts
+ * getHttpStatusMessage(200) // 'OK'
+ * getHttpStatusMessage(404) // 'Not Found'
+ * getHttpStatusMessage(500) // 'Internal Server Error'
+ * getHttpStatusMessage(418) // "I'm a Teapot"
+ * ```
+ */
 declare function getHttpStatusMessage(code: keyof typeof status): "Continue" | "Switching Protocols" | "Processing" | "Early Hints" | "OK" | "Created" | "Accepted" | "Non-Authoritative Information" | "No Content" | "Reset Content" | "Partial Content" | "Multi-Status" | "Already Reported" | "IM Used" | "Multiple Choices" | "Moved Permanently" | "Found" | "See Other" | "Not Modified" | "Use Proxy" | "Temporary Redirect" | "Permanent Redirect" | "Bad Request" | "Unauthorized" | "Payment Required" | "Forbidden" | "Not Found" | "Method Not Allowed" | "Not Acceptable" | "Proxy Authentication Required" | "Request Timeout" | "Conflict" | "Gone" | "Length Required" | "Precondition Failed" | "Payload Too Large" | "URI Too Long" | "Unsupported Media Type" | "Range Not Satisfiable" | "Expectation Failed" | "I'm a Teapot" | "Misdirected Request" | "Unprocessable Entity" | "Locked" | "Failed Dependency" | "Too Early" | "Upgrade Required" | "Precondition Required" | "Too Many Requests" | "Request Header Fields Too Large" | "Unavailable For Legal Reasons" | "Internal Server Error" | "Not Implemented" | "Bad Gateway" | "Service Unavailable" | "Gateway Timeout" | "HTTP Version Not Supported" | "Variant Also Negotiates" | "Insufficient Storage" | "Loop Detected" | "Bandwidth Limit Exceeded" | "Not Extended" | "Network Authentication Required";
 //#endregion
 //#region src/addons/natural-compare.d.ts
+/**
+ * 自然排序比较函数，按自然语言顺序比较字符串或数字
+ * 类似文件名排序，"file2" < "file10"
+ * @param a - 第一个值
+ * @param b - 第二个值
+ * @returns 比较结果：-1 表示 a < b，0 表示 a = b，1 表示 a > b
+ * @example
+ * ```ts
+ * naturalCompare(1, 2) // -1
+ * naturalCompare(2, 1) // 1
+ * naturalCompare(1, 1) // 0
+ *
+ * naturalCompare('a', 'b') // -1
+ * naturalCompare('b', 'a') // 1
+ * naturalCompare('a', 'a') // 0
+ *
+ * // 数字字符串按数值大小排序，而不是字典序
+ * naturalCompare('file1', 'file2') // -1
+ * naturalCompare('file2', 'file10') // -1 (2 < 10 自然顺序)
+ * naturalCompare('file10', 'file2') // 1
+ *
+ * // 用于数组排序
+ * ['file10.txt', 'file2.txt', 'file1.txt'].sort(naturalCompare) // ['file1.txt', 'file2.txt', 'file10.txt']
+ *
+ * // 版本号比较
+ * naturalCompare('v1.0.1', 'v1.0.10') // -1
+ * naturalCompare('v1.0.10', 'v1.0.2') // 1
+ * ```
+ */
 declare function naturalCompare<T extends string | number>(a: T, b: T): -1 | 0 | 1;
 //#endregion
 //#region src/addons/promise.d.ts
+/**
+ * 可等待的类型，可以是普通值或 Promise
+ * @example
+ * ```ts
+ * async function process<T>(value: Awaitable<T>): Promise<T> {
+ *   return await value
+ * }
+ *
+ * process('hello') // 返回 Promise<'hello'>
+ * process(Promise.resolve('hello')) // 返回 Promise<'hello'>
+ * ```
+ */
 type Awaitable<T> = T | PromiseLike<T>;
 //#endregion
 //#region src/base/array.d.ts
+/**
+ * 获取数组元素的类型
+ * @example
+ * ```ts
+ * type ElementType = ElementOf<string[]> // string
+ * type ElementType2 = ElementOf<number[]> // number
+ * ```
+ */
 type ElementOf<T> = T extends (infer E)[] ? E : never;
+/**
+ * 可数组的类型，可以是单个值或数组
+ * @example
+ * ```ts
+ * type StringOrArray = Arrayable<string> // string | string[]
+ * function process(val: Arrayable<string>) {
+ *   const arr = toArray(val) // 总是得到 string[]
+ * }
+ * ```
+ */
 type Arrayable<T> = T | Array<T>;
+/**
+ * 判断值是否为数组
+ * @param val - 要判断的值
+ * @returns 是否为数组
+ * @example
+ * ```ts
+ * isArray([]) // true
+ * isArray([1, 2, 3]) // true
+ * isArray('') // false
+ * isArray(null) // false
+ * ```
+ */
 declare const isArray: (val: unknown) => val is any[];
+/**
+ * 将值转换为数组，如果已经是数组则返回原数组
+ * @param val - 要转换的值
+ * @returns 数组
+ * @example
+ * ```ts
+ * toArray(1) // [1]
+ * toArray([1, 2, 3]) // [1, 2, 3]
+ * toArray('hello') // ['hello']
+ * toArray(null) // [null]
+ * ```
+ */
 declare const toArray: <T>(val: Arrayable<T>) => T[];
+/**
+ * 数组去重
+ * @param arr - 输入数组
+ * @returns 去重后的数组
+ * @example
+ * ```ts
+ * uniq([1, 2, 2, 3, 3, 3]) // [1, 2, 3]
+ * uniq(['a', 'b', 'a', 'c']) // ['a', 'b', 'c']
+ * uniq([]) // []
+ * ```
+ */
 declare const uniq: <T>(arr: readonly T[]) => T[];
+/**
+ * 获取数组的单个元素，如果数组只有一个元素则返回该元素，否则返回 null
+ * @param arr - 输入数组
+ * @returns 单个元素或 null
+ * @example
+ * ```ts
+ * singleOrNull([1]) // 1
+ * singleOrNull(['only']) // 'only'
+ * singleOrNull([]) // null
+ * singleOrNull([1, 2, 3]) // null
+ * ```
+ */
 declare const singleOrNull: <T>(arr: T[]) => T | null;
+/**
+ * 创建指定长度的数组
+ * @param len - 数组长度
+ * @param mapFn - 映射函数，可选
+ * @returns 创建的数组
+ * @example
+ * ```ts
+ * createArray(3) // [0, 1, 2]
+ * createArray(3, (i) => i * 2) // [0, 2, 4]
+ * createArray(5, (i) => `item-${i}`) // ['item-0', 'item-1', 'item-2', 'item-3', 'item-4']
+ * createArray(0) // []
+ * ```
+ */
 declare function createArray<T = number>(len: number, mapFn?: (idx: number) => T): T[];
+/**
+ * 随机打乱数组（会修改原数组）
+ * @param array - 要打乱的数组
+ * @returns 打乱后的数组
+ * @example
+ * ```ts
+ * const arr = [1, 2, 3, 4, 5]
+ * shuffle(arr) // [3, 1, 5, 2, 4] (随机顺序)
+ * // ⚠️ 原数组也会被修改
+ * ```
+ */
 declare function shuffle<T>(array: T[]): T[];
+/**
+ * 生成数字范围序列
+ * @param stop - 结束值
+ * @returns 数字数组
+ * @example
+ * ```ts
+ * range(5) // [0, 1, 2, 3, 4]
+ * range(1, 5) // [1, 2, 3, 4]
+ * range(0, 10, 2) // [0, 2, 4, 6, 8]
+ * range(1, 1) // []
+ * range(0, 0) // []
+ * ```
+ */
 declare function range(stop: number): number[];
+/**
+ * 生成数字范围序列
+ * @param start - 开始值
+ * @param stop - 结束值
+ * @param step - 步长，默认为 1
+ * @returns 数字数组
+ */
 declare function range(start: number, stop: number, step?: number): number[];
 //#endregion
 //#region src/base/boolean.d.ts
+/**
+ * 判断值是否为布尔类型
+ * @param val - 要判断的值
+ * @returns 是否为布尔值
+ * @example
+ * ```ts
+ * isBoolean(true) // true
+ * isBoolean(false) // true
+ * isBoolean('true') // false
+ * isBoolean(1) // false
+ * isBoolean(null) // false
+ * ```
+ */
 declare const isBoolean: (val: any) => val is boolean;
 //#endregion
 //#region src/base/date.d.ts
+/**
+ * 判断值是否为 Date 对象
+ * @param val - 要判断的值
+ * @returns 是否为 Date 对象
+ * @example
+ * ```ts
+ * isDate(new Date()) // true
+ * isDate(new Date('2024-01-01')) // true
+ * isDate('2024-01-01') // false
+ * isDate(null) // false
+ * ```
+ */
 declare const isDate: (val: any) => val is Date;
+/**
+ * 获取当前时间戳（毫秒）
+ * @returns 时间戳
+ * @example
+ * ```ts
+ * timestamp() // 1705401600000
+ * ```
+ */
 declare const timestamp: () => number;
+/**
+ * 判断日期是否为今天
+ * @param date - 要判断的日期
+ * @returns 是否为今天
+ * @example
+ * ```ts
+ * isToDay(new Date()) // true
+ * isToDay(new Date('2000-01-01')) // false
+ * ```
+ */
 declare const isToDay: (date: Date) => boolean;
+/**
+ * 判断两个日期是否为同一天
+ * @param dateA - 第一个日期
+ * @param dateB - 第二个日期
+ * @returns 是否为同一天
+ * @example
+ * ```ts
+ * const date1 = new Date('2024-01-15T10:30:00')
+ * const date2 = new Date('2024-01-15T23:59:59')
+ * isSameDay(date1, date2) // true
+ * ```
+ * @example
+ * ```ts
+ * const date1 = new Date('2024-01-15')
+ * const date2 = new Date('2024-01-16')
+ * isSameDay(date1, date2) // false
+ * ```
+ */
 declare function isSameDay(dateA: Date, dateB: Date): boolean;
 //#endregion
 //#region src/base/function.d.ts
+/**
+ * 函数类型定义
+ * @example
+ * ```ts
+ * type MyFunc = Fn<string> // () => string
+ * const fn: MyFunc = () => 'hello'
+ * ```
+ */
 type Fn<T = void> = () => T;
+/**
+ * 判断值是否为函数
+ * @param val - 要判断的值
+ * @returns 是否为函数
+ * @example
+ * ```ts
+ * isFunction(() => {}) // true
+ * isFunction(function() {}) // true
+ * isFunction('function') // false
+ * isFunction(null) // false
+ * ```
+ */
 declare const isFunction: <T extends Function>(val: any) => val is T;
+/**
+ * 空函数，什么都不做
+ * @returns void
+ * @example
+ * ```ts
+ * const callback: Fn = noop // 作为默认回调
+ * callback() // 什么都不执行
+ * ```
+ */
 declare const noop: () => void;
+/**
+ * 对值应用转换函数
+ * @param val - 输入值
+ * @param fn - 转换函数
+ * @returns 转换后的值
+ * @example
+ * ```ts
+ * transform(5, (x) => x * 2) // 10
+ * transform('hello', (s) => s.toUpperCase()) // 'HELLO'
+ * transform([1, 2, 3], (arr) => arr.length) // 3
+ * ```
+ */
 declare const transform: <T, R>(val: T, fn: (val: T) => R) => R;
 //#endregion
 //#region src/base/nullable.d.ts
+/**
+ * 可为空值的类型，包含 T、null 或 undefined
+ * @example
+ * ```ts
+ * type StringOrNull = Nullable<string> // string | null | undefined
+ * const val1: StringOrNull = 'hello'
+ * const val2: StringOrNull = null
+ * const val3: StringOrNull = undefined
+ * ```
+ */
 type Nullable<T> = T | null | undefined;
+/**
+ * 判断值是否为真值
+ * @param v - 要判断的值
+ * @returns 是否为真值
+ * @example
+ * ```ts
+ * isTruthy(true) // true
+ * isTruthy(1) // true
+ * isTruthy('hello') // true
+ * isTruthy({}) // true
+ * isTruthy([]) // true
+ * isTruthy(false) // false
+ * isTruthy(0) // false
+ * isTruthy('') // false
+ * isTruthy(null) // false
+ * isTruthy(undefined) // false
+ * ```
+ */
 declare const isTruthy: <T>(v: T) => v is NonNullable<T>;
+/**
+ * 判断值是否为 undefined
+ * @param val - 要判断的值
+ * @returns 是否为 undefined
+ * @example
+ * ```ts
+ * isUndefined(undefined) // true
+ * isUndefined(void 0) // true
+ * isUndefined(null) // false
+ * isUndefined('') // false
+ * ```
+ */
 declare const isUndefined: (val: any) => val is undefined;
+/**
+ * 判断值是否不为 undefined
+ * @param v - 要判断的值
+ * @returns 是否不为 undefined
+ * @example
+ * ```ts
+ * notUndefined('hello') // true
+ * notUndefined(0) // true
+ * notUndefined(null) // true
+ * notUndefined(undefined) // false
+ * ```
+ */
 declare const notUndefined: <T>(v: T) => v is Exclude<T, undefined>;
+/**
+ * 判断值是否为 null
+ * @param val - 要判断的值
+ * @returns 是否为 null
+ * @example
+ * ```ts
+ * isNull(null) // true
+ * isNull(undefined) // false
+ * isNull('') // false
+ * isNull(0) // false
+ * ```
+ */
 declare const isNull: (val: any) => val is null;
+/**
+ * 判断值是否不为 null
+ * @param v - 要判断的值
+ * @returns 是否不为 null
+ * @example
+ * ```ts
+ * notNull('hello') // true
+ * notNull(0) // true
+ * notNull(undefined) // true
+ * notNull(null) // false
+ * ```
+ */
 declare const notNull: <T>(v: T | null) => v is Exclude<T, null>;
+/**
+ * 判断值是否不为 null 且不为 undefined
+ * @param v - 要判断的值
+ * @returns 是否为非空值
+ * @example
+ * ```ts
+ * notNullish('hello') // true
+ * notNullish(0) // true
+ * notNullish(false) // true
+ * notNullish(null) // false
+ * notNullish(undefined) // false
+ * ```
+ */
 declare const notNullish: <T>(v: T | null | undefined) => v is NonNullable<T>;
+/**
+ * 判断值是否已定义（不是 undefined）
+ * @param val - 要判断的值
+ * @returns 是否已定义
+ * @example
+ * ```ts
+ * isDefined('hello') // true
+ * isDefined(0) // true
+ * isDefined(null) // true
+ * isDefined(false) // true
+ * isDefined(undefined) // false
+ * ```
+ */
 declare const isDefined: <T = any>(val?: T) => val is T;
 //#endregion
 //#region src/base/number.d.ts
+/**
+ * 判断值是否为数字类型
+ * @param val - 要判断的值
+ * @returns 是否为数字
+ * @example
+ * ```ts
+ * isNumber(0) // true
+ * isNumber(1) // true
+ * isNumber(1.5) // true
+ * isNumber(Number.NaN) // true
+ * isNumber(Number.POSITIVE_INFINITY) // true
+ * isNumber('123') // false
+ * isNumber(null) // false
+ * ```
+ */
 declare const isNumber: (val: any) => val is number;
+/**
+ * 将值限制在指定范围内
+ * @param n - 要限制的值
+ * @param min - 最小值
+ * @param max - 最大值
+ * @returns 限制后的值
+ * @example
+ * ```ts
+ * clamp(5, 0, 10) // 5 (在范围内)
+ * clamp(-5, 0, 10) // 0 (小于最小值，返回最小值)
+ * clamp(15, 0, 10) // 10 (大于最大值，返回最大值)
+ * clamp(1.5, 0, 1) // 1
+ * clamp(0.5, 0, 1) // 0.5
+ * ```
+ */
 declare const clamp: (n: number, min: number, max: number) => number;
+/**
+ * 线性插值，返回两个值之间的插值
+ * @param min - 起始值
+ * @param max - 结束值
+ * @param t - 插值参数（0-1 之间）
+ * @returns 插值结果
+ * @example
+ * ```ts
+ * lerp(0, 100, 0.5) // 50 (中点)
+ * lerp(0, 100, 0) // 0 (起始点)
+ * lerp(0, 100, 1) // 100 (结束点)
+ * lerp(0, 100, -0.5) // 0 (t 被限制到 0)
+ * lerp(0, 100, 1.5) // 100 (t 被限制到 1)
+ * lerp(-100, 0, 0.5) // -50
+ * lerp(0, 10, 0.25) // 2.5
+ * ```
+ */
 declare function lerp(min: number, max: number, t: number): number;
 //#endregion
 //#region src/base/object.d.ts
+/**
+ * 判断值是否为普通对象
+ * @param val - 要判断的值
+ * @returns 是否为对象
+ * @example
+ * ```ts
+ * isObject({}) // true
+ * isObject({ a: 1 }) // true
+ * isObject([]) // false
+ * isObject(null) // false
+ * isObject(new Date()) // false
+ * ```
+ */
 declare const isObject: (val: any) => val is object;
+/**
+ * 判断键是否为对象的键
+ * @param val - 对象
+ * @param key - 键
+ * @returns 是否为对象的键
+ * @example
+ * ```ts
+ * const obj = { a: 1, b: 2, c: 3 }
+ * isKeyOf(obj, 'a') // true
+ * isKeyOf(obj, 'b') // true
+ * isKeyOf(obj, 'd') // false
+ * // 注意：isKeyOf 使用 'key in val'，所以继承属性也会返回 true
+ * isKeyOf(obj, 'toString') // true
+ * ```
+ */
 declare const isKeyOf: <T extends object>(val: T, key: keyof any) => key is keyof T;
+/**
+ * 根据条件过滤对象的属性
+ * @param obj - 输入对象
+ * @param fn - 过滤函数
+ * @returns 过滤后的对象
+ * @example
+ * ```ts
+ * const obj = { a: 1, b: 2, c: 3, d: 4 }
+ * objectFilter(obj, (key, value) => value > 2) // { c: 3, d: 4 }
+ * objectFilter(obj, (key, value) => key === 'a') // { a: 1 }
+ * ```
+ */
 declare function objectFilter<O extends object>(obj: O, fn: (key: keyof O, value: O[keyof O]) => boolean): O;
+/**
+ * 从对象中选取指定的属性
+ * @param obj - 输入对象
+ * @param keys - 要选取的键
+ * @returns 包含指定属性的新对象
+ * @example
+ * ```ts
+ * const obj = { a: 1, b: 2, c: 3, d: 4 }
+ * objectPick(obj, 'a', 'c') // { a: 1, c: 3 }
+ * objectPick(obj, 'a', 'x') // { a: 1 }
+ * objectPick(obj) // {}
+ * ```
+ */
 declare function objectPick<O extends object, T extends keyof O>(obj: O, ...keys: T[]): Pick<O, T>;
+/**
+ * 从对象中排除指定的属性
+ * @param obj - 输入对象
+ * @param keys - 要排除的键
+ * @returns 不包含指定属性的新对象
+ * @example
+ * ```ts
+ * const obj = { a: 1, b: 2, c: 3, d: 4 }
+ * objectOmit(obj, 'a', 'c') // { b: 2, d: 4 }
+ * objectOmit(obj, 'a', 'x') // { b: 2, c: 3, d: 4 }
+ * objectOmit(obj) // { a: 1, b: 2, c: 3, d: 4 }
+ * ```
+ */
 declare function objectOmit<O extends object, T extends keyof O>(obj: O, ...keys: T[]): Omit<O, T>;
+/**
+ * 清除对象中值为 undefined 的属性
+ * @param obj - 输入对象
+ * @returns 清除 undefined 后的对象
+ * @example
+ * ```ts
+ * clearUndefined({ a: 1, b: undefined, c: 3 }) // { a: 1, c: 3 }
+ * clearUndefined({ a: undefined }) // {}
+ * clearUndefined({ a: null, b: undefined }) // { a: null } // null 不会被清除
+ * ```
+ */
 declare function clearUndefined<O extends object>(obj: O): O;
 //#endregion
 //#region src/base/regexp.d.ts
+/**
+ * 判断值是否为正则表达式
+ * @param val - 要判断的值
+ * @returns 是否为正则表达式
+ * @example
+ * ```ts
+ * isRegExp(/test/) // true
+ * isRegExp(new RegExp('test')) // true
+ * isRegExp('test') // false
+ * isRegExp(null) // false
+ * ```
+ */
 declare const isRegExp: (val: any) => val is RegExp;
 //#endregion
 //#region src/base/string.d.ts
+/**
+ * 获取值的字符串表示形式
+ * @param val - 输入值
+ * @returns 字符串表示
+ * @example
+ * ```ts
+ * toString({}) // '[object Object]'
+ * toString([]) // '[object Array]'
+ * toString(null) // '[object Null]'
+ * toString(undefined) // '[object Undefined]'
+ * toString(123) // '[object Number]'
+ * ```
+ */
 declare const toString: (val: any) => string;
+/**
+ * 判断值是否为字符串
+ * @param val - 要判断的值
+ * @returns 是否为字符串
+ * @example
+ * ```ts
+ * isString('hello') // true
+ * isString('') // true
+ * isString(123) // false
+ * isString(null) // false
+ * ```
+ */
 declare const isString: (val: unknown) => val is string;
+/**
+ * 将反斜杠转换为正斜杠
+ * @param str - 输入字符串
+ * @returns 转换后的字符串
+ * @example
+ * ```ts
+ * slash('C:\\Users\\test') // 'C:/Users/test'
+ * slash('path\\to\\file') // 'path/to/file'
+ * slash('path/to/file') // 'path/to/file'
+ * ```
+ */
 declare const slash: (str: string) => string;
+/**
+ * 确保字符串以指定前缀开头
+ * @param str - 输入字符串
+ * @param prefix - 前缀
+ * @returns 处理后的字符串
+ * @example
+ * ```ts
+ * ensurePrefix('example.com', 'https://') // 'https://example.com'
+ * ensurePrefix('https://example.com', 'https://') // 'https://example.com'
+ * ensurePrefix('path', '/') // '/path'
+ * ```
+ */
 declare const ensurePrefix: (str: string, prefix: string) => string;
+/**
+ * 确保字符串以指定后缀结尾
+ * @param str - 输入字符串
+ * @param suffix - 后缀
+ * @returns 处理后的字符串
+ * @example
+ * ```ts
+ * ensureSuffix('file', '.json') // 'file.json'
+ * ensureSuffix('file.json', '.json') // 'file.json'
+ * ensureSuffix('path', '/') // 'path/'
+ * ```
+ */
 declare const ensureSuffix: (str: string, suffix: string) => string;
+/**
+ * 将字符串首字母大写，其余字母小写
+ * @param str - 输入字符串
+ * @returns 处理后的字符串
+ * @example
+ * ```ts
+ * capitalize('hello') // 'Hello'
+ * capitalize('HELLO') // 'Hello'
+ * capitalize('hELLO') // 'Hello'
+ * capitalize('hello world') // 'Hello world'
+ * // ⚠️ 空字符串会返回 'undefined'
+ * ```
+ */
 declare const capitalize: (str: string) => string;
 //#endregion
 export { Arrayable, Awaitable, ElementOf, Fn, Nullable, assert, capitalize, clamp, clearUndefined, createArray, ensurePrefix, ensureSuffix, getHttpStatusMessage, isArray, isBoolean, isDate, isDeepEqual, isDefined, isFunction, isKeyOf, isNull, isNumber, isObject, isRegExp, isSameDay, isString, isToDay, isTruthy, isUndefined, lerp, naturalCompare, noop, notNull, notNullish, notUndefined, objectFilter, objectOmit, objectPick, range, shuffle, singleOrNull, slash, status, timestamp, toArray, toString, transform, uniq };