@tanwan/utils 1.0.0 → 1.2.0

package/dist/treeFind.js

@@ -0,0 +1,34 @@
+//#region src/tree/treeFind/index.ts
+/**
+* 在树结构中查找节点（深度优先）
+*
+* @param tree - 树结构数组
+* @param predicate - 匹配函数
+* @param options - 配置项
+* @param options.children - 子节点属性名，默认 `'children'`
+* @returns 第一个匹配的节点，未找到返回 `undefined`
+*
+* @example
+* ```ts
+* import treeFind from '@tanwan/utils/treeFind'
+* const tree = [
+*   { id: 1, children: [{ id: 2 }] },
+*   { id: 3, children: [] },
+* ]
+* treeFind(tree, (node) => node.id === 2)
+* // { id: 2 }
+* ```
+*/
+function treeFind(tree, predicate, options = {}) {
+	const { children = "children" } = options;
+	for (const node of tree) {
+		if (predicate(node)) return node;
+		const childNodes = node[children];
+		if (Array.isArray(childNodes)) {
+			const found = treeFind(childNodes, predicate, options);
+			if (found) return found;
+		}
+	}
+}
+//#endregion
+export { treeFind as default };

package/dist/treeToList.cjs

@@ -0,0 +1,33 @@
+//#region src/tree/treeToList/index.ts
+/**
+* 将树结构拍平为数组（BFS 广度优先）
+*
+* @param tree - 树结构数组
+* @param options - 配置项
+* @param options.children - 子节点属性名，默认 `'children'`
+* @returns 扁平数组（不含 children 属性）
+*
+* @example
+* ```ts
+* import treeToList from '@tanwan/utils/treeToList'
+* const tree = [
+*   { id: 1, children: [{ id: 2, children: [] }] },
+*   { id: 3, children: [] },
+* ]
+* treeToList(tree)
+* // [{ id: 1 }, { id: 3 }, { id: 2 }]
+* ```
+*/
+function treeToList(tree, options = {}) {
+	const { children = "children" } = options;
+	const result = [];
+	const queue = [...tree];
+	while (queue.length) {
+		const { [children]: childNodes, ...rest } = queue.shift();
+		result.push(rest);
+		if (Array.isArray(childNodes)) queue.push(...childNodes);
+	}
+	return result;
+}
+//#endregion
+module.exports = treeToList;

package/dist/treeToList.d.cts

@@ -0,0 +1,24 @@
+//#region src/tree/treeToList/index.d.ts
+/**
+* 将树结构拍平为数组（BFS 广度优先）
+*
+* @param tree - 树结构数组
+* @param options - 配置项
+* @param options.children - 子节点属性名，默认 `'children'`
+* @returns 扁平数组（不含 children 属性）
+*
+* @example
+* ```ts
+* import treeToList from '@tanwan/utils/treeToList'
+* const tree = [
+*   { id: 1, children: [{ id: 2, children: [] }] },
+*   { id: 3, children: [] },
+* ]
+* treeToList(tree)
+* // [{ id: 1 }, { id: 3 }, { id: 2 }]
+* ```
+*/
+declare function treeToList<T extends Record<string, unknown>>(tree: T[], options?: {
+  children?: string;
+}): Omit<T, "children">[];
+export = treeToList;

package/dist/treeToList.d.ts

@@ -0,0 +1,25 @@
+//#region src/tree/treeToList/index.d.ts
+/**
+* 将树结构拍平为数组（BFS 广度优先）
+*
+* @param tree - 树结构数组
+* @param options - 配置项
+* @param options.children - 子节点属性名，默认 `'children'`
+* @returns 扁平数组（不含 children 属性）
+*
+* @example
+* ```ts
+* import treeToList from '@tanwan/utils/treeToList'
+* const tree = [
+*   { id: 1, children: [{ id: 2, children: [] }] },
+*   { id: 3, children: [] },
+* ]
+* treeToList(tree)
+* // [{ id: 1 }, { id: 3 }, { id: 2 }]
+* ```
+*/
+declare function treeToList<T extends Record<string, unknown>>(tree: T[], options?: {
+  children?: string;
+}): Omit<T, "children">[];
+//#endregion
+export { treeToList as default };

package/dist/treeToList.js

