~/alexsh.blog

$ cat advanced-typescript/14-type-safe-builder-pattern.md

Type-Safe Builder Pattern

February 9, 20261 min readpart 14/20

Difficulty: Advanced. Prerequisites: Generics, mapped types, conditional types, method chaining.

The type-safe builder pattern uses TypeScript's type system to enforce that all required fields are set before building, prevent setting the same field twice, and provide accurate autocompletion at each step.

Key concepts

  • Tracking set/unset fields in the type parameter
  • Progressive type narrowing as methods are called
  • build() only available when all required fields are set
  • Preventing duplicate field setting

Example

codets
interface Config { name: string; email: string; age?: number }

// Extract required keys (not the built-in Required which makes all props required)
type RequiredKeys<T> = { [K in keyof T]-?: undefined extends T[K] ? never : K }[keyof T];

type Builder<T, Set extends keyof T = never> = {
  [K in keyof T as K extends Set ? never : `set${Capitalize<string & K>}`]:
    (v: T[K]) => Builder<T, Set | K>
} & (RequiredKeys<T> extends Set ? { build(): T } : {});

function createBuilder(): Builder<Config> {
  const c: Partial<Config> = {};
  const b: any = {
    setName: (n: string) => { c.name = n; return b; },
    setEmail: (e: string) => { c.email = e; return b; },
    setAge: (a: number) => { c.age = a; return b; },
    build: () => c as Config
  };
  return b;
}

createBuilder().setName('A').setEmail('a@b').build(); // OK
// createBuilder().setName('A').build(); // Error — email required!
// createBuilder().setName('A').setName('B'); // Error — already set!

// Real-world: Kysely — each .select() returns Builder<..., O & { newCol: Type }>

Resources

Practice

Hints

  • Track which fields have been set using a type parameter that accumulates set keys.
  • Use conditional types to only expose build() when all required keys are in the Set parameter.