es-toolkit `initial` 完全指南：兼容版与原生版的取舍与源码解析

es-toolkitinitial完全指南：兼容版与原生版的取舍与源码解析

【免费下载链接】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

本文聚焦 es-toolkit 中initial函数的完整使用与实现原理。initial用于返回数组中除最后一个元素外的全部元素，是数组处理中高频使用的"去掉末尾"工具。通过阅读本文，你将掌握es-toolkit/compat兼容版与es-toolkit/array现代版的调用方式、边界行为差异，以及二者在源码层面的实现取舍，能够在实际项目中正确选择版本并规避性能陷阱。

一、initial是什么

initial接收一个数组（或数组类似对象），返回一个不包含最后一个元素的新数组。它与 lodash 的同名函数行为一致，是 es-toolkit 提供 Lodash 兼容 API 的一部分。

const result = initial(array);

该函数的官方说明与用法详见 initial（compat 参考文档） 与 initial（现代版参考文档）。

二、重要提示：优先使用 es-toolkit 现代版

es-toolkit 官方在兼容版文档中给出了明确警告：

请使用 es-toolkit 的 initial。此initial函数（指 compat 版本）由于ArrayLike对象的处理与数组转换过程，运行会更慢。

也就是说，默认场景下应优先从es-toolkit/array导入现代版initial，仅当项目需要迁移自 lodash、需要保持参数签名兼容（如支持ArrayLike、null、undefined）时才使用es-toolkit/compat版本。

三、基础用法

3.1 现代版es-toolkit/array的 initial

import { initial } from 'es-toolkit/array'; // 从数字数组中排除最后一个元素 const numbers = [1, 2, 3, 4, 5]; initial(numbers); // 返回: [1, 2, 3, 4] // 从字符串数组中排除最后一个元素 const strings = ['a', 'b', 'c']; initial(strings); // 返回: ['a', 'b'] // 仅含一个元素的数组返回空数组 const single = [42]; initial(single); // 返回: []

3.2 兼容版es-toolkit/compat的 initial

兼容版除了处理普通数组，还支持数组类似对象（ArrayLike）：

import { initial } from 'es-toolkit/compat'; // 从数字数组中排除最后一个元素 const numbers = [1, 2, 3, 4]; const result = initial(numbers); // result 为 [1, 2, 3] // 从字符串数组中排除最后一个元素 const strings = ['a', 'b', 'c', 'd']; const withoutLast = initial(strings); // withoutLast 为 ['a', 'b', 'c'] // 数组类似对象：{ 0: 'x', 1: 'y', 2: 'z', length: 3 } const arrayLike = { 0: 'x', 1: 'y', 2: 'z', length: 3 }; const items = initial(arrayLike); // items 为 ['x', 'y']

四、边界行为与返回规则

initial对空数组、单元素数组以及无效输入均做了安全处理：

import { initial } from 'es-toolkit/compat'; // 空数组返回空数组 const emptyArray: number[] = []; const result = initial(emptyArray); // result 为 [] // 单元素数组返回空数组 const singleItem = [42]; const onlyOne = initial(singleItem); // onlyOne 为 [] // null / undefined 返回空数组 initial(null); // [] initial(undefined); // []

参数与返回值

五、源码级原理剖析

5.1 现代版实现：一行slice(0, -1)

现代版位于 src/array/initial.ts，核心实现极为精简：

export function initial<T>(arr: readonly T[]): T[] { return arr.slice(0, -1); }

slice(0, -1)是原生方法，返回从索引 0 到倒数第一个元素（不含）之间的浅拷贝新数组。它天然满足"空数组返回空数组"与"单元素数组返回空数组"的语义（[].slice(0, -1)与[42].slice(0, -1)均得到[]），且不修改原数组。

5.2 现代版的 TypeScript 重载：元组类型推导

值得关注的是，现代版为元组（tuple）输入提供了多个重载，让类型推导更精确（见 src/array/initial.ts）：

• 单元素元组readonly [T]→ 返回[]（空数组类型）
• 空元组readonly []→ 返回[]
• 多元素元组readonly [...T[], U]→ 返回T[]（剔除最后一个元素后的类型）
• 普通数组readonly T[]→ 返回T[]

const array = ['apple', 'banana', 'cherry'] as const; const result = initial(array); // result 类型推导为 ['apple', 'banana']

5.3 兼容版实现：ArrayLike 处理带来额外开销

兼容版位于 src/compat/array/initial.ts：

import { initial as initialToolkit } from '../../array/initial.ts'; import { isArrayLike } from '../predicate/isArrayLike.ts'; export function initial<T>(arr: ArrayLike<T> | null | undefined): T[] { if (!isArrayLike(arr)) { return []; } return initialToolkit(Array.from(arr)); }

其执行流程为：

1. 用isArrayLike判断输入是否为数组类似对象，不合法（null/undefined/数字/布尔值/函数等）直接返回[]；
2. 通过Array.from(arr)将ArrayLike转换为真正的数组；
3. 委托给现代版initialToolkit执行slice(0, -1)。

正是第 2 步的Array.from转换（以及第 1 步的类型判断）导致兼容版比直接调用现代版更慢，这也是官方文档建议优先使用现代版的原因。

5.4 isArrayLike 判断规则

isArrayLike位于 src/compat/predicate/isArrayLike.ts：

export function isArrayLike(value?: any): boolean { return value != null && typeof value !== 'function' && isLength((value as ArrayLike<unknown>).length); }

判断三要素：非null/undefined、非函数、length属性为合法长度。因此字符串'123'（length为 3）、{ 0: 1, length: 3 }这类对象都被视为数组类似对象，而普通对象（无length）则被排除。

5.5 测试用例佐证

兼容版的测试见 src/compat/array/initial.spec.ts，它对齐了 lodash 的原始测试（文件注释中标注了参考来源），覆盖了以下关键场景：

// 排除最后一个元素 expect(initial([1, 2, 3])).toEqual([1, 2]); // 空数组返回空数组 expect(initial([])).toEqual([]); // 可作为 map 等方法的 iteratee 直接使用 const array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]; const actual = array.map(initial); // [[1, 2], [4, 5], [7, 8]] // null / undefined 返回空数组 expect(initial(null)).toEqual([]); // 非数组类似对象（数字、布尔值）返回空数组 expect(initial(1)).toEqual([]); expect(initial(true)).toEqual([]); // 支持数组类似对象、字符串与 arguments 对象 expect(initial({ 0: 1, 1: null, 2: 3, length: 3 })).toEqual([1, null]); expect(initial('123')).toEqual(['1', '2']); expect(initial(args)).toEqual([1, 2]);

现代版测试见 src/array/initial.spec.ts，额外验证了大数组（1000 个元素）与嵌套数组的处理：

// 大数组：1000 个元素返回前 999 个 const largeArray = Array(1000).fill(0).map((_, i) => i); expect(initial(largeArray)).toEqual(Array(999).fill(0).map((_, i) => i)); // 嵌套数组 const nestedArray = [[3, 1], [3, 2], [3, 3]]; expect(initial(nestedArray)).toEqual([[3, 1], [3, 2]]);

六、两个版本的选型建议

结论：新代码一律优先从es-toolkit/array导入；只有当你需要处理ArrayLike对象、或正在从 lodash 迁移并希望保持原有调用语义时，才使用es-toolkit/compat版本。若兼容版传入的是普通数组，也可自行先做Array.isArray判断再调用现代版以规避转换开销。

【免费下载链接】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