Builder Pattern

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

class FluentBuilder {
    private value: string = '';
    
    // Key: Each method returns 'this'
    append(text: string): this {
        this.value += text;
        return this;  // <-- Enables chaining
    }
    
    appendLine(text: string): this {
        this.value += text + '\n';
        return this;  // <-- Enables chaining
    }
    
    uppercase(): this {
        this.value = this.value.toUpperCase();
        return this;  // <-- Enables chaining
    }
    
    // Terminal method - returns final result
    build(): string {
        return this.value;
    }
}
 
// Without fluent interface (multiple statements)
const builder1 = new FluentBuilder();
builder1.append('Hello');
builder1.append(' ');
builder1.append('World');
builder1.uppercase();
const result1 = builder1.build();
 
// With fluent interface (single chained expression)
const result2 = new FluentBuilder()
    .append('Hello')
    .append(' ')
    .append('World')
    .uppercase()
    .build();
 
// Both produce "HELLO WORLD"
// The fluent version is one expression, more composable, and clearer

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

// Problem: Returning the base type breaks chaining for subclasses
 
class BaseBuilder {
    protected name: string = '';
    
    // Returns BaseBuilder - problem for inheritance
    setName(name: string): BaseBuilder {
        this.name = name;
        return this;
    }
}
 
class ExtendedBuilder extends BaseBuilder {
    private description: string = '';
    
    setDescription(desc: string): ExtendedBuilder {
        this.description = desc;
        return this;
    }
}
 
// This doesn't work!
const result = new ExtendedBuilder()
    .setName('Test')      // Returns BaseBuilder
    .setDescription('...')  // ERROR: setDescription not on BaseBuilder
 
// ============================================
// Solution: Use 'this' as return type
// ============================================
 
class BaseBuilder2 {
    protected name: string = '';
    
    // Returns 'this' - the actual runtime type
    setName(name: string): this {
        this.name = name;
        return this;
    }
}
 
class ExtendedBuilder2 extends BaseBuilder2 {
    private description: string = '';
    
    setDescription(desc: string): this {
        this.description = desc;
        return this;
    }
}
 
// Now this works!
const result2 = new ExtendedBuilder2()
    .setName('Test')        // Returns ExtendedBuilder2 (this)
    .setDescription('...')  // setDescription is available
    .setName('Updated')     // Can still chain parent methods
    .build();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// Java's approach: Curiously Recurring Template Pattern (CRTP)
 
abstract class BaseBuilder<T extends BaseBuilder<T>> {
    protected String name;
    
    @SuppressWarnings("unchecked")
    protected T self() {
        return (T) this;
    }
    
    public T setName(String name) {
        this.name = name;
        return self();  // Returns T, the actual subclass type
    }
}
 
class ConcreteBuilder extends BaseBuilder<ConcreteBuilder> {
    private String description;
    
    public ConcreteBuilder setDescription(String desc) {
        this.description = desc;
        return self();
    }
    
    public Product build() {
        return new Product(name, description);
    }
}
 
// Now chaining works correctly
Product product = new ConcreteBuilder()
    .setName("Test")
    .setDescription("...")
    .setName("Updated")
    .build();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

// ❌ Poor fluent interface - reads awkwardly
const req1 = new RequestBuilder()
    .setMethod('POST')
    .setUrl('/api/users')
    .setHeader('Content-Type', 'application/json')
    .setBody({ name: 'John' })
    .setRetryCount(3)
    .setTimeoutMilliseconds(5000)
    .buildRequest();
 
// ✅ Excellent fluent interface - reads naturally
const req2 = new RequestBuilder()
    .post('/api/users')              // Combined method + url
    .contentType('application/json') // Specific header shorthand
    .body({ name: 'John' })          // Simple, obvious
    .withRetries(3)                  // Preposition for clarity
    .timeout(5000)                   // Units in documentation
    .build();
 
// ✅ Even better with domain-specific shortcuts
const req3 = new RequestBuilder()
    .post('/api/users')
    .json({ name: 'John' })  // Sets body AND content-type
    .authenticated()          // Uses default auth mechanism
    .resilient()              // Applies standard retry policy
    .build();
 
