Crate dilib

Expand description

§dilib-rs

A dependency injection library for Rust.

§Usage

[dependencies]
dilib = "0.2.0"

§Example

§Basic Usage

use dilib::Container;

struct Printer;
impl Printer {
    pub fn print(&self, s: &str) {
        println!("{}", s);
    }
}

struct EnglishGreeting;
impl EnglishGreeting {
    pub fn greet(&self) -> String {
        "Hello!".to_string()
    }
}

struct SpanishGreeting;
impl SpanishGreeting {
    pub fn greet(&self) -> String {
        "Hola!".to_string()
    }
}

let mut container = Container::new();
container.add_singleton(Printer).unwrap();
container.add_scoped(|| EnglishGreeting).unwrap();
container.add_scoped_with_name("es", || SpanishGreeting).unwrap();

let printer = container.get::<Printer>().unwrap();
let en = container.get::<EnglishGreeting>().unwrap();
let es = container.get_with_name::<SpanishGreeting>("es").unwrap();

printer.print(&en.greet());
printer.print(&es.greet());

§Table of Contents

Container
Derive Inject
Global Container
Provide
- Why ‘unstable_provide’?
- provide macro

§Container

The container is the main storage for the 2 types of provides:

Scoped: creates a new instance each time
Singleton: returns the same instance each time

All these providers can be named using the methods ended with with_name(...).

§Scoped provider

The scoped providers creates a new instance each time they are called.

use dilib::Container;

let mut container = Container::new();
container.add_scoped(|| String::from("Apple Pie")).unwrap();

let s = container.get::<String>().unwrap();
assert_eq!(s.as_ref(), "Apple Pie");

§Singleton provider

The singleton providers returns the same instance each time they are called.

use dilib::Container;
use std::sync::Mutex;

let mut container = Container::new();
container.add_singleton(Mutex::new(0)).unwrap();

{
    let c1 = container.get::<Mutex<i32>>().unwrap();
    *c1.lock().unwrap() = 3;
}

let c2 = container.get::<Mutex<i32>>().unwrap();
assert_eq!(*c2.lock().unwrap(), 3);

§Inject trait

The Inject trait is a mechanism to create a type using the providers of a container.

To add a type that implements Inject to the container, you use the add_deps methods, this adds the type as a Scoped provider.

use std::sync::{Mutex, atomic::AtomicUsize};
use dilib::{Container, Inject};

struct IdGenerator(AtomicUsize);
impl IdGenerator {
  pub fn next(&self) -> usize {
    1 + self.0.fetch_add(1, std::sync::atomic::Ordering::SeqCst)
  }
}

#[derive(Clone, Debug)]
struct Fruit {
    id: usize,
    tag: String
}

impl Inject for Fruit {
    fn inject(container: &Container) -> Self {
      let generator = container.get::<IdGenerator>().unwrap();
      let id = generator.next();
      let tag = container.get_with_name::<String>("fruit").unwrap().cloned();
      Fruit { id, tag }
    }
}

let mut container = Container::new();
container.add_singleton(IdGenerator(AtomicUsize::new(0))).unwrap();
container.add_scoped_with_name("fruit", || String::from("b18ap31")).unwrap();
container.add_deps::<Fruit>().unwrap();

let f1 = container.get::<Fruit>().unwrap();
let f2 = container.get::<Fruit>().unwrap();

assert_eq!(f1.id, 1);
assert_eq!(f1.tag, "b18ap31");

assert_eq!(f2.id, 2);
assert_eq!(f2.tag, "b18ap31");

§Bind trait to implementation

To add a trait to a container you should bind the trait to its implementation using the macros:

add_scoped_trait!(container, name, trait => impl)
add_singleton_trait!(container, name, trait => impl)
add_scoped_trait!(container, name, trait @ Inject)
add_singleton_trait!(container, name, trait @ Inject)

The name is optional.

This adds the trait as a Box<dyn Trait>.

And you can get the values back using:

get_scoped_trait!(container, name, trait)
get_singleton_trait!(container, name, trait)
get_resolved_trait(container, name, trait)

The name is also optional.

This returns the trait as a Box<dyn Trait>.

use dilib::{
  Container,
  add_scoped_trait, 
  add_singleton_trait, 
  get_resolved_trait, 
};

trait Discount {
  fn get_discount(&self) -> f32;
}

trait Fruit {
  fn name(&self) -> &str;
  fn price(&self) -> f32;
}

struct TenPercentDiscount;
impl Discount for TenPercentDiscount {
  fn get_discount(&self) -> f32 {
    0.1
  }
}

struct Apple;
struct Orange;

impl Fruit for Apple {
  fn name(&self) -> &str {
    "Apple"
  }
  
  fn price(&self) -> f32 {
    2.0
  }
}

impl Fruit for Orange {
  fn name(&self) -> &str {
    "Orange"
  }
  
  fn price(&self) -> f32 {
    1.7
  }
}

let mut container = Container::new();
add_singleton_trait!(container, Discount => TenPercentDiscount).unwrap();
add_scoped_trait!(container, "apple", Fruit => Apple).unwrap();
add_scoped_trait!(container, "orange", Fruit => Orange).unwrap();

// All types are returned as `Box<dyn Trait>`
let discount = get_resolved_trait!(container, Discount).unwrap();
let apple = get_resolved_trait!(container, Fruit, "apple").unwrap();
let orange = get_resolved_trait!(container, Fruit, "orange").unwrap();

assert_eq!(discount.get_discount(), 0.1);

assert_eq!(apple.name(), "Apple");
assert_eq!(apple.price(), 2.0);

assert_eq!(orange.name(), "Orange");
assert_eq!(orange.price(), 1.7);

