chassis 0.2.0

#![doc(html_root_url = "https://docs.rs/chassis/0.2.0")]

//! Compile-time dependency injector.
//!
//! *Let the compiler generate your dependency injection code.*
//!
//! ## Goals
//! * No need to annotate your classes (support for third-party classes)
//! * No required usage of [`Arc`]
//! * Zero overhead: Fast as handwritten code
//!     * No use of runtime type information (provided by [`Any`] references) -
//!       At the moment relying on compiler optimization until [`min_specialization`]
//!      is stabilized.
//! * (Detect errors at compile time like missing dependencies or cyclic dependencies)
//!   * Waiting for compile time reflection or at least stabilization of
//!     [`min_specialization`], [`const_type_id`] and [`const_cmp_type_id`]
//!
//! ## Use
//!
//! Add `chassis` to your crate dependencies
//! ```toml
//! [dependencies]
//! chassis = "^0.2.0"
//! ```
//!
//! Structs will be modules that can provide dependencies with functions
//! and that itself can have dependencies.
//! *Note: Currently only associated functions are supported!*
//! ```rust,no_run
//! # pub struct Dependency1;
//! # pub struct Dependency2;
//! # pub struct Dependency3;
//! # impl Dependency3 { fn new(dep1: Dependency1, dep2: Dependency2) -> Self { Self } }
//! #[derive(Default)]
//! pub struct Module;
//!
//! #[chassis::module]
//! impl Module {
//!     pub fn provide_something(dep1: Dependency1, dep2: Dependency2) -> Dependency3 {
//!         Dependency3::new(dep1, dep2)
//!     }
//!     // ...
//! }
//! ```
//!
//! Traits will be components. For each trait an implemented component will be created.
//! The generated implementation will have a `Impl` suffix, for example `ComponentImpl`. Also a
//! `Component::new` function is created.
//! ```rust,no_run
//! # pub struct MainClass;
//! # #[derive(Default)] pub struct Module;
//! # #[chassis::module] impl Module { }
//! #[chassis::injector(modules = [Module])]
//! pub trait Component {
//!     fn resolve_main_class(&self) -> MainClass;
//! }
//! ```
//!
//! ## Example
//! ```rust,no_run
//! use std::rc::Rc;
//!
//! // define your business logic
//!
//! /// printer trait
//! pub trait Printer {
//!     fn print(&self, input: &str);
//! }
//!
//! /// a printer implementation
//! pub struct StdoutPrinter;
//! impl Printer for StdoutPrinter {
//!     fn print(&self, input: &str) {
//!         println!("{}", input);
//!     }
//! }
//!
//! /// greeter for messages
//! pub struct Greeter {
//!     message: String,
//!     printer: Rc<dyn Printer>,
//! }
//! impl Greeter {
//!     /// constructor with dependencies
//!     pub fn new(message: String, printer: Rc<dyn Printer>) -> Self {
//!         Self { message, printer }
//!     }
//!
//!     /// your business logic
//!     pub fn say_hello(&self) {
//!         self.printer.print(&self.message);
//!     }
//! }
//!
//! /// module that is parsed to create the dependency injection code
//! #[derive(Default)]
//! pub struct DemoModule;
//!
//! // use strong types when in need to distinguish
//! pub struct Message(String);
//!
//! /// Define how to create your dependencies
//! #[chassis::module]
//! impl DemoModule {
//!     pub fn provide_printer() -> Rc<dyn Printer> {
//!         Rc::new(StdoutPrinter)
//!     }
//!
//!     pub fn provide_message() -> Message {
//!         Message("Hello World".to_string())
//!     }
//!
//!     pub fn provide_greeter(
//!         message: Message,
//!         printer: Rc<dyn Printer>
//!     ) -> Greeter {
//!         Greeter::new(message.0, printer)
//!     }
//! }
//!
//! /// Define which dependencies you need.
//! ///
//! /// A struct `DemoComponentImpl` will be created for
//! /// you which implements `DemoComponent`.
//! #[chassis::injector(modules = [DemoModule])]
//! pub trait DemoComponent {
//!     /// request the to create injection code for our main class `Greeter`
//!     fn resolve_greeter(&self) -> Greeter;
//! }
//!
//! fn main() {
//!     // use generated component implementation
//!     let injector = <dyn DemoComponent>::new()
//!         .expect("DI container should be consistent");
//!
//!     // Resolve main dependency
//!     // Note: it can not fail at runtime!
//!     let greeter = injector.resolve_greeter();
//!
//!     // enjoy!
//!     greeter.say_hello();
//! }
//! ```
//!
//! ## Singletons
//!
//! Normally for every needed dependency the provider function on the module is called. This results
//! in types created multiple times. This is maybe not intended. The solution is to use a
//! `singleton` attribute. The provide method will than only called once at build time of the
//! component (call to `ComponentImpl::new`). The requirement is that the type implements the
//! [`Clone`] trait. It is recommendable to use a shared reference type like [`Rc`] or [`Arc`] for
//! singletons so that really only one instance is created.
//!
//! ### Example
//! ```rust,no_run
//! # use std::rc::Rc;
//! # trait Printer {}
//! # struct StdoutPrinter;
//! # impl Printer for StdoutPrinter {}
//! # #[derive(Default)]
//! # struct Module;
//! #[chassis::module]
//! impl Module {
//!     #[chassis(singleton)]
//!     pub fn provide_printer() -> Rc<dyn Printer> {
//!         Rc::new(StdoutPrinter)
//!     }
//! }
//! ```
//!
//! ## Limitations
//! * Lifetimes in the types are not supported (except `'static`)
//! * Generics are not handled correctly
//! * Request a reference to a registered non-reference type in a module
//!   (`&MyType` when `MyType` is provided by a module)
//! * Lazy requests (request a provider instead of concrete type)
//! * Optional requests (only get it when it exists)
//! * Multiple provider (useful for plugins)
//! * Failable module functions (return `Result` in module)
//!
//! [`Clone`]: Clone
//! [`Copy`]: Copy
//! [`Rc`]: std::rc::Rc
//! [`Arc`]: std::sync::Arc
//! [`Any`]: std::any::Any
//! [`min_specialization`]: https://github.com/rust-lang/rust/issues/68970
//! [`const_type_id`]: https://github.com/rust-lang/rust/issues/77125
//! [`const_cmp_type_id`]: https://github.com/rust-lang/rust/issues/101871

