pen-it 1.0.6 → 1.0.8

package/README.md

@@ -1,6 +1,6 @@
 # pen-it
 
-用笔锚定记忆中的前端常用工具函数，一个轻量级的前端实用程序库，支持类型检查、日期/数字格式化、字符串操作、数据存储、深度克隆、数组操作、Cookie 以及浏览器 API
+用“笔”锚定记忆，一个轻量级前端工具库，覆盖类型检查、日期格式化、数字处理、深克隆、本地存储、Cookie 及浏览器 API。零依赖，支持 Tree-shaking，让常用函数信手拈来。
 
 ## 安装
 
@@ -572,4 +572,33 @@ import { isArray, formatFull, deepClone, unique } from 'pen-it'
   const fn = throttle((val: string) => console.log(val), 500)
   fn('a'); fn('b'); fn('c')
   // => 'a'，500ms 后输出 'c'
-  ```
+  ```
+
+---
+
+## 更新日志
+
+### v1.0.7
+
+- **体积优化** — 移除JSDoc `@example` 示例注释（共 294 行），减少包体积
+- **文档** — README 底部新增更新日志模块
+
+### v1.0.6
+
+- **数组模块** — 新增 `mergeArrays` 数组合并、`flatten` 数组扁平化（支持任意层级）、`arrFind` 数组项查询、`groupBy` JSON 数组分组、`filterEmptyValues` 对象移除空值属性、`createRange` 快速生成范围数组
+- **浏览器模块** — 新增 `observeIntersection` 可视区域检测（基于 IntersectionObserver）
+
+### v1.0.5
+
+- **控制模块** — 新增 `debounce` 防抖与 `throttle` 节流
+
+### v1.0.4
+
+- 初始版本，包含以下模块：
+  - **类型判断** — `isArray` `isObject` `is` `isFunction` `isAsyncFunction` `isPromise` `isDate` `isNumber` `isInt` `isFloat` `isString` `isBoolean` `isSymbol` `isPrimitive` `isNull` `isDef` `isUnDef` `isNullOrUnDef` `isEmpty` `isEmptySv` `isEqual` `isHexColor` `isValidEmail` `isPC` `isWindow` `isElement` `isIOS` 共 27 个函数
+  - **格式化** — 日期时间（`formatFull` `formatFullReplace` `formatYMD` `formatWeek`）、数字货币（`formatRmb` `formatNum` `percentCN` `compactEN` `compactCN` `signed`）、字符串（`maskPhone` `spacePhone` `capitalize` `kebabToCamel` `camelToKebab` `toCamel` `firstUpper` `firstLower` `reverse` `trimAll` `truncate` `truncateByWords`）共 22 个函数
+  - **存储** — `localGet` `localSet` `localRm` `localClear` 共 4 个函数
+  - **拷贝** — `deepClone` `deepCloneWithJSON` `shallowClone` 共 3 个函数
+  - **数组** — `unique` `uniqueByKey` `sortNumAsc` `sortNumDesc` `sortByKey` `toArray` 共 6 个函数
+  - **Cookie** — `setCookie` `getCookie` `delCookie` 共 3 个函数
+  - **浏览器** — `getUrlParams` `getUrlParam` `toQueryString` `copyToClipboard` `downloadFile` `exportJSON` `scrollToTop` `scrollToBottom` `onScroll` 共 9 个函数

package/dist/array/index.d.ts

@@ -2,9 +2,6 @@
  * Set 去重
  * @param arr - 数组
  * @returns 去重后的数组
