TypeStateBuilder

https://github.com/welf/type-state-builder
Admin
TypeStateBuilder is a Rust derive macro that generates compile-time safe builders using the...
Tokens:9,080
Snippets:82
Trust Score:5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install TypeStateBuilder

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Add the dependency to your Cargo.toml file.

```toml
[dependencies]
type-state-builder = "0.5.1"
```

--------------------------------

### Basic User Builder Example

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Demonstrates setting required and optional fields for a User struct using the generated builder. All required fields must be set before build() is available.

```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);
}
```

--------------------------------

### DatabaseConfig Builder with Required Fields

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Example of defining a DatabaseConfig struct with two required fields, 'host' and 'database', using the `#[builder(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();
```

--------------------------------

### View Compile-Time Error Message

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Example of the error message generated when a required field is missing.

```text
error[E0599]: no method named `build` found for struct
              `UserBuilder_HasName_MissingEmail` in the current scope
```

--------------------------------

### View Generated Struct Names

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Example of the explicit struct names generated by TypeStateBuilder to indicate field state.

```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
```

--------------------------------

### Use Builder Method as Entry Point

Source: https://context7.com/welf/type-state-builder/llms.txt

Employ `#[builder(builder_method)]` on a required field to make its setter the initial method for the builder. This enhances API ergonomics by replacing the standard `builder()` call.

```rust
use type_state_builder::TypeStateBuilder;

#[derive(TypeStateBuilder, Debug, PartialEq)]
struct User {
    #[builder(required, builder_method)]
    id: u64,

    #[builder(required, impl_into)]
    name: String,
}

fn main() {
    // 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());
}
```

--------------------------------

### Compare Traditional and TypeStateBuilder Patterns

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Demonstrates the difference between runtime validation in traditional builders and compile-time validation with TypeStateBuilder.

```rust
// Traditional builder - fails at runtime
let user = UserBuilder::new()
    .name("Alice")
    // Forgot to set email
    .build(); // Returns Err or panics at runtime
```

```rust
// TypeStateBuilder - fails at compile time
let user = User::builder()
    .name("Alice".to_string())
    // Forgot to set email
    .build(); // Compile error: method `build` not found
```

--------------------------------

### Combine Custom Entry Point with Const Builders

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Custom entry points can be used in conjunction with const builders for more ergonomic API design.

```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();
```

--------------------------------

### ServerConfig Builder with Default Values

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Demonstrates providing custom default values for optional fields in ServerConfig using `#[builder(default = ...)]`. Fields without setters will use their default values.

```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();
```

--------------------------------

### State Transitions in Builder Pattern

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Shows the type-state transitions for a builder with required fields. Each setter returns a new builder type reflecting the updated state.

```rust
User::builder()                           // UserBuilder_MissingName_MissingEmail
    .name("Alice".to_string())            // UserBuilder_HasName_MissingEmail
    .email("alice@example.com".to_string()) // UserBuilder_HasName_HasEmail
    .build()                              // User
```

--------------------------------

### Configure a Custom Builder Entry Point

Source: https://github.com/welf/type-state-builder/blob/main/README.md

The #[builder(builder_method)] attribute allows a specific required field's setter to act as the entry point for the builder.

```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());
```

--------------------------------

### Config Struct with Required and Optional Fields

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Illustrates a Config struct with a required 'api_key' and optional 'timeout' and 'retries' fields. Required fields must be set before build() is available.

```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
}
```

--------------------------------

### Compare Type-State Implementation Approaches

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Shows the difference between generic type parameter tracking and TypeStateBuilder's explicit struct naming.

```rust
// Other implementations might generate something like:
UserBuilder<Set, Unset, Set, Unset>
//          ^    ^     ^    ^
//          What do these mean?
```

--------------------------------

### Handle Generics and Lifetimes

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Demonstrates support for generic types, lifetime parameters, and trait bounds within the builder.

```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();
```

--------------------------------

### ApiClient Builder with Setter Prefixes

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Illustrates applying setter prefixes at both the struct level (`#[builder(setter_prefix = "...")]`) and field level, with field-level prefixes overriding struct-level ones.

