pen-it 1.0.1 → 1.0.3

package/README.md

@@ -22,106 +22,425 @@ import { isArray, formatFull, deepClone, unique } from 'pen-it'
 
 ### 类型判断 — `is`
 
-- **`isArray(value)`** — 判断是否为数组。 `isArray([1,2,3]) // true`
-- **`isObject(value)`** — 判断是否为对象（不含数组）。 `isObject({a:1}) // true`
-- **`is(val, type)`** — 通用类型判断（内部工具）。 `is([], "Array") // true`
-- **`isFunction(val)`** — 判断是否为函数。 `isFunction(()=>{}) // true`
-- **`isAsyncFunction(val)`** — 判断是否为异步函数。 `isAsyncFunction(async ()=>{}) // true`
-- **`isPromise(value)`** — 判断是否为 Promise。 `isPromise(Promise.resolve()) // true`
-- **`isDate(val)`** — 判断是否为 Date 对象。 `isDate(new Date()) // true`
-- **`isNumber(val)`** — 判断是否为数字（含 NaN/Infinity）。 `isNumber(42) // true`
-- **`isInt(val)`** — 判断是否为整数。 `isInt(42) // true`
-- **`isFloat(val)`** — 判断是否为浮点数。 `isFloat(3.14) // true`
-- **`isString(val)`** — 判断是否为字符串。 `isString("hello") // true`
-- **`isBoolean(val)`** — 判断是否为布尔值。 `isBoolean(true) // true`
-- **`isSymbol(value)`** — 判断是否为 Symbol。 `isSymbol(Symbol("foo")) // true`
-- **`isPrimitive(value)`** — 判断是否为原始类型。 `isPrimitive(42) // true`
-- **`isNull(val)`** — 判断是否为 null。 `isNull(null) // true`
-- **`isDef(val)`** — 判断是否不是 undefined。 `isDef("hello") // true`
-- **`isUnDef(val)`** — 判断是否为 undefined。 `isUnDef(undefined) // true`
-- **`isNullOrUnDef(val)`** — 判断是否为 null 或 undefined。 `isNullOrUnDef(null) // true`
-- **`isEmpty(value)`** — 判断是否为空（完备版：支持 Date/Map/Set 等）。 `isEmpty("") // true`
-- **`isEmptySv(value)`** — 判断是否为空（简化版）。 `isEmptySv([]) // true`
-- **`isEqual(x, y)`** — 深度相等比较（支持 Date/RegExp）。 `isEqual({a:1}, {a:1}) // true`
-- **`isHexColor(str)`** — 判断是否为十六进制颜色。 `isHexColor("#fff") // true`
-- **`isValidEmail(email)`** — 判断是否为有效邮箱。 `isValidEmail("a@b.com") // true`
-- **`isPC()`** — 判断是否为浏览器环境。 `isPC() // true`
-- **`isWindow(val)`** — 判断是否为 window 对象。 `isWindow(window) // true`
-- **`isElement(val)`** — 判断是否为 DOM 元素。 `isElement(document.body) // true`
-- **`isIOS()`** — 判断设备是否为 iOS。 `isIOS() // true`
+- **`isArray(value)`** — 判断是否为数组。
+
+  ```ts
+  isArray([1, 2, 3])  // true
+  ```
+
+- **`isObject(value)`** — 判断是否为对象（不含数组）。
+
+  ```ts
+  isObject({ a: 1 })  // true
+  ```
+
+- **`is(val, type)`** — 通用类型判断（内部工具）。
+
+  ```ts
+  is([], 'Array')  // true
+  ```
+
+- **`isFunction(val)`** — 判断是否为函数。
+
+  ```ts
+  isFunction(() => {})  // true
+  ```
+
+- **`isAsyncFunction(val)`** — 判断是否为异步函数。
+
+  ```ts
+  isAsyncFunction(async () => {})  // true
+  ```
+
+- **`isPromise(value)`** — 判断是否为 Promise。
+
+  ```ts
+  isPromise(Promise.resolve())  // true
+  ```
+
+- **`isDate(val)`** — 判断是否为 Date 对象。
+
+  ```ts
+  isDate(new Date())  // true
+  ```
+
+- **`isNumber(val)`** — 判断是否为数字（含 NaN/Infinity）。
+
+  ```ts
+  isNumber(42)  // true
+  ```
+
+- **`isInt(val)`** — 判断是否为整数。
+
+  ```ts
+  isInt(42)  // true
+  ```
+
+- **`isFloat(val)`** — 判断是否为浮点数。
+
+  ```ts
+  isFloat(3.14)  // true
+  ```
+
+- **`isString(val)`** — 判断是否为字符串。
+
+  ```ts
+  isString('hello')  // true
+  ```
+
+- **`isBoolean(val)`** — 判断是否为布尔值。
+
+  ```ts
+  isBoolean(true)  // true
+  ```
+
+- **`isSymbol(value)`** — 判断是否为 Symbol。
+
+  ```ts
+  isSymbol(Symbol('foo'))  // true
+  ```
+
+- **`isPrimitive(value)`** — 判断是否为原始类型。
+
+  ```ts
+  isPrimitive(42)  // true
+  ```
+
+- **`isNull(val)`** — 判断是否为 null。
+
+  ```ts
+  isNull(null)  // true
+  ```
+
+- **`isDef(val)`** — 判断是否不是 undefined。
+
+  ```ts
+  isDef('hello')  // true
+  ```
+
+- **`isUnDef(val)`** — 判断是否为 undefined。
+
+  ```ts
+  isUnDef(undefined)  // true
+  ```
+
+- **`isNullOrUnDef(val)`** — 判断是否为 null 或 undefined。
+
+  ```ts
+  isNullOrUnDef(null)  // true
+  ```
+
+- **`isEmpty(value)`** — 判断是否为空（完备版：支持 Date/Map/Set 等）。
+
+  ```ts
+  isEmpty('')   // true
+  isEmpty([])   // true
+  isEmpty({})   // true
+  ```
+
+- **`isEmptySv(value)`** — 判断是否为空（简化版）。
+
+  ```ts
+  isEmptySv([])  // true
+  ```
+
+- **`isEqual(x, y)`** — 深度相等比较（支持 Date/RegExp）。
+
+  ```ts
+  isEqual({ a: 1 }, { a: 1 })  // true
+  ```
+
+- **`isHexColor(str)`** — 判断是否为十六进制颜色。
+
+  ```ts
+  isHexColor('#fff')  // true
+  ```
+
+- **`isValidEmail(email)`** — 判断是否为有效邮箱。
+
+  ```ts
+  isValidEmail('a@b.com')  // true
+  ```
+
+- **`isPC()`** — 判断是否为浏览器环境。
+
+  ```ts
+  isPC()  // true
+  ```
+
+- **`isWindow(val)`** — 判断是否为 window 对象。
+
+  ```ts
+  isWindow(window)  // true
+  ```
+
+- **`isElement(val)`** — 判断是否为 DOM 元素。
+
+  ```ts
+  isElement(document.body)  // true
+  ```
+
+- **`isIOS()`** — 判断设备是否为 iOS。
+
+  ```ts
+  isIOS()  // true
+  ```
 
 ---
 
 ### 日期时间格式化 — `format`
 