- * @example
- * unique([1, 2, 2, 3])
- * // => [1, 2, 3]
  */
 export declare const unique: <T>(arr: T[]) => T[];
 /**
@@ -12,27 +9,18 @@ export declare const unique: <T>(arr: T[]) => T[];
  * @param arr - 对象数组
  * @param key - 用于去重判定的键名
  * @returns 去重后的数组
- * @example
- * uniqueByKey([{ id: 1, name: "a" }, { id: 1, name: "b" }], "id")
- * // => [{ id: 1, name: "a" }]
  */
 export declare const uniqueByKey: <T extends Record<string, any>>(arr: T[], key: keyof T) => T[];
 /**
  * 数值升序
  * @param arr - 数值数组
  * @returns 升序排序后的新数组
- * @example
- * sortNumAsc([3, 1, 2])
- * // => [1, 2, 3]
  */
 export declare const sortNumAsc: (arr: number[]) => number[];
 /**
  * 数值降序
  * @param arr - 数值数组
  * @returns 降序排序后的新数组
- * @example
- * sortNumDesc([1, 3, 2])
- * // => [3, 2, 1]
  */
 export declare const sortNumDesc: (arr: number[]) => number[];
 /**
@@ -41,27 +29,18 @@ export declare const sortNumDesc: (arr: number[]) => number[];
  * @param key - 用于排序的属性名
  * @param order - 排序方向，"asc" 升序 / "desc" 降序，默认 "asc"
  * @returns 排序后的新数组
- * @example
- * sortByKey([{ age: 30 }, { age: 20 }], "age", "asc")
- * // => [{ age: 20 }, { age: 30 }]
  */
 export declare const sortByKey: <T extends Record<string, any>>(arr: T[], key: keyof T, order?: "asc" | "desc") => T[];
 /**
  * 类数组转数组
  * @param arrayLike - 类数组对象（如 NodeList、arguments）
  * @returns 转换后的数组
- * @example
- * toArray(document.querySelectorAll("div"))
- * // => [div, div, ...]
  */
 export declare const toArray: <T>(arrayLike: ArrayLike<T>) => T[];
 /**
  * 合并多个数组
  * @param arrays - 一个或多个数组
  * @returns 合并后的新数组
- * @example
- * mergeArrays([1, 2], [3, 4], [5])
- * // => [1, 2, 3, 4, 5]
  */
 export declare const mergeArrays: <T>(...arrays: T[][]) => T[];
 /**
@@ -69,12 +48,6 @@ export declare const mergeArrays: <T>(...arrays: T[][]) => T[];
  * @param arr - 多维数组
  * @param depth - 扁平化深度，默认 1（仅展开一层）。传 Infinity 可完全扁平化为一维
  * @returns 扁平化后的数组
- * @example
- * flatten([1, [2, [3, 4]], 5])
- * // => [1, 2, [3, 4], 5]
- * @example
- * flatten([1, [2, [3, 4]], 5], Infinity)
- * // => [1, 2, 3, 4, 5]
  */
 export declare const flatten: <T>(arr: any[], depth?: number) => T[];
 /**
@@ -83,9 +56,6 @@ export declare const flatten: <T>(arr: any[], depth?: number) => T[];
  * @param key - 要匹配的键名
  * @param value - 要匹配的键值
  * @returns 第一个匹配的对象，无匹配则返回 undefined
- * @example
- * arrFind([{ id: 1, name: "a" }, { id: 2, name: "b" }], "id", 2)
- * // => { id: 2, name: "b" }
  */
 export declare const arrFind: <T extends Record<string, any>>(arr: T[], key: keyof T, value: T[keyof T]) => T | undefined;
 /**
@@ -93,18 +63,12 @@ export declare const arrFind: <T extends Record<string, any>>(arr: T[], key: key
  * @param arr - 对象数组
  * @param key - 用于分组的属性名
  * @returns 以属性值为键、对应数组为值的对象
- * @example
- * groupBy([{ type: "fruit", name: "apple" }, { type: "vegetable", name: "carrot" }], "type")
- * // => { fruit: [{ type: "fruit", name: "apple" }], vegetable: [{ type: "vegetable", name: "carrot" }] }
  */
 export declare const groupBy: <T extends Record<string, any>>(arr: T[], key: keyof T) => Record<string, T[]>;
 /**
  * 移除对象中值为空（null / undefined / 空字符串）的属性
  * @param obj - 待过滤的对象
  * @returns 过滤后的新对象
- * @example
- * filterEmptyValues({ a: 1, b: "", c: null, d: 3 })
- * // => { a: 1, d: 3 }
  */
 export declare const filterEmptyValues: <T extends Record<string, any>>(obj: T) => Partial<T>;
 /**
@@ -112,8 +76,5 @@ export declare const filterEmptyValues: <T extends Record<string, any>>(obj: T)
  * @param length - 数组长度
  * @param mapFn - 映射函数，接收索引返回元素值，默认为返回索引
  * @returns 生成的数组
- * @example
- * createRange(5)
- * // => [0, 1, 2, 3, 4]
  */
 export declare const createRange: <T = number>(length: number, mapFn?: (index: number) => T) => T[];

