企业官网建设流程全解析

es-toolkit isNumber 源码剖析：Lodash 兼容版如何同时识别原始数字与 Number 包装对象

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit

isNumber 是 es-toolkitcompat（Lodash 兼容）子路径下最常用的类型谓词之一，用于判断一个值是否为数字。与 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，后续可以安全地对其执行算术运算或调用数字专用 API：

function 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); }

整个判断由两个分支的“或”组成：

1. typeof value === 'number'：最快捷的路径，直接命中所有原始数字，包括NaN、Infinity、-Infinity、0和负数。这是主入口src/predicate/isNumber.ts的全部实现。

2. isObjectLike(value) && getTag(value) === numberTag：当值不是原始数字时，进一步检查它是否为 Number 包装对象。这一步由两个内部工具函数协作完成：

   • isObjectLike：判断值是否为“类对象”——即typeof value === 'object' && value !== null。它先排除null（typeof null === 'object'但显然不是对象），避免后续调用toString报错；
   • getTag：对null/undefined单独返回'[object Undefined]'/'[object Null]'，其余值调用Object.prototype.toString.call(value)获取其内部toStringTag；
   • numberTag：定义在 src/compat/_internal/tags.ts，值为字符串'[object Number]'。只有new Number(...)这类包装对象经由Object.prototype.toString才会得到该标签。

综合来看，isNumber的结果矩阵可以归纳为：

一个值得注意的边界情况是Object.create(Number.prototype)：它继承了 Number 原型，但Object.prototype.toString会返回'[object Object]'而非'[object Number]'，因此 isNumber 对它返回false，测试用例 isNumber.spec.ts 专门验证了这一行为。

测试覆盖：行为契约的完整见证

src/compat/predicate/isNumber.spec.ts 使用 Vitest 编写，全面锁定了函数的边界行为：

• 数字值返回 true：0、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.ts：isNaN先调用isNumber(value)过滤掉非数字，再通过Number.isNaN(Number(value))判断。由于先经过了 isNumber，isNaN('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 兼容函数，行为对齐优先级高于极致性能。

使用建议与注意事项

1. 优先使用typeof：原文档的警告非常明确——对于绝大多数现代代码，typeof value === 'number'更简单、更快速，且能覆盖除 Number 包装对象外的全部场景。只有在确实需要兼容new Number(...)或对齐 Lodash 时才引入 compat 版；
2. 注意 NaN 与 Infinity 的语义：isNumber(NaN)和isNumber(Infinity)都返回true。若需要排除 NaN，请与Number.isNaN或 compat 的isNaN组合使用；
3. 不要依赖数字字符串：isNumber('123')返回false，它只判断值的类型，不做任何隐式转换，这与Number('123')的行为有本质区别；
4. TypeScript 类型收窄：利用value is number的谓词签名，在条件分支内获得精确的number类型推断。

isNumber 虽小，却是理解 es-toolkit 兼容层设计哲学的绝佳样本：一条typeof分支保证主路径效率，一条getTag分支保证与 Lodash 行为对齐，两者结合并用测试锁死契约，为上层isNaN、sortedIndex等函数提供了可靠的类型地基。

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit