Builder Pattern with Fluent Generics

The plain-language idea

A normal builder's .build() method has a problem: it either requires every field to already be optional on the target type (weakening the type you actually want), or it can't know at compile time whether you've called every required .set*() method yet. The fix is to make the builder's own type change with every call, tracking which fields have been provided so far as a generic type parameter — and only expose .build() once that accumulated type proves every required field is present.

interface Pizza {
  size: "small" | "medium" | "large";
  crust: "thin" | "thick";
  toppings: string[];
}

class PizzaBuilder<Built extends Partial<Pizza> = {}> {
  private data: Built;

  constructor(data: Built) {
    this.data = data;
  }

  size(size: Pizza["size"]): PizzaBuilder<Built & { size: Pizza["size"] }> {
    return new PizzaBuilder({ ...this.data, size });
  }

  crust(crust: Pizza["crust"]): PizzaBuilder<Built & { crust: Pizza["crust"] }> {
    return new PizzaBuilder({ ...this.data, crust });
  }

  toppings(toppings: string[]): PizzaBuilder<Built & { toppings: string[] }> {
    return new PizzaBuilder({ ...this.data, toppings });
  }

  build(this: PizzaBuilder<Pizza>): Pizza {
    return this.data;
  }
}

Each fluent method doesn't return this — it returns a new builder whose generic parameter is the old accumulated type intersected with the new field. Built & { size: Pizza["size"] } means "everything already set, plus size now too." The type parameter grows, call by call, into an ever-more-complete picture of what's been provided.

See it in a real thing: build() only exists once everything's there

const pizza = new PizzaBuilder({})
  .size("large")
  .crust("thin")
  .toppings(["olives"])
  .build(); // ✅ Built is now { size, crust, toppings } — matches Pizza exactly

const incomplete = new PizzaBuilder({})
  .size("large")
  .crust("thin")
  .build();
// ❌ Property 'this' is incompatible — Built is { size, crust }, missing 'toppings'

The trick living in build(this: PizzaBuilder<Pizza>): Pizza is TypeScript's this parameter — a way to constrain which specific instantiation of the class a method is even callable on. build isn't callable on any PizzaBuilder<Built>; it's only callable on one whose Built is assignable to the full Pizza type. Calling it before every field is set means this's actual type (say, PizzaBuilder<{ size, crust }>) doesn't satisfy PizzaBuilder<Pizza>, and TypeScript rejects the call — at the .build() call site, not buried somewhere at runtime.

What people usually miss

Watch out

• Each fluent call must return a new builder instance, not this. Returning this from .size() would keep the same runtime object but couldn't actually change its own generic type parameter after construction — TypeScript's type system has no mechanism for a value's static type to mutate in place, so a new object carrying the new type is required.
• The this parameter trick has nothing to do with this at runtime. build(this: PizzaBuilder<Pizza>) never receives an actual argument for this — it's purely a compile-time constraint on which instantiations of the class the method is callable on. Omit it, and build() becomes callable on an incomplete builder, silently returning an object with missing fields typed as Pizza anyway.
• This pattern's error messages are notoriously unhelpful. "Property 'this' is incompatible" doesn't say which field is missing — reading the two Built types side by side (or hovering the failing call) is usually the fastest way to see the actual gap, which is a real, known ergonomic cost of the pattern worth weighing against its safety.

Why this matters in interviews

"How would you design a builder API where forgetting a required field is a compile error, not a runtime one?" is a strong systems-design-flavored TypeScript question — the answer requires combining generics, intersection types, and the this parameter constraint, which is exactly the kind of multi-feature synthesis that separates "knows the syntax" from "can design with it."