@tanwan/utils 1.1.0 → 1.2.0

package/dist/lazyLoadImages.js

@@ -0,0 +1,36 @@
+//#region src/dom/lazyLoadImages/index.ts
+/**
+* 为图片添加懒加载（IntersectionObserver）
+*
+* 图片需要有 `data-src` 属性存放真实 URL。加载时会替换到 `src`，并从 `data-src` 移除。
+*
+* @param selector - 图片选择器，默认 `'img[data-src]'`
+* @returns 清理函数（调用后取消懒加载）
+*
+* @example
+* ```ts
+* import lazyLoadImages from '@tanwan/utils/lazyLoadImages'
+* lazyLoadImages()
+* // 或指定选择器
+* lazyLoadImages('.lazy-img')
+* ```
+*/
+function lazyLoadImages(selector = "img[data-src]") {
+	const observer = new IntersectionObserver((entries) => {
+		for (const entry of entries) {
+			if (!entry.isIntersecting) continue;
+			const img = entry.target;
+			const src = img.dataset.src;
+			if (src) {
+				img.src = src;
+				delete img.dataset.src;
+			}
+			observer.unobserve(img);
+		}
+	}, { rootMargin: "100px" });
+	const images = document.querySelectorAll(selector);
+	for (const img of images) observer.observe(img);
+	return () => observer.disconnect();
+}
+//#endregion
+export { lazyLoadImages as default };

package/dist/listToTree.cjs

@@ -0,0 +1,25 @@
+//#region src/tree/listToTree/index.ts
+function listToTree(list, options = {}) {
+	const { id = "id", parentId = "parentId", children = "children", rootValue = null } = options;
+	const map = /* @__PURE__ */ new Map();
+	const result = [];
+	for (const item of list) {
+		const node = {
+			...item,
+			[children]: []
+		};
+		map.set(item[id], node);
+	}
+	for (const item of list) {
+		const node = map.get(item[id]);
+		const pid = item[parentId];
+		if (pid === rootValue) result.push(node);
+		else {
+			const parent = map.get(pid);
+			if (parent) parent[children].push(node);
+		}
+	}
+	return result;
+}
+//#endregion
+module.exports = listToTree;

package/dist/listToTree.d.cts

@@ -0,0 +1,32 @@
+//#region src/tree/listToTree/index.d.ts
+/**
+* 将扁平数组转换为树结构
+*
+* @param list - 扁平数据数组
+* @param options - 配置项
+* @param options.id - 节点唯一标识的属性名，默认 `'id'`
+* @param options.parentId - 父节点标识的属性名，默认 `'parentId'`
+* @param options.children - 存放子节点的属性名，默认 `'children'`
+* @param options.rootValue - 根节点的 parentId 值，默认 `null`
+* @returns 树结构数组
+*
+* @example
+* ```ts
+* import listToTree from '@tanwan/utils/listToTree'
+* const list = [
+*   { id: 1, parentId: null, name: '根' },
+*   { id: 2, parentId: 1, name: '子' },
+*   { id: 3, parentId: 1, name: '子2' },
+* ]
+* listToTree(list)
+* // [{ id: 1, parentId: null, name: '根', children: [{ id: 2, ... }, { id: 3, ... }] }]
+* ```
+*/
+interface TreeOptions {
+  id?: string;
+  parentId?: string;
+  children?: string;
+  rootValue?: unknown;
+}
+declare function listToTree<T extends Record<string, unknown>>(list: T[], options?: TreeOptions): (T & Record<string, unknown[]>)[];
+export = listToTree;

package/dist/listToTree.d.ts

