Lightweight, generic & simple dependency injection (DI) container.

# ore - Generic Dependency Injection Container for Go

[![Go Report Card](https://goreportcard.com/badge/github.com/firasdarwish/ore)](https://goreportcard.com/report/github.com/firasdarwish/ore)
[![Go Reference](https://pkg.go.dev/badge/github.com/firasdarwish/ore.svg)](https://pkg.go.dev/github.com/firasdarwish/ore)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go?tab=readme-ov-file#dependency-injection)
[![Maintainability](https://api.codeclimate.com/v1/badges/3bd6f2fa4390af7c8faa/maintainability)](https://codeclimate.com/github/firasdarwish/ore/maintainability)
[![codecov](https://codecov.io/gh/firasdarwish/ore/graph/badge.svg?token=ISZVCCYGCR)](https://codecov.io/gh/firasdarwish/ore)

![ore](https://github.com/firasdarwish/ore/assets/1930361/c1426ba1-777a-43f5-8a9a-7520caa45516)


___
`ore` is a lightweight, generic & simple dependency injection (DI) container for Go.

Inspired by the principles of ASP.NET Dependency Injection, designed to facilitate
the management of object lifetimes and the inversion of control in your applications.


<br />

# Features

- **Singletons**: Register components as singletons, ensuring that there's only one instance throughout the entire
  application.


- **Transients**: Register components as transients, creating a new instance each time it is requested.


- **Scoped Instances**: Register components as scoped, tying them to a specific context or scope. Scoped components are
  created once per scope and reused within that scope.


- **Lazy Initialization**: Support for lazy initialization of components, allowing for efficient resource utilization.


- **Multiple Implementations of the Same Interface**: Register and retrieve several implementations of the same
  interface type, allowing for flexible and modular design.


- **Keyed Services Injection**: Support for injecting services based on a key, allowing you to differentiate between
  multiple implementations of the same interface or type.


- **Concurrency-Safe**: Utilizes a mutex to ensure safe concurrent access to the container.

<br />

# Installation

```bash
go get -u github.com/firasdarwish/ore
```

<br />

# Usage

### Import

```go
import "github.com/firasdarwish/ore"
```

### Example Service

```go
// interface
type Counter interface {
  AddOne()
  GetCount() int
}

// implementation
type simpleCounter struct {
  counter int
}

func (c *simpleCounter) AddOne()  {
  c.counter++
}

func (c *simpleCounter) GetCount() int {
  return c.counter
}

func (c *simpleCounter) New(ctx context.Context) Counter {
  return &simpleCounter{}
}
```

<br />

### Eager Singleton

```go
package main

import (
  "context"
  "github.com/firasdarwish/ore"
)

func main() {
  var c Counter
  c = &simpleCounter{}

  // register
  ore.RegisterEagerSingleton[Counter](c)

  ctx := context.Background()

  // retrieve
  c, ctx := ore.Get[Counter](ctx)
  c.AddOne()
  c.AddOne()
}
```

<br />

### Lazy (using Creator[T] interface)

```go
package main

import (
  "context"
  "fmt"
  "github.com/firasdarwish/ore"
)

func main() {
  // register
  ore.RegisterLazyCreator[Counter](ore.Scoped, &simpleCounter{})

  // OR
  //ore.RegisterLazyCreator[Counter](ore.Transient, &simpleCounter{})
  //ore.RegisterLazyCreator[Counter](ore.Singleton, &simpleCounter{})

  ctx := context.Background()

  // retrieve
  c, ctx := ore.Get[Counter](ctx)
  c.AddOne()
  c.AddOne()

  // retrieve again
  c, ctx = ore.Get[Counter](ctx)
  c.AddOne()

  // prints out: `TOTAL: 3`
  fmt.Println("TOTAL: ", c.GetCount())
}
```

<br />

### Lazy (using anonymous func)

```go
package main

import (
  "context"
  "fmt"
  "github.com/firasdarwish/ore"
)

func main() {
  // register
  ore.RegisterLazyFunc[Counter](ore.Scoped, func(ctx context.Context) Counter {
    return &simpleCounter{}
  })

  // OR
  //ore.RegisterLazyFunc[Counter](ore.Transient, func(ctx context.Context) Counter {
  //  return &simpleCounter{}
  //})

  // Keyed service registration
  //ore.RegisterLazyFunc[Counter](ore.Singleton, func(ctx context.Context) Counter {
  // return &simpleCounter{}
  //}, "name here", 1234)

  ctx := context.Background()

  // retrieve
  c, ctx := ore.Get[Counter](ctx)
  c.AddOne()
  c.AddOne()

  // Keyed service retrieval
  //c, ctx := ore.Get[Counter](ctx, "name here", 1234)

  // retrieve again
  c, ctx = ore.Get[Counter](ctx)
  c.AddOne()

  // prints out: `TOTAL: 3`
  fmt.Println("TOTAL: ", c.GetCount())
}
```

<br />

### Several Implementations

```go
package main

import (
  "context"
  "github.com/firasdarwish/ore"
)

func main() {
  // register
  ore.RegisterLazyCreator[Counter](ore.Scoped, &simpleCounter{})

  ore.RegisterLazyCreator[Counter](ore.Scoped, &yetAnotherCounter{})

  ore.RegisterLazyFunc[Counter](ore.Transient, func(ctx context.Context) Counter {
    return &simpleCounter{}
  })

  ore.RegisterLazyCreator[Counter](ore.Singleton, &yetAnotherCounter{})

  ctx := context.Background()

  // returns a slice of `Counter` implementations
  counters, ctx := ore.GetList[Counter](ctx)

  // to retrieve a slice of keyed services
  //counters, ctx := ore.GetList[Counter](ctx, "my integer counters")

  for _, c := range counters {
    c.AddOne()
  }

  // It will always return the LAST registered implementation
  defaultImplementation, ctx := ore.Get[Counter](ctx) // simpleCounter
  defaultImplementation.AddOne()
}

```

<br />

### Keyed Services Retrieval Example

```go
package main

import (
  "context"
  "fmt"
  "github.com/firasdarwish/ore"
)

func main() {
  // register
  ore.RegisterLazyFunc[Counter](ore.Singleton, func(ctx context.Context) Counter {
    return &simpleCounter{}
  }, "name here", 1234)

  //ore.RegisterLazyCreator[Counter](ore.Scoped, &simpleCounter{}, "name here", 1234)

  //ore.RegisterEagerSingleton[Counter](&simpleCounter{}, "name here", 1234)

  ctx := context.Background()

  // Keyed service retrieval
  c, ctx := ore.Get[Counter](ctx, "name here", 1234)
  c.AddOne()

  // prints out: `TOTAL: 1`
  fmt.Println("TOTAL: ", c.GetCount())
}

```

## More Complex Example
```go

type Numeric interface {
	int
}

type GenericCounter[T Numeric] interface {
  Add(number T)
  GetCount() T
}

type genericCounter[T Numeric] struct {
  counter T
}

func (gc *genericCounter[T]) Add(number T) {
  gc.counter += number
}

func (gc *genericCounter[T]) GetCount(ctx context.Context) T {
  return gc.counter
}
```

```go
package main

import (
  "context"
  "github.com/firasdarwish/ore"
)

func main() {

  // register
  ore.RegisterLazyFunc[GenericCounter[int]](ore.Scoped, func(ctx context.Context) GenericCounter[int] {
    return &genericCounter[int]{}
  })

  // retrieve
  c, ctx := ore.Get[GenericCounter[int]](ctx)
}

```

<br />

# Benchmarks

```bash
goos: windows
goarch: amd64
pkg: github.com/firasdarwish/ore
cpu: 13th Gen Intel(R) Core(TM) i9-13900H
BenchmarkRegisterLazyFunc
BenchmarkRegisterLazyFunc-20             5404572               209.6 ns/op
BenchmarkRegisterLazyCreator
BenchmarkRegisterLazyCreator-20          5683119               195.5 ns/op
BenchmarkRegisterEagerSingleton
BenchmarkRegisterEagerSingleton-20       5335443               218.8 ns/op
BenchmarkGet
BenchmarkGet-20                          4231207               279.8 ns/op
BenchmarkGetList
BenchmarkGetList-20                      2098818               544.6 ns/op
```


# Contributing


Feel free to contribute by opening issues, suggesting features, or submitting pull requests. We welcome your feedback and contributions.


# License


This project is licensed under the MIT License - see the LICENSE file for details.


Component-based development with dependency injection using reflections for Go developers.

<div>
    <div align="center"><img src="https://avatars.githubusercontent.com/u/80048065?s=200&u=a95ef12cecad462ed24df9418a8464241301cc16"/></div>
    <div align="center">
        <a href="https://github.com/boot-go/boot/tags"><img alt="Commit tag" src="https://img.shields.io/github/v/tag/boot-go/boot"></a>
        <a href="https://github.com/boot-go/boot/actions/workflows/action.yml"><img src="https://github.com/boot-go/boot/actions/workflows/action.yml/badge.svg?branch=main" alt="github action"></a>
        <a href="https://htmlpreview.github.io/?https://gist.githubusercontent.com/boot-go/c77b22000b3e249510dfb4542847c708/raw/ae9b2e83e9a4adafed6da2160e40855f86ca58a8/cover.html"><img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/boot-go/c77b22000b3e249510dfb4542847c708/raw/test_coverage.json" alt="test coverage"></a>
        <a href="https://goreportcard.com/report/github.com/boot-go/boot"><img src="https://goreportcard.com/badge/github.com/boot-go/boot" alt="go report"></a>
        <a href="https://pkg.go.dev/github.com/boot-go/boot"><img src="https://pkg.go.dev/badge/github.com/boot-go/boot.svg" alt="Go Reference"></a>
        <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
    </div>
</div>

**boot-go** accentuate [component-based development](https://en.wikipedia.org/wiki/Component-based_software_engineering) (CBD).

This is an opinionated view of writing modular and cohesive [Go](https://github.com/golang/go) code. It emphasizes the separation of concerns by loosely coupled components, which communicate with each other via methods and events. The goal is to support writing maintainable code on the long run by leveraging the well-defined standard library.

**boot-go** provided key features are:
- dependency injection
- configuration handling
- code decoupling

### Development characteristic
**boot-go** supports two different development characteristic. For simplicity reason, use the functions ```Register```, ```RegisterName```, ```Override```, ```OverrideName```, ```Shutdown``` and ```Go``` to register components and start **boot-go**. This is the recommended way, despite the fact that one global session is used.

But **boot-go** supports also creating new sessions, so that no global variable is required. In this case, the methods ```Register```, ```RegisterName```, ```Override```, ```OverrideName```, ```Shutdown``` and ```Go``` are provided to register components and start **boot-go**.

### Simple Example
The **hello** component is a very basic example. It contains no fields or provides any interface to interact with other components. The component will just print the _'Hello World'_ message to the console.
```go
package main

import (
	"github.com/boot-go/boot"
	"log"
)

// init() registers a factory method, which creates a hello component.
func init() {
	boot.Register(func() boot.Component {
		return &hello{}
	})
}

// hello is the simplest component.
type hello struct{}

// Init is the initializer of the component.
func (c *hello) Init() error {
	log.Printf("boot-go says > 'Hello World'\n")
	return nil
}

// Start the example and exit after the component was completed.
func main() {
	boot.Go()
}
```

The same example using a new session, which don't need any global variables.
```Go
package main

import (
	"github.com/boot-go/boot"
	"log"
)

// hello is the simplest component.
type hello struct{}

// Init is the initializer of the component.
func (c *hello) Init() error {
	log.Printf("boot-go says > 'Hello World'\n")
	return nil
}

// Start the example and exit after the component was completed.
func main() {
	s := boot.NewSession()
	s.Register(func() boot.Component {
		return &hello{}
	})
	s.Go()
}
```

### Component wiring
This example shows how components get wired automatically with dependency injection. The server component starts at ```:8080``` by default, but the port is configurable by setting the environment variable ```HTTP_SERVER_PORT```. 
```go
package main

import (
	"github.com/boot-go/boot"
	"github.com/boot-go/stack/server/httpcmp"
	"io"
	"net/http"
)

// init() registers a factory method, which creates a hello component
func init() {
	boot.Register(func() boot.Component {
		return &hello{}
	})
}

// hello is a very simple http server example.
// It requires the Eventbus and the chi.Server component. Both components
// are injected by the boot framework automatically
type hello struct {
	Eventbus boot.EventBus  `boot:"wire"`
	Server   httpcmp.Server `boot:"wire"`
}

// Init is the constructor of the component. The handler registration takes place here.
func (h *hello) Init() error {
	// Subscribe to the registration event
	h.Eventbus.Subscribe(func(event httpcmp.InitializedEvent) {
		h.Server.HandleFunc("/", func(writer http.ResponseWriter, request *http.Request) {
			io.WriteString(writer, "boot-go says: 'Hello World'\n")
		})
	})
	return nil
}

// Start the example and test with 'curl localhost:8080'
func main() {
	boot.Go()
}
```

### Component
Everything in **boot-go** starts with a component. They are key fundamental in the development and can be considered as an elementary build block. The essential concept is to get all the necessary components functioning with as less effort as possible. Therefore, components must always provide a default configuration, which uses the most common settings. As an example, a **http server** should always start using port **8080**, unless the developer specifies it. Or a postgres component should try to connect to **localhost:5432** when there is no database url provided.

A component should be _fail tolerant_, _recoverable_, _agnostic_ and _decent_.

| Facet           | Meaning                                       | Example                                                                                                                                                                         |
|-----------------|-----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| _fail tolerant_ | Don't stop processing on errors.              | A http request can still be processed, even when the metrics server is not available anymore.                                                                                   |
| _recoverable_   | Try to recover from errors.                   | A database component should try to reconnect after losing the connection.                                                                                                       |
| _agnostic_      | Behave the same in any environment.           | A key-value store component should work on a local development machine the same way as in a containerized environment.                                                          |
| _decent_        | Don't overload the developer with complexity. | Keep the interface and events as simple as possible. It's better to build three smaller but specific components then one general with increased complexity. Less is often more. |

### Configuration
Configuration values can also be automatically injected with arguments or environment variables at start time. The value from ```USER``` will be used in this example. If the argument ```--USER madpax``` is not set and the environment variable is not defined, it is possible to specify the reaction whether the execution should stop with a panic or continue with a warning.
```go
package main

import (
	"github.com/boot-go/boot"
	"log"
)

// hello is still a simple component.
type hello struct{
	Out string `boot:"config,key:USER,default:madjax"` // get the value from the argument list or environment variable. If no value could be determined, then use the default value `madjax`.
}

// init() registers a factory method, which creates a hello component and returns a reference to it.
func init() {
	boot.Register(func() boot.Component {
		return &hello{}
	})
}

// Init is the initializer of the component.
func (c *hello) Init() error {
	log.Printf("boot-go says > 'Hello %s'\n", c.Out)
	return nil
}

// Start the example and exit after the component was completed
func main() {
	boot.Go()
}

```


### boot stack
**boot-go** was primarily designed to build opinionated frameworks and bundle them as a stack. So every developer or company can choose to use the [default stack](https://github.com/boot-go/stack), a shared stack or rather create a new one. Stacks should be build with one specific purpose in mind for building a **microservice**, **ui application**, **web application**, **data analytics application** and so on. As an example, a **web application boot stack** could contain a http server component, a sql database component, a logging and a web application framework.


### Examples
More examples can be found in the [tutorial repository](https://github.com/boot-go/tutorial).


boot-go

A dependency injection framework based on components, allowing dynamic dependency replacement without duplicating code in tests.

# ComponeGo Framework

[![Go Report Card](https://goreportcard.com/badge/github.com/componego/componego)](https://goreportcard.com/report/github.com/componego/componego)
[![Tests](https://github.com/componego/componego/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/componego/componego/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/componego/componego/branch/master/graph/badge.svg?token=W4CPM75389)](https://codecov.io/gh/componego/componego)
[![Go Reference](https://pkg.go.dev/badge/github.com/componego/componego.svg)](https://pkg.go.dev/github.com/componego/componego)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

![screenshot](./docs/mkdocs/theme/assets/images/social.png)

It is a framework for building applications based on components. These components can be used in multiple applications and are interchangeable.
This framework is used solely to initialize the application and does NOT affect the main loop of your application.
You can still use your favorite frameworks and libraries. We allow you to wrap them in components.

Components may depend on other components. They can be expanded or reduced based on your requirements.
Components are not microservices; they are folders that contain different functionalities.

The framework has very low coupling within its code. All entities are optional.

We provide the ability to use dependency injection, configuration, and error handling.
However, one of the framework's main features is that you can modify entities without changing the application code.
This allows you to create mocks for any part of your application without changing the code.

If your application is divided into components (modules), it further separates your code into different services and allows you to reuse it in other applications.
Of course, you don’t need to make components too small.

### Documentation

Introduction: [medium.com/@konstanchuk/25bfd16a97a9](https://medium.com/@konstanchuk/25bfd16a97a9).

Visit our website to learn more: [componego.github.io](https://componego.github.io/).

The documentation is up-to-date with the latest version of the framework.
Please update your version to [the latest](https://github.com/componego/componego/releases).

### Examples

You can find some examples [here](./examples).

A typical application of this framework looks like [this](./examples/url-shortener-app/internal/application/application.go).

### Skeleton

You can quickly create a basic application in several ways:
```shell
curl -sSL https://raw.githubusercontent.com/componego/componego/master/tools/create-basic-app.sh | sh
```
or
```shell
wget -O - https://raw.githubusercontent.com/componego/componego/master/tools/create-basic-app.sh | sh
```
On Windows, you can run the commands above with Git Bash, which comes with [Git for Windows](https://git-scm.com/download/win).

### Contributing

We are open to improvements and suggestions. Pull requests are welcome.

### License

The source code of the repository is licensed under the [Apache 2.0 license](./LICENSE).
The core of the framework does not depend on other packages.


componego

A dependency injection service container for Go projects.

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![GoDoc](https://pkg.go.dev/badge/github.com/NVIDIA/gontainer)](https://pkg.go.dev/github.com/NVIDIA/gontainer)
![Test](https://github.com/NVIDIA/gontainer/actions/workflows/go.yml/badge.svg)
[![Report](https://goreportcard.com/badge/github.com/NVIDIA/gontainer)](https://goreportcard.com/report/github.com/NVIDIA/gontainer)

# Gontainer

Dependency injection service container for Golang projects.
<p align="center"><img src="splash.png" width="400"/></p>

## Features

- 🚀 Eager services instantiation with automatic dependencies resolution and optional dependencies support.
- 🛠 Dependency Injection for service factories, avoiding manual fetch through container API.
- 🔄 Reverse-to-Instantiation order for service termination to ensure proper resource release and shutdown.
- 📣 Events broker for inter-service container-wide communications.
- 🤖 Clean, tested and with small codebase based on reflection.

## Examples

* [Basic script example](./examples/01_basic_usage/main.go) showing how to do something useful and then exit.
* [Daemon service example](./examples/02_daemon_service/main.go) showing how to launch background services.

## Quick Start

1. Define an example service object.
    ```go
    // MyService performs some crucial tasks.
    type MyService struct{}

    // SayHello outputs a friendly greeting.
    func (s *MyService) SayHello(name string) {
        log.Println("Hello,", name)
    }
   ```
2. Define a service factory.
   ```go
   func NewMyService() *MyService {
      return new(MyService)
   }
   ```
3. Register service factories in the container.
   ```go
   container, err := gontainer.New(
      // Define MyService factory in the container.
      gontainer.NewFactory(NewMyService),
   
      // Here we can define another services depending on `*MyService`.
      // All dependencies are declared using factory function args.
      gontainer.NewFactory(func(service *MyService) {
         service.SayHello("Username")
      }),
   )
   if err != nil {
      log.Fatalf("Failed to init service container: %s", err)
   }
   ```
5. Start the container and launch all factories.
   ```go
   if err := container.Start(); err != nil {
      log.Fatalf("Failed to start service container: %s", err)
   }
   ```
   
6. Alternatively to eager start with a `Start()` call it is possible to use `Resolver` or `Invoker` service. It will spawn only explicitly requested services. 
   ```go
   var MyService myService
   if err := container.Resolver().Resolve(&MyService); err != nil {
       log.Fatalf("Failed to resolve MyService dependency: %s", err)
   }
   myServise.DoSomething()
   ```
   or
   ```go
   if err := container.Invoker().Invoke(func(myService &MyService) {
       myServise.DoSomething()
   }); err != nil {
       log.Fatalf("Failed to invoke a function: %s", err)
   }
   ```

## Key Concepts

### Service Factories

The **Service Factory** is a key component of the service container, serving as a mechanism for creating service instances.
A **Service Factory** is essentially a function that accepts another services and returns an instances of services of concrete types or an
interfaces and optionally spawn an error in the last return argument. Using service factory signature, the service container
will resolve and spawn all dependency services using reflection and fail, if there are unresolvable dependencies.

```go
// MyServiceFactory is an example of a service factory.
func MyServiceFactory( /* service dependencies */) *MyService {
   // Initialize service instance.
   return new(MyService)
}

// MyServiceFactory depends on two services.
func MyServiceFactory(svc1 MyService1, svc2 MyService2) MyService {...}

// MyServiceFactory provides two services.
func MyServiceFactory() (MyService1, MyService2) {...}

// MyServiceFactory provides two services and spawn error.
func MyServiceFactory() (MyService1, MyService2, error) {...}

// MyServiceFactory provides no services an error.
func MyServiceFactory() error {...}

// MyServiceFactory provides nothing. Sic!
func MyServiceFactory() {...}
```

The factory function's role is to perform any necessary initializations and return a fully-configured service instance
to the container.

There are several predefined by container service types that may be used as a dependencies in the factory arguments.

1. The `context.Context` service provides the per-service context, inherited from the background context.
   This context is cancelled right before the service's `Close()` call and intended to be used with service functions.
1. The `gontainer.Events` service provides the events broker. It can be used to send and receive events
   inside service container between services or outside from the client code.
1. The `gontainer.Resolver` service provides a service to resolve dependencies dynamically.
1. The `gontainer.Invoker` service provides a service to invoke functions dynamically.

In addition, there are several generic types allowing to declare dependencies on a type.

#### Optional Dependency Declaration

The `gontainer.Optional[T]` type allows to depend on a type that may or may not be present.
For example, when developing a factory that uses a telemetry service, this type can be used if the service
is registered in the container. If the telemetry service is not registered, this is not considered an error,
and telemetry initialization can be skipped in the factory.

```go
// MyServiceFactory optionally depends on the service.
func MyServiceFactory(optService1 gontainer.Optional[MyService1]) {
    // Get will not produce any error if the MyService1 is not registered
    // in the container: it will return zero value for the service type.
    service := optSvc1.Get()
}
```

#### Multiple Dependencies Declaration

The `gontainer.Multiple[T]` type allows retrieval of all services that match the type `T`. This feature is 
intended to be used when providing concrete service types from multiple factories (e.g., struct pointers like
`*passwordauth.Provider`, `*tokenauth.Provider`) and depending on them as services `Multiple[IProvider]`.
In this case, the length of the `services` slice could be in the range `[0, N]`.

If a concrete non-interface type is specified in `T`, then the length of the slice could only be `[0, 1]` 
because the container restricts the registration of the same non-interface type more than once.

```go
// MyServiceFactory depends on the all implementing interface types.
func MyServiceFactory(servicesSlice gontainer.Multiple[MyInterface]) {
    for _, service := range servicesSlice {

    }
}
```

### Services

A service is a functional component of the application, created and managed by a Service Factory. 
The lifetime of a service is tied to the lifetime of the entire container.

A service may optionally implement a `Close() error` or just `Close()` method, which is called when the container is shutting down.
The `Close` call is synchronous: remaining services will not be closed until this method returns.

```go
// MyService defines example service.
type MyService struct {}

// SayHello is service domain method example. 
func (s *MyService) SayHello(name string) {
    fmt.Println("Hello,", name)
}

// Close is an optional method called from container's Close(). 
func (s *MyService) Close() error {
   // Synchronous cleanup logic here.
   return nil
}
```

### Service Functions

The **Service Function** is a specialized form of service optimized for simpler tasks. Instead of returning a concrete
type object or an interface, the service factory returns a function that conforms to `func() error` type.

The function serves two primary roles:

- It encapsulates the behavior to execute when the container starts asynchronously to the `Start()` method.
- It returns an error, which is treated as if it were returned by a conventional `Close()` method.

```go
// MyServiceFactory is an example of a service function usage.
func MyServiceFactory(ctx context.Context) func () error {
    return func () error {
        // Await its order in container close.
        <-ctx.Done()
      
        // Return nil from the `service.Close()`.
        return nil
    }
}
```

In this design, the factory function is responsible for receiving the context. This context is canceled when the service
needs to close, allowing the function to terminate gracefully.

Errors returned by the function are processed as if they were errors returned by a standard `Close()` method to the container.
This means the container will synchronously wait until a service function returns an error or nil before closing the next services.

### Events Broker

The **Events Broker** is an additional part of the service container architecture. It facilitates communication between services
without them having to be directly aware of each other. The Events Broker works on a publisher-subscriber model, enabling services
to publish events to, and subscribe to events from, a centralized broker.

This mechanism allows services to remain decoupled while still being able to interact through a centralized medium.
In particular, the `gontainer.Events` service provides an interface to the events broker and can be injected as a dependency in any service factory.

#### Triggering Events

To trigger an event, use the `Trigger()` method. Create an event using `NewEvent()` and pass the necessary arguments:

```go
events.Trigger(gontainer.NewEvent("Event1", event, arguments, here))
```

#### Subscribing to Events

To subscribe to an event, use the `Subscribe()` method. Two types of handler functions are supported:

- A function that accepts a variable number of any-typed arguments:
  ```go
  events.Subscribe("Event1", func(args ...any) {
      // Handle the event with args slice.
  })
  ```
- A function that accepts concrete argument types:
  ```go
  ev.Subscribe("Event1", func(x string, y int, z bool) {
      // Handle the event with specific args.
  })
  ```
  - The **number of arguments** in the event and the handler can differ because handlers are designed to be flexible and can process varying numbers and types of arguments, allowing for greater versatility in handling different event scenarios.
  - The **types of arguments** in the event and the handler must be assignable. Otherwise, an error will be returned from a `Trigger()` call.
  
Every handler function could return an `error` which will be joined and returned from `Trigger()` call.

### Container Interface

```go
// Container defines service container interface.
type Container interface {
    // Start initializes every service in the container.
    Start() error

    // Close closes service container with all services.
    // Blocks invocation until the container is closed.
    Close() error

    // Done is closing after closing of all services.
    Done() <-chan struct{}

    // Factories returns all defined factories.
    Factories() []*Factory

    // Services returns all spawned services.
    Services() []any

    // Events returns events broker instance.
    Events() Events

    // Resolver returns service resolver instance.
    // If container is not started, only requested services
    // will be spawned on `resolver.Resolve(...)` call.
    Resolver() Resolver

    // Invoker returns function invoker instance.
    // If container is not started, only requested services
    // will be spawned to invoke the func.
    Invoker() Invoker
}
```

### Container Events

The service container emits several events during its lifecycle:

| Event               | Description                                                                   |
|---------------------|-------------------------------------------------------------------------------|
| `ContainerStarting` | Emitted when the container's start method is invoked.                         |
| `ContainerStarted`  | Emitted when the container's start method has completed.                      |
| `ContainerClosing`  | Emitted when the container's close method is invoked.                         |
| `ContainerClosed`   | Emitted when the container's close method has completed.                      |
| `UnhandledPanic`    | Emitted when a panic occurs during container initialization, start, or close. |

### Container Errors

The service container may return the following errors, which can be checked using `errors.Is`:

| Error                       | Description                                                                           |
|-----------------------------|---------------------------------------------------------------------------------------|
| `ErrFactoryReturnedError`   | Occurs when the factory function returns an error during invocation.                  |
| `ErrServiceNotResolved`     | Occurs when resolving a service fails due to an unregistered service type.            |
| `ErrServiceDuplicated`      | Occurs when a service type duplicate found during the initialization procedure.       |
| `ErrCircularDependency`     | Occurs when a circular dependency found during the initialization procedure.          |
| `ErrHandlerArgTypeMismatch` | Occurs when an event handler's arguments do not match the event's expected arguments. |


gontainer

A YAML-based Dependency Injection container for GO. It supports dependencies' scopes, and auto-detection of circular dependencies. Gontainer is concurrent-safe.

[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
[![Go Reference](https://pkg.go.dev/badge/github.com/gontainer/gontainer.svg)](https://pkg.go.dev/github.com/gontainer/gontainer)
[![Build Status](https://github.com/gontainer/gontainer/actions/workflows/tests.yaml/badge.svg?branch=main)](https://github.com/gontainer/gontainer/actions?query=workflow%3ATests)
[![Coverage Status](https://coveralls.io/repos/github/gontainer/gontainer/badge.svg?branch=main)](https://coveralls.io/github/gontainer/gontainer?branch=main)
[![Go Report Card](https://goreportcard.com/badge/github.com/gontainer/gontainer)](https://goreportcard.com/report/github.com/gontainer/gontainer)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=gontainer_gontainer&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=gontainer_gontainer)

# Gontainer

A Dependency Injection container for GO. Gontainer is concurrent-safe, supports scopes and offers hot swapping.

If the code generation is not for you, [see](https://github.com/gontainer/gontainer-helpers/blob/main/container/README.md) how to manually build a container.

Using the bootstrapping technique, Gontainer uses itself to compile its dependencies.
1. [Configuration](internal/gontainer)
2. [Usage](internal/cmd/runner_builder.go)

## Docs

1. Documentation
   1. [Version](docs/VERSION.md)
   2. [Meta](docs/META.md)
   3. [Parameters](docs/PARAMETERS.md)
   4. [Services](docs/SERVICES.md)
   5. [Decorators](docs/DECORATORS.md)
2. [Interface](docs/INTERFACE.md)

## Installation

**homebrew**

```bash
brew install gontainer/homebrew-tap/gontainer
```

**go install**

```bash
go install github.com/gontainer/gontainer@latest
```

**Manual compilation**

```bash
git clone git@github.com:gontainer/gontainer.git
cd gontainer
GONTAINER_BINARY=/usr/local/bin/gontainer make
```

## TL;DR

**Describe dependencies**

Either YAML or GO

<details>
  <summary>YAML</summary>

File `gontainer/gontainer.yaml`:

```yaml
meta:
  pkg: "gontainer"
  constructor: "New"
  imports:
     mypkg: "github.com/user/repo/pkg"

parameters:
  appPort: '%envInt("APP_PORT", 9090)%' # get the port from the ENV variable if it exists, otherwise, use the default one

services:
  endpointHelloWorld:
    constructor: "mypkg.NewHelloWorld"

  serveMux:
    constructor: '"net/http".NewServeMux'                       # serveMux := http.NewServerMux()
    calls:                                                      #
      - [ "Handle", [ "/hello-world", "@endpointHelloWorld" ] ] # serveMux.Handle("/hello-world", gontainer.Get("endpointHelloWorld"))

  server:
    getter: "GetServer"           # func (*gontainer) GetServer() (*http.Server, error) { ... }
    must_getter: true             # func (*gontainer) MustGetServer() *http.Server { ... }
    type: '*"net/http".Server'    # 
    value: '&"net/http".Server{}' # server := &http.Server{}
    fields:                       #
      Addr: ":%appPort%"          # server.Addr = ":" + gontainer.GetParam("appPort")
      Handler: "@serveMux"        # server.Handler = gontainer.Get("serverMux")
```

**Compile it**

```bash
gontainer build -i gontainer/gontainer.yaml -o gontainer/container.go

# it can read multiple configuration files, e.g.
# gontainer build -i gontainer/gontainer.yaml -i gontainer/dev/\*.yaml -o gontainer/container.go
```
</details>

<details>
<summary>GO</summary>

File `gontainer/gontainer.go`:

```go
package gontainer

import (
   "net/http"
   "os"

   "github.com/gontainer/gontainer-helpers/v3/container"
   "github.com/user/repo/pkg"
)

type gontainer struct {
   *container.SuperContainer
}

func (g *gontainer) MustGetServer() *http.Server {
   raw, err := g.Get("server")
   if err != nil {
      panic(err)
   }
   return raw.(*http.Server)
}

func New() *gontainer {
   sc := &gontainer{
      SuperContainer: container.NewSuperContainer(),
   }

   sc.OverrideParam("serverAddr", container.NewDependencyProvider(func() string {
      if v, ok := os.LookupEnv("APP_PORT"); ok {
         return ":" + v
      }
      return ":9090"
   }))

   endpointHelloWorld := container.NewService()
   endpointHelloWorld.SetConstructor(pkg.NewHelloWorld)
   sc.OverrideService("endpointHelloWorld", endpointHelloWorld)

   serveMux := container.NewService()
   serveMux.SetConstructor(http.NewServeMux)
   serveMux.AppendCall(
      "Handle",
      container.NewDependencyValue("/hello-world"),
      container.NewDependencyService("endpointHelloWorld"),
   )
   sc.OverrideService("serveMux", serveMux)

   server := container.NewService()
   server.SetConstructor(func() *http.Server {
      return &http.Server{}
   })
   server.SetField("Addr", container.NewDependencyProvider(func() (interface{}, error) {
      return sc.GetParam("serverAddr")
   }))
   server.SetField("Handler", container.NewDependencyService("serveMux"))
   sc.OverrideService("server", server)

   return sc
}
```
</details>

**Voilà!**

File `main.go`:

```go
package main

import (
	"github.com/user/repo/gontainer"
)

func main() {
	c := gontainer.New()
	s := c.MustGetServer()

	err := s.ListenAndServe()
	if err != nil {
		panic(err)
	}
}
```


gontainer/gontainer

A generics based dependency injection framework for Go.

A type safe, reflective framework for libraries, tests, http endpoints, and service startup.

# nject - dependency injection 

[![Stability: Active](https://masterminds.github.io/stability/active.svg)](https://masterminds.github.io/stability/active.html)
[![GoDoc](https://godoc.org/github.com/muir/nject?status.png)](https://pkg.go.dev/github.com/muir/nject)
![unit tests](https://github.com/muir/nject/actions/workflows/go.yml/badge.svg)
[![report card](https://goreportcard.com/badge/github.com/muir/nject)](https://goreportcard.com/report/github.com/muir/nject)
[![codecov](https://codecov.io/gh/muir/nject/branch/main/graph/badge.svg)](https://codecov.io/gh/muir/nject)

Install:

	go get github.com/muir/nject

---

This package provides type-safe dependency injection without requiring
users to do type assertions.

Dependencies are injected via a call chain: list functions to be called
that take and return various parameters.  The functions will be called
in order using the return values from earlier functions as parameters
for later functions.  Only the functions that are needed to be called in
order to be able to call the last function in the chain are invoked.  Then
the last function in the chain is called.

Parameters are identified by their types.  To have two different `int`
parameters, define custom types.

Type safety is checked before any functions are called.

Functions whose outputs are not used are not called.  Functions may
"wrap" the rest of the list so that they can choose to invoke the
remaining list zero or more times.

Chains may be pre-compiled into closures so that they have very little
runtime penealty.

### example

	func example() {
		// Sequences can be reused.
		providerChain := Sequence("example sequence",
			// Constants can be injected.
			"a literal string value",
			// This function will be run if something downstream needs an int
			func(s string) int {
				return len(s)
			})
		Run("example",
			providerChain,
			// The last function in the list is always run.  This one needs
			// and int and a string.  The string can come from the constant
			// and the int from the function in the provider chain.
			func(i int, s string) {
				fmt.Println(i, len(s))
			})
	}

### Main APIs

Nject provides two main APIs: Bind() and Run().

Bind() is used when performance matters: given a chain of providers,
it will write two functions: one to initialize the chain and another to
invoke it.  As much as possible, all dependency injection work is done
at the time of binding and initialization so that the invoke function
operates with very little overhead.  The chain is initialized when the
initialize function is called.  The chain is run when the invoke function
is called.  Bind() does not run the chain.

Run() is used when ad-hoc injection is desired and performance is not
critical.  Run is appropriate when starting servers and running tests.
It is not recommended for HTTP endpoint handlers.  Run exectes the
chain immediately.

### Identified by type

Rather than naming values, inputs and outputs are identified by their types.  
Since Go makes it easy to create new types, this turns out to be quite easy to use.

### Types of providers

Multiple types of providers are supported.

#### Literal values

You can provide a constant if you have one.

#### Injectors

Regular functions can provide values.  Injectors will be called at
initialization time when they're marked as cacheable or at invocation
time if they're not.

Injectors can be memoized.

Injectors can return a special error type that stops the chain.

Injectors can use data produced by earlier injectors simply by having
a function parameter that matches the type of a return value of an
earlier injector.

Injector chains can be collapsed to become a single injector -- this
allows the chain to branch out in a tree structure so that it can 
generate multiple copies of the same type.

Injectors can be automatically reordered so that outputs are generated
before they're required as inputs.

#### Wrappers (aka Middleware)

Wrappers are special functions that are responsible for invoking
the part of the injection chain that comes after themselves.  They
do this by calling an `inner()` function that the nject framework
defines for them.

Any arguments to the inner() function are injected as values available
further down the chain.  Any return values from inner() must be returned
by the final function in the chain or from another wrapper further down
the chain.

### Composition

Collections of injectors may be composed by including them in
other collections.

## Debugging injector chains

If you chain successfully binds but does not do what you expect, add
something into your chain that receives the `nject.Debugging` type:

	func(d *nject.Debugging) {
		fmt.Println("Injectors included\n", d.Included)
	}

If you chain does not bind, then `Debugging` won't help.
Injection chain errors attempt to be self-explanatory, but sometimes that's not enough.

If you're building your injection sequence dynamically, it may be useful to print
the injection chain.  It has a `String()` method.

If you think that the issue is with nject, then open an issue with the reproduce information
that is available as part of the debugging (`Debugging.Reproduce`) or available by calling
`nject.DetailedError(err)` on the error returned from `Bind()` or `Run()`.

# Uses

Nject has been successfully used for:

- Test frameworks so that test authors specify the test dependencies with the types
  injected into a function that runs a test.  Using wrappers or `t.Clanup()` in the
  injection chain allows test writers to skip all or most test cleanup.
- Endpoint handlers.  Nject makes middleware easier to write.
- Server startup.

# Related packages

The following use nject to provide nicer APIs:

- [nape](https://github.com/muir/nape): dependency injection wrappers for binding http endpoint handlers using gorilla/mux
- [nchi](https://github.com/muir/nchi): http router on top of [httprouter](https://pkg.go.dev/github.com/julienschmidt/httprouter) with a go-chi-like API
- [nfigure](https://github.com/muir/nfigure): configuration and flag processing
- [npoint](https://github.com/muir/npoint): dependency injection wrappers for binding http endpoint handlers
- [nserve](https://github.com/muir/nserve): injection chains for for starting and stopping servers
- [ntest](https://github.com/memsql/ntest): support functions and hints for using nject to write tests
- [nvalid](https://github.com/muir/nvalid): enforce that http endpoints conform to Swagger definitions
- [nvelope](https://github.com/muir/nvelope): injection chains for building endpoints

### Development status

The core of nject is stable and reliable.  New features have tests, but may not have
enough production use to be reliable.

This repo represents continued development of Blue Owl's 
[nject](https://github.com/BlueOwlOpenSource/nject) base.

Nject will follow strict semver behavior except (1) things noted as experimental;
and (2) releases that are less than 10 days old may have corrections applied that
are not strictly backwards compatible with the recent release (for example, 1.0.0
accidentally exported a type that should have remained private).

Prior to release 0.2.0, nject was bundled with other packages.  Those
other packages are now in their own repos: 
[npoint](https://github.com/muir/npoint),
[nserve](https://github.com/muir/nserve), and
[nvelope](https://github.com/muir/nvelope).  Additionally, npoint
was split apart so that the gorilla dependency is separate and is in
[nape](https://github.com/muir/nape).

Please create issues for any suggested features, improvements, or problems you run into.



nject

Dependency injection using Generics and reflection.

[![Go Version][gover-img]][gover] [![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov] [![GoReport][rpt-img]][rpt]

# Dependency injection for Go 1.18+ using Generics and reflection

## Functionalities

- Automatically wiring/injecting objects on creation.
- Easy to use (see Usage section).
- `Shared mode` by default that creates only one instance for a type (this option is configurable).
- Ability to overwrite objects of specific types on building which is convenient for unit testing.
- No code generation.

## Installation

```shell
go get github.com/tiendc/autowire
```

## Usage

### General usage

```go
    // Suppose you have ServiceA and a creator function
    type ServiceA interface {}
    func NewServiceA(srvB ServiceB, repoX RepoX) ServiceA {
        return <ServiceA-instance>
    }

    // and ServiceB
    type ServiceB interface {}
    func NewServiceB(ctx context.Context, repoX RepoX, repoY RepoY) (ServiceB, error) {
        return <ServiceB-instance>, nil
    }

    // and RepoX
    type RepoX interface {}
    func NewRepoX(s3Client S3Client) (RepoX, error) {
        return <RepoX-instance>, nil
    }

    // and RepoY
    type RepoY interface {}
    func NewRepoY(redisClient RedisClient) RepoY {
        return <RepoY-instance>
    }

    // and a struct provider
    type ProviderStruct struct {
        RedisClient RedisClient
        S3Client    S3Client
    }

    var (
        // init the struct value
        providerStruct = &ProviderStruct{...}

        // create a container with passing providers
        container = MustNewContainer([]any{
            // Service providers
            NewServiceA,
            NewServiceB,
            // Repo providers
            NewRepoX,
            NewRepoY,
            // Struct provider (must be a pointer)
            providerStruct,
        })
    )

    func main() {
        // Update some values of the struct provider
        providerStruct.RedisClient = newRedisClient()
        providerStruct.S3Client = newS3Client()

        // Create ServiceA
        serviceA, err := autowire.BuildWithCtx[ServiceA](ctx, container)
        // Create RepoX
        repoX, err := autowire.Build[RepoX](container)
    }
```

### Non-shared mode

```go
    // Set sharedMode when create a container
    container = MustNewContainer([]any{
        // your providers
    }, SetSharedMode(false))

    // Activate non-shared mode inline for a specific build only
    serviceA, err := Build[ServiceA](container, NonSharedMode())
```

### Overwrite values of specific types

This is convenient in unit testing to overwrite specific types only.

```go
    // In unit testing, you may want to overwrite some `repos` and `clients` with fake instances.
    // NOTE: you may need to use `non-shared mode` to make sure cached objects are not used.
    serviceA, err := Build[ServiceA](container, NonSharedMode(),
            ProviderOverwrite[RepoX](fakeRepoX),
            ProviderOverwrite[RepoY](fakeRepoY))
    serviceA, err := Build[ServiceA](container, NonSharedMode(),
            ProviderOverwrite[RedisClient](fakeRedisClient),
            ProviderOverwrite[S3Client](fakeS3Client))
```

### Reclaim memory after use

Typically, dependency injection is only used at the initialization phase of a program.
However, it can take some space in memory which will become wasted after the phase.
Use the below trick to reclaim the memory taken by the autowire variables.

```go
    var (
        // create a global container
        container = MustNewContainer(...)
    )

    func autowireCleanUp() {
        // Assign nil to allow the garbage collector to reclaim the taken memory
        container = nil
    }

    func main() {
        // Initialization phase
        // Create services and use them
        serviceA, _ := autowire.Build[ServiceA](container)
        serviceB, _ := autowire.Build[ServiceB](container)

        // Clean up the usage, make sure you won't use the vars any more
        autowireCleanUp()
    }
```

## Contributing

- You are welcome to make pull requests for new functions and bug fixes.

## License

- [MIT License](LICENSE)

[doc-img]: https://pkg.go.dev/badge/github.com/tiendc/autowire
[doc]: https://pkg.go.dev/github.com/tiendc/autowire
[gover-img]: https://img.shields.io/badge/Go-%3E%3D%201.18-blue
[gover]: https://img.shields.io/badge/Go-%3E%3D%201.18-blue
[ci-img]: https://github.com/tiendc/autowire/actions/workflows/go.yml/badge.svg
[ci]: https://github.com/tiendc/autowire/actions/workflows/go.yml
[cov-img]: https://codecov.io/gh/tiendc/autowire/branch/main/graph/badge.svg
[cov]: https://codecov.io/gh/tiendc/autowire
[rpt-img]: https://goreportcard.com/badge/github.com/tiendc/autowire
[rpt]: https://goreportcard.com/report/github.com/tiendc/autowire


autowire

A dependency injection container for go programming language.

# DI

[![Documentation](https://img.shields.io/badge/godoc-reference-blue.svg?style=for-the-badge&logo=go)](https://pkg.go.dev/github.com/defval/di)
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/defval/di?logo=semver&style=for-the-badge)](https://github.com/defval/di/releases/latest)
[![GitHub Workflow Status (with branch)](https://img.shields.io/github/actions/workflow/status/defval/di/go.yml?branch=master&logo=github-actions&style=for-the-badge)](https://github.com/defval/di/actions/workflows/go.yml)
[![Go Report Card](https://img.shields.io/badge/go%20report-A%2B-green?style=for-the-badge)](https://goreportcard.com/report/github.com/defval/di)
[![Codecov](https://img.shields.io/codecov/c/github/defval/di?logo=codecov&style=for-the-badge)](https://codecov.io/gh/defval/di)

**DI** is a dependency injection library for the Go programming language.

Dependency injection is a form of inversion of control that increases modularity and extensibility in your programs.
This library helps you organize responsibilities in your codebase and makes it easy to combine low-level implementations
into high-level behavior without boilerplate.

## Features

- Intuitive auto wiring
- Interface implementations
- Constructor injection
- Optional injection
- Field injection
- Lazy-loading
- Tagging
- Grouping
- Iteration
- Decoration
- Cleanup
- Container Chaining / Scopes

## Installation

```shell
go get github.com/defval/di
```

## Documentation

You can use the standard [pkg.go.dev](https://pkg.go.dev/github.com/defval/di) and inline code comments. If you are new
to auto-wiring libraries such as [google/wire](https://github.com/google/wire)
or [uber-go/dig](https://github.com/uber-go/dig), start with the [tutorial](./docs/tutorial.md).

### Essential Reading

- [Tutorial](./docs/tutorial.md)
- [Examples](./_examples)
- [Advanced Features](./docs/advanced.md)

## Example Usage

```go
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"

	"github.com/defval/di"
)

func main() {
	di.SetTracer(&di.StdTracer{})
	// create container
	c, err := di.New(
		di.Provide(NewContext),  // provide application context
		di.Provide(NewServer),   // provide http server
		di.Provide(NewServeMux), // provide http serve mux
		// controllers as []Controller group
		di.Provide(NewOrderController, di.As(new(Controller))),
		di.Provide(NewUserController, di.As(new(Controller))),
	)
	// handle container errors
	if err != nil {
		log.Fatal(err)
	}
	// invoke function
	if err := c.Invoke(StartServer); err != nil {
		log.Fatal(err)
	}
}
```

Full code available [here](./_examples/tutorial/main.go).

## Questions

If you have any questions, feel free to create an issue.


A reflection based dependency injection toolkit for Go.

# :hammer_and_pick: dig [![GoDoc][doc-img]][doc] [![GitHub release][release-img]][release] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov] [![Go Report Card][report-card-img]][report-card]

A reflection based dependency injection toolkit for Go.

### Good for:

* Powering an application framework, e.g. [Fx](https://github.com/uber-go/fx).
* Resolving the object graph during process startup.

### Bad for:

* Using in place of an application framework, e.g. [Fx](https://github.com/uber-go/fx).
* Resolving dependencies after the process has already started.
* Exposing to user-land code as a [Service Locator](https://martinfowler.com/articles/injection.html#UsingAServiceLocator).

## Installation

We recommend consuming [SemVer](http://semver.org/) major version `1` using
your dependency manager of choice.

```
$ glide get 'go.uber.org/dig#^1'
$ dep ensure -add "go.uber.org/dig@v1"
$ go get 'go.uber.org/dig@v1'
```

## Stability

This library is `v1` and follows [SemVer](http://semver.org/) strictly.

No breaking changes will be made to exported APIs before `v2.0.0`.

[doc-img]: http://img.shields.io/badge/GoDoc-Reference-blue.svg
[doc]: https://godoc.org/go.uber.org/dig

[release-img]: https://img.shields.io/github/release/uber-go/dig.svg
[release]: https://github.com/uber-go/dig/releases

[ci-img]: https://github.com/uber-go/dig/actions/workflows/go.yml/badge.svg
[ci]: https://github.com/uber-go/dig/actions/workflows/go.yml

[cov-img]: https://codecov.io/gh/uber-go/dig/branch/master/graph/badge.svg
[cov]: https://codecov.io/gh/uber-go/dig/branch/master

[report-card-img]: https://goreportcard.com/badge/github.com/uber-go/dig
[report-card]: https://goreportcard.com/report/github.com/uber-go/dig

## Stargazers over time

[![Stargazers over time](https://starchart.cc/uber-go/dig.svg)](https://starchart.cc/uber-go/dig)



A dependency injection toolkit for Go, based on Guice.

# Dingo

[![Go Report Card](https://goreportcard.com/badge/flamingo.me/dingo)](https://goreportcard.com/report/flamingo.me/dingo) [![GoDoc](https://godoc.org/flamingo.me/dingo?status.svg)](https://godoc.org/flamingo.me/dingo) [![Tests](https://github.com/i-love-flamingo/dingo/workflows/Tests/badge.svg?branch=master)](https://github.com/i-love-flamingo/dingo/actions?query=branch%3Amaster+workflow%3ATests)

Dependency injection for go

## Hello Dingo

Dingo works very similar to [Guice](https://github.com/google/guice/wiki/GettingStarted)

Basically one binds implementations/factories to interfaces, which are then resolved by Dingo.

Given that Dingo's idea is based on Guice we use similar examples in this documentation:

The following example shows a BillingService with two injected dependencies. Please note
that Go's nature does not allow constructors, and does not allow decorations/annotations
beside struct-tags, thus, we only use struct tags (and later arguments for providers).

Also, Go does not have a way to reference types (like Java's `Something.class`) we use either pointers
or `nil` and cast it to a pointer to the interface we want to specify: `(*Something)(nil)`.
Dingo then knows how to dereference it properly and derive the correct type `Something`.
This is not necessary for structs, where we can just use the null value via `Something{}`.

See the example folder for a complete example.

```go
package example

type BillingService struct {
	processor CreditCardProcessor
	transactionLog TransactionLog
}

func (billingservice *BillingService) Inject(processor CreditCardProcessor, transactionLog TransactionLog) {
	billingservice.processor = processor
	billingservice.transactionLog = transactionLog
}

func (billingservice *BillingService) ChargeOrder(order PizzaOrder, creditCard CreditCard) Receipt {
	// ...
}
```

We want the BillingService to get certain dependencies, and configure this in a `BillingModule`
which implements `dingo.Module`:

```go
package example

type BillingModule struct {}

func (module *BillingModule) Configure(injector *dingo.Injector) {
	// This tells Dingo that whenever it sees a dependency on a TransactionLog, 
	// it should satisfy the dependency using a DatabaseTransactionLog. 
	injector.Bind(new(TransactionLog)).To(DatabaseTransactionLog{})

	// Similarly, this binding tells Dingo that when CreditCardProcessor is used in
	// a dependency, that should be satisfied with a PaypalCreditCardProcessor. 
	injector.Bind(new(CreditCardProcessor)).To(PaypalCreditCardProcessor{})
}
```

## Requesting injection

Every instance that is created through the container can use injection. 

Dingo supports two ways of requesting dependencies that should be injected:

* usage of struct tags to allow structs to request injection into fields. This should be used for public fields.
* implement a public Inject(...) method to request injections of private fields. Dingo calls this method automatically and passes the requested injections.

For every requested injection (unless an exception applies) Dingo does the following:

- Is there a binding? If so: delegate to the binding
    - Is the binding in a certain scope (Singleton)? If so, delegate to scope (might result in a new loop)
    - Binding is bound to an instance: inject instance
    - Binding is bound to a provider: call provider
    - Binding is bound to a type: request injection of this type (might return in a new loop to resolve the binding)
- No binding? Try to create (only possible for concrete types, not interfaces or functions)


*Example:*
Here is another example using the Inject method for private fields
```go
package example

type MyBillingService struct {
	processor CreditCardProcessor
	accountId string
}

func (m *MyBillingService) Inject(
	processor CreditCardProcessor,
	config *struct {
		AccountId  string `inject:"config:myModule.myBillingService.accountId"`
	},
) {
	m.processor = CreditCardProcessor
	m.accountId = config.AccountId
}
```

### Usage of Providers

Dingo allows to request the injection of provider instead of instances.
A "Provider" for dingo is a function that return a new Instance of a certain type.

```go
package example

type pizzaProvider func() Pizza

func (s *Service) Inject(provider pizzaProvider) {
	s.provider = provider
}
```

If there is no concrete binding to the type `func() Pizza`, then instead of constructing one `Pizza` instance
Dingo will create a new function which, on every call, will return a new instance of `Pizza`.

The type must be of `func() T`, a function without any arguments which returns a type, which again has a binding.

This allows to lazily create new objects whenever needed, instead of requesting the Dingo injector itself.


You can use Providers and call them to always get a new instance.
Dingo will provide you with an automatic implementation of a Provider if you did not bind a specific one.

*Use a Provider instead of requesting the Type directly when*:

* for lazy binding 
* if you need new instances on demand
* In general, it is best practice using a Provider for everything that has a state that might be changed. This way you will avoid undesired side effects. That is especially important for dependencies in objects that are shared between requests - for example a controller!

*Example 1:*
This is the only code required to request a Provider as a dependency:
```go
MyStructProvider func() *MyStruct
MyStruct         struct {}

MyService struct {
	MyStructProvider MyStructProvider `inject:""`
}

```

*Example 2:*
```go
package example

func createSomething(thing SomethingElse) Something{
	return &MySomething{somethingElse: thing}
}

injector.Bind(new(Something)).ToProvider(createSomething)

type somethingProvider func() Something

type service struct {
	provider somethingProvider
}
```

will essentially call `createSomething(new(SomethingElse))` everytime `SomethingProvider()` is called,
passing the resulting instance through the injection to finalize uninjected fields. 


### Optional injection

An injection struct tag can be marked as optional by adding the suffix `,optional` to it.
This means that for interfaces, slices, pointers etc where dingo can not resolve a concrete type, the `nil`-type is injected.

You can check via `if my.Prop == nil` if this is nil.

## Bindings

Dingo uses bindings to express dependencies resolutions, and will panic if there is more than one
binding for a type with the same name (or unnamed), unless you use multibindings.

### Bind

Bind creates a new binding, and tells Dingo how to resolve the type when it encounters a request for this type.
Bindings can chain, but need to implement the correct interfaces.

```go
injector.Bind(new(Something))
```

### AnnotatedWith

By default a binding is unnamed, and thus requested with the `inject:""` tag.

However, you can name bindings to have more concrete kinds of it. Using `AnnotatedWith` you can specify the name:

```go
injector.Bind((*Something)(nil)).AnnotatedWith("myAnnotation")
```

It is requested via the `inject:"myAnnotation"` tag. For example:

```go
struct {
	PaypalPaymentProcessor PaymentProcessor `inject:"Paypal"`
}
```

### To

To defines which type should be created when this type is requested.
This can be an Interface which implements to one it is bound to, or a concrete type.
The type is then created via `reflect.New`.

```go
injector.Bind(new(Something)).To(MyType{})
```

### ToProvider

If you want a factory to create your types then you rather use `ToProvider` instead of `To`.

`ToProvider` is a function which returns an instance (which again will go through Dingo to fill dependencies).

Also, the provider can request arguments from Dingo which are necessary to construct the bounded type.
If you need named arguments (e.g. a string instance annotated with a configuration value) you need to request
an instance of an object with these annotations, because Go does not allow to pass any meta-information on function
arguments.

```go
func MyTypeProvider(se SomethingElse) *MyType {
	return &MyType{
		Special: se.DoSomething(),
	}
}

injector.Bind(new(Something)).ToProvider(MyTypeProvider)
```

This example will make Dingo call `MyTypeProvider` and pass in an instance of `SomethingElse` as it's first argument,
then take the result of `*MyType` as the value for `Something`.

`ToProvider` takes precedence over `To`.

### ToInstance

For situations where you have one, and only one, concrete instance you can use `ToInstance` to bind
something to the concrete instance. This is not the same as a Singleton!
(Even though the resulting behaviour is very similar.)

```go
var myInstance = new(MyType)
myInstance.Connect(somewhere)
injector.Bind(new(Something)).ToInstance(myInstance)
```

You can also bind an instance it to a struct obviously, not only to interfaces.

`ToInstance` takes precedence over both `To` and `ToProvider`.

### In (Singleton scopes)

If really necessary it is possible to use singletons
``` 
.AsEagerSingleton() binds as a singleton, and loads it when the application is initialized
.In(dingo.Singleton) makes it a global singleton
.In(dingo.ChildSingleton) makes it a singleton limited to the current injector
```

`In` allows us to bind in a scope, making the created instances scoped in a certain way.

Currently, Dingo only allows to bind to `dingo.Singleton` and `dingo.ChildSingleton`.

```go
injector.Bind(new(Something)).In(dingo.Singleton).To(MyType{})
```

#### dingo.Singleton

The `dingo.Singleton` scope makes sure a dependency is only resolved once, and the result is
reused. Because the Singleton needs synchronisation for types over multiple concurrent
goroutines and make sure that a Singleton is only created once, the initial creation
can be costly and also the injection of a Singleton is always taking more resources than creation
of an immutable new object.

The synchronisation is done on multiple levels, a first test tries to find the singleton,
if that is not possible a lock-mechanism via a scoped Mutex takes care of delegating
the concrete creation to one goroutine via a scope+type specific Mutex which then generates
the Singleton and makes it available to other currently waiting injection requests, as
well as future injection requests.

By default, it is advised to not use Singletons whenever possible, and rather use
immutable objects you inject whenever you need them.

#### dingo.ChildSingleton

The ChildSingleton is just another Singleton (actually of the same type), but dingo will create a new one
for every derived child injector.

This allows frameworks like Flamingo to distinguish at a root level between singleton scopes, e.g. for
multi-page setups where we need a wide scope for routers.

Since ChildSingleton is very similar to Singleton you should only use it with care.

#### AsEagerSingleton

Singleton creation is always costly due to synchronisation overhead, therefore
Dingo bindings allow to mark a binding `AsEagerSingleton`.

This makes sure the Singleton is created as soon as possible, before the rest of the Application
runs. `AsEagerSingleton` implies `In(dingo.Singleton)`.

```go
injector.Bind(new(Something)).To(MyType{}).AsEagerSingleton()
```

It is also possible to bind a concrete type without `To`:

```go
injector.Bind(MyType{}).AsEagerSingleton()
```

Binding this type as an eager singleton inject the singleton instance whenever `MyType` is requested. `MyType` is a concrete type (struct) here, so we can use this mechanism to create an instance explicitly before the application is run.

### Override

In rare cases you might have to override an existing binding, which can be done with `Override`:

```go
injector.Override(new(Something), "").To(MyBetterType{})
```

`Override` also returns a binding such as `Bind`, but removes the original binding.

The second argument sets the annotation if you want to override a named binding.

### MultiBindings

MultiBindings provide a way of binding multiple implementations of a type to a type,
making the injection a list.

Essentially this means that multiple modules are able to register for a type, and a user of this
type can request an injection of a slice `[]T` to get a list of all registered bindings.

```go
injector.BindMulti(new(Something)).To(MyType1{})
injector.BindMulti(new(Something)).To(MyType2{})

struct {
	List []Something `inject:""`  // List is a slice of []Something{MyType1{}, MyType2{}}
}
```

MultiBindings are used to allow multiple modules to register for a certain type, such as a list of
encoders, subscribers, etc.

Please note that MultiBindings are not always a clear pattern, as it might hide certain complexity.

Usually it is easier to request some kind of registry in your module, and then register explicitly.


### Bind maps

Similar to Multibindings, but with a key instead of a list
```go
MyService struct {
	Ifaces map[string]Iface `inject:""`
}

injector.BindMap(new(Iface), "impl1").To(IfaceImpl{})
injector.BindMap(new(Iface), "impl2").To(IfaceImpl2{})
```

### Binding basic types

Dingo allows binding values to `int`, `string` etc., such as with any other type.

This can be used to inject configuration values.

Flamingo makes an annotated binding of every configuration value in the form of:

```go
var Configuration map[string]interface{}

for k, v := range Configuration {
	injector.Bind(v).AnnotatedWith("config:" + k).ToInstance(v)
}
```

In this case Dingo learns the actual type of `v` (such as string, bool, int) and provides the annotated injection.

Later this can be used via

```go
struct {
	ConfigParam string `inject:"config:myconfigParam"`
}
```



## Dingo Interception

Dingo allows modules to bind interceptors for interfaces.

Essentially this means that whenever the injection of a certain type is happening,
the interceptor is injected instead with the actual injection injected into the interceptor's
first field. This mechanism can only work for interface interception.

Multiple interceptors stack upon each other.

Interception should be used with care!

```go
func (m *Module) Configure(injector *dingo.Injector) {
	injector.BindInterceptor(new(template.Engine), TplInterceptor{})
	injector.BindInterceptor(new(template.Function), FunctionInterceptor{})
}

type (
	TplInterceptor struct {
		template.Engine
	}

	FunctionInterceptor struct {
		template.Function
	}
)

func (t *TplInterceptor) Render(context web.Context, name string, data interface{}) io.Reader {
	log.Println("Before Rendering", name)
	start := time.Now()
	r := t.Engine.Render(context, name, data)
	log.Println("After Rendering", time.Since(start))
	return r
}

func (f *FunctionInterceptor) Name() string {
	funcname := f.Function.Name()
	log.Println("Function", funcname, "used")
	return funcname
}
```

## Initializing Dingo
At the topmost level the injector is created and used in the following way:

```go
package main

import "flamingo.me/dingo"

func main() {
	injector, err := dingo.NewInjector()
	if err != nil {
		panic(err)
	}

	// The injector can be initialized by modules:
	injector.InitModules(new(BillingModule))

	// Now that we've got the injector, we can build objects.
	// We get a new instance, and cast it accordingly:
	instance, err := injector.GetInstance(new(BillingService))
	if err != nil {
		panic(err)
	}
    billingService := instance.(BillingService) 
	//...
}
```

## Dingo vs. Wire

Recently https://github.com/google/go-cloud/tree/master/wire popped out in the go ecosystem, which seems to be a great choice, also because it supports compile time dependency injection.
However, when Dingo was first introduced wire was not a thing, and wire still lacks features dingo provides. 

https://gocover.io/github.com/i-love-flamingo/dingo

## ModuleFunc

Dingo has a wrapper for `func(*Injector)` called `ModuleFunc`. It is possible to wrap a function with the `ModuleFunc` to become a `Module`.
This is similar to the `http` Packages `HandlerFunc` mechanism and allows to save code and easier set up small projects.


dingo

A dependency injection framework based on Generics.


# do - Dependency Injection

[![tag](https://img.shields.io/github/tag/samber/do.svg)](https://github.com/samber/do/releases)
![Go Version](https://img.shields.io/badge/Go-%3E%3D%201.18-%23007d9c)
[![GoDoc](https://godoc.org/github.com/samber/do?status.svg)](https://pkg.go.dev/github.com/samber/do)
![Build Status](https://github.com/samber/do/actions/workflows/test.yml/badge.svg)
[![Go report](https://goreportcard.com/badge/github.com/samber/do)](https://goreportcard.com/report/github.com/samber/do)
[![Coverage](https://img.shields.io/codecov/c/github/samber/do)](https://codecov.io/gh/samber/do)
[![License](https://img.shields.io/github/license/samber/do)](./LICENSE)

**⚙️ A dependency injection toolkit based on Go 1.18+ Generics.**

This library implements the Dependency Injection design pattern. It may replace the `uber/dig` fantastic package in simple Go projects. `samber/do` uses Go 1.18+ generics and therefore offers a typesafe API.

**See also:**

- [samber/lo](https://github.com/samber/lo): A Lodash-style Go library based on Go 1.18+ Generics
- [samber/mo](https://github.com/samber/mo): Monads based on Go 1.18+ Generics (Option, Result, Either...)

**Why this name?**

I love **short name** for such a utility library. This name is the sum of `DI` and `Go` and no Go package currently uses this name.

**⭕⭕⭕⭕⭕⭕ About v2 ⭕⭕⭕⭕⭕⭕**

Check out the beta now!

```bash
go get -u github.com/samber/do/v2@v2.0.0-beta.7
```

Documentation: https://do.samber.dev/

Please report bugs here: [#45](https://github.com/samber/do/pull/45).

## 💡 Features

- Service registration
- Service invocation
- Service health check
- Service shutdown
- Service lifecycle hooks
- Named or anonymous services
- Eagerly or lazily loaded services
- Dependency graph resolution
- Default injector
- Injector cloning
- Service override
- Lightweight, no dependencies
- No code generation

🚀 Services are loaded in invocation order.

🕵️ Service health can be checked individually or globally. Services implementing `do.Healthcheckable` interface will be called via `do.HealthCheck[type]()` or `injector.HealthCheck()`.

🛑 Services can be shutdowned properly, in back-initialization order. Services implementing `do.Shutdownable` interface will be called via `do.Shutdown[type]()` or `injector.Shutdown()`.

## 🚀 Install

```sh
go get github.com/samber/do@v1
```

This library is v1 and follows SemVer strictly.

No breaking changes will be made to exported APIs before v2.0.0.

This library has no dependencies except the Go std lib.

## 💡 Quick start

You can import `do` using:

```go
import (
    "github.com/samber/do"
)
```

Then instantiate services:

```go
func main() {
    injector := do.New()

    // provides CarService
    do.Provide(injector, NewCarService)

    // provides EngineService
    do.Provide(injector, NewEngineService)

    car := do.MustInvoke[*CarService](injector)
    car.Start()
    // prints "car starting"

    do.HealthCheck[EngineService](injector)
    // returns "engine broken"

    // injector.ShutdownOnSIGTERM()    // will block until receiving sigterm signal
    injector.Shutdown()
    // prints "car stopped"
}
```

Services:

```go
type EngineService interface{}

func NewEngineService(i *do.Injector) (EngineService, error) {
    return &engineServiceImplem{}, nil
}

type engineServiceImplem struct {}

// [Optional] Implements do.Healthcheckable.
func (c *engineServiceImplem) HealthCheck() error {
	return fmt.Errorf("engine broken")
}
```

```go
func NewCarService(i *do.Injector) (*CarService, error) {
    engine := do.MustInvoke[EngineService](i)
    car := CarService{Engine: engine}
    return &car, nil
}

type CarService struct {
	Engine EngineService
}

func (c *CarService) Start() {
	println("car starting")
}

// [Optional] Implements do.Shutdownable.
func (c *CarService) Shutdown() error {
	println("car stopped")
	return nil
}
```

## 🤠 Spec

[GoDoc: https://godoc.org/github.com/samber/do](https://godoc.org/github.com/samber/do)

Injector:

- [do.New](https://pkg.go.dev/github.com/samber/do#New)
- [do.NewWithOpts](https://pkg.go.dev/github.com/samber/do#NewWithOpts)
  - [injector.Clone](https://pkg.go.dev/github.com/samber/do#injector.Clone)
  - [injector.CloneWithOpts](https://pkg.go.dev/github.com/samber/do#injector.CloneWithOpts)
  - [injector.HealthCheck](https://pkg.go.dev/github.com/samber/do#injector.HealthCheck)
  - [injector.Shutdown](https://pkg.go.dev/github.com/samber/do#injector.Shutdown)
  - [injector.ShutdownOnSIGTERM](https://pkg.go.dev/github.com/samber/do#injector.ShutdownOnSIGTERM)
  - [injector.ShutdownOnSignals](https://pkg.go.dev/github.com/samber/do#injector.ShutdownOnSignals)
  - [injector.ListProvidedServices](https://pkg.go.dev/github.com/samber/do#injector.ListProvidedServices)
  - [injector.ListInvokedServices](https://pkg.go.dev/github.com/samber/do#injector.ListInvokedServices)
- [do.HealthCheck](https://pkg.go.dev/github.com/samber/do#HealthCheck)
- [do.HealthCheckNamed](https://pkg.go.dev/github.com/samber/do#HealthCheckNamed)
- [do.Shutdown](https://pkg.go.dev/github.com/samber/do#Shutdown)
- [do.ShutdownNamed](https://pkg.go.dev/github.com/samber/do#ShutdownNamed)
- [do.MustShutdown](https://pkg.go.dev/github.com/samber/do#MustShutdown)
- [do.MustShutdownNamed](https://pkg.go.dev/github.com/samber/do#MustShutdownNamed)

Service registration:

- [do.Provide](https://pkg.go.dev/github.com/samber/do#Provide)
- [do.ProvideNamed](https://pkg.go.dev/github.com/samber/do#ProvideNamed)
- [do.ProvideNamedValue](https://pkg.go.dev/github.com/samber/do#ProvideNamedValue)
- [do.ProvideValue](https://pkg.go.dev/github.com/samber/do#ProvideValue)

Service invocation:

- [do.Invoke](https://pkg.go.dev/github.com/samber/do#Invoke)
- [do.MustInvoke](https://pkg.go.dev/github.com/samber/do#MustInvoke)
- [do.InvokeNamed](https://pkg.go.dev/github.com/samber/do#InvokeNamed)
- [do.MustInvokeNamed](https://pkg.go.dev/github.com/samber/do#MustInvokeNamed)

Service override:

- [do.Override](https://pkg.go.dev/github.com/samber/do#Override)
- [do.OverrideNamed](https://pkg.go.dev/github.com/samber/do#OverrideNamed)
- [do.OverrideNamedValue](https://pkg.go.dev/github.com/samber/do#OverrideNamedValue)
- [do.OverrideValue](https://pkg.go.dev/github.com/samber/do#OverrideValue)

### Injector (DI container)

Build a container for your components. `Injector` is responsible for building services in the right order, and managing service lifecycle.

```go
injector := do.New()
```

Or use `nil` as the default injector:

```go
do.Provide(nil, func (i *Injector) (int, error) {
    return 42, nil
})

service := do.MustInvoke[int](nil)
```

You can check health of services implementing `func HealthCheck() error`.

```go
type DBService struct {
    db *sql.DB
}

func (s *DBService) HealthCheck() error {
    return s.db.Ping()
}

injector := do.New()
do.Provide(injector, ...)
do.Invoke(injector, ...)

statuses := injector.HealthCheck()
// map[string]error{
//   "*DBService": nil,
// }
```

De-initialize all compoments properly. Services implementing `func Shutdown() error` will be called synchronously in back-initialization order.

```go
type DBService struct {
    db *sql.DB
}

func (s *DBService) Shutdown() error {
    return s.db.Close()
}

injector := do.New()
do.Provide(injector, ...)
do.Invoke(injector, ...)

// shutdown all services in reverse order
injector.Shutdown()
```

List services:

```go
type DBService struct {
    db *sql.DB
}

injector := do.New()

do.Provide(injector, ...)
println(do.ListProvidedServices())
// output: []string{"*DBService"}

do.Invoke(injector, ...)
println(do.ListInvokedServices())
// output: []string{"*DBService"}
```

### Service registration

Services can be registered in multiple way:

- with implicit name (struct or interface name)
- with explicit name
- eagerly
- lazily

Anonymous service, loaded lazily:

```go
type DBService struct {
    db *sql.DB
}

do.Provide[DBService](injector, func(i *Injector) (*DBService, error) {
    db, err := sql.Open(...)
    if err != nil {
        return nil, err
    }

    return &DBService{db: db}, nil
})
```

Named service, loaded lazily:

```go
type DBService struct {
    db *sql.DB
}

do.ProvideNamed(injector, "dbconn", func(i *Injector) (*DBService, error) {
    db, err := sql.Open(...)
    if err != nil {
        return nil, err
    }

    return &DBService{db: db}, nil
})
```

Anonymous service, loaded eagerly:

```go
type Config struct {
    uri string
}

do.ProvideValue[Config](injector, Config{uri: "postgres://user:pass@host:5432/db"})
```

Named service, loaded eagerly:

```go
type Config struct {
    uri string
}

do.ProvideNamedValue(injector, "configuration", Config{uri: "postgres://user:pass@host:5432/db"})
```

### Service invocation

Loads anonymous service:

```go
type DBService struct {
    db *sql.DB
}

dbService, err := do.Invoke[DBService](injector)
```

Loads anonymous service or panics if service was not registered:

```go
type DBService struct {
    db *sql.DB
}

dbService := do.MustInvoke[DBService](injector)
```

Loads named service:

```go
config, err := do.InvokeNamed[Config](injector, "configuration")
```

Loads named service or panics if service was not registered:

```go
config := do.MustInvokeNamed[Config](injector, "configuration")
```

### Individual service healthcheck

Check health of anonymous service:

```go
type DBService struct {
    db *sql.DB
}

dbService, err := do.Invoke[DBService](injector)
err = do.HealthCheck[DBService](injector)
```

Check health of named service:

```go
config, err := do.InvokeNamed[Config](injector, "configuration")
err = do.HealthCheckNamed(injector, "configuration")
```

### Individual service shutdown

Unloads anonymous service:

```go
type DBService struct {
    db *sql.DB
}

dbService, err := do.Invoke[DBService](injector)
err = do.Shutdown[DBService](injector)
```

Unloads anonymous service or panics if service was not registered:

```go
type DBService struct {
    db *sql.DB
}

dbService := do.MustInvoke[DBService](injector)
do.MustShutdown[DBService](injector)
```

Unloads named service:

```go
config, err := do.InvokeNamed[Config](injector, "configuration")
err = do.ShutdownNamed(injector, "configuration")
```

Unloads named service or panics if service was not registered:

```go
config := do.MustInvokeNamed[Config](injector, "configuration")
do.MustShutdownNamed(injector, "configuration")
```

### Service override

By default, providing a service twice will panic. Service can be replaced at runtime using `do.Override` helper.

```go
do.Provide[Vehicle](injector, func (i *do.Injector) (Vehicle, error) {
    return &CarImplem{}, nil
})

do.Override[Vehicle](injector, func (i *do.Injector) (Vehicle, error) {
    return &BusImplem{}, nil
})
```

### Hooks

2 lifecycle hooks are available in Injectors:
- After registration
- After shutdown

```go
injector := do.NewWithOpts(&do.InjectorOpts{
    HookAfterRegistration: func(injector *do.Injector, serviceName string) {
        fmt.Printf("Service registered: %s\n", serviceName)
    },
    HookAfterShutdown: func(injector *do.Injector, serviceName string) {
        fmt.Printf("Service stopped: %s\n", serviceName)
    },

    Logf: func(format string, args ...any) {
        log.Printf(format, args...)
    },
})
```

### Cloning injector

Cloned injector have same service registrations as it's parent, but it doesn't share invoked service state.

Clones are useful for unit testing by replacing some services to mocks.

```go
var injector *do.Injector;

func init() {
    do.Provide[Service](injector, func (i *do.Injector) (Service, error) {
        return &RealService{}, nil
    })
    do.Provide[*App](injector, func (i *do.Injector) (*App, error) {
        return &App{i.MustInvoke[Service](i)}, nil
    })
}

func TestService(t *testing.T) {
    i := injector.Clone()
    defer i.Shutdown()

    // replace Service to MockService
    do.Override[Service](i, func (i *do.Injector) (Service, error) {
        return &MockService{}, nil
    }))

    app := do.Invoke[*App](i)
    // do unit testing with mocked service
}
```

## 🛩 Benchmark

// @TODO

## 🤝 Contributing

- Ping me on twitter [@samuelberthe](https://twitter.com/samuelberthe) (DMs, mentions, whatever :))
- Fork the [project](https://github.com/samber/do)
- Fix [open issues](https://github.com/samber/do/issues) or request new features

Don't hesitate ;)

### With Docker

```bash
docker-compose run --rm dev
```

### Without Docker

```bash
# Install some dev dependencies
make tools

# Run tests
make test
# or
make watch-test
```

## 👤 Contributors

![Contributors](https://contrib.rocks/image?repo=samber/do)

## 💫 Show your support

Give a ⭐️ if this project helped you!

[![GitHub Sponsors](https://img.shields.io/github/sponsors/samber?style=for-the-badge)](https://github.com/sponsors/samber)

## 📝 License

Copyright © 2022 [Samuel Berthe](https://github.com/samber).

This project is [MIT](./LICENSE) licensed.


A dependency injection based application framework for Go (built on top of dig).

# :unicorn: Fx [![GoDoc](https://pkg.go.dev/badge/go.uber.org/fx)](https://pkg.go.dev/go.uber.org/fx) [![Github release](https://img.shields.io/github/release/uber-go/fx.svg)](https://github.com/uber-go/fx/releases) [![Build Status](https://github.com/uber-go/fx/actions/workflows/go.yml/badge.svg)](https://github.com/uber-go/fx/actions/workflows/go.yml) [![Coverage Status](https://codecov.io/gh/uber-go/fx/branch/master/graph/badge.svg)](https://codecov.io/gh/uber-go/fx/branch/master) [![Go Report Card](https://goreportcard.com/badge/go.uber.org/fx)](https://goreportcard.com/report/go.uber.org/fx)

Fx is a dependency injection system for Go.

**Benefits**

- Eliminate globals: Fx helps you remove global state from your application.
  No more `init()` or global variables. Use Fx-managed singletons.
- Code reuse: Fx lets teams within your organization build loosely-coupled
  and well-integrated shareable components.
- Battle tested: Fx is the backbone of nearly all Go services at Uber.

See our [docs](https://uber-go.github.io/fx/) to get started and/or
learn more about Fx.

## Installation

Use Go modules to install Fx in your application.

```shell
go get go.uber.org/fx@v1
```

## Getting started

To get started with Fx, [start here](https://uber-go.github.io/fx/get-started/).

## Stability

This library is `v1` and follows [SemVer](https://semver.org/) strictly.

No breaking changes will be made to exported APIs before `v2.0.0`.

This project follows the [Go Release Policy](https://golang.org/doc/devel/release.html#policy). Each major
version of Go is supported until there are two newer major releases.

## Stargazers over time

[![Stargazers over time](https://starchart.cc/uber-go/fx.svg)](https://starchart.cc/uber-go/fx)



🪣 gocontainer
================
[![Build Status](https://travis-ci.org/vardius/gocontainer.svg?branch=master)](https://travis-ci.org/vardius/gocontainer)
[![Go Report Card](https://goreportcard.com/badge/github.com/vardius/gocontainer)](https://goreportcard.com/report/github.com/vardius/gocontainer)
[![codecov](https://codecov.io/gh/vardius/gocontainer/branch/master/graph/badge.svg)](https://codecov.io/gh/vardius/gocontainer)
[![](https://godoc.org/github.com/vardius/gocontainer?status.svg)](https://pkg.go.dev/github.com/vardius/gocontainer)
[![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/vardius/gocontainer/blob/master/LICENSE.md)

<img align="right" height="180px" src="https://github.com/vardius/gorouter/blob/master/website/src/static/img/logo.png?raw=true" alt="logo" />

gocontainer - Dependency Injection Container

📖 ABOUT
==================================================
Contributors:

* [Rafał Lorenz](http://rafallorenz.com)

Want to contribute ? Feel free to send pull requests!

Have problems, bugs, feature ideas?
We are using the github [issue tracker](https://github.com/vardius/gocontainer/issues) to manage them.

## 📚 Documentation

For __examples__ **visit [godoc#pkg-examples](http://godoc.org/github.com/vardius/gocontainer#pkg-examples)**

For **GoDoc** reference, **visit [pkg.go.dev](https://pkg.go.dev/github.com/vardius/gocontainer)**

[MustInvokeMany](https://godoc.org/github.com/vardius/gocontainer#example-package--MustInvokeMany)

🚏 HOW TO USE
==================================================

First file `main.go` simply gets the repository from the container and prints it
we use **MustInvoke** method to simply present the way where we keep type safety
```go
package main

import (
    "github.com/vardius/gocontainer/example/repository"
    "github.com/vardius/gocontainer"
)

func main() {
    gocontainer.MustInvoke("repository.mysql", func(r Repository) {
        fmt.Println(r)
    })
}
```
Our database implementation uses `init()` function to register db service
```go
package database

import (
    "fmt"
    "database/sql"

    "github.com/vardius/gocontainer"
)

func NewDatabase() *sql.DB {
    db, _ := sql.Open("mysql", "dsn")

    return db
}

func init() {
    db := gocontainer.MustGet("db")

    gocontainer.Register("db", NewDatabase())
}
```
Our repository accesses earlier on registered db service
and following the same patter uses `init()` function to register repository service within container
```go
package repository

import (
    "fmt"
    "database/sql"

    "github.com/vardius/gocontainer"
    _ "github.com/vardius/gocontainer/example/database"
)

type Repository interface {}

func NewRepository(db *sql.DB) Repository {
    return &mysqlRepository{db}
}

type mysqlRepository struct {
    db *sql.DB
}

func init() {
    db := gocontainer.MustGet("db")

    gocontainer.Register("repository.mysql", NewRepository(db.(*sql.DB)))
}
```
You can disable global container instance by setting `gocontainer.GlobalContainer` to `nil`.
This package allows you to create many containers.
```go
package main

import (
    "github.com/vardius/gocontainer/example/repository"
    "github.com/vardius/gocontainer"
)

func main() {
    // disable global container instance
    gocontainer.GlobalContainer = nil

    mycontainer := gocontainer.New()
    mycontainer.Register("test", 1)
}
```
Please check [GoDoc](http://godoc.org/github.com/vardius/gocontainer) for more methods and examples.

📜 [License](LICENSE.md)
-------

This package is released under the MIT license. See the complete license in the package


gocontainer

Spring-inspired Dependency Injection Container.

# goioc/di: Dependency Injection
[![goioc](https://habrastorage.org/webt/ym/pu/dc/ympudccm7j7a3qex_jjroxgsiwg.png)](https://github.com/goioc)

[![Go](https://github.com/goioc/di/workflows/Go/badge.svg)](https://github.com/goioc/di/actions)
[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/goioc/di/?tab=doc)
[![CodeFactor](https://www.codefactor.io/repository/github/goioc/di/badge)](https://www.codefactor.io/repository/github/goioc/di)
[![Go Report Card](https://goreportcard.com/badge/github.com/goioc/di)](https://goreportcard.com/report/github.com/goioc/di)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=goioc_di&metric=alert_status)](https://sonarcloud.io/dashboard?id=goioc_di)
[![codecov](https://codecov.io/gh/goioc/di/branch/master/graph/badge.svg)](https://codecov.io/gh/goioc/di)
[![DeepSource](https://static.deepsource.io/deepsource-badge-light-mini.svg)](https://deepsource.io/gh/goioc/di/?ref=repository-badge)
[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome)

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/G2G5JUKU7)

## Why DI in Go? Why IoC at all?
I've been using Dependency Injection in Java for nearly 10 years via [Spring Framework](https://spring.io/). I'm not saying that one can't live without it, but it's proven to be very useful for large enterprise-level applications. You may argue that Go follows a completely different ideology, values different principles and paradigms than Java, and DI is not needed in this better world. And I can even partly agree with that. And yet I decided to create this light-weight Spring-like library for Go. You are free to not use it, after all 🙂

## Is it the only DI library for Go?
No, of course not. There's a bunch of libraries around which serve a similar purpose (I even took inspiration from some of them). The problem is that I was missing something in all of these libraries... Therefore I decided to create Yet Another IoC Container that would rule them all. You are more than welcome to use any other library, for example [this nice project](https://github.com/sarulabs/di). And still, I'd recommend stopping by here 😉

## So, how does it work? 
It's better to show than to describe. Take a look at this toy-example (error-handling is omitted to minimize code snippets):

**services/weather_service.go**
```go
package services

import (
	"io"
	"net/http"
)

type WeatherService struct {
}

func (ws *WeatherService) Weather(city string) (*string, error) {
	response, err := http.Get("https://wttr.in/" + city)
	if err != nil {
		return nil, err
	}
	all, err := io.ReadAll(response.Body)
	if err != nil {
		return nil, err
	}
	weather := string(all)
	return &weather, nil
}
```

**controllers/weather_controller.go**
```go
package controllers

import (
	"di-demo/services"
	"github.com/goioc/di"
	"net/http"
)

type WeatherController struct {
	// note that injection works even with unexported fields
	weatherService *services.WeatherService `di.inject:"weatherService"`
}

func (wc *WeatherController) Weather(w http.ResponseWriter, r *http.Request) {
	weather, _ := wc.weatherService.Weather(r.URL.Query().Get("city"))
	_, _ = w.Write([]byte(*weather))
}
```

**init.go**
```go
package main

import (
	"di-demo/controllers"
	"di-demo/services"
	"github.com/goioc/di"
	"reflect"
)

func init() {
	_, _ = di.RegisterBean("weatherService", reflect.TypeOf((*services.WeatherService)(nil)))
	_, _ = di.RegisterBean("weatherController", reflect.TypeOf((*controllers.WeatherController)(nil)))
	_ = di.InitializeContainer()
}
```

**main.go**
```go
package main

import (
	"di-demo/controllers"
	"github.com/goioc/di"
	"net/http"
)

func main() {
	http.HandleFunc("/weather", func(w http.ResponseWriter, r *http.Request) {
		di.GetInstance("weatherController").(*controllers.WeatherController).Weather(w, r)
	})
	_ = http.ListenAndServe(":8080", nil)
}
```

If you run it, you should be able to observe a neat weather forecast at http://localhost:8080/weather?city=London (or for any other city).

Of course, for such a simple example it may look like an overkill. But for larger projects with many interconnected services with complicated business logic, it can really simplify your life!

## Looks nice... Give me some details!

The main component of the library is the [Inversion of Control Container](https://www.martinfowler.com/articles/injection.html) that contains and manages instances of your structures (called "beans").

### Types of beans

- **Singleton**. Exists only in one copy in the container. Every time you retrieve the instance from the container (or every time it's being injected to another bean) - it will be the same instance.
- **Prototype**. It can exist in multiple copies: a new copy is created upon retrieval from the container (or upon injection into another bean).
- **Request**. Similar to `Prototype`, however it has a few differences and features (since its lifecycle is bound to a web request):
   - Can't be injected to other beans.
   - Can't be manually retrieved from the Container.
   - `Request` beans are automatically injected to the `context.Context` of a corresponding `http.Request`. 
   - If a `Request` bean implements `io.Closer`, it will be "closed" upon corresponding request's cancellation.

### Beans registration

For the container to become aware of the beans, one must register them manually (unlike Java, unfortunately, we can't scan classpath to do it automatically, because Go runtime doesn't contain high-level information about types). How can one register beans in the container?

- **By type**. This is described in the example above. A structure is declared with a field tagged with `di.scope:"<scope>"`. This field can be even omitted - in this case, the default scope will be `Singleton`. Then the registration is done like this:
```go
di.RegisterBean("beanID", reflect.TypeOf((*YourAwesomeStructure)(nil)))
```

- **Using pre-created instance**. What if you already have an instance that you want to register as a bean? You can do it like this:
```go
di.RegisterBeanInstance("beanID", yourAwesomeInstance)
```
For this type of beans, the only supported scope is `Singleton`, because I don't dare to clone your instances to enable prototyping 😅

- **Via bean factory**. If you have a method that is producing instances for you, you can register it as a bean factory:
```go
di.RegisterBeanFactory("beanID", Singleton, func(context.Context) (interface{}, error) {
		return "My awesome string that is going to become a bean!", nil
	})
```
Feel free to use any scope with this method. By the way, you can even lookup other beans within the factory:
```go
di.RegisterBeanFactory("beanID", Prototype, func(context.Context) (interface{}, error) {
		return di.GetInstance("someOtherBeanID"), nil
	})
```
Note that factory-method accepts `context.Context`. It can be useful for request-scoped beans (the HTTP request context is set in this case). For all other beans it will be `context.Background()`.

### Beans initialization

There's a special interface `InitializingBean` that can be implemented to provide your bean with some initialization logic that will be executed after the container is initialized (for `Singleton` beans) or after the `Prototype`/`Request` instance is created. Again, you can also lookup other beans during initialization (since the container is ready by that time):

```go
type PostConstructBean1 struct {
	Value string
}

func (pcb *PostConstructBean1) PostConstruct() error {
	pcb.Value = "some content"
	return nil
}

type PostConstructBean2 struct {
	Scope              Scope `di.scope:"prototype"`
	PostConstructBean1 *PostConstructBean1
}

func (pcb *PostConstructBean2) PostConstruct() error {
	instance, err := di.GetInstanceSafe("postConstructBean1")
	if err != nil {
		return err
	}
	pcb.PostConstructBean1 = instance.(*PostConstructBean1)
	return nil
}
```

### Beans post-processors

The alternative way of initializing beans is using so-called "beans post-processors". Take a look at the example:

```go
type postprocessedBean struct {
	a string
	b string
}

_, _ := RegisterBean("postprocessedBean", reflect.TypeOf((*postprocessedBean)(nil)))

_ = RegisterBeanPostprocessor(reflect.TypeOf((*postprocessedBean)(nil)), func(instance interface{}) error {
    instance.(*postprocessedBean).a = "Hello, "
    return nil
})

_ = RegisterBeanPostprocessor(reflect.TypeOf((*postprocessedBean)(nil)), func(instance interface{}) error {
instance.(*postprocessedBean).b = "world!"
    return nil
})

_ = InitializeContainer()

instance := GetInstance("postprocessedBean")

postprocessedBean := instance.(*postprocessedBean)
println(postprocessedBean.a+postprocessedBean.b) // prints out "Hello, world!"
```

### Beans injection

As was mentioned above, one bean can be injected into another with the `PostConstruct` method. However, the more handy way of doing it is by using a special tag:

```go
type SingletonBean struct {
	SomeOtherBean *SomeOtherBean `di.inject:"someOtherBean"`
}
```

... or via interface ...

```go
type SingletonBean struct {
	SomeOtherBean SomeOtherBeansInterface `di.inject:"someOtherBean"`
}
```

Note that you can refer dependencies either by pointer, or by interface, but not by value. And just a reminder: you can't inject `Request` beans.

Sometimes we might want to have optional dependencies. By default, all declared dependencies are considered to be required: if some dependency is not found in the Container, you will get an error. However, you can specify an optional dependency like this:

```go
type SingletonBean struct {
	SomeOtherBean *string `di.inject:"someOtherBean" di.optional:"true"`
}
```

In this case, if `someOtherBean` is not found in the Container, you will get `nil` injected into this field.

In fact, you don't need a bean ID to preform an injection! Check this out:

```go
type SingletonBean struct {
	SomeOtherBean *string `di.inject:""`
}
```

In this case, DI will try to find a candidate for the injection automatically (among registered beans of type `*string`). Cool, ain't it? 🤠
It will panic though if no candidates are found (and if the dependency is not marked as optional), or if there is more than one candidate found. 

Finally, you can inject beans to slices and maps. It works similarly to the ID-less inections above, but injects all candidates that were found:

```go
type SingletonBean struct {
	someOtherBeans []*string `di.inject:""`
}
```

```go
type SingletonBean struct {
	someOtherBeans map[string]*string `di.inject:""`
}
```

### Circular dependencies

The problem with all IoC containers is that beans' interconnection may suffer from so-called circular dependencies. Consider this example:

```go
type CircularBean struct {
	Scope        Scope         `di.scope:"prototype"`
	CircularBean *CircularBean `di.inject:"circularBean"`
}
```

Trying to use such bean will result in the `circular dependency detected for bean: circularBean` error. There's no problem as such with referencing a bean from itself - if it's a `Singleton` bean. But doing it with `Prototype`/`Request` beans will lead to infinite creation of the instances. So, be careful with this: "with great power comes great responsibility" 🕸 

## What about middleware?

We have some 😎 Here's an example with [gorilla/mux](https://github.com/gorilla/mux) router (but feel free to use any other router). 
Basically, it's an extension of the very first example with the weather controller, but this time we add `Request` beans and access them via request's context. 
Also, this example demonstrates how DI can automatically close resources for you (DB connection in this case). The proper error handling is, again, omitted for simplicity.

**controllers/weather_controller.go**
```go
package controllers

import (
	"database/sql"
	"di-demo/services"
	"github.com/goioc/di"
	"net/http"
)

type WeatherController struct {
	// note that injection works even with unexported fields
	weatherService *services.WeatherService `di.inject:"weatherService"`
}

func (wc *WeatherController) Weather(w http.ResponseWriter, r *http.Request) {
	dbConnection := r.Context().Value(di.BeanKey("dbConnection")).(*sql.Conn)
	city := r.URL.Query().Get("city")
	_, _ = dbConnection.ExecContext(r.Context(), "insert into log values (?, ?, datetime('now'))", city, r.RemoteAddr)
	weather, _ := wc.weatherService.Weather(city)
	_, _ = w.Write([]byte(*weather))
}
```

**controllers/index_controller.go**
```go
package controllers

import (
	"database/sql"
	"fmt"
	"github.com/goioc/di"
	"net/http"
	"strings"
	"time"
)

type IndexController struct {
}

func (ic *IndexController) Log(w http.ResponseWriter, r *http.Request) {
	dbConnection := r.Context().Value(di.BeanKey("dbConnection")).(*sql.Conn)
	rows, _ := dbConnection.QueryContext(r.Context(), "select * from log")
	columns, _ := rows.Columns()
	_, _ = w.Write([]byte(strings.ToUpper(fmt.Sprintf("Requests log: %v\n\n", columns))))
	for rows.Next() {
		var city string
		var ip string
		var dateTime time.Time
		_ = rows.Scan(&city, &ip, &dateTime)
		_, _ = w.Write([]byte(fmt.Sprintln(city, "\t", ip, "\t", dateTime)))
	}
}
```

**init.go**
```go
package main

import (
	"context"
	"database/sql"
	"di-demo/controllers"
	"di-demo/services"
	"github.com/goioc/di"
	"os"
	"reflect"
)

func init() {
	_, _ = di.RegisterBean("weatherService", reflect.TypeOf((*services.WeatherService)(nil)))
	_, _ = di.RegisterBean("indexController", reflect.TypeOf((*controllers.IndexController)(nil)))
	_, _ = di.RegisterBean("weatherController", reflect.TypeOf((*controllers.WeatherController)(nil)))
	_, _ = di.RegisterBeanFactory("db", di.Singleton, func(context.Context) (interface{}, error) {
		_ = os.Remove("./di-demo.db")
		db, _ := sql.Open("sqlite3", "./di-demo.db")
		db.SetMaxOpenConns(1)
		_, _ = db.Exec("create table log ('city' varchar not null, 'ip' varchar not null, 'time' datetime not null)")
		return db, nil
	})
	_, _ = di.RegisterBeanFactory("dbConnection", di.Request, func(ctx context.Context) (interface{}, error) {
		db, _ := di.GetInstanceSafe("db")
		return db.(*sql.DB).Conn(ctx)
	})
	_ = di.InitializeContainer()
}
```

**main.go**
```go
package main

import (
	"di-demo/controllers"
	"github.com/goioc/di"
	"github.com/gorilla/mux"
	_ "github.com/mattn/go-sqlite3"
	"net/http"
)

func main() {
	router := mux.NewRouter()
	router.Use(di.Middleware)
	router.Path("/").HandlerFunc(di.GetInstance("indexController").(*controllers.IndexController).Log)
	router.Path("/weather").Queries("city", "{*?}").HandlerFunc(di.GetInstance("weatherController").(*controllers.WeatherController).Weather)
	_ = http.ListenAndServe(":8080", router)
}
```

## Okaaay... More examples?

Please, take a look at the [unit-tests](https://github.com/goioc/di/blob/master/di_test.go) for more examples.


goioc/di

GoLobby Container is a lightweight yet powerful IoC dependency injection container for the Go programming language.

[![Go Reference](https://pkg.go.dev/badge/github.com/golobby/container.svg)](https://pkg.go.dev/github.com/golobby/container)
[![CI](https://github.com/golobby/container/actions/workflows/ci.yml/badge.svg)](https://github.com/golobby/container/actions/workflows/ci.yml)
[![CodeQL](https://github.com/golobby/container/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/golobby/container/actions/workflows/codeql-analysis.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/golobby/container)](https://goreportcard.com/report/github.com/golobby/container)
[![Coverage Status](https://coveralls.io/repos/github/golobby/container/badge.svg)](https://coveralls.io/github/golobby/container?branch=master)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)  

# Container
GoLobby Container is a lightweight yet powerful IoC (dependency injection) container for Go projects.
It's built neat, easy-to-use, and performance-in-mind to be your ultimate requirement.

Features:
- Singleton and Transient bindings
- Named dependencies (bindings)
- Resolve by functions, variables, and structs
- Must helpers that convert errors to panics
- Optional lazy loading of bindings
- Global instance for small applications
- 100% Test coverage!

## Documentation
### Required Go Versions
It requires Go `v1.11` or newer versions.

### Installation
To install this package, run the following command in your project directory.

```bash
go get github.com/golobby/container/v3
```

Next, include it in your application:

```go
import "github.com/golobby/container/v3"
```

### Introduction
GoLobby Container is used to bind abstractions to their implementations.
Binding is the process of introducing appropriate concretes (implementations) of abstractions to an IoC container.
In this process, you also determine the resolving type, singleton or transient.
In singleton bindings, the container provides an instance once and returns it for all the requests.
In transient bindings, the container always returns a brand-new instance for each request.
After the binding process, you can ask the IoC container to make the appropriate implementation of the abstraction that your code needs.
Then your code will depend on abstractions, not implementations!

### Quick Start
The following example demonstrates a simple binding and resolving.

```go
// Bind Config interface to JsonConfig struct
err := container.Singleton(func() Config {
    return &JsonConfig{...}
})

var c Config
err := container.Resolve(&c)
// `c` will be the instance of JsonConfig
```

### Typed Binding
#### Singleton
The following snippet expresses singleton binding.

```go
err := container.Singleton(func() Abstraction {
  return Implementation
})

// If you might return an error...

err := container.Singleton(func() (Abstraction, error) {
  return Implementation, nil
})
```

It takes a resolver (function) whose return type is the abstraction and the function body returns the concrete (implementation).

The example below shows a singleton binding.

```go
err := container.Singleton(func() Database {
  return &MySQL{}
})
```

#### Transient
The example below shows a transient binding.

```go
err := container.Transient(func() Shape {
  return &Rectangle{}
})
```

### Named Bindings
You may have different concretes for an abstraction.
In this case, you can use named bindings instead of typed bindings.
Named bindings take the dependency name into account as well.
The rest is similar to typed bindings.
The following examples demonstrate some named bindings.

```go
// Singleton
err := container.NamedSingleton("square", func() Shape {
    return &Rectangle{}
})
err := container.NamedSingleton("rounded", func() Shape {
    return &Circle{}
})

// Transient
err := container.NamedTransient("sql", func() Database {
    return &MySQL{}
})
err := container.NamedTransient("noSql", func() Database {
    return &MongoDB{}
})
```

### Resolver Errors

The process of creating concrete (resolving) might face an error.
In this case, you can return the error as the second return value like the example below.

```go
err := container.Transient(func() (Shape, error) {
  return nil, errors.New("my-app: cannot create a Shape implementation")
})
```

It could be applied to other binding types.

### Resolving
Container resolves the dependencies with the `Resolve()`, `Call()`, and `Fill()` methods.

#### Using References
The `Resolve()` method takes reference of the abstraction type and fills it with the appropriate concrete.

```go
var a Abstraction
err := container.Resolve(&a)
// `a` will be an implementation of the Abstraction
```

Example of resolving using references:

```go
var m Mailer
err := container.Resolve(&m)
// `m` will be an implementation of the Mailer interface
m.Send("contact@miladrahimi.com", "Hello Milad!")
```

Example of named-resolving using references:

```go
var s Shape
err := container.NamedResolve(&s, "rounded")
// `s` will be an implementation of the Shape that named rounded
```

#### Using Closures
The `Call()` method takes a receiver (function) with arguments of abstractions you need.
It calls it with parameters of appropriate concretes.

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

Example of resolving using closures:

```go
err := container.Call(func(db Database) {
  // `db` will be an implementation of the Database interface
  db.Query("...")
})
```

You can also resolve multiple abstractions like the following example:

```go
err := container.Call(func(db Database, s Shape) {
  db.Query("...")
  s.Area()
})
```

You are able to raise an error in your receiver function, as well.

```go
err := container.Call(func(db Database) error {
  return db.Ping()
})
// err could be `db.Ping()` error.
```

Caution: The `Call()` method does not support named bindings.

#### Using Structs
The `Fill()` method takes a struct (pointer) and resolves its fields.

The example below expresses how the `Fill()` method works.

```go
type App struct {
    mailer Mailer   `container:"type"`
    sql    Database `container:"name"`
    noSql  Database `container:"name"`
    other  int
}

myApp := App{}

err := container.Fill(&myApp)

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

// [Named Bindings]
// `myApp.sql` will be a sql implementation of the Database interface
// `myApp.noSql` will be a noSql implementation of the Database interface

// `myApp.other` will be ignored since it has no `container` tag
```

#### Binding time
You can resolve dependencies at the binding time if you need previous dependencies for the new one.

The following example shows resolving dependencies at binding time.

```go
// Bind Config to JsonConfig
err := container.Singleton(func() Config {
    return &JsonConfig{...}
})

// Bind Database to MySQL
err := container.Singleton(func(c Config) Database {
    // `c` will be an instance of `JsonConfig`
    return &MySQL{
        Username: c.Get("DB_USERNAME"),
        Password: c.Get("DB_PASSWORD"),
    }
})
```

### Standalone Instance
By default, the Container keeps your bindings in the global instance.
Sometimes you may want to create a standalone instance for a part of your application.
If so, create a standalone instance like the example below.

```go
c := container.New()

err := c.Singleton(func() Database {
    return &MySQL{}
})

err := c.Call(func(db Database) {
    db.Query("...")
})
```

The rest stays the same.
The global container is still available.

### Must Helpers

You might believe that the container shouldn't raise any error and/or you prefer panics.
In this case, Must helpers are for you.
Must helpers are global methods that panic instead of returning errors.

```go
c := container.New()
// Global instance:
// c := container.Global

container.MustSingleton(c, func() Shape {
    return &Circle{a: 13}
})

container.MustCall(c, func(s Shape) {
    // ...
})

// Other Must Helpers:
// container.MustSingleton()
// container.MustSingletonLazy()
// container.MustNamedSingleton()
// container.MustNamedSingletonLazy()
// container.MustTransient()
// container.MustTransientLazy()
// container.MustNamedTransient()
// container.MustNamedTransientLazy()
// container.MustCall()
// container.MustResolve()
// container.MustNamedResolve()
// container.MustFill()
```

### Lazy Binding
Both the singleton and transient binding calls have a lazy version.
Lazy versions defer calling the provided resolver function until the first call.
For singleton bindings, It calls the resolver function only once and stores the result.

Lazy binding methods:
* `container.SingletonLazy()`
* `container.NamedSingletonLazy()`
* `container.TransientLazy()`
* `container.NamedTransientLazy()`

### Performance
The package Container inevitably uses reflection for binding and resolving processes. 
If performance is a concern, try to bind and resolve the dependencies where it runs only once, like the main and init functions.

## License

GoLobby Container is released under the [MIT License](http://opensource.org/licenses/mit-license.php).


The Best Go Libraries For Miscellaneous - Libraries for working with dependency injection. (16)

ore