// ============================================
// Implementation of well-designed vocabulary
// ============================================
 
class RequestBuilder {
    private config: RequestConfig = {
        method: 'GET',
        url: '',
        headers: new Map(),
        body: undefined,
        timeout: 30000,
        retries: 0,
    };
    
    // HTTP method shortcuts that set URL too
    get(url: string): this {
        return this.method('GET').url(url);
    }
    
    post(url: string): this {
        return this.method('POST').url(url);
    }
    
    put(url: string): this {
        return this.method('PUT').url(url);
    }
    
    delete(url: string): this {
        return this.method('DELETE').url(url);
    }
    
    // Generic method/url for flexibility
    method(method: HttpMethod): this {
        this.config.method = method;
        return this;
    }
    
    url(url: string): this {
        this.config.url = url;
        return this;
    }
    
    // Common headers as named methods
    contentType(type: string): this {
        return this.header('Content-Type', type);
    }
    
    accept(type: string): this {
        return this.header('Accept', type);
    }
    
    authorization(value: string): this {
        return this.header('Authorization', value);
    }
    
    bearer(token: string): this {
        return this.authorization(`Bearer ${token}`);
    }
    
    // Generic header for anything else
    header(name: string, value: string): this {
        this.config.headers.set(name, value);
        return this;
    }
    
    headers(headers: Record<string, string>): this {
        for (const [name, value] of Object.entries(headers)) {
            this.header(name, value);
        }
        return this;
    }
    
    // Body shortcuts
    body(data: unknown): this {
        this.config.body = data;
        return this;
    }
    
    json(data: unknown): this {
        return this.contentType('application/json').body(data);
    }
    
    form(data: Record<string, string>): this {
        return this.contentType('application/x-www-form-urlencoded')
            .body(new URLSearchParams(data));
    }
    
    // Configuration with readable names
    timeout(ms: number): this {
        this.config.timeout = ms;
        return this;
    }
    
    withRetries(count: number): this {
        this.config.retries = count;
        return this;
    }
    
    // Semantic shortcuts for common configurations
    resilient(): this {
        return this.withRetries(3).timeout(10000);
    }
    
    authenticated(): this {
        // Use stored credentials or throw if not configured
        const token = getStoredAuthToken();
        return this.bearer(token);
    }
    
