Designing and honoring contracts

A contract is three clauses: preconditions, postconditions, invariants — and substitutability is defined in terms of them. A precondition is what a caller must guarantee before calling (inputs in range, system in a valid state). A postcondition is what the implementation guarantees on return. An invariant is what stays true before and after every operation. The Liskov rule, stated precisely, is about these: a substitute may weaken preconditions (demand no more of callers) and strengthen postconditions (promise no less), and must preserve invariants — but never the reverse.

/**
 * Stores a record and returns its assigned id.
 * @pre   record.id is unset; record passes validate()
 * @post  the record is durably persisted before this resolves;
 *        get(returnedId) returns an equal record
 * @inv   ids are never reused, even after delete
 */
interface Repository<T extends { id?: string }> {
  save(record: T): Promise<string>;
  get(id: string): Promise<T | null>;
}

The doc comment is not decoration — it is the part of the interface a caller actually relies on. A save that returns before the write is durable hasn’t changed the type, but it has broken the contract.

A conforming implementation and a subtly violating one can be type-identical — types catch shape, not behaviour. Here are two repositories. Both satisfy the TypeScript interface exactly. One honours the contract; the other strengthens a precondition and weakens a postcondition, which is precisely the illegal direction.

// Conforming: weaker preconditions are fine, postcondition is met.
class PgRepository<T extends { id?: string }> implements Repository<T> {
  async save(record: T): Promise<string> {
    const id = crypto.randomUUID();
    await this.db.insert({ ...record, id }); // awaits durability
    return id;                               // post: persisted before resolve
  }
  async get(id: string) { return this.db.findById(id); }
}

// Violating — yet it compiles and passes naive unit tests.
class CacheRepository<T extends { id?: string }> implements Repository<T> {
  async save(record: T): Promise<string> {
    if (!record.id) throw new Error("id required"); // STRENGTHENED precondition
    this.buffer.push(record);                        // not yet durable
    return record.id;                                // WEAKENED postcondition
  }
  async get(id: string) { return this.map.get(id) ?? null; }
}

CacheRepository demands callers supply an id (the base said they must not), and returns before the record is durable (the base promised it would be). A caller written against the contract — “I can save without an id and trust it’s saved” — breaks the moment it’s handed this implementation. The compiler is silent, because nothing about the types is wrong.

Encode what you can in types; pin the rest with a shared contract test run against every implementation. Some clauses move into the type system: make id genuinely optional on input and required on output (save(r: Omit<T,"id">): Promise<T & {id: string}>) and a caller can’t be forced to pass one. But durability, ordering, id-non-reuse — properties of behaviour over time — can’t be expressed in a structural type. For those, write one test suite parameterised over a factory, and run it against each implementation. The suite is the executable contract; an implementation that drifts fails the shared test, not just its own.

// contract.test.ts — one suite, every implementation must pass it.
export function repositoryContract(make: () => Repository<Doc>) {
  test("save assigns an id and persists before resolving", async () => {
    const repo = make();
    const id = await repo.save({ title: "x" });      // no id supplied
    expect(await repo.get(id)).toMatchObject({ title: "x" }); // durable now
  });
  test("ids are never reused after delete", async () => { /* ... */ });
}
// Each implementation opts in — drift in any one is caught here, not in prod.
describe("PgRepository",   () => repositoryContract(() => new PgRepository()));
describe("CacheRepository",() => repositoryContract(() => new CacheRepository()));

CacheRepository now fails the first assertion (it required an id). The contract stopped being a comment people skim and became a gate every implementation must clear.

Shrink the contract: “tell, don’t ask” and narrow interfaces leave fewer clauses to honour — and fewer to violate. Every method and every getter you expose is a clause implementors must get right and a thing callers can couple to. “Tell, don’t ask” — give the object a command and let it decide, instead of pulling out its state and deciding for the caller — removes whole families of preconditions (“only call applyDiscount when isEligible is true” becomes “call checkout(), it knows”). Interface segregation does the same structurally: a fat Repository with save/get/query/stream/migrate forces every implementation to honour clauses it doesn’t need. Split it, and an in-memory cache implements Reader only — there’s no migrate postcondition for it to silently get wrong.

// Narrow contracts: each implementation honours only the clauses it actually has.
interface Reader<T> { get(id: string): Promise<T | null>; }
interface Writer<T> { save(record: Omit<T, "id">): Promise<T & { id: string }>; }
// A read-through cache is a Reader. It can't violate a Writer postcondition
// it was never asked to make.

A smaller contract is not just less code — it is a smaller substitutability surface, so there are fewer ways for an implementation to be subtly wrong.

When substitutability is genuinely uncertain, prefer composition over inheritance. A shared supertype is a promise that every implementation is interchangeable. If you can’t actually make that promise — the classic Square extends Rectangle where setWidth must break Rectangle’s independent-sides invariant, or a ReadOnlyList extends List whose add must throw — then forcing the inheritance ships a lie that callers will trust and that no shared test can rescue, because the contract itself is unsatisfiable. The senior move is to stop forcing the is-a and use has-a: the read-only collection wraps a list and exposes only the operations it can truly honour. No false supertype, no Liskov violation, no throw new Error("unsupported") lurking behind a method the type says exists.

// Don't: ReadOnlyList "is a" List but can't honour add()/remove().
// Do: it "has a" list and exposes only what it can truly promise.
class ReadOnlyView<T> {
  constructor(private readonly items: readonly T[]) {}
  get(i: number) { return this.items[i]; }
  get length() { return this.items.length; }
  // no add/remove to lie about
}