```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();
```

--------------------------------

### Person Builder with Custom Setter Names

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Demonstrates customizing setter method names using `#[builder(setter_name = "...")]` for individual fields.

```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();
```

--------------------------------

### Generated builder implementation

Source: https://github.com/welf/type-state-builder/blob/main/README.md

The macro generates specific builder structs and methods to manage state transitions based on required fields.

```rust
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,
        }
    }
}
```

--------------------------------

### Optional-Only Structs with Regular Builder

Source: https://context7.com/welf/type-state-builder/llms.txt

For structs with no required fields, a regular builder is generated, allowing `build()` to be called immediately. Default values can be specified for fields.

```rust
use type_state_builder::TypeStateBuilder;

#[derive(TypeStateBuilder)]
struct Settings {
    debug: bool,
    max_connections: Option<u32>,

    #[builder(default = "default.log".to_string())]
    log_file: String,

    #[builder(skip_setter, default = 42)]
    magic_number: i32,
}

fn main() {
    // Can call build() immediately since no required fields
    let settings = Settings::builder()
        .debug(true)
        .max_connections(Some(100))
        .build();

    assert!(settings.debug);
    assert_eq!(settings.max_connections, Some(100));
    assert_eq!(settings.log_file, "default.log");
    assert_eq!(settings.magic_number, 42);
}
```

--------------------------------

### Implement Custom Conversions with converter

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Applies custom transformation logic to setter inputs using closure expressions. The converter must be a closure with an explicitly typed parameter.

```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()));
```

```rust
// Correct
#[builder(converter = |value: &str| value.to_uppercase())]

// Incorrect - function references are not supported
#[builder(converter = str::to_uppercase)]
```

--------------------------------

### Document Builder with Skipped Setters

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Shows how to use `#[builder(skip_setter)]` to prevent a setter from being generated for a field, relying solely on its default value.

```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();
```

--------------------------------

### Generate Const fn Builder Methods

Source: https://context7.com/welf/type-state-builder/llms.txt

Use the `#[builder(const)]` attribute to generate `const fn` builder methods for compile-time constant construction. This is useful for static configuration and embedded systems.

```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,

    #[builder(default = false)]
    debug: bool,
}

// Compile-time constant construction
const APP_CONFIG: Config = Config::builder()
    .name("my-app")
    .version(1)
    .port(3000)
    .build();

// Static context
static DEFAULT_CONFIG: Config = Config::builder()
    .name("default")
    .version(0)
    .build();

// Const function
const fn make_config(name: &'static str, version: u32) -> Config {
    Config::builder()
        .name(name)
        .version(version)
        .debug(true)
        .build()
}

const DEBUG_CONFIG: Config = make_config("debug", 999);

fn main() {
    assert_eq!(APP_CONFIG.name, "my-app");
    assert_eq!(APP_CONFIG.port, 3000);
    assert_eq!(DEFAULT_CONFIG.port, 8080);  // Uses default
    assert!(DEBUG_CONFIG.debug);
}
```

--------------------------------

### Impl Into for Setters

Source: https://context7.com/welf/type-state-builder/llms.txt

The `#[builder(impl_into)]` attribute generates setters that accept `impl Into<T>`, allowing for more ergonomic API usage by automatically converting compatible types.

```APIDOC
## #[builder(impl_into)] Attribute

Generates setters that accept `impl Into<T>`, allowing more ergonomic API usage by automatically converting compatible types.

### Method

Applied at the struct level or field level with `impl_into = false` to override.

### Example

```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>,
}

fn main() {
    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();

    assert_eq!(config.name, "MyApp");
    assert_eq!(config.description, "An application");
    assert_eq!(config.id, Some(42));
}
```
```

--------------------------------

### Implementing a Type-Safe Builder

Source: https://context7.com/welf/type-state-builder/llms.txt

Use the TypeStateBuilder derive macro to generate a builder that enforces required fields at compile time.

