bon

bon is a Rust procedural-macro crate that generates compile-time-checked builders for structs, free functions, and methods via #[derive(Builder)] or #[builder]. Its generated builders use the typestate pattern so that forgetting a required field, or attempting to set the same field twice, is a compile error rather than a runtime panic — while optional fields can be skipped entirely.

Beyond struct builders, bon effectively gives Rust named and optional function arguments: annotating a function or method with #[builder] turns its positional parameters into a chainable, named-argument call style (greet().name("Bon").level(24).call()), supporting async, generic, and fallible functions. It’s built as a thin bon wrapper crate around the heavier bon-macros proc-macro implementation crate in the same workspace.

What You Get

• #[derive(Builder)] for structs, generating a .builder()...build() chain with typestate-enforced required fields
• #[builder] on free functions and, combined with #[bon] on impl blocks, on associated methods and constructors
• Typestate-based compile errors instead of runtime panics for missing required fields or repeated setter calls
• Support for async, generic, fallible functions, impl Trait, and no_std/no_alloc environments via feature flags

Common Use Cases

• Replacing hand-written builder boilerplate for structs with many optional fields, especially configuration or request-object types
• Giving library functions named, optional arguments without requiring callers to remember positional order
• Enforcing at compile time that all required builder fields are set before .build()/.call() is reachable, catching mistakes before runtime
• Building async or generic APIs (e.g. SDK client constructors) where a fluent, chainable call style improves readability over long positional signatures

Under The Hood

Architecture — bon is a Cargo workspace: the thin bon crate (bon/src/lib.rs) re-exports macros implemented in the separate bon-macros crate (~11,200 lines), which parses #[builder]/#[derive(Builder)] annotations and expands them into a typestate-driven builder struct with one marker type per required field’s fill status, so the compiler rejects .build() calls until every required setter has been invoked. Tech Stack — Pure Rust built on syn/proc-macro2/quote inside bon-macros, with the public bon crate depending on a version-pinned bon-macros (exact-matched via =x.y.z since generated code touches private, non-semver-guarded APIs) plus rustversion for MSRV-gated code paths; the workspace also includes a website (Vue/TypeScript) and dedicated benchmarks crates for compile-time and runtime overhead tracking. Code Quality — The bon crate’s tests/integration directory contains roughly 84 test files covering builder attributes, UI/compile-error snapshots (via trybuild), init ordering, and generics, and the workspace enforces an extensive Clippy lint configuration in the root Cargo.toml; commit and release cadence is active (47 releases, ~2.7 commits/month). API Design — The #[builder]/#[derive(Builder)] surface mirrors ordinary struct/function definitions closely, and the generated .field_name(value) chainable setters plus .build()/.call() terminal methods read naturally, though the typestate machinery it generates under the hood can produce verbose compiler errors when something is misused, and advanced features (custom getters, overwritable fields, generics setters) are gated behind explicit opt-in attributes.