TypeSafe Builder

The Ultimate Builder Pattern Implementation Powered by Rust's Type System

Eliminate bugs at the type level and revolutionize your development experience

Why TypeSafe Builder?

Traditional builder patterns can't detect missing required fields until runtime. TypeSafe Builder leverages Rust's powerful type system to verify all constraints at compile time.

// ❌ Traditional builder - potential runtime errors
let user = UserBuilder::new()
    .name("Alice")
    .build()?; // Compiles even with missing required fields

// ✅ TypeSafe Builder - compile-time safety guarantee
let user = UserBuilder::new()
    .with_name("Alice".to_string())
    .with_email("alice@example.com".to_string()) // Compile error if email is required
    .build(); // Always guaranteed to succeed

Key Features

Type-Level Constraint System

• Required Fields - Completely prevent missing required field configuration
• Optional Fields - Freely configurable fields
• Default Values - Fields with intelligent default values using Default::default() or custom expressions
• Conditional Requirements - Express dynamic dependencies at the type level
• Complex Logic - Support for AND/OR/NOT operators in complex conditional expressions
• Into Conversion - Ergonomic setters with automatic type conversion via Into<T>

Performance Characteristics

• Zero Runtime Cost - All validation completed at compile time

Safety Guarantees

• No Panic - Complete elimination of runtime panics

Quick Start

[dependencies]
typesafe_builder = "*.*.*" # Replace with the actual version

use typesafe_builder::*;

#[derive(Builder)]
struct User {
    #[builder(required)]
    name: String,
    #[builder(optional)]
    age: Option<u32>,
    #[builder(default = "String::from(\"user@example.com\")")]
    email: String,
    #[builder(default)]
    active: bool,
}

// Type-safe builder pattern
let user = UserBuilder::new()
    .with_name("Alice".to_string())
    .with_age(30)
    .build(); // email will be "user@example.com", active will be false

Advanced Features

1. Conditional Required Fields

use typesafe_builder::*;

#[derive(Builder)]
struct Account {
    #[builder(optional)]
    email: Option<String>,
    #[builder(required_if = "email")]  // Required when email is set
    email_verified: Option<bool>,
}

// ✅ Compiles successfully
let account1 = AccountBuilder::new().build();

// ✅ Compiles successfully
let account2 = AccountBuilder::new()
    .with_email("user@example.com".to_string())
    .with_email_verified(true)
    .build();

// ❌ Compile error: email_verified is not set
// let account3 = AccountBuilder::new()
//     .with_email("user@example.com".to_string())
//     .build();

2. Conditional Optional Fields

use typesafe_builder::*;

#[derive(Builder)]
struct Config {
    #[builder(optional)]
    debug_mode: Option<bool>,
    #[builder(optional_if = "debug_mode")]  // Required when debug_mode is not set
    log_level: Option<String>,
}

// ✅ When debug_mode is not set, log_level is required
let config1 = ConfigBuilder::new()
    .with_log_level("INFO".to_string())
    .build();

// ✅ When debug_mode is set, log_level is optional
let config2 = ConfigBuilder::new()
    .with_debug_mode(true)
    .build();

3. Complex Conditional Logic

use typesafe_builder::*;

#[derive(Builder)]
struct ApiClient {
    #[builder(optional)]
    use_auth: Option<bool>,
    #[builder(optional)]
    use_https: Option<bool>,
    #[builder(optional)]
    api_key: Option<String>,

    // Secret is required if using auth OR HTTPS
    #[builder(required_if = "use_auth || use_https")]
    secret: Option<String>,

    // Certificate is required only when using both auth AND HTTPS
    #[builder(required_if = "use_auth && use_https")]
    certificate: Option<String>,

    // Warning is required when using neither auth NOR HTTPS
    #[builder(required_if = "!use_auth && !use_https")]
    insecure_warning: Option<String>,

    // Complex condition: Token required when (auth OR HTTPS) AND (no API key)
    #[builder(required_if = "(use_auth || use_https) && !api_key")]
    fallback_token: Option<String>,
}

// ✅ All dependencies satisfied (auth + HTTPS)
let client1 = ApiClientBuilder::new()
    .with_use_auth(true)
    .with_use_https(true)
    .with_api_key("key123".to_string())
    .with_secret("secret456".to_string())
    .with_certificate("cert.pem".to_string())
    .build();