```rust
use type_state_builder::TypeStateBuilder;

#[derive(TypeStateBuilder, Debug)]
struct User {
    #[builder(required)]
    name: String,

    #[builder(required)]
    email: String,

    age: Option<u32>,
    active: bool, // Uses Default::default() if not set
}

fn main() {
    // All required fields must be set before build() becomes available
    let user = User::builder()
        .name("Alice".to_string())
        .email("alice@example.com".to_string())
        .age(Some(30))
        .build();

    println!("User: {} ({})", user.name, user.email);
    // Output: User: Alice (alice@example.com)

    // Optional fields can be omitted
    let user2 = User::builder()
        .name("Bob".to_string())
        .email("bob@example.com".to_string())
        .build();

    assert_eq!(user2.age, None);
    assert_eq!(user2.active, false);
}
```

--------------------------------

### Configure Ergonomic Conversions with impl_into

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Uses impl_into to allow setters to accept any type that implements Into<T>. Individual fields can override this behavior by setting impl_into to false.

```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();
```

--------------------------------

### Setting Custom Default Values

Source: https://context7.com/welf/type-state-builder/llms.txt

Use the #[builder(default = expr)] attribute to 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,
}

fn main() {
    let config = ServerConfig::builder()
        .host("localhost".to_string())
        // port defaults to 8080
        // timeout_seconds defaults to 30
        // environment defaults to "production"
        .build();

    assert_eq!(config.port, 8080);
    assert_eq!(config.timeout_seconds, 30);
    assert_eq!(config.environment, "production");
}
```

--------------------------------

### Customize Build Method Name with #[builder(build_method = "...")]

Source: https://context7.com/welf/type-state-builder/llms.txt

Use the `build_method` attribute at the struct level to specify a custom name for the final build method, instead of the default `build()`.

```rust
use type_state_builder::TypeStateBuilder;

#[derive(TypeStateBuilder)]
#[builder(build_method = "create")]
struct Connection {
    #[builder(required)]
    host: String,

    #[builder(required, setter_name = "set_content")]
    content: String,

    #[builder(default = 42)]
    page_count: u32,
}

fn main() {
    let conn = Connection::builder()
        .host("localhost".to_string())
        .set_content("Document content".to_string())
        .page_count(100)
        .create();  // Uses custom build method name

    assert_eq!(conn.host, "localhost");
}
```

--------------------------------

### Define a struct with TypeStateBuilder

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Use the TypeStateBuilder derive macro to automatically generate builder states for a struct with required fields.

```rust
#[derive(TypeStateBuilder)]
struct User {
    #[builder(required)]
    name: String,
    age: Option<u32>,
}
```

--------------------------------

### Enable `impl Into<T>` for Setters with #[builder(impl_into)]

Source: https://context7.com/welf/type-state-builder/llms.txt

The `impl_into` attribute, when applied at the struct level, generates setters that accept any type implementing `Into<T>`, allowing for more flexible input types like `&str` for `String` fields. It can be disabled for specific fields using `impl_into = false`.

```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>,
}

fn main() {
    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();

    assert_eq!(config.name, "MyApp");
    assert_eq!(config.description, "An application");
    assert_eq!(config.id, Some(42));
}
```

--------------------------------

### Define a Const Builder

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Use the #[builder(const)] attribute to enable compile-time constant construction. Requires explicit defaults for optional fields and const-compatible types.

```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");
```

--------------------------------

### Use Closure Converters with Const Builders

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Closure converters allow transforming input values during the build process within a const context.

```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();
```

--------------------------------

### Customize Setter Method Name with #[builder(setter_name = "...")]

Source: https://context7.com/welf/type-state-builder/llms.txt

Use `setter_name` to specify a custom name for a field's setter method. This is useful for avoiding naming conflicts or for more descriptive 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>,
}

fn main() {
    let person = Person::builder()
        .full_name("Alice Smith".to_string())  // Custom setter name
        .years_old(Some(30))                   // Custom setter name
        .build();

    assert_eq!(person.name, "Alice Smith");
    assert_eq!(person.age, Some(30));
}
```

