@jiakun-zhao/utils 1.4.2 → 1.4.4

package/dist/index.mjs

@@ -1,10 +1,44 @@
 //#region src/addons/assert.ts
+/**
+* 断言函数，当条件为 false 时抛出错误
+* @param condition - 断言条件
+* @param message - 错误信息
+* @example
+* ```ts
+* assert(true, '不会抛出错误') // 正常执行
+* assert(false, '会抛出错误') // 抛出 Error: 会抛出错误
+* ```
+*/
 function assert(condition, message) {
 	if (!condition) throw new Error(message);
 }
 
 //#endregion
 //#region src/addons/deep-equal.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
+* ```
+*/
 function isDeepEqual(a, b) {
 	if (a === b) return true;
 	const constructor = a?.constructor;
@@ -22,6 +56,17 @@ function isDeepEqual(a, b) {
 
 //#endregion
 //#region src/addons/http-status-code.ts
+/**
+* HTTP 状态码及其对应的描述信息
+* 包含了所有标准的 HTTP 状态码
+* @example
+* ```ts
+* status[200] // 'OK'
+* status[404] // 'Not Found'
+* status[500] // 'Internal Server Error'
+* status[418] // "I'm a Teapot"
+* ```
+*/
 const status = {
 	100: "Continue",
 	101: "Switching Protocols",
@@ -87,12 +132,53 @@ const status = {
 	510: "Not Extended",
 	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"
+* ```
+*/
 function getHttpStatusMessage(code) {
 	return status[code];
 }
 
 //#endregion
 //#region src/addons/natural-compare.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
+* ```
+*/
 function naturalCompare(a, b) {
 	var i, codeA, codeB = 1, posA = 0, posB = 0, alphabet = String.alphabet;
 	function getCode(str, pos, code) {
@@ -118,13 +204,84 @@ function naturalCompare(a, b) {
 
 //#endregion
 //#region src/base/array.ts
+/**
+* 判断值是否为数组
+* @param val - 要判断的值
+* @returns 是否为数组
+* @example
+* ```ts
+* isArray([]) // true
+* isArray([1, 2, 3]) // true
+* isArray('') // false
+* isArray(null) // false
+* ```
+*/
 const isArray = (val) => Array.isArray(val);
+/**
+* 将值转换为数组，如果已经是数组则返回原数组
+* @param val - 要转换的值
+* @returns 数组
+* @example
+* ```ts
+* toArray(1) // [1]
+* toArray([1, 2, 3]) // [1, 2, 3]
+* toArray('hello') // ['hello']
+* toArray(null) // [null]
+* ```
+*/
 const toArray = (val) => isArray(val) ? val : [val];
+/**
+* 数组去重
+* @param arr - 输入数组
+* @returns 去重后的数组
+* @example
+* ```ts
+* uniq([1, 2, 2, 3, 3, 3]) // [1, 2, 3]
+* uniq(['a', 'b', 'a', 'c']) // ['a', 'b', 'c']
+* uniq([]) // []
+* ```
+*/
 const uniq = (arr) => [...new Set(arr)];
+/**
+* 获取数组的单个元素，如果数组只有一个元素则返回该元素，否则返回 null
+* @param arr - 输入数组
+* @returns 单个元素或 null
+* @example
+* ```ts
+* singleOrNull([1]) // 1
+* singleOrNull(['only']) // 'only'
+* singleOrNull([]) // null
+* singleOrNull([1, 2, 3]) // null
+* ```
+*/
 const singleOrNull = (arr) => arr.length === 1 ? arr[0] : 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) // []
+* ```
+*/
 function createArray(len, mapFn) {
 	return Array.from({ length: len }, (_, index) => mapFn?.(index) ?? index);
 }
