es-toolkit/compat 的 range 函数完全指南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-toolkit本篇技术指南聚焦于 es-toolkit 的 Lodash 兼容入口es-toolkit/compat中的range函数日文文档docs/ja/compat/reference/math/range.md。你将掌握range的三种调用签名单参、双参、三参、自动步长推断、零步长与小步步长的边界行为、以及作为map等函数 iteratee 的 guard 用法并深入源码层理解其参数归一化toFinite与迭代调用识别isIterateeCall的底层实现最终学会在 Lodash 迁移场景中正确选型。一、函数定位Lodash 兼容的rangees-toolkit/compat是 es-toolkit 为平滑迁移 Lodash 而提供的兼容入口。其中的range函数用于创建数值范围数组行为与_.range保持一致const numbers range(start, end, step);需要特别注意的是该 compat 版本在 文档开头即给出警告由于它需要处理复杂的参数形态与类型转换如字符串数字、NaN、Infinity、假值等运行速度比 es-toolkit 原生range更慢。文档明确建议追求性能时应改用更快速、更现代的 es-toolkit 原生 range从es-toolkit/math导入。换句话说compat版本的存在价值是行为兼容优先而非性能优先。二、三种调用签名与基本用法1.range(end)从 0 开始、步长为 1只传一个参数时end被当作范围的终点不含起点固定为 0步长自动为 1import { range } from es-toolkit/compat; range(4); // Returns: [0, 1, 2, 3] range(0); // Returns: [] range(-4); // Returns: [0, -1, -2, -3]可以看到当end为负数时步长会自动推断为 -1向负方向生成序列。当end为 0 时返回空数组。2.range(start, end)从 start 到 end自动推断步长传入起止两个参数时步长根据start end自动确定为 1 或 -1无需手动指定方向import { range } from es-toolkit/compat; range(1, 5); // Returns: [1, 2, 3, 4] range(5, 1); // Returns: [5, 4, 3, 2] (自動的に-1ずつ減少) range(-2, 3); // Returns: [-2, -1, 0, 1, 2]起点包含在结果中终点不包含。3.range(start, end, step)显式指定步长三参数形态完全由你控制步长支持正负方向、零步长以及小数步长import { range } from es-toolkit/compat; range(0, 20, 5); // Returns: [0, 5, 10, 15] range(0, -4, -1); // Returns: [0, -1, -2, -3] range(1, 4, 0); // Returns: [1, 1, 1]其中step 0是一个值得注意的 Lodash 兼容行为结果数组中会不断重复start的值循环次数由(end - start) / 1向上取整决定。这与原生range见第四节会直接抛错的行为截然不同。小数步长同样被支持import { range } from es-toolkit/compat; range(0, 1, 0.2); // Returns: [0, 0.2, 0.4, 0.6, 0.8] range(1, 0, -0.25); // Returns: [1, 0.75, 0.5, 0.25]4. 参数与返回值一览参数类型说明startnumber范围的起始值包含。当不传end时该值被当作end使用endnumber可选范围的结束值不包含stepnumber可选递增/递减步长默认根据方向取 1 或 -1返回值number[]即按指定范围与步长生成的数值数组。三、作为 iteratee 使用guard 参数机制range还可以直接作为map等方法的回调iteratee使用此时会自动命中 guard 分支import { range } from es-toolkit/compat; [1, 2, 3].map(range); // Returns: [[0], [0, 1], [0, 1, 2]]其原理在源码 src/compat/math/range.ts 中清晰可见——实现为函数重载当传入三个参数(end, index, guard)时若step存在但不是数字且满足isIterateeCall(start, end, step)则判定为 iteratee 调用将end与step重置为undefined从而退回仅end的处理路径export function range(start: number, end?: PropertyKey, step?: any): number[] { // Enables use as an iteratee for methods like _.map. if (step typeof step ! number isIterateeCall(start, end, step)) { end step undefined; } // ... }isIterateeCall定义在 src/compat/_internal/isIterateeCall.ts其判定逻辑是第三个参数object必须是一个对象isObject若第二个参数index是数字则它必须是该对象类数组的有效索引借助 isIndex 校验非负整数且小于长度若index是字符串则它必须是对象上的属性最后校验object[index] value通过eq比较。只有在以上条件全部满足时才认定是一次 iteratee 调用。对应的测试在 src/compat/math/range.spec.ts 中验证了数组与对象两种集合map场景均能得到[[0], [0, 1], [0, 1, 2]]。四、源码级剖析compat 版为何慢而兼容1. 参数归一化toFinitecompat 版的第一步是把所有参数强制转为有限数字调用 src/compat/util/toFinite.tsstart toFinite(start); if (end undefined) { end start; start 0; } else { end toFinite(end); } step step undefined ? (start end ? 1 : -1) : toFinite(step);toFinite的处理规则包括假值null、undefined、、false、0统一归一为 0-0会被保留字符串数字如1经toNumber转为数字Infinity/-Infinity被钳制为Number.MAX_VALUE的正负值NaN归一为 0。这正是测试 src/compat/math/range.spec.ts 中断言的range(1)、range(0, 1)、range(0, 1, 1)均能给出合理结果的原因——它们分别返回[[0], [0], [0]]而range(NaN)与range(NaN, NaN)返回空数组。相比之下原生range不做这些转换因此更快。2. 长度计算与数组填充步长确定后结果长度通过如下公式计算const length Math.max(Math.ceil((end - start) / (step || 1)), 0); const result new Array(length); for (let index 0; index length; index) { result[index] start; start step; } return result;几个关键点step || 1使得step 0时按步长 1 计算长度从而产生重复start的序列对应range(1, 4, 0)返回[1, 1, 1]当step绝对值大于区间跨度时Math.ceil后长度可能为 1测试 range.spec.ts 验证range(1, 5, 20)返回[1]负向区间配合负步长同样成立如range(21, 10, -3)返回[21, 18, 15, 12]使用new Array(length)预分配容量避免逐个push带来的扩容开销-0起始值会被保留测试 range.spec.ts 验证1 / actual[0]为-Infinity。五、与原生range的关键差异与选型建议es-toolkit 原生rangesrc/math/range.ts与 compat 版本在 API 相似但语义上有明确区别对比项compatrange原生range导入路径es-toolkit/compates-toolkit/math见 文档参数转换经toFinite接受字符串、NaN等直接使用数字step 0返回重复start的数组抛出错误小数步长支持要求非零整数否则抛错性能因复杂参数处理与类型转换而较慢更快速、更现代原生实现 src/math/range.ts 中明确通过Number.isInteger(step) || step 0校验并抛出The step value must be a non-zero integer.同时默认步长为 1不根据方向自动推断为 -1元素生成采用start i * step的乘法累加方式不做 iteratee guard 处理。选型建议正在从 Lodash 迁移、需要一行不改地保持既有_.range行为含零步长、字符串参数等历史怪癖时使用es-toolkit/compat版本新写代码、对性能敏感例如在热循环中生成索引序列时优先使用es-toolkit/math的原生range并遵守其step 必须为非零整数的约束日常生成连续索引range(10)得到[0..9]或分页序号range(1, 11)得到1..10时两种版本均可胜任此时原生版本是更优选择。六、行为边界速查结合 源码 与 测试用例以下是 compat 版range的完整行为边界清单单参负数range(-4)→[0, -1, -2, -3]步长自动为 -1双参降序range(5, 1)→[5, 4, 3, 2]无需显式负步长零步长range(1, 4, 0)→[1, 1, 1]步长超过区间range(1, 5, 20)→[1]负向大步长range(21, 10, -3)→[21, 18, 15, 12]假值 startrange()、range(null)等均按 0 处理range()返回[]类型强制range(1)→[0]range(0, 1)→[0]range(0, 1, 1)→[0]range(NaN)→[]iteratee[1, 2, 3].map(range)→[[0], [0, 1], [0, 1, 2]]且对数组与普通对象集合均生效。掌握这些边界行为你就能在 Lodash 迁移与日常开发中准确预判range的输出并在需要更高性能时果断切换到原生版本。【免费下载链接】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），仅供参考
es-toolkit/compat 的 range 函数完全指南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-toolkit本篇技术指南聚焦于 es-toolkit 的 Lodash 兼容入口es-toolkit/compat中的range函数日文文档docs/ja/compat/reference/math/range.md。你将掌握range的三种调用签名单参、双参、三参、自动步长推断、零步长与小步步长的边界行为、以及作为map等函数 iteratee 的 guard 用法并深入源码层理解其参数归一化toFinite与迭代调用识别isIterateeCall的底层实现最终学会在 Lodash 迁移场景中正确选型。一、函数定位Lodash 兼容的rangees-toolkit/compat是 es-toolkit 为平滑迁移 Lodash 而提供的兼容入口。其中的range函数用于创建数值范围数组行为与_.range保持一致const numbers range(start, end, step);需要特别注意的是该 compat 版本在 文档开头即给出警告由于它需要处理复杂的参数形态与类型转换如字符串数字、NaN、Infinity、假值等运行速度比 es-toolkit 原生range更慢。文档明确建议追求性能时应改用更快速、更现代的 es-toolkit 原生 range从es-toolkit/math导入。换句话说compat版本的存在价值是行为兼容优先而非性能优先。二、三种调用签名与基本用法1.range(end)从 0 开始、步长为 1只传一个参数时end被当作范围的终点不含起点固定为 0步长自动为 1import { range } from es-toolkit/compat; range(4); // Returns: [0, 1, 2, 3] range(0); // Returns: [] range(-4); // Returns: [0, -1, -2, -3]可以看到当end为负数时步长会自动推断为 -1向负方向生成序列。当end为 0 时返回空数组。2.range(start, end)从 start 到 end自动推断步长传入起止两个参数时步长根据start end自动确定为 1 或 -1无需手动指定方向import { range } from es-toolkit/compat; range(1, 5); // Returns: [1, 2, 3, 4] range(5, 1); // Returns: [5, 4, 3, 2] (自動的に-1ずつ減少) range(-2, 3); // Returns: [-2, -1, 0, 1, 2]起点包含在结果中终点不包含。3.range(start, end, step)显式指定步长三参数形态完全由你控制步长支持正负方向、零步长以及小数步长import { range } from es-toolkit/compat; range(0, 20, 5); // Returns: [0, 5, 10, 15] range(0, -4, -1); // Returns: [0, -1, -2, -3] range(1, 4, 0); // Returns: [1, 1, 1]其中step 0是一个值得注意的 Lodash 兼容行为结果数组中会不断重复start的值循环次数由(end - start) / 1向上取整决定。这与原生range见第四节会直接抛错的行为截然不同。小数步长同样被支持import { range } from es-toolkit/compat; range(0, 1, 0.2); // Returns: [0, 0.2, 0.4, 0.6, 0.8] range(1, 0, -0.25); // Returns: [1, 0.75, 0.5, 0.25]4. 参数与返回值一览参数类型说明startnumber范围的起始值包含。当不传end时该值被当作end使用endnumber可选范围的结束值不包含stepnumber可选递增/递减步长默认根据方向取 1 或 -1返回值number[]即按指定范围与步长生成的数值数组。三、作为 iteratee 使用guard 参数机制range还可以直接作为map等方法的回调iteratee使用此时会自动命中 guard 分支import { range } from es-toolkit/compat; [1, 2, 3].map(range); // Returns: [[0], [0, 1], [0, 1, 2]]其原理在源码 src/compat/math/range.ts 中清晰可见——实现为函数重载当传入三个参数(end, index, guard)时若step存在但不是数字且满足isIterateeCall(start, end, step)则判定为 iteratee 调用将end与step重置为undefined从而退回仅end的处理路径export function range(start: number, end?: PropertyKey, step?: any): number[] { // Enables use as an iteratee for methods like _.map. if (step typeof step ! number isIterateeCall(start, end, step)) { end step undefined; } // ... }isIterateeCall定义在 src/compat/_internal/isIterateeCall.ts其判定逻辑是第三个参数object必须是一个对象isObject若第二个参数index是数字则它必须是该对象类数组的有效索引借助 isIndex 校验非负整数且小于长度若index是字符串则它必须是对象上的属性最后校验object[index] value通过eq比较。只有在以上条件全部满足时才认定是一次 iteratee 调用。对应的测试在 src/compat/math/range.spec.ts 中验证了数组与对象两种集合map场景均能得到[[0], [0, 1], [0, 1, 2]]。四、源码级剖析compat 版为何慢而兼容1. 参数归一化toFinitecompat 版的第一步是把所有参数强制转为有限数字调用 src/compat/util/toFinite.tsstart toFinite(start); if (end undefined) { end start; start 0; } else { end toFinite(end); } step step undefined ? (start end ? 1 : -1) : toFinite(step);toFinite的处理规则包括假值null、undefined、、false、0统一归一为 0-0会被保留字符串数字如1经toNumber转为数字Infinity/-Infinity被钳制为Number.MAX_VALUE的正负值NaN归一为 0。这正是测试 src/compat/math/range.spec.ts 中断言的range(1)、range(0, 1)、range(0, 1, 1)均能给出合理结果的原因——它们分别返回[[0], [0], [0]]而range(NaN)与range(NaN, NaN)返回空数组。相比之下原生range不做这些转换因此更快。2. 长度计算与数组填充步长确定后结果长度通过如下公式计算const length Math.max(Math.ceil((end - start) / (step || 1)), 0); const result new Array(length); for (let index 0; index length; index) { result[index] start; start step; } return result;几个关键点step || 1使得step 0时按步长 1 计算长度从而产生重复start的序列对应range(1, 4, 0)返回[1, 1, 1]当step绝对值大于区间跨度时Math.ceil后长度可能为 1测试 range.spec.ts 验证range(1, 5, 20)返回[1]负向区间配合负步长同样成立如range(21, 10, -3)返回[21, 18, 15, 12]使用new Array(length)预分配容量避免逐个push带来的扩容开销-0起始值会被保留测试 range.spec.ts 验证1 / actual[0]为-Infinity。五、与原生range的关键差异与选型建议es-toolkit 原生rangesrc/math/range.ts与 compat 版本在 API 相似但语义上有明确区别对比项compatrange原生range导入路径es-toolkit/compates-toolkit/math见 文档参数转换经toFinite接受字符串、NaN等直接使用数字step 0返回重复start的数组抛出错误小数步长支持要求非零整数否则抛错性能因复杂参数处理与类型转换而较慢更快速、更现代原生实现 src/math/range.ts 中明确通过Number.isInteger(step) || step 0校验并抛出The step value must be a non-zero integer.同时默认步长为 1不根据方向自动推断为 -1元素生成采用start i * step的乘法累加方式不做 iteratee guard 处理。选型建议正在从 Lodash 迁移、需要一行不改地保持既有_.range行为含零步长、字符串参数等历史怪癖时使用es-toolkit/compat版本新写代码、对性能敏感例如在热循环中生成索引序列时优先使用es-toolkit/math的原生range并遵守其step 必须为非零整数的约束日常生成连续索引range(10)得到[0..9]或分页序号range(1, 11)得到1..10时两种版本均可胜任此时原生版本是更优选择。六、行为边界速查结合 源码 与 测试用例以下是 compat 版range的完整行为边界清单单参负数range(-4)→[0, -1, -2, -3]步长自动为 -1双参降序range(5, 1)→[5, 4, 3, 2]无需显式负步长零步长range(1, 4, 0)→[1, 1, 1]步长超过区间range(1, 5, 20)→[1]负向大步长range(21, 10, -3)→[21, 18, 15, 12]假值 startrange()、range(null)等均按 0 处理range()返回[]类型强制range(1)→[0]range(0, 1)→[0]range(0, 1, 1)→[0]range(NaN)→[]iteratee[1, 2, 3].map(range)→[[0], [0, 1], [0, 1, 2]]且对数组与普通对象集合均生效。掌握这些边界行为你就能在 Lodash 迁移与日常开发中准确预判range的输出并在需要更高性能时果断切换到原生版本。【免费下载链接】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），仅供参考