@@ -0,0 +1,33 @@
+//#region src/tree/listToTree/index.d.ts
+/**
+* 将扁平数组转换为树结构
+*
+* @param list - 扁平数据数组
+* @param options - 配置项
+* @param options.id - 节点唯一标识的属性名，默认 `'id'`
+* @param options.parentId - 父节点标识的属性名，默认 `'parentId'`
+* @param options.children - 存放子节点的属性名，默认 `'children'`
+* @param options.rootValue - 根节点的 parentId 值，默认 `null`
+* @returns 树结构数组
+*
+* @example
+* ```ts
+* import listToTree from '@tanwan/utils/listToTree'
+* const list = [
+*   { id: 1, parentId: null, name: '根' },
+*   { id: 2, parentId: 1, name: '子' },
+*   { id: 3, parentId: 1, name: '子2' },
+* ]
+* listToTree(list)
+* // [{ id: 1, parentId: null, name: '根', children: [{ id: 2, ... }, { id: 3, ... }] }]
+* ```
+*/
+interface TreeOptions {
+  id?: string;
+  parentId?: string;
+  children?: string;
+  rootValue?: unknown;
+}
+declare function listToTree<T extends Record<string, unknown>>(list: T[], options?: TreeOptions): (T & Record<string, unknown[]>)[];
+//#endregion
+export { listToTree as default };

package/dist/listToTree.js

@@ -0,0 +1,25 @@
+//#region src/tree/listToTree/index.ts
+function listToTree(list, options = {}) {
+	const { id = "id", parentId = "parentId", children = "children", rootValue = null } = options;
+	const map = /* @__PURE__ */ new Map();
+	const result = [];
+	for (const item of list) {
+		const node = {
+			...item,
+			[children]: []
+		};
+		map.set(item[id], node);
+	}
+	for (const item of list) {
+		const node = map.get(item[id]);
+		const pid = item[parentId];
+		if (pid === rootValue) result.push(node);
+		else {
+			const parent = map.get(pid);
+			if (parent) parent[children].push(node);
+		}
+	}
+	return result;
+}
+//#endregion
+export { listToTree as default };

package/dist/mapValues.cjs

@@ -0,0 +1,25 @@
+//#region src/object/mapValues/index.ts
+/**
+* 映射对象的所有值，返回新对象
+*
+* @param obj - 源对象
+* @param iteratee - 值映射函数，接收 value 和 key
+* @returns 映射值后的新对象
+*
+* @example
+* ```ts
+* import mapValues from '@tanwan/utils/mapValues'
+* mapValues({ a: 1, b: 2 }, (v) => v * 2)
+* // { a: 2, b: 4 }
+*
+* mapValues({ x: 'a', y: 'b' }, (v, k) => k + v)
+* // { x: 'xa', y: 'yb' }
+* ```
+*/
+function mapValues(obj, iteratee) {
+	const result = {};
+	for (const key of Object.keys(obj)) result[key] = iteratee(obj[key], key);
+	return result;
+}
+//#endregion
+module.exports = mapValues;

package/dist/mapValues.d.cts

@@ -0,0 +1,20 @@
+//#region src/object/mapValues/index.d.ts
+/**
+* 映射对象的所有值，返回新对象
+*
+* @param obj - 源对象
+* @param iteratee - 值映射函数，接收 value 和 key
+* @returns 映射值后的新对象
+*
+* @example
+* ```ts
+* import mapValues from '@tanwan/utils/mapValues'
+* mapValues({ a: 1, b: 2 }, (v) => v * 2)
+* // { a: 2, b: 4 }
+*
+* mapValues({ x: 'a', y: 'b' }, (v, k) => k + v)
+* // { x: 'xa', y: 'yb' }
+* ```
+*/
+declare function mapValues<T extends Record<string, unknown>, V>(obj: T, iteratee: (value: T[keyof T], key: keyof T) => V): Record<keyof T, V>;
+export = mapValues;

package/dist/mapValues.d.ts

