collect.js reduce() 方法完全指南:将数组与对象集合折叠为单一值
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;
};
从源码中可以提炼出四条关键实现事实:
-
默认累计值为
null:reduceCarry初始化为null,只有当第二个参数carry !== undefined时才被覆盖。这与文档中"第一轮迭代 carry 为 null"的描述完全吻合——注意判定的边界是undefined,因此显式传入null或0、''等值都会被采用。 -
数组走
forEach分支:当this.items是数组时,回调只接收两个参数(carry, item)。 -
对象走
Object.keys分支:当集合是对象(hashmap)时,通过Object.keys(this.items)遍历键名,回调接收三个参数(carry, value, key)——第三个参数是当前项的键名。这意味着你可以基于键名做归约逻辑(详见第五节)。 -
不修改原集合:整个归约过程仅更新局部变量
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() 简化代码。