Example

/////////////////////////////////////////

// Define interfaces in traits
trait A: Send + Sync {
    fn test(&self) -> String;
}

// Implement traits to define components
#[dill::component]
#[dill::interface(dyn A)]
struct AImpl {
    // Auto-inject dependencies (also supports by-value)
    b: Arc<dyn B>,
}

impl A for AImpl {
    fn test(&self) -> String {
        format!("aimpl::{}", self.b.test())
    }
}

/////////////////////////////////////////

trait B: Send + Sync {
    fn test(&self) -> String;
}

#[dill::component]
#[dill::interface(dyn B)]
struct BImpl;

impl B for BImpl {
    fn test(&self) -> String {
        "bimpl".to_owned()
    }
}

/////////////////////////////////////////

// Register components
let cat = Catalog::builder()
    .add::<AImpl>()
    .add::<BImpl>()
    .build();

// Get objects and have their deps satisfied automatically
let inst = cat.get::<OneOf<dyn A>>().unwrap();
assert_eq!(inst.test(), "aimpl::bimpl");

Status

While documentation is still lacking, this crate is production-ready and is in active use in kamu-cli - a fairly large project organized according to Onion/Clean Architecture.

Features

• Injection specs:
  • OneOf - expects a single implementation of a given interface
  • AllOf - returns a collection of all implementations on a given interface
  • Maybe<Spec> - returns None if inner Spec cannot be resolved
  • Lazy<Spec> - injects an object that delays the creation of value until it is requested
• Component scopes:
  • Transient (default) - short-lived, a new instance is created for every invocation
  • Agnostic - same as Transient but signals that it's OK to inject this instance into more long-lived scopes
  • Singleton - an instance is created upon first use and then reused for the rest of calls
  • Transaction - an instance will be cached for the duration of a transaction
• #[component] macro can derive Builder:
  • When used directly for a struct or on impl block with Impl::new() function
  • Can inject as Arc<T>, T: Clone, &T
  • Option<T> is interpreted as Maybe<OneOf<T>> spec
  • Vec<T> is interpreted as AllOf<T> spec
  • Supports custom argument bindings in Builder
  • Supports default interface bindings via #[interface] attribute
  • Supports metadata association via #[meta(...)] attribute
• Prebuilt / add by value support
• By value injection of Clone types
• Catalog can be self-injected
• Chaining of Catalogs allows adding values dynamically (e.g. in middleware chains like tower)
• CatalogBuilder::validate() performs static analysis to detect dangling and ambiguous dependencies and scope inversion issues
• Catalog can be scoped within a tokio task as "current" to override the source of Lazyly injected values
• Utils:

  • dill::utils::graphviz and dill::utils::plantuml allow visualizing the dependency graph

Design Principles

• Non-intrusive
  • Writing DI-friendly code should be as close as possible to writing regular types
  • DI should be an additive feature - we should be able to disable it and have all code compile (i.e. allowing for DI-optional libraries)
• Externalizable
  • It should be possible to add DI capabilities to 3rd party code
• Focus on runtime injection
  • Leveraging type system and zero-cost abstractions is great, but hard to get right - this project started because we needed something practical fast
  • Some cases involve dynamic registration of objects (e.g. adding an auth token during HTTP request processing), which further complicates compile-time DI
  • We use DI to integrate coarse-grained components, where some overhead is tolerable
  • We compensate for safety by providing runtime graph validation
• Focus on constructor injection
  • Field/property/accessor-based injection would complicate the system, and in our experience is of little use
• Put implementation in control

  • The type implementor (and not type user) usually has the best knowledge of what the optimal lifecycle for the type should be and its concurrency characteristics, thus implementors should be in control of the defaults

TODO

• Support stable rust
• Make Scopes external to Builders so they could be overridden
• Consider using traits to map Arc, Option, Vec to dependency specs instead of relying on macro magic
• Add trybuild tests (see https://youtu.be/geovSK3wMB8?t=956)
• Support generic types
• Replace add_* with generic add<B: Into<Builder>>
• value by reference in new()
• • Send + Sync plague https://www.reddit.com/r/rust/comments/6dz0xh/abstracting_over_reference_counted_types_rc_and/
• doctests
• proc macro error handling
• build a type without registering
• Support PImpl idiom, where Arc<dyn Iface> can be hidden behind a movable object

  • This even further hides lifetime management from consumers

  • Allows generic methods to be implemented to improve usability of dyn Trait (e.g. accepting impl AsRef<str> parameters instead of &str)