@@ -0,0 +1,21 @@
+//#region src/object/mapValues/index.d.ts
+/**
+* 映射对象的所有值，返回新对象
+*
+* @param obj - 源对象
+* @param iteratee - 值映射函数，接收 value 和 key
+* @returns 映射值后的新对象
+*
+* @example
+* ```ts
+* import mapValues from '@tanwan/utils/mapValues'
+* mapValues({ a: 1, b: 2 }, (v) => v * 2)
+* // { a: 2, b: 4 }
+*
+* mapValues({ x: 'a', y: 'b' }, (v, k) => k + v)
+* // { x: 'xa', y: 'yb' }
+* ```
+*/
+declare function mapValues<T extends Record<string, unknown>, V>(obj: T, iteratee: (value: T[keyof T], key: keyof T) => V): Record<keyof T, V>;
+//#endregion
+export { mapValues as default };

package/dist/mapValues.js

@@ -0,0 +1,25 @@
+//#region src/object/mapValues/index.ts
+/**
+* 映射对象的所有值，返回新对象
+*
+* @param obj - 源对象
+* @param iteratee - 值映射函数，接收 value 和 key
+* @returns 映射值后的新对象
+*
+* @example
+* ```ts
+* import mapValues from '@tanwan/utils/mapValues'
+* mapValues({ a: 1, b: 2 }, (v) => v * 2)
+* // { a: 2, b: 4 }
+*
+* mapValues({ x: 'a', y: 'b' }, (v, k) => k + v)
+* // { x: 'xa', y: 'yb' }
+* ```
+*/
+function mapValues(obj, iteratee) {
+	const result = {};
+	for (const key of Object.keys(obj)) result[key] = iteratee(obj[key], key);
+	return result;
+}
+//#endregion
+export { mapValues as default };

package/dist/maskString.cjs

@@ -0,0 +1,28 @@
+//#region src/string/maskString/index.ts
+/**
+* 字符串脱敏处理，将中间部分替换为指定字符
+*
+* @param str - 原字符串
+* @param start - 保留前几位，默认 3
+* @param end - 保留后几位，默认 4
+* @param mask - 脱敏字符，默认 `'*'`
+* @returns 脱敏后的字符串
+*
+* @example
+* ```ts
+* import maskString from '@tanwan/utils/maskString'
+* // 手机号脱敏
+* maskString('18812345678', 3, 4)
+* // '188****5678'
+*
+* // 身份证脱敏
+* maskString('510123199001011234', 6, 4)
+* // '510123********1234'
+* ```
+*/
+function maskString(str, start = 3, end = 4, mask = "*") {
+	if (str.length <= start + end) return str;
+	return str.slice(0, start) + mask.repeat(str.length - start - end) + str.slice(-end);
+}
+//#endregion
+module.exports = maskString;

package/dist/maskString.d.cts

@@ -0,0 +1,24 @@
+//#region src/string/maskString/index.d.ts
+/**
+* 字符串脱敏处理，将中间部分替换为指定字符
+*
+* @param str - 原字符串
+* @param start - 保留前几位，默认 3
+* @param end - 保留后几位，默认 4
+* @param mask - 脱敏字符，默认 `'*'`
+* @returns 脱敏后的字符串
+*
+* @example
+* ```ts
+* import maskString from '@tanwan/utils/maskString'
+* // 手机号脱敏
+* maskString('18812345678', 3, 4)
+* // '188****5678'
+*
+* // 身份证脱敏
+* maskString('510123199001011234', 6, 4)
+* // '510123********1234'
+* ```
+*/
+declare function maskString(str: string, start?: number, end?: number, mask?: string): string;
+export = maskString;

package/dist/maskString.d.ts

@@ -0,0 +1,25 @@
+//#region src/string/maskString/index.d.ts
+/**
+* 字符串脱敏处理，将中间部分替换为指定字符
+*
+* @param str - 原字符串
+* @param start - 保留前几位，默认 3
+* @param end - 保留后几位，默认 4
+* @param mask - 脱敏字符，默认 `'*'`
+* @returns 脱敏后的字符串
+*
+* @example
+* ```ts
+* import maskString from '@tanwan/utils/maskString'
+* // 手机号脱敏
+* maskString('18812345678', 3, 4)
+* // '188****5678'
+*
+* // 身份证脱敏
+* maskString('510123199001011234', 6, 4)
+* // '510123********1234'
+* ```
+*/
+declare function maskString(str: string, start?: number, end?: number, mask?: string): string;
+//#endregion
+export { maskString as default };

package/dist/maskString.js

@@ -0,0 +1,28 @@
+//#region src/string/maskString/index.ts
+/**
+* 字符串脱敏处理，将中间部分替换为指定字符
+*
+* @param str - 原字符串
+* @param start - 保留前几位，默认 3
+* @param end - 保留后几位，默认 4
+* @param mask - 脱敏字符，默认 `'*'`
+* @returns 脱敏后的字符串
+*
+* @example
+* ```ts
+* import maskString from '@tanwan/utils/maskString'
+* // 手机号脱敏
+* maskString('18812345678', 3, 4)
+* // '188****5678'
+*
+* // 身份证脱敏
+* maskString('510123199001011234', 6, 4)
+* // '510123********1234'
+* ```
+*/
+function maskString(str, start = 3, end = 4, mask = "*") {
+	if (str.length <= start + end) return str;
+	return str.slice(0, start) + mask.repeat(str.length - start - end) + str.slice(-end);
+}
+//#endregion
+export { maskString as default };

package/dist/memoize.cjs

@@ -0,0 +1,32 @@
+//#region src/function/memoize/index.ts
+/**
+* 缓存函数调用结果，相同参数直接返回缓存值
+*
+* 仅支持 `JSON.stringify` 可序列化参数。不适合复杂对象、大参数字符串或副作用函数。
+*
+* @param fn - 需要缓存结果的函数
+* @returns 带缓存能力的函数
+*
+* @example
+* ```ts
+* import memoize from '@tanwan/utils/memoize'
+* const factorial = memoize((n: number): number => {
+*   console.log('计算中')
+*   return n <= 1 ? 1 : n * factorial(n - 1)
+* })
+* factorial(5) // 输出多次"计算中"
+* factorial(5) // 直接返回缓存（无输出）
+* ```
+*/
+function memoize(fn) {
+	const cache = /* @__PURE__ */ new Map();
+	return ((...args) => {
+		const key = JSON.stringify(args);
+		if (cache.has(key)) return cache.get(key);
+		const result = fn(...args);
+		cache.set(key, result);
+		return result;
+	});
+}
+//#endregion
+module.exports = memoize;

package/dist/memoize.d.cts

@@ -0,0 +1,22 @@
+//#region src/function/memoize/index.d.ts
+/**
+* 缓存函数调用结果，相同参数直接返回缓存值
+*
+* 仅支持 `JSON.stringify` 可序列化参数。不适合复杂对象、大参数字符串或副作用函数。
+*
+* @param fn - 需要缓存结果的函数
+* @returns 带缓存能力的函数
+*
+* @example
+* ```ts
+* import memoize from '@tanwan/utils/memoize'
+* const factorial = memoize((n: number): number => {
+*   console.log('计算中')
+*   return n <= 1 ? 1 : n * factorial(n - 1)
+* })
+* factorial(5) // 输出多次"计算中"
+* factorial(5) // 直接返回缓存（无输出）
+* ```
+*/
+declare function memoize<T extends (...args: unknown[]) => unknown>(fn: T): T;
+export = memoize;

package/dist/memoize.d.ts