--------------------------------

### Customize Build Method Name

Source: https://github.com/welf/type-state-builder/blob/main/README.md

Renames the final build method generated by the builder using the build_method attribute.

```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
```

--------------------------------

### Custom Setter Transformations with #[builder(converter = |param: Type| expr)]

Source: https://context7.com/welf/type-state-builder/llms.txt

The `converter` attribute allows defining custom logic for transforming input values in setters. This is useful for parsing strings, normalizing data (e.g., trimming whitespace, converting case), or performing validation before assigning the value.

```rust
use type_state_builder::TypeStateBuilder;

#[derive(TypeStateBuilder, Debug)]
struct User {
    #[builder(required)]
    name: String,

    // Normalize email to lowercase and trim whitespace
    #[builder(required, converter = |email: &str| email.trim().to_lowercase())]
    email: String,

    // Parse comma-separated tags into Vec<String>
    #[builder(converter = |tags: &str| tags.split(',').map(|s| s.trim().to_string()).collect())]
    interests: Vec<String>,

    // Parse age from string with fallback
    #[builder(converter = |age: &str| age.parse().unwrap_or(0))]
    age: u32,
}

fn main() {
    let user = User::builder()
        .name("Alice".to_string())
        .email("  ALICE@EXAMPLE.COM  ")       // Normalized to "alice@example.com"
        .interests("rust, programming, web")  // Parsed to Vec<String>
        .age("25")                            // Parsed from string to u32
        .build();

    assert_eq!(user.email, "alice@example.com");
    assert_eq!(user.interests, vec!["rust", "programming", "web"]);
    assert_eq!(user.age, 25);
}
```

--------------------------------

### Custom Build Method Name

Source: https://context7.com/welf/type-state-builder/llms.txt

The `#[builder(build_method = "...")]` attribute allows you to customize the name of the final build method used to construct the object.

```APIDOC
## #[builder(build_method = "name")] Attribute

Customizes the name of the final build method. Applied at struct level.

### Method

Applied at the struct level.

### Example

```rust
use type_state_builder::TypeStateBuilder;

#[derive(TypeStateBuilder)]
#[builder(build_method = "create")]
struct Connection {
    #[builder(required)]
    host: String,

    #[builder(required, setter_name = "set_content")]
    content: String,

    #[builder(default = 42)]
    page_count: u32,
}

fn main() {
    let conn = Connection::builder()
        .host("localhost".to_string())
        .set_content("Document content".to_string())
        .page_count(100)
        .create();  // Uses custom build method name

    assert_eq!(conn.host, "localhost");
}
```
```

--------------------------------

### Setter Prefix

Source: https://context7.com/welf/type-state-builder/llms.txt

The `#[builder(setter_prefix = "...")]` attribute adds a specified prefix to setter method names. It can be applied at the struct level for all fields or at the field level to override the struct-level setting.

```APIDOC
## #[builder(setter_prefix = "prefix_")] Attribute

Adds a prefix to setter method names. Can be applied at struct level (all fields) or field level (overrides struct-level).

### Method

Can be applied to the struct or individual fields.

### Example

```rust
use type_state_builder::TypeStateBuilder;

#[derive(TypeStateBuilder)]
#[builder(setter_prefix = "with_")]
struct ApiClient {
    #[builder(required)]
    base_url: String,

    #[builder(required, setter_prefix = "set_")]  // Field-level override
    api_key: String,

    timeout: Option<u32>,
}

fn main() {
    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();

    assert_eq!(client.base_url, "https://api.example.com");
    assert_eq!(client.api_key, "secret123");
}
```
```

--------------------------------

### Custom Converter for Setters

Source: https://context7.com/welf/type-state-builder/llms.txt

The `#[builder(converter = |param: Type| expr)]` attribute provides custom transformation logic for setters, enabling parsing, normalization, and validation of input values.

