es-toolkit isNumber 源码剖析Lodash 兼容版如何同时识别原始数字与 Number 包装对象【免费下载链接】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-toolkitisNumber 是 es-toolkitcompatLodash 兼容子路径下最常用的类型谓词之一用于判断一个值是否为数字。与 es-toolkit 主入口中只做typeof检查的简化版不同compat 版本为了与 Lodash 行为保持一致还必须识别new Number(42)这类 Number 包装对象。读完本文你将掌握 isNumber 的完整用法、返回值语义、基于Object.prototype.toString的内部实现原理以及它在sortedIndex、isNaN等函数中的真实调用场景。功能概述它识别什么、不识别什么isNumber(value)检查一个值是否为数字。它同时将**原始数字primitive number**和Number 包装对象Number object视为数字这是与 Lodash 保持兼容的关键语义。核心签名如下const result isNumber(value);需要注意NaN、Infinity、-Infinity都属于 number 类型因此isNumber对它们都返回true而字符串123、布尔值、null、undefined、对象、数组等一律返回false。基础用法与代码示例在 compat 模式下从es-toolkit/compat导入即可使用import { isNumber } from es-toolkit/compat; // 原始数字 isNumber(123); // Returns: true isNumber(3.14); // Returns: true isNumber(NaN); // Returns: true // Number 包装对象 isNumber(new Number(42)); // Returns: true // 其他类型 isNumber(123); // Returns: false isNumber(true); // Returns: false isNumber(null); // Returns: false参数value(unknown)要判断是否为数字的值。返回值(value is number)如果值是数字则返回true否则返回false。返回类型声明为value is number的类型谓词type predicate意味着在 TypeScript 中一旦isNumber(x)返回true编译器就会把x的类型收窄为number后续可以安全地对其执行算术运算或调用数字专用 APIfunction process(input: unknown) { if (isNumber(input)) { // 此处 input 已被收窄为 number可安全调用 toFixed、toExponential 等 return input.toFixed(2); } return String(input); }源码实现为什么 compat 版如此“复杂”原文档的警告框明确指出这个 isNumber 函数因为要处理 Number 对象包装器而变得复杂。让我们逐行拆解 src/compat/predicate/isNumber.ts 的实现export function isNumber(value?: any): value is number { return typeof value number || (isObjectLike(value) getTag(value) numberTag); }整个判断由两个分支的“或”组成typeof value number最快捷的路径直接命中所有原始数字包括NaN、Infinity、-Infinity、0和负数。这是主入口src/predicate/isNumber.ts的全部实现。isObjectLike(value) getTag(value) numberTag当值不是原始数字时进一步检查它是否为 Number 包装对象。这一步由两个内部工具函数协作完成isObjectLike判断值是否为“类对象”——即typeof value object value ! null。它先排除nulltypeof null object但显然不是对象避免后续调用toString报错getTag对null/undefined单独返回[object Undefined]/[object Null]其余值调用Object.prototype.toString.call(value)获取其内部toStringTagnumberTag定义在 src/compat/_internal/tags.ts值为字符串[object Number]。只有new Number(...)这类包装对象经由Object.prototype.toString才会得到该标签。综合来看isNumber的结果矩阵可以归纳为输入值typeofgetTagisNumber123、3.14、NaN、Infinitynumber—truenew Number(42)object[object Number]true123、true、{}、[]其他非 Number 标签falsenull/undefinedobject/undefined[object Null]/[object Undefined]false一个值得注意的边界情况是Object.create(Number.prototype)它继承了 Number 原型但Object.prototype.toString会返回[object Object]而非[object Number]因此 isNumber 对它返回false测试用例 isNumber.spec.ts 专门验证了这一行为。测试覆盖行为契约的完整见证src/compat/predicate/isNumber.spec.ts 使用 Vitest 编写全面锁定了函数的边界行为数字值返回 true0、1、-1、1.5、Infinity、-Infinity全部为true第 9-16 行非数字返回 false字符串、布尔、null、undefined、空对象、空数组、箭头函数均返回false第 18-27 行NaN 返回 true单独用例确认NaN属于数字第 29-31 行包装对象Object(0)与0一样返回true第 33-37 行falsey 值全量扫描测试用falsey数组如0、、null、undefined、NaN等逐一映射typeof value number的期望结果与实际结果比对第 39-44 行确保兼容版与纯 typeof 语义在 falsey 输入上完全一致其他内置类型排除arguments、数组、Date、Error、函数、对象、正则、Symbol 均返回false第 46-55 行原型继承边界Object.create(Number.prototype)返回false第 58-60 行。与主入口 isNumber 的差异两种语义并存es-toolkit 在主入口 src/predicate/isNumber.ts 提供了更简单的版本export function isNumber(x: unknown): x is number { return typeof x number; }它的行为与 compat 版在原始数字上完全一致测试中isNumber(123)、isNumber(true)等均返回false参见 src/predicate/isNumber.spec.ts但不识别 Number 包装对象——例如isNumber(new Number(42))返回false。因此选择建议是编写新代码且不依赖 Lodash 兼容语义时优先使用主入口的es-toolkit版isNumber性能更好、语义更清晰从 Lodash 迁移或需要与 Lodash 行为逐一对齐时使用es-toolkit/compat的版本它保证new Number(42)也被判定为数字。实战组合isNumber 在仓库内部的真实调用isNumber 并非孤立存在它在 compat 内部被多个核心函数复用src/compat/predicate/isNaN.tsisNaN先调用isNumber(value)过滤掉非数字再通过Number.isNaN(Number(value))判断。由于先经过了 isNumberisNaN(NaN)这类字符串输入会安全地返回false避免了全局isNaN的隐式类型转换陷阱src/compat/array/sortedIndex.ts与 src/compat/array/sortedLastIndex.ts在数值有序数组中查找插入位置时用isNumber(value)配合value value排除 NaN来保护位运算与数组长度上限HALF_MAX_ARRAY_LENGTH的安全性src/compat/util/cond.ts条件分支组合场景中借助 isNumber 区分数字分支。这些调用印证了 compat 版“宁可多一次Object.prototype.toString也要兼容包装对象”的设计取向因为被它服务的都是 Lodash 兼容函数行为对齐优先级高于极致性能。使用建议与注意事项优先使用typeof原文档的警告非常明确——对于绝大多数现代代码typeof value number更简单、更快速且能覆盖除 Number 包装对象外的全部场景。只有在确实需要兼容new Number(...)或对齐 Lodash 时才引入 compat 版注意 NaN 与 Infinity 的语义isNumber(NaN)和isNumber(Infinity)都返回true。若需要排除 NaN请与Number.isNaN或 compat 的isNaN组合使用不要依赖数字字符串isNumber(123)返回false它只判断值的类型不做任何隐式转换这与Number(123)的行为有本质区别TypeScript 类型收窄利用value is number的谓词签名在条件分支内获得精确的number类型推断。isNumber 虽小却是理解 es-toolkit 兼容层设计哲学的绝佳样本一条typeof分支保证主路径效率一条getTag分支保证与 Lodash 行为对齐两者结合并用测试锁死契约为上层isNaN、sortedIndex等函数提供了可靠的类型地基。【免费下载链接】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），仅供参考