企业官网建设流程全解析

es-toolkit compat maxBy 完全指南：Lodash 兼容版的迭代器（iteratee）机制与边界行为

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

maxBy是 es-toolkit 的 Lodash 兼容层（es-toolkit/compat）中用于「按指定规则求最大值元素」的工具函数。本文基于 compat 版 maxBy 官方文档，结合 src/compat/math/maxBy.ts 及其测试用例，系统讲解它的四种 iteratee 形态、空值与 NaN 等边界行为，并与更快、更现代的原生版 maxBy 做对比，帮助你根据场景做出正确选型。

一、compat 版 maxBy 的定位与使用前提

es-toolkit 提供两套 API：现代原生 API（从es-toolkit/array等子路径导入）与 Lodash 兼容 API（从es-toolkit/compat导入）。本文主角是兼容版maxBy，它被设计为可直接替换 Lodash 的_.maxBy：

import { maxBy } from 'es-toolkit/compat'; const maxItem = maxBy(array, iteratee);

函数签名与语义：

maxBy<T>(array: ArrayLike<T> | null | undefined, iteratee?: ValueIteratee<T>): T | undefined

• array：待搜索的数组（ArrayLike<T>），也接受null与undefined；
• iteratee（可选）：作用于每个元素的函数、属性名或匹配条件，默认值为identity（原样返回元素本身）；
• 返回值：计算值最大的元素；数组为空、传入null/undefined、或没有任何元素可比较时，返回undefined。

值得特别注意的是，官方文档在开头就给出明确警告：该兼容版本因 iteratee 函数处理和类型转换，运行速度较慢，建议改用更快、更现代的原生版 maxBy（从es-toolkit/array导入）。这一警告背后是两种实现设计目标的差异，本文第五节会做源码级剖析。

二、基础用法：从简单函数到属性名快捷方式

2.1 用函数提取比较值

将数组元素逐一交给回调函数，取返回值最大者对应的原始元素：

import { maxBy } from 'es-toolkit/compat'; // 从对象数组中找出 age 最大的元素 const people = [ { name: '홍길동', age: 25 }, { name: '김철수', age: 30 }, { name: '이영희', age: 35 }, ]; maxBy(people, person => person.age); // Returns: { name: '이영희', age: 35 } // 用函数做值变换后再比较（求绝对值最大者） const numbers = [-1, -2, -3]; maxBy(numbers, x => Math.abs(x)); // Returns: -3 （绝对值最大，但返回的是原始元素本身）

注意第二例的返回值：maxBy返回的是原始数组元素（-3），而不是变换后的值（3）——这是maxBy与max的本质区别，也是它命名为 "by" 的原因。

2.2 属性名（property name）快捷方式

当元素是对象时，可以直接传属性名字符串，等价于element => element[property]：

import { maxBy } from 'es-toolkit/compat'; const people = [ { name: '홍길동', age: 25 }, { name: '김철수', age: 30 }, { name: '이영희', age: 35 }, ]; maxBy(people, 'age'); // Returns: { name: '이영희', age: 35 }

该用法与_.property简写一致，兼容版测试中有对应的验证（见 src/compat/math/maxBy.spec.ts 中should work with \_.property` shorthands` 用例）。

2.3 数字索引访问数组元素

属性名快捷方式同样适用于「以数字为键」的场景，即传入数组的索引号，找出该位置元素最大的那一项：

import { maxBy } from 'es-toolkit/compat'; const arrays = [ [1, 2], [3, 4], [0, 5], ]; maxBy(arrays, 0); // 按第 1 个元素比较 → [3, 4] maxBy(arrays, 1); // 按第 2 个元素比较 → [0, 5]

2.4 键值对与部分对象匹配（布尔型 iteratee）

兼容版还支持 Lodash 特有的「匹配型」iteratee：当传入[key, value]键值对或部分对象时，iteratee 会返回布尔值，maxBy在所有匹配元素中取第一个遇到的元素：

import { maxBy } from 'es-toolkit/compat'; const users = [ { name: '홍길동', age: 25, active: true }, { name: '김철수', age: 30, active: false }, { name: '이영희', age: 35, active: true }, ]; // active 为 true 的元素中，返回第一个 maxBy(users, ['active', true]); // Returns: { name: '홍길동', age: 25, active: true } // 对象形式的条件指定 maxBy(users, { active: true }); // Returns: { name: '홍길동', age: 25, active: true }

这种用法等价于「先 filter 再取首元素」，在源码层面由 iteratee 工具函数 统一转换实现（见第四节）。

2.5 空数组与 null/undefined

import { maxBy } from 'es-toolkit/compat'; maxBy([], x => x.a); // Returns: undefined maxBy(null); // Returns: undefined maxBy(undefined); // Returns: undefined

空数组、null、undefined均安全返回undefined，不会抛出异常——这是 Lodash 兼容语义的一部分，在实现中通过两重判空保证（详见 src/compat/math/maxBy.ts 的items == null检查与toArray后的length === 0检查）。

三、iteratee 的四种形态与 ValueIteratee 类型

兼容版之所以「慢」，根源在于它需要支持 Lodash 全套 iteratee 简写。官方文档将iteratee的类型定义为ValueIteratee<T>，其完整定义见 src/compat/_internal/ValueIteratee.ts：

export type ValueIteratee<T> = | ((value: T) => unknown) | (PropertyKey | [PropertyKey, any] | PartialShallow<T>);

对应四种形态：

这些简写由 src/compat/util/iteratee.ts 的iteratee()函数统一归一化：函数原样返回；PropertyKey走property简写；对象与键值对分别走matches与matchesProperty；当值为null/undefined时返回identity。因此maxBy(people)不传 iteratee 时等价于maxBy(people, x => x)。

