es-toolkit isSafeInteger 完全指南Lodash 兼容层中的安全整数校验与类型收窄【免费下载链接】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-toolkitisSafeInteger是 es-toolkit 的compatLodash 兼容模块提供的一个谓词函数用于判断任意值是否处于-(2^53 - 1)到(2^53 - 1)的安全整数区间内并可在 TypeScript 中将unknown收窄为number。本文基于官方兼容文档 isSafeInteger 展开结合 源码实现 与 测试用例 剖析其判定规则、类型谓词行为以及它在 es-toolkit 内部被哪些函数复用。读完本文你将掌握安全整数校验的边界条件、该函数在迁移 lodash 代码时的正确用法以及何时应直接使用原生Number.isSafeInteger。什么是安全整数JavaScript 的number类型基于 IEEE 754 双精度浮点数并非所有整数都能被精确表示。规范用Number.MAX_SAFE_INTEGER9007199254740991即2^53 - 1和Number.MIN_SAFE_INTEGER-9007199254740991标定了这个边界落在[-(2^53 - 1), 2^53 - 1]闭区间内的整数称为安全整数它们在 JavaScript 中可以被精确表示且不会有其他整数被舍入到同一位置超出该边界的值如Number.MAX_SAFE_INTEGER 1虽然看起来是整数但已经不能保证算术运算如递增、累加的精确性。因此安全整数同时要求两点值是整数排除小数、NaN、Infinity且在安全范围内。字符串3、BigInt的1n、数组、对象、null、undefined等一律返回false函数不做任何隐式类型转换。函数签名与用法文档中的函数签名为const result isSafeInteger(value);参数参数类型说明valueany源码签名为unknown待检查的任意值返回值返回类型为value is number这是一个 TypeScript类型谓词当返回true时TypeScript 会自动将value的类型收窄为number可以在if分支内安全地执行Math运算或传入要求number参数的函数。完整行为示例以下示例完整继承自官方文档覆盖安全整数、越界整数、非整数与特殊值四类情况import { isSafeInteger } from es-toolkit/compat; // 安全整数 isSafeInteger(3); // true isSafeInteger(-42); // true isSafeInteger(0); // true isSafeInteger(Number.MAX_SAFE_INTEGER); // true (9007199254740991) isSafeInteger(Number.MIN_SAFE_INTEGER); // true (-9007199254740991) // 安全范围之外的整数 isSafeInteger(Number.MAX_SAFE_INTEGER 1); // false isSafeInteger(Number.MIN_SAFE_INTEGER - 1); // false isSafeInteger(9007199254740992); // false // 非整数 isSafeInteger(3.14); // false isSafeInteger(3); // false isSafeInteger(1n); // false (BigInt) isSafeInteger([]); // false isSafeInteger({}); // false isSafeInteger(null); // false isSafeInteger(undefined); // false // 无穷大与 NaN isSafeInteger(Infinity); // false isSafeInteger(-Infinity); // false isSafeInteger(NaN); // false类型收窄的典型用法const value: unknown JSON.parse(3); if (isSafeInteger(value)) { // 此处 value 已被收窄为 number console.log(value * 2); // 合法 }测试用例 中专门有一条用例验证了这一类型谓词行为对应 spec 文件第 97-103 行的should work as a type predicate通过expectTypeOf(value).toEqualTypeOfnumber()在编译期断言收窄结果。源码剖析一个极薄的兼容包装从源码结构看这个兼容函数的实现非常克制isSafeInteger.ts 全文核心逻辑只有一行export function isSafeInteger(value: unknown): value is number { return Number.isSafeInteger(value); }几个值得注意的实现细节参数类型是unknown而非any调用方可以传入任意值而不产生类型错误函数内部直接委托给引擎原生的Number.isSafeInteger所有边界判定整数性、范围都由 JS 引擎保证返回值是类型谓词value is number这与实现解耦——即便运行时逻辑完全等价于Number.isSafeInteger(value)函数签名仍为调用者提供了静态类型收益这也是 Lodash 迁移场景中类型安全的关键导出路径该函数通过 compat 聚合入口src/compat/compat.ts从es-toolkit/compat包导出同时也在 browser 入口src/browser.ts中导出供浏览器构建使用。也就是说在运行时层面它没有任何额外算法其存在价值完全在于兼容 lodash 的 API 形状lodash 中_.isSafeInteger的等价物与提供类型谓词签名。为什么官方文档推荐使用Number.isSafeInteger文档开头有一条明确的 warningThisisSafeIntegerfunction operates slowly due to additional type checking overhead. Instead, use the faster and modernNumber.isSafeInteger.结合源码可以准确理解这条提示的含义兼容层的isSafeInteger本质上是一次函数调用转发——调用原生Number.isSafeInteger前需要经历一次额外的 JS 函数调用与参数检查开销。如果你不需要 lodash 迁移语义、也不需要value is number类型谓词直接在现代 JavaScript/TypeScript 环境中调用Number.isSafeInteger(value)是最快的写法Number.isSafeInteger(3); // true无额外包装调用选择建议可以归纳为从 lodash 迁移代码、希望保持isSafeInteger(...)调用习惯使用es-toolkit/compat的isSafeInteger并免费获得类型收窄新代码且无需类型谓词直接使用Number.isSafeInteger减少一次函数调用层。值得注意的是这种推荐原生 API的写法贯穿 es-toolkit 的 compat 文档体系——例如同目录下的 isInteger 同样只是Number.isInteger的薄封装风格保持一致。内部复用哪些函数依赖安全整数判定在仓库源码中可以确认Number.isSafeInteger这一判定并非只服务于对外 API它还被 es-toolkit 内部多个函数复用isLengthsrc/compat/predicate/isLength.ts核心入口在src/predicate/isLength.ts判断值是否为合法长度实现为Number.isSafeInteger(value) value 0即在安全整数基础上追加非负约束。可见isSafeInteger的语义是isLength的基础组成timessrc/compat/util/times.ts第 40 行在执行循环前用if (n 1 || !Number.isSafeInteger(n))校验迭代次数防止传入越界或非法的n导致循环异常。从源码结构看可以推断出 es-toolkit 内部在凡是需要对数值型输入做范围/合法性校验的位置长度、次数类参数都统一采用了安全整数判定isSafeInteger对外暴露的正是这一套判定标准。测试覆盖边界与类型收窄都有验证isSafeInteger.spec.ts 的测试用例与文档描述的行为一一对应覆盖了三类场景基本判定整数1返回true浮点1.1、BigInt1n、字符串1、数组、NaN、Infinity均返回false边界越界Number.MIN_SAFE_INTEGER - 2与Number.MAX_SAFE_INTEGER 2都返回false并用1.7976931348623157e308Number.MAX_VALUE这类极大数验证范围外判定非数值类型穷举对 falsy 值集合、true、Date、Error、{ a: 1 }、正则、Symbol 等逐一断言false确认函数不做隐式转换类型谓词编译期断言if (isSafeInteger(value))之后value等价于number。如果你在使用中遇到疑似边界行为可以直接对照该 spec 文件中的断言确认预期。小结isSafeInteger是 es-toolkit 兼容层中对齐 lodash API 的谓词函数判定规则为整数且在±(2^53 - 1)闭区间内不做隐式类型转换其返回类型value is number提供 TypeScript 类型收窄是迁移 lodash 代码时保持类型安全的关键实现上它是 Number.isSafeInteger 的薄封装官方文档明确建议在不需要 lodash 语义时直接使用原生Number.isSafeInteger以避免额外的函数调用开销该判定逻辑在库内部被 isLength、times 等函数复用是 es-toolkit 处理数值型参数校验的统一标准。【免费下载链接】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），仅供参考