§get, get_scoped and get_singleton

There are 3 ways to retrieve a value from the container:

get
get_scoped
get_singleton

And it’s named variants:

get_with_name
get_scoped_with_name
get_singleton_with_name

get_scoped and get_singleton are self-explanatory, they get a value from a scoped or singleton provider.

But get can get any scoped and singleton value, the difference is that get returns a Resolved<T> and the others returns a T (scoped) or Arc<T> (singletons).

Resolved<T> is just an enum for a Scoped(T) and Singleton(Arc<T>) where you can convert it back using into_scoped or into_singleton, it also implements Deref over T.

§Derive Inject

This requires the derive feature.

Inject is implemented for all types that implement Default and can be auto-implemented using #[derive]. When using the derive types Arc<T> and Singleton<T> will be injected as singleton, and other types as scoped unless specified.

use dilib::{Singleton, Inject, Container};
use dilib_derive::*;

#[derive(Inject)]
struct Apple {
  // Singleton is an alias for Arc<T>
  #[inject(name="apple")]
  tag: Singleton<String>,
  #[inject(name="apple_price")]
  price: f32
}

let mut container = Container::new();
container.add_singleton_with_name("apple", String::from("FRUIT_APPLE")).unwrap();
container.add_scoped_with_name("apple_price", || 2.0_f32).unwrap();
container.add_deps::<Apple>();

let apple = container.get::<Apple>().unwrap();
assert_eq!(apple.tag.as_ref(), "FRUIT_APPLE");
assert_eq!(apple.price, 2.0);

§Global Container

This requires the global feature.

dilib also offers a global container so you don’t require to declare your own, you can access the values of the container using get_scoped!, get_singleton!or get_resolved!, you can also access the container directly using get_container().

use dilib::{global::init_container, resolve};

init_container(|container| {
    container.add_scoped(|| String::from("Orange")).unwrap();
    container.add_singleton_with_name("num", 123_i32).unwrap();
}).expect("unable to initialize the container");

let orange = resolve!(String).unwrap();
let num = resolve!(i32, "num").unwrap();

assert_eq!(orange.as_ref(), "Orange");
assert_eq!(*num, 123);

§Provide

This requires the unstable_provide feature.

§Why unstable_provide?

The feature unstable_provide make possible to have dependency injection more similar to other frameworks like C# EF Core or Java Spring.

To allow run code before main we use the the ctor crate, which have been tested in several OS so is stable for most of the use cases.

§provide macro

You can use the #[provide] macro over any function or type that implements **Inject to register it to the global container.

** Any type that implements `Default` also implements `Inject`.

use std::sync::RwLock;
use dilib::global::init_container;
use dilib::{resolve, Singleton, Inject, provide};

#[allow(dead_code)]
#[derive(Debug, Clone)]
struct User {
    name: &'static str,
    email: &'static str,
}

trait Repository<T> {
    fn add(&self, item: T);
    fn get_all(&self) -> Vec<T>;
}

#[derive(Default)]
#[provide(scope="singleton")]
struct Db(RwLock<Vec<User>>);

#[derive(Inject)]
#[provide(bind="Repository<User>")]
struct UserRepository(Singleton<Db>);
impl Repository<User> for UserRepository {
    fn add(&self, item: User) {
        self.0.0.write().unwrap().push(item);
    }

    fn get_all(&self) -> Vec<User> {
        self.0.0.read().unwrap().clone()
    }
}

// Initialize the container to register the providers
init_container(|_container| {
// Add additional providers
}).unwrap();

let user_repository = resolve!(trait Repository<User>).unwrap();
user_repository.add(User { name: "Marie", email: "marie@example.com" });
user_repository.add(User { name: "Natasha", email: "natasha@example.com" });

let users = user_repository.get_all();
let db = resolve!(Db).unwrap();
println!("Total users: {}", db.0.read().unwrap().len());
println!("{:#?}", users);

Re-exports§

pub use macros::*;

Modules§

global: A global instance of Container.
late_init: A lazy evaluated cell.
macros: procedural macros of dilib.

Macros§

add_scoped_trait: Helper macro to bind a trait to it’s implementation in a Container as scoped.
add_singleton_trait: Helper macro to bind a trait to it’s implementation in a Container as a singleton.
get_resolved_trait: Helper macro to get an implementation of a trait in a Container.
get_scoped: Returns a scoped value from the global Container or None if is not in the container.
get_scoped_trait: Helper macro to get the implementation of a trait in a Container as scoped.
get_singleton: Returns a singleton value from the global Container or None if is not in the container.
get_singleton_trait: Helper macro to get the implementation of a trait in a Container as a singleton.
resolve: Returns a value from the Container or None if is not in the container.

Structs§

Container: Represents a store to register and retrieve objects.
InjectionKey: Represents an unique key for identify a provider.

Enums§

Provider: Provides a Container value.
ProviderKind: Represents the type of the provider.
Resolved: Represents a value from a Container.
Scoped: Represents an Scoped provider which provide a new instance each time.
Shared: Provides a singleton value.

Traits§

Inject: A trait for constructing a type getting the dependencies from a Container.

Type Aliases§

Singleton: A convenient singleton type.

Derive Macros§

Inject: Provides an implementation of the Inject trait for the given type.

Crate dilib

Crate dilib Copy item path

§dilib-rs

§Usage

§Example

§Basic Usage

§Table of Contents

§Container

§Scoped provider

§Singleton provider

§Inject trait

§Bind trait to implementation

§get, get_scoped and get_singleton

§Derive Inject

§Global Container

§Provide

§Why unstable_provide?

§provide macro

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Type Aliases§

Derive Macros§

Crate dilib