collect.js 的 max() 方法:从数组与对象集合中安全提取最大值

原创2026-10-14 23:57:441,992 阅读
文章标签:开发工具

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);
};

关键逻辑可以拆解为三个步骤:

  1. 判断参数类型:只有 typeof key === 'string'(传入字符串字段名)时才走对象字段分支;否则走"直接对元素求最大值"分支。这与 min() 的判断方式略有差异——src/methods/min.js 使用的是 key !== undefined 判断,而 max() 使用 typeof key === 'string',也就是说传入非字符串(如数字索引、函数)时,max() 会将其忽略并退化为无 key 行为。
  2. 过滤缺失字段:在对象分支中,先执行 this.items.filter(item => item[key] !== undefined),把"字段不存在"(访问得到 undefined)以及"字段值显式为 undefined"的元素全部剔除。这正是示例中 { unicorn: false } 被安全跳过的原因。
  3. 展开求值:用展开运算符 ... 将数组摊平后交给 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。
登录后查看全文
collect.js