es-toolkit 的 isWeakMap 类型守卫从 compat 用法到 instanceof 源码实现【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkitisWeakMap是 es-toolkit 提供的判断值是否为WeakMap的类型守卫函数同时存在于es-toolkit/predicate与es-toolkit/compat两个入口中。本文以 compat 参考文档 为主体完整介绍其用法、参数与返回值约定、与 Map/Set/WeakSet 等相似集合的区分技巧并结合仓库源码剖析其基于instanceof的极简实现、TypeScript 类型收窄能力、测试用例与性能基准帮助你安全地在弱引用缓存、元数据管理等场景中使用它。一、函数概览一行签名、一个职责isWeakMap的职责非常单一检查传入的值是否是WeakMap实例。其函数签名如下const result isWeakMap(value);对应的参数与返回值约定为项目说明参数value类型unknown需要判断是否为WeakMap的值返回值类型value is WeakMapobject, anycompat 版/value is WeakMapWeakKey, any核心版为true表示是WeakMap否则为false两个关键设计值得注意参数是unknown函数接受任意类型的值包括null、undefined、原始类型、对象、数组等不会因传入非法值而抛出异常返回值是类型谓词type predicate返回值类型不是普通的boolean而是value is WeakMap...。这意味着在 TypeScript 中调用后编译器会把变量的类型收窄为WeakMap从而安全地访问set、get、has、delete等 WeakMap 专属 API。需要说明的是compat 版与核心版的类型签名略有差异compat 版返回WeakMapobject, any核心版返回WeakMapWeakKey, any这源于两者对键类型的表述方式不同但判断逻辑完全一致。二、快速上手基础用法与各类值的判定结果使用isWeakMap最简单的方式是从es-toolkit/compat导入并直接调用import { isWeakMap } from es-toolkit/compat; // WeakMap checking const weakMap new WeakMap(); isWeakMap(weakMap); // true // Other types return false isWeakMap(new Map()); // false isWeakMap(new Set()); // false isWeakMap(new WeakSet()); // false isWeakMap({}); // false isWeakMap([]); // false isWeakMap(weakmap); // false isWeakMap(123); // false isWeakMap(null); // false isWeakMap(undefined); // false从输出可以看出isWeakMap只对真正的WeakMap实例返回true。即使是与WeakMap血缘最近的Map同样是键值对集合、WeakSet同样是弱引用集合也会被准确地区分出来。除了es-toolkit/compat如果你只需要核心版本也可以从es-toolkit/predicate或顶层入口es-toolkit导入行为完全一致import { isWeakMap } from es-toolkit/predicate; console.log(isWeakMap(new WeakMap())); // true console.log(isWeakMap(new Map())); // false console.log(isWeakMap(null)); // false在仓库中核心版本由 src/predicate/isWeakMap.ts 实现并通过 src/predicate/index.ts 导出compat 版本则由 src/compat/predicate/isWeakMap.ts 实现经 src/compat/compat.ts 统一导出到es-toolkit/compat入口src/compat/index.ts 再通过export * from ./compat.ts对外暴露。三、区分相似集合WeakMap 与 Map / WeakSet / 普通对象isWeakMap的一个典型价值在于它能在运行期可靠地区分外观相似、但语义完全不同的集合类型。参考文档给出了三组对照示例import { isWeakMap } from es-toolkit/compat; // WeakMap vs Map const obj {}; const weakMap new WeakMap([[obj, value]]); const map new Map([[obj, value]]); isWeakMap(weakMap); // true isWeakMap(map); // false // WeakMap vs WeakSet isWeakMap(new WeakMap()); // true isWeakMap(new WeakSet()); // false // WeakMap vs regular objects isWeakMap(new WeakMap()); // true isWeakMap({}); // false为什么这组区分有实际意义因为WeakMap是唯一的以对象为键、持弱引用、且不暴露size信息的键值对集合与Map的区别Map的键可以是任意类型包括原始值且持有强引用有size属性WeakMap的键只能是对象持有弱引用没有size属性不可遍历与WeakSet的区别WeakSet是值的集合而非键值对的集合没有get/set方法只能add/has/delete与普通对象的区别普通{}不是WeakMap实例没有set/get等集合 API。从源码结构看这种区分完全由instanceof WeakMap保证详见下文第四节因此只要值确实是原生WeakMap或继承自WeakMap.prototype的对象判断结果就是精确的。四、实战场景利用 WeakMap 特殊性质做类型安全处理当你的函数接收unknown类型的参数、需要针对 WeakMap 走不同分支时isWeakMap既能完成运行时判断又能让 TypeScript 在该分支内自动收窄类型。参考文档中的setupWeakReference示例就演示了这一模式import { isWeakMap } from es-toolkit/compat; function setupWeakReference(collection: unknown, key: object, value: any) { if (isWeakMap(collection)) { // WeakMap can only use objects as keys and maintains weak references collection.set(key, value); console.log(Stored with weak reference in WeakMap); // WeakMap does not have size information console.log(WeakMap has no size information); } else { console.log(Not a WeakMap); } } const weakMap new WeakMap(); const regularMap new Map(); const obj { id: 1 }; setupWeakReference(weakMap, obj, data); // Stored with weak reference in WeakMap setupWeakReference(regularMap, obj, data); // Not a WeakMap这段代码展示了两个实际收益类型收窄参数collection声明为unknown但在isWeakMap(collection)为真的分支内它被收窄为WeakMap因此可以放心调用collection.set(key, value)编译器不会报错语义分支WeakMap 以对象为键、持弱引用、无size信息与Map的行为不同所以在使用弱引用缓存例如为对象附加私有元数据、缓存计算结果时需要先确认集合类型再按对应语义操作。一个典型的工程场景是用WeakMap为任意对象关联私有的、不会阻止 GC 回收的元数据。此时入参往往是unknown借助isWeakMap可以在工具函数中安全地读写这类弱引用缓存同时避免把Map误当作WeakMap使用否则可能导致内存无法释放或调用不存在的 API。五、源码剖析极简的 instanceof 实现与 compat 委托isWeakMap之所以高效、轻量是因为它的核心实现只有一行。核心版本在 src/predicate/isWeakMap.ts 中实现如下export function isWeakMap(value: unknown): value is WeakMapWeakKey, any { return value instanceof WeakMap; }而 compat 版本 src/compat/predicate/isWeakMap.ts 则直接委托给核心版本export function isWeakMap(value?: any): value is WeakMapobject, any { return isWeakMapToolkit(value); }这一设计值得展开说明无依赖、无兜底逻辑整个判断完全依赖 JavaScript 原生的instanceof运算符。与 lodash 等库为了兼容旧环境而做的复杂特征检测不同es-toolkit 面向现代运行时ES2015 之后的WeakMap为内建对象因此不需要任何 polyfill 或特殊兜底compat 层薄封装compat 版本只是把类型签名调整为WeakMapobject, any与 lodash 风格保持一致逻辑上完全复用核心实现避免了重复代码类型守卫能力来自 TypeScript 的类型谓词value is WeakMap...让函数在编译期即可参与类型收窄这是运行时instanceof与编译期类型系统结合的典型写法。六、测试验证覆盖边界值与非函数构造器对象仓库为isWeakMap编写了详尽的测试见 src/compat/predicate/isWeakMap.spec.ts使用 Vitest 组织覆盖了三类关键场景对 WeakMap 返回trueisWeakMap(new WeakMap())为true测试中先判断WeakMap是否存在兼容不支持 WeakMap 的旧环境对大量非 WeakMap 值返回false包括假值列表falsey、arguments对象、数组[1, 2, 3]、布尔值、Date、Error、函数、普通对象、数字、正则、字符串、Symbol 等十余种类型对带非函数constructor属性的对象返回false例如{ constructor: false }与{ constructor: true }这模拟了 IE 11 等环境下对象拥有同名属性时的边界情况确保不会误判。这些测试既验证了isWeakMap的正确性也体现了作为类型检查函数应具备的健壮性无论传入什么值都不会抛错只返回布尔结果。七、性能验证与 lodash 的同场基准仓库在 benchmarks/performance/isWeakMap.bench.ts 中提供了isWeakMap的基准测试使用 Vitest 的bench对三组实现进行同场对比es-toolkit/isWeakMap核心版本es-toolkit/compat/isWeakMapcompat 版本lodash/isWeakMaplodash 对照每组测试都会依次对new WeakMap()、new Map()、空字符串、数字 123 四种输入做判断覆盖是 WeakMap / 相似集合 / 原始类型三类输入形态。由于核心实现仅是一次instanceof运算从源码结构可以推断其在现代引擎上开销极低且不会引入 lodash 式特征检测的额外分支成本。运行该基准的方式与仓库其他基准一致即通过 Vitest 执行bench用例可参考 benchmarks/performance 目录的通用配置。八、官方建议优先使用原生 instanceof最后需要特别说明的是参考文档在开头明确给出了一条警告isWeakMap本质上是 Lodash 兼容函数而它做的只是一个简单的类型检查因此官方建议直接用更简单、更现代的value instanceof WeakMap代替。// 官方推荐的替代写法 const isWeakMap value instanceof WeakMap;这条建议的适用前提是你的代码运行在支持 ES2015WeakMap的现代环境中且不需要与 lodash 保持 API 级兼容。反之如果你正在从 lodash 迁移到 es-toolkit、希望保持isWeakMap(value)的调用形式不变或者需要借助类型谓词value is WeakMap...自动获得 TypeScript 类型收窄那么直接使用es-toolkit/compat的isWeakMap依然是最省心、最类型安全的选择。总结isWeakMap是 es-toolkit 提供的 WeakMap 类型守卫核心实现为一行value instanceof WeakMapsrc/predicate/isWeakMap.tscompat 版通过薄封装复用核心逻辑src/compat/predicate/isWeakMap.ts它能精确区分 WeakMap 与 Map、WeakSet、普通对象返回值是类型谓词可在 TypeScript 中自动收窄类型适合在unknown入参的工具函数中安全操作弱引用缓存官方建议在无需 lodash 兼容的现代环境下直接使用原生instanceof在需要保持 lodash 调用形式或依赖类型收窄时使用es-toolkit/compat的版本即可。【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考