es-toolkit compat maxBy 完全指南Lodash 兼容版的迭代器iteratee机制与边界行为【免费下载链接】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-toolkitmaxBy是 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 的_.maxByimport { maxBy } from es-toolkit/compat; const maxItem maxBy(array, iteratee);函数签名与语义maxByT(array: ArrayLikeT | null | undefined, iteratee?: ValueIterateeT): T | undefinedarray待搜索的数组ArrayLikeT也接受null与undefinediteratee可选作用于每个元素的函数、属性名或匹配条件默认值为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/undefinedimport { 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的类型定义为ValueIterateeT其完整定义见 src/compat/_internal/ValueIteratee.tsexport type ValueIterateeT | ((value: T) unknown) | (PropertyKey | [PropertyKey, any] | PartialShallowT);对应四种形态形态写法示例实际行为比较值类型函数x x.a直接作为回调任意通常为 number属性名age/0取元素指定属性property简写属性值键值对[active, true]判断元素属性是否等于给定值matchesProperty布尔值部分对象{ active: true }判断元素是否包含给定属性集matches布尔值这些简写由 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; }即兼容版会跳过以下三类不可比较的值NaN直接忽略与 Lodash 一致。maxBy([NaN, 1, 3, 2], x x)返回3若所有值都是NaN则返回undefinednull/undefined忽略。例如maxBy([{ a: undefined }, { a: -5 }, { a: null }], a)会跳过两个无效项返回{ a: -5 }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 的签名maxByT( 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 则多出三处开销判空与类型转换先做items null判断再通过 src/compat/_internal/toArray.ts 的toArray()将ArrayLike统一转为真数组Array.isArray命中则直接返回否则Array.fromiteratee 归一化const getValue iterateeToolkit(iteratee)将四种简写统一转为函数走 src/compat/util/iteratee.ts逐值过滤循环内多一次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])为例兼容版的完整调用链为入参检查items null为假继续类型转换toArray(users)得到真数组src/compat/_internal/toArray.ts空数组检查array.length 0为假继续iteratee 归一化iteratee([active, true])经 src/compat/util/iteratee.ts 的 switch 分支命中object类型转换为matchesProperty(active, true)谓词函数线性扫描从i 0开始遍历对每个元素调用getValue(element, i, array)跳过null/NaN/symbol用current max维护最大值与对应元素返回结果返回最大元素若全程无可比较值返回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 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），仅供参考 
长河君 · 2026/9/18 15:30:57 · 阅读 1.2k es-toolkit compat maxBy 完全指南：Lodash 兼容版的迭代器（iteratee）机制与边界行为
es-toolkit compat maxBy 完全指南Lodash 兼容版的迭代器iteratee机制与边界行为【免费下载链接】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-toolkitmaxBy是 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 的_.maxByimport { maxBy } from es-toolkit/compat; const maxItem maxBy(array, iteratee);函数签名与语义maxByT(array: ArrayLikeT | null | undefined, iteratee?: ValueIterateeT): T | undefinedarray待搜索的数组ArrayLikeT也接受null与undefinediteratee可选作用于每个元素的函数、属性名或匹配条件默认值为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/undefinedimport { 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的类型定义为ValueIterateeT其完整定义见 src/compat/_internal/ValueIteratee.tsexport type ValueIterateeT | ((value: T) unknown) | (PropertyKey | [PropertyKey, any] | PartialShallowT);对应四种形态形态写法示例实际行为比较值类型函数x x.a直接作为回调任意通常为 number属性名age/0取元素指定属性property简写属性值键值对[active, true]判断元素属性是否等于给定值matchesProperty布尔值部分对象{ active: true }判断元素是否包含给定属性集matches布尔值这些简写由 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; }即兼容版会跳过以下三类不可比较的值NaN直接忽略与 Lodash 一致。maxBy([NaN, 1, 3, 2], x x)返回3若所有值都是NaN则返回undefinednull/undefined忽略。例如maxBy([{ a: undefined }, { a: -5 }, { a: null }], a)会跳过两个无效项返回{ a: -5 }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 的签名maxByT( 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 则多出三处开销判空与类型转换先做items null判断再通过 src/compat/_internal/toArray.ts 的toArray()将ArrayLike统一转为真数组Array.isArray命中则直接返回否则Array.fromiteratee 归一化const getValue iterateeToolkit(iteratee)将四种简写统一转为函数走 src/compat/util/iteratee.ts逐值过滤循环内多一次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])为例兼容版的完整调用链为入参检查items null为假继续类型转换toArray(users)得到真数组src/compat/_internal/toArray.ts空数组检查array.length 0为假继续iteratee 归一化iteratee([active, true])经 src/compat/util/iteratee.ts 的 switch 分支命中object类型转换为matchesProperty(active, true)谓词函数线性扫描从i 0开始遍历对每个元素调用getValue(element, i, array)跳过null/NaN/symbol用current max维护最大值与对应元素返回结果返回最大元素若全程无可比较值返回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 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），仅供参考