-- **`formatFull(date)`** — 完整日期时间（斜杠分隔）。 `formatFull(new Date()) // "2026/06/03 14:30:45"`
-- **`formatFullReplace(date)`** — 完整日期时间（短横线分隔）。 `formatFullReplace(new Date()) // "2026-06-03 14:30:45"`
-- **`formatYMD(date)`** — 中文年月日。 `formatYMD(new Date()) // "2026年6月3日"`
-- **`formatWeek(date)`** — 星期几。 `formatWeek(new Date()) // "星期三"`
+- **`formatFull(date)`** — 完整日期时间（斜杠分隔）。
+
+  ```ts
+  formatFull(new Date())  // "2026/06/03 14:30:45"
+  ```
+
+- **`formatFullReplace(date)`** — 完整日期时间（短横线分隔）。
+
+  ```ts
+  formatFullReplace(new Date())  // "2026-06-03 14:30:45"
+  ```
+
+- **`formatYMD(date)`** — 中文年月日。
+
+  ```ts
+  formatYMD(new Date())  // "2026年6月3日"
+  ```
+
+- **`formatWeek(date)`** — 星期几。
+
+  ```ts
+  formatWeek(new Date())  // "星期三"
+  ```
 
 ---
 
 ### 数字与货币格式化 — `format`
 