// ✅ Insecure configuration with warning
let client2 = ApiClientBuilder::new()
    .with_use_auth(false)
    .with_use_https(false)
    .with_insecure_warning("WARNING: Insecure connection!".to_string())
    .build();

// ✅ Using fallback token when API key is not set
let client3 = ApiClientBuilder::new()
    .with_use_auth(true)
    .with_secret("secret".to_string())
    .with_fallback_token("backup_token".to_string())
    .build();

4. Default Values

TypeSafe Builder supports two ways to specify default values:

Simple Default Values (using Default::default())

use typesafe_builder::*;

#[derive(Builder)]
struct Config {
    // Uses String::default() (empty string)
    #[builder(default)]
    name: String,

    // Uses i32::default() (0)
    #[builder(default)]
    port: i32,

    // Uses bool::default() (false)
    #[builder(default)]
    enabled: bool,

    // Uses Vec::default() (empty vector)
    #[builder(default)]
    items: Vec<String>,

    // Uses HashMap::default() (empty map)
    #[builder(default)]
    metadata: std::collections::HashMap<String, String>,

    // Works with custom types that implement Default
    #[builder(default)]
    custom_field: MyCustomType,

    #[builder(required)]
    service_name: String,
}

// ✅ Use default values
let config = ConfigBuilder::new()
    .with_service_name("my-service".to_string())
    .build();
// name: "", port: 0, enabled: false, items: [], metadata: {}, custom_field: MyCustomType::default()

Custom Default Expressions

use typesafe_builder::*;

#[derive(Builder)]
struct ServerConfig {
    #[builder(default = "String::from(\"localhost\")")]
    host: String,

    #[builder(default = "8080")]
    port: u16,

    #[builder(default = "vec![\"GET\".to_string(), \"POST\".to_string()]")]
    allowed_methods: Vec<String>,

    #[builder(default = "std::collections::HashMap::new()")]
    headers: std::collections::HashMap<String, String>,

    #[builder(required)]
    service_name: String,

    #[builder(optional)]
    ssl_cert: Option<String>,
}

// ✅ Use default values
let config1 = ServerConfigBuilder::new()
    .with_service_name("my-api".to_string())
    .build();
// host: "localhost", port: 8080, allowed_methods: ["GET", "POST"], headers: {}

// ✅ Override some defaults
let config2 = ServerConfigBuilder::new()
    .with_service_name("my-api".to_string())
    .with_host("0.0.0.0".to_string())
    .with_port(3000)
    .build();
// host: "0.0.0.0", port: 3000, allowed_methods: ["GET", "POST"], headers: {}

// ✅ Complex default expressions
#[derive(Builder)]
struct AppConfig {
    #[builder(default = "std::env::var(\"APP_NAME\").unwrap_or_else(|_| \"default-app\".to_string())")]
    app_name: String,

    #[builder(default = "chrono::Utc::now()")]
    created_at: chrono::DateTime<chrono::Utc>,

    #[builder(default = "uuid::Uuid::new_v4()")]
    instance_id: uuid::Uuid,
}

Mixed Default Types

use typesafe_builder::*;

#[derive(Builder)]
struct MixedConfig {
    // Simple default (uses Default::default())
    #[builder(default)]
    name: String,

    // Custom expression default
    #[builder(default = "42")]
    port: i32,

    // Simple default for collections
    #[builder(default)]
    tags: Vec<String>,

    // Custom expression for complex initialization
    #[builder(default = "std::collections::HashMap::from([(\"key\".to_string(), \"value\".to_string())])")]
    metadata: std::collections::HashMap<String, String>,
}

let config = MixedConfigBuilder::new().build();
// name: "", port: 42, tags: [], metadata: {"key": "value"}

Key features of default values:

• Simple defaults: Use #[builder(default)] for types implementing Default
• Custom expressions: Use #[builder(default = "expression")] for any valid Rust expression
• No type restrictions: Works with primitives, collections, function calls, etc.
• Environment variables: Access environment variables at build time (custom expressions)
• Function calls: Call any function or method as default value (custom expressions)
• Standalone attribute: Cannot be combined with required, optional, etc.
• Zero runtime cost: All defaults are computed at build time

5. Negation Operator Support