package/dist/browser/index.d.ts

@@ -2,9 +2,6 @@
  * 获取 URL 参数对象
  * @param url - URL 字符串，默认使用当前页面地址
  * @returns 参数键值对对象
- * @example
- * getUrlParams("https://example.com?a=1&b=2")
- * // => { a: "1", b: "2" }
  */
 export declare const getUrlParams: (url?: string) => Record<string, string>;
 /**
@@ -12,18 +9,12 @@ export declare const getUrlParams: (url?: string) => Record<string, string>;
  * @param key - 参数名
  * @param url - URL 字符串，默认使用当前页面地址
  * @returns 参数值，不存在则返回 null
- * @example
- * getUrlParam("a", "https://example.com?a=1")
- * // => "1"
  */
 export declare const getUrlParam: (key: string, url?: string) => string | null;
 /**
  * 对象转 URL 参数字符串
  * @param params - 参数键值对对象，值为 null/undefined 的项会被过滤
  * @returns URL 参数字符串（不含 ? 前缀）
- * @example
- * toQueryString({ a: 1, b: "hello", c: null })
- * // => "a=1&b=hello"
  */
 export declare const toQueryString: (params: Record<string, any>) => string;
 /**
@@ -31,9 +22,6 @@ export declare const toQueryString: (params: Record<string, any>) => string;
  * 优先使用 Clipboard API，失败时降级为 execCommand
  * @param text - 要复制的文本
  * @returns 复制成功返回 true，失败返回 false
- * @example
- * await copyToClipboard("Hello World")
- * // => true
  */
 export declare const copyToClipboard: (text: string) => Promise<boolean>;
 /**
@@ -41,39 +29,28 @@ export declare const copyToClipboard: (text: string) => Promise<boolean>;
  * @param content - 文件内容
  * @param filename - 文件名
  * @param mimeType - MIME 类型，默认 "text/plain"
- * @example
- * downloadFile("Hello", "hello.txt")
  */
 export declare const downloadFile: (content: string | BlobPart, filename: string, mimeType?: string) => void;
 /**
  * 导出 JSON 为文件
  * @param data - 要导出的数据
  * @param filename - 文件名，默认 "data.json"
- * @example
- * exportJSON({ name: "张三", age: 30 })
  */
 export declare const exportJSON: (data: any, filename?: string) => void;
 /**
  * 滚动到顶部
  * @param behavior - 滚动行为，"smooth" 平滑 / "auto" 瞬间，默认 "smooth"
- * @example
- * scrollToTop()
  */
 export declare const scrollToTop: (behavior?: ScrollBehavior) => void;
 /**
  * 滚动到底部
  * @param behavior - 滚动行为，"smooth" 平滑 / "auto" 瞬间，默认 "smooth"
- * @example
- * scrollToBottom()
  */
 export declare const scrollToBottom: (behavior?: ScrollBehavior) => void;
 /**
  * 监听页面滚动（requestAnimationFrame 节流）
  * @param callback - 滚动回调，接收当前 scrollY 值
  * @returns 清理函数，调用后移除事件监听
- * @example
- * const cleanup = onScroll((y) => console.log(y));
- * cleanup(); // 停止监听
  */
 export declare const onScroll: (callback: (scrollY: number) => void) => () => void;
 /**
@@ -83,11 +60,5 @@ export declare const onScroll: (callback: (scrollY: number) => void) => () => vo
  * @param onLeave - 元素离开可视区域时的回调（可选）
  * @param options - IntersectionObserver 配置项
  * @returns 清理函数，调用后停止观察
- * @example
- * const cleanup = observeIntersection(
- *   document.querySelector(".footer")!,
- *   () => loadMore(10),
- * );
- * cleanup(); // 停止观察
  */
 export declare const observeIntersection: (target: Element, onEnter: (entry: IntersectionObserverEntry) => void, onLeave?: (entry: IntersectionObserverEntry) => void, options?: IntersectionObserverInit) => () => void;