@@ -0,0 +1,23 @@
+//#region src/function/memoize/index.d.ts
+/**
+* 缓存函数调用结果，相同参数直接返回缓存值
+*
+* 仅支持 `JSON.stringify` 可序列化参数。不适合复杂对象、大参数字符串或副作用函数。
+*
+* @param fn - 需要缓存结果的函数
+* @returns 带缓存能力的函数
+*
+* @example
+* ```ts
+* import memoize from '@tanwan/utils/memoize'
+* const factorial = memoize((n: number): number => {
+*   console.log('计算中')
+*   return n <= 1 ? 1 : n * factorial(n - 1)
+* })
+* factorial(5) // 输出多次"计算中"
+* factorial(5) // 直接返回缓存（无输出）
+* ```
+*/
+declare function memoize<T extends (...args: unknown[]) => unknown>(fn: T): T;
+//#endregion
+export { memoize as default };

package/dist/memoize.js

@@ -0,0 +1,32 @@
+//#region src/function/memoize/index.ts
+/**
+* 缓存函数调用结果，相同参数直接返回缓存值
+*
+* 仅支持 `JSON.stringify` 可序列化参数。不适合复杂对象、大参数字符串或副作用函数。
+*
+* @param fn - 需要缓存结果的函数
+* @returns 带缓存能力的函数
+*
+* @example
+* ```ts
+* import memoize from '@tanwan/utils/memoize'
+* const factorial = memoize((n: number): number => {
+*   console.log('计算中')
+*   return n <= 1 ? 1 : n * factorial(n - 1)
+* })
+* factorial(5) // 输出多次"计算中"
+* factorial(5) // 直接返回缓存（无输出）
+* ```
+*/
+function memoize(fn) {
+	const cache = /* @__PURE__ */ new Map();
+	return ((...args) => {
+		const key = JSON.stringify(args);
+		if (cache.has(key)) return cache.get(key);
+		const result = fn(...args);
+		cache.set(key, result);
+		return result;
+	});
+}
+//#endregion
+export { memoize as default };

package/dist/off.cjs

@@ -0,0 +1,22 @@
+//#region src/dom/off/index.ts
+/**
+* 解绑元素事件
+*
+* @param el - DOM 元素
+* @param event - 事件名
+* @param handler - 事件处理函数（必须与绑定时的引用相同）
+* @param options - removeEventListener 选项
+*
+* @example
+* ```ts
+* import { on, off } from '@tanwan/utils'
+* const handler = () => console.log('clicked')
+* on(el, 'click', handler)
+* off(el, 'click', handler)
+* ```
+*/
+function off(el, event, handler, options) {
+	el.removeEventListener(event, handler, options);
+}
+//#endregion
+module.exports = off;

package/dist/off.d.cts

@@ -0,0 +1,19 @@
+//#region src/dom/off/index.d.ts
+/**
+* 解绑元素事件
+*
+* @param el - DOM 元素
+* @param event - 事件名
+* @param handler - 事件处理函数（必须与绑定时的引用相同）
+* @param options - removeEventListener 选项
+*
+* @example
+* ```ts
+* import { on, off } from '@tanwan/utils'
+* const handler = () => console.log('clicked')
+* on(el, 'click', handler)
+* off(el, 'click', handler)
+* ```
+*/
+declare function off(el: EventTarget, event: string, handler: EventListenerOrEventListenerObject, options?: EventListenerOptions): void;
+export = off;

package/dist/off.d.ts

@@ -0,0 +1,20 @@
+//#region src/dom/off/index.d.ts
+/**
+* 解绑元素事件
+*
+* @param el - DOM 元素
+* @param event - 事件名
+* @param handler - 事件处理函数（必须与绑定时的引用相同）
+* @param options - removeEventListener 选项
+*
+* @example
+* ```ts
+* import { on, off } from '@tanwan/utils'
+* const handler = () => console.log('clicked')
+* on(el, 'click', handler)
+* off(el, 'click', handler)
+* ```
+*/
+declare function off(el: EventTarget, event: string, handler: EventListenerOrEventListenerObject, options?: EventListenerOptions): void;
+//#endregion
+export { off as default };

package/dist/off.js

