dig

README

Dependency Injection Graph

package dig provides an opinionated way of resolving object dependencies. There are two sides of dig: Register and Resolve.

Register

Register adds an object, or a constructor of an object to the graph.

There are two ways to register an object:

1. Register a pointer to an existing object
2. Register a "constructor function" that returns one pointer (or interface)

Register an object

Injecting an object means it has no dependencies, and will be used as a shared singleton instance for all resolutions within the graph.

type Fake struct {
    Name string
}

g := dig.New()
err := g.Register(&Fake{Name: "I am an injected thing"})
require.NoError(t, err)

var f1 *Fake
err = g.Resolve(&f1)
require.NoError(t, err)

// f1 is ready to use here...

Register a constructor

This is a more interesting and widely used scenario. Constructor is defined as a function that returns exactly one pointer (or interface) and takes 0-N number of arguments. Each one of the arguments is automatically registered as a dependency and must also be an interface or a pointer.

The following example illustrates injecting a constructor function for type *Object that requires *Dep to be present in the graph

g := dig.New()

type Dep struct{}
type Object struct{
  Dep
}

func NewObject(d *Dep) *Object {
  return &Object{Dep: d}
}

err := g.Register(NewObject)

Resolve

Resolve retrieves objects from the graph by type.

There are future plans to do named retrievals to support multiple objects of the same type in the graph.

g := dig.New()

var o *Object
err := g.Resolve(&o) // notice the pointer to a pointer as param type
if err == nil {
    // o is ready to use
}

type Do interface{}
var d Do
err := g.Resolve(&d) // notice pointer to an interface
if err == nil {
    // d is ready to use
}

Documentation

Overview

Package dig is the Dependency Injection Graph.

package dig provides an opinionated way of resolving object dependencies. There are two sides of dig: Register and Resolve.

Register

Register adds an object, or a constructor of an object to the graph.

There are two ways to register an object:

• Register a pointer to an existing object

• Register a "constructor function" that returns one pointer (or interface)

Register an object

Injecting an object means it has no dependencies, and will be used as a **shared** singleton instance for all resolutions within the graph.

type Fake struct {
    Name string
}

g := dig.New()
err := g.Register(&Fake{Name: "I am an injected thing"})
require.NoError(t, err)

var f1 *Fake
err = g.Resolve(&f1)
require.NoError(t, err)

// f1 is ready to use here...

Register a constructor

This is a more interesting and widely used scenario. Constructor is defined as a function that returns exactly one pointer (or interface) and takes 0-N number of arguments. Each one of the arguments is automatically registered as a **dependency** and must also be an interface or a pointer.

The following example illustrates injecting a constructor function for type *Object that requires *Dep to be present in the graph

g := dig.New()

type Dep struct{}
type Object struct{
  Dep
}

func NewObject(d *Dep) *Object {
  return &Object{Dep: d}
}

err := g.Register(NewObject)

Resolve

Resolve retrieves objects from the graph by type.

There are future plans to do named retrievals to support multiple objects of the same type in the graph.

g := dig.New()

var o *Object
err := g.Resolve(&o) // notice the pointer to a pointer as param type
if err == nil {
    // o is ready to use
}

type Do interface{}
var d Do
err := g.Resolve(&d) // notice pointer to an interface
if err == nil {
    // d is ready to use
}

Index

• func MustRegister(i interface{})
• func MustRegisterAll(is ...interface{})
• func MustResolve(i interface{})
• func MustResolveAll(is ...interface{})
• func Register(i interface{}) error
• func RegisterAll(is ...interface{}) error
• func Reset()
• func Resolve(i interface{}) error
• func ResolveAll(is ...interface{}) error
• type Graph
  • func DefaultGraph() *Graph
  • func New() *Graph
  • func (g *Graph) MustRegister(c interface{})
  • func (g *Graph) MustRegisterAll(cs ...interface{})
  • func (g *Graph) MustResolve(obj interface{})
  • func (g *Graph) MustResolveAll(objs ...interface{})
  • func (g *Graph) Register(c interface{}) error
  • func (g *Graph) RegisterAll(cs ...interface{}) error
  • func (g *Graph) Reset()
  • func (g *Graph) Resolve(obj interface{}) (err error)
  • func (g *Graph) ResolveAll(objs ...interface{}) error
  • func (g *Graph) String() string

Functions

func MustRegister

func MustRegister(i interface{})

MustRegister calls Register and panics if an error is encountered

func MustRegisterAll

func MustRegisterAll(is ...interface{})

MustRegisterAll into the default graph

func MustResolve

func MustResolve(i interface{})

MustResolve through the default graph

func MustResolveAll

func MustResolveAll(is ...interface{})

MustResolveAll on the default graph

func Register

func Register(i interface{}) error

Register into the default graph

func RegisterAll

func RegisterAll(is ...interface{}) error

RegisterAll into the default graph

func Reset

func Reset()

Reset the default graph

func Resolve

func Resolve(i interface{}) error

Resolve an object through the default graph

func ResolveAll

func ResolveAll(is ...interface{}) error

ResolveAll through the default graph

Types

type Graph

type Graph struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Graph facilitates automated dependency resolution

func DefaultGraph

func DefaultGraph() *Graph

DefaultGraph returns the graph used by top-level calls

func New

func New() *Graph

New returns a new Dependency Injection Graph

func (*Graph) MustRegister

func (g *Graph) MustRegister(c interface{})

MustRegister will attempt to register the object and panic if error is encountered

func (*Graph) MustRegisterAll

func (g *Graph) MustRegisterAll(cs ...interface{})

MustRegisterAll calls RegisterAll and panics is an error is encountered

func (*Graph) MustResolve

func (g *Graph) MustResolve(obj interface{})

MustResolve calls Resolve and panics if an error is encountered

func (*Graph) MustResolveAll

func (g *Graph) MustResolveAll(objs ...interface{})

MustResolveAll calls ResolveAll and panics if an error is encountered

func (*Graph) Register

func (g *Graph) Register(c interface{}) error

Register an object in the dependency graph.

The provided argument must be a function that accepts its dependencies as arguments and returns a single result, which must be a pointer type. The function may optionally return an error as a second result.

func (*Graph) RegisterAll

func (g *Graph) RegisterAll(cs ...interface{}) error

RegisterAll registers all the provided args in the dependency graph

func (*Graph) Reset

func (g *Graph) Reset()

Reset the graph by removing all the registered nodes

func (*Graph) Resolve

func (g *Graph) Resolve(obj interface{}) (err error)

Resolve all of the dependencies of the provided class

Provided object must be a pointer Any dependencies of the object will receive constructor calls, or be initialized (once) Constructor with return value *object will be called

func (*Graph) ResolveAll

func (g *Graph) ResolveAll(objs ...interface{}) error

ResolveAll the dependencies of each provided object Returns the first error encountered

func (*Graph) String

func (g *Graph) String() string

String representation of the entire graph