pen-it 1.0.5 → 1.0.6

package/README.md

@@ -418,6 +418,45 @@ import { isArray, formatFull, deepClone, unique } from 'pen-it'
   toArray(document.querySelectorAll('div'))
   ```
 
+- **`mergeArrays(...arrays)`** — 合并多个数组。
+
+  ```ts
+  mergeArrays([1, 2], [3, 4], [5])  // [1, 2, 3, 4, 5]
+  ```
+
+- **`flatten(arr, depth?)`** — 多维数组扁平化到指定层级（默认 1 层，传 `Infinity` 完全展开）。
+
+  ```ts
+  flatten([1, [2, [3, 4]], 5])          // [1, 2, [3, 4], 5]
+  flatten([1, [2, [3, 4]], 5], Infinity) // [1, 2, 3, 4, 5]
+  ```
+
+- **`arrFind(arr, key, value)`** — 对象数组中按 key-value 查找第一个匹配项。
+
+  ```ts
+  arrFind([{ id: 1 }, { id: 2 }], 'id', 2)  // { id: 2 }
+  ```
+
+- **`groupBy(arr, key)`** — 对象数组按指定属性分组。
+
+  ```ts
+  groupBy([{ type: 'fruit' }, { type: 'vegetable' }], 'type')
+  // => { fruit: [...], vegetable: [...] }
+  ```
+
+- **`filterEmptyValues(obj)`** — 移除对象中值为空（null / undefined / 空字符串）的属性。
+
+  ```ts
+  filterEmptyValues({ a: 1, b: '', c: null })  // { a: 1 }
+  ```
+
+- **`createRange(length, mapFn?)`** — 快速生成范围数组。
+
+  ```ts
+  createRange(5)  // [0, 1, 2, 3, 4]
+  createRange(3, (i) => i * 2)  // [0, 2, 4]
+  ```
+
 ---
 
 ### Cookie — `cookie`
@@ -504,6 +543,17 @@ import { isArray, formatFull, deepClone, unique } from 'pen-it'
   const off = onScroll(y => console.log(y))
   ```
 
+#### 可视区域检测
+
+- **`observeIntersection(target, onEnter, onLeave?, options?)`** — 监听元素进入/离开可视区域，返回清理函数。
+
+  ```ts
+  const cleanup = observeIntersection(
+    document.querySelector('.footer')!,
+    () => loadMore(10),
+  );
+  ```
+
 ---
 
 ### 防抖与节流 — `control`

package/dist/array/index.d.ts

