Crafting Type-Safe Builders in TypeScript

TypeScript's strength lies in its static typing, helping catch errors at compile time. However, constructing complex objects with many optional properties can lead to verbose and error-prone code. This challenge focuses on building a type-safe builder pattern in TypeScript. The goal is to create a fluent API for object construction that ensures all required properties are set and prevents accidental misuse of optional properties, all while maintaining excellent type safety.

Problem Description

You need to implement a generic Builder class in TypeScript that allows for the type-safe construction of any object. The builder should:

1. Support required properties: The builder must enforce that all properties designated as "required" in the target object's type are set before the object can be built.
2. Support optional properties: The builder should allow setting optional properties.
3. Provide a fluent API: Method chaining should be supported for setting properties.
4. Maintain type safety: TypeScript should correctly infer types and flag any attempts to set invalid properties or fail to set required ones.
5. Handle immutability: Each method called on the builder should return a new instance of the builder with the updated state, ensuring the original builder remains unchanged.

Consider a scenario where you need to build a User object with required id and username properties, and optional email, isActive, and roles properties.

Key Requirements:

• A generic Builder<T> class where T represents the target object type.
• A set<K extends keyof T>(key: K, value: T[K]): Builder<T> method for setting properties.
• A build(): T method to finalize the object construction.
• The build() method should only be callable when all required properties are set.
• The builder should be immutable: each set operation should return a new builder instance.

Expected Behavior:

When a UserBuilder is used, the following should hold true:

• Calling build() before id and username are set should result in a compile-time error.
• Setting email on the builder should not affect the ability to set isActive later.
• Attempting to set a property that does not exist on the User type should result in a compile-time error.
• The final User object should have all the properties that were set during the building process.

Edge Cases:

• How do you differentiate between required and optional properties in the builder's methods without explicit configuration? The builder should infer this from the target type T.
• What happens if a property is set multiple times? The latest value should be retained.

Examples

Example 1: Basic User Creation

// Assume Target Type:
interface User {
  id: number;
  username: string;
  email?: string;
  isActive?: boolean;
  roles?: string[];
}

// --- Expected Usage ---
// const userBuilder = new Builder<User>(); // Conceptual, actual implementation will be specific or generic

// This should NOT compile because id and username are missing
// const incompleteUser = userBuilder.set('email', 'test@example.com').build();

// This should compile
// const completeUser = userBuilder
//   .set('id', 1)
//   .set('username', 'johndoe')
//   .set('email', 'john.doe@example.com')
//   .set('isActive', true)
//   .build();

// console.log(completeUser);
// Expected Output: { id: 1, username: 'johndoe', email: 'john.doe@example.com', isActive: true }

Example 2: Optional Properties and Immutability

// --- Expected Usage ---
// const userBuilder1 = new Builder<User>();
// const userBuilder2 = userBuilder1.set('id', 2).set('username', 'janedoe');

// // userBuilder1 should not have id or username set yet (if builder is immutable)
// // This would likely result in a compile-time error if build() is called on userBuilder1
// // const user1Built = userBuilder1.build(); // Expected compile-time error

// const user2Built = userBuilder2.set('roles', ['admin', 'editor']).build();

// console.log(user2Built);
// Expected Output: { id: 2, username: 'janedoe', roles: [ 'admin', 'editor' ] }

Example 3: Compile-Time Errors

// --- Expected Errors ---

// Error 1: Trying to set a non-existent property
// const errorUser = new Builder<User>()
//   .set('id', 3)
//   .set('username', 'testuser')
//   .set('nonExistentProp', 'value') // Expected: TypeScript error
//   .build();

// Error 2: Calling build() with missing required properties
// const errorUserMissing = new Builder<User>()
//   .set('id', 4)
//   // username is missing
//   .set('email', 'missing@example.com')
//   .build(); // Expected: TypeScript error before execution

// Error 3: Type mismatch
// const errorUserType = new Builder<User>()
//   .set('id', 'not a number') // Expected: TypeScript error
//   .set('username', 'user')
//   .build();

Constraints

• The solution must be written entirely in TypeScript.
• The builder should handle any valid TypeScript type T as its target.
• The implementation should focus on leveraging TypeScript's type system, not runtime checks for property existence or requiredness.
• Performance is not a primary concern, but the solution should be reasonably efficient.

Notes

• Think about how you can define the state of the builder. You might need to track which properties have been set.
• Consider the use of mapped types and conditional types in TypeScript to achieve the desired type safety for set and build methods.
• The immutability requirement can be achieved by returning this in a typed manner that reflects the new state, or by creating new instances.
• For the build() method to be callable only when required properties are met, you might need a way to represent partial states of the builder. This could involve different generic types for the builder itself.