dig

dig is a reflection-based dependency injection toolkit for Go.

Best Use Cases:

• Powering an application framework (e.g., Fx).
• Resolving the object graph during process startup.

When NOT to use dig:

• As a replacement for a full application framework.
• For resolving dependencies after the process has already started.
• As a Service Locator in user-land code.

To run the standard unit tests and the visualization golden tests, use the make command.

$ make test

To visualize the effect of code changes, you can generate DOT files and then convert them to PNG images using graphviz.

1. Generate the DOT files in the dig root directory:

   go test -generate

2. Navigate to the testdata directory.
3. Convert the .dot file to a .png using the dot command (requires graphviz):

   dot -Tpng ${name_of_dot_file_in_testdata}.dot -o ${name_of_dot_file_in_testdata}.png
   open ${name_of_dot_file_in_testdata}.png

$ go test -generate
$ dot -Tpng ${name_of_dot_file_in_testdata}.dot -o ${name_of_dot_file_in_testdata}.png

Install the v1 major version of dig using your preferred Go dependency manager. It is recommended to use SemVer major version 1.

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

In dig, dependencies for constructors are represented by the param interface. When you provide a constructor to a container, dig identifies its dependencies using one of the following internal parameter implementations:

• paramSingle: An explicitly requested type (the most common case).
• paramObject: A dig.In struct where each field is treated as an individual dependency.
• paramGroupedSlice: A slice that consumes all values produced with a group:".." tag sharing the same group name.
• paramList: Represents all arguments of a constructor (used internally to build the list of arguments).

Instead of listing many arguments in a constructor, you can use a struct that embeds dig.In. Each exported field in the struct becomes a dependency that dig will attempt to satisfy.

Rules for dig.In structs:

• The struct must embed dig.In.
• Fields must be exported (start with an uppercase letter).
• You cannot embed *dig.In (the pointer version); use the value type instead.
• You cannot depend on a pointer to a dig.In struct; use the value type.
• You can use the name:"..." tag to request a specific named dependency.
• You can use the optional tag to make a field dependency optional.
• You can use the group:"..." tag to consume a group of values into a slice.
• You can use the ignoreUnexported:"true" tag on the dig.In field to allow dig to ignore unexported fields in the struct.

When using a dig.In struct, you can refine how dependencies are matched using struct tags:

• name:"foo": Matches a dependency that was provided with the name "foo".
• optional: If the dependency is not found in the container, dig will provide the zero value for that type instead of returning an error.

Example:

type MyDeps struct {
	dig.In
	// Requests a specific named dependency
	Logger Logger `name:"audit_logger"` 

	// If this dependency is missing, it won't cause an error
	Config *Config `optional` 
}

You can collect multiple values of the same type into a single slice by using the group tag. This is useful for plugin architectures or collecting multiple implementations of an interface.

To use this, define a field in a dig.In struct as a slice and tag it with group:"<name>".

Example:

type MyConfig struct {
	dig.In
	Plugins []Plugin `group:"plugins"` // Consumes all values in the "plugins" group
}

Use WithDecoratorCallback to register a Callback that executes after a decorator finishes running. The callback receives a CallbackInfo object containing the function's name, any error returned, and the execution duration.

This is useful for monitoring the execution of decorators used to wrap or modify existing providers.

c := dig.New()
myCallback := func(ci CallbackInfo) {
	var errorAdd string
	if ci.Error != nil {
		errorAdd = fmt.Sprintf("with error: %v", ci.Error)
	}
	fmt.Printf("%q finished%v", ci.Name, errorAdd)
}
c.Decorate(myDecorator, WithDecoratorCallback(myCallback))