@@ -55,3 +55,65 @@ export declare const sortByKey: <T extends Record<string, any>>(arr: T[], key: k
  * // => [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

@@ -76,3 +76,18 @@ export declare const scrollToBottom: (behavior?: ScrollBehavior) => void;
  * 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/index.cjs

@@ -844,6 +844,85 @@ const sortByKey = (arr, key, order = "asc") => {
 const toArray = (arrayLike) => {
 	return Array.from(arrayLike);
 };
+/**
+* 合并多个数组
+* @param arrays - 一个或多个数组
+* @returns 合并后的新数组
+* @example
+* mergeArrays([1, 2], [3, 4], [5])
+* // => [1, 2, 3, 4, 5]
+*/
+const mergeArrays = (...arrays) => {
+	return [].concat(...arrays);
+};
+/**
+* 将多维数组扁平化到指定层级
+* @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]
+*/
+const flatten = (arr, depth = 1) => {
+	return arr.flat(depth);
+};
+/**
+* 在对象数组中按 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" }
+*/
+const arrFind = (arr, key, value) => {
+	return arr.find((item) => item[key] === value);
+};
+/**
+* 将对象数组按指定属性分组
+* @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" }] }
+*/
+const groupBy = (arr, key) => {
+	return arr.reduce((acc, item) => {
+		const groupKey = String(item[key]);
+		if (!acc[groupKey]) acc[groupKey] = [];
+		acc[groupKey].push(item);
+		return acc;
+	}, {});
+};
+/**
+* 移除对象中值为空（null / undefined / 空字符串）的属性
+* @param obj - 待过滤的对象
+* @returns 过滤后的新对象
+* @example
+* filterEmptyValues({ a: 1, b: "", c: null, d: 3 })
+* // => { a: 1, d: 3 }
+*/
+const filterEmptyValues = (obj) => {
+	return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== null && v !== void 0 && v !== ""));
+};
+/**
+* 根据长度和映射函数快速生成数组
+* @param length - 数组长度
+* @param mapFn - 映射函数，接收索引返回元素值，默认为返回索引
+* @returns 生成的数组
+* @example
+* createRange(5)
+* // => [0, 1, 2, 3, 4]
+*/
+const createRange = (length, mapFn) => {
+	return Array.from({ length }, (_, i) => mapFn ? mapFn(i) : i);
+};
 //#endregion
 //#region src/cookie/index.ts
 /**
@@ -1019,6 +1098,30 @@ const onScroll = (callback) => {
 	window.addEventListener("scroll", handler);
 	return () => window.removeEventListener("scroll", handler);
 };
+/**
+* 监听目标元素是否进入/离开可视区域
+* @param target - 目标 DOM 元素
+* @param onEnter - 元素进入可视区域时的回调
+* @param onLeave - 元素离开可视区域时的回调（可选）
+* @param options - IntersectionObserver 配置项
+* @returns 清理函数，调用后停止观察
+* @example
+* const cleanup = observeIntersection(
+*   document.querySelector(".footer")!,
+*   () => loadMore(10),
+* );
+* cleanup(); // 停止观察
+*/
+const observeIntersection = (target, onEnter, onLeave, options) => {
+	const observer = new IntersectionObserver((entries) => {
+		entries.forEach((entry) => {
+			if (entry.isIntersecting) onEnter(entry);
+			else if (onLeave) onLeave(entry);
+		});
+	}, options);
+	observer.observe(target);
+	return () => observer.disconnect();
+};
 //#endregion
 //#region src/control/index.ts
 /**
@@ -1106,19 +1209,23 @@ const throttle = (fn, interval = 300, { leading = true, trailing = true } = {})
 	return throttled;
 };
 //#endregion
+exports.arrFind = arrFind;
 exports.camelToKebab = camelToKebab;
 exports.capitalize = capitalize;
 exports.compactCN = compactCN;
 exports.compactEN = compactEN;
 exports.copyToClipboard = copyToClipboard;
+exports.createRange = createRange;
 exports.debounce = debounce;
 exports.deepClone = deepClone;
 exports.deepCloneWithJSON = deepCloneWithJSON;
 exports.delCookie = delCookie;
 exports.downloadFile = downloadFile;
 exports.exportJSON = exportJSON;
+exports.filterEmptyValues = filterEmptyValues;
 exports.firstLower = firstLower;
 exports.firstUpper = firstUpper;
+exports.flatten = flatten;
 exports.formatFull = formatFull;
 exports.formatFullReplace = formatFullReplace;
 exports.formatNum = formatNum;
@@ -1128,6 +1235,7 @@ exports.formatYMD = formatYMD;
 exports.getCookie = getCookie;
 exports.getUrlParam = getUrlParam;
 exports.getUrlParams = getUrlParams;
+exports.groupBy = groupBy;
 exports.is = is;
 exports.isArray = isArray;
 exports.isAsyncFunction = isAsyncFunction;
@@ -1161,6 +1269,8 @@ exports.localGet = localGet;
 exports.localRm = localRm;
 exports.localSet = localSet;
 exports.maskPhone = maskPhone;
+exports.mergeArrays = mergeArrays;
+exports.observeIntersection = observeIntersection;
 exports.onScroll = onScroll;
 exports.percentCN = percentCN;
 exports.reverse = reverse;

package/dist/index.js

@@ -843,6 +843,85 @@ const sortByKey = (arr, key, order = "asc") => {
 const toArray = (arrayLike) => {
 	return Array.from(arrayLike);
 };
+/**
+* 合并多个数组
+* @param arrays - 一个或多个数组
+* @returns 合并后的新数组
+* @example
+* mergeArrays([1, 2], [3, 4], [5])
+* // => [1, 2, 3, 4, 5]
+*/
+const mergeArrays = (...arrays) => {
+	return [].concat(...arrays);
+};
+/**
+* 将多维数组扁平化到指定层级
+* @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]
+*/
+const flatten = (arr, depth = 1) => {
+	return arr.flat(depth);
+};
+/**
+* 在对象数组中按 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" }
+*/
+const arrFind = (arr, key, value) => {
+	return arr.find((item) => item[key] === value);
+};
+/**
+* 将对象数组按指定属性分组
+* @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" }] }
+*/
+const groupBy = (arr, key) => {
+	return arr.reduce((acc, item) => {
+		const groupKey = String(item[key]);
+		if (!acc[groupKey]) acc[groupKey] = [];
+		acc[groupKey].push(item);
+		return acc;
+	}, {});
+};
+/**
+* 移除对象中值为空（null / undefined / 空字符串）的属性
+* @param obj - 待过滤的对象
+* @returns 过滤后的新对象
+* @example
+* filterEmptyValues({ a: 1, b: "", c: null, d: 3 })
+* // => { a: 1, d: 3 }
+*/
+const filterEmptyValues = (obj) => {
+	return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== null && v !== void 0 && v !== ""));
+};
+/**
+* 根据长度和映射函数快速生成数组
+* @param length - 数组长度
+* @param mapFn - 映射函数，接收索引返回元素值，默认为返回索引
+* @returns 生成的数组
+* @example
+* createRange(5)
+* // => [0, 1, 2, 3, 4]
+*/
+const createRange = (length, mapFn) => {
+	return Array.from({ length }, (_, i) => mapFn ? mapFn(i) : i);
+};
 //#endregion
 //#region src/cookie/index.ts
 /**
@@ -1018,6 +1097,30 @@ const onScroll = (callback) => {
 	window.addEventListener("scroll", handler);
 	return () => window.removeEventListener("scroll", handler);
 };
+/**
+* 监听目标元素是否进入/离开可视区域
+* @param target - 目标 DOM 元素
+* @param onEnter - 元素进入可视区域时的回调
+* @param onLeave - 元素离开可视区域时的回调（可选）
+* @param options - IntersectionObserver 配置项
+* @returns 清理函数，调用后停止观察
+* @example
+* const cleanup = observeIntersection(
+*   document.querySelector(".footer")!,
+*   () => loadMore(10),
+* );
+* cleanup(); // 停止观察
+*/
+const observeIntersection = (target, onEnter, onLeave, options) => {
+	const observer = new IntersectionObserver((entries) => {
+		entries.forEach((entry) => {
+			if (entry.isIntersecting) onEnter(entry);
+			else if (onLeave) onLeave(entry);
+		});
+	}, options);
+	observer.observe(target);
+	return () => observer.disconnect();
+};
 //#endregion
 //#region src/control/index.ts
 /**
@@ -1105,4 +1208,4 @@ const throttle = (fn, interval = 300, { leading = true, trailing = true } = {})
 	return throttled;
 };
 //#endregion
-export { camelToKebab, capitalize, compactCN, compactEN, copyToClipboard, debounce, deepClone, deepCloneWithJSON, delCookie, downloadFile, exportJSON, firstLower, firstUpper, formatFull, formatFullReplace, formatNum, formatRmb, formatWeek, formatYMD, getCookie, getUrlParam, getUrlParams, is, isArray, isAsyncFunction, isBoolean, isDate, isDef, isElement, isEmpty, isEmptySv, isEqual, isFloat, isFunction, isHexColor, isIOS, isInt, isNull, isNullOrUnDef, isNumber, isObject, isPC, isPrimitive, isPromise, isString, isSymbol, isUnDef, isValidEmail, isWindow, kebabToCamel, localClear, localGet, localRm, localSet, maskPhone, onScroll, percentCN, reverse, scrollToBottom, scrollToTop, setCookie, shallowClone, signed, sortByKey, sortNumAsc, sortNumDesc, spacePhone, throttle, toArray, toCamel, toQueryString, trimAll, truncate, truncateByWords, unique, uniqueByKey };
+export { arrFind, camelToKebab, capitalize, compactCN, compactEN, copyToClipboard, createRange, debounce, deepClone, deepCloneWithJSON, delCookie, downloadFile, exportJSON, filterEmptyValues, firstLower, firstUpper, flatten, formatFull, formatFullReplace, formatNum, formatRmb, formatWeek, formatYMD, getCookie, getUrlParam, getUrlParams, groupBy, is, isArray, isAsyncFunction, isBoolean, isDate, isDef, isElement, isEmpty, isEmptySv, isEqual, isFloat, isFunction, isHexColor, isIOS, isInt, isNull, isNullOrUnDef, isNumber, isObject, isPC, isPrimitive, isPromise, isString, isSymbol, isUnDef, isValidEmail, isWindow, kebabToCamel, localClear, localGet, localRm, localSet, maskPhone, mergeArrays, observeIntersection, onScroll, percentCN, reverse, scrollToBottom, scrollToTop, setCookie, shallowClone, signed, sortByKey, sortNumAsc, sortNumDesc, spacePhone, throttle, toArray, toCamel, toQueryString, trimAll, truncate, truncateByWords, unique, uniqueByKey };

package/package.json

@@ -1,63 +1,63 @@
-{
-  "name": "pen-it",
-  "version": "1.0.5",
-  "description": "用笔锚定记忆中的前端常用工具函数，一个轻量级的前端实用程序库，支持类型检查、日期/数字格式化、字符串操作、数据存储、深度克隆、数组操作、Cookie 以及浏览器 API",
-  "type": "module",
-  "main": "dist/index.cjs",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "scripts": {
-    "build": "rimraf dist && rolldown -c rolldown.config.js",
-    "test": "vitest"
-  },
-  "files": [
-    "dist"
-  ],
-  "keywords": [
-    "utils",
-    "utilities",
-    "toolkit",
-    "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",
-    "@vitest/coverage-v8": "^4.1.8",
-    "jsdom": "^29.1.1",
-    "rimraf": "^6.1.3",
-    "rolldown": "^1.0.3",
-    "tslib": "^2.8.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.8"
-  }
+{
+  "name": "pen-it",
+  "version": "1.0.6",
+  "description": "用笔锚定记忆中的前端常用工具函数，一个轻量级的前端实用程序库，支持类型检查、日期/数字格式化、字符串操作、数据存储、深度克隆、数组操作、Cookie 以及浏览器 API",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c rolldown.config.js",
+    "test": "vitest"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "utils",
+    "utilities",
+    "toolkit",
+    "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",
+    "@vitest/coverage-v8": "^4.1.8",
+    "jsdom": "^29.1.1",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.0.3",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
 }