# nicer_builder

This repository endeavors to develop a builder derive macro that is more intelligent and cognizant of the existing builder context.

# Observation

Consider having a Rust struct as follows:

```rust
struct User {
    name: &'static str,
    age: Option<u32>,
    address: Option<&'static str>,
}
```

Now, suppose you wish to implement a builder pattern for this struct; it could be crafted as follows:

```rust
impl User {
    pub fn builder() -> UserBuilder {
        UserBuilder::default()
    }
}

#[derive(Default)]
pub struct UserBuilder {
    name: Option<&'static str>,
    age: Option<u32>,
    address: Option<&'static str>,
}

impl UserBuilder {
    pub fn name(mut self, name: &'static str) -> Self {
        self.name = Some(name);
        self
    }

    pub fn age(mut self, age: u32) -> Self {
        self.age = Some(age);
        self
    }

    pub fn address(mut self, address: &'static str) -> Self {
        self.address = Some(address);
        self
    }

    pub fn build(self) -> Result<User, &'static str> {
        let name = self.name.ok_or("Name is required")?;

        Ok(User {
            name,
            age: self.age,
            address: self.address,
        })
    }
}
```

which can be later use like this:

```rust
let user = User::builder()
    .name("Alice")
    .age(30)
    .address("Wonderland")
    .build()
    .unwrap();

println!("User: {:?}", user);
```

Regardless of whether you favor this approach, it presents several challenges:

## The build method returns a `Result`

Although the builder technically knows its state, we are compelled to return the `User` instance, constructed by the builder, wrapped in a `Result`

## Builder lacks awareness of fields already set

This results in the following sequence of methods being entirely feasible:

```rust
let user = User::builder()
    .name("Alice")
    .age(30)
    .age(20)
    .address("Wonderland")
    .age(333)
    .build()
    .unwrap();
```

## Suboptimal IDE completion support

This issue stems from the previous one; when I enter:

```rust
let user = User::builder()
    .name("Alice")
    .
```

Upon receiving this `.` input, the language server protocol (`LSP`) proposes the complete list of builder methods - `name`, `age`, and `address`, even though `name` has just been set. Furthermore, the visibility of the `build` method is unrestricted - you can invoke it in the midst of the build process, potentially leading to a `panic` when attempting to`unwrap` the result.

## Manual implementation

Hence, introducing a new field to the `User` struct will necessitate corresponding adjustments on the `Builder` side.

# Solution?

This repository offers a solution to these issues by providing a proc_macro that automatically generates the Builder implementation for the struct, devoid of the aforementioned problems.

```rust
#[derive(nicer_builder::Builder)]
struct User {
    name: &'static str,
    age: Option<u32>,
    address: Option<&'static str>,
}

let alice = User::builder()
    .with_address("SF")
    .with_age(10)
    .with_name("alice")
    .build();
```

Notably, the build method no longer returns a `Result`; instead, it directly returns the actual `User` instance, and it is guaranteed not to fail at compile time.

# Downsides

The `proc_macro` provided by this crate essentially generates a comprehensive state machine. Each node of this machine contains a dedicated sub-builder implementation, defining its own set of methods. In simpler terms, the `proc_macro` would generate approximately `2^(number of fields)` new structs, which can become costly quicker than one might prefer.