```APIDOC
## #[builder(converter = |param: Type| expr)] Attribute

Provides custom transformation logic for setters, enabling parsing, normalization, and validation.

### Method

Applied to individual fields.

### Example

```rust
use type_state_builder::TypeStateBuilder;

#[derive(TypeStateBuilder, Debug)]
struct User {
    #[builder(required)]
    name: String,

    // Normalize email to lowercase and trim whitespace
    #[builder(required, converter = |email: &str| email.trim().to_lowercase())]
    email: String,

    // Parse comma-separated tags into Vec<String>
    #[builder(converter = |tags: &str| tags.split(',').map(|s| s.trim().to_string()).collect())]
    interests: Vec<String>,

    // Parse age from string with fallback
    #[builder(converter = |age: &str| age.parse().unwrap_or(0))]
    age: u32,
}

fn main() {
    let user = User::builder()
        .name("Alice".to_string())
        .email("  ALICE@EXAMPLE.COM  ")       // Normalized to "alice@example.com"
        .interests("rust, programming, web")  // Parsed to Vec<String>
        .age("25")                            // Parsed from string to u32
        .build();

    assert_eq!(user.email, "alice@example.com");
    assert_eq!(user.interests, vec!["rust", "programming", "web"]);
    assert_eq!(user.age, 25);
}
```
```

--------------------------------

### Add Prefix to Setter Names with #[builder(setter_prefix = "...")]

Source: https://context7.com/welf/type-state-builder/llms.txt

The `setter_prefix` attribute adds a prefix to all generated setter methods. It can be applied at the struct level for a global prefix or at the field level to override the struct-level prefix for a specific field.

```rust
use type_state_builder::TypeStateBuilder;

#[derive(TypeStateBuilder)]
#[builder(setter_prefix = "with_")]
struct ApiClient {
    #[builder(required)]
    base_url: String,

    #[builder(required, setter_prefix = "set_")]  // Field-level override
    api_key: String,

    timeout: Option<u32>,
}

fn main() {
    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();

    assert_eq!(client.base_url, "https://api.example.com");
    assert_eq!(client.api_key, "secret123");
}
```

--------------------------------

### Enforcing Required Fields

Source: https://context7.com/welf/type-state-builder/llms.txt

The #[builder(required)] attribute ensures that specific fields must be initialized before the build() method is accessible.

```rust
use type_state_builder::TypeStateBuilder;

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

    #[builder(required)]
    database: String,

    port: u16,  // Optional, defaults to 0
}

fn main() {
    let config = DatabaseConfig::builder()
        .host("localhost".to_string())
        .database("myapp".to_string())
        .build();

    // Attempting to build without required fields produces compile error:
    // error[E0599]: no method named `build` found for struct
    //               `DatabaseConfigBuilder_MissingHost_MissingDatabase`
}
```

--------------------------------

### Support for Generic Types and Lifetimes

Source: https://context7.com/welf/type-state-builder/llms.txt

TypeStateBuilder handles generic types, lifetime parameters, and complex trait bounds. Ensure that generic parameters and bounds are correctly defined in the struct.

```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>,
}

fn main() {
    let text = "referenced text";

    let container = Container::<String, i32>::builder()
        .data("Hello".to_string())
        .metadata(42)
        .reference(Some(text))
        .build();

    println!("Data: {}, Metadata: {}", container.data, container.metadata);
    // Output: Data: Hello, Metadata: 42
}
```

--------------------------------

### Custom Setter Name

Source: https://context7.com/welf/type-state-builder/llms.txt

The `#[builder(setter_name = "...")]` attribute allows you to specify a custom name for the setter method generated for a field.

```APIDOC
## #[builder(setter_name = "name")] Attribute

Customizes the setter method name for a specific field.

### Method

This attribute is applied to struct fields.

### Example

```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>,
}

fn main() {
    let person = Person::builder()
        .full_name("Alice Smith".to_string())  // Custom setter name
        .years_old(Some(30))                   // Custom setter name
        .build();

    assert_eq!(person.name, "Alice Smith");
    assert_eq!(person.age, Some(30));
}
```
```
Tokens:
Raw