use typesafe_builder::*;

#[derive(Builder)]
struct Database {
    #[builder(optional)]
    use_ssl: Option<bool>,

    // Warning message required when NOT using SSL
    #[builder(required_if = "!use_ssl")]
    warning_message: Option<String>,
}

// ✅ Warning configuration for non-SSL usage
let db = DatabaseBuilder::new()
    .with_use_ssl(false)
    .with_warning_message("Insecure connection!".to_string())
    .build();

6. Into Conversion Support

The #[builder(into)] attribute allows setter methods to accept any type that implements Into<T> for the field type T, providing more ergonomic APIs:

use typesafe_builder::*;

#[derive(Builder)]
struct User {
    #[builder(required)]
    #[builder(into)]
    name: String,

    #[builder(optional)]
    #[builder(into)]
    email: Option<String>,
}

// ✅ Accept &str directly (converts to String via Into)
let user1 = UserBuilder::new()
    .with_name("Alice")  // &str -> String
    .with_email("alice@example.com")  // &str -> String
    .build();

// ✅ Still works with String directly
let user2 = UserBuilder::new()
    .with_name("Bob".to_string())
    .build();

Key benefits:

• Ergonomic APIs: Accept &str for String fields without manual conversion
• Type flexibility: Any Into<T> implementation works automatically
• Zero overhead: Conversion happens at the call site
• Backward compatible: Works alongside existing setter patterns

7. Custom Builder Name

use typesafe_builder::*;

#[derive(Builder)]
#[builder(name = "MyCustomBuilder")]  // Customize the builder name
struct User {
    #[builder(required)]
    name: String,
}

// Use the customized builder name
let user = MyCustomBuilder::new()
    .with_name("Alice".to_string())
    .build();

Error Handling

Compile-Time Error Examples

#[derive(Builder)]
struct User {
    #[builder(required)]
    name: String,
}

// ❌ Compile error
let user = UserBuilder::new().build();
//                           ^^^^^
// error: no method named `build` found for struct `UserBuilder<_TypesafeBuilderEmpty>`
//        method `build` is available on `UserBuilder<_TypesafeBuilderFilled>`

Constraint Violation Error Examples

#[derive(Builder)]
struct Config {
    #[builder(optional)]
    feature: Option<bool>,
    #[builder(required_if = "feature")]
    config: Option<String>,
}

// ❌ Compile error
let config = ConfigBuilder::new()
    .with_feature(true)
    .build();
//   ^^^^^
// error: no method named `build` found for struct `ConfigBuilder<_TypesafeBuilderFilled, _TypesafeBuilderEmpty>`
//        method `build` is available on `ConfigBuilder<_TypesafeBuilderFilled, _TypesafeBuilderFilled>`

Real-World Use Cases

Web API Configuration

#[derive(Builder)]
struct ApiConfig {
    #[builder(required)]
    base_url: String,

    #[builder(optional)]
    use_auth: Option<bool>,

    #[builder(required_if = "use_auth")]
    api_key: Option<String>,

    #[builder(required_if = "use_auth")]
    secret: Option<String>,

    #[builder(default = "30")]
    timeout_seconds: u64,

    #[builder(default = "String::from(\"application/json\")")]
    content_type: String,
}

Database Connection

#[derive(Builder)]
struct DatabaseConfig {
    #[builder(required)]
    host: String,

    #[builder(required)]
    database: String,

    #[builder(default = "5432")]
    port: u16,

    #[builder(default = "10")]
    max_connections: u32,

    #[builder(optional)]
    use_ssl: Option<bool>,

    #[builder(required_if = "use_ssl")]
    ssl_cert_path: Option<String>,

    #[builder(optional_if = "!use_ssl")]
    allow_insecure: Option<bool>,
}

Contributing

We welcome contributions to TypeSafe Builder!

Development Environment Setup

git clone https://github.com/tomoikey/typesafe_builder.git
cd typesafe_builder
cargo test

Running Tests

# Run all tests
cargo test

# UI tests (compile error verification)
cargo test --package typesafe_builder_derive --test ui

Contributors

Amazing developers who have contributed to this project:

Want to see your name here? Contribute now and join our amazing community!

License

MIT License - see the LICENSE file for details.

Give us a star!

If you find this project useful, please consider giving it a star!