-- **`formatRmb(value, options)`** — 货币格式化（人民币）。 `formatRmb(1234.56, { type: "zh-CN", currency: "CNY" }) // "¥1,234.56"`
-- **`formatNum(value)`** — 千位分隔符。 `formatNum(1234567) // "1,234,567"`
-- **`percentCN(value, digit)`** — 百分比格式化。 `percentCN(0.1234, 2) // "12.34%"`
-- **`compactEN(value)`** — 大数简化（英文缩写）。 `compactEN(12345) // "12K"`
-- **`compactCN(value)`** — 大数简化（中文缩写）。 `compactCN(12345) // "1.2万"`
-- **`signed(value, digit)`** — 带正负号显示。 `signed(42, 1) // "+42.0"`
+- **`formatRmb(value, options)`** — 货币格式化（人民币）。
+
+  ```ts
+  formatRmb(1234.56, { type: 'zh-CN', currency: 'CNY' })  // "¥1,234.56"
+  ```
+
+- **`formatNum(value)`** — 千位分隔符。
+
+  ```ts
+  formatNum(1234567)  // "1,234,567"
+  ```
+
+- **`percentCN(value, digit)`** — 百分比格式化。
+
+  ```ts
+  percentCN(0.1234, 2)  // "12.34%"
+  ```
+
+- **`compactEN(value)`** — 大数简化（英文缩写）。
+
+  ```ts
+  compactEN(12345)  // "12K"
+  ```
+
+- **`compactCN(value)`** — 大数简化（中文缩写）。
+
+  ```ts
+  compactCN(12345)  // "1.2万"
+  ```
+
+- **`signed(value, digit)`** — 带正负号显示。
+
+  ```ts
+  signed(42, 1)  // "+42.0"
+  ```
 
 ---
 
 ### 字符串处理 — `format`
 
-- **`maskPhone(phone)`** — 手机号脱敏（隐藏中间4位）。 `maskPhone("13812345678") // "138****5678"`
-- **`spacePhone(phone)`** — 手机号空格分隔。 `spacePhone("13812345678") // "138 1234 5678"`
-- **`capitalize(str)`** — 每个单词首字母大写。 `capitalize("hello world") // "Hello World"`
-- **`kebabToCamel(str)`** — 短横线转小驼峰。 `kebabToCamel("hello-world") // "helloWorld"`
-- **`camelToKebab(str)`** — 驼峰转短横线。 `camelToKebab("helloWorld") // "hello-world"`
-- **`toCamel(str)`** — 下划线转驼峰。 `toCamel("hello_world") // "helloWorld"`
-- **`firstUpper(str)`** — 首字母大写。 `firstUpper("hello") // "Hello"`
-- **`firstLower(str)`** — 首字母小写。 `firstLower("Hello") // "hello"`
-- **`reverse(str)`** — 反转字符串。 `reverse("hello") // "olleh"`
-- **`trimAll(str)`** — 去除所有空格。 `trimAll(" h e l lo ") // "hello"`
-- **`truncate(str, max, suffix?)`** — 超长文本截断。 `truncate("Hello World", 8) // "Hello..."`
-- **`truncateByWords(str, max, suffix?)`** — 按字数截断（中文友好）。 `truncateByWords("你好世界欢迎你", 4) // "你好世界..."`
+- **`maskPhone(phone)`** — 手机号脱敏（隐藏中间4位）。
+
+  ```ts
+  maskPhone('13812345678')  // "138****5678"
+  ```
+
+- **`spacePhone(phone)`** — 手机号空格分隔。
+
+  ```ts
+  spacePhone('13812345678')  // "138 1234 5678"
+  ```
+
+- **`capitalize(str)`** — 每个单词首字母大写。
+
+  ```ts
+  capitalize('hello world')  // "Hello World"
+  ```
+
+- **`kebabToCamel(str)`** — 短横线转小驼峰。
+
+  ```ts
+  kebabToCamel('hello-world')  // "helloWorld"
+  ```
+
+- **`camelToKebab(str)`** — 驼峰转短横线。
+
+  ```ts
+  camelToKebab('helloWorld')  // "hello-world"
+  ```
+
+- **`toCamel(str)`** — 下划线转驼峰。
+
+  ```ts
+  toCamel('hello_world')  // "helloWorld"
+  ```
+
+- **`firstUpper(str)`** — 首字母大写。
+
+  ```ts
+  firstUpper('hello')  // "Hello"
+  ```
+
+- **`firstLower(str)`** — 首字母小写。
+
+  ```ts
+  firstLower('Hello')  // "hello"
+  ```
+
+- **`reverse(str)`** — 反转字符串。
+
+  ```ts
+  reverse('hello')  // "olleh"
+  ```
+
+- **`trimAll(str)`** — 去除所有空格。
+
+  ```ts
+  trimAll(' h e l lo ')  // "hello"
+  ```
+
+- **`truncate(str, max, suffix?)`** — 超长文本截断。
+
+  ```ts
+  truncate('Hello World', 8)  // "Hello..."
+  ```
+
+- **`truncateByWords(str, max, suffix?)`** — 按字数截断（中文友好）。
+
+  ```ts
+  truncateByWords('你好世界欢迎你', 4)  // "你好世界..."
+  ```
 
 ---
 
 ### 存储 — `storage`
 