extern crate core;

use core::fmt;
use std::any::{Any, TypeId};
use std::error::Error;

pub use chassis_proc_macros::{injector, module};

mod check;

/// Internal interface between modules and injector
#[doc(hidden)]
pub mod injector {
    use std::any::Any;

    /// Interface implemented by [crate::module]
    pub trait ProvideModule {
        /// Return type of [ProvideModule::into_provider]
        type Provider: Provider;

        /// Allow introspection of this module
        fn introspect<T: Any>(visitor: &mut impl IntrospectVisitor);
        /// Turn module in a real provider
        ///
        /// This provider holds for example singleton values.
        fn into_provider(self) -> Self::Provider;
    }

    /// Provider for values.
    ///
    /// This provider holds singleton values and calls module methods.
    ///
    /// Implemented by [crate::module]
    pub trait Provider {
        fn provide<T: Any, V: Injector>(&self, v: &V) -> Option<T>;
    }

    /// Injector interface.
    ///
    /// Implemented by [crate::injector]
    pub trait Injector {
        fn provide<T: Any>(&self) -> T;
        fn introspect<T: Any>(visitor: &mut impl IntrospectVisitor);
    }

    /// Interface for introspection of injector.
    ///
    /// Implemented by a user of [Injector::introspect]
    pub trait IntrospectVisitor {
        /// Visit provider for `T` provided by module `M`.
        ///
        /// `dependencies` provides ability to iterate over dependencies of the provider.
        fn item<M: Any, T: Any, A: DependenciesAccess>(&mut self, dependencies: A);
    }

    /// Iterator over dependencies of a provider.
    ///
    /// Implemented by [crate::module]
    pub trait DependenciesAccess {
        /// Called for every dependency of provider
        fn next<V: DependenciesVisitor>(&self, visitor: &mut V);
    }

