Course contentsShow
← TypeScript
Lesson 1429 of 1,79632. Advanced PatternsFree lesson

Conditional Method Availability

Make builder methods conditionally available based on previous calls using conditional types and overloads.

Conditional Method Availability

You'll learn how to make certain builder methods appear or disappear based on which methods have already been called.

What Is Conditional Method Availability?

Imagine a builder where calling .withName() should only be possible if you haven't already called it. Or a Query builder where .execute() only appears after you've called .select() and .from(). This is conditional method availability: using TypeScript's type system to control which methods exist based on the builder's state.

This pattern takes the phantom type builder concept and pushes it further—instead of just tracking state, we make methods conditionally visible using conditional types and method overloads.

How It Works

The core technique:

  1. Use a type parameter to track state (like which methods have been called)
  2. Use conditional types to check that state
  3. Use method overloads or conditional return types to include or exclude methods based on the state
  4. Return this with an updated state type after each method call

Think of it like a video game skill tree: you can only unlock certain abilities after you've unlocked their prerequisites. The type system enforces the dependency graph.

The Pattern in Action

type BuilderState = {
  hasName: boolean;
  hasAge: boolean;
};

class ConditionalBuilder<S extends BuilderState = { hasName: false; hasAge: false }> {
  private data: Partial<{ name: string; age: number }> = {};

  // withName only available when hasName is false
  withName<T extends S>(
    this: T extends { hasName: false } ? ConditionalBuilder<T> : never,
    name: string
  ): ConditionalBuilder<S & { hasName: true }> {
    this.data.name = name;
    return this as unknown as ConditionalBuilder<S & { hasName: true }>;
  }

  // withAge only available when hasAge is false
  withAge<T extends S>(
    this: T extends { hasAge: false } ? ConditionalBuilder<T> : never,
    age: number
  ): ConditionalBuilder<S & { hasAge: true }> {
    this.data.age = age;
    return this as unknown as ConditionalBuilder<S & { hasAge: true }>;
  }

  // build only available when both are set
  build<T extends S>(
    this: T extends { hasName: true; hasAge: true } ? ConditionalBuilder<T> : never
  ): { name: string; age: number } {
    return this.data as { name: string; age: number };
  }
}

const builder = new ConditionalBuilder();

builder
  .withName("Alice")
  .withAge(30)
  .build(); // ✓ Valid

// builder.withName("Alice").withName("Bob"); // ✗ Error: withName not available
// builder.build(); // ✗ Error: build not available without name and age

The this parameter with a conditional type creates the constraint: the method only exists when the condition is true, otherwise it becomes never (impossible to call).

Key Takeaway: Conditional method availability uses conditional types on the this parameter to make methods appear or disappear based on tracked state, creating compile-time enforcement of required call sequences and preventing duplicate or invalid operations.