-- **`localGet<T>(key)`** — 获取 localStorage（自动 JSON 解析）。 `localGet("user") // { name: "张三" }`
-- **`localSet(key, value)`** — 设置 localStorage（自动 JSON 序列化）。 `localSet("user", { name: "张三" })`
-- **`localRm(key)`** — 移除指定 localStorage。 `localRm("user")`
-- **`localClear()`** — 清除所有 localStorage。 `localClear()`
+- **`localGet<T>(key)`** — 获取 localStorage（自动 JSON 解析）。
+
+  ```ts
+  localGet('user')  // { name: '张三' }
+  ```
+
+- **`localSet(key, value)`** — 设置 localStorage（自动 JSON 序列化）。
+
+  ```ts
+  localSet('user', { name: '张三' })
+  ```
+
+- **`localRm(key)`** — 移除指定 localStorage。
+
+  ```ts
+  localRm('user')
+  ```
+
+- **`localClear()`** — 清除所有 localStorage。
+
+  ```ts
+  localClear()
+  ```
 
 ---
 
 ### 拷贝 — `copy`
 
-- **`deepClone(obj)`** — 递归深拷贝（支持 Date/RegExp/Map/Set/循环引用）。 `deepClone({a:1, b:{c:2}})`
-- **`deepCloneWithJSON(obj)`** — JSON 深拷贝（仅 JSON 安全类型）。 `deepCloneWithJSON({a:1})`
-- **`shallowClone(obj)`** — 浅拷贝（仅第一层）。 `shallowClone({a:1, b:{c:2}})`
+- **`deepClone(obj)`** — 递归深拷贝（支持 Date/RegExp/Map/Set/循环引用）。
+
+  ```ts
+  deepClone({ a: 1, b: { c: 2 } })
+  ```
+
+- **`deepCloneWithJSON(obj)`** — JSON 深拷贝（仅 JSON 安全类型）。
+
+  ```ts
+  deepCloneWithJSON({ a: 1 })
+  ```
+
+- **`shallowClone(obj)`** — 浅拷贝（仅第一层）。
+
+  ```ts
+  shallowClone({ a: 1, b: { c: 2 } })
+  ```
 
 ---
 
 ### 数组 — `array`
 
-- **`unique(arr)`** — Set 去重。 `unique([1,2,2,3]) // [1,2,3]`
-- **`uniqueByKey(arr, key)`** — 对象数组按 key 去重。 `uniqueByKey([{id:1},{id:1}], "id")`
-- **`sortNumAsc(arr)`** — 数值升序。 `sortNumAsc([3,1,2]) // [1,2,3]`
-- **`sortNumDesc(arr)`** — 数值降序。 `sortNumDesc([1,3,2]) // [3,2,1]`
-- **`sortByKey(arr, key, order?)`** — 按对象属性排序。 `sortByKey([{age:30},{age:20}], "age")`
-- **`toArray(arrayLike)`** — 类数组转数组。 `toArray(document.querySelectorAll("div"))`
+- **`unique(arr)`** — Set 去重。
+
+  ```ts
+  unique([1, 2, 2, 3])  // [1, 2, 3]
+  ```
+
+- **`uniqueByKey(arr, key)`** — 对象数组按 key 去重。
+
+  ```ts
+  uniqueByKey([{ id: 1 }, { id: 1 }], 'id')
+  ```
+
+- **`sortNumAsc(arr)`** — 数值升序。
+
+  ```ts
+  sortNumAsc([3, 1, 2])  // [1, 2, 3]
+  ```
+
+- **`sortNumDesc(arr)`** — 数值降序。
+
+  ```ts
+  sortNumDesc([1, 3, 2])  // [3, 2, 1]
+  ```
+
+- **`sortByKey(arr, key, order?)`** — 按对象属性排序。
+
+  ```ts
+  sortByKey([{ age: 30 }, { age: 20 }], 'age')
+  ```
+
+- **`toArray(arrayLike)`** — 类数组转数组。
+
+  ```ts
+  toArray(document.querySelectorAll('div'))
+  ```
 
 ---
 
 ### Cookie — `cookie`
 