@@ -0,0 +1,33 @@
+//#region src/tree/treeToList/index.ts
+/**
+* 将树结构拍平为数组（BFS 广度优先）
+*
+* @param tree - 树结构数组
+* @param options - 配置项
+* @param options.children - 子节点属性名，默认 `'children'`
+* @returns 扁平数组（不含 children 属性）
+*
+* @example
+* ```ts
+* import treeToList from '@tanwan/utils/treeToList'
+* const tree = [
+*   { id: 1, children: [{ id: 2, children: [] }] },
+*   { id: 3, children: [] },
+* ]
+* treeToList(tree)
+* // [{ id: 1 }, { id: 3 }, { id: 2 }]
+* ```
+*/
+function treeToList(tree, options = {}) {
+	const { children = "children" } = options;
+	const result = [];
+	const queue = [...tree];
+	while (queue.length) {
+		const { [children]: childNodes, ...rest } = queue.shift();
+		result.push(rest);
+		if (Array.isArray(childNodes)) queue.push(...childNodes);
+	}
+	return result;
+}
+//#endregion
+export { treeToList as default };

package/dist/truncate.cjs

@@ -0,0 +1,23 @@
+//#region src/string/truncate/index.ts
+/**
+* 截断字符串并添加省略号
+*
+* @param str - 原字符串
+* @param maxLength - 最大长度（含省略号）
+* @param suffix - 省略号后缀，默认 `'…'`
+* @returns 截断后的字符串
+*
+* @example
+* ```ts
+* import truncate from '@tanwan/utils/truncate'
+* truncate('Hello World', 8)        // 'Hello W…'
+* truncate('Hello', 10)             // 'Hello'（不截断）
+* truncate('Hello World', 8, '...') // 'Hello...'
+* ```
+*/
+function truncate(str, maxLength, suffix = "…") {
+	if (str.length <= maxLength) return str;
+	return str.slice(0, maxLength - suffix.length) + suffix;
+}
+//#endregion
+module.exports = truncate;

package/dist/truncate.d.cts

@@ -0,0 +1,19 @@
+//#region src/string/truncate/index.d.ts
+/**
+* 截断字符串并添加省略号
+*
+* @param str - 原字符串
+* @param maxLength - 最大长度（含省略号）
+* @param suffix - 省略号后缀，默认 `'…'`
+* @returns 截断后的字符串
+*
+* @example
+* ```ts
+* import truncate from '@tanwan/utils/truncate'
+* truncate('Hello World', 8)        // 'Hello W…'
+* truncate('Hello', 10)             // 'Hello'（不截断）
+* truncate('Hello World', 8, '...') // 'Hello...'
+* ```
+*/
+declare function truncate(str: string, maxLength: number, suffix?: string): string;
+export = truncate;

package/dist/truncate.d.ts

@@ -0,0 +1,20 @@
+//#region src/string/truncate/index.d.ts
+/**
+* 截断字符串并添加省略号
+*
+* @param str - 原字符串
+* @param maxLength - 最大长度（含省略号）
+* @param suffix - 省略号后缀，默认 `'…'`
+* @returns 截断后的字符串
+*
+* @example
+* ```ts
+* import truncate from '@tanwan/utils/truncate'
+* truncate('Hello World', 8)        // 'Hello W…'
+* truncate('Hello', 10)             // 'Hello'（不截断）
+* truncate('Hello World', 8, '...') // 'Hello...'
+* ```
+*/
+declare function truncate(str: string, maxLength: number, suffix?: string): string;
+//#endregion
+export { truncate as default };

package/dist/truncate.js

@@ -0,0 +1,23 @@
+//#region src/string/truncate/index.ts
+/**
+* 截断字符串并添加省略号
+*
+* @param str - 原字符串
+* @param maxLength - 最大长度（含省略号）
+* @param suffix - 省略号后缀，默认 `'…'`
+* @returns 截断后的字符串
+*
+* @example
+* ```ts
+* import truncate from '@tanwan/utils/truncate'
+* truncate('Hello World', 8)        // 'Hello W…'
+* truncate('Hello', 10)             // 'Hello'（不截断）
+* truncate('Hello World', 8, '...') // 'Hello...'
+* ```
+*/
+function truncate(str, maxLength, suffix = "…") {
+	if (str.length <= maxLength) return str;
+	return str.slice(0, maxLength - suffix.length) + suffix;
+}
+//#endregion
+export { truncate as default };

package/dist/uniqBy.cjs

