@pawover/kit 0.4.2 → 0.6.0

package/packages/utils/dist/index.js

@@ -1,11 +1,11 @@
-import { n as StringUtil, r as TypeUtil, t as MathUtil } from "./math-B5PyWuKn.js";
+import { n as StringUtil, r as TypeUtil, t as MathUtil } from "./math-DRbCtLQH.js";
 //#region src/array/arrayUtil.ts
 /**
 * 数组工具类
 */
 var ArrayUtil = class {
-	static cast(candidate, checkEmpty = true) {
-		if (checkEmpty && (TypeUtil.isUndefined(candidate) || TypeUtil.isNull(candidate))) return [];
+	static cast(candidate, checkNullish = true) {
+		if (checkNullish && TypeUtil.isNullish(candidate)) return [];
 		return TypeUtil.isArray(candidate) ? [...candidate] : [candidate];
 	}
 	static first(initialList, fallback) {
@@ -68,8 +68,13 @@ var ArrayUtil = class {
 	* @returns 差集数组
 	* @example
 	* ```ts
+	* // 重载 1: 按元素本身比较（自动去重）
 	* ArrayUtil.difference([1, 2, 3], [2, 3, 4]); // [1]
+	* ArrayUtil.difference([1, 1, 2], [2]); // [1]，重复项会被去重
+	*
+	* // 重载 2: 按 match 结果比较（不去重，保留 initialList 原始重复项与顺序）
 	* ArrayUtil.difference([{ id: 1 }, { id: 2 }], [{ id: 2 }], (x) => x.id); // [{ id: 1 }]
+	* ArrayUtil.difference([{ id: 1 }, { id: 1 }], [{ id: 2 }], (x) => x.id); // [{ id: 1 }, { id: 1 }]
 	* ```
 	*/
 	static difference(initialList, diffList, match) {
@@ -138,6 +143,7 @@ var ArrayUtil = class {
 	* - 在给定的数组中，替换并移动符合匹配函数结果的项目
 	* - 只替换和移动第一个匹配项
 	* - 未匹配时，根据 `position` 在指定位置插入 `newItem`
+	* - ⚠️ `position` 为负数或非正整数（如 `-1`、`2.5`）时不生效，静默回退为 `push`（追加到末尾）
 	*
 	* @param initialList 初始数组
 	* @param newItem 替换项
@@ -150,6 +156,9 @@ var ArrayUtil = class {
 	* ArrayUtil.replaceMove([1, 2, 3, 4], 5, (n) => n === 2, 2); // [1, 3, 5, 4]
 	* ArrayUtil.replaceMove([1, 2, 3, 4], 5, (n) => n === 2, "start"); // [5, 1, 3, 4]
 	* ArrayUtil.replaceMove([1, 2, 3, 4], 5, (n) => n === 2); // [1, 3, 4, 5]
+	*
+	* // position 为负数 → 静默回退为 push
+	* ArrayUtil.replaceMove([1, 2, 3, 4], 5, (n) => n === 2, -1); // [1, 3, 4, 5]
 	* ```
 	*/
 	static replaceMove(initialList, newItem, match, position) {
@@ -206,31 +215,48 @@ var ArrayUtil = class {
 	/**
 	* 数组解压
 	* - `ArrayUtil.zip` 的反向操作
+	* - 默认按最长数组补齐 `undefined`
 	*
 	* @param arrayList 压缩后的数组
+	* @param options 配置项（`truncate` 为 `true` 时按最短数组截断）
 	* @returns 解压后的二维数组
 	* @example
 	* ```ts
 	* ArrayUtil.unzip([[1, "a"], [2, "b"]]); // [[1, 2], ["a", "b"]]
+	*
+	* // 补齐语义
+	* ArrayUtil.unzip([[1, 2], [3]]); // [[1, 3], [2, undefined]]
+	*
+	* // 截断语义
+	* ArrayUtil.unzip([[1, 2], [3]], { truncate: true }); // [[1, 3]]
 	* ```
 	*/
-	static unzip(arrayList) {
+	static unzip(arrayList, options) {
 		if (!TypeUtil.isArray(arrayList) || !arrayList.length) return [];
-		const out = new Array(arrayList.reduce((max, arr) => Math.max(max, arr.length), 0));
+		const length = options?.truncate ? arrayList.reduce((min, arr) => Math.min(min, arr.length), Infinity) : arrayList.reduce((max, arr) => Math.max(max, arr.length), 0);
+		const out = new Array(length);
 		let index = 0;
 		const get = (array) => array[index];
 		for (; index < out.length; index++) out[index] = Array.from(arrayList, get);
 		return out;
 	}
-	static zip(...arrays) {
-		return this.unzip(arrays);
+	static zip(...arraysAndOptions) {
+		const last = arraysAndOptions[arraysAndOptions.length - 1];
+		const options = last && !TypeUtil.isArray(last) ? last : void 0;
+		const arrays = options ? arraysAndOptions.slice(0, -1) : arraysAndOptions;
+		return this.unzip(arrays, options);
 	}
 	static zipToObject(keys, values) {
 		const result = {};
 		if (!TypeUtil.isArray(keys) || !keys.length) return result;
 		const getValue = TypeUtil.isFunction(values) ? values : TypeUtil.isArray(values) ? (_k, i) => values[i] : (_k, _i) => values;
 		return keys.reduce((acc, key, idx) => {
-			acc[key] = getValue(key, idx);
+			Object.defineProperty(acc, key, {
+				value: getValue(key, idx),
+				enumerable: true,
+				writable: true,
+				configurable: true
+			});
 			return acc;
 		}, result);
 	}
@@ -361,17 +387,19 @@ var CurrencyUtil = class {
 		XPF: "fr-PF"
 	};
 	static currencyFormatter(value, options) {
-		if (TypeUtil.isNull(value) || TypeUtil.isUndefined(value)) return null;
+		if (TypeUtil.isNullish(value)) return null;
 		const { currencySign, currencySignPosition, locales, currencyFormatOptions } = options;
-		let formatedValue = Number(value).toLocaleString(locales, currencyFormatOptions).replace(currencySign, "").trim();
+		const numberValue = Number(value);
+		if (Number.isNaN(numberValue)) return null;
+		let formatedValue = numberValue.toLocaleString(locales, currencyFormatOptions).replace(currencySign, "").trim();
 		if (currencySignPosition === "start") formatedValue = `${currencySign} ${formatedValue}`;
 		if (currencySignPosition === "end") formatedValue = `${formatedValue} ${currencySign}`;
 		return formatedValue;
 	}
 	static toRealValue(mathJsInstance, value, precision, stringMode) {
-		if (TypeUtil.isNull(value) || TypeUtil.isUndefined(value)) return null;
+		if (TypeUtil.isNullish(value)) return null;
 		const precisionValue = MathUtil.toDecimal(mathJsInstance, value, precision);
-		return stringMode ? precisionValue : Number(precisionValue);
+		return stringMode === false ? Number(precisionValue) : precisionValue;
 	}
 };
 //#endregion
@@ -528,9 +556,13 @@ var DateTimeUtil = class {
 	* ```
 	*/
 	static getTimeZone() {
-		const hour = 0 - (/* @__PURE__ */ new Date()).getTimezoneOffset() / this.MINUTE_PER_HOUR;
+		const offsetMinutes = 0 - (/* @__PURE__ */ new Date()).getTimezoneOffset();
+		const sign = offsetMinutes >= 0 ? "+" : "-";
+		const absMinutes = Math.abs(offsetMinutes);
+		const hours = Math.floor(absMinutes / this.MINUTE_PER_HOUR);
+		const minutes = absMinutes % this.MINUTE_PER_HOUR;
 		return {
-			UTC: "UTC" + (hour >= 0 ? "+" + hour : hour),
+			UTC: `UTC${sign}${hours}${minutes ? `:${String(minutes).padStart(2, "0")}` : ""}`,
 			timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone
 		};
 	}
@@ -539,6 +571,8 @@ var DateTimeUtil = class {
 //#region src/env/envUtil.ts
 /**
 * 环境检查工具类
+* - ⚠️ `isBrowser` / `isWebWorker` / `isReactNative` 基于静态字段判定，在**模块加载时**求值一次。
+*   SSR 场景下若在 Node 端 import（此时 `window` 未定义），结果会永久为 `false`，不会随运行时环境变化重算。
 */
 var EnvUtil = class {
 	static _isBrowser = typeof window !== "undefined" && TypeUtil.isFunction(window?.document?.createElement);
@@ -711,6 +745,7 @@ var EnvUtil = class {
 	* @param maxWidth - 平板最大宽度（默认 1200px）
 	* @param dpi - 标准 DPI 基准（默认 160）
 	* @returns 是否为平板设备
+	* - 宽度命中 `[minWidth, maxWidth]` 区间，或 CSS/DPI 折算尺寸落在 `[7, 13)` 英寸（排除 DPR=1 的 1920×1080 桌面）
 	* @example
 	* ```ts
 	* // 假设 window.innerWidth = 1000
@@ -728,7 +763,7 @@ var EnvUtil = class {
 			const widthInch = widthPx / DPI;
 			const heightInch = heightPx / DPI;
 			const screenInches = Math.sqrt(widthInch ** 2 + heightInch ** 2);
-			return isWithinWidthRange || screenInches >= 7;
+			return isWithinWidthRange || screenInches >= 7 && screenInches < 13;
 		} catch {
 			return isWithinWidthRange;
 		}
@@ -766,7 +801,10 @@ var FunctionUtil = class {
 					Object.getOwnPropertyNames(err).forEach((key) => {
 						if (!(key in parsedError)) parsedError[key] = err[key];
 					});
-				} else Object.assign(parsedError, err);
+				} else {
+					Object.assign(parsedError, err);
+					if (!parsedError.message) parsedError.message = String(err);
+				}
 				Object.assign(parsedError, errorExt);
 				return [parsedError, void 0];
 			}
@@ -1294,7 +1332,12 @@ var ObjectUtil = class {
 		if (!TypeUtil.isPlainObject(plainObject)) return defaultResult;
 		return this.entries(plainObject).reduce((acc, [key, value]) => {
 			const [newKey, newValue] = toEntry(key, value);
-			acc[newKey] = newValue;
+			Object.defineProperty(acc, newKey, {
+				value: newValue,
+				enumerable: true,
+				writable: true,
+				configurable: true
+			});
 			return acc;
 		}, defaultResult);
 	}
@@ -1303,7 +1346,12 @@ var ObjectUtil = class {
 		if (!TypeUtil.isPlainObject(obj)) return result;
 		if (!TypeUtil.isArray(keys)) return obj;
 		return keys.reduce((acc, key) => {
-			if (key in obj) acc[key] = obj[key];
+			if (key in obj) Object.defineProperty(acc, key, {
+				value: obj[key],
+				enumerable: true,
+				writable: true,
+				configurable: true
+			});
 			return acc;
 		}, result);
 	}
@@ -1313,7 +1361,12 @@ var ObjectUtil = class {
 		if (!TypeUtil.isArray(keys)) return obj;
 		const keysToOmit = new Set(keys);
 		return Object.keys(obj).reduce((acc, key) => {
-			if (!keysToOmit.has(key)) acc[key] = obj[key];
+			if (!keysToOmit.has(key)) Object.defineProperty(acc, key, {
+				value: obj[key],
+				enumerable: true,
+				writable: true,
+				configurable: true
+			});
 			return acc;
 		}, result);
 	}
@@ -1427,7 +1480,7 @@ function postImpl$3(row, callback, options) {
 			parents: [...options.parents, row],
 			depth: options.depth + 1
 		};
-		newChildren = children.map((c) => preImpl$3(c, callback, nextLevelOptions)).filter((c) => !!c);
+		newChildren = children.map((c) => postImpl$3(c, callback, nextLevelOptions)).filter((c) => !!c);
 	}
 	if (!callback(row, options)) return;
 	return {
@@ -1692,47 +1745,68 @@ const treeMapStrategies = {
 //#region src/tree/treeUtil.ts
 /**
 * 树结构工具类
+*
+* 引用策略约定：
+* - 转换类方法（`rowsToTree` / `treeToRows` / `filter` / `map`）：不突变输入；输出的每个节点均为**新对象引用**（来源节点的浅拷贝，仅自有可枚举属性；非枚举属性、原型链、getter 及深层嵌套对象不保证）。
+* - 查询类方法（`find` / `forEach`）：按查询语义直接使用**原对象引用**。
 */
 var TreeUtil = class {
 	/**
 	* 行结构 转 树结构
 	* - 将平铺的数组转换为树形结构
+	* - 返回的树结构与输入行无共享节点（新对象引用），输入行不会被突变
+	* - 重复 id 的行只取首次出现；仅叶子/缺失父节点的 id 会作为根节点，且每个根节点只输出一次
 	*
 	* @param rows 行数据数组
 	* @param options 配置项
-	* @returns 树结构数组
+	* @returns 树结构数组（所有节点均包含 children 数组）
 	* @example
 	* ```ts
 	* const rows = [
 	*   { id: 1, parentId: null },
 	*   { id: 2, parentId: 1 },
 	* ];
-	* TreeUtil.rowsToTree(rows); // [{ id: 1, parentId: null, children: [{ id: 2, parentId: 1 }] }]
+	* TreeUtil.rowsToTree(rows); // [{ id: 1, parentId: null, children: [{ id: 2, parentId: 1, children: [] }] }]
 	* ```
 	*/
 	static rowsToTree(rows, options) {
 		const { parentIdKey = "parentId", rowKey = "id", childrenKey = "children" } = options || {};
 		const result = [];
 		const map = /* @__PURE__ */ new Map();
+		const processedIds = /* @__PURE__ */ new Set();
 		for (const row of rows) {
 			const id = row[rowKey];
-			if (!map.get(id)) map.set(id, row);
+			if (!map.get(id)) map.set(id, { ...row });
 		}
 		for (const row of rows) {
+			const id = row[rowKey];
+			if (processedIds.has(id)) continue;
+			processedIds.add(id);
 			const parentId = row[parentIdKey];
-			const parent = map.get(parentId);
-			if (!parent || !parentId) {
-				result.push(row);
+			const node = map.get(id);
+			if (!node) continue;
+			if (TypeUtil.isNullish(parentId) || parentId === id || !map.has(parentId)) {
+				result.push(node);
 				continue;
 			}
+			const parent = map.get(parentId);
 			const siblings = parent[childrenKey];
-			if (TypeUtil.isNull(siblings) || TypeUtil.isUndefined(siblings)) parent[childrenKey] = [row];
-			else if (Array.isArray(siblings)) siblings.push(row);
+			if (TypeUtil.isNullish(siblings)) parent[childrenKey] = [node];
+			else if (Array.isArray(siblings)) siblings.push(node);
 			else {
 				const message = `The key "${childrenKey.toString()}" in parent item is not an array.`;
 				throw new Error(message);
 			}
 		}
+		for (const root of result) this.forEach(root, (node) => {
+			const record = node;
+			const children = record[childrenKey];
+			if (TypeUtil.isNullish(children)) record[childrenKey] = [];
+			else if (!Array.isArray(children)) {
+				const message = `The key "${childrenKey.toString()}" in parent item is not an array.`;
+				throw new Error(message);
+			}
+		}, { childrenKey });
 		return result;
 	}
 	/**
@@ -1923,25 +1997,37 @@ var ValidateUtil = class {
 	}
 	static _uscc = /^[0-9A-HJ-NPQRTUWXY]{2}\d{6}[0-9A-HJ-NPQRTUWXY]{10}$/;
 	/**
-	* 验证是否为统一社会信用代码
+	* 验证是否为统一社会信用代码（USCC / USCI / USCCS）
+	* - 固定 18 位：1 位登记管理部门码 + 1 位机构类别码 + 6 位行政区划码 + 9 位主体标识码 + 1 位校验码
+	* - 字符集：数字 0-9 + 大写英文字母（排除 I、O、Z、S、V，防视觉混淆）
+	* - 第 1-2 位允许字母（如登记管理部门码 `A`，代表"其他"），第 3-8 位行政区划码为纯数字
+	*
+	* @param input 待校验字符串
+	* @returns 是否为合法格式的统一社会信用代码
 	* @example
 	* ```ts
 	* ValidateUtil.isUSCC("91350100M000100Y43"); // true
+	* ValidateUtil.isUSCC("A1350100M000100Y43"); // true (A 开头"其他"部门码)
 	* ```
 	*/
 	static isUSCC(input) {
 		return this._uscc.test(input.toString());
 	}
-	static _usccs = /^[0-9A-HJ-NPQRTUWXY]{2}\d{6}[0-9A-HJ-NPQRTUWXY]{10}$/;
 	/**
-	* 验证是否为统一社会信用代码 - 15位/18位/20位数字/字母
+	* 验证是否为统一社会信用代码（同 `isUSCC`）
+	* - USCC / USCI / USCCS 均指统一社会信用代码，固定 18 位
+	* - 15 位旧税务登记号在 2015 年"三证合一"前使用，现已作废，视为无效
+	*
+	* @param input 待校验字符串
+	* @returns 是否为合法代码
 	* @example
 	* ```ts
-	* ValidateUtil.isUSCCS("91350100M000100Y43"); // true
+	* ValidateUtil.isUSCCS("91350100M000100Y43"); // true (18位)
+	* ValidateUtil.isUSCCS("91350100M000100"); // false (15位旧号，已作废)
 	* ```
 	*/
 	static isUSCCS(input) {
-		return this._usccs.test(input.toString());
+		return this.isUSCC(input);
 	}
 	static _dirPathWindows = /^[a-z]:\\(?:\w+\\?)*$/i;
 	/**
@@ -2023,6 +2109,7 @@ var ValidateUtil = class {
 	static _chineseId = /^\d{6}((((((19|20)\d{2})(0[13-9]|1[012])(0[1-9]|[12]\d|30))|(((19|20)\d{2})(0[13578]|1[02])31)|((19|20)\d{2})02(0[1-9]|1\d|2[0-8])|((((19|20)([13579][26]|[2468][048]|0[48]))|(2000))0229))\d{3})|((((\d{2})(0[13-9]|1[012])(0[1-9]|[12]\d|30))|((\d{2})(0[13578]|1[02])31)|((\d{2})02(0[1-9]|1\d|2[0-8]))|(([13579][26]|[2468][048]|0[048])0229))\d{2}))([\dX])$/i;
 	/**
 	* 验证是否为中国身份证号
+	* - ⚠️ 仅校验 18 位格式（含生日合法性），**不验证第 18 位校验位**，伪造码可通过校验
 	* @example
 	* ```ts
 	* ValidateUtil.isChineseID("11010519491231002X"); // true
@@ -2031,7 +2118,7 @@ var ValidateUtil = class {
 	static isChineseID(input) {
 		return this._chineseId.test(input.toString());
 	}
-	static _chineseProvince = /^安徽|澳门|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|河南|黑龙江|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|台湾|天津|西藏|香港|新疆|云南|浙江$/;
+	static _chineseProvince = /^(?:安徽|澳门|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|河南|黑龙江|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|台湾|天津|西藏|香港|新疆|云南|浙江)$/;
 	/**
 	* 验证是否为中国省份
 	* @example
@@ -2042,7 +2129,7 @@ var ValidateUtil = class {
 	static isChineseProvince(input) {
 		return this._chineseProvince.test(input.toString());
 	}
-	static _chineseNation = /^汉族|蒙古族|回族|藏族|维吾尔族|苗族|彝族|壮族|布依族|朝鲜族|满族|侗族|瑶族|白族|土家族|哈尼族|哈萨克族|傣族|黎族|傈僳族|佤族|畲族|高山族|拉祜族|水族|东乡族|纳西族|景颇族|柯尔克孜族|土族|达斡尔族|仫佬族|羌族|布朗族|撒拉族|毛南族|仡佬族|锡伯族|阿昌族|普米族|塔吉克族|怒族|乌孜别克族|俄罗斯族|鄂温克族|德昂族|保安族|裕固族|京族|塔塔尔族|独龙族|鄂伦春族|赫哲族|门巴族|珞巴族|基诺族|其它未识别民族|外国人入中国籍$/;
+	static _chineseNation = /^(?:汉族|蒙古族|回族|藏族|维吾尔族|苗族|彝族|壮族|布依族|朝鲜族|满族|侗族|瑶族|白族|土家族|哈尼族|哈萨克族|傣族|黎族|傈僳族|佤族|畲族|高山族|拉祜族|水族|东乡族|纳西族|景颇族|柯尔克孜族|土族|达斡尔族|仫佬族|羌族|布朗族|撒拉族|毛南族|仡佬族|锡伯族|阿昌族|普米族|塔吉克族|怒族|乌孜别克族|俄罗斯族|鄂温克族|德昂族|保安族|裕固族|京族|塔塔尔族|独龙族|鄂伦春族|赫哲族|门巴族|珞巴族|基诺族|其它未识别民族|外国人入中国籍)$/;
 	/**
 	* 验证是否为中华民族
 	* @example