-- **`setCookie(name, value, days?)`** — 设置 Cookie（默认7天）。 `setCookie("token", "abc123", 30)`
-- **`getCookie(name)`** — 获取 Cookie。 `getCookie("token") // "abc123"`
-- **`delCookie(name)`** — 删除 Cookie。 `delCookie("token")`
+- **`setCookie(name, value, days?)`** — 设置 Cookie（默认7天）。
+
+  ```ts
+  setCookie('token', 'abc123', 30)
+  ```
+
+- **`getCookie(name)`** — 获取 Cookie。
+
+  ```ts
+  getCookie('token')  // "abc123"
+  ```
+
+- **`delCookie(name)`** — 删除 Cookie。
+
+  ```ts
+  delCookie('token')
+  ```
 
 ---
 
@@ -129,18 +448,60 @@ import { isArray, formatFull, deepClone, unique } from 'pen-it'
 
 #### URL 参数
 
-- **`getUrlParams(url?)`** — 获取 URL 参数对象。 `getUrlParams("?a=1&b=2") // {a:"1",b:"2"}`
-- **`getUrlParam(key, url?)`** — 获取单个 URL 参数。 `getUrlParam("a") // "1"`
-- **`toQueryString(params)`** — 对象转 URL 参数字符串。 `toQueryString({a:1,b:"hello"}) // "a=1&b=hello"`
+- **`getUrlParams(url?)`** — 获取 URL 参数对象。
+
+  ```ts
+  getUrlParams('?a=1&b=2')  // { a: '1', b: '2' }
+  ```
+
+- **`getUrlParam(key, url?)`** — 获取单个 URL 参数。
+
+  ```ts
+  getUrlParam('a')  // "1"
+  ```
+
+- **`toQueryString(params)`** — 对象转 URL 参数字符串。
+
+  ```ts
+  toQueryString({ a: 1, b: 'hello' })  // "a=1&b=hello"
+  ```
 
 #### 剪贴板与文件
 
-- **`copyToClipboard(text)`** — 复制文本到剪贴板（支持降级）。 `await copyToClipboard("Hello")`
-- **`downloadFile(content, filename, mimeType?)`** — 下载文件（Blob）。 `downloadFile("Hello", "hello.txt")`
-- **`exportJSON(data, filename?)`** — 导出 JSON 为文件。 `exportJSON({name:"张三"})`
+- **`copyToClipboard(text)`** — 复制文本到剪贴板（支持降级）。
+
+  ```ts
+  await copyToClipboard('Hello')
+  ```
+
+- **`downloadFile(content, filename, mimeType?)`** — 下载文件（Blob）。
+
+  ```ts
+  downloadFile('Hello', 'hello.txt')
+  ```
+
+- **`exportJSON(data, filename?)`** — 导出 JSON 为文件。
+
+  ```ts
+  exportJSON({ name: '张三' })
+  ```
 
 #### 页面滚动
 
-- **`scrollToTop(behavior?)`** — 滚动到顶部（默认平滑）。 `scrollToTop()`
-- **`scrollToBottom(behavior?)`** — 滚动到底部（默认平滑）。 `scrollToBottom()`
-- **`onScroll(callback)`** — 监听滚动（rAF 节流），返回清理函数。 `const off = onScroll(y => console.log(y))`
+- **`scrollToTop(behavior?)`** — 滚动到顶部（默认平滑）。
+
+  ```ts
+  scrollToTop()
+  ```
+
+- **`scrollToBottom(behavior?)`** — 滚动到底部（默认平滑）。
+
+  ```ts
+  scrollToBottom()
+  ```
+
+- **`onScroll(callback)`** — 监听滚动（rAF 节流），返回清理函数。
+
+  ```ts
+  const off = onScroll(y => console.log(y))
+  ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pen-it",
-  "version": "1.0.1",
-  "description": "用笔锚定记忆中的前端常用工具函数",
+  "version": "1.0.3",
+  "description": "用笔锚定记忆中的前端常用工具函数 — A lightweight frontend utility library for type checking, date/number formatting, string manipulation, storage, deep clone, array operations, cookies, and browser APIs",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -22,12 +22,33 @@
   ],
   "keywords": [
     "utils",
-    "pen-it",
+    "utilities",
     "toolkit",
-    "helpers"
+    "helpers",
+    "frontend",
+    "typescript",
+    "type-checking",
+    "date-format",
+    "number-format",
+    "deep-clone",
+    "string-manipulation",
+    "array-operations",
+    "cookie",
+    "localstorage",
+    "browser-api",
+    "debounce",
+    "throttle"
   ],
   "author": "newborn_calf",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Libao-Jun/pen-it"
+  },
+  "homepage": "https://github.com/Libao-Jun/pen-it#readme",
+  "bugs": {
+    "url": "https://github.com/Libao-Jun/pen-it/issues"
+  },
   "packageManager": "pnpm@10.19.0",
   "devDependencies": {
     "@rollup/plugin-typescript": "^12.3.0",