@@ -0,0 +1,30 @@
+//#region src/array/uniqBy/index.ts
+/**
+* 按指定 key 或迭代函数去重（保留第一个出现的元素）
+*
+* @param arr - 待去重数组
+* @param iteratee - 去重依据：属性名或返回唯一标识的函数
+* @returns 去重后的新数组
+*
+* @example
+* ```ts
+* import uniqBy from '@tanwan/utils/uniqBy'
+* uniqBy([{ id: 1, name: 'a' }, { id: 2, name: 'b' }, { id: 1, name: 'c' }], 'id')
+* // [{ id: 1, name: 'a' }, { id: 2, name: 'b' }]
+*
+* uniqBy([1.1, 2.2, 1.3], Math.floor)
+* // [1.1, 2.2]
+* ```
+*/
+function uniqBy(arr, iteratee) {
+	const seen = /* @__PURE__ */ new Set();
+	const getValue = typeof iteratee === "function" ? iteratee : (item) => item[iteratee];
+	return arr.filter((item) => {
+		const value = getValue(item);
+		if (seen.has(value)) return false;
+		seen.add(value);
+		return true;
+	});
+}
+//#endregion
+module.exports = uniqBy;

package/dist/uniqBy.d.cts

@@ -0,0 +1,20 @@
+//#region src/array/uniqBy/index.d.ts
+/**
+* 按指定 key 或迭代函数去重（保留第一个出现的元素）
+*
+* @param arr - 待去重数组
+* @param iteratee - 去重依据：属性名或返回唯一标识的函数
+* @returns 去重后的新数组
+*
+* @example
+* ```ts
+* import uniqBy from '@tanwan/utils/uniqBy'
+* uniqBy([{ id: 1, name: 'a' }, { id: 2, name: 'b' }, { id: 1, name: 'c' }], 'id')
+* // [{ id: 1, name: 'a' }, { id: 2, name: 'b' }]
+*
+* uniqBy([1.1, 2.2, 1.3], Math.floor)
+* // [1.1, 2.2]
+* ```
+*/
+declare function uniqBy<T>(arr: T[], iteratee: keyof T | ((item: T) => string | number)): T[];
+export = uniqBy;

package/dist/uniqBy.d.ts

@@ -0,0 +1,21 @@
+//#region src/array/uniqBy/index.d.ts
+/**
+* 按指定 key 或迭代函数去重（保留第一个出现的元素）
+*
+* @param arr - 待去重数组
+* @param iteratee - 去重依据：属性名或返回唯一标识的函数
+* @returns 去重后的新数组
+*
+* @example
+* ```ts
+* import uniqBy from '@tanwan/utils/uniqBy'
+* uniqBy([{ id: 1, name: 'a' }, { id: 2, name: 'b' }, { id: 1, name: 'c' }], 'id')
+* // [{ id: 1, name: 'a' }, { id: 2, name: 'b' }]
+*
+* uniqBy([1.1, 2.2, 1.3], Math.floor)
+* // [1.1, 2.2]
+* ```
+*/
+declare function uniqBy<T>(arr: T[], iteratee: keyof T | ((item: T) => string | number)): T[];
+//#endregion
+export { uniqBy as default };

package/dist/uniqBy.js

@@ -0,0 +1,30 @@
+//#region src/array/uniqBy/index.ts
+/**
+* 按指定 key 或迭代函数去重（保留第一个出现的元素）
+*
+* @param arr - 待去重数组
+* @param iteratee - 去重依据：属性名或返回唯一标识的函数
+* @returns 去重后的新数组
+*
+* @example
+* ```ts
+* import uniqBy from '@tanwan/utils/uniqBy'
+* uniqBy([{ id: 1, name: 'a' }, { id: 2, name: 'b' }, { id: 1, name: 'c' }], 'id')
+* // [{ id: 1, name: 'a' }, { id: 2, name: 'b' }]
+*
+* uniqBy([1.1, 2.2, 1.3], Math.floor)
+* // [1.1, 2.2]
+* ```
+*/
+function uniqBy(arr, iteratee) {
+	const seen = /* @__PURE__ */ new Set();
+	const getValue = typeof iteratee === "function" ? iteratee : (item) => item[iteratee];
+	return arr.filter((item) => {
+		const value = getValue(item);
+		if (seen.has(value)) return false;
+		seen.add(value);
+		return true;
+	});
+}
+//#endregion
+export { uniqBy as default };

package/dist/{array/unique.cjs → unique.cjs}

@@ -3,7 +3,7 @@
 * 数组去重
 * @example
 * ```ts
-* import unique from '@tw/utils/unique'
+* import unique from '@tanwan/utils/unique'
 * unique([1, 2, 2, 3]) // [1, 2, 3]
 * unique(['a', 'b', 'a']) // ['a', 'b']
 * ```

package/dist/{array/unique.d.cts → unique.d.cts}

@@ -3,11 +3,10 @@
 * 数组去重
 * @example
 * ```ts
-* import unique from '@tw/utils/unique'
+* import unique from '@tanwan/utils/unique'
 * unique([1, 2, 2, 3]) // [1, 2, 3]
 * unique(['a', 'b', 'a']) // ['a', 'b']
 * ```
 */
 declare function unique<T>(arr: T[]): T[];
