befly-shared 1.2.6 → 1.2.8

package/dist/deepTransformKeys.js

@@ -0,0 +1,139 @@
+import { isPlainObject } from 'es-toolkit/compat';
+import { camelCase, snakeCase, kebabCase, pascalCase } from 'es-toolkit/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 = (data, transformer, options = {}) => {
+    const { maxDepth = 100, excludeKeys = [] } = options;
+    // 获取实际的转换函数
+    let transformFn;
+    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) => key.toUpperCase();
+    }
+    else {
+        transformFn = (key) => key.toLowerCase();
+    }
+    // 用于检测循环引用的 WeakSet
+    const visited = new WeakSet();
+    // 创建排除键名集合，提升查找性能
+    const excludeSet = new Set(excludeKeys);
+    // 递归转换函数
+    const transform = (value, depth) => {
+        // 处理 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) => 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 = {};
+            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);
+};

package/dist/index.js

@@ -13,6 +13,7 @@ export * from './arrayKeysToCamel.js';
 export * from './arrayToTree.js';
 export * from './calcPerfTime.js';
 export * from './configTypes.js';
+export * from './deepTransformKeys.js';
 export * from './genShortId.js';
 export * from './scanConfig.js';
 export * from './fieldClear.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly-shared",
-    "version": "1.2.6",
+    "version": "1.2.8",
     "type": "module",
     "exports": {
         ".": {
@@ -32,9 +32,9 @@
         "typescript": "^5.7.2"
     },
     "dependencies": {
-        "es-toolkit": "^1.42.0",
+        "es-toolkit": "^1.43.0",
         "merge-anything": "^6.0.6",
         "pathe": "^2.0.3"
     },
-    "gitHead": "f1d08a65a7e98e89da1d42688f1ed96fd06b444d"
+    "gitHead": "e078b94f087ddf21f289b55ab86c0b8dce105807"
 }

package/src/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/src/index.ts

@@ -16,6 +16,7 @@ export * from './arrayKeysToCamel.js';
 export * from './arrayToTree.js';
 export * from './calcPerfTime.js';
 export * from './configTypes.js';
+export * from './deepTransformKeys.js';
 export * from './genShortId.js';
 export * from './scanConfig.js';
 export * from './fieldClear.js';

package/tests/deepTransformKeys.test.ts

