di

README

Dependency injection

DI is a dependency injection library that is focused on clean API and flexibility. DI has two types of top-level abstractions: Container and Resolver. First one is responsible for accepting constructors and implementations and creating abstraction bindings out of them. Second implements different implementation resolution scenarios against one or more Containers.

Initially this library was heavily inspired by GoLobby Container but since then had a lot of backwards incompatible changes in structure, functionality and API. To install DI simply run in your project directory:

go get github.com/HnH/di

Container

type Container interface {
    Singleton(constructor interface{}, opts ...Option) error
    Factory(constructor interface{}, opts ...Option) error
    Implementation(implementation interface{}, opts ...Option) error
    ListBindings(reflect.Type) (map[string]Binding, error)
    Reset()
}

Singleton

Singleton() method requires a constructor which will return Implementation(s) of Abstraction(s). Constructor will be called once and returned Implementations(s) will later always bound to Abstraction(s) on resolution requests.

err = di.Singleton(func() (Abstraction, SecondAbstraction) {
    return Implementation, SecondImplementation
})

// Singleton may also accept naming option which means that returned Implementation will be available only under provided name.
err = di.Singleton(func() (Abstraction) {
    return Implementation
}, di.WithName("customName"))

// Name can be provided for each of the Implementations if there are more than one.
err = di.Singleton(func() (Abstraction, SecondAbstraction) {
    return Implementation, SecondImplementation
}, di.WithName("customName", "secondCustomName"))

// If there is only one Implementation returned you may give multiple aliases for it.
err = di.Singleton(func() (Abstraction) {
    return Implementation
}, di.WithName("customName", "secondCustomName"))


// WithFill() option calls `resolver.Fill()` on an instance right after it is created.
err = di.Singleton(func() (Abstraction) {
    return Implementation
}, di.WithFill()) // di.resolver.Fill(Implementation) will be called under the hood

Factory

Factory() method requires a constructor which will return exactly one Implementation of exactly one Abstraction. Constructor will be called on each Abstraction resolution request.

err = di.Factory(func() (Abstraction) {
    return Implementation
})

// Factory also optionally accepts naming option which means that returned Implementation will be available only under provided name.
err := di.Factory(func() (Abstraction) {
    return Implementation
}, di.WithName("customName"))

// Similarly to Singleton binding WithFill() option can be provided
err = di.Factory(func() (Abstraction) {
    return Implementation
}, di.WithFill()) // di.resolver.Fill(Implementation) will be called under the hood

Implementation

Implementation() receives ready instance and binds it to its real type, which means that declared abstract variable type (interface) is ignored.

var circle Shape = newCircle()
err = di.Implementation(circle)

// Will return error di: no binding found for di_test.Shape
var a Shape
err = di.Resolve(&a)

// Will resolve circle.
var c *Circle
err = di.Resolve(&a)

// Also naming options can be used as everywhere.
err = di.Implementation(circle, di.WithName("customName"))
err = di.Resolve(&c, di.WithName("customName"))

Resolver

type Resolver interface {
    With(implementations ...interface{}) Resolver
    Resolve(receiver interface{}, opts ...Option) error
    Call(function interface{}, opts ...Option) error
    Fill(receiver interface{}) error
}

With

With() takes a list of instantiated implementations and tries to use them in resolving scenarios. In the opposite to Container's Implementation() method With() does not put instances into container and does not reflect a type on a binding time. Instead of this it reuses reflect.Type.AssignableTo() method capabilities on abstraction resolution time.

var circle Shape = newCircle()
err = di.Implementation(circle)

// di: no binding found for di_test.Shape
di.Call(func(s Shape) { return })

// ok
di.With(circle).Call(func(s Shape) { return }))

Resolve

Resolve() requires a receiver (pointer) of an Abstraction and fills it with appropriate Implementation.

var abs Abstraction
err = di.Resolve(&a)

// Resolution can be done with previously registered names as well
err = di.Resolve(&a, di.WithName("customName"))

Call