-export = unique;
-//# sourceMappingURL=unique.d.cts.map
+export = unique;

package/dist/{array/unique.d.ts → unique.d.ts}

@@ -3,12 +3,11 @@
 * 数组去重
 * @example
 * ```ts
-* import unique from '@tw/utils/unique'
+* import unique from '@tanwan/utils/unique'
 * unique([1, 2, 2, 3]) // [1, 2, 3]
 * unique(['a', 'b', 'a']) // ['a', 'b']
 * ```
 */
 declare function unique<T>(arr: T[]): T[];
 //#endregion
-export { unique as default };
-//# sourceMappingURL=unique.d.ts.map
+export { unique as default };

package/dist/{array/unique.js → unique.js}

@@ -3,7 +3,7 @@
 * 数组去重
 * @example
 * ```ts
-* import unique from '@tw/utils/unique'
+* import unique from '@tanwan/utils/unique'
 * unique([1, 2, 2, 3]) // [1, 2, 3]
 * unique(['a', 'b', 'a']) // ['a', 'b']
 * ```
@@ -13,5 +13,3 @@ function unique(arr) {
 }
 //#endregion
 export { unique as default };
-
-//# sourceMappingURL=unique.js.map

package/dist/uuid.cjs

@@ -0,0 +1,23 @@
+//#region src/string/uuid/index.ts
+/**
+* 生成 UUID v4
+*
+* 优先使用 `crypto.randomUUID()`，不支持时自动降级为手动生成方案
+*
+* @returns UUID v4 格式字符串，例如 `'550e8400-e29b-41d4-a716-446655440000'`
+*
+* @example
+* ```ts
+* import uuid from '@tanwan/utils/uuid'
+* uuid() // 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
+* ```
+*/
+function uuid() {
+	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+		const r = Math.random() * 16 | 0;
+		return (c === "x" ? r : r & 3 | 8).toString(16);
+	});
+}
+//#endregion
+module.exports = uuid;

package/dist/uuid.d.cts

@@ -0,0 +1,16 @@
+//#region src/string/uuid/index.d.ts
+/**
+* 生成 UUID v4
+*
+* 优先使用 `crypto.randomUUID()`，不支持时自动降级为手动生成方案
+*
+* @returns UUID v4 格式字符串，例如 `'550e8400-e29b-41d4-a716-446655440000'`
+*
+* @example
+* ```ts
+* import uuid from '@tanwan/utils/uuid'
+* uuid() // 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
+* ```
+*/
+declare function uuid(): string;
+export = uuid;

package/dist/uuid.d.ts

@@ -0,0 +1,17 @@
+//#region src/string/uuid/index.d.ts
+/**
+* 生成 UUID v4
+*
+* 优先使用 `crypto.randomUUID()`，不支持时自动降级为手动生成方案
+*
+* @returns UUID v4 格式字符串，例如 `'550e8400-e29b-41d4-a716-446655440000'`
+*
+* @example
+* ```ts
+* import uuid from '@tanwan/utils/uuid'
+* uuid() // 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
+* ```
+*/
+declare function uuid(): string;
+//#endregion
+export { uuid as default };

package/dist/uuid.js

@@ -0,0 +1,23 @@
+//#region src/string/uuid/index.ts
+/**
+* 生成 UUID v4
+*
+* 优先使用 `crypto.randomUUID()`，不支持时自动降级为手动生成方案
+*
+* @returns UUID v4 格式字符串，例如 `'550e8400-e29b-41d4-a716-446655440000'`
+*
+* @example
+* ```ts
+* import uuid from '@tanwan/utils/uuid'
+* uuid() // 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
+* ```
+*/
+function uuid() {
+	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+		const r = Math.random() * 16 | 0;
+		return (c === "x" ? r : r & 3 | 8).toString(16);
+	});
+}
+//#endregion
+export { uuid as default };

package/dist/validateEmail.cjs

