es-toolkit/compat nth() 详解：兼容 Lodash 的按索引取数组元素函数

es-toolkit/compat nth() 详解兼容 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导读nth()是 es-toolkit 兼容层es-toolkit/compat中用于按索引获取数组元素的函数它 1:1 复刻了 Lodash_.nth的行为支持负索引从数组末尾计数并针对越界、null/undefined输入等边界情况做了统一处理。本文将以 docs/compat/reference/array/nth.md 为核心结合 nth 源码 与其单元测试完整讲解nth()的签名、参数、返回值、边界行为以及底层实现原理并给出在实际项目中的使用与迁移建议。背景为什么需要nth以及何时不该用它nth属于es-toolkit/compat兼容层。正如 compat 介绍文档 所述es-toolkit/compat镜像了 Lodash 的接口与行为其存在的意义是让已有 Lodash 代码库无需改写调用点即可平滑迁移到 es-toolkit之后再逐步切换到严格类型的es-toolkit主包。因此nth的典型使用场景是旧代码迁移期——当代码中原本写的是_.nth(array, index)你可以把导入路径从lodash直接换成es-toolkit/compat行为保持一致。需要特别注意的是官方文档在函数开头就给出了明确的警告::: warning优先使用数组索引访问由于需要处理null/undefined输入以及整数转换nth函数的运行速度较慢。 请改用更快、更现代的数组索引访问方式array[index]或array.at(index)。也就是说如果你的项目没有历史包袱、并不是在迁移 Lodash 代码那么直接使用原生语法array[index]或array.at(index)即可——nth的存在意义是行为兼容而不是性能最优。这也是 es-toolkit 设计哲学的一部分兼容层为了对齐 Lodash 的隐式类型转换等行为会携带额外逻辑因此“略大、略慢”详见 docs/compat/intro.md 中 “How it differs fromes-toolkit” 一节。函数签名与类型定义nth的 TypeScript 签名如下const element nth(array, index);对应源码中的实际定义src/compat/array/nth.tsexport function nthT(array: ArrayLikeT | null | undefined, n 0): T | undefined参数说明参数类型是否可选说明arrayArrayLikeT \| null \| undefined必填要查询的数组或类数组对象indexnumber可选要获取元素的索引。为负数时从数组末尾计数。默认值为0返回值T | undefined返回指定索引处的元素如果索引越界返回undefined。值得留意的是默认值index省略时相当于nth(array, 0)即返回数组第一个元素这与 Lodash_.nth的默认行为一致。使用方式与代码示例从es-toolkit/compat导入import { nth } from es-toolkit/compat; const array [1, 2, 3begin▁of▁sentence , 4, 5]; // 正索引 nth(array, 1); // 2 // 负索引从末尾计数 nth(array, -1); // 5 nth(array, -2); // 4 // 越界索引 nth(array, 10); // undefined nth(array, -10); // undefinednull或undefined的输入null或undefined会被当作undefined处理import { nth } from es-toolkit/compat; nth(null, 0); // undefined nth(undefined, 0); // undefined按需导入独立入口与lodash/merge的形态类似compat 层的每个函数都拥有独立入口只加载该函数所需的文件而不是整个es-toolkit/compat模块。这在无法进行 tree-shaking 的环境如 CommonJSrequire()、React Native、无打包器直接在 Node.js 上运行中尤其有用参考 docs/compat/intro.md 的 “Importing individual functions” 一节import nth from es-toolkit/compat/nth;或 CommonJS 风格const nth require(es-toolkit/compat/nth);源码实现与底层原理完整的实现非常精简src/compat/array/nth.ts 全文 27 行export function nthT(array: ArrayLikeT | null | undefined, n 0): T | undefined { if (!isArrayLike(array) || array.length 0) { return undefined; } n toInteger(n); if (n 0) { n array.length; } return array[n]; }下面逐行拆解其内部逻辑并结合测试用例印证每一步行为。第一步isArrayLike校验与空数组短路if (!isArrayLike(array) || array.length 0) { return undefined; }isArrayLike的实现位于 src/compat/predicate/isArrayLike.tsexport function isArrayLike(value?: any): boolean { return value ! null typeof value ! function isLength((value as ArrayLikeunknown).length); }它要求三个条件同时成立value ! null排除null和undefinedtypeof value ! function函数永远不被视为类数组value.length是一个合法的“长度值”isLength即非负有限整数。这意味着nth(null, 0)和nth(undefined, 0)返回undefined对应文档示例与测试中的 “should returnundefinedfor empty arrays” 用例空数组[]直接返回undefined无需再做索引计算字符串也是合法的类数组因此nth(abc, 0) a、nth(abc, -1) c测试用例 “should support strings” 验证了这一点。第二步toInteger索引整数化n toInteger(n);toInteger的实现位于 src/compat/util/toInteger.tsexport function toInteger(value: any): number { const finite toFinite(value); const remainder finite % 1; return remainder ? finite - remainder : finite; }其行为链是toInteger → toFinite → toNumber小数会被向下取整nth(array, 1.6)等效于nth(array, 1)测试用例 “should coercento an integer” 验证了1.6 → b即索引 1 的结果字符串数字会被转换nth(array, 1)等效于nth(array, 1)false、NaN、空字符串等 falsy 值会被转为0即退化为取第一个元素Infinity会经toFinite收敛为Number.MAX_VALUE这必然越界从而返回undefined测试用例 “should returnundefinedfor non-indexes” 验证了Infinity与array.length都返回undefined。第三步负索引从末尾计数if (n 0) { n array.length; }当索引为负时将其加上数组长度转换为正向索引。例如nth([1, 2, 3, 4, 5], -1)n -1 5 4取到array[4] 5。测试用例 “should work with a negativen” 使用range(1, array.length 1)对[a,b,c,d]逐次取-1到-4验证结果为[d, c, b, a]。注意如果负索引的绝对值超过数组长度比如nth(array, -10)则n -10 5 -5array[-5]在 JavaScript 中读取到的是对象上的-5属性不存在因此返回undefined——这正是文档中“越界返回undefined”的体现。第四步返回元素return array[n];最终通过索引直接读取返回。整个过程没有做任何额外的“是否存在该索引”的显式判断而是依赖 JavaScript 数组越界访问天然返回undefined的特性。边界行为一览附测试佐证结合 src/compat/array/nth.spec.ts 中的全部用例可将nth的边界行为总结如下输入行为测试用例nth(array, index)正索引返回对应元素should get the nth element ofarraynth(array, -n)负索引从末尾计数返回元素should work with a negativennth(array, 1.6)/nth(array, 1)索引被整数化 / 字符串化转换should coercento an integernth(null, n)/nth(undefined, n)/nth([], n)返回undefinedshould returnundefinedfor empty arraysnth(abc, n)支持字符串类数组should support stringsnth(array, Infinity)/nth(array, array.length)返回undefined越界should returnundefinedfor non-indexes其中 “should returnundefinedfor non-indexes” 这个用例还揭示了一个细节测试特意给数组设置了array[-1] 3在数组对象上挂一个-1属性然后调用nth(array, -1)之外的越界场景验证nth不会误读这类非索引属性——因为负数索引经过n array.length之后已经不再是负数自然不会命中array[-1]这样的属性键。这说明nth的负索引处理是严格基于“真实数组位置”而非属性查找的。性能注意点与迁移建议新代码请直接用array.at(index)at是 ES2022 引入的原生方法同样支持负索引array.at(-1)即最后一个元素且没有任何类型转换开销。nth的额外成本主要来自isArrayLike校验和toInteger整数转换——文档明确提示这一点。迁移 Lodash 旧代码时把import { nth } from lodash改为import { nth } from es-toolkit/compat调用点无需改动行为完全一致后续可再逐步清理为原生at/索引访问。追求极致体积时使用按需入口es-toolkit/compat/nth或依赖打包器的 tree-shaking只打包该函数及其依赖isArrayLike、toInteger、toFinite、toNumber、isLength。小结nth是 es-toolkit 兼容层中一个“小而精”的函数27 行源码通过isArrayLike空值守卫、toInteger索引规范化、负索引长度换算三步完整复刻了 Lodash_.nth的语义包括空输入返回undefined、字符串类数组支持、小数与字符串索引的隐式转换等细节并有覆盖全面的单元测试作为行为契约。理解它的实现既能让你在迁移 Lodash 代码时放心替换也能帮你更清晰地认识到何时应该放弃它、改用原生array[index]或array.at(index)。【免费下载链接】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），仅供参考