collect.js 的 max() 方法:从数组与对象集合中安全提取最大值
collect.js 的 max() 方法:从数组与对象集合中安全提取最大值
max() 是 collect.js 提供的集合统计方法之一,用于返回集合中的最大值。它支持两种调用形态:不传参数时直接对集合元素求最大值,传入字符串 key 时则对对象集合按指定字段求最大值。本文以 官方 API 文档 为主体,结合 源码实现 与 测试用例,完整讲解 max() 的用法、底层原理、边界行为以及与其他统计方法(min()、median()、mode()、average() 等)的配合方式。
环境准备:安装与引入 collect.js
collect.js 是一个零依赖(dependency free)的数组与对象操作封装库,安装方式参见 docs/installation.md:
npm install collect.js --save
# 或
yarn add collect.js
在代码中引入后即可开始使用:
// CommonJS
const collect = require('collect.js');
// ES Module
import collect from 'collect.js';
// 或直接使用底层 Collection 类
import { Collection } from 'collect.js';
const collection = new Collection(products);
max() 通过 src/index.js 中的 Collection.prototype.max = require('./methods/max'); 挂载到 Collection 原型上,因此任何由 collect() 工厂函数创建的集合实例都可以直接调用。
max() 的两种核心用法
1. 不传参数:对集合元素直接求最大值
当集合本身就是一组数值时,直接调用 max() 即可:
collect([-1, -2345, 12, 11, 3]).max();
// 12
这是官方文档给出的第一个示例。传入的数组 [-1, -2345, 12, 11, 3] 中最大值为 12,方法返回数字 12。
2. 传入 key:对对象集合按字段求最大值
当集合元素是对象时,传入字符串 key 让 max() 按该字段取值并求最大值:
const collection = collect([
{ value: 10 },
{ value: -13 },
{ value: 12 },
{ unicorn: false },
]);
const max = collection.max('value');
// 12
这是官方文档给出的第二个示例。集合中有 4 个对象,其中前 3 个带有 value 字段,第 4 个对象没有 value 字段(只有 unicorn)。max('value') 的结果仍然是 12——注意最后一个对象并未导致结果变成 NaN,这正是 max() 内部做了过滤处理的结果(详见下文源码解析)。
源码级解析:max() 是如何工作的
max() 的完整实现非常简洁,src/methods/max.js 全文如下:
'use strict';
module.exports = function max(key) {
if (typeof key === 'string') {
const filtered = this.items.filter(item => item[key] !== undefined);
return Math.max(...filtered.map(item => item[key]));
}
return Math.max(...this.items);
};
关键逻辑可以拆解为三个步骤:
- 判断参数类型:只有
typeof key === 'string'(传入字符串字段名)时才走对象字段分支;否则走"直接对元素求最大值"分支。这与min()的判断方式略有差异——src/methods/min.js 使用的是key !== undefined判断,而max()使用typeof key === 'string',也就是说传入非字符串(如数字索引、函数)时,max()会将其忽略并退化为无 key 行为。 - 过滤缺失字段:在对象分支中,先执行
this.items.filter(item => item[key] !== undefined),把"字段不存在"(访问得到undefined)以及"字段值显式为undefined"的元素全部剔除。这正是示例中{ unicorn: false }被安全跳过的原因。 - 展开求值:用展开运算符
...将数组摊平后交给Math.max()。Math.max会对每个参数做 ToNumber 数值转换,因此字符串形式的数字(如'12')也能参与比较。
不变性:max() 不会修改原集合
从 测试用例 可以看到,调用 max() 后原集合内容保持不变:
const max = collection.max('value');
expect(max).to.eql(12);
expect(collection.all()).to.eql([
{ value: 10 },
{ value: -13 },
{ value: 12 },
{ value: undefined },
{ unicorn: false },
]);
测试中特意加入了一个 { value: undefined } 元素,验证它同样会被过滤而不会污染计算结果。max() 通过 filter 和 map 生成新数组,对 this.items 只读,因此可以安全地链式调用而不必担心副作用。
边界情况与注意事项
空集合返回 -Infinity
从源码结构可以推断:当集合为空数组时,Math.max(...[]) 等价于无参调用 Math.max(),按 JavaScript 标准行为会返回 -Infinity。因此对空集合调用 max() 得到的是 -Infinity 而非 0 或 undefined,在业务代码中需要自行判空(可配合 isEmpty() 方法使用)。
全被过滤时同样得到 -Infinity
在对象分支中,如果所有元素的 item[key] 都为 undefined(字段全部缺失或值全为 undefined),filter 后得到空数组,同样返回 -Infinity。这一点与测试中"部分缺失"的场景不同,属于需要留意的最坏情况。
混合类型与不可比较值
Math.max 会对参数执行数值转换:数字字符串可以正常参与比较,但 null 会被转换为 0,NaN 参与比较时结果恒为 NaN。如果集合中含有 NaN,max() 会直接返回 NaN。因此建议保证传入数据是可比较的同类型数值。
与 min() 的对称设计
max() 与 min() 是一对对称方法,文档分别为 docs/api/max.md 与 docs/api/min.md。二者在对象分支上的过滤逻辑一致(都剔除 item[key] !== undefined 的元素),区别仅在于 max 使用 Math.max、min 使用 Math.min。可以成对使用来快速获取集合的数值区间:
const scores = collect([88, 72, 95, 61, 80]);
scores.min(); // 61
scores.max(); // 95
TypeScript 类型签名
在 index.d.ts 中,max() 的签名定义为:
max(key?: keyof Item | string): number;
key 为可选参数,类型为 keyof Item 或任意字符串,返回值恒为 number。这也印证了前面提到的"不传 key 也可以调用"的用法,并为 TypeScript 用户提供了编译期类型校验。
与其他统计方法的配合
max() 属于 collect.js 统计方法家族的一员,同类方法包括:
| 方法 | 说明 | 文档 |
|---|---|---|
max() |
返回最大值 | docs/api/max.md |
min() |
返回最小值 | docs/api/min.md |
median() |
返回中位数(可传 key) | docs/api/median.md |
mode() |
返回众数数组(可传 key) | docs/api/mode.md |
average() / avg() |
返回平均值(可传 key 或回调) | src/methods/average.js |
sum() |
返回总和(可传 key 或回调) | src/methods/sum.js |
与 average()、sum() 支持"字符串 key、回调函数"两种取值方式不同,max() 目前只支持字符串 key 与无参两种形态。在实战中,可以用 max() 快速找出最高分、最新时间戳、最大订单金额等,再配合 filter()、where()、sortBy() 等实现"找出最大值对应的记录"类需求;若需按嵌套字段(如 product.price)取最大值,可先用 pluck() 提取字段值再调用 max()。
小结
max()有两种用法:无参对元素求最大,传字符串 key 对对象字段求最大;- 对象分支会自动过滤字段缺失或值为
undefined的元素,避免结果被污染为NaN; - 方法只读,不修改原集合,可安全链式调用;
- 空集合或元素全被过滤时返回
-Infinity,需结合isEmpty()等做判空处理; - 完整源码见 src/methods/max.js,行为验证见 test/methods/max_test.js。