@@ -0,0 +1,19 @@
+//#region src/business/validateEmail/index.ts
+/**
+* 校验邮箱格式
+*
+* @param email - 待校验的邮箱
+* @returns 是否为合法邮箱
+*
+* @example
+* ```ts
+* import validateEmail from '@tanwan/utils/validateEmail'
+* validateEmail('user@example.com')  // true
+* validateEmail('invalid-email')     // false
+* ```
+*/
+function validateEmail(email) {
+	return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+//#endregion
+module.exports = validateEmail;

package/dist/validateEmail.d.cts

@@ -0,0 +1,16 @@
+//#region src/business/validateEmail/index.d.ts
+/**
+* 校验邮箱格式
+*
+* @param email - 待校验的邮箱
+* @returns 是否为合法邮箱
+*
+* @example
+* ```ts
+* import validateEmail from '@tanwan/utils/validateEmail'
+* validateEmail('user@example.com')  // true
+* validateEmail('invalid-email')     // false
+* ```
+*/
+declare function validateEmail(email: string): boolean;
+export = validateEmail;

package/dist/validateEmail.d.ts

@@ -0,0 +1,17 @@
+//#region src/business/validateEmail/index.d.ts
+/**
+* 校验邮箱格式
+*
+* @param email - 待校验的邮箱
+* @returns 是否为合法邮箱
+*
+* @example
+* ```ts
+* import validateEmail from '@tanwan/utils/validateEmail'
+* validateEmail('user@example.com')  // true
+* validateEmail('invalid-email')     // false
+* ```
+*/
+declare function validateEmail(email: string): boolean;
+//#endregion
+export { validateEmail as default };

package/dist/validateEmail.js

@@ -0,0 +1,19 @@
+//#region src/business/validateEmail/index.ts
+/**
+* 校验邮箱格式
+*
+* @param email - 待校验的邮箱
+* @returns 是否为合法邮箱
+*
+* @example
+* ```ts
+* import validateEmail from '@tanwan/utils/validateEmail'
+* validateEmail('user@example.com')  // true
+* validateEmail('invalid-email')     // false
+* ```
+*/
+function validateEmail(email) {
+	return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+//#endregion
+export { validateEmail as default };

package/dist/validateIdCard.cjs

@@ -0,0 +1,62 @@
+//#region src/business/validateIdCard/index.ts
+/**
+* 校验身份证号码格式（含校验位算法）
+*
+* @param idCard - 18 位身份证号
+* @returns 是否为合法身份证号
+*
+* @example
+* ```ts
+* import validateIdCard from '@tanwan/utils/validateIdCard'
+* validateIdCard('110101199001011234')  // true（示例号，实际需按算法校验）
+* ```
+*/
+function validateIdCard(idCard) {
+	if (!/^\d{17}[\dXx]$/.test(idCard)) return false;
+	const provinceCode = idCard.substring(0, 2);
+	if (Number.parseInt(provinceCode) < 11 || Number.parseInt(provinceCode) > 82) return false;
+	const birth = idCard.substring(6, 14);
+	const year = Number.parseInt(birth.substring(0, 4));
+	const month = Number.parseInt(birth.substring(4, 6));
+	const day = Number.parseInt(birth.substring(6, 8));
+	if (year < 1900 || year > 2100) return false;
+	if (month < 1 || month > 12) return false;
+	if (day < 1 || day > 31) return false;
+	const weights = [
+		7,
+		9,
+		10,
+		5,
+		8,
+		4,
+		2,
+		1,
+		6,
+		3,
+		7,
+		9,
+		10,
+		5,
+		8,
+		4,
+		2
+	];
+	const checkCodes = [
+		"1",
+		"0",
+		"X",
+		"9",
+		"8",
+		"7",
+		"6",
+		"5",
+		"4",
+		"3",
+		"2"
+	];
+	let sum = 0;
+	for (let i = 0; i < 17; i++) sum += Number.parseInt(idCard[i]) * weights[i];
+	return checkCodes[sum % 11] === idCard[17].toUpperCase();
+}
+//#endregion
+module.exports = validateIdCard;

package/dist/validateIdCard.d.cts

@@ -0,0 +1,15 @@
+//#region src/business/validateIdCard/index.d.ts
+/**
+* 校验身份证号码格式（含校验位算法）
+*
+* @param idCard - 18 位身份证号
+* @returns 是否为合法身份证号
+*
+* @example
+* ```ts
+* import validateIdCard from '@tanwan/utils/validateIdCard'
+* validateIdCard('110101199001011234')  // true（示例号，实际需按算法校验）
+* ```
+*/
+declare function validateIdCard(idCard: string): boolean;
+export = validateIdCard;

package/dist/validateIdCard.d.ts

@@ -0,0 +1,16 @@
+//#region src/business/validateIdCard/index.d.ts
+/**
+* 校验身份证号码格式（含校验位算法）
+*
+* @param idCard - 18 位身份证号
+* @returns 是否为合法身份证号
+*
+* @example
+* ```ts
+* import validateIdCard from '@tanwan/utils/validateIdCard'
+* validateIdCard('110101199001011234')  // true（示例号，实际需按算法校验）
+* ```
+*/
+declare function validateIdCard(idCard: string): boolean;
+//#endregion
+export { validateIdCard as default };