Combinable — Combining Values

Aggregating collections of data is a fundamental task in software engineering. Summing an array of invoice prices, concatenating list items into a single string, or merging a series of configuration profiles are structurally identical operations.

In JavaScript, our standard tool for this is Array.prototype.reduce. While powerful, reduce forces us to explicitly supply both the combining callback and the initial starting value at every single call site:

const totalCost = items.reduce((sum, item) => sum + item.price, 0);
const fullText  = fragments.reduce((acc, str) => acc + str, "");

This leads to redundant, repetitive ceremony. If we want to sum numbers, we must write (acc, x) => acc + x and 0. If we want to multiply numbers, we must write (acc, x) => acc * x and 1. The combining logic and the starting value are decoupled, forcing the developer to track both separately.

Combinable<A> packages these two related concerns into a single, reusable data structure:

type Combinable<A> = {
  readonly empty: A;
  readonly combine: (next: A) => (accumulated: A) => A;
};

empty is the neutral starting element. Combining any value with empty yields the original value unchanged.
combine is the data-last combining operation, taking the next element and appending it to the accumulated value.

In abstract algebra, this combination is known as a Monoid. By packaging the baseline value and the appending logic into a first-class blueprint, we get a highly reusable, clean strategy for collection aggregation.

Built-In Aggregators

The library provides optimized, built-in combiners for standard primitives:

import { Combinable } from "@nlozgachev/pipelined/core";

// 1. Strings (empty: "")
Combinable.string.combine(" world")("hello"); // "hello world"

// 2. Numbers (Sum vs Product)
// Both interpretations of combining numbers are equally valid, carrying different baselines:
Combinable.sum.combine(3)(2);     // 5 (empty: 0)
Combinable.product.combine(3)(2); // 6 (empty: 1)

// 3. Booleans (All vs Any)
Combinable.all.combine(true)(true);  // true (empty: true)
Combinable.any.combine(true)(false); // true (empty: false)

// 4. Arrays
Combinable.array<number>().combine([3, 4])([1, 2]); // [1, 2, 3, 4]

Notice the numbers example. Summation and multiplication are both mathematically valid ways to combine numbers, but they require different baseline elements (0 for sum, 1 for product). By using Combinable.sum or Combinable.product, we make our exact aggregation intent explicit in our code.

Folding Collections point-free: fold

Combinable.fold accepts a Combinable<A> and returns a clean, single-argument function (as: A[]) => A that collapses an array into a single value:

import { pipe } from "@nlozgachev/pipelined/composition";

// Collapsing strings
pipe(["hello", ", ", "world"], Combinable.fold(Combinable.string)); // "hello, world"

// Summing numbers
pipe([1, 2, 3, 4, 5], Combinable.fold(Combinable.sum)); // 15

// Multiplying numbers
pipe([2, 3, 4], Combinable.fold(Combinable.product)); // 24

// Folding an empty array returns the baseline "empty" value:
pipe([], Combinable.fold(Combinable.sum)); // 0

Combining Optional Values: maybe

Often, the values we want to combine are optional, represented by Maybe<A>. Combinable.maybe lifts a Combinable<A> to operate safely over Maybe<A> values:

import { Maybe } from "@nlozgachev/pipelined/core";

const maybeSum = Combinable.maybe(Combinable.sum);

// None acts as the neutral element:
maybeSum.combine(Maybe.make.some(3))(Maybe.make.some(2)); // Some(5)
maybeSum.combine(Maybe.make.none())(Maybe.make.some(5));  // Some(5)
maybeSum.combine(Maybe.make.some(5))(Maybe.make.none());  // Some(5)

This makes folding collections of optional domain fields extremely elegant:

const totalScores = pipe(
  [Maybe.make.some(10), Maybe.make.none(), Maybe.make.some(20)],
  Combinable.fold(Combinable.maybe(Combinable.sum)),
); // Some(30)

Problems it solves

Aggregating distributed telemetry and metric reports: In telemetry and reporting services, merging multiple event payloads (such as summing total request counts, combining latency tallies, and aggregating error counts) often requires repetitive reducer loops. Combinable.struct combines complex metric records automatically based on field-level rules.
Hierarchical configuration merging: In applications loading layered configurations (such as default settings overlaid with environment variables and tenant-specific overrides), Combinable.record merges configuration layers cleanly while preserving immutability.
Aggregating sparse or optional metrics (Combinable.maybe): Folding streams of optional data (such as user ratings or partial session durations) where missing values (None) are safely ignored while valid numbers are accumulated.
Reusable collection reduction strategies: Instead of re-writing Array.prototype.reduce callbacks with manual initial values across multiple call sites, Combinable provides named, reusable aggregation strategies (Combinable.sum, Combinable.concat, Combinable.maybe) for point-free list folding.