KInit

Installation

go get github.com/go-kata/kinit

Status

This is a beta version. API is not stabilized for now.

Versioning

Till the first major release minor version (v0.x.0) must be treated as a major version
and patch version (v0.0.x) must be treated as a minor version.

For example, changing of version from v0.1.0 to v0.1.1 indicates compatible changes,
but when version changes v0.1.1 to v0.2.0 this means that the last version breaks the API.

How to use

This library provides the global IoC container which does
the automatic Dependency Injection:

kinit.Global()

If you need a local one (e.g. for tests), you can create it as following:

ctr := kinit.NewContainer()

A local container must be filled up with constructors and processors manually whereas the global one
can be filled up when initializing packages.

Constructors

Constructors are entities that create objects (dependencies for injection in context of the DI). They have the
following interface:

type Constructor interface {
    Type() reflect.Type
    Parameters() []reflect.Type
    Create(a ...reflect.Value) (reflect.Value, kdone.Destructor, error)
}

Here Type returns a type of object to create, Parameters returns types of other objects required to create
this object and finally Create creates and returns a new object and its destructor (usekdone.Noop, not nil,
if object has no destructor).

To register a constructor in the container use the Provide method.

The container allows to have only one constructor for each type. However, the reflect.Type is the interface, and
you can implement it as you want, e.g. as following:

type NamedType stuct {
    reflect.Type
    Name string
}

Just keep in mind that the container uses a simple comparison of reflect.Type instances when looks up for
necessary constructors (as well as processors and already created objects).

Processors

Processors are entities that process already created objects. The container applies processors immediately after
the object creation and before an object will be injected as a dependency at the first time. Processors have the
following interface:

type Processor interface {
    Type() reflect.Type
    Parameters() []reflect.Type
    Process(obj reflect.Value, a ...reflect.Value) error
}

Here Type returns a type of object to process, Parameters returns types of other objects required to process
this object and finally Process processes an object.

To register a processor in the container use the Attach method.

The container allows to have an unlimited number of processors for each type but doesn’t guarantee the order of
their calling.

Functors

Functors represent functions to be run in the container and have the following interface:

type Functor interface {
    Parameters() []reflect.Type
    Call(a ...reflect.Value) ([]Functor, error)
}

Here Parameters returns types of objects required to call a function and Call calls a function and may return
further functors.

To run functors in the container use the Run method.

At the start of run the container creates so-called arena that holds all created objects (only one object
for each type). If some object required as a dependency is already on the arena it will be used, otherwise
it will be firstly created and processed. All objects that are on the arena at the end of run will be
automatically destroyed.

The container runs given functors sequentially. Their dependencies are resolved recursively using registered
constructors and processors. If functor (let’s call it branched) returns further functors, the container runs
all of them before continue running functors following the branched one. This is called the Depth-First Run.

KInitX

This subpackage provides the expansion set includes default handy implementations of main library interfaces
along with other handy tools. In most cases the KInitX is all you need to use the entire KInit functionality.

There are following implementations:

Constructor represents a constructor based on a function. It accepts func(...) T, func(...) (T, error) and
func(...) (T, kdone.Destructor, error) signatures where T is an arbitrary Go type.

kinitx.MustProvide(func(config *Config) (*Object, kdone.Destructor, error) { ... })

Opener represents a constructor based on a function that creates an implementation of the io.Closer interface.
It accepts func(...) C and func(...) (C, error) signatures where C is an arbitrary implementation of the
io.Closer interface.

kinitx.MustProvide(func(logger *log.Logger) (*sql.DB, error) { ... })

Initializer represents a memberwise initializer of a struct. It accepts a template struct like a YourType{}
and a template struct pointer like a (*YourType)(nil) or new(YourType).

kinitx.MustProvide((*Config)(nil))

Binder represents a pseudo-constructor that casts an object to an interface. It accepts an interface pointer
like a (*YourInterface)(nil).

kinitx.MustBind((*StorageInterface)(nil), (*PostgresStrorage)(nil))

Processor represents a processor based on a function. It accepts func(T, ...) and func(T, ...) error
signatures where T is an arbitrary Go type.

kinitx.MustAttach((*Object).SetOptionalProperty)

Functor represents a functor based on a function. It accepts func(...), func(...) error,
func(...) (kinit.Functor, error) and func(...) ([]kinit.Functor, error) signatures.

kinitx.MustRun(func(app *Application) error { ... })

KInitQ

The DI mechanism provided by the main library is reflection-based and works in the runtime. However, this subpackage
makes it possible to validate the dependency graph semi-statically thanks to build tags.

Just add two main functions as following:

main.go

// +build !inspect
package main
import "github.com/go-kata/kinit/kinitx"
func main() { kinitx.MustRun(EntryPoint) }

main_inspect.go

// +build inspect
package main
import "github.com/go-kata/kinit/kinitx"
func main() { kinitx.MustInspect(nil) }

Now to validate the dependency graph of your program just run:

go run -tags inspect

Example output:

2 errors occurred:
    #1 🠖 cyclic dependency: *config.Config 🠖 config.Loader 🠖 *config.FileLoader 🠖 *config.Config
    #2 🠖 unsatisfied dependency: *sql.DB 🠖 *log.Logger

For more details learn the documentation and explore examples.

Putting all together

In the github.com/go-kata/examples repository you can find examples of
how may the code uses this library looks like.

References

KDone is the library that provides tools for destroying objects.

KError is the library that provides tools for handling errors.