@@ -0,0 +1,22 @@
+//#region src/dom/off/index.ts
+/**
+* 解绑元素事件
+*
+* @param el - DOM 元素
+* @param event - 事件名
+* @param handler - 事件处理函数（必须与绑定时的引用相同）
+* @param options - removeEventListener 选项
+*
+* @example
+* ```ts
+* import { on, off } from '@tanwan/utils'
+* const handler = () => console.log('clicked')
+* on(el, 'click', handler)
+* off(el, 'click', handler)
+* ```
+*/
+function off(el, event, handler, options) {
+	el.removeEventListener(event, handler, options);
+}
+//#endregion
+export { off as default };

package/dist/{object/omit.d.cts → omit.d.cts}

@@ -14,5 +14,4 @@
 * ```
 */
 declare function omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
-export = omit;
-//# sourceMappingURL=omit.d.cts.map
+export = omit;

package/dist/{object/omit.d.ts → omit.d.ts}

@@ -15,5 +15,4 @@
 */
 declare function omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
 //#endregion
-export { omit as default };
-//# sourceMappingURL=omit.d.ts.map
+export { omit as default };

package/dist/{object/omit.js → omit.js}

@@ -21,5 +21,3 @@ function omit(obj, keys) {
 }
 //#endregion
 export { omit as default };
-
-//# sourceMappingURL=omit.js.map

package/dist/on.cjs

@@ -0,0 +1,21 @@
+//#region src/dom/on/index.ts
+/**
+* 给元素绑定事件
+*
+* @param el - DOM 元素
+* @param event - 事件名
+* @param handler - 事件处理函数
+* @param options - addEventListener 选项
+*
+* @example
+* ```ts
+* import on from '@tanwan/utils/on'
+* on(el, 'click', () => console.log('clicked'))
+* on(el, 'scroll', handler, { passive: true })
+* ```
+*/
+function on(el, event, handler, options) {
+	el.addEventListener(event, handler, options);
+}
+//#endregion
+module.exports = on;

package/dist/on.d.cts

@@ -0,0 +1,18 @@
+//#region src/dom/on/index.d.ts
+/**
+* 给元素绑定事件
+*
+* @param el - DOM 元素
+* @param event - 事件名
+* @param handler - 事件处理函数
+* @param options - addEventListener 选项
+*
+* @example
+* ```ts
+* import on from '@tanwan/utils/on'
+* on(el, 'click', () => console.log('clicked'))
+* on(el, 'scroll', handler, { passive: true })
+* ```
+*/
+declare function on(el: EventTarget, event: string, handler: EventListenerOrEventListenerObject, options?: AddEventListenerOptions): void;
+export = on;

package/dist/on.d.ts

@@ -0,0 +1,19 @@
+//#region src/dom/on/index.d.ts
+/**
+* 给元素绑定事件
+*
+* @param el - DOM 元素
+* @param event - 事件名
+* @param handler - 事件处理函数
+* @param options - addEventListener 选项
+*
+* @example
+* ```ts
+* import on from '@tanwan/utils/on'
+* on(el, 'click', () => console.log('clicked'))
+* on(el, 'scroll', handler, { passive: true })
+* ```
+*/
+declare function on(el: EventTarget, event: string, handler: EventListenerOrEventListenerObject, options?: AddEventListenerOptions): void;
+//#endregion
+export { on as default };

package/dist/on.js

@@ -0,0 +1,21 @@
+//#region src/dom/on/index.ts
+/**
+* 给元素绑定事件
+*
+* @param el - DOM 元素
+* @param event - 事件名
+* @param handler - 事件处理函数
+* @param options - addEventListener 选项
+*
+* @example
+* ```ts
+* import on from '@tanwan/utils/on'
+* on(el, 'click', () => console.log('clicked'))
+* on(el, 'scroll', handler, { passive: true })
+* ```
+*/
+function on(el, event, handler, options) {
+	el.addEventListener(event, handler, options);
+}
+//#endregion
+export { on as default };