pen-it 1.0.7 → 1.0.9

package/README.md

@@ -578,7 +578,12 @@ import { isArray, formatFull, deepClone, unique } from 'pen-it'
 
 ## 更新日志
 
-### v1.0.7
+### v1.0.9
+
+- **构建优化** — rolldown 开启 `minify: true`压缩 JS/CJS（注释/空白移除 + 变量名缩短）
+- **类型声明优化** — 移除 `.d.ts` 中冗余的 JSDoc 注释
+
+### v1.0.7 & v1.0.8
 
 - **体积优化** — 移除JSDoc `@example` 示例注释（共 294 行），减少包体积
 - **文档** — README 底部新增更新日志模块

package/dist/array/index.d.ts

@@ -1,119 +1,12 @@
-/**
- * Set 去重
- * @param arr - 数组
- * @returns 去重后的数组
- * @example
- * unique([1, 2, 2, 3])
- * // => [1, 2, 3]
- */
 export declare const unique: <T>(arr: T[]) => T[];
-/**
- * 对象数组按 key 去重
- * @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[];
-/**
- * 按对象属性排序
- * @param arr - 对象数组
- * @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[];
-/**
- * 将多维数组扁平化到指定层级
- * @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[];
-/**
- * 在对象数组中按 key-value 查找第一个匹配项
- * @param arr - 对象数组
- * @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;
-/**
- * 将对象数组按指定属性分组
- * @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>;
-/**
- * 根据长度和映射函数快速生成数组
- * @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

@@ -1,93 +1,10 @@
-/**
- * 获取 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>;
-/**
- * 获取单个 URL 参数
- * @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;
-/**
- * 复制文本到剪贴板
- * 优先使用 Clipboard API，失败时降级为 execCommand
- * @param text - 要复制的文本
- * @returns 复制成功返回 true，失败返回 false
- * @example
- * await copyToClipboard("Hello World")
- * // => true
- */
 export declare const copyToClipboard: (text: string) => Promise<boolean>;
-/**
- * 下载文件（Blob）
- * @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;
-/**
- * 监听目标元素是否进入/离开可视区域
- * @param target - 目标 DOM 元素
- * @param onEnter - 元素进入可视区域时的回调
- * @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

@@ -1,33 +1,9 @@
-/**
- * 防抖 —— 在事件被触发 n 秒后再执行，如果 n 秒内再次触发则重新计时
- * @param fn - 需要防抖的函数
- * @param delay - 延迟时间（毫秒），默认 300
- * @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;
     trailing?: boolean;
 }) => ((...args: Parameters<T>) => void) & {
     cancel: () => void;
 };
-/**
- * 节流 —— 固定间隔内最多执行一次，超出频率的调用被忽略
- * @param fn - 需要节流的函数
- * @param interval - 间隔时间（毫秒），默认 300
- * @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;
     trailing?: boolean;

package/dist/cookie/index.d.ts

@@ -1,25 +1,3 @@
-/**
- * 设置 Cookie
- * @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

@@ -1,35 +1,3 @@
-/**
- * 递归深拷贝
- * 支持 Date、RegExp、Map、Set、Array、Object 以及循环引用
- * @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;
-/**
- * JSON 深拷贝
- * 使用 JSON 序列化与反序列化实现，仅支持 JSON 安全的数据类型
- * （不支持函数、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;
-/**
- * 浅拷贝
- * 仅拷贝第一层属性，嵌套对象仍共享引用
- * @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

@@ -1,211 +1,25 @@
-/**
- * 完整日期时间（年/月/日 时分秒）_ 斜杠
- * @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;
-/**
- * 货币格式化
- * @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";
     currency: "CNY";
 }) => string;
-/**
- * 千位分隔符（数字格式化），中文（逗号分隔）
- * @param value - 数值
- * @returns 格式化后的千位分隔数字字符串
- * @example
- * formatNum(1234567)
- * // => "1,234,567"
- */
 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;
-/**
- * 带符号的正负数显示
- * @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;
-/**
- * 超长文本截断
- * @param str - 内容
- * @param maxLength - 截断位置
- * @param suffix - 自定义的替换截断后的内容
- * @returns 超长文本截断后内容
- * @example
- * truncate("Hello World", 8)
- * // => "Hello..."
- */
 export declare const truncate: (str: string, maxLength: number, suffix?: string) => string;
-/**
- * 按字数截断（中文友好）
- * @param str - 内容
- * @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;