    /// Interface for introspection of a dependency.
    ///
    /// Implemented by a user of [Injector::introspect]
    pub trait DependenciesVisitor {
        /// Visit dependency on type `T`.
        fn dependency<T: Any>(&mut self);
    }
}

/// Information about a type
///
/// Useful for error messages.
pub struct TypeInfo {
    id: TypeId,
    name: &'static str,
}

impl TypeInfo {
    /// Create for type
    pub fn of<T: Any>() -> Self {
        Self {
            id: TypeId::of::<T>(),
            name: std::any::type_name::<T>(),
        }
    }

    /// Type identifier
    pub fn id(&self) -> TypeId {
        self.id
    }

    /// Type name from [std::any::type_name]
    pub fn name(&self) -> &'static str {
        self.name
    }
}

impl PartialEq for TypeInfo {
    fn eq(&self, other: &Self) -> bool {
        self.id == other.id
    }
}

impl fmt::Debug for TypeInfo {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_tuple("TypeInfo").field(&self.name).finish()
    }
}

/// Errors detected when assembling inject modules.
#[derive(Debug, PartialEq)]
pub struct AssembleErrors(Box<[AssembleError]>);

impl AssembleErrors {
    /// Create from a list of errors
    pub fn new(errors: impl Into<Box<[AssembleError]>>) -> Self {
        Self(errors.into())
    }

    /// Provide iterator to errors
    pub fn iter(&self) -> std::slice::Iter<AssembleError> {
        self.0.iter()
    }

    /// Provide errors slice
    pub fn as_slice(&self) -> &[AssembleError] {
        &self.0
    }
}

/// Error detected when assembling inject modules.
#[derive(Debug, PartialEq)]
#[allow(unused)]
pub enum AssembleError {
    /// Cyclic dependency detected
    ///
    /// An injection point requests an value that requires transitive this value.
    CyclicDependency { ty: TypeInfo },
    /// Implementation is missing
    ///
    /// It is impossible to provide value because no module provides it.
    MissingImplementation {
        /// Type for which a implementation is missing
        ty: TypeInfo,
    },
    /// Multiple implementations found for a type
    ///
    /// Multiple modules provide implementations to provide a type
    DuplicateImplementation {
        /// Type for which multiple implementations exist
        ty: TypeInfo,
    },
    /// Internal error happened
    ///
    /// Should not occur. It is possibly a bug of this library.
    InternalError(String),
}

impl fmt::Display for AssembleError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            AssembleError::InternalError(message) => {
                f.write_fmt(format_args!("Internal error: {}", message))
            }
            AssembleError::CyclicDependency { ty } => f.write_fmt(format_args!(
                "Cyclic dependency when providing '{}'",
                ty.name()
            )),
            AssembleError::MissingImplementation { ty } => {
                f.write_fmt(format_args!("No provider for '{}'", ty.name()))
            }
            AssembleError::DuplicateImplementation { ty } => {
                f.write_fmt(format_args!("Multiple providers for '{}'", ty.name()))
            }
        }
    }
}

impl fmt::Display for AssembleErrors {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        for (i, error) in self.0.iter().enumerate() {
            if i != 0 {
                f.write_str("\n")?;
            }
            fmt::Display::fmt(error, f)?;
        }
        Ok(())
    }
}

impl Error for AssembleErrors {}

/// Result type of factory builder
pub type AssembleResult<T> = Result<T, AssembleErrors>;

/// Internal helper functions
#[doc(hidden)]
pub mod __priv {
    use std::any::Any;

    pub use crate::check::check_factory;

    #[inline]
    #[allow(clippy::mem_replace_option_with_none)]
    pub fn safe_transmute<U: Any, T: Any>(x: U) -> T {
        let mut tmp: Option<U> = Some(x);
        std::mem::replace(
            (&mut tmp as &mut dyn Any)
                .downcast_mut::<Option<T>>()
                .unwrap(),
            None,
        )
        .unwrap()
    }
}