es-toolkit/compat 的 flatten 深度解析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导读flatten是 es-toolkit 兼容层es-toolkit/compat中面向 Lodash 用户提供的数组展平函数它按 Lodash 语义将嵌套数组只展平一层并完整支持arguments对象、Symbol.isConcatSpreadable对象、类数组ArrayLike以及null/undefined等特殊输入。本文将围绕 docs/compat/reference/array/flatten.md 展开先给出可直接运行的用法示例再深入 flatten.ts 与 flattenDepth.ts 的源码剖析其判定逻辑最后对比 es-toolkit 原生flatten的性能差异与取舍帮助你准确选用合适的 API。一、flatten是什么Lodash 兼容版的单层展平flatten的作用是将一个数组按一层深度展平只解开最外层的嵌套更深层的数组原样保留在结果中。import { flatten } from es-toolkit/compat; flatten([1, [2, [3, [4]], 5]]); // Result: [1, 2, [3, [4]], 5]从输出可以看到[3, [4]]这一层并没有被继续展开——这正是「单层展平」与flattenDeep无限深度展平的核心区别。与 Lodash 的_.flatten一样compat 版flatten的定位是逐字兼容 Lodash 的输入输出语义因此它需要处理大量 Lodash 特有的边界输入详见下文第三节。它的完整函数签名定义在 src/compat/array/flatten.tsexport function flattenT(array: ArrayLikeT | readonly T[] | null | undefined): T[] { return flattenDepth(array as ListOfRecursiveArraysOrValuesT | null | undefined, 1); }可以看到flatten本身只是一个薄封装把深度固定为1后委托给flattenDepth执行真正的展平逻辑。二、安装与快速上手安装es-toolkit 是一个 npm 包安装后即可使用npm install es-toolkit兼容层 API 通过子路径es-toolkit/compat引入与原生 APIes-toolkit或es-toolkit/array相互独立import { flatten } from es-toolkit/compat;基础用法// 基础单层展平 flatten([1, [2, [3, [4]], 5]]); // Result: [1, 2, [3, [4]], 5]// 空数组与纯一维数组 flatten([]); // [] flatten([1, 2, 3]); // [1, 2, 3]三、核心行为完整覆盖 Lodash 的边界输入语义原文档明确强调compat 版flatten除了基础展平外还针对以下特殊输入提供了与 Lodash 一致的兼容处理这也是它区别于原生flatten的关键所在。1. 支持arguments对象函数内部的arguments对象会被当作数组一样展平import { flatten } from es-toolkit/compat; function example() { return flatten(arguments); } example(1, [2, 3], [[4]]); // Result: [1, 2, 3, [4]]arguments中的元素1、[2, 3]、[[4]]被逐项取出其中[2, 3]被展开[[4]]只展开到[4]单层符合预期。2. 支持带Symbol.isConcatSpreadable的对象任何带有真值Symbol.isConcatSpreadable的对象其索引属性会被当作数组元素展开const spreadable { 0: a, 1: b, length: 2, [Symbol.isConcatSpreadable]: true }; flatten([1, spreadable, 3]); // Result: [1, a, b, 3]这与原生Array.prototype.concat的展开规则一致是 Lodash 兼容行为的重要一环。3.null与undefined视为空数组import { flatten } from es-toolkit/compat; flatten(null); // [] flatten(undefined); // [] flatten([]); // []传入null或undefined不会抛错而是返回空数组保证了与 Lodash 一致的容错性。4. 稀疏数组按稠密数组处理测试用例 flatten.spec.ts 验证了稀疏数组如Array(3)会被填充为显式的undefined元素const array [[1, 2, 3], Array(3)]; flatten(array); // Expected: [1, 2, 3, undefined, undefined, undefined] // 且结果中 4 in actual 为 true索引 4 真实存在5. 支持类数组ArrayLike与字符串compat 版flatten接受ArrayLikeT输入包括字符串和普通类数组对象flatten({ 0: [1, 2, 3], length: 1 }); // [1, 2, 3] flatten(123); // [1, 2, 3] flatten(arguments); // [1, 2, 3]函数调用时传入 1,2,3而非类数组对象如{ 0: a }没有合法length则返回空数组flatten({ 0: a } as any); // []参数与返回值项目说明arrayArrayLikeT \| null \| undefined要展平的数组或类数组允许为null/undefined返回值T[]展平一层后的新数组原数组不会被修改四、源码剖析flatten底层到底做了什么1. 委托链flatten→flattenDepthflatten把「展平一层」这一语义翻译为flattenDepth(array, 1)真正的算法实现在 src/compat/array/flattenDepth.tsexport function flattenDepthT(array: ListOfRecursiveArraysOrValuesT | null | undefined, depth 1): T[] { if (!isArrayLike(array)) { return []; } const result: T[] []; const flooredDepth Math.floor(depth); const recursive (arr: readonly T[], currentDepth: number) { for (let i 0; i arr.length; i) { const item arr[i]; if (isFlattenable(item) currentDepth flooredDepth) { recursive(item as T[], currentDepth 1); } else { result.push(item); } } }; recursive(Array.from(array) as T[], 0); return result; }关键点非类数组直接返回[]这是对null/undefined/普通对象容错的第一道闸门由isArrayLike判定。深度取整Math.floor(depth)意味着flattenDepth(arr, 1.9)等价于深度1。递归展开只有当当前元素「可被展平」且「未超过深度上限」时才递归否则原样push。2. 可展平判定isFlattenablecompat 版展平哪些东西取决于内部的isFlattenable判定同样位于 src/compat/array/flattenDepth.tsfunction isFlattenable(value: unknown): boolean { return isArray(value) || isArguments(value) || Boolean(value (value as any)[Symbol.isConcatSpreadable]); }这条判定同时覆盖了第三节中的三类特殊输入真正的数组isArray、arguments对象isArguments、以及带真值Symbol.isConcatSpreadable的对象。输入类型声明ListOfRecursiveArraysOrValuesT定义在 src/compat/_internal/ListOfRecursiveArraysOrValues.ts即ArrayLikeT | RecursiveArrayT。3. 兼容层内部还有一个针对类数组的辅助函数在 src/compat/_internal/flattenArrayLike.ts 中还有一个flattenArrayLike专门把一组类数组对象逐项拼接为普通数组export function flattenArrayLikeT(values: ArrayArrayLikeT): T[] { const result: T[] []; for (let i 0; i values.length; i) { const arrayLike values[i]; if (!isArrayLikeObject(arrayLike)) { continue; } for (let j 0; j arrayLike.length; j) { result.push(arrayLike[j] as T); } } return result; }从源码结构看它服务于 compat 层内部对类数组的通用拼接需求体现了兼容层「处处以类数组为输入基础」的设计取向。五、对比compat 版 vs es-toolkit 原生flatten原文档在开头就给出了一条明确的性能警告compat 版flatten因需要处理null/undefined与ArrayLike类型而较慢建议改用 es-toolkit 原生flatten。原生flatten的实现es-toolkit 原生flatten位于 src/array/flatten.ts它是面向现代 JavaScript 的精简实现export function flattenT, D extends number 1(arr: readonly T[], depth 1 as D): ArrayFlatArrayT[], D { const result: ArrayFlatArrayT[], D []; const flooredDepth Math.floor(depth); const recursive (arr: readonly T[], currentDepth: number) { for (let i 0; i arr.length; i) { const item arr[i]; if (Array.isArray(item) currentDepth flooredDepth) { recursive(item, currentDepth 1); } else { result.push(item as FlatArrayT[], D); } } }; recursive(arr, 0); return result; }两者的差异可以总结为下表维度compat 版flatten原生flattenes-toolkit/array入口es-toolkit/compates-toolkit/es-toolkit/array输入类型ArrayLikeT \| null \| undefinedreadonly T[]深度参数固定为 1由flattenDepth支撑可选depth默认 1支持任意深度可展平判定isArray/isArguments/Symbol.isConcatSpreadable仅Array.isArray容错行为null/undefined返回[]类数组、arguments 均可处理要求数组输入逻辑更少性能较慢判定分支多、需Array.from转换更快仅内建Array.isArray分支原生版本的完整文档见 docs/reference/array/flatten.md其用法为import { flatten } from es-toolkit/array; const array [1, [2, 3], [4, [5, 6]]]; flatten(array); // [1, 2, 3, 4, [5, 6]] flatten(array, 2); // [1, 2, 3, 4, 5, 6]选择建议在全新代码中优先使用原生flatten仅当需要从 Lodash 迁移、或确实依赖 arguments/类数组/Symbol.isConcatSpreadable等兼容语义时才使用es-toolkit/compat版本。六、测试验证compat 语义有据可查compat 版flatten的行为由 src/compat/array/flatten.spec.ts 中的 Vitest 用例逐一锁定主要包括arguments 对象展平flatten([args, [args]])结果为[1, 2, 3, args]稀疏数组稠密化[[1, 2, 3], Array(3)]展平后补齐 3 个显式undefinedSymbol.isConcatSpreadable对象{ 0: a, length: 1, [Symbol.isConcatSpreadable]: true }展平为[a]空数组嵌套[[], [[]], [[], [[[]]]]]展平为[[], [], [[[]]]]非类数组返回空数组flatten({ 0: a })返回[]类数组与字符串flatten({ 0: [1, 2, 3], length: 1 })、flatten(123)、flatten(args)均按预期输出。这些用例直接印证了本文第三节描述的每一项兼容行为可作为迁移或回归测试时的参考基线。七、相关 API从flatten延伸的展平家族compat 层围绕展平提供了一组配套函数全部位于 src/compat/array 目录下函数说明实现文件flatten只展平一层兼容 arguments/类数组/Symbol.isConcatSpreadableflatten.tsflattenDepth展平到指定深度depth默认为 1是flatten的底层实现flattenDepth.tsflattenDeep无限深度展平等价于flattenDepth(array, Infinity)flattenDeep.tsflattenDeep的实现非常简洁export function flattenDeepT(array: ListOfRecursiveArraysOrValuesT | null | undefined) { return flattenDepth(array, Infinity) as any; }它们的组合关系是flatten与flattenDeep都只是flattenDepth在不同深度参数下的特例理解了flattenDepth的递归算法就等于理解了整个 compat 展平家族。结语es-toolkit 的 compat 版flatten是一份「语义先行」的 Lodash 兼容实现它牺牲了一部分性能换来对arguments、类数组、Symbol.isConcatSpreadable、null/undefined等 Lodash 生态边界输入的完整支持。如果你正在从 Lodash 迁移到 es-toolkit直接替换_.flatten即可得到一致的结果而如果是在新项目里追求极致性能则应选择 src/array/flatten.ts 中的原生实现。无论走哪条路径都建议结合 flatten.spec.ts 中的测试用例验证你的迁移行为确保边界场景万无一失。【免费下载链接】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 的 flatten 深度解析：Lodash 兼容单层数组展平与源码原理
es-toolkit/compat 的 flatten 深度解析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导读flatten是 es-toolkit 兼容层es-toolkit/compat中面向 Lodash 用户提供的数组展平函数它按 Lodash 语义将嵌套数组只展平一层并完整支持arguments对象、Symbol.isConcatSpreadable对象、类数组ArrayLike以及null/undefined等特殊输入。本文将围绕 docs/compat/reference/array/flatten.md 展开先给出可直接运行的用法示例再深入 flatten.ts 与 flattenDepth.ts 的源码剖析其判定逻辑最后对比 es-toolkit 原生flatten的性能差异与取舍帮助你准确选用合适的 API。一、flatten是什么Lodash 兼容版的单层展平flatten的作用是将一个数组按一层深度展平只解开最外层的嵌套更深层的数组原样保留在结果中。import { flatten } from es-toolkit/compat; flatten([1, [2, [3, [4]], 5]]); // Result: [1, 2, [3, [4]], 5]从输出可以看到[3, [4]]这一层并没有被继续展开——这正是「单层展平」与flattenDeep无限深度展平的核心区别。与 Lodash 的_.flatten一样compat 版flatten的定位是逐字兼容 Lodash 的输入输出语义因此它需要处理大量 Lodash 特有的边界输入详见下文第三节。它的完整函数签名定义在 src/compat/array/flatten.tsexport function flattenT(array: ArrayLikeT | readonly T[] | null | undefined): T[] { return flattenDepth(array as ListOfRecursiveArraysOrValuesT | null | undefined, 1); }可以看到flatten本身只是一个薄封装把深度固定为1后委托给flattenDepth执行真正的展平逻辑。二、安装与快速上手安装es-toolkit 是一个 npm 包安装后即可使用npm install es-toolkit兼容层 API 通过子路径es-toolkit/compat引入与原生 APIes-toolkit或es-toolkit/array相互独立import { flatten } from es-toolkit/compat;基础用法// 基础单层展平 flatten([1, [2, [3, [4]], 5]]); // Result: [1, 2, [3, [4]], 5]// 空数组与纯一维数组 flatten([]); // [] flatten([1, 2, 3]); // [1, 2, 3]三、核心行为完整覆盖 Lodash 的边界输入语义原文档明确强调compat 版flatten除了基础展平外还针对以下特殊输入提供了与 Lodash 一致的兼容处理这也是它区别于原生flatten的关键所在。1. 支持arguments对象函数内部的arguments对象会被当作数组一样展平import { flatten } from es-toolkit/compat; function example() { return flatten(arguments); } example(1, [2, 3], [[4]]); // Result: [1, 2, 3, [4]]arguments中的元素1、[2, 3]、[[4]]被逐项取出其中[2, 3]被展开[[4]]只展开到[4]单层符合预期。2. 支持带Symbol.isConcatSpreadable的对象任何带有真值Symbol.isConcatSpreadable的对象其索引属性会被当作数组元素展开const spreadable { 0: a, 1: b, length: 2, [Symbol.isConcatSpreadable]: true }; flatten([1, spreadable, 3]); // Result: [1, a, b, 3]这与原生Array.prototype.concat的展开规则一致是 Lodash 兼容行为的重要一环。3.null与undefined视为空数组import { flatten } from es-toolkit/compat; flatten(null); // [] flatten(undefined); // [] flatten([]); // []传入null或undefined不会抛错而是返回空数组保证了与 Lodash 一致的容错性。4. 稀疏数组按稠密数组处理测试用例 flatten.spec.ts 验证了稀疏数组如Array(3)会被填充为显式的undefined元素const array [[1, 2, 3], Array(3)]; flatten(array); // Expected: [1, 2, 3, undefined, undefined, undefined] // 且结果中 4 in actual 为 true索引 4 真实存在5. 支持类数组ArrayLike与字符串compat 版flatten接受ArrayLikeT输入包括字符串和普通类数组对象flatten({ 0: [1, 2, 3], length: 1 }); // [1, 2, 3] flatten(123); // [1, 2, 3] flatten(arguments); // [1, 2, 3]函数调用时传入 1,2,3而非类数组对象如{ 0: a }没有合法length则返回空数组flatten({ 0: a } as any); // []参数与返回值项目说明arrayArrayLikeT \| null \| undefined要展平的数组或类数组允许为null/undefined返回值T[]展平一层后的新数组原数组不会被修改四、源码剖析flatten底层到底做了什么1. 委托链flatten→flattenDepthflatten把「展平一层」这一语义翻译为flattenDepth(array, 1)真正的算法实现在 src/compat/array/flattenDepth.tsexport function flattenDepthT(array: ListOfRecursiveArraysOrValuesT | null | undefined, depth 1): T[] { if (!isArrayLike(array)) { return []; } const result: T[] []; const flooredDepth Math.floor(depth); const recursive (arr: readonly T[], currentDepth: number) { for (let i 0; i arr.length; i) { const item arr[i]; if (isFlattenable(item) currentDepth flooredDepth) { recursive(item as T[], currentDepth 1); } else { result.push(item); } } }; recursive(Array.from(array) as T[], 0); return result; }关键点非类数组直接返回[]这是对null/undefined/普通对象容错的第一道闸门由isArrayLike判定。深度取整Math.floor(depth)意味着flattenDepth(arr, 1.9)等价于深度1。递归展开只有当当前元素「可被展平」且「未超过深度上限」时才递归否则原样push。2. 可展平判定isFlattenablecompat 版展平哪些东西取决于内部的isFlattenable判定同样位于 src/compat/array/flattenDepth.tsfunction isFlattenable(value: unknown): boolean { return isArray(value) || isArguments(value) || Boolean(value (value as any)[Symbol.isConcatSpreadable]); }这条判定同时覆盖了第三节中的三类特殊输入真正的数组isArray、arguments对象isArguments、以及带真值Symbol.isConcatSpreadable的对象。输入类型声明ListOfRecursiveArraysOrValuesT定义在 src/compat/_internal/ListOfRecursiveArraysOrValues.ts即ArrayLikeT | RecursiveArrayT。3. 兼容层内部还有一个针对类数组的辅助函数在 src/compat/_internal/flattenArrayLike.ts 中还有一个flattenArrayLike专门把一组类数组对象逐项拼接为普通数组export function flattenArrayLikeT(values: ArrayArrayLikeT): T[] { const result: T[] []; for (let i 0; i values.length; i) { const arrayLike values[i]; if (!isArrayLikeObject(arrayLike)) { continue; } for (let j 0; j arrayLike.length; j) { result.push(arrayLike[j] as T); } } return result; }从源码结构看它服务于 compat 层内部对类数组的通用拼接需求体现了兼容层「处处以类数组为输入基础」的设计取向。五、对比compat 版 vs es-toolkit 原生flatten原文档在开头就给出了一条明确的性能警告compat 版flatten因需要处理null/undefined与ArrayLike类型而较慢建议改用 es-toolkit 原生flatten。原生flatten的实现es-toolkit 原生flatten位于 src/array/flatten.ts它是面向现代 JavaScript 的精简实现export function flattenT, D extends number 1(arr: readonly T[], depth 1 as D): ArrayFlatArrayT[], D { const result: ArrayFlatArrayT[], D []; const flooredDepth Math.floor(depth); const recursive (arr: readonly T[], currentDepth: number) { for (let i 0; i arr.length; i) { const item arr[i]; if (Array.isArray(item) currentDepth flooredDepth) { recursive(item, currentDepth 1); } else { result.push(item as FlatArrayT[], D); } } }; recursive(arr, 0); return result; }两者的差异可以总结为下表维度compat 版flatten原生flattenes-toolkit/array入口es-toolkit/compates-toolkit/es-toolkit/array输入类型ArrayLikeT \| null \| undefinedreadonly T[]深度参数固定为 1由flattenDepth支撑可选depth默认 1支持任意深度可展平判定isArray/isArguments/Symbol.isConcatSpreadable仅Array.isArray容错行为null/undefined返回[]类数组、arguments 均可处理要求数组输入逻辑更少性能较慢判定分支多、需Array.from转换更快仅内建Array.isArray分支原生版本的完整文档见 docs/reference/array/flatten.md其用法为import { flatten } from es-toolkit/array; const array [1, [2, 3], [4, [5, 6]]]; flatten(array); // [1, 2, 3, 4, [5, 6]] flatten(array, 2); // [1, 2, 3, 4, 5, 6]选择建议在全新代码中优先使用原生flatten仅当需要从 Lodash 迁移、或确实依赖 arguments/类数组/Symbol.isConcatSpreadable等兼容语义时才使用es-toolkit/compat版本。六、测试验证compat 语义有据可查compat 版flatten的行为由 src/compat/array/flatten.spec.ts 中的 Vitest 用例逐一锁定主要包括arguments 对象展平flatten([args, [args]])结果为[1, 2, 3, args]稀疏数组稠密化[[1, 2, 3], Array(3)]展平后补齐 3 个显式undefinedSymbol.isConcatSpreadable对象{ 0: a, length: 1, [Symbol.isConcatSpreadable]: true }展平为[a]空数组嵌套[[], [[]], [[], [[[]]]]]展平为[[], [], [[[]]]]非类数组返回空数组flatten({ 0: a })返回[]类数组与字符串flatten({ 0: [1, 2, 3], length: 1 })、flatten(123)、flatten(args)均按预期输出。这些用例直接印证了本文第三节描述的每一项兼容行为可作为迁移或回归测试时的参考基线。七、相关 API从flatten延伸的展平家族compat 层围绕展平提供了一组配套函数全部位于 src/compat/array 目录下函数说明实现文件flatten只展平一层兼容 arguments/类数组/Symbol.isConcatSpreadableflatten.tsflattenDepth展平到指定深度depth默认为 1是flatten的底层实现flattenDepth.tsflattenDeep无限深度展平等价于flattenDepth(array, Infinity)flattenDeep.tsflattenDeep的实现非常简洁export function flattenDeepT(array: ListOfRecursiveArraysOrValuesT | null | undefined) { return flattenDepth(array, Infinity) as any; }它们的组合关系是flatten与flattenDeep都只是flattenDepth在不同深度参数下的特例理解了flattenDepth的递归算法就等于理解了整个 compat 展平家族。结语es-toolkit 的 compat 版flatten是一份「语义先行」的 Lodash 兼容实现它牺牲了一部分性能换来对arguments、类数组、Symbol.isConcatSpreadable、null/undefined等 Lodash 生态边界输入的完整支持。如果你正在从 Lodash 迁移到 es-toolkit直接替换_.flatten即可得到一致的结果而如果是在新项目里追求极致性能则应选择 src/array/flatten.ts 中的原生实现。无论走哪条路径都建议结合 flatten.spec.ts 中的测试用例验证你的迁移行为确保边界场景万无一失。【免费下载链接】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），仅供参考
