befly-shared 1.3.0 → 1.3.2

package/package.json

@@ -1,13 +1,13 @@
 {
     "name": "befly-shared",
-    "version": "1.3.0",
+    "version": "1.3.2",
     "private": false,
     "description": "Befly 纯函数与纯常量共享包（不包含 Node/浏览器特定实现）",
     "license": "Apache-2.0",
     "author": "chensuiyi <bimostyle@qq.com>",
     "files": [
         "package.json",
-        "utils"
+        "utils/"
     ],
     "type": "module",
     "exports": {
@@ -19,5 +19,5 @@
     "engines": {
         "bun": ">=1.3.0"
     },
-    "gitHead": "123125b9d7a6c26879a5b5c9d3ac05e2082141c6"
+    "gitHead": "7dd54bc1ed484139fa52ce5408f1a6c166e2a928"
 }

package/utils/deepTransformKeys.ts

@@ -0,0 +1,172 @@
+import { isPlainObject } from "es-toolkit/compat";
+import { camelCase, snakeCase, kebabCase, pascalCase } from "es-toolkit/string";
+
+/**
+ * 键名转换函数类型
+ */
+export type KeyTransformer = (key: string) => string;
+
+/**
+ * 预设的转换方式
+ * - camel: 小驼峰 user_id → userId
+ * - snake: 下划线 userId → user_id
+ * - kebab: 短横线 userId → user-id
+ * - pascal: 大驼峰 user_id → UserId
+ * - upper: 大写 userId → USERID
+ * - lower: 小写 UserId → userid
+ */
+export type PresetTransform = "camel" | "snake" | "kebab" | "pascal" | "upper" | "lower";
+
+/**
+ * 转换选项
+ */
+export interface TransformOptions {
+    /** 最大递归深度，默认 100。设置为 0 表示不限制深度（不推荐） */
+    maxDepth?: number;
+    /** 排除的键名列表，这些键名不会被转换 */
+    excludeKeys?: string[];
+}
+
+/**
+ * 深度递归遍历数据结构，转换所有键名
+ * 支持嵌套对象和数组，自动防止循环引用和栈溢出
+ *
+ * @param data - 源数据（对象、数组或其他类型）
+ * @param transformer - 转换函数或预设方式
+ * @param options - 转换选项
+ * @returns 键名转换后的新数据
+ *
+ * @example
+ * // 小驼峰
+ * deepTransformKeys({ user_id: 123, user_info: { first_name: 'John' } }, 'camel')
+ * // { userId: 123, userInfo: { firstName: 'John' } }
+ *
+ * @example
+ * // 下划线
+ * deepTransformKeys({ userId: 123, userInfo: { firstName: 'John' } }, 'snake')
+ * // { user_id: 123, user_info: { first_name: 'John' } }
+ *
+ * @example
+ * // 短横线
+ * deepTransformKeys({ userId: 123, userInfo: { firstName: 'John' } }, 'kebab')
+ * // { 'user-id': 123, 'user-info': { 'first-name': 'John' } }
+ *
+ * @example
+ * // 大驼峰
+ * deepTransformKeys({ user_id: 123 }, 'pascal')
+ * // { UserId: 123 }
+ *
+ * @example
+ * // 大写
+ * deepTransformKeys({ userId: 123 }, 'upper')
+ * // { USERID: 123 }
+ *
+ * @example
+ * // 小写
+ * deepTransformKeys({ UserId: 123 }, 'lower')
+ * // { userid: 123 }
+ *
+ * @example
+ * // 自定义转换函数
+ * deepTransformKeys({ user_id: 123 }, (key) => `prefix_${key}`)
+ * // { prefix_user_id: 123 }
+ *
+ * @example
+ * // 限制递归深度
+ * deepTransformKeys(deepData, 'camel', { maxDepth: 10 })
+ *
+ * @example
+ * // 排除特定键名
+ * deepTransformKeys({ _id: '123', user_name: 'John' }, 'camel', { excludeKeys: ['_id'] })
+ * // { _id: '123', userName: 'John' }
+ *
+ * @example
+ * // 嵌套数组和对象
+ * deepTransformKeys({
+ *   user_list: [{ user_id: 1, user_tags: [{ tag_name: 'vip' }] }]
+ * }, 'camel')
+ * // { userList: [{ userId: 1, userTags: [{ tagName: 'vip' }] }] }
+ */
+export const deepTransformKeys = <T = any>(data: any, transformer: KeyTransformer | PresetTransform, options: TransformOptions = {}): T => {
+    const { maxDepth = 100, excludeKeys = [] } = options;
+
+    // 获取实际的转换函数
+    let transformFn: KeyTransformer;
+    if (typeof transformer === "function") {
+        transformFn = transformer;
+    } else if (transformer === "camel") {
+        transformFn = camelCase;
+    } else if (transformer === "snake") {
+        transformFn = snakeCase;
+    } else if (transformer === "kebab") {
+        transformFn = kebabCase;
+    } else if (transformer === "pascal") {
+        transformFn = pascalCase;
+    } else if (transformer === "upper") {
+        transformFn = (key: string) => key.toUpperCase();
+    } else {
+        transformFn = (key: string) => key.toLowerCase();
+    }
+
+    // 用于检测循环引用的 WeakSet
+    const visited = new WeakSet();
+
+    // 创建排除键名集合，提升查找性能
+    const excludeSet = new Set(excludeKeys);
+
+    // 递归转换函数
+    const transform = (value: any, depth: number): any => {
+        // 处理 null 和 undefined
+        if (value === null || value === undefined) {
+            return value;
+        }
+
+        // 处理数组
+        if (Array.isArray(value)) {
+            // 检测循环引用
+            if (visited.has(value)) {
+                return value;
+            }
+            visited.add(value);
+
+            // 检查深度限制：如果达到限制，返回原数组
+            if (maxDepth > 0 && depth >= maxDepth) {
+                visited.delete(value);
+                return value;
+            }
+
+            const result = value.map((item: any) => transform(item, depth + 1));
+            visited.delete(value);
+            return result;
+        }
+
+        // 处理对象
+        if (isPlainObject(value)) {
+            // 检测循环引用
+            if (visited.has(value)) {
+                return value;
+            }
+            visited.add(value);
+
+            // 检查深度限制：如果达到限制，返回原对象
+            if (maxDepth > 0 && depth >= maxDepth) {
+                visited.delete(value);
+                return value;
+            }
+
+            const result: any = {};
+            for (const [key, val] of Object.entries(value)) {
+                // 检查是否在排除列表中
+                const transformedKey = excludeSet.has(key) ? key : transformFn(key);
+                result[transformedKey] = transform(val, depth + 1);
+            }
+            visited.delete(value);
+            return result;
+        }
+
+        // 其他类型（字符串、数字、布尔值等）直接返回
+        return value;
+    };
+
+    return transform(data, 0) as T;
+};

package/utils/genShortId.ts

@@ -0,0 +1,12 @@
+/**
+ * 生成短 ID
+ * 由时间戳（base36）+ 随机字符组成，约 13 位
+ * - 前 8 位：时间戳（可排序）
+ * - 后 5 位：随机字符（防冲突）
+ * @returns 短 ID 字符串
+ * @example
+ * genShortId() // "lxyz1a2b3c4"
+ */
+export function genShortId(): string {
+    return Date.now().toString(36) + Math.random().toString(36).slice(2, 7);
+}

package/utils/buildTreeByParentPath.ts

@@ -1,127 +0,0 @@
-export type BuildTreeByParentPathOptions = {
-    pathKey?: string;
-    parentPathKey?: string;
-    childrenKey?: string;
-    normalize?: (value: unknown) => string;
-};
-
-export type BuildTreeByParentPathResult<T extends Record<string, any>> = {
-    flat: Array<T>;
-    tree: Array<T>;
-    map: Map<string, T>;
-};
-
-/**
- * 将一维数组按 { path, parentPath } 组装为树形结构（纯函数 / 无副作用）。
- *
- * - 默认字段：path / parentPath / children
- * - parentPath 为空字符串或父节点不存在时，视为根节点
- * - 内部会 clone 一份节点对象，并写入 children: []
- * - 默认自带递归排序：按 sort 升序；sort 缺省/非法或 < 1 视为 999999；sort 相同按 path 自然序
- */
-export function buildTreeByParentPath<T extends Record<string, any>>(items: T[], options?: BuildTreeByParentPathOptions): BuildTreeByParentPathResult<T> {
-    const pathKey = typeof options?.pathKey === "string" && options.pathKey.length > 0 ? options.pathKey : "path";
-    const parentPathKey = typeof options?.parentPathKey === "string" && options.parentPathKey.length > 0 ? options.parentPathKey : "parentPath";
-    const childrenKey = typeof options?.childrenKey === "string" && options.childrenKey.length > 0 ? options.childrenKey : "children";
-
-    const normalize =
-        typeof options?.normalize === "function"
-            ? options.normalize
-            : (value: unknown) => {
-                  return typeof value === "string" ? value : "";
-              };
-
-    const map = new Map<string, T>();
-    const flat: T[] = [];
-
-    const safeItems = Array.isArray(items) ? items : [];
-
-    for (const item of safeItems) {
-        const rawPath = item ? item[pathKey] : undefined;
-        const rawParentPath = item ? item[parentPathKey] : undefined;
-
-        const normalizedPath = normalize(rawPath);
-        const normalizedParentPath = normalize(rawParentPath);
-
-        const nextNode = Object.assign({}, item) as T;
-        (nextNode as any)[pathKey] = normalizedPath;
-        (nextNode as any)[parentPathKey] = normalizedParentPath;
-        (nextNode as any)[childrenKey] = [];
-
-        flat.push(nextNode);
-
-        if (typeof normalizedPath === "string" && normalizedPath.length > 0) {
-            map.set(normalizedPath, nextNode);
-        }
-    }
-
-    const tree: T[] = [];
-    for (const node of flat) {
-        const parentPath = (node as any)[parentPathKey];
-
-        if (typeof parentPath === "string" && parentPath.length > 0) {
-            const parent = map.get(parentPath);
-            if (parent && Array.isArray((parent as any)[childrenKey])) {
-                (parent as any)[childrenKey].push(node);
-                continue;
-            }
-        }
-
-        tree.push(node);
-    }
-
-    const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" });
-
-    const getSortValue = (node: T): number => {
-        const raw = node ? (node as any).sort : undefined;
-        if (typeof raw !== "number") {
-            return 999999;
-        }
-
-        if (!Number.isFinite(raw)) {
-            return 999999;
-        }
-
-        if (raw < 1) {
-            return 999999;
-        }
-
-        return raw;
-    };
-
-    const compareNode = (a: T, b: T): number => {
-        const aSort = getSortValue(a);
-        const bSort = getSortValue(b);
-
-        if (aSort !== bSort) {
-            return aSort - bSort;
-        }
-
-        const aPath = a ? (a as any)[pathKey] : "";
-        const bPath = b ? (b as any)[pathKey] : "";
-        return collator.compare(typeof aPath === "string" ? aPath : "", typeof bPath === "string" ? bPath : "");
-    };
-
-    const sortTreeInPlace = (nodes: Array<T>): void => {
-        if (!Array.isArray(nodes) || nodes.length <= 1) {
-            return;
-        }
-
-        nodes.sort(compareNode);
-
-        for (const node of nodes) {
-            const children = node ? (node as any)[childrenKey] : undefined;
-            if (Array.isArray(children) && children.length > 0) {
-                sortTreeInPlace(children);
-            }
-        }
-    };
-
-    sortTreeInPlace(tree);
-
-    return {
-        flat: flat,
-        tree: tree,
-        map: map
-    };
-}