Command/query separation

A function should either DO something or ANSWER something — never both. Bertrand Meyer’s command/query separation (CQS) draws one line through every method you write. A command changes observable state (mutates a field, writes a row, sends a request) and conventionally returns void or just the result of that effect. A query returns a value and leaves the world exactly as it found it — calling it zero times, once, or a hundred times makes no observable difference.

// query: answers, changes nothing observable
getBalance(): number;

// command: does, changes state
deposit(amount: number): void;

The value of the rule is the guarantee it buys: when you see a query, you know it is safe to call. You can log it, assert on it in a test, call it twice, reorder it — and nothing downstream shifts. That single guarantee is what the rest of this lesson cashes in.

The classic violation is a getter that mutates — and it produces “spooky” double-call bugs. A function named like a question (currentUser, peek, nextId, a property getter) that also changes state is the trap, because every caller reasonably assumes it’s a query and calls it freely.

class IdGenerator {
  private n = 0;
  // looks like a query, is secretly a command
  get current(): number {
    return ++this.n; // mutates on every read
  }
}

const gen = new IdGenerator();
console.log(gen.current); // 1
console.log(gen.current); // 2 — reading "current" twice gave different answers

The instant a “read” changes state, two truths a programmer relies on break: reading twice can return different answers, and adding a read (a log line, a debugger watch, an assertion) changes program behaviour. Now no one can inspect the value without risk. The fix isn’t subtle — make the read a real query and give the mutation its own command name.

Separated queries are referentially transparent enough to call freely — which is what makes code predictable and testable. Once a query has no side effect, you can substitute its result for the call without changing behaviour, hoist it out of a loop, cache it, or evaluate it in a test assertion with zero setup. Tests stop needing elaborate “and verify nothing else changed” scaffolding, because a query can’t change anything else.

// pure query: trivial to test, safe to call anywhere
function totalCents(items: LineItem[]): number {
  return items.reduce((sum, i) => sum + i.cents, 0);
}

// command: test by checking the effect it caused, in isolation
function chargeCard(gateway: Gateway, cents: number): Promise<Receipt> {
  return gateway.charge(cents);
}

The asymmetry is deliberate: queries are tested for their return value, commands for their effect. Conflate them and every test has to assert both the answer and the state change — and you’ve lost the ability to use the function in a log line, a guard, or an assertion without consequences.

CQS underpins idempotency reasoning — and therefore safe retries. A pure query is automatically idempotent: calling it again costs nothing and changes nothing, so a retry, a refresh, or a duplicate request is free. Commands are where idempotency must be engineered (dedup keys, conditional writes), and CQS is what lets you see exactly where that engineering is needed. When reads and writes are tangled, you can’t reason about “is it safe to retry this?” at all, because every call might be doing both.

// safe to retry: a query does nothing the second time
const price = quotePrice(cart);        // idempotent for free

// must be made idempotent on purpose: a command has an effect
await placeOrder(cart, idempotencyKey); // retry only safe with the key

This is the senior payoff. In distributed systems, networks duplicate and retry requests for you whether you like it or not. CQS gives you a vocabulary — this is a query, retrying is free; this is a command, retrying needs a key — so duplicate-delivery reasoning becomes mechanical instead of a case-by-case panic.