The Builder Pattern

19 min read

The builder pattern assembles a complex value step by step, one named setter at a time, instead of forcing everything through a single positional constructor. If you have ever written a fluent new HttpRequestBuilder(url).method("POST").header(...).build() chain in TypeScript, you already know the shape. Rust uses the same idea, but the choice of who owns the builder — and the option to make required fields a compile error when missing — turns a convenience pattern into a genuine correctness tool.

Quick Overview

A builder is a helper type that accumulates configuration through chained method calls and produces the finished value with a final build(). It matters to a TypeScript/JavaScript developer for two reasons. First, Rust has no function overloading and no optional/named parameters, so a struct with many optional fields has no ergonomic constructor — the builder fills that gap. Second, Rust lets you push correctness into the type system: an owned builder, a fallible Result-returning builder, or a type-state builder can each make “you forgot a required field” fail at compile time rather than at run time.

Note: This file focuses purely on the builder pattern. The compile-time-state technique used here is covered in depth in type-state.md; for wrapping a single field in a meaningful type see newtype.md.

TypeScript/JavaScript Example

A classic fluent builder in TypeScript. Each setter mutates this and returns this, so calls chain. The constructor takes the one truly required value (the URL); everything else has a default or is optional.

1
// TypeScript - a fluent, mutate-this-and-return-this builder
2
class HttpRequestBuilder {
3
  private method = "GET";
4
  private headers: [string, string][] = [];
5
  private body: string | undefined;
6
  private timeoutMs = 30_000;
7

8
  constructor(private url: string) {}
9

10
  setMethod(method: string): this {
11
    this.method = method;
12
    return this;
13
  }
14
  header(name: string, value: string): this {
15
    this.headers.push([name, value]);
16
    return this;
17
  }
18
  setBody(body: string): this {
19
    this.body = body;
20
    return this;
21
  }
22
  timeout(ms: number): this {
23
    this.timeoutMs = ms;
24
    return this;
25
  }
26

27
  build() {
28
    return {
29
      method: this.method,
30
      url: this.url,
31
      headers: this.headers,
32
      body: this.body,
33
      timeoutMs: this.timeoutMs,
34
    };
35
  }
36
}
37

38
const req = new HttpRequestBuilder("https://api.example.com/users")
39
  .setMethod("POST")
40
  .header("Content-Type", "application/json")
41
  .header("Authorization", "Bearer token123")
42
  .setBody(JSON.stringify({ name: "Bob" }))
43
  .timeout(5_000)
44
  .build();
45

46
console.log(req);

Running this under Node v22 prints the assembled object:

1
{
2
  method: 'POST',
3
  url: 'https://api.example.com/users',
4
  headers: [
5
    [ 'Content-Type', 'application/json' ],
6
    [ 'Authorization', 'Bearer token123' ]
7
  ],
8
  body: '{"name":"Bob"}',
9
  timeoutMs: 5000
10
}

Notice what TypeScript cannot do here: nothing stops you from calling .build() immediately after new HttpRequestBuilder(url) and skipping a step you meant to set. Required-ness lives in your head, not in the type. Rust offers ways to fix exactly that.

Rust Equivalent

There are two idiomatic shapes for a Rust builder. The most common is the owned (move) builder: each setter takes self by value, mutates it, and returns it. Because the value is moved through the chain, the compiler guarantees you never accidentally reuse a half-finished builder.

1
// Rust - an owned (move) builder: each setter consumes `self` and returns it
2
#[derive(Debug)]
3
struct HttpRequest {
4
    method: String,
5
    url: String,
6
    headers: Vec<(String, String)>,
7
    body: Option<String>,
8
    timeout_ms: u64,
9
}
10

11
struct HttpRequestBuilder {
12
    method: String,
13
    url: String,
14
    headers: Vec<(String, String)>,
15
    body: Option<String>,
16
    timeout_ms: u64,
17
}
18

19
impl HttpRequestBuilder {
20
    // The one required value goes in `new`; everything else gets a default.
21
    fn new(url: impl Into<String>) -> Self {
22
        HttpRequestBuilder {
23
            method: "GET".to_string(),
24
            url: url.into(),
25
            headers: Vec::new(),
26
            body: None,
27
            timeout_ms: 30_000,
28
        }
29
    }
30

31
    fn method(mut self, method: impl Into<String>) -> Self {
32
        self.method = method.into();
33
        self
34
    }
35

36
    fn header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
37
        self.headers.push((name.into(), value.into()));
38
        self
39
    }
40