The Call() executes as function with resolved Implementation as a arguments.

err = di.Call(func(a Abstraction) {
    // `a` will be an implementation of the Abstraction
})

// Returned values can be bound to variables by providing an option.
var db Database
err = di.Call(func(a Abstraction) Database {
    return &MySQL{a}
}, di.WithReturn(&db))
// db == &MySQL{a}

Fill

The Fill() method takes a struct (pointer) and resolves its fields. The example below expresses how the Fill() method works.

err = di.Singleton(func() Mailer { return &someMailer{} })

err = di.Singleton(func() (Database, Database) {
    return &MySQL{}, &Redis{} 
}, di.WithName("data", "cache"))

type App struct {
    mailer  Mailer     `di:"type"` // fills by field type (Mailer)
    data    Database   `di:"name"` // fills by field type (Mailer) and requires binding name to be field name (data)
    cache   Database   `di:"name"`
    inner   struct {
        cache Database `di:"name"`	
    } `di:"recursive"`             // instructs DI to fill struct recursively
    another struct {
        cache Database `di:"name"` // won't have any affect as long as outer field in App struct won't have `di:"recursive"` tag
    }
}

var App = App{}
err = container.Fill(&myApp)

// [Typed Bindings]
// `App.mailer` will be an implementation of the Mailer interface

// [Named Bindings]
// `App.data` will be a MySQL implementation of the Database interface
// `App.cache` will be a Redis implementation of the Database interface
// `App.inner.cache` will be a Redis implementation of the Database interface

// `App.another` will be ignored since it has no `di` tag

Notice that by default Fill() method returns error if unable to resolve any struct fields. If one of the fields if optional, omitempty suffix should be added to the di tag.

type App struct {
    mailer  Mailer `di:"type,omitempty"` // Fill will not return error if Mailer was not provided
}

Alternatively map[string]Type or []Type can be provided. It will be filled with all available implementations of provided Type.

var list []Shape
container.Fill(&list)

// []Shape{&Rectangle{}, &Circle{}}

var list map[string]Shape
container.Fill(&list)

// map[string]Shape{"square": &Rectangle{}, "rounded": &Circle{}} 

Provider

Provider is an abstraction of an entity that provides something to Container

type Provider interface {
    Provide(Container) error
}

Constructor

Constructor implements a Construct() method which is called either after binding to container in case of singleton, either after factory method was called. Note that context.Context must be provided in container before Constructor method can be called.

type Constructor interface {
    Construct(context.Context) error
}

Context propagation

type Context interface {
    Put(Container) Context
    Container() Container
    Resolver() Resolver
    Raw() context.Context
}

Context propagation is possible via di.Context abstraction. Quick example:

var container = di.NewContainer()
container.Implementation(newCircle())

var (
    ctx = di.Ctx(context.Background).Put(container)
    shp Shape
)

err = ctx.Resolver().Resolve(&shp) // err == nil

Documentation

Overview

Package di is a dependency injection library that is focused on clean API and flexibility. DI has two types of top-level abstractions: Container and Resolver. First one is responsible for accepting constructors and implementations and creating abstraction bindings out of them. Second implements different implementation resolution scenarios against one or more Containers.

