开源分享：ReflectDeep - 一个强大的深度对象操作 TypeScript 库

KasukabeTsumugi
123 阅读3分钟

开源分享：ReflectDeep - 一个强大的深度对象操作 TypeScript 库

这是一篇AI翻译的介绍，有任何问题请告诉我！

大家好！👋

我开发了一个叫做 ReflectDeep 的 TypeScript 库，专门用于简化和安全化深度对象操作。在多个项目中遇到无数次嵌套属性访问 bug 和循环引用噩梦后，我决定构建一个既健壮又对开发者友好的解决方案。

什么是 ReflectDeep？

ReflectDeep 是一个全面的 JavaScript 对象深度反射操作工具库。可以把它看作是原生 Reflect 方法的超级增强版，专门针对嵌套属性，并提供了大量额外的安全特性。

核心特性

🔍 深度属性访问 - 经典的 API，如 get、set、has、deleteProperty 和 defineProperty，但支持嵌套路径

🔄 防弹级深度克隆 - 处理循环引用、Maps、Sets、TypedArrays 等各种复杂类型

🔑 原型链检查 - 使用 keys() 和 groupedKeys() 从整个原型链中提取键

🛡️ 完整 TypeScript 支持 - 适当的类型推断和安全性

🌐 全面的类型覆盖 - 支持 Arrays、Maps、Sets、Dates、RegExp、Node.js Buffers 等

快速示例

import { ReflectDeep } from 'reflect-deep';

const obj = { users: [{ profile: { settings: { theme: 'dark' } } }] };

// 安全的嵌套访问
const theme = ReflectDeep.get(obj, ['users', 0, 'profile', 'settings', 'theme']);
// 返回 'dark' 或如果路径不存在则返回 undefined

// 安全的嵌套赋值，自动创建中间对象
ReflectDeep.set(obj, ['users', 0, 'profile', 'notifications'], { email: true });

// 检查嵌套属性是否存在
const hasTheme = ReflectDeep.has(obj, ['users', 0, 'profile', 'settings', 'theme']);

// 支持循环引用的克隆
const cloned = ReflectDeep.clone(obj);

它的独特之处？

安全第一：再也不会遇到访问嵌套属性时的 Cannot read property of undefined 错误。

循环引用处理：与 JSON.parse(JSON.stringify()) 不同，这个库能正确处理循环引用。

熟悉的 API：如果你知道 Reflect.get()，你就已经知道 ReflectDeep.get() 了 - 只需传递一个键数组即可。

TypeScript 原生：从头开始用 TypeScript 构建，具有适当的类型推断。

实际应用场景

  • 配置管理：安全访问嵌套配置对象
  • 表单验证：导航复杂的表单数据结构
  • API 响应处理：处理深度嵌套的 API 响应
  • 状态管理：克隆和操作复杂的应用状态
  • 对象转换：在不产生副作用的情况下转换嵌套数据结构

高级功能展示

1. 原型链检查

// 获取对象及其原型链上的所有键
const allKeys = ReflectDeep.keys(myObject);

// 按原型层分组获取键
const groupedKeys = ReflectDeep.groupedKeys(myObject);
// 返回: [
//   { keys: ['ownProp'], object: myObject },
//   { keys: ['prototypeProp'], object: MyClass.prototype },
//   { keys: ['toString', ...], object: Object.prototype }
// ]

2. 路径遍历

// 找到最远可达的值
const result = ReflectDeep.reach(obj, ['a', 'b', 'nonexistent']);
// 返回: { value: {b: {...}}, index: 1, reached: false }

3. 属性定义

// 深度定义带描述符的属性
ReflectDeep.defineProperty(obj, ['nested', 'readonly'], {
  value: 'immutable',
  writable: false,
  enumerable: true,
  configurable: true,
});

性能与兼容性

  • 使用 WeakMap 进行高效的循环引用检测
  • 无外部依赖
  • 支持 Node.js 和浏览器环境
  • 处理边缘情况，如 TypedArrays、DataView、Node.js Buffers
  • 针对不同对象类型进行了优化

技术亮点

  1. 类型安全：完整的 TypeScript 类型定义，编译时就能发现问题
  2. 性能优化：针对不同数据类型使用不同的克隆策略
  3. 错误处理：对无效输入提供清晰的错误信息
  4. 测试覆盖：100% 的测试覆盖率，包括边缘情况

安装使用

npm install reflect-deep

import { ReflectDeep } from 'reflect-deep';
import ReflectDeep from 'reflect-deep';

// 开始使用！

链接

这个库使用 MIT 许可证，并具有全面的测试覆盖。欢迎大家试用并提供反馈！

如果你觉得这个库有用，欢迎给个 ⭐️ star！感谢大家的支持！🚀

标签: #TypeScript #JavaScript #开源 #工具库 #对象操作

avatar
文章
阅读
粉丝