# TypeStateBuilder
[](https://crates.io/crates/type-state-builder)
[](https://docs.rs/type-state-builder)
[](https://github.com/welf/type-state-builder/actions)
[](https://www.rust-lang.org)
[](https://opensource.org/licenses/MIT)
A Rust derive macro that generates compile-time safe builders using the type-state pattern. It prevents incomplete
object construction by making missing required fields a compile-time error rather than a runtime failure.
## Table of Contents
- [Introduction](#introduction)
- [Design Philosophy](#design-philosophy)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Core Concepts](#core-concepts)
- [Features](#features)
- [Understanding Error Messages](#understanding-error-messages)
- [Compatibility](#compatibility)
- [How It Works](#how-it-works)
- [License](#license)
- [Contributing](#contributing)
## Introduction
Traditional builder patterns in Rust typically validate required fields at runtime, returning `Result` or panicking when
fields are missing:
```rust,ignore
// Traditional builder - fails at runtime
let user = UserBuilder::new()
.name("Alice")
// Forgot to set email
.build(); // Returns Err or panics at runtime
```
TypeStateBuilder moves this validation to compile time:
```rust,ignore
// TypeStateBuilder - fails at compile time
let user = User::builder()
.name("Alice".to_string())
// Forgot to set email
.build(); // Compile error: method `build` not found
```
The compiler error message clearly indicates what is missing:
```text
error[E0599]: no method named `build` found for struct
`UserBuilder_HasName_MissingEmail` in the current scope
```
## Design Philosophy
TypeStateBuilder was designed with AI-assisted development in mind. Two principles guided its design:
### Compiler-Enforced Correctness
In AI-assisted development, code generation happens rapidly. LLMs can produce syntactically correct code that
nonetheless contains logical errors, such as forgetting to initialize required fields. By encoding field requirements in
the type system, TypeStateBuilder ensures that such errors are caught immediately by the compiler rather than
manifesting as runtime failures.
The type system becomes a safety net: if the code compiles, the builder is correctly configured.
### Actionable Error Messages
Many type-state builder implementations use generic type parameters to track field states:
```rust,ignore
// Other implementations might generate something like:
UserBuilder<Set, Unset, Set, Unset>
// ^ ^ ^ ^
// What do these mean?
```
When a required field is missing, the resulting error message requires decoding which type parameter corresponds to
which field.
TypeStateBuilder takes a different approach. It generates a separate struct for each possible state, with the struct
name explicitly describing which fields have been set and which are missing:
```text
UserBuilder_HasName_HasEmail // Both fields set - build() available
UserBuilder_HasName_MissingEmail // Name set, email missing
UserBuilder_MissingName_HasEmail // Email set, name missing
UserBuilder_MissingName_MissingEmail // Neither field set
```
When an AI assistant encounters an error like `UserBuilder_HasName_MissingEmail doesn't have method build`, it can
immediately understand that the `email` field needs to be set. No documentation lookup or type parameter decoding is
required.
### Trade-offs
This approach generates more structs than a type-parameter-based solution, which increases compile time slightly.
However, the improved error message clarity is worth this cost, particularly in AI-assisted workflows where rapid
iteration and clear feedback are essential.
Importantly, there is no runtime cost. Rust's zero-cost abstractions ensure that the generated code is as efficient as a
hand-written builder.
## Installation
Add TypeStateBuilder to your `Cargo.toml`:
```toml
[dependencies]
type-state-builder = "0.5.1"
```
### no_std Support
TypeStateBuilder is compatible with `no_std` environments. The generated code uses only `core` types
(`core::option::Option`, `core::marker::PhantomData`, etc.) and does not require the standard library.
### Minimum Supported Rust Version
TypeStateBuilder requires Rust 1.70.0 or later.
## Quick Start
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder, Debug)]
struct User {
#[builder(required)]
name: String,
#[builder(required)]
email: String,
age: Option<u32>,
}
fn main() {
// All required fields must be set before build() is available
let user = User::builder()
.name("Alice".to_string())
.email("alice@example.com".to_string())
.age(Some(30))
.build();
println!("{:?}", user);
// Optional fields can be omitted
let user2 = User::builder()
.name("Bob".to_string())
.email("bob@example.com".to_string())
.build();
println!("{:?}", user2);
}
```
## Core Concepts
### Required vs Optional Fields
Fields marked with `#[builder(required)]` must be set before the `build()` method becomes available. All other fields
are optional and will use their default values if not set.
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder)]
struct Config {
#[builder(required)]
api_key: String, // Must be set
timeout: Option<u32>, // Optional, defaults to None
retries: u32, // Optional, defaults to 0
}
```
### Builder Pattern Selection
TypeStateBuilder automatically selects the appropriate builder pattern based on your struct:
- **Type-state builder**: When the struct has required fields. The `build()` method is only available after all required
fields are set.
- **Regular builder**: When all fields are optional. The `build()` method is available immediately.
### State Transitions
Each setter method returns a new builder type that reflects the updated state. For a struct with required fields `name`
and `email`:
```rust,ignore
User::builder() // UserBuilder_MissingName_MissingEmail
.name("Alice".to_string()) // UserBuilder_HasName_MissingEmail
.email("alice@example.com".to_string()) // UserBuilder_HasName_HasEmail
.build() // User
```
Optional fields can be set at any point without affecting the type-state progression.
## Features
### Required Fields
Mark fields as required using the `required` attribute:
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder)]
struct DatabaseConfig {
#[builder(required)]
host: String,
#[builder(required)]
database: String,
port: u16, // Optional, defaults to 0
}
let config = DatabaseConfig::builder()
.host("localhost".to_string())
.database("myapp".to_string())
.build();
```
### Default Values
Provide custom default values for optional fields:
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder)]
struct ServerConfig {
#[builder(required)]
host: String,
#[builder(default = 8080)]
port: u16,
#[builder(default = 30)]
timeout_seconds: u32,
#[builder(default = String::from("production"))]
environment: String,
}
let config = ServerConfig::builder()
.host("localhost".to_string())
// port defaults to 8080
// timeout_seconds defaults to 30
// environment defaults to "production"
.build();
```
### Skip Setter
Some fields should only use their default value without exposing a setter:
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder)]
struct Document {
#[builder(required)]
title: String,
#[builder(default = generate_id(), skip_setter)]
id: String,
#[builder(default = now(), skip_setter)]
created_at: u64,
}
fn generate_id() -> String {
"doc-123".to_string()
}
fn now() -> u64 {
1234567890
}
let doc = Document::builder()
.title("My Document".to_string())
// id and created_at are set automatically, no setters available
.build();
```
### Custom Setter Names
Customize individual setter method names:
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder)]
struct Person {
#[builder(required, setter_name = "full_name")]
name: String,
#[builder(setter_name = "years_old")]
age: Option<u32>,
}
let person = Person::builder()
.full_name("Alice Smith".to_string())
.years_old(Some(30))
.build();
```
### Setter Prefixes
Add consistent prefixes to setter methods at the struct or field level:
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder)]
#[builder(setter_prefix = "with_")]
struct ApiClient {
#[builder(required)]
base_url: String,
#[builder(required, setter_prefix = "set_")] // Overrides struct-level prefix
api_key: String,
timeout: Option<u32>,
}
let client = ApiClient::builder()
.with_base_url("https://api.example.com".to_string())
.set_api_key("secret123".to_string()) // Uses field-level prefix
.with_timeout(Some(5000))
.build();
```
### Ergonomic Conversions with impl_into
The `impl_into` attribute generates setters that accept `impl Into<T>`, allowing more ergonomic API usage:
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder)]
#[builder(impl_into)] // Apply to all fields
struct Config {
#[builder(required)]
name: String,
#[builder(required)]
description: String,
#[builder(impl_into = false)] // Override: require exact type
id: Option<u64>,
}
let config = Config::builder()
.name("MyApp") // &str converts to String via Into
.description("An application") // &str converts to String via Into
.id(Some(42u64)) // Requires Option<u64> exactly
.build();
```
### Custom Conversions with converter
The `converter` attribute provides custom transformation logic for setters:
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder, Debug)]
struct User {
#[builder(required, converter = |email: &str| email.trim().to_lowercase())]
email: String,
#[builder(converter = |tags: &str| tags.split(',').map(|s| s.trim().to_string()).collect())]
interests: Vec<String>,
#[builder(converter = |value: &str| Some(value.to_string()))]
nickname: Option<String>,
}
let user = User::builder()
.email(" ALICE@EXAMPLE.COM ") // Normalized to "alice@example.com"
.interests("rust, programming, web") // Parsed to Vec<String>
.nickname("ally") // Wrapped in Some
.build();
assert_eq!(user.email, "alice@example.com");
assert_eq!(user.interests, vec!["rust", "programming", "web"]);
assert_eq!(user.nickname, Some("ally".to_string()));
```
The converter must be a closure expression with an explicitly typed parameter:
```rust,ignore
// Correct
#[builder(converter = |value: &str| value.to_uppercase())]
// Incorrect - function references are not supported
#[builder(converter = str::to_uppercase)]
```
### Custom Build Method Name
Customize the name of the final build method:
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder)]
#[builder(build_method = "create")]
struct Connection {
#[builder(required)]
host: String,
}
let conn = Connection::builder()
.host("localhost".to_string())
.create(); // Uses custom method name
```
### Generics and Lifetimes
TypeStateBuilder supports generic types, lifetime parameters, and complex bounds:
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder, Debug)]
struct Container<'a, T, U>
where
T: Clone + Send,
U: std::fmt::Debug,
{
#[builder(required)]
data: T,
#[builder(required)]
metadata: U,
reference: Option<&'a str>,
}
let text = "referenced text";
let container = Container::<String, i32>::builder()
.data("Hello".to_string())
.metadata(42)
.reference(Some(text))
.build();
```
### Const Builders
The `#[builder(const)]` attribute generates `const fn` builder methods, enabling compile-time constant construction.
This is useful for embedded systems, static configuration, and other scenarios where values must be known at compile
time.
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder, Debug, PartialEq)]
#[builder(const)]
struct Config {
#[builder(required)]
name: &'static str,
#[builder(required)]
version: u32,
#[builder(default = 8080)]
port: u16,
}
// Compile-time constant construction
const APP_CONFIG: Config = Config::builder()
.name("my-app")
.version(1)
.port(3000)
.build();
// Also works in static context
static DEFAULT_CONFIG: Config = Config::builder()
.name("default")
.version(0)
.build();
// And in const fn
const fn make_config(name: &'static str) -> Config {
Config::builder()
.name(name)
.version(1)
.build()
}
const CUSTOM: Config = make_config("custom");
```
**Requirements for const builders:**
- **Explicit defaults required**: Optional fields must use `#[builder(default = expr)]` because `Default::default()`
cannot be called in const context
- **No `impl_into`**: The `impl_into` attribute is incompatible with const builders because trait bounds are not
supported in const fn
- **Const-compatible types**: Field types must support const construction (e.g., `&'static str` instead of `String`,
arrays instead of `Vec`)
**Converters with const builders:**
Closure converters work with const builders. The macro automatically generates a `const fn` from the closure body:
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder, Debug, PartialEq)]
#[builder(const)]
struct Data {
#[builder(required, converter = |s: &'static str| s.len())]
name_length: usize,
#[builder(default = 0, converter = |n: i32| n * 2)]
doubled: i32,
}
const DATA: Data = Data::builder()
.name_length("hello") // Converted to 5
.doubled(21) // Converted to 42
.build();
```
### Builder Method Entry Point
The `#[builder(builder_method)]` attribute makes a required field's setter the entry point to the builder, replacing the
`builder()` method. This provides a more ergonomic API when one field is the natural starting point.
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder, Debug, PartialEq)]
struct User {
#[builder(required, builder_method)]
id: u64,
#[builder(required, impl_into)]
name: String,
}
// Instead of User::builder().id(1).name("Alice").build()
let user = User::id(1).name("Alice").build();
assert_eq!(user.id, 1);
assert_eq!(user.name, "Alice".to_string());
```
**Requirements:**
- Only one field per struct can have `builder_method`
- The field must be required (not optional)
- Cannot be combined with `skip_setter`
**With const builders:**
```rust
use type_state_builder::TypeStateBuilder;
#[derive(TypeStateBuilder, Debug, PartialEq)]
#[builder(const)]
struct Config {
#[builder(required, builder_method)]
name: &'static str,
#[builder(default = 0)]
version: u32,
}
const APP: Config = Config::name("myapp").version(1).build();
```
## Understanding Error Messages
When a required field is missing, the compiler error includes the builder's type name, which explicitly states the
current state:
```text
error[E0599]: no method named `build` found for struct
`ConfigBuilder_MissingApi_key_MissingEndpoint` in the current scope
```
The naming pattern is:
```text
{StructName}Builder_{FieldState1}_{FieldState2}_...
```
Where each field state is either:
- `Has{FieldName}` - the field has been set
- `Missing{FieldName}` - the field has not been set
For example, with a struct having fields `api_key` and `endpoint`:
| Neither set | `ConfigBuilder_MissingApi_key_MissingEndpoint` |
| Only api_key set | `ConfigBuilder_HasApi_key_MissingEndpoint` |
| Only endpoint set | `ConfigBuilder_MissingApi_key_HasEndpoint` |
| Both set | `ConfigBuilder_HasApi_key_HasEndpoint` |
The `build()` method is only available on the final state where all required fields are set.
## Compatibility
### no_std Support
TypeStateBuilder generates code that is compatible with `no_std` environments. The generated code uses:
- `core::option::Option` instead of `std::option::Option`
- `core::marker::PhantomData` instead of `std::marker::PhantomData`
- `core::fmt::Debug` instead of `std::fmt::Debug`
- `core::default::Default` instead of `std::default::Default`
No feature flags are required; `no_std` compatibility is the default.
### Minimum Supported Rust Version
TypeStateBuilder requires **Rust 1.70.0** or later. This requirement is driven by:
- Stable proc-macro features used in code generation
- Advanced generic parameter handling
The MSRV is tested in CI and will not be increased without a minor version bump.
## How It Works
TypeStateBuilder implements the type-state pattern using Rust's type system to encode state at compile time.
### Generated Types
For a struct with required fields, the macro generates:
1. Multiple builder structs, one for each possible combination of set/unset required fields
2. Setter methods that transition between states
3. A `build()` method only on the final state
### State Encoding
Each required field contributes to the builder's type name. With `n` required fields, there are `2^n` possible states.
The macro generates a struct for each state, though in practice many states are not reachable through normal usage.
### Zero Runtime Cost
The state tracking is entirely compile-time:
- No runtime state variable
- No runtime validation
- No `Option` wrappers for required fields internally
- The final `build()` call simply moves values into the target struct
The generated code is equivalent to what you would write by hand, with the type system providing the safety guarantees.
### Example Generation
For this input:
```rust,ignore
#[derive(TypeStateBuilder)]
struct User {
#[builder(required)]
name: String,
age: Option<u32>,
}
```
The macro generates (simplified):
```rust,ignore
struct UserBuilder_MissingName {
age: Option<u32>,
}
struct UserBuilder_HasName {
name: String,
age: Option<u32>,
}
impl UserBuilder_MissingName {
fn name(self, value: String) -> UserBuilder_HasName {
UserBuilder_HasName {
name: value,
age: self.age,
}
}
fn age(self, value: Option<u32>) -> Self {
Self { age: value, ..self }
}
}
impl UserBuilder_HasName {
fn age(self, value: Option<u32>) -> Self {
Self { age: value, ..self }
}
fn build(self) -> User {
User {
name: self.name,
age: self.age,
}
}
}
```
## License
Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or [MIT license](LICENSE-MIT) at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as
defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
## Contributing
Contributions are welcome. Please open an issue to discuss significant changes before submitting a pull request.
For bug reports and feature requests, use the [issue tracker](https://github.com/welf/type-state-builder/issues).