I Built a JavaScript groupBy Library — Here's What I Learned

Julio Aguilar — Mon, 21 Sep 2026 16:55:45 +0000

The problem: `Object.groupBy()` gets you halfway there

ES2024 finally gave JavaScript a native Object.groupBy(). It's great no more hand-rolled reduce just to
bucket an array by a key.

But in real applications, grouping is rarely the end goal. The moment you group orders by status, someone asks for revenue per status. Group logs by day, and you need error counts per day. Group inventory by SKU, and you need total units on hand per SKU.

Object.groupBy() stops exactly where the interesting work begins. It hands you arrays of raw items and leaves
the summing, averaging, and counting to you — every single time.

Why I stopped writing the same reduce over and over

I noticed I was writing this pattern constantly, in slightly different shapes, across dashboards, reporting endpoints, and ETL scripts:

const byStatus = Object.groupBy(orders, (o) => o.status);

  const result = {};
  for (const status in byStatus) {
    const items = byStatus[status];
    result[status] = {
      revenue: items.reduce((sum, o) => sum + o.amount, 0),
      avgOrder: items.reduce((sum, o) => sum + o.amount, 0) / items.length,
      orders: items.length,
    };
  }

It works, but it's brittle — every new metric is another reduce pass, and nothing guards against a null amount quietly turning the whole sum into NaN. I'd copy-pasted this pattern into enough projects that it stopped feeling like "just a reduce" and started feeling like a missing standard library function — the GROUP BY + SUM/AVG/COUNT step SQL gives you for free. So I built groupjs_by: a small, zero-dependency library that picks up exactly where Object.groupBy() leaves off.

API design: group, then aggregate, in one chain

const { groupBy } = require('groupjs_by');

  groupBy(orders, 'status')
    .sum('revenue', 'amount')
    .avg('avgOrder', 'amount')
    .count('orders')
    .data;

That's the whole surface, more or less:

-groupBy(data, key, options?) — groups by a field name, an accessor function, or an array of both for multi-key grouping (['country', 'status']).

sum(alias, column), .avg(alias, column, decimals?),
min(alias, column), max(alias, column),distinctCount(alias, column)
count(alias) — the aggregates you'd write by hand, as one-liners.
where(predicate) — filters items inside each group before you aggregate.
aggregate(spec) — computes several metrics in a single pass instead of one scan per method.
reduce(alias, reducer, initial?) — an escape hatch for custom per-group folds.
orderBy(field, direction?) and .toArray() — for turning groups into sorted, chart-ready rows.

Every column argument accepts a string key or an accessor function, so nested or derived values work without flattening your data first:

groupBy(checkoutEvents, (row) => row.meta.channel).aggregate({
    sum: ['revenue', (row) => row.payment.total],
    count: ['checkouts'],
 }).data;

Why chaining, specifically

A single config object (groupBy(data, { key, aggregates: {...} })) is arguably more "data-driven," but reporting code gets built up incrementally — you group, look at the shape, then decide you also want an average, then a distinct count of something. Chaining mirrors that workflow and reads close to the SQL you're mentally translating from:


  SELECT status, SUM(amount) AS revenue, AVG(amount) AS avg_order, COUNT(*) AS orders
  FROM orders GROUP BY status;

 groupBy(orders, 'status')
    .sum('revenue', 'amount')
    .avg('avgOrder', 'amount')
    .count('orders');

The one deliberate escape hatch is .aggregate(spec), which takes a plain object instead of a chain purely for performance, since chaining
.sum().avg().min().max()
scans each group once per method, while .aggregate()scans each group once.

Output format: built for tables and dashboards, not just objects

.data gives you { [groupKey]: { items, ...aggregates } } , good for direct lookups, but awkward to map over for a UI table. So every result also exposes .toArray():

groupBy(orders, ['country', 'status'])
    .sum('revenue', 'amount')
    .count('orders')
    .toArray();

  // [
  //   { key: ['US', 'paid'], items: [...], revenue: 150, orders: 2 },
  //   { key: ['US', 'refunded'], items: [...], revenue: 20, orders: 1 },
  //   { key: ['MX', 'paid'], items: [...], revenue: 80, orders: 1 },
  // ]

