collect.js reduce() 方法完全指南:将数组与对象集合折叠为单一值

原创2026-10-14 21:51:131,848 阅读
文章标签:开发工具

collect.js reduce() 方法完全指南:将数组与对象集合折叠为单一值

本文围绕 collect.js 官方 API 文档 docs/api/reduce.md 展开,结合 reduce() 源码、单元测试 与 TypeScript 类型声明,系统讲解 reduce() 的核心语义、初始值机制、源码实现原理与实战用法。读完本文,你将掌握如何用 collect.js 的 reduce() 对数组、对象(hashmap)集合做任意形式的归约聚合,并理解它与 sum()、transform() 等方法的差异与适用场景。

一、reduce() 是什么:把整个集合折叠成一个值

在数组与对象处理场景中,reduce(归约 / 折叠)是一种将"整个集合"收敛为"单个值"的经典操作:它遍历集合中的每一个元素,把上一次迭代的计算结果作为 carry(累计值)传入下一次迭代,最终返回一个单一结果。

collect.js 中的 reduce() 正是这一能力的实现。官方文档给出的定义是:

The reduce method reduces the collection to a single value, passing the result of each iteration into the subsequent iteration.

即:reduce 方法将集合归约为一个单一值,并把每次迭代的结果传递给后续迭代。例如把 [1, 2, 3] 归约为总和 6:

const collection = collect([1, 2, 3]);

const total = collection.reduce((carry, item) => carry + item);

// 6

在 README.md 的 API 总览中,reduce() 的说明与用法与此完全一致,可见它是该库的核心聚合方法之一。

二、基本语法与回调签名

reduce() 的调用形式为:

collection.reduce(fn, carry?)
  • fn:必填的迭代回调。对数组,回调签名为 (carry, item);对对象集合,回调签名为 (carry, value, key)(详见下文第三节)。
  • carry:可选的初始累计值。不传时,第一轮迭代的 carry 为 null,这是官方文档明确说明的默认行为。

这一签名在 TypeScript 类型声明 中被精确描述为:

reduce<T>(fn: (_carry: T | null, item: Item) => T, carry?: T): any;

注意其中的 _carry: T | null——类型系统同样告诉我们:carry 的第一轮取值可能为 null,这正是"未传初始值"时的默认状态。因此在使用时,如果你的归约逻辑基于数值累加,建议始终显式传入初始值,避免第一轮对 null 做运算产生非预期结果。

三、指定初始值:reduce 的第二个参数

官方文档强调:第一轮迭代中 carry 的值是 null,但你可以通过第二个参数显式指定初始值:

const total = collection.reduce((carry, item) => carry + item, 4);

// 10

这里初始值 4 先作为 carry 参与第一轮迭代,因此最终结果是 4 + 1 + 2 + 3 = 10(区别于不传初始值时的 1 + 2 + 3 = 6)。

初始值机制在实际编码中非常关键:

  • 累加 / 累乘:以 0、1 等数值作为起点,避免对 null 做算术运算;
  • 字符串拼装:以 '' 空字符串作为起点;
  • 聚合到容器:以 []、{}、Map 等容器作为起点,把集合元素逐项塞入。

四、源码级原理剖析:reduce 是如何实现的

reduce() 的实现位于 src/methods/reduce.js,完整源码如下:

'use strict';

module.exports = function reduce(fn, carry) {
  let reduceCarry = null;

  if (carry !== undefined) {
    reduceCarry = carry;
  }

  if (Array.isArray(this.items)) {
    this.items.forEach((item) => {
      reduceCarry = fn(reduceCarry, item);
    });
  } else {
    Object.keys(this.items).forEach((key) => {
      reduceCarry = fn(reduceCarry, this.items[key], key);
    });
  }

  return reduceCarry;
};

从源码中可以提炼出四条关键实现事实:

  1. 默认累计值为 null:reduceCarry 初始化为 null,只有当第二个参数 carry !== undefined 时才被覆盖。这与文档中"第一轮迭代 carry 为 null"的描述完全吻合——注意判定的边界是 undefined,因此显式传入 null 或 0、'' 等值都会被采用。

  2. 数组走 forEach 分支:当 this.items 是数组时,回调只接收两个参数 (carry, item)。

  3. 对象走 Object.keys 分支:当集合是对象(hashmap)时,通过 Object.keys(this.items) 遍历键名,回调接收三个参数 (carry, value, key)——第三个参数是当前项的键名。这意味着你可以基于键名做归约逻辑(详见第五节)。

  4. 不修改原集合:整个归约过程仅更新局部变量 reduceCarry,this.items 从未被改写,因此 reduce() 是不可变操作。这一点被 单元测试 显式断言:expect(collection.all()).to.eql([1, 2, 3, 4, 5, 6, 7]);。

reduce 方法通过 src/index.js#L102 挂载到原型链上:

Collection.prototype.reduce = require('./methods/reduce');

五、对象集合的归约:善用回调的 key 参数

当集合由对象构成时,reduce() 回调会收到 (carry, value, key) 三个参数。这一行为在 单元测试 中有直接佐证:

it('should support hashmaps', () => {
  const collection = collect({ Joe: 'Doe', Foo: 'Bar' });
  const reduced = collection.reduce((carry, item, key) => carry + item + key, '');

  expect(reduced).to.eql('DoeJoeBarFoo');
  expect(collection.all()).to.eql({ Joe: 'Doe', Foo: 'Bar' });
});

运行逻辑如下:初始 carry 为 '',第一轮得到 '' + 'Doe' + 'Joe',第二轮再拼接 'Bar' 与 'Foo',最终结果是 'DoeJoeBarFoo'。可见回调的第三个参数 key 就是当前遍历到的对象键名,你可以据此实现键值拼接、按键条件累加等需求。

六、空集合与边界行为

从源码可以推断出空集合的归约结果:

  • 传了初始值:集合为空时不执行任何回调,直接返回初始值。测试用例如下(reduce_test.js):
const collection = collect([]);
const result = collection.reduce((carry, number) => carry + number, 0);
// 0

const collection2 = collect([]);
const result2 = collection2.reduce((carry, number) => carry + number, 1);
// 1
  • 未传初始值:空集合会直接返回 null(因为 reduceCarry 保持初始值且从未被回调更新)。这是从源码结构可以直接得出的推断,写作归约逻辑时请务必留意——若集合可能为空,请显式传入合适的初始值。

七、reduce() 与 sum()、transform() 的对比选型

理解 reduce() 的定位,能帮你选出最合适的聚合方法:

方法 返回结果 是否修改原集合 典型场景
reduce() 任意单一值 否 自定义聚合、拼装、按规则折叠
sum() 数值 否 纯数值求和
transform() 新的 Collection 是(就地修改 this.items) 原地变换每个元素

对照实现可以看到差异的根源:

  • sum() 源码 固定做数值累加:对每个元素执行 parseFloat,最终 total += ...,并返回数字。它本质上是一个"数值专用、不可定制"的归约。
  • transform() 源码 则把 this.items 重新赋值为 map 的结果(数组)或新构建的对象(对象集合),属于可变的逐元素变换,返回的是 Collection 自身。
  • reduce() 则把折叠逻辑完全交给回调函数,返回值类型不受限制——可以是数字、字符串、数组、对象,甚至一个新集合,因此是三者中表达能力最强、最通用的方法。

一句话选型建议:只求和用 sum();想就地改写每个元素用 transform();需要自定义聚合逻辑(或返回值不是简单数字)时,用 reduce()。

八、实战示例

下面给出几个可直接运行的实战场景,均基于 reduce() 的初始值与 key 参数特性。

1. 求订单总价

const orders = collect([
  { id: 1, price: 100 },
  { id: 2, price: 250 },
  { id: 3, price: 50 },
]);

const total = orders.reduce((carry, order) => carry + order.price, 0);

// 400

2. 按类别统计数量

const items = collect(['fruit', 'veg', 'fruit', 'meat', 'veg']);

const stats = items.reduce((carry, item) => {
  carry[item] = (carry[item] || 0) + 1;
  return carry;
}, {});

// { fruit: 2, veg: 2, meat: 1 }

3. 对象集合拼接键值

const map = collect({ user: 'Alice', role: 'admin' });

const query = map.reduce((carry, value, key) =>
  carry ? `${carry}&${key}=${value}` : `${key}=${value}`, '');

// 'user=Alice&role=admin'

4. 扁平数组转分组对象

const numbers = collect([1, 2, 3, 4, 5, 6]);

const grouped = numbers.reduce((carry, number) => {
  const bucket = number % 2 === 0 ? 'even' : 'odd';
  (carry[bucket] = carry[bucket] || []).push(number);
  return carry;
}, {});

// { odd: [1, 3, 5], even: [2, 4, 6] }

以上示例都遵循同一模式:以容器型初始值起步(0、''、{}),回调内更新容器并显式返回 carry,这是 reduce() 正确工作的关键——回调的返回值会被用作下一轮迭代的 carry。

九、安装与快速上手

在本地运行上述示例前,请先安装 collect.js(详见 安装文档):

npm install collect.js --save
# 或使用 Yarn
yarn add collect.js

引入方式参考 usage.md,支持 CommonJS 与 ES Module 两种风格:

// require 方式
const collect = require('collect.js');

// import 方式
import collect from 'collect.js';

// 底层 Collection 类
import { Collection } from 'collect.js';

TypeScript 项目可直接获得类型提示(reduce 签名位于 index.d.ts)。若想验证库的整体行为,可在仓库根目录运行 npm test(Mocha 驱动,入口为 test/tests.js),其中 reduce_test.js 覆盖了求和、初始值、hashmap 与空集合四类核心场景。

结语

reduce() 是 collect.js 中表达力最强的聚合工具:它以"单一值"为目标,通过回调自由定义折叠规则,同时保持原集合不可变;null 默认累计值与可选初始值参数是其语义核心,对象集合下的 key 参数则进一步扩展了它的适用面。理解本文的源码行为与边界规则后,你便可以在求和、统计、拼装、分组等场景中安全地使用 reduce(),并在合适时机改用 sum() 或 transform() 简化代码。

登录后查看全文
collect.js