Struct Kit 

pub struct Kit<S = Unbuilt> { /* private fields */ }

The capability and configuration management center.

Implementations

impl Kit

pub fn new() -> Self

Create a new empty Kit.

pub fn register<M: AutoBuilder>(&mut self) -> Result<(), TraitKitError>

Register a module for construction.

Errors

Returns TraitKitError::AlreadyRegistered if a module with the same TypeId was already registered.

pub fn register_lazy<M: AutoBuilder>(&mut self) -> Result<(), TraitKitError>

where M::Capability: Clone + 'static,

Register a module for lazy construction.

The module is added to the dependency graph (for validation) but its build_fn is not invoked during build(). Instead, the build_fn is stored in lazy_builders and transferred to Kit<Ready>.lazy_slots during build(). The capability is constructed on first require() call and cached via OnceLock for subsequent accesses.

This is useful for modules that are expensive to build or may never be needed in a particular run.

Errors

Returns TraitKitError::AlreadyRegistered if the module was already registered (via register or register_lazy). Returns TraitKitError::DependencyMissing if a dependency is not registered.

pub fn register_multi<M: AutoBuilder>(&mut self) -> Result<(), TraitKitError>

where M::Capability: Clone + 'static,

Register a module for multi-binding construction.

Multiple module types that share the same M::Capability type can be registered via register_multi; their build_fns are appended to a Vec keyed by TypeId::of::<M::Capability>() (the capability type, not the module type). The Vec preserves registration order.

The module is also added to the dependency graph for validation, so M must be distinct from any previously registered module (via register, register_lazy, or register_multi). Two registrations of the same module type M will return AlreadyRegistered.

During build(), all multi-binding builders are invoked and the results are stored in multi_capabilities (T011). Use require_all to retrieve the ordered Vec of capabilities.

Errors

Returns TraitKitError::AlreadyRegistered if M was already registered (via any register* method). Dependency validation is deferred to build() (via graph.validate()).

pub fn override_module<M: AutoBuilder>(&self, capability: M::Capability)

where M::Capability: 'static,

Override a module’s capability with a pre-built value, skipping build_fn.

Used for test injection: inject a mock capability without running the module’s build function. Completely skips dependency checking (pure unit testing). The module does not need to be registered via register() first — the override is keyed by TypeId::of::<M>().

If build() is called later, the override is consumed and the original build_fn (if any) is never invoked for this module.

pub fn override_module_strict<M: AutoBuilder>( &mut self, capability: M::Capability, ) -> Result<(), TraitKitError>

where M::Capability: 'static,

Override a module’s capability with a pre-built value, but still verify that the module’s declared dependencies are registered in the dependency graph.

Unlike override_module, this method requires &mut self (exclusive access) and checks M::dependencies() against the graph. If any dependency is not registered, returns TraitKitError::DependencyMissing.

The module does not need to be registered via register() first. Only the dependencies must be present.

Errors

Returns TraitKitError::DependencyMissing if any of M::dependencies() is not registered in the graph.

pub fn set_config<C: Clone + 'static>(&self, config: C)

Set a configuration value.

pub fn build(self) -> Result<Kit<Ready>, TraitKitError>

Validate the dependency graph and build all modules in topological order.

After this call, all capabilities are available via require().

Errors

Returns TraitKitError::DependencyMissing if a registered module depends on an unregistered module. Returns TraitKitError::CycleDetected if a dependency cycle is found. Returns TraitKitError::MissingCapability if a build function is missing for a sorted module. Returns TraitKitError::BuildFailed if a module’s build callback returns an error.

pub fn register_if<M: AutoBuilder>( &mut self, predicate: impl FnOnce(&Kit) -> bool, ) -> Result<bool, TraitKitError>

Conditionally register a module based on a runtime predicate.

The predicate receives the current Kit (for inspecting configs or other state). Returns true if the module was actually registered.

Errors

Returns TraitKitError::AlreadyRegistered if the predicate returns true but the module was already registered.

impl<S> Kit<S>

pub fn require<M: AutoBuilder>(&self) -> Result<M::Capability, TraitKitError>

Retrieve a capability by its module type.

Available on both Kit<Unbuilt> (inside AutoBuilder::build callbacks) and Kit<Ready> (after build() completes).

On Kit<Ready>, if the module was registered via register_lazy, the first require() call triggers lazy construction: the stored build_fn is invoked, the result is cached in a OnceLock cell, and subsequent calls return a clone from the cache without re-running the builder.

Errors

Returns TraitKitError::MissingCapability if the module has not been built. Returns TraitKitError::BuildFailed if a lazy module’s build_fn fails.

pub fn require_all<M: AutoBuilder>( &self, ) -> Result<Vec<M::Capability>, TraitKitError>

where M::Capability: Clone + 'static,

Retrieve all capabilities registered via register_multi for the given module type, in registration order.

Available on both Kit<Unbuilt> and Kit<Ready>, but multi_capabilities is only populated after build(). Calling require_all before build() returns MissingCapability.

Errors

Returns TraitKitError::MissingCapability if no multi-binding capabilities were registered for M::Capability.

pub fn config<C: Clone + 'static>(&self) -> Result<C, TraitKitError>

Get a configuration value.

Errors

Returns TraitKitError::MissingConfig if no value of type C was set.

impl Kit<Ready>

pub fn optional<M: AutoBuilder>(&self) -> Option<M::Capability>

Retrieve an optional capability. Returns None if not built.

pub fn require_ref<M: AutoBuilder>( &self, ) -> Result<Ref<'_, M::Capability>, TraitKitError>

where M::Capability: 'static,

Retrieve a capability by reference, avoiding Clone.

Unlike require(), this returns a Ref borrowing the stored value directly, with no clone overhead. The Ref holds a read lock on the interior RefCell — while it is alive, calling reload_config or any mutating method will panic (borrow_mut conflict). Keep the Ref lifetime short.

Errors

Returns TraitKitError::MissingCapability if the module has not been built.

pub fn contains<M: AutoBuilder>(&self) -> bool

Check if a capability has been built.

pub fn contains_config<C: Clone + 'static>(&self) -> bool

Check if a config is registered.

pub fn factory<M: AutoBuilder>( &self, ) -> impl Fn() -> Result<M::Capability, TraitKitError> + '_

Create a factory closure that produces new instances on each call.

Unlike require() which returns the singleton built during build(), the factory invokes M::build() on every call, producing a fresh instance each time.

pub fn graph_dot(&self) -> String

Export the dependency graph as a Graphviz DOT string.

pub fn graph_mermaid(&self) -> String

Export the dependency graph as a Mermaid flowchart string.

Trait Implementations

impl Debug for Kit

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Debug for Kit<Ready>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Kit

fn default() -> Self

Returns the “default value” for a type.