@@ -0,0 +1,466 @@
+import { describe, expect, it } from 'bun:test';
+import { deepTransformKeys } from '../src/deepTransformKeys';
+
+describe('deepTransformKeys', () => {
+    describe('预设转换 - camel', () => {
+        it('应该转换简单对象的键名为小驼峰', () => {
+            const input = { user_id: 123, user_name: 'John' };
+            const expected = { userId: 123, userName: 'John' };
+            expect(deepTransformKeys(input, 'camel')).toEqual(expected);
+        });
+
+        it('应该转换嵌套对象的键名为小驼峰', () => {
+            const input = {
+                user_id: 123,
+                user_info: {
+                    first_name: 'John',
+                    last_name: 'Doe'
+                }
+            };
+            const expected = {
+                userId: 123,
+                userInfo: {
+                    firstName: 'John',
+                    lastName: 'Doe'
+                }
+            };
+            expect(deepTransformKeys(input, 'camel')).toEqual(expected);
+        });
+    });
+
+    describe('预设转换 - snake', () => {
+        it('应该转换简单对象的键名为下划线', () => {
+            const input = { userId: 123, userName: 'John' };
+            const expected = { user_id: 123, user_name: 'John' };
+            expect(deepTransformKeys(input, 'snake')).toEqual(expected);
+        });
+
+        it('应该转换嵌套对象的键名为下划线', () => {
+            const input = {
+                userId: 123,
+                userInfo: {
+                    firstName: 'John',
+                    lastName: 'Doe'
+                }
+            };
+            const expected = {
+                user_id: 123,
+                user_info: {
+                    first_name: 'John',
+                    last_name: 'Doe'
+                }
+            };
+            expect(deepTransformKeys(input, 'snake')).toEqual(expected);
+        });
+    });
+
+    describe('预设转换 - kebab', () => {
+        it('应该转换简单对象的键名为短横线', () => {
+            const input = { userId: 123, userName: 'John' };
+            const expected = { 'user-id': 123, 'user-name': 'John' };
+            expect(deepTransformKeys(input, 'kebab')).toEqual(expected);
+        });
+
+        it('应该转换嵌套对象的键名为短横线', () => {
+            const input = {
+                userId: 123,
+                userInfo: {
+                    firstName: 'John',
+                    lastName: 'Doe'
+                }
+            };
+            const expected = {
+                'user-id': 123,
+                'user-info': {
+                    'first-name': 'John',
+                    'last-name': 'Doe'
+                }
+            };
+            expect(deepTransformKeys(input, 'kebab')).toEqual(expected);
+        });
+    });
+
+    describe('预设转换 - pascal', () => {
+        it('应该转换简单对象的键名为大驼峰', () => {
+            const input = { user_id: 123, user_name: 'John' };
+            const expected = { UserId: 123, UserName: 'John' };
+            expect(deepTransformKeys(input, 'pascal')).toEqual(expected);
+        });
+
+        it('应该转换嵌套对象的键名为大驼峰', () => {
+            const input = {
+                user_id: 123,
+                user_info: {
+                    first_name: 'John'
+                }
+            };
+            const expected = {
+                UserId: 123,
+                UserInfo: {
+                    FirstName: 'John'
+                }
+            };
+            expect(deepTransformKeys(input, 'pascal')).toEqual(expected);
+        });
+    });
+
+    describe('预设转换 - upper', () => {
+        it('应该转换简单对象的键名为大写', () => {
+            const input = { userId: 123, userName: 'John' };
+            const expected = { USERID: 123, USERNAME: 'John' };
+            expect(deepTransformKeys(input, 'upper')).toEqual(expected);
+        });
+
+        it('应该转换嵌套对象的键名为大写', () => {
+            const input = {
+                userId: 123,
+                userInfo: {
+                    firstName: 'John'
+                }
+            };
+            const expected = {
+                USERID: 123,
+                USERINFO: {
+                    FIRSTNAME: 'John'
+                }
+            };
+            expect(deepTransformKeys(input, 'upper')).toEqual(expected);
+        });
+    });
+
+    describe('预设转换 - lower', () => {
+        it('应该转换简单对象的键名为小写', () => {
+            const input = { UserId: 123, UserName: 'John' };
+            const expected = { userid: 123, username: 'John' };
+            expect(deepTransformKeys(input, 'lower')).toEqual(expected);
+        });
+
+        it('应该转换嵌套对象的键名为小写', () => {
+            const input = {
+                UserId: 123,
+                UserInfo: {
+                    FirstName: 'John'
+                }
+            };
+            const expected = {
+                userid: 123,
+                userinfo: {
+                    firstname: 'John'
+                }
+            };
+            expect(deepTransformKeys(input, 'lower')).toEqual(expected);
+        });
+    });
+
+    describe('自定义转换函数', () => {
+        it('应该使用自定义函数转换键名为大写', () => {
+            const input = { user_id: 123, user_name: 'John' };
+            const expected = { USER_ID: 123, USER_NAME: 'John' };
+            expect(deepTransformKeys(input, (key) => key.toUpperCase())).toEqual(expected);
+        });
+
+        it('应该使用自定义函数转换嵌套对象', () => {
+            const input = {
+                user_id: 123,
+                user_info: {
+                    first_name: 'John'
+                }
+            };
+            const expected = {
+                USER_ID: 123,
+                USER_INFO: {
+                    FIRST_NAME: 'John'
+                }
+            };
+            expect(deepTransformKeys(input, (key) => key.toUpperCase())).toEqual(expected);
+        });
+
+        it('应该支持自定义前缀添加', () => {
+            const input = { id: 1, name: 'test' };
+            const expected = { prefix_id: 1, prefix_name: 'test' };
+            expect(deepTransformKeys(input, (key) => `prefix_${key}`)).toEqual(expected);
+        });
+    });
+
+    describe('数组处理', () => {
+        it('应该转换数组中对象的键名', () => {
+            const input = [
+                { user_id: 1, user_name: 'Alice' },
+                { user_id: 2, user_name: 'Bob' }
+            ];
+            const expected = [
+                { userId: 1, userName: 'Alice' },
+                { userId: 2, userName: 'Bob' }
+            ];
+            expect(deepTransformKeys(input, 'camel')).toEqual(expected);
+        });
+
+        it('应该转换嵌套数组和对象', () => {
+            const input = {
+                user_list: [
+                    {
+                        user_id: 1,
+                        user_tags: [
+                            { tag_name: 'vip', tag_level: 5 },
+                            { tag_name: 'active', tag_level: 3 }
+                        ]
+                    }
+                ]
+            };
+            const expected = {
+                userList: [
+                    {
+                        userId: 1,
+                        userTags: [
+                            { tagName: 'vip', tagLevel: 5 },
+                            { tagName: 'active', tagLevel: 3 }
+                        ]
+                    }
+                ]
+            };
+            expect(deepTransformKeys(input, 'camel')).toEqual(expected);
+        });
+    });
+
+    describe('边界情况', () => {
+        it('应该处理 null 值', () => {
+            expect(deepTransformKeys(null, 'camel')).toBeNull();
+        });
+
+        it('应该处理 undefined', () => {
+            expect(deepTransformKeys(undefined, 'camel')).toBeUndefined();
+        });
+
+        it('应该处理基本类型', () => {
+            expect(deepTransformKeys('string', 'camel')).toBe('string');
+            expect(deepTransformKeys(123, 'camel')).toBe(123);
+            expect(deepTransformKeys(true, 'camel')).toBe(true);
+        });
+
+        it('应该处理空对象', () => {
+            expect(deepTransformKeys({}, 'camel')).toEqual({});
+        });
+
+        it('应该处理空数组', () => {
+            expect(deepTransformKeys([], 'camel')).toEqual([]);
+        });
+
+        it('应该处理混合类型的数组', () => {
+            const input = [{ user_id: 1 }, 'string', 123, null, { nested_obj: { deep_key: 'value' } }];
+            const expected = [{ userId: 1 }, 'string', 123, null, { nestedObj: { deepKey: 'value' } }];
+            expect(deepTransformKeys(input, 'camel')).toEqual(expected);
+        });
+
+        it('应该处理深层嵌套的结构', () => {
+            const input = {
+                level_1: {
+                    level_2: {
+                        level_3: {
+                            deep_key: 'deep_value'
+                        }
+                    }
+                }
+            };
+            const expected = {
+                level1: {
+                    level2: {
+                        level3: {
+                            deepKey: 'deep_value'
+                        }
+                    }
+                }
+            };
+            expect(deepTransformKeys(input, 'camel')).toEqual(expected);
+        });
+    });
+
+    describe('循环引用和深度限制', () => {
+        it('应该处理循环引用的对象', () => {
+            const obj: any = { user_id: 1, user_name: 'test' };
+            obj.self = obj; // 循环引用
+
+            const result = deepTransformKeys(obj, 'camel');
+
+            expect(result.userId).toBe(1);
+            expect(result.userName).toBe('test');
+            // 循环引用的部分应该保持原样
+            expect(result.self).toBe(obj);
+        });
+
+        it('应该处理循环引用的数组', () => {
+            const arr: any = [{ user_id: 1 }];
+            arr.push(arr); // 循环引用
+
+            const result = deepTransformKeys(arr, 'camel');
+
+            expect(result[0]).toEqual({ userId: 1 });
+            // 循环引用的部分应该保持原样
+            expect(result[1]).toBe(arr);
+        });
+
+        it('应该遵守 maxDepth 限制', () => {
+            const input = {
+                level_1: {
+                    level_2: {
+                        level_3: {
+                            deep_key: 'value'
+                        }
+                    }
+                }
+            };
+
+            // 限制深度为 2
+            const result = deepTransformKeys(input, 'camel', { maxDepth: 2 });
+
+            expect(result.level1).toBeDefined();
+            expect(result.level1.level2).toBeDefined();
+            // 第 3 层应该保持原样
+            expect(result.level1.level2.level_3).toBeDefined();
+            expect(result.level1.level2.level_3.deep_key).toBe('value');
+        });
+
+        it('应该在深度为 1 时只转换第一层', () => {
+            const input = {
+                user_id: 1,
+                user_info: {
+                    first_name: 'John'
+                }
+            };
+
+            const result = deepTransformKeys(input, 'camel', { maxDepth: 1 });
+
+            expect(result.userId).toBe(1);
+            // 第二层应该保持原样
+            expect(result.userInfo.first_name).toBe('John');
+        });
+
+        it('maxDepth 为 0 时不限制深度', () => {
+            const input = {
+                l1: { l2: { l3: { l4: { l5: { deep_key: 'value' } } } } }
+            };
+
+            const result = deepTransformKeys(input, 'camel', { maxDepth: 0 });
+
+            expect(result.l1.l2.l3.l4.l5.deepKey).toBe('value');
+        });
+
+        it('默认 maxDepth 应该足够处理常见深度', () => {
+            // 创建 50 层深度的对象（小于默认的 100）
+            let obj: any = { deep_key: 'value' };
+            for (let i = 0; i < 49; i++) {
+                obj = { nested_obj: obj };
+            }
+
+            const result = deepTransformKeys(obj, 'camel');
+
+            // 应该能完全转换
+            let current = result;
+            for (let i = 0; i < 49; i++) {
+                expect(current.nestedObj).toBeDefined();
+                current = current.nestedObj;
+            }
+            expect(current.deepKey).toBe('value');
+        });
+    });
+
+    describe('排除键名功能', () => {
+        it('应该排除指定的键名不转换', () => {
+            const input = { _id: '123', user_id: 456, user_name: 'John' };
+            const result = deepTransformKeys(input, 'camel', { excludeKeys: ['_id'] });
+
+            expect(result._id).toBe('123');
+            expect(result.userId).toBe(456);
+            expect(result.userName).toBe('John');
+        });
+
+        it('应该排除嵌套对象中的指定键名', () => {
+            const input = {
+                _id: '123',
+                user_id: 456,
+                user_info: {
+                    _id: '789',
+                    first_name: 'John',
+                    __v: 1
+                }
+            };
+            const result = deepTransformKeys(input, 'camel', { excludeKeys: ['_id', '__v'] });
+
+            expect(result._id).toBe('123');
+            expect(result.userId).toBe(456);
+            expect(result.userInfo._id).toBe('789');
+            expect(result.userInfo.firstName).toBe('John');
+            expect(result.userInfo.__v).toBe(1);
+        });
+
+        it('应该排除数组中对象的指定键名', () => {
+            const input = [
+                { _id: '1', user_name: 'Alice' },
+                { _id: '2', user_name: 'Bob' }
+            ];
+            const result = deepTransformKeys(input, 'camel', { excludeKeys: ['_id'] });
+
+            expect(result[0]._id).toBe('1');
+            expect(result[0].userName).toBe('Alice');
+            expect(result[1]._id).toBe('2');
+            expect(result[1].userName).toBe('Bob');
+        });
+
+        it('应该支持多个排除键名', () => {
+            const input = {
+                _id: '123',
+                __v: 1,
+                created_at: Date.now(),
+                user_id: 456,
+                user_name: 'John'
+            };
+            const result = deepTransformKeys(input, 'camel', {
+                excludeKeys: ['_id', '__v', 'created_at']
+            });
+
+            expect(result._id).toBe('123');
+            expect(result.__v).toBe(1);
+            expect(result.created_at).toBe(input.created_at);
+            expect(result.userId).toBe(456);
+            expect(result.userName).toBe('John');
+        });
+
+        it('排除键名不存在时应该正常转换', () => {
+            const input = { user_id: 1, user_name: 'test' };
+            const result = deepTransformKeys(input, 'camel', {
+                excludeKeys: ['_id', 'non_existent']
+            });
+
+            expect(result.userId).toBe(1);
+            expect(result.userName).toBe('test');
+        });
+
+        it('空排除列表应该正常转换所有键', () => {
+            const input = { user_id: 1, user_name: 'test' };
+            const result = deepTransformKeys(input, 'camel', { excludeKeys: [] });
+
+            expect(result.userId).toBe(1);
+            expect(result.userName).toBe('test');
+        });
+
+        it('应该结合深度限制和排除键名使用', () => {
+            const input = {
+                _id: '123',
+                user_info: {
+                    _id: '456',
+                    nested: {
+                        deep_key: 'value'
+                    }
+                }
+            };
+            const result = deepTransformKeys(input, 'camel', {
+                maxDepth: 2,
+                excludeKeys: ['_id']
+            });
+
+            expect(result._id).toBe('123');
+            expect(result.userInfo._id).toBe('456');
+            // 深度限制，第三层保持原样
+            expect(result.userInfo.nested.deep_key).toBe('value');
+        });
+    });
+});

package/types/deepTransformKeys.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 键名转换函数类型
+ */
+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 declare const deepTransformKeys: <T = any>(data: any, transformer: KeyTransformer | PresetTransform, options?: TransformOptions) => T;

package/types/index.d.ts

@@ -10,6 +10,7 @@ export * from './arrayKeysToCamel.js';
 export * from './arrayToTree.js';
 export * from './calcPerfTime.js';
 export * from './configTypes.js';
+export * from './deepTransformKeys.js';
 export * from './genShortId.js';
 export * from './scanConfig.js';
 export * from './fieldClear.js';