es-toolkit/compat 的 isLength 详解用类型守卫精准校验 JavaScript 安全整数长度【免费下载链接】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-toolkitisLength是 es-toolkit 提供的谓词predicate函数用于判断一个值是否为合法的长度valid length。本文以 compat 版参考文档 为核心结合源码、测试与基准讲解其判定规则、TypeScript 类型守卫用法、与 lodash 的兼容关系以及在实际项目中校验数组/字符串length属性的完整方案。读完本文你将能准确区分安全整数与合法长度的边界并能在自己的代码中正确选用 es-toolkit 原版 或es-toolkit/compat版本。一、函数定位什么是合法长度在 JavaScript 中数组的length属性在规范层面被约束为无符号 32 位整数而 es-toolkit 的isLength采用更宽松也更符合日常语义的判定只要值是number类型、是非负整数、且不超过Number.MAX_SAFE_INTEGER即9007199254740991就认为是合法长度。compat 版文档给出的类型签名如下const result isLength(value);对应的参数与返回值项目说明参数valueany要检查是否为合法长度的值返回值boolean合法长度返回true否则返回false需要注意的是es-toolkit/compat与es-toolkit/predicate两个入口都导出了isLength且当前仓库中两者的实现完全一致详见下文源码分析。二者的区别在于入口归属es-toolkit/compat定位为 lodash 兼容层es-toolkit/predicate是 es-toolkit 的现代原生入口。二、快速上手与完整示例2.1 导入方式// 从 compat 兼容层导入与 lodash 行为对齐 import { isLength } from es-toolkit/compat; // 从 predicate 原生入口导入推荐性能更优 import { isLength } from es-toolkit/predicate;2.2 有效长度示例以下值都会返回true引用 compat 文档 的示例import { isLength } from es-toolkit/compat; // 有效长度 isLength(0); // true isLength(42); // true isLength(100); // true isLength(Number.MAX_SAFE_INTEGER); // true2.3 无效长度示例import { isLength } from es-toolkit/compat; // 无效长度 isLength(-1); // false (负数) isLength(1.5); // false (非整数) isLength(Number.MAX_SAFE_INTEGER 1); // false (超出安全整数范围) isLength(3); // false (字符串) isLength(null); // false isLength(undefined); // false isLength({}); // false isLength([]); // false从判定结果可以归纳出五类无效值负数、小数非整数、超过安全范围的整数、非number类型字符串、null、undefined、对象、数组等。三、核心判定规则源码级原理要彻底理解isLength最可靠的方式是直接阅读实现。compat 版源码 与 predicate 版源码 完全相同核心只有一行export function isLength(value?: any): boolean { return Number.isSafeInteger(value) (value as number) 0; }判定由两个条件的逻辑与构成Number.isSafeInteger(value)要求值是number类型、是整数、且绝对值不超过Number.MAX_SAFE_INTEGER。注意Number.isSafeInteger与Number.isInteger不同——后者不检查安全范围因此Number.MAX_SAFE_INTEGER 1这种不安全整数会被isSafeInteger拦截。(value as number) 0在通过第一关的前提下进一步要求值非负。这两个条件叠加恰好精确对应非负安全整数的语义也正是文档中valid length定义number类型、非负整数、不超过Number.MAX_SAFE_INTEGER的代码实现。3.1 边界情况推导基于上述两行实现可以直接推导出一些容易踩坑的边界行为输入判定过程结果-0Number.isSafeInteger(-0)为true且-0 0为truetrueNaN非整数falseInfinity/-Infinity非整数falsenew Number(3)包装对象对象类型非numberfalseNumber.MAX_SAFE_INTEGER安全整数且非负trueNumber.MAX_SAFE_INTEGER 1超出安全整数范围false其中-0会被判定为合法长度这是直接从实现逻辑可推出的行为包装对象如new Number(3)因为不是原始number类型而被拒绝这与值必须是 number 类型的定义一致。四、作为 TypeScript 类型守卫使用isLength的实现返回boolean且其类型签名在 predicate 版文档 中标注为对unknown参数做收窄。它可以直接充当 TypeScript 类型守卫把unknown或any收窄为numberimport { isLength } from es-toolkit/predicate; function processLength(value: unknown) { if (isLength(value)) { // 此处 value 已被收窄为 number 类型 console.log(value.toFixed(2)); } }这一点对从外部输入API 响应、用户配置、运行时数据中安全恢复数值语义特别有用先通过isLength做运行时校验再放心调用number类型的方法编译期与运行期都能得到保障。五、实际应用场景校验数组与字符串长度isLength最典型的用途是校验数组或字符串的length属性避免后续索引访问越界或依赖错误值。compat 文档给出了数组场景的示例import { isLength } from es-toolkit/compat; function validateArrayLength(arr: any[]) { if (isLength(arr.length)) { console.log(Array length ${arr.length} is valid); return true; } return false; } validateArrayLength([1, 2, 3]); // Array length 3 is valid同理可用于字符串isLength(str.length)可以确保length是安全非负整数后再进行substring、slice等操作。由于isLength以Number.MAX_SAFE_INTEGER为上限比数组规范意义上的2^32 - 1更宽松用于校验真实的length属性时不会产生误杀。六、compat 版本与 lodash 的兼容关系es-toolkit/compat的目标是提供与 lodash 行为对齐的兼容实现。这一点在 compat 版测试 中有明确证据——测试注释引用了 lodash 官方isLength测试用例的对应位置测试数据与 predicate 版测试 保持一致// src/compat/predicate/isLength.spec.ts it(should return true for lengths, () { const values [0, 3, Number.MAX_SAFE_INTEGER]; const expected values.map(() true); const actual values.map(isLength); expect(actual).toEqual(expected); }); it(should return false for non-lengths, () { const values [-1, 1, 1.1, Number.MAX_SAFE_INTEGER 1]; const expected values.map(() false); const actual values.map(isLength); expect(actual).toEqual(expected); });两组测试分别覆盖了合法长度0、3、Number.MAX_SAFE_INTEGER与非法长度负数、数字字符串、小数、不安全整数与文档示例完全对应。6.1 为什么 compat 文档建议改用原版compat 参考文档开头有一条醒目的警告warning核心意思是compat 版isLength因需要做 lodash 兼容处理而运行较慢建议改用更快的 es-toolkit 原生isLength并给出了 原版文档 的链接。从当前仓库的源码看两个版本的实现目前完全一致都是Number.isSafeInteger(value) value 0但在 es-toolkit 的项目定位中compat入口需要承载大量 lodash 兼容的边界逻辑与重导出成本整体更重而predicate入口是面向现代 JavaScript 的精简路径。因此新项目推荐直接使用es-toolkit/predicate的isLength只有当你正在从 lodash 迁移、需要保持代码行为与 lodash 完全一致时才使用es-toolkit/compat。七、性能对比基准仓库在 benchmarks/performance/isLength.bench.ts 中为isLength提供了 vitest bench 基准对三种实现进行同输入对比es-toolkit/isLength原生版es-toolkit/compat/isLength兼容版lodash/isLengthlodash 原版基准对同一组输入100、0、-1、1.5、Number.MAX_SAFE_INTEGER、Number.MAX_SAFE_INTEGER 1、100、true、null、undefined、{}、[]依次调用三种实现。这组输入恰好完整覆盖了合法长度 / 负数 / 小数 / 超范围整数 / 字符串 / 布尔 / null / undefined / 对象 / 数组等全部边界类别与文档示例、测试用例形成三方印证。如需查看历史基准结果可参考 docs/data/benchmark-results.json。八、与其他谓词函数的协作在 es-toolkit 内部isLength并非孤立存在它被其他谓词函数复用。例如 compat 版isArrayLike的实现就依赖了isLengthimport { isLength } from ../../predicate/isLength.ts; // ... return value ! null typeof value ! function isLength((value as ArrayLikeunknown).length);可以看到isArrayLike的判定链条中length属性是合法长度是类数组成立的必要条件。这体现了isLength作为基础谓词在 es-toolkit 内部被组合使用的方式——理解它也就理解了isArrayLike、isArrayLikeObject等上游函数的判定基础。九、小结isLength(value)用于判断值是否为合法长度number类型、非负整数、不超过Number.MAX_SAFE_INTEGER。实现仅一行Number.isSafeInteger(value) (value as number) 0两个条件缺一不可。它同时是 TypeScript 类型守卫可将unknown/any收窄为number适合校验来自外部的数组、字符串长度数据。两个入口es-toolkit/compat与es-toolkit/predicate当前实现一致compat 文档明确建议优先使用 es-toolkit 原版 isLength以获得更简洁、更快的现代实现。仓库内提供了 单元测试 与 三方性能基准可据此验证行为与性能。【免费下载链接】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），仅供参考