+/**
+* 随机打乱数组（会修改原数组）
+* @param array - 要打乱的数组
+* @returns 打乱后的数组
+* @example
+* ```ts
+* const arr = [1, 2, 3, 4, 5]
+* shuffle(arr) // [3, 1, 5, 2, 4] (随机顺序)
+* // ⚠️ 原数组也会被修改
+* ```
+*/
 function shuffle(array) {
 	for (let i = array.length - 1; i > 0; i--) {
 		const j = Math.floor(Math.random() * (i + 1));
@@ -132,6 +289,11 @@ function shuffle(array) {
 	}
 	return array;
 }
+/**
+* 生成数字范围序列
+* @param args - 参数
+* @returns 数字数组
+*/
 function range(...args) {
 	if (args.length === 1) args.unshift(0);
 	const [start, stop, step = 1] = args;
@@ -142,46 +304,352 @@ function range(...args) {
 
 //#endregion
 //#region src/base/boolean.ts
+/**
+* 判断值是否为布尔类型
+* @param val - 要判断的值
+* @returns 是否为布尔值
+* @example
+* ```ts
+* isBoolean(true) // true
+* isBoolean(false) // true
+* isBoolean('true') // false
+* isBoolean(1) // false
+* isBoolean(null) // false
+* ```
+*/
 const isBoolean = (val) => typeof val === "boolean";
 
 //#endregion
 //#region src/base/string.ts
+/**
+* 获取值的字符串表示形式
+* @param val - 输入值
+* @returns 字符串表示
+* @example
+* ```ts
+* toString({}) // '[object Object]'
+* toString([]) // '[object Array]'
+* toString(null) // '[object Null]'
+* toString(undefined) // '[object Undefined]'
+* toString(123) // '[object Number]'
+* ```
+*/
 const toString = (val) => Object.prototype.toString.call(val);
+/**
+* 判断值是否为字符串
+* @param val - 要判断的值
+* @returns 是否为字符串
+* @example
+* ```ts
+* isString('hello') // true
+* isString('') // true
+* isString(123) // false
+* isString(null) // false
+* ```
+*/
 const isString = (val) => typeof val === "string";
-const slash = (str) => str.replace(/\\/g, "/");
+/**
+* 将反斜杠转换为正斜杠
+* @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'
+* ```
+*/
+const slash = (str) => str.replace(/\\\\/g, "/");
+/**
+* 确保字符串以指定前缀开头
+* @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'
+* ```
+*/
 const ensurePrefix = (str, prefix) => str.startsWith(prefix) ? str : prefix + str;
+/**
+* 确保字符串以指定后缀结尾
+* @param str - 输入字符串
+* @param suffix - 后缀
+* @returns 处理后的字符串
+* @example
+* ```ts
+* ensureSuffix('file', '.json') // 'file.json'
+* ensureSuffix('file.json', '.json') // 'file.json'
+* ensureSuffix('path', '/') // 'path/'
+* ```
+*/
 const ensureSuffix = (str, suffix) => str.endsWith(suffix) ? str : str + suffix;
+/**
+* 将字符串首字母大写，其余字母小写
+* @param str - 输入字符串
+* @returns 处理后的字符串
+* @example
+* ```ts
+* capitalize('hello') // 'Hello'
+* capitalize('HELLO') // 'Hello'
+* capitalize('hELLO') // 'Hello'
+* capitalize('hello world') // 'Hello world'
+* // ⚠️ 空字符串会返回 'undefined'
+* ```
+*/
 const capitalize = (str) => str[0].toUpperCase() + str.slice(1).toLowerCase();
 
 //#endregion
 //#region src/base/date.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
+* ```
+*/
 const isDate = (val) => toString(val) === "[object Date]";
+/**
+* 获取当前时间戳（毫秒）
+* @returns 时间戳
+* @example
+* ```ts
+* timestamp() // 1705401600000
+* ```
+*/
 const timestamp = () => +Date.now();
+/**
+* 判断日期是否为今天
+* @param date - 要判断的日期
+* @returns 是否为今天
+* @example
+* ```ts
+* isToDay(new Date()) // true
+* isToDay(new Date('2000-01-01')) // false
+* ```
+*/
 const isToDay = (date) => isSameDay(date, /* @__PURE__ */ new Date());
+/**
+* 判断两个日期是否为同一天
+* @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
+* ```
+*/
 function isSameDay(dateA, dateB) {
 	return dateA.getDate() === dateB.getDate() && dateA.getMonth() === dateB.getMonth() && dateA.getFullYear() === dateB.getFullYear();
 }
 
 //#endregion
 //#region src/base/function.ts
+/**
+* 判断值是否为函数
+* @param val - 要判断的值
+* @returns 是否为函数
+* @example
+* ```ts
+* isFunction(() => {}) // true
+* isFunction(function() {}) // true
+* isFunction('function') // false
+* isFunction(null) // false
+* ```
+*/
 const isFunction = (val) => typeof val === "function";
+/**
+* 空函数，什么都不做
+* @returns void
+* @example
+* ```ts
+* const callback: Fn = noop // 作为默认回调
+* callback() // 什么都不执行
+* ```
+*/
 const noop = () => {};
+/**
+* 对值应用转换函数
+* @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
+* ```
+*/
 const transform = (val, fn) => fn(val);
 
 //#endregion
 //#region src/base/nullable.ts
+/**
+* 判断值是否为真值
+* @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
+* ```
+*/
 const isTruthy = (v) => Boolean(v);
+/**
+* 判断值是否为 undefined
+* @param val - 要判断的值
+* @returns 是否为 undefined
+* @example
+* ```ts
+* isUndefined(undefined) // true
+* isUndefined(void 0) // true
+* isUndefined(null) // false
+* isUndefined('') // false
+* ```
+*/
 const isUndefined = (val) => toString(val) === "[object Undefined]";
+/**
+* 判断值是否不为 undefined
+* @param v - 要判断的值
+* @returns 是否不为 undefined
+* @example
+* ```ts
+* notUndefined('hello') // true
+* notUndefined(0) // true
+* notUndefined(null) // true
+* notUndefined(undefined) // false
+* ```
+*/
 const notUndefined = (v) => v !== void 0;
+/**
+* 判断值是否为 null
+* @param val - 要判断的值
+* @returns 是否为 null
+* @example
+* ```ts
+* isNull(null) // true
+* isNull(undefined) // false
+* isNull('') // false
+* isNull(0) // false
+* ```
+*/
 const isNull = (val) => toString(val) === "[object Null]";
+/**
+* 判断值是否不为 null
+* @param v - 要判断的值
+* @returns 是否不为 null
+* @example
+* ```ts
+* notNull('hello') // true
+* notNull(0) // true
+* notNull(undefined) // true
+* notNull(null) // false
+* ```
+*/
 const notNull = (v) => v !== null;
+/**
+* 判断值是否不为 null 且不为 undefined
+* @param v - 要判断的值
+* @returns 是否为非空值
+* @example
+* ```ts
+* notNullish('hello') // true
+* notNullish(0) // true
+* notNullish(false) // true
+* notNullish(null) // false
+* notNullish(undefined) // false
+* ```
+*/
 const notNullish = (v) => v != null;
+/**
+* 判断值是否已定义（不是 undefined）
+* @param val - 要判断的值
+* @returns 是否已定义
+* @example
+* ```ts
+* isDefined('hello') // true
+* isDefined(0) // true
+* isDefined(null) // true
+* isDefined(false) // true
+* isDefined(undefined) // false
+* ```
+*/
 const isDefined = (val) => typeof val !== "undefined";
 
 //#endregion
 //#region src/base/number.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
+* ```
+*/
 const isNumber = (val) => typeof val === "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
+* ```
+*/
 const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
+/**
+* 线性插值，返回两个值之间的插值
+* @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
+* ```
+*/
 function lerp(min, max, t) {
 	const interpolation = clamp(t, 0, 1);
 	return min + (max - min) * interpolation;
@@ -189,23 +657,112 @@ function lerp(min, max, t) {
 
 //#endregion
 //#region src/base/object.ts
+/**
+* 判断值是否为普通对象
+* @param val - 要判断的值
+* @returns 是否为对象
+* @example
+* ```ts
+* isObject({}) // true
+* isObject({ a: 1 }) // true
+* isObject([]) // false
+* isObject(null) // false
+* isObject(new Date()) // false
+* ```
+*/
 const isObject = (val) => toString(val) === "[object 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
+* ```
+*/
 const isKeyOf = (val, key) => key in val;
+/**
+* 根据条件过滤对象的属性
+* @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 }
+* ```
+*/
 function objectFilter(obj, fn) {
 	return Object.fromEntries(Object.entries(obj).filter(([key, value]) => fn(key, value)));
 }
+/**
+* 从对象中选取指定的属性
+* @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) // {}
+* ```
+*/
 function objectPick(obj, ...keys) {
 	return objectFilter(obj, (key) => keys.includes(key));
 }
+/**
+* 从对象中排除指定的属性
+* @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 }
+* ```
+*/
 function objectOmit(obj, ...keys) {
 	return objectFilter(obj, (key) => !keys.includes(key));
 }
+/**
+* 清除对象中值为 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 不会被清除
+* ```
+*/
 function clearUndefined(obj) {
 	return objectFilter(obj, (_, value) => notUndefined(value));
 }
 
 //#endregion
 //#region src/base/regexp.ts
+/**
+* 判断值是否为正则表达式
+* @param val - 要判断的值
+* @returns 是否为正则表达式
+* @example
+* ```ts
+* isRegExp(/test/) // true
+* isRegExp(new RegExp('test')) // true
+* isRegExp('test') // false
+* isRegExp(null) // false
+* ```
+*/
 const isRegExp = (val) => toString(val) === "[object RegExp]";
 
 //#endregion