41
    fn body(mut self, body: impl Into<String>) -> Self {
42
        self.body = Some(body.into());
43
        self
44
    }
45

46
    fn timeout_ms(mut self, ms: u64) -> Self {
47
        self.timeout_ms = ms;
48
        self
49
    }
50

51
    // `build` consumes the builder one last time and yields the finished value.
52
    fn build(self) -> HttpRequest {
53
        HttpRequest {
54
            method: self.method,
55
            url: self.url,
56
            headers: self.headers,
57
            body: self.body,
58
            timeout_ms: self.timeout_ms,
59
        }
60
    }
61
}
62

63
fn main() {
64
    let req = HttpRequestBuilder::new("https://api.example.com/users")
65
        .method("POST")
66
        .header("Content-Type", "application/json")
67
        .header("Authorization", "Bearer token123")
68
        .body(r#"{"name":"Bob"}"#)
69
        .timeout_ms(5_000)
70
        .build();
71

72
    println!("{req:#?}");
73
}

Running it prints the finished HttpRequest:

1
HttpRequest {
2
    method: "POST",
3
    url: "https://api.example.com/users",
4
    headers: [
5
        (
6
            "Content-Type",
7
            "application/json",
8
        ),
9
        (
10
            "Authorization",
11
            "Bearer token123",
12
        ),
13
    ],
14
    body: Some(
15
        "{\"name\":\"Bob\"}",
16
    ),
17
    timeout_ms: 5000,
18
}

Tip: Accepting impl Into<String> in setters is the idiomatic way to let callers pass either a &str literal or an owned String without ceremony. It is the closest Rust gets to TypeScript’s “just pass a string.”

Detailed Explanation

Why a builder at all in Rust?

In TypeScript a builder is mostly about fluency and readability — you could just pass an options object. Rust reaches for builders for a more structural reason: there is no function overloading, no default parameter values, and no named arguments. A struct with five fields, three of them optional, has exactly one way to be constructed with a literal — and that literal requires every field, in order, with no names at call sites that read well. A builder restores named, optional, order-independent configuration.

The owned-builder mechanics, line by line

fn method(mut self, ...) -> Self takes self by value (self, not &self or &mut self). The mut is on the binding, letting the body reassign fields; it is not part of the public signature. The method returns Self, so the chain continues on the value that was just moved out and back.
Because each call moves the builder, the previous binding is consumed. You physically cannot touch a stale copy — there is only ever one live builder threading through the chain. This is ownership (Section 05) doing correctness work for free.
build(self) is the terminal move. After it runs, the builder no longer exists; it has been transformed into the HttpRequest.

The `&mut self` builder variant

The other common shape borrows the builder mutably instead of moving it. Each setter takes &mut self and returns &mut Self:

1
// Rust - a `&mut self` builder; the builder lives in a local you keep
2
#[derive(Debug, Default)]
3
struct ServerConfig {
4
    host: String,
5
    port: u16,
6
    workers: usize,
7
    tls: bool,
8
}
9

10
#[derive(Default)]
11
struct ServerConfigBuilder {
12
    host: Option<String>,
13
    port: Option<u16>,
14
    workers: Option<usize>,
15
    tls: bool,
16
}
17

18
impl ServerConfigBuilder {
19
    fn new() -> Self {
20
        Self::default()
21
    }
22

23
    fn host(&mut self, host: impl Into<String>) -> &mut Self {
24
        self.host = Some(host.into());
25
        self
26
    }
27

28
    fn port(&mut self, port: u16) -> &mut Self {
29
        self.port = Some(port);
30
        self
31
    }
32

33
    fn tls(&mut self, enabled: bool) -> &mut Self {
34
        self.tls = enabled;
35
        self
36
    }
37

38
    // `build` borrows, so the builder can be reused or inspected afterward.
39
    fn build(&mut self) -> ServerConfig {
40
        ServerConfig {
41
            host: self.host.clone().unwrap_or_else(|| "127.0.0.1".to_string()),
42
            port: self.port.unwrap_or(8080),
43
            workers: self.workers.unwrap_or(4),
44
            tls: self.tls,
45
        }
46
    }
47
}
48

49
fn main() {
50
    let mut builder = ServerConfigBuilder::new();
51
    builder.host("0.0.0.0").port(443).tls(true);
52
    let config = builder.build();
53
    println!("{config:?}");
54
}

Output:

1
ServerConfig { host: "0.0.0.0", port: 443, workers: 4, tls: true }

The difference is who keeps the builder. With &mut self the builder lives in a let mut binding you hold; the chain mutates it in place and build() reads from it (note the .clone() — since build only borrows, it cannot move the String out). This shape shines when the same builder is configured across several statements, or in if/loop blocks where moving on every branch would be awkward.

Warning: A &mut self builder still works as a one-shot temporary as long as the chain ends in an owned-returning build() — the temporary builder lives to the end of the statement. What you cannot do is let the intermediate &mut Self borrow escape that temporary: bind it to a let that outlives the statement, or return it. That fails with E0716/E0515 (“temporary value dropped while borrowed” / “cannot return value referencing temporary value”). Owned builders sidestep this entirely because they yield an owned value at every step. See Common Pitfalls below.

Optional fields are just defaults

In both shapes, “optional” simply means the field has a sensible default the builder seeds (in new or via #[derive(Default)]), and the setter overrides it. Fields the finished type models as genuinely absent use Option<T> (like body: Option<String> above), so None is a first-class “not set” rather than a magic sentinel value.

Required fields: runtime vs compile time

The owned and &mut self builders above make every field optional once you have a builder — new only demands the URL. If you have fields that must be supplied but cannot be defaulted, you have two real choices, covered in the next two sections: a fallible build() that returns Result (checked at run time), or a type-state builder that makes build() unavailable until the requirements are met (checked at compile time).

Key Differences

Aspect	TypeScript builder	Rust builder
Receiver	Always mutates `this`, returns `this`	Choose owned `self` or `&mut self`
Stale-state reuse	Possible; not prevented	Owned builder moves, so reuse is a compile error
Optional params	Optional/default params or options object	No language defaults; builder seeds them
Missing required field	Runtime bug at best	Can be a compile error (type-state) or a `Result`
Overloading	Allowed	Not allowed; builder works around it
Generated boilerplate	Manual or libraries	Manual, or `bon` / `derive_builder` macros

The headline difference is the move builder. In TypeScript a builder is a style. In Rust the owned builder additionally encodes a guarantee — once a step has been taken, the pre-step builder is gone — that the borrow checker enforces with zero runtime cost.

Common Pitfalls

Pitfall 1: reusing an owned builder after it was moved

A TypeScript habit is to keep a “base” builder and branch off it. With an owned builder, the first chain consumes the base:

1
// does not compile (error[E0382]: use of moved value: `base`)
2
struct Widget { width: u32, height: u32 }
3
struct WidgetBuilder { width: u32, height: u32 }
4
impl WidgetBuilder {
5
    fn new() -> Self { WidgetBuilder { width: 0, height: 0 } }
6
    fn width(mut self, w: u32) -> Self { self.width = w; self }
7
    fn height(mut self, h: u32) -> Self { self.height = h; self }
8
    fn build(self) -> Widget { Widget { width: self.width, height: self.height } }
9
}
10
fn main() {
11
    let base = WidgetBuilder::new().width(100);
12
    let a = base.height(50).build();
13
    let b = base.height(80).build(); // base was already moved by the first chain
14
    println!("{} {}", a.width, b.width);
15
}

The real compiler error:

1
error[E0382]: use of moved value: `base`
2
  --> src/main.rs:12:13
3
   |
4
10 |     let base = WidgetBuilder::new().width(100);
5
   |         ---- move occurs because `base` has type `WidgetBuilder`, which does not implement the `Copy` trait
6
11 |     let a = base.height(50).build();
7
   |                  ---------- `base` moved due to this method call
8
12 |     let b = base.height(80).build(); // base was already moved by the first chain
9
   |             ^^^^ value used here after move
10
   |
11
note: `WidgetBuilder::height` takes ownership of the receiver `self`, which moves `base`

To branch off a shared base with an owned builder, derive Clone on the builder and clone before each branch (base.clone().height(50)), or use a &mut self builder instead.

Pitfall 2: the `&mut self` builder’s borrow outlives what you expect

If you bind the &mut Self a chain returns and then keep using the original builder, you get an aliasing conflict — the chain’s borrow is still alive:

1
// does not compile (error[E0499]: cannot borrow `b` as mutable more than once at a time)
2
#[derive(Default)]
3
struct ConfigBuilder { port: u16, host: String }
4
impl ConfigBuilder {
5
    fn port(&mut self, p: u16) -> &mut Self { self.port = p; self }
6
    fn host(&mut self, h: &str) -> &mut Self { self.host = h.to_string(); self }
7
}
8
fn main() {
9
    let mut b = ConfigBuilder::default();
10
    let chained = b.port(8080).host("localhost"); // first &mut borrow, kept in `chained`
11
    b.port(9090);                                  // second &mut borrow while the first is live
12
    println!("{}", chained.port);
13
}

The real compiler error:

1
error[E0499]: cannot borrow `b` as mutable more than once at a time
2
  --> src/main.rs:10:5
3
   |
4
 9 |     let chained = b.port(8080).host("localhost"); // first &mut borrow, kept in `chained`
5
   |                   - first mutable borrow occurs here
6
10 |     b.port(9090);                                  // second &mut borrow while the first is live
7
   |     ^ second mutable borrow occurs here
8
11 |     println!("{}", chained.port);
9
   |                    ------------ first borrow later used here

Do not store the intermediate &mut Self. Either chain through to a value (let cfg = b.port(8080).host("localhost").build();) or finish the chain on its own statement and then read b directly. This is exactly why owned builders compose more freely as one-shot expressions.

Pitfall 3: forgetting to return `self` from a setter

Coming from TypeScript, where return this; is easy to drop, the equivalent slip in Rust is writing a setter body that ends in ; after the field assignment without the final self. That makes the method return () instead of Self, and the next .method(...) in the chain fails to resolve because () has no such method. The fix is to ensure the last expression of the setter is self (no trailing semicolon on it).

Best Practices

Default to the owned (move) builder. It is the most common form, composes as a single expression, and gives you free protection against reusing a half-built value. Reach for &mut self only when the builder genuinely lives across multiple statements or branches.
Put truly required, non-defaultable values in new / the constructor function. A builder’s job is the optional surface. If exactly one value is mandatory (the URL above), require it up front and you avoid needing fallible builds at all.
Do not hand-roll a builder when the struct just needs defaults. Often #[derive(Default)] plus struct-update syntax is enough and far less code:

1
// Rust - sometimes Default + struct-update beats a whole builder
2
#[derive(Debug)]
3
struct Settings {
4
    verbose: bool,
5
    retries: u32,
6
    color: bool,
7
}
8

9
impl Default for Settings {
10
    fn default() -> Self {
11
        Settings { verbose: false, retries: 3, color: true }
12
    }
13
}
14

15
fn main() {
16
    // Override only what differs; `..Default::default()` fills the rest.
17
    let custom = Settings { verbose: true, ..Settings::default() };
18
    println!("{custom:?}");
19
}

Output:

1
Settings { verbose: true, retries: 3, color: true }

Reach for a derive macro before writing a large builder by hand. The bon crate (current version 3.9.1) generates a builder that even checks required fields at compile time; derive_builder (0.20.2) is the long-standing alternative that produces a Result-returning build. Hand-write a builder only when you need behavior the macros do not give you — most often the type-state shape.
Name terminal and setter methods clearly. build() (or finish()/spawn() when domain-appropriate) for the consumer; plain field names for setters. Avoid set_/with_ prefixes unless they read better in your domain — Rust API guidelines prefer the bare field name.

Real-World Example

In production you rarely hand-roll the boilerplate. The bon crate gives you a derive macro that produces a builder and makes missing required fields a compile error — no Result, no unwrap, no manual Option plumbing. Add it with cargo add bon (resolves to 3.9.1 on the current stable toolchain, Rust 1.96.0 / 2024 edition):

1
[dependencies]
2
bon = "3"

1
// Rust - a derive-generated builder with required + optional + defaulted fields
2
use bon::Builder;
3

4
#[derive(Debug, Builder)]
5
struct Notification {
6
    // Required: a plain field with no default must be provided.
7
    // `#[builder(into)]` lets the setter accept anything that converts via Into,
8
    // so a `&str` literal works for a `String` field.
9
    #[builder(into)]
10
    recipient: String,
11
    #[builder(into)]
12
    subject: String,
13
    // Optional: an `Option<T>` field may be omitted; it defaults to `None`.
14
    #[builder(into)]
15
    cc: Option<String>,
16
    // Optional with an explicit default value.
17
    #[builder(default = 3)]
18
    retries: u32,
19
    // Optional, defaulting to the type's `Default` (`false`).
20
    #[builder(default)]
21
    urgent: bool,
22
}
23

24
fn main() {
25
    let n = Notification::builder()
26
        .recipient("ops@example.com")
27
        .subject("Deploy finished")
28
        .urgent(true)
29
        .build();
30

31
    println!("{n:#?}");
32
}

Output:

1
Notification {
2
    recipient: "ops@example.com",
3
    subject: "Deploy finished",
4
    cc: None,
5
    retries: 3,
6
    urgent: true,
7
}

The payoff is that forgetting a required field does not compile. Dropping the .subject(...) call yields a clear, readable diagnostic from bon (excerpt — the real output also carries per-note: --> src/main.rs locations and a trailing “this error originates in the derive macro” note):

1
error[E0277]: the member `Unset<subject>` was not set, but this method requires it to be set
2
 --> src/main.rs:9:66
3
  |
4
9 |     let n = Notification::builder().recipient("ops@example.com").build();
5
  |                                                                  ^^^^^ the member `Unset<subject>` was not set, but this method requires it to be set
6
  |
7
  = help: the trait `IsSet` is not implemented for `Unset<subject>`
8
note: required for `SetRecipient` to implement `IsComplete`
9
note: required by a bound in `NotificationBuilder::<S>::build`

Under the hood bon is generating the type-state machinery described in the next section. You get the strongest guarantee with the least code.

Exercises

Exercise 1: a move builder for a `Pizza`

Difficulty: Beginner

Objective: Practice the owned-builder shape with optional fields and a defaulted setter.

Instructions: Define a Pizza { size: String, cheese: bool, toppings: Vec<String> } and a PizzaBuilder. The size is required (take it in new); cheese defaults to true; toppings starts empty. Provide a cheese(bool) setter and a topping(impl Into<String>) setter that appends (so it can be called several times), plus build(). Construct a large pizza with no cheese and one "mushroom" topping and print it with {:?}.

Solution

1
#[derive(Debug)]
2
struct Pizza {
3
    size: String,
4
    cheese: bool,
5
    toppings: Vec<String>,
6
}
7

8
struct PizzaBuilder {
9
    size: String,
10
    cheese: bool,
11
    toppings: Vec<String>,
12
}
13

14
impl PizzaBuilder {
15
    fn new(size: impl Into<String>) -> Self {
16
        PizzaBuilder {
17
            size: size.into(),
18
            cheese: true,
19
            toppings: Vec::new(),
20
        }
21
    }
22

23
    fn cheese(mut self, yes: bool) -> Self {
24
        self.cheese = yes;
25
        self
26
    }
27

28
    fn topping(mut self, t: impl Into<String>) -> Self {
29
        self.toppings.push(t.into());
30
        self
31
    }
32

33
    fn build(self) -> Pizza {
34
        Pizza {
35
            size: self.size,
36
            cheese: self.cheese,
37
            toppings: self.toppings,
38
        }
39
    }
40
}
41

42
fn main() {
43
    let pizza = PizzaBuilder::new("large")
44
        .cheese(false)
45
        .topping("mushroom")
46
        .build();
47
    println!("{pizza:?}");
48
}

Output:

1
Pizza { size: "large", cheese: false, toppings: ["mushroom"] }

Exercise 2: a fallible `Result` builder with required fields

Difficulty: Intermediate

Objective: Enforce required fields at run time by returning a Result from build().

Instructions: Build an ApiClient { base_url: String, api_key: String, timeout_ms: u64 }. Store the in-progress fields as Options in the builder. base_url and api_key are required; timeout_ms defaults to 30_000. build() should return Result<ApiClient, String>, returning an Err naming the first missing required field. Show one successful build and one that omits base_url, printing both results.

Solution

1
#[derive(Debug)]
2
struct ApiClient {
3
    base_url: String,
4
    api_key: String,
5
    timeout_ms: u64,
6
}
7

8
#[derive(Default)]
9
struct ApiClientBuilder {
10
    base_url: Option<String>,
11
    api_key: Option<String>,
12
    timeout_ms: Option<u64>,
13
}
14

15
impl ApiClientBuilder {
16
    fn base_url(mut self, v: impl Into<String>) -> Self {
17
        self.base_url = Some(v.into());
18
        self
19
    }
20
    fn api_key(mut self, v: impl Into<String>) -> Self {
21
        self.api_key = Some(v.into());
22
        self
23
    }
24
    fn timeout_ms(mut self, v: u64) -> Self {
25
        self.timeout_ms = Some(v);
26
        self
27
    }
28

29
    fn build(self) -> Result<ApiClient, String> {
30
        Ok(ApiClient {
31
            base_url: self.base_url.ok_or("base_url is required")?,
32
            api_key: self.api_key.ok_or("api_key is required")?,
33
            timeout_ms: self.timeout_ms.unwrap_or(30_000),
34
        })
35
    }
36
}
37

38
fn main() {
39
    let client = ApiClientBuilder::default()
40
        .base_url("https://api.example.com")
41
        .api_key("secret")
42
        .build();
43
    println!("{client:?}");
44

45
    let bad = ApiClientBuilder::default().api_key("secret").build();
46
    println!("{bad:?}");
47
}

Output:

1
Ok(ApiClient { base_url: "https://api.example.com", api_key: "secret", timeout_ms: 30000 })
2
Err("base_url is required")

The ? operator turns each missing Option into an early Err. The error type here is a String for brevity; a real library would use a dedicated error enum — see error-propagation.md.

Exercise 3: a compile-checked (type-state) `QueryBuilder`

Difficulty: Advanced

Objective: Make “you forgot the required from(table)” a compile error rather than a runtime check.

Instructions: Build a Query { table: String, columns: Vec<String>, limit: Option<u32> }. Use a QueryBuilder<State> with zero-sized marker types NoTable and HasTable. QueryBuilder::new() starts in NoTable; calling .from(table) returns a QueryBuilder<HasTable>. The optional setters .select(col) (appends) and .limit(n) should work in any state. Define build() only for QueryBuilder<HasTable>. Build a query selecting "id" and "email" from "users" with a limit of 10, and print it. (For the deeper theory, see type-state.md.)

Solution

1
use std::marker::PhantomData;
2

3
struct NoTable;
4
struct HasTable;
5

6
#[derive(Debug)]
7
struct Query {
8
    table: String,
9
    columns: Vec<String>,
10
    limit: Option<u32>,
11
}
12

13
struct QueryBuilder<State> {
14
    table: Option<String>,
15
    columns: Vec<String>,
16
    limit: Option<u32>,
17
    _state: PhantomData<State>,
18
}
19

20
impl QueryBuilder<NoTable> {
21
    fn new() -> Self {
22
        QueryBuilder {
23
            table: None,
24
            columns: Vec::new(),
25
            limit: None,
26
            _state: PhantomData,
27
        }
28
    }
29

30
    // Setting the table is the only way into the `HasTable` state.
31
    fn from(self, table: impl Into<String>) -> QueryBuilder<HasTable> {
32
        QueryBuilder {
33
            table: Some(table.into()),
34
            columns: self.columns,
35
            limit: self.limit,
36
            _state: PhantomData,
37
        }
38
    }
39
}
40

41
// Optional setters are available in every state and keep the state unchanged.
42
impl<State> QueryBuilder<State> {
43
    fn select(mut self, col: impl Into<String>) -> Self {
44
        self.columns.push(col.into());
45
        self
46
    }
47
    fn limit(mut self, n: u32) -> Self {
48
        self.limit = Some(n);
49
        self
50
    }
51
}
52

53
// `build` exists ONLY once we are in `HasTable`.
54
impl QueryBuilder<HasTable> {
55
    fn build(self) -> Query {
56
        Query {
57
            table: self.table.unwrap(), // safe: `HasTable` guarantees it was set
58
            columns: self.columns,
59
            limit: self.limit,
60
        }
61
    }
62
}
63

64
fn main() {
65
    let q = QueryBuilder::new()
66
        .from("users")
67
        .select("id")
68
        .select("email")
69
        .limit(10)
70
        .build();
71
    println!("{q:?}");
72
}

Output:

1
Query { table: "users", columns: ["id", "email"], limit: Some(10) }

Try deleting the .from("users") line: the value stays QueryBuilder<NoTable>, build is not in scope for that type, and compilation fails with error[E0599]: no method named buildfound for structQueryBuilder“. The mistake is now impossible to ship.

The Builder Pattern

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Why a builder at all in Rust?

The owned-builder mechanics, line by line

The &mut self builder variant

Optional fields are just defaults

Required fields: runtime vs compile time

Key Differences

Common Pitfalls

Pitfall 1: reusing an owned builder after it was moved

Pitfall 2: the &mut self builder’s borrow outlives what you expect

Pitfall 3: forgetting to return self from a setter

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: a move builder for a Pizza

Exercise 2: a fallible Result builder with required fields

Exercise 3: a compile-checked (type-state) QueryBuilder

The `&mut self` builder variant

Pitfall 2: the `&mut self` builder’s borrow outlives what you expect

Pitfall 3: forgetting to return `self` from a setter

Exercise 1: a move builder for a `Pizza`

Exercise 2: a fallible `Result` builder with required fields

Exercise 3: a compile-checked (type-state) `QueryBuilder`