@jiakun-zhao/utils 1.4.1 → 1.4.3

package/llms.txt

@@ -0,0 +1,596 @@
+# @jiakun-zhao/utils
+
+## 目录
+
+- [类型定义](#类型定义)
+- [数组工具](#数组工具)
+- [字符串工具](#字符串工具)
+- [对象工具](#对象工具)
+- [数字工具](#数字工具)
+- [日期工具](#日期工具)
+- [函数工具](#函数工具)
+- [布尔工具](#布尔工具)
+- [正则工具](#正则工具)
+- [null/undefined 工具](#nullundefined-工具)
+- [扩展工具](#扩展工具)
+
+---
+
+## 类型定义
+
+### ElementOf<T>
+获取数组元素的类型
+
+```typescript
+type ElementType = ElementOf<string[]> // string
+type ElementType2 = ElementOf<number[]> // number
+```
+
+### Arrayable<T>
+可数组的类型，可以是单个值或数组
+
+```typescript
+type StringOrArray = Arrayable<string> // string | string[]
+function process(val: Arrayable<string>) {
+  const arr = toArray(val) // 总是得到 string[]
+}
+```
+
+### Nullable<T>
+可为空值的类型，包含 T、null 或 undefined
+
+```typescript
+type StringOrNull = Nullable<string> // string | null | undefined
+const val1: StringOrNull = 'hello'
+const val2: StringOrNull = null
+const val3: StringOrNull = undefined
+```
+
+### Awaitable<T>
+可等待的类型，可以是普通值或 Promise
+
+```typescript
+async function process<T>(value: Awaitable<T>): Promise<T> {
+  return await value
+}
+
+process('hello') // 返回 Promise<'hello'>
+process(Promise.resolve('hello')) // 返回 Promise<'hello'>
+```
+
+### Fn<T>
+函数类型定义
+
+```typescript
+type MyFunc = Fn<string> // () => string
+const fn: MyFunc = () => 'hello'
+```
+
+---
+
+## 数组工具
+
+### isArray
+判断值是否为数组
+
+```typescript
+isArray([]) // true
+isArray([1, 2, 3]) // true
+isArray('') // false
+isArray(null) // false
+```
+
+### toArray
+将值转换为数组，如果已经是数组则返回原数组
+
+```typescript
+toArray(1) // [1]
+toArray([1, 2, 3]) // [1, 2, 3]
+toArray('hello') // ['hello']
+toArray(null) // [null]
+```
+
+### uniq
+数组去重
+
+```typescript
+uniq([1, 2, 2, 3, 3, 3]) // [1, 2, 3]
+uniq(['a', 'b', 'a', 'c']) // ['a', 'b', 'c']
+uniq([]) // []
+```
+
+### singleOrNull
+获取数组的单个元素，如果数组只有一个元素则返回该元素，否则返回 null
+
+```typescript
+singleOrNull([1]) // 1
+singleOrNull(['only']) // 'only'
+singleOrNull([]) // null
+singleOrNull([1, 2, 3]) // null
+```
+
+### createArray
+创建指定长度的数组
+
+```typescript
+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) // []
+```
+
+### shuffle
+随机打乱数组（会修改原数组）
+
+```typescript
+const arr = [1, 2, 3, 4, 5]
+shuffle(arr) // [3, 1, 5, 2, 4] (随机顺序)
+// ⚠️ 原数组也会被修改
+```
+
+### range
+生成数字范围序列
+
+```typescript
+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) // []
+```
+
+---
+
+## 字符串工具
+
+### toString
+获取值的字符串表示形式
+
+```typescript
+toString({}) // '[object Object]'
+toString([]) // '[object Array]'
+toString(null) // '[object Null]'
+toString(undefined) // '[object Undefined]'
+toString(123) // '[object Number]'
+```
+
+### isString
+判断值是否为字符串
+
+```typescript
+isString('hello') // true
+isString('') // true
+isString(123) // false
+isString(null) // false
+```
+
+### slash
+将反斜杠转换为正斜杠
+
+```typescript
+slash('C:\\Users\\test') // 'C:/Users/test'
+slash('path\\to\\file') // 'path/to/file'
+slash('path/to/file') // 'path/to/file'
+```
+
+### ensurePrefix
+确保字符串以指定前缀开头
+
+```typescript
+ensurePrefix('example.com', 'https://') // 'https://example.com'
+ensurePrefix('https://example.com', 'https://') // 'https://example.com'
+ensurePrefix('path', '/') // '/path'
+```
+
+### ensureSuffix
+确保字符串以指定后缀结尾
+
+```typescript
+ensureSuffix('file', '.json') // 'file.json'
+ensureSuffix('file.json', '.json') // 'file.json'
+ensureSuffix('path', '/') // 'path/'
+```
+
+### capitalize
+将字符串首字母大写，其余字母小写
+
+```typescript
+capitalize('hello') // 'Hello'
+capitalize('HELLO') // 'Hello'
+capitalize('hELLO') // 'Hello'
+capitalize('hello world') // 'Hello world'
+// ⚠️ 空字符串会返回 'undefined'
+```
+
+---
+
+## 对象工具
+
+### isObject
+判断值是否为普通对象
+
+```typescript
+isObject({}) // true
+isObject({ a: 1 }) // true
+isObject([]) // false
+isObject(null) // false
+isObject(new Date()) // false
+```
+
+### isKeyOf
+判断键是否为对象的键
+
+```typescript
+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
+```
+
+### objectFilter
+根据条件过滤对象的属性
+
+```typescript
+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 }
+```
+
+### objectPick
+从对象中选取指定的属性
+
+```typescript
+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) // {}
+```
+
+### objectOmit
+从对象中排除指定的属性
+
+```typescript
+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 }
+```
+
+### clearUndefined
+清除对象中值为 undefined 的属性
+
+```typescript
+clearUndefined({ a: 1, b: undefined, c: 3 }) // { a: 1, c: 3 }
+clearUndefined({ a: undefined }) // {}
+clearUndefined({ a: null, b: undefined }) // { a: null } // null 不会被清除
+```
+
+---
+
+## 数字工具
+
+### isNumber
+判断值是否为数字类型
+
+```typescript
+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
+```
+
+### clamp
+将值限制在指定范围内
+
+```typescript
+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
+```
+
+### lerp
+线性插值，返回两个值之间的插值
+
+```typescript
+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
+```
+
+---
+
+## 日期工具
+
+### isDate
+判断值是否为 Date 对象
+
+```typescript
+isDate(new Date()) // true
+isDate(new Date('2024-01-01')) // true
+isDate('2024-01-01') // false
+isDate(null) // false
+```
+
+### timestamp
+获取当前时间戳（毫秒）
+
+```typescript
+timestamp() // 1705401600000
+```
+
+### isToDay
+判断日期是否为今天
+
+```typescript
+isToDay(new Date()) // true
+isToDay(new Date('2000-01-01')) // false
+```
+
+### isSameDay
+判断两个日期是否为同一天
+
+```typescript
+const date1 = new Date('2024-01-15T10:30:00')
+const date2 = new Date('2024-01-15T23:59:59')
+isSameDay(date1, date2) // true
+```
+
+```typescript
+const date1 = new Date('2024-01-15')
+const date2 = new Date('2024-01-16')
+isSameDay(date1, date2) // false
+```
+
+---
+
+## 函数工具
+
+### isFunction
+判断值是否为函数
+
+```typescript
+isFunction(() => {}) // true
+isFunction(function() {}) // true
+isFunction('function') // false
+isFunction(null) // false
+```
+
+### noop
+空函数，什么都不做
+
+```typescript
+const callback: Fn = noop // 作为默认回调
+callback() // 什么都不执行
+```
+
+### transform
+对值应用转换函数
+
+```typescript
+transform(5, (x) => x * 2) // 10
+transform('hello', (s) => s.toUpperCase()) // 'HELLO'
+transform([1, 2, 3], (arr) => arr.length) // 3
+```
+
+---
+
+## 布尔工具
+
+### isBoolean
+判断值是否为布尔类型
+
+```typescript
+isBoolean(true) // true
+isBoolean(false) // true
+isBoolean('true') // false
+isBoolean(1) // false
+isBoolean(null) // false
+```
+
+---
+
+## 正则工具
+
+### isRegExp
+判断值是否为正则表达式
+
+```typescript
+isRegExp(/test/) // true
+isRegExp(new RegExp('test')) // true
+isRegExp('test') // false
+isRegExp(null) // false
+```
+
+---
+
+## null/undefined 工具
+
+### isTruthy
+判断值是否为真值
+
+```typescript
+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
+```
+
+### isUndefined
+判断值是否为 undefined
+
+```typescript
+isUndefined(undefined) // true
+isUndefined(void 0) // true
+isUndefined(null) // false
+isUndefined('') // false
+```
+
+### notUndefined
+判断值是否不为 undefined
+
+```typescript
+notUndefined('hello') // true
+notUndefined(0) // true
+notUndefined(null) // true
+notUndefined(undefined) // false
+```
+
+### isNull
+判断值是否为 null
+
+```typescript
+isNull(null) // true
+isNull(undefined) // false
+isNull('') // false
+isNull(0) // false
+```
+
+### notNull
+判断值是否不为 null
+
+```typescript
+notNull('hello') // true
+notNull(0) // true
+notNull(undefined) // true
+notNull(null) // false
+```
+
+### notNullish
+判断值是否不为 null 且不为 undefined
+
+```typescript
+notNullish('hello') // true
+notNullish(0) // true
+notNullish(false) // true
+notNullish(null) // false
+notNullish(undefined) // false
+```
+
+### isDefined
+判断值是否已定义（不是 undefined）
+
+```typescript
+isDefined('hello') // true
+isDefined(0) // true
+isDefined(null) // true
+isDefined(false) // true
+isDefined(undefined) // false
+```
+
+---
+
+## 扩展工具
+
+### assert
+断言函数，当条件为 false 时抛出错误
+
+```typescript
+assert(true, '不会抛出错误') // 正常执行
+assert(false, '会抛出错误') // 抛出 Error: 会抛出错误
+```
+
+### isDeepEqual
+深度比较两个值是否相等
+支持 Array、Object、RegExp、Date 等类型的比较
+
+```typescript
+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
+```
+
+### naturalCompare
+自然排序比较函数，按自然语言顺序比较字符串或数字
+类似文件名排序，"file2" < "file10"
+
+```typescript
+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
+```
+
+### status
+HTTP 状态码及其对应的描述信息
+包含了所有标准的 HTTP 状态码
+
+```typescript
+status[200] // 'OK'
+status[404] // 'Not Found'
+status[500] // 'Internal Server Error'
+status[418] // "I'm a Teapot"
+```
+
+### getHttpStatusMessage
+根据 HTTP 状态码获取对应的描述信息
+
+```typescript
+getHttpStatusMessage(200) // 'OK'
+getHttpStatusMessage(404) // 'Not Found'
+getHttpStatusMessage(500) // 'Internal Server Error'
+getHttpStatusMessage(418) // "I'm a Teapot"
+```
+
+---
+
+## 已知问题
+
+### shuffle
+会修改原数组，而不是返回新数组。建议使用前先复制数组。
+
+### capitalize
+空字符串会返回 `'undefined'`，建议在使用前检查空字符串。
+
+### isSameDay
+使用本地日期方法，对时区敏感。不同时区的相同日期可能返回 false。
+
+### clearUndefined
+只会清除 `undefined`，不会清除 `null`。
+
+### isDeepEqual
+没有处理循环引用，循环引用会导致栈溢出。
+
+---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jiakun-zhao/utils",
   "type": "module",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "Utils.",
   "author": "Jiakun Zhao <hi@zhaojiakun.com>",
   "license": "MIT",
@@ -17,13 +17,15 @@
     ".": {
       "import": "./dist/index.mjs",
       "types": "./dist/index.d.mts"
-    }
+    },
+    "./llms.txt": "./llms.txt"
   },
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "files": [
-    "dist"
+    "dist",
+    "llms.txt"
   ],
   "devDependencies": {
     "@jiakun-zhao/eslint-config": "^4.1.8",