    build(): HttpRequest {
        this.validate();
        return new HttpRequest(this.config);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

class EmailBuilder {
    private to?: string;
    private subject?: string;
    private body?: string;
    private from?: string;  // Optional with default
    
    to(address: string): this {
        this.to = address;
        return this;
    }
    
    subject(text: string): this {
        this.subject = text;
        return this;
    }
    
    body(content: string): this {
        this.body = content;
        return this;
    }
    
    from(address: string): this {
        this.from = address;
        return this;
    }
    
    build(): Email {
        // Runtime validation
        if (!this.to) throw new Error('Recipient (to) is required');
        if (!this.subject) throw new Error('Subject is required');
        if (!this.body) throw new Error('Body is required');
        
        return new Email({
            to: this.to,
            subject: this.subject,
            body: this.body,
            from: this.from ?? 'noreply@example.com',
        });
    }
}
 
// This compiles but fails at runtime
const email = new EmailBuilder()
    .subject('Hello')
    // Missing 'to' and 'body'
    .build();  // Runtime error!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

class EmailBuilder {
    private config: EmailConfig;
    
    // Required parameters passed to constructor
    constructor(to: string, subject: string, body: string) {
        this.config = {
            to,
            subject,
            body,
            from: 'noreply@example.com',
            cc: [],
            bcc: [],
            attachments: [],
            priority: 'normal',
        };
    }
    
    // Only optional methods need to be fluent
    from(address: string): this {
        this.config.from = address;
        return this;
    }
    
    cc(...addresses: string[]): this {
        this.config.cc.push(...addresses);
        return this;
    }
    
    bcc(...addresses: string[]): this {
        this.config.bcc.push(...addresses);
        return this;
    }
    
    attach(file: Attachment): this {
        this.config.attachments.push(file);
        return this;
    }
    
    highPriority(): this {
        this.config.priority = 'high';
        return this;
    }
    
    build(): Email {
        return new Email(this.config);
    }
}
 
// Required parameters enforced at construction
const email = new EmailBuilder(
    'user@example.com',
    'Welcome!',
    'Thank you for signing up.'
)
    .from('hello@company.com')
    .cc('manager@company.com')
    .highPriority()
    .build();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

// Type state pattern: track completion at compile time
 
// Phantom types for tracking required steps
interface HasTo {}
interface HasSubject {}
interface HasBody {}
 
// Builder with generic tracking of completed steps
class EmailBuilder<CompletedSteps = {}> {
    private config: Partial<EmailConfig> = {};
    
    to(address: string): EmailBuilder<CompletedSteps & HasTo> {
        this.config.to = address;
        // Return a new type that includes HasTo
        return this as unknown as EmailBuilder<CompletedSteps & HasTo>;
    }
    
    subject(text: string): EmailBuilder<CompletedSteps & HasSubject> {
        this.config.subject = text;
        return this as unknown as EmailBuilder<CompletedSteps & HasSubject>;
    }
    
    body(content: string): EmailBuilder<CompletedSteps & HasBody> {
        this.config.body = content;
        return this as unknown as EmailBuilder<CompletedSteps & HasBody>;
    }
    
    // Optional steps don't add to CompletedSteps
    from(address: string): this {
        this.config.from = address;
        return this;
    }
    
    cc(...addresses: string[]): this {
        this.config.cc = addresses;
        return this;
    }
    
    // build() only available when all required steps completed
    // This method is conditionally available
}
 
// Conditional method availability using intersection types
interface EmailBuilder<CompletedSteps> {
    build: CompletedSteps extends HasTo & HasSubject & HasBody 
        ? () => Email 
        : never;
}
 
// Implementation detail: add build to prototype conditionally
EmailBuilder.prototype.build = function() {
    return new Email(this.config as EmailConfig);
};
 
// Usage - type system enforces requirements
const builder = new EmailBuilder()
    .to('user@example.com')
    .subject('Hello');
// builder.build(); // ERROR: build is 'never' - body not set
 
const complete = new EmailBuilder()
    .to('user@example.com')
    .subject('Hello')
    .body('Welcome!');
complete.build(); // OK! All required steps done

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

/** Duration in milliseconds */
type Milliseconds = number;
 
/** Count of retry attempts */
type RetryCount = number;
 
/** HTTP methods supported by the request builder */
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 
/**
 * Builds HTTP requests with a fluent interface.
 * 
 * @example
 * ```typescript
 * const request = new RequestBuilder()
 *     .post('/api/users')
 *     .json({ name: 'John' })
 *     .build();
 * ```
 */
class RequestBuilder {
    private config: RequestConfig = { /* defaults */ };
    
    // ==========================================
    // HTTP Methods - grouped for autocomplete
    // ==========================================
    
    /**
     * Sets the HTTP method to GET and configures the URL.
     * @param url - The request URL (absolute or relative)
     * @example
     * ```typescript
     * builder.get('/api/users')
     * builder.get('https://api.example.com/users')
     * ```
     */
    get(url: string): this {
        return this.method('GET').url(url);
    }
    
    /**
     * Sets the HTTP method to POST and configures the URL.
     * @param url - The request URL (absolute or relative)
     */
    post(url: string): this {
        return this.method('POST').url(url);
    }
    
    /**
     * Sets the HTTP method to PUT and configures the URL.
     * @param url - The request URL (absolute or relative)
     */
    put(url: string): this {
        return this.method('PUT').url(url);
    }
    
    /**
     * Sets the HTTP method to DELETE and configures the URL.
     * @param url - The request URL (absolute or relative)
     */
    delete(url: string): this {
        return this.method('DELETE').url(url);
    }
    
    // ==========================================
    // with* methods - configuration group
    // ==========================================
    
    /**
     * Sets the request timeout.
     * @param duration - Timeout in milliseconds (default: 30000)
     * @throws Error if duration is negative
     * @example
     * ```typescript
     * builder.withTimeout(5000)  // 5 seconds
     * ```
     */
    withTimeout(duration: Milliseconds): this {
        if (duration < 0) {
            throw new Error('Timeout cannot be negative');
        }
        this.config.timeout = duration;
        return this;
    }
    
    /**
     * Configures automatic retry behavior.
     * @param count - Number of retry attempts (0 = no retries)
     * @param backoff - Optional backoff strategy ('linear' | 'exponential')
     * @example
     * ```typescript
     * builder.withRetries(3)
     * builder.withRetries(5, 'exponential')
     * ```
     */
    withRetries(count: RetryCount, backoff?: 'linear' | 'exponential'): this {
        this.config.retries = count;
        this.config.backoffStrategy = backoff ?? 'linear';
        return this;
    }
    
    /**
     * Configures authentication using a bearer token.
     * @param token - The bearer token (without 'Bearer ' prefix)
     * @example
     * ```typescript
     * builder.withBearerAuth('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...')
     * ```
     */
    withBearerAuth(token: string): this {
        return this.header('Authorization', `Bearer ${token}`);
    }
    
    /**
     * Configures Basic authentication.
     * @param username - The username
     * @param password - The password
     */
    withBasicAuth(username: string, password: string): this {
        const encoded = btoa(`${username}:${password}`);
        return this.header('Authorization', `Basic ${encoded}`);
    }
    
    // ==========================================
    // Terminal methods - clearly final
    // ==========================================
    
    /**
     * Builds the final HttpRequest object.
     * 
     * This is a terminal operation that validates the configuration
     * and creates an immutable request object.
     * 
     * @throws Error if required configuration is missing
     * @returns The configured HttpRequest
     */
    build(): HttpRequest {
        this.validate();
        return Object.freeze(new HttpRequest(this.config));
    }
    
    /**
     * Builds and immediately executes the request.
     * 
     * Convenience method equivalent to `builder.build().execute()`.
     * 
     * @returns Promise resolving to the response
     */
    async execute<T>(): Promise<HttpResponse<T>> {
        return this.build().execute<T>();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

// Best approach: Let methods be called in any order
// Apply configuration in correct order at build time
 
class ConnectionBuilder {
    private config = {
        host: '',
        port: 0,
        ssl: false,
        sslCert: '',
        auth: null as AuthConfig | null,
        poolSize: 10,
    };
    
    // Order of these calls doesn't matter
    host(host: string): this { this.config.host = host; return this; }
    port(port: number): this { this.config.port = port; return this; }
    enableSsl(cert: string): this { 
        this.config.ssl = true; 
        this.config.sslCert = cert; 
        return this; 
    }
    authenticate(user: string, pass: string): this {
        this.config.auth = { user, pass };
        return this;
    }
    poolSize(size: number): this { this.config.poolSize = size; return this; }
    
    build(): Connection {
        // Apply configuration in CORRECT order regardless of call order
        const connection = new Connection();
        
        // Step 1: Basic connection info
        connection.setHost(this.config.host);
        connection.setPort(this.config.port);
        
        // Step 2: SSL must be configured before connecting
        if (this.config.ssl) {
            connection.configureSsl(this.config.sslCert);
        }
        
        // Step 3: Connection pool
        connection.setPoolSize(this.config.poolSize);
        
        // Step 4: Authentication (after SSL is ready)
        if (this.config.auth) {
            connection.authenticate(this.config.auth.user, this.config.auth.pass);
        }
        
        return connection;
    }
}
 
// Both orderings produce identical, correct results
const conn1 = new ConnectionBuilder()
    .host('db.example.com')
    .authenticate('admin', 'secret')  // Called before SSL
    .enableSsl('/path/to/cert')       // But SSL applies first
    .port(5432)
    .build();
 
const conn2 = new ConnectionBuilder()
    .enableSsl('/path/to/cert')
    .host('db.example.com')
    .port(5432)
    .authenticate('admin', 'secret')
    .build();
 
// conn1 and conn2 are equivalent!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

// When order IS significant, use separate builder stages
// Each stage returns a different builder type with only valid next methods
 
class QueryBuilder {
    static select(...columns: string[]): FromClause {
        return new FromClause(columns);
    }
}
 
class FromClause {
    constructor(private columns: string[]) {}
    
    from(table: string): WhereClause {
        return new WhereClause(this.columns, table);
    }
}
 
class WhereClause {
    private conditions: string[] = [];
    
    constructor(
        private columns: string[],
        private table: string
    ) {}
    
    where(condition: string): this {
        this.conditions.push(condition);
        return this;
    }
    
    and(condition: string): this {
        this.conditions.push('AND ' + condition);
        return this;
    }
    
    or(condition: string): this {
        this.conditions.push('OR ' + condition);
        return this;
    }
    
    orderBy(column: string, direction: 'ASC' | 'DESC' = 'ASC'): FinalClause {
        return new FinalClause(
            this.columns, 
            this.table, 
            this.conditions, 
            column, 
            direction
        );
    }
    
    build(): SqlQuery {
        return new FinalClause(this.columns, this.table, this.conditions).build();
    }
}
 
class FinalClause {
    constructor(
        private columns: string[],
        private table: string,
        private conditions: string[],
        private orderColumn?: string,
        private orderDirection?: 'ASC' | 'DESC'
    ) {}
    
    limit(count: number): this {
        // Add limit
        return this;
    }
    
    build(): SqlQuery {
        let sql = `SELECT ${this.columns.join(', ')} FROM ${this.table}`;
        if (this.conditions.length > 0) {
            sql += ' WHERE ' + this.conditions.join(' ');
        }
        if (this.orderColumn) {
            sql += ` ORDER BY ${this.orderColumn} ${this.orderDirection}`;
        }
        return new SqlQuery(sql);
    }
}
 
// Usage - type system enforces correct order
const query = QueryBuilder
    .select('id', 'name', 'email')
    .from('users')                    // Must come after select
    .where('active = true')
    .and('role = \'admin\'')
    .orderBy('name', 'ASC')           // Must come after where
    .limit(10)                        // Must come after orderBy
    .build();
 
// This won't compile:
// QueryBuilder.select('id').where('x = 1')  // ERROR: no 'where' on select result
// QueryBuilder.select('id').from('t').limit(5).where('x')  // ERROR: no 'where' on FinalClause

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

// Each method returns a NEW builder, leaving original unchanged
 
class ImmutableRequestBuilder {
    // Config is readonly; store as a fresh object each time
    private readonly config: Readonly<RequestConfig>;
    
    constructor(config: Partial<RequestConfig> = {}) {
        this.config = Object.freeze({
            method: 'GET',
            url: '',
            headers: {},
            timeout: 30000,
            ...config,
        });
    }
    
    // Each method creates a new builder with updated config
    method(method: HttpMethod): ImmutableRequestBuilder {
        return new ImmutableRequestBuilder({
            ...this.config,
            method,
        });
    }
    
    url(url: string): ImmutableRequestBuilder {
        return new ImmutableRequestBuilder({
            ...this.config,
            url,
        });
    }
    
    header(name: string, value: string): ImmutableRequestBuilder {
        return new ImmutableRequestBuilder({
            ...this.config,
            headers: {
                ...this.config.headers,
                [name]: value,
            },
        });
    }
    
    timeout(ms: number): ImmutableRequestBuilder {
        return new ImmutableRequestBuilder({
            ...this.config,
            timeout: ms,
        });
    }
    
    build(): HttpRequest {
        return new HttpRequest(this.config);
    }
}
 
// Usage: branching configurations
const baseBuilder = new ImmutableRequestBuilder()
    .url('https://api.example.com/data')
    .header('Accept', 'application/json')
    .timeout(5000);
 
// Create variants - baseBuilder is unchanged!
const getRequest = baseBuilder
    .method('GET')
    .build();
 
const postRequest = baseBuilder
    .method('POST')
    .header('Content-Type', 'application/json')
    .build();
 
const adminRequest = baseBuilder
    .header('Authorization', 'Bearer admin-token')
    .method('DELETE')
    .build();
 
// baseBuilder still has original config
// Each variant is independent