Primitive obsession & data clumps

Primitive obsession is using a language primitive to stand in for a domain concept, which forces every caller to know the concept’s rules. A money value has invariants (a currency, a scale, non-negativity for a price) and behaviour (add only same-currency, round on division). Modelled as number, none of that travels with the value, so each call site re-implements it — inconsistently.

// Money as a bare number: the rules live nowhere, so they live everywhere.
function priceWithTax(amount: number): number {
  return amount + amount * 0.2; // dollars? cents? can amount be -5? nobody knows
}

const refund = order.total / 3;   // float division → 33.333333, a fraction of a cent
const eur = usdAmount;            // type system is fine with mixing currencies

Each of those lines is locally reasonable and globally wrong. The number carries no scale, no currency, no rounding policy — so the policy is duplicated, and duplicated rules drift.

A value object centralises the validation and behaviour the primitive scattered, so the rule has exactly one home. Wrap the concept in a small immutable type that owns its invariants and operations. Now there is one place the rule can be wrong, and one place to fix it.

class Money {
  private constructor(readonly cents: number, readonly currency: string) {}

  static of(cents: number, currency: string): Money {
    if (!Number.isInteger(cents)) throw new Error("Money is whole cents");
    if (cents < 0) throw new Error("Money cannot be negative");
    return new Money(cents, currency);
  }

  add(other: Money): Money {
    if (other.currency !== this.currency) throw new Error("currency mismatch");
    return new Money(this.cents + other.cents, this.currency);
  }
}

Construction is the only door, so an invalid Money cannot exist. Mixing currencies is now a thrown error instead of a silent usd + eur. The validation that was copy-pasted across priceWithTax, refund, and convert collapses into the type — the change-amplification lever from unit 00, applied to a single value.

A data clump is the same group of values that always travel together; recurring togetherness is the runtime telling you a concept is missing. When lat and lng appear in the same parameter list everywhere, validated separately everywhere, the pair is a concept — Coordinate — that you simply haven’t named yet.

// Before: lat & lng are a clump — three params that are really one thing,
// plus a parameter-order bug waiting to happen.
function distance(lat1: number, lng1: number, lat2: number, lng2: number): number { /* … */ }
distance(lng1, lat1, lng2, lat2); // swapped, compiles, ships, wrong by a continent

// After: name the concept the clump was pointing at.
class Coordinate {
  constructor(readonly lat: number, readonly lng: number) {
    if (Math.abs(lat) > 90 || Math.abs(lng) > 180) throw new Error("out of range");
  }
  distanceTo(other: Coordinate): number { /* … */ }
}

The clump didn’t just shorten the signature. It gave the range check one home, killed the order-swap class of bug, and gave behaviour (distanceTo) a natural place to live instead of floating as a free function with four loose arguments.

The failure mode is the opposite reflex: wrapping every primitive in a class even when it carries no invariant or behaviour — ceremony without payoff. A value object pays for itself when there is a rule to centralise: a validation, an arithmetic that must stay consistent, a unit that must not be confused. A primitive that has none of those gains nothing from a wrapper but indirection.

// Payoff: EmailAddress has a real invariant (must be a valid address) reused everywhere.
class EmailAddress { /* validates once, every caller trusts it */ }

// Ceremony: a wrapper with zero invariant and zero behaviour.
class FirstName {
  constructor(readonly value: string) {} // any string is a valid first name
}
// Now every read is `name.value` and you've added a type that buys nothing.

The senior test is not “is this a primitive?” but “does this concept have a rule or behaviour that is currently duplicated or unenforced?” If yes, the value object centralises it. If no, leave the primitive — a type alias (type UserId = string) often captures the intent at zero ceremony. Over-wrapping is its own smell; it just costs reading time instead of correctness.