四、边界行为：NaN、symbol、null 与 undefined 的跳过规则

这是兼容版与原生版行为差异最大的地方。在 src/compat/math/maxBy.ts 的主循环中，存在一个显式的过滤条件：

if (current == null || Number.isNaN(current) || typeof current === 'symbol') { continue; }

即兼容版会跳过以下三类不可比较的值：

1. NaN：直接忽略（与 Lodash 一致）。maxBy([NaN, 1, 3, 2], x => x)返回3；若所有值都是NaN，则返回undefined；
2. null/undefined：忽略。例如maxBy([{ a: undefined }, { a: -5 }, { a: null }], 'a')会跳过两个无效项，返回{ a: -5 }；
3. symbol：忽略。maxBy([Symbol('a'), 1, 3, 2], x => x)返回3。

对应的行为全部有测试用例背书（见 src/compat/math/maxBy.spec.ts 中的should skip NaN values, matching lodash、should skip symbol values、should skip null and undefined values, matching lodash等用例）。此外，should return undefined when the iteratee yields no comparable value用例还确认：当所有元素经 iteratee 后都得到不可比较值时，返回undefined。

与之相对，原生版src/array/maxBy.ts 采取的是「NaN 传播」策略：

if (Number.isNaN(value)) { return element; }

只要某个元素的比较值为NaN，立即返回该元素——这与Math.max的行为一致（Math.max(1, NaN)结果为NaN），且被 src/array/maxBy.spec.ts 中should propagate NaN regardless of its position用例验证。也就是说：

• 需要 Lodash 兼容语义（跳过 NaN）→ 用es-toolkit/compat版；
• 需要 Math.max 语义（NaN 传播）或追求性能→ 用es-toolkit/array原生版。

五、compat 版与原生版：实现差异与选型建议

两个版本的核心差异可从源码对比中直观看出。

原生版 src/array/maxBy.ts 的签名：

maxBy<T>( items: readonly T[], getValue: (element: T, index: number, array: readonly T[]) => number ): T | undefined;

• 只接受纯函数回调（getValue），没有简写转换；
• 循环内直接调用getValue(element, i, items)，无额外分支；
• 空数组、null/undefined不做容错（类型层面null/undefined根本不被接受）；
• getValue会收到(element, index, array)三个参数，可用于item.value + index这类依赖位置的比较（见 src/array/maxBy.spec.ts 对应用例）。

兼容版 src/compat/math/maxBy.ts 则多出三处开销：

1. 判空与类型转换：先做items == null判断，再通过 src/compat/_internal/toArray.ts 的toArray()将ArrayLike统一转为真数组（Array.isArray命中则直接返回，否则Array.from）；
2. iteratee 归一化：const getValue = iterateeToolkit(iteratee)将四种简写统一转为函数（走 src/compat/util/iteratee.ts）；
3. 逐值过滤：循环内多一次current == null || Number.isNaN(current) || typeof current === 'symbol'判断。

官方文档给出的结论是明确的：日常新代码应优先使用原生版，只有需要直接替换存量 Lodash 代码（依赖简写语法与 NaN 跳过语义）时才应选择 compat 版。两者使用形态对比如下：

// 原生版：只认函数，更快 import { maxBy } from 'es-toolkit/array'; maxBy(people, person => person.age); // { name: '이영희', age: 35 } // 兼容版：支持全部 Lodash 简写 import { maxBy } from 'es-toolkit/compat'; maxBy(people, 'age'); // 属性名 maxBy(users, ['active', true]); // 键值对 maxBy(users, { active: true }); // 部分对象

六、源码级运行流程：一次调用经历了什么

以maxBy(users, ['active', true])为例，兼容版的完整调用链为：

1. 入参检查：items == null为假，继续；
2. 类型转换：toArray(users)得到真数组（src/compat/_internal/toArray.ts）；
3. 空数组检查：array.length === 0为假，继续；
4. iteratee 归一化：iteratee(['active', true])经 src/compat/util/iteratee.ts 的 switch 分支命中object类型，转换为matchesProperty('active', true)谓词函数；
5. 线性扫描：从i = 0开始遍历，对每个元素调用getValue(element, i, array)，跳过null/NaN/symbol，用current > max维护最大值与对应元素；
6. 返回结果：返回最大元素；若全程无可比较值，返回undefined。

在实现细节上，兼容版用let max: unknown配合max === undefined作为「尚未赋值」的哨兵，从而允许比较值本身是-Infinity（测试用例should work when \iteratee` returns +/-Infinity验证了-Infinity也能被正确选出）；而原生版则用let max = -Infinity初始化，两条路线殊途同归。此外，兼容版测试还覆盖了Date对象（maxBy([curr, past], date => date.getTime())）与 50 万级超长数组（should work with extremely large arrays`）的场景，证明其线性时间复杂度在真实数据下表现稳定。

七、总结

maxBy（兼容版）是一个「为 Lodash 迁移而生」的函数：它以少量性能开销换取完整的 iteratee 简写语法与 Lodash 一致的边界语义（跳过NaN、null、undefined、symbol，空值与null安全返回undefined）。判断取舍的标准非常清晰：

• 正在迁移 Lodash 存量代码，且依赖'age'、['active', true]、{ active: true }等简写 → 使用es-toolkit/compat版；
• 编写新代码，追求速度与更小的包体积 → 使用es-toolkit/array原生版（参见 原生版文档 与 原生实现），它只接受函数回调并遵循Math.max的 NaN 传播语义。

两种实现、两套语义、两个导入路径，充分体现了 es-toolkit「现代 API 追求性能、compat API 追求兼容」的双轨设计理念。

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