Initially this library was heavily inspired by GoLobby Container (https://github.com/golobby/container) but since then had a lot of backwards incompatible changes in structure, functionality and API.

Index

• Constants
• func Call(ctx context.Context, function interface{}, opts ...Option) error
• func Factory(ctx context.Context, constructor interface{}, opts ...Option) error
• func Fill(ctx context.Context, receiver interface{}) error
• func Implementation(ctx context.Context, implementation interface{}, opts ...Option) error
• func Reset(ctx context.Context)
• func Resolve(ctx context.Context, receiver interface{}, opts ...Option) error
• func Singleton(ctx context.Context, constructor interface{}, opts ...Option) error
• type Binding
• type Constructor
• type Container
  • func NewContainer() Container
• type Context
  • func Ctx(ctxt context.Context) Context
• type FillingOption
• type NamingOption
• type Option
  • func WithFill() Option
  • func WithName(names ...string) Option
  • func WithReturn(returns ...interface{}) Option
• type Options
• type Provider
• type Resolver
  • func NewResolver(containers ...Container) Resolver
  • func With(ctx context.Context, implementations ...interface{}) Resolver
• type ReturnOption

Constants

const DefaultBindName = "default"

DefaultBindName is the name that is used in containers by default when binding values.

Functions

func Call

func Call(ctx context.Context, function interface{}, opts ...Option) error

Call takes a function, builds a list of arguments for it from the available bindings, calls it and returns a result.

func Factory

func Factory(ctx context.Context, constructor interface{}, opts ...Option) error

Factory binds constructor as a factory method of related type.

func Fill

func Fill(ctx context.Context, receiver interface{}) error

Fill takes a struct and resolves the fields with the tag `di:"..."`. Alternatively map[string]Type or []Type can be provided. It will be filled with all available implementations of provided Type.

func Implementation

func Implementation(ctx context.Context, implementation interface{}, opts ...Option) error

Implementation receives ready instance and binds it to its REAL type, which means that declared abstract variable type (interface) is ignored

func Reset

func Reset(ctx context.Context)

Reset deletes all the existing bindings and empties the container instance.

func Resolve

func Resolve(ctx context.Context, receiver interface{}, opts ...Option) error

Resolve takes a receiver and fills it with the related implementation.

func Singleton

func Singleton(ctx context.Context, constructor interface{}, opts ...Option) error

Singleton binds value(s) returned from constructor as a singleton objects of related types.

Types

type Binding

type Binding struct {
	// contains filtered or unexported fields
}

Binding holds either singleton instance or factory method for a binding

type Constructor

type Constructor interface {
	Construct(context.Context) error
}

Constructor implements a `Construct()` method which is called either after binding to container in case of singleton or after factory method was called.

type Container

type Container interface {
	Singleton(constructor interface{}, opts ...Option) error
	Factory(constructor interface{}, opts ...Option) error
	Implementation(implementation interface{}, opts ...Option) error
	ListBindings(reflect.Type) (map[string]Binding, error)
	Reset()
}

Container is responsible for abstraction binding

func NewContainer

func NewContainer() Container

NewContainer creates a new instance of the Container

type Context

type Context interface {
	SetContainer(Container) Context
	Container() Container
	SetResolver(Resolver) Context
	Resolver() Resolver
	Raw() context.Context
}

Context describe DI context propagator capabilities

func Ctx

func Ctx(ctxt context.Context) Context

Ctx returns context propagator

type FillingOption

type FillingOption interface {
	SetFill(bool)
}

FillingOption supports setting a fill flag

type NamingOption

type NamingOption interface {
	SetName(...string)
}

NamingOption supports setting a name

type Option

type Option func(Options)

Option represents single option type

func WithFill

func WithFill() Option

WithFill returns a FillingOption

func WithName

func WithName(names ...string) Option

WithName returns a NamingOption

func WithReturn

func WithReturn(returns ...interface{}) Option

WithReturn returns a ReturnOption

type Options

type Options interface {
	Apply(Option)
}

Options represents a target for applying an Option

type Provider

type Provider interface {
	Provide(Container) error
}

Provider is an abstraction of an entity that provides something to Container

type Resolver

type Resolver interface {
	With(implementations ...interface{}) Resolver
	Resolve(receiver interface{}, opts ...Option) error
	Call(function interface{}, opts ...Option) error
	Fill(receiver interface{}) error
}

Resolver implements methods for several implementation resolution scenarios

func NewResolver

func NewResolver(containers ...Container) Resolver

NewResolver constructs a Resolver against one or more Containers

func With

func With(ctx context.Context, implementations ...interface{}) Resolver

With takes a list of instantiated implementations and tries to use them in resolving scenarios

type ReturnOption

type ReturnOption interface {
	SetReturn(...interface{})
}

ReturnOption supports setting a return target