package/dist/control/index.d.ts

@@ -5,10 +5,6 @@
  * @param options.leading - 首次调用是否立即执行，默认 false
  * @param options.trailing - 停止调用后是否延迟执行，默认 true
  * @returns 防抖后的函数，附带 cancel 方法
- * @example
- * const fn = debounce((val: string) => console.log(val), 500)
- * fn("a"); fn("b"); fn("c")
- * // => "c"
  */
 export declare const debounce: <T extends (...args: any[]) => any>(fn: T, delay?: number, { leading, trailing }?: {
     leading?: boolean;
@@ -23,10 +19,6 @@ export declare const debounce: <T extends (...args: any[]) => any>(fn: T, delay?
  * @param options.leading - 首次调用是否立即执行，默认 true
  * @param options.trailing - 最后一次调用后是否尾部执行，默认 true
  * @returns 节流后的函数，附带 cancel 方法
- * @example
- * const fn = throttle((val: string) => console.log(val), 500)
- * fn("a"); fn("b"); fn("c")
- * // => "a"，500ms 后输出 "c"
  */
 export declare const throttle: <T extends (...args: any[]) => any>(fn: T, interval?: number, { leading, trailing }?: {
     leading?: boolean;

package/dist/cookie/index.d.ts

@@ -3,23 +3,16 @@
  * @param name - Cookie 名称
  * @param value - Cookie 值
  * @param days - 有效天数，默认 7 天
- * @example
- * setCookie("token", "abc123", 30)
  */
 export declare const setCookie: (name: string, value: string, days?: number) => void;
 /**
  * 获取 Cookie
  * @param name - Cookie 名称
  * @returns Cookie 值，不存在则返回 null
- * @example
- * getCookie("token")
- * // => "abc123"
  */
 export declare const getCookie: (name: string) => string | null;
 /**
  * 删除 Cookie
  * @param name - Cookie 名称
- * @example
- * delCookie("token")
  */
 export declare const delCookie: (name: string) => void;

package/dist/copy/index.d.ts

@@ -4,11 +4,6 @@
  * @param obj - 要拷贝的值
  * @param hash - 内部 WeakMap 用于处理循环引用，调用方无需传入
  * @returns 深拷贝后的值
- * @example
- * const obj = { a: 1, b: { c: 2 }, d: new Date() };
- * const cloned = deepClone(obj);
- * // cloned.b !== obj.b
- * // cloned.d !== obj.d
  */
 export declare function deepClone<T>(obj: T, hash?: WeakMap<any, any>): T;
 /**
@@ -17,9 +12,6 @@ export declare function deepClone<T>(obj: T, hash?: WeakMap<any, any>): T;
  * （不支持函数、undefined、Date、RegExp、Map、Set 等）
  * @param obj - 要拷贝的 JSON 安全值
  * @returns 深拷贝后的值
- * @example
- * deepCloneWithJSON({ a: 1, b: [2, 3] })
- * // => { a: 1, b: [2, 3] }
  */
 export declare function deepCloneWithJSON<T>(obj: T): T;
 /**
@@ -27,9 +19,5 @@ export declare function deepCloneWithJSON<T>(obj: T): T;
  * 仅拷贝第一层属性，嵌套对象仍共享引用
  * @param obj - 要拷贝的对象或数组
  * @returns 浅拷贝后的值
- * @example
- * const obj = { a: 1, b: { c: 2 } };
- * const cloned = shallowClone(obj);
- * // cloned.b === obj.b（共享引用）
  */
 export declare function shallowClone<T>(obj: T): T;

package/dist/format/index.d.ts

@@ -2,36 +2,24 @@
  * 完整日期时间（年/月/日 时分秒）_ 斜杠
  * @param date - Date 对象
  * @returns 格式化后的完整日期时间字符串，如 "2026/06/03 14:30:45"
- * @example
- * formatFull(new Date("2026-06-03T14:30:45"))
- * // => "2026/06/03 14:30:45"
  */
 export declare const formatFull: (date: Date) => string;
 /**
  * 完整日期时间（年-月-日 时分秒）_ 短横线
  * @param date - Date 对象
  * @returns 格式化后的完整日期时间字符串，如 "2026-06-03 14:30:45"
- * @example
- * formatFullReplace(new Date("2026-06-03T14:30:45"))
- * // => "2026-06-03 14:30:45"
  */
 export declare const formatFullReplace: (date: Date) => string;
 /**
  * 中文年月日
  * @param date - Date 对象
  * @returns 格式化后的中文日期字符串，如 "2026年6月3日"
- * @example
- * formatYMD(new Date("2026-06-03"))
- * // => "2026年6月3日"
  */
 export declare const formatYMD: (date: Date) => string;
 /**
  * 星期几
  * @param date - Date 对象
  * @returns 中文星期字符串，如 "星期三"
- * @example
- * formatWeek(new Date("2026-06-03"))
- * // => "星期三"
  */
 export declare const formatWeek: (date: Date) => string;
 /**
@@ -39,9 +27,6 @@ export declare const formatWeek: (date: Date) => string;
  * @param value - 数值
  * @param options - 格式化选项
  * @returns 格式化后的货币字符串
- * @example
- * formatRmb(1234.56, { type: "zh-CN", currency: "CNY" })
- * // => "¥1,234.56"
  */
 export declare const formatRmb: (value: number, options: {
     type: "zh-CN";
@@ -51,9 +36,6 @@ export declare const formatRmb: (value: number, options: {
  * 千位分隔符（数字格式化），中文（逗号分隔）
  * @param value - 数值
  * @returns 格式化后的千位分隔数字字符串
- * @example
- * formatNum(1234567)
- * // => "1,234,567"
  */
 export declare const formatNum: (value: number) => string;
 /**
@@ -61,27 +43,18 @@ export declare const formatNum: (value: number) => string;
  * @param value - 百分比数值
  * @param digit - 保留的小数位数，默认为 0
  * @returns 格式化后的百分比字符串
- * @example
- * percentCN(0.1234, 2)
- * // => "12.34%"
  */
 export declare const percentCN: (value: number, digit?: number) => string;
 /**
  * 紧凑计数法（大数简化）_ 英文缩写
  * @param value - 数值
  * @returns 格式化后的紧凑数字字符串（英文缩写）
- * @example
- * compactEN(12345)
- * // => "12K"
  */
 export declare const compactEN: (value: number) => string;
 /**
  * 紧凑计数法（大数简化）_ 中文缩写
  * @param value - 数值
  * @returns 格式化后的紧凑数字字符串（中文缩写）
- * @example
- * compactCN(12345)
- * // => "1.2万"
  */
 export declare const compactCN: (value: number) => string;
 /**
@@ -89,57 +62,36 @@ export declare const compactCN: (value: number) => string;
  * @param value - 数值
  * @param digit - 保留的小数位数，默认为 0
  * @returns 格式化后的带正负号的数值显示
- * @example
- * signed(42, 1)
- * // => "+42.0"
- * @example
- * signed(-5)
- * // => "-5"
  */
 export declare const signed: (value: number, digit?: number) => string;
 /**
  * 手机号格式化脱敏 _ 隐藏中间 4 位数
  * @param phone - 手机号码
  * @returns 手机号格式化脱敏后的手机号
- * @example
- * maskPhone("13812345678")
- * // => "138****5678"
  */
 export declare const maskPhone: (phone: string) => string;
 /**
  * 手机号格式化 _ 空格分隔
  * @param phone - 手机号
  * @returns 手机号空格格式化的手机号
- * @example
- * spacePhone("13812345678")
- * // => "138 1234 5678"
  */
 export declare const spacePhone: (phone: string) => string;
 /**
  * 每个单词首字母大写
  * @param str - 字符串
  * @returns 每个单词首字母大写后的字符串
- * @example
- * capitalize("hello world")
- * // => "Hello World"
  */
 export declare const capitalize: (str: string) => string;
 /**
  * 短横线连接转小驼峰（kebab-case → camelCase）
  * @param str - 字符串
  * @returns 转换后的小驼峰字符串
- * @example
- * kebabToCamel("hello-world")
- * // => "helloWorld"
  */
 export declare const kebabToCamel: (str: string) => string;
 /**
  * 大驼峰或小驼峰 _ 转为 ‘-’ 短横线连接
  * @param str - 字符串
  * @returns 大驼峰或小驼峰命名格式化的字符串
- * @example
- * camelToKebab("helloWorld")
- * // => "hello-world"
  */
 export declare const camelToKebab: (str: string) => string;
 /**
@@ -148,9 +100,6 @@ export declare const camelToKebab: (str: string) => string;
  * @param maxLength - 截断位置
  * @param suffix - 自定义的替换截断后的内容
  * @returns 超长文本截断后内容
- * @example
- * truncate("Hello World", 8)
- * // => "Hello..."
  */
 export declare const truncate: (str: string, maxLength: number, suffix?: string) => string;
 /**
@@ -159,53 +108,35 @@ export declare const truncate: (str: string, maxLength: number, suffix?: string)
  * @param maxWords - 截断位置
  * @param suffix - 自定义的替换截断后的内容
  * @returns 超长文本截断后内容
- * @example
- * truncateByWords("你好世界欢迎你", 4)
- * // => "你好世界..."
  */
 export declare const truncateByWords: (str: string, maxWords: number, suffix?: string) => string;
 /**
  * 去除所有空格 _ 前后中间
  * @param str - 内容
  * @returns 去除空格后的内容
- * @example
- * trimAll(" hello  world ")
- * // => "helloworld"
  */
 export declare const trimAll: (str: string) => string;
 /**
  * 下划线转驼峰（snake_case → camelCase）
  * @param str - 字符串
  * @returns 转换后的驼峰字符串
- * @example
- * toCamel("hello_world")
- * // => "helloWorld"
  */
 export declare const toCamel: (str: string) => string;
 /**
  * 首字母大写
  * @param str - 字符串
  * @returns 首字母大写后的字符串
- * @example
- * firstUpper("hello")
- * // => "Hello"
  */
 export declare const firstUpper: (str: string) => string;
 /**
  * 首字母小写
  * @param str - 字符串
  * @returns 首字母小写后的字符串
- * @example
- * firstLower("Hello")
- * // => "hello"
  */
 export declare const firstLower: (str: string) => string;
 /**
  * 反转字符串
  * @param str - 字符串
  * @returns 反转后的字符串
- * @example
- * reverse("hello")
- * // => "olleh"
  */
 export declare const reverse: (str: string) => string;