Pair that with .orderBy('revenue', 'desc')and you have exactly the row shape a dashboard table or chart
expects .omitItems() (called last) strips the raw items before you serialize the result over the wire.

What I learned shipping an npm package

A few things surprised me more than the aggregation logic itself:

Dual CJS/ESM output is not optional anymore. Between require('groupjs_by'), import { groupBy } from 'groupjs_by', and bundlers that care about "exports" conditions, I ended up maintaining index.js / index.mjs and matching .d.ts / .d.mts type declarations, wired through package.json's exports map for both import and require resolution.
coverageThreshold in Jest is a good forcing function. Setting functions: 100, lines: 100, statements: 100 early meant every edge case I described above had to be exercised by a real test, not just handled optimistically in the code.
CI is where you find the YAML mistakes, not the JS ones. More than one release cycle here was "fix invalid YAML in the workflow" rather than a code fix — worth budgeting time for.
Trusted Publishing (OIDC) beats a long-lived NPM_TOKEN. Wiring GitHub Actions to publish via npm's OIDC trust relationship instead of a stored token was a small setup cost that removes a credential I'd otherwise have to rotate.
The README is a design document. Writing the "recipes" section — sales reports, log rollups, inventoryvaluation — before locking the API surface surfaced awkward method signatures earlier than writing tests did.

Try it

groupjs_by is zero-dependency, ships TypeScript types out of the box, and works in Node 18+ via CommonJS or ESM.

npm install groupjs_by

npm link
github
License: MIT

If you've been writing the same reduce for sums and averages after every Object.groupBy() call, I'd love feedback — issues and PRs are open, and I'm especially curious what aggregate types people find themselves reaching for beyond sum/avg/min/max/distinctCount.

How do I group an array of objects in JavaScript and sum a field?

Julio Aguilar — Mon, 17 Aug 2026 20:37:34 +0000

import { groupBy } from 'groupjs_by';

const byStatus = groupBy(orders, 'status')
  .sum('revenue', 'amount')
  .count('orders')
  .toArray();

bash

npm install groupjs_by

Every modern article tells you to use native Object.groupBy(). The problem? It stops halfway. Native bucketing only splits your data into isolated arrays. It leaves you stuck writing messy reduce() loops just to figure out a basic sum, average, or count.

// Native Object.groupBy(): Only creates buckets. You still have to loop.
const buckets = Object.groupBy(orders, o => o.status);
const result = Object.keys(buckets).map(status => ({
  status,
  revenue: buckets[status].reduce((sum, o) => sum + o.amount, 0),
  orders: buckets[status].length
}));

// groupjs_by: Groups AND aggregates in a single, fast pass.
const result = groupBy(orders, 'status').sum('revenue', 'amount').count('orders').toArray();

If you are building dashboards, reporting pipelines, or handling metrics, here are two common patterns you can grab right now.

Multi-Key Grouping (Two Dimensions)
Need to group by country and status at the same time? Instead of writing nested loops, pass an array of keys. Calling .toArray() formats the results into flat, chart-ready rows.

You can pass an array of keys for multi-key dimensions like country and status, or use accessor functions for nested JSON data. For full code examples, multi-key implementations, nested JSON accessor patterns, and benchmarks, check the repository.

Zero Dependencies. Built for Performance.

Single-Pass Aggregation: .aggregate() runs math operations concurrently to scan large datasets efficiently.
Safe Loops: Avoids call-stack overflows on giant arrays (100k+ rows).
Data Hygiene: Skips null, undefined, or corrupted non-numeric fields automatically so your math never breaks into NaN.

Check out the full documentation, TypeScript examples, and performance benchmarks on GitHub:

groupBy

Drop a star ⭐ if this saves you from writing another boilerplate reduce loop!

DEV Community: Julio Aguilar