godi

README

godi

Overview

godi is a lightweight DI helper built on top of go.uber.org/dig.

Features

• Provide / Replace / Decorate over dependency "slots"
• Module scopes with Private() providers
• Automatic dig.As(...) bindings via matchings
• dig.Out multi-output support (including name / group tags)
• Runnable collection + Lifecycle helper
• Dependency graph export (DOT/Graphviz) and override detection

Install

go get github.com/assurrussa/godi@latest

Quick Start

package main

import (
	"os"

	"go.uber.org/dig"

	"github.com/assurrussa/godi"
)

func main() {
	cnt, err := godi.NewContainer(
		godi.WithDependencies(
			godi.CollectDependencies(
				godi.NewDependency(func() string { return "world" }, godi.WithName("target")),
				godi.NewDependency(func(in struct {
					dig.In
					Target string `name:"target"`
				}) string {
					return "hello " + in.Target
				}),
			),
		),
	)
	if err != nil {
		panic(err)
	}

	if err := cnt.Validate(); err != nil {
		panic(err)
	}

	var greeting string
	if err := cnt.Invoke(func(s string) { greeting = s }); err != nil {
		panic(err)
	}

	if _, err := os.Stdout.WriteString(greeting + "\n"); err != nil {
		panic(err)
	}
}

Documentation

• English: docs/en/README.md
• Russian: docs/README.md

Examples

• go run ./examples/basic
• go run ./examples/modules
• go run ./examples/digout

License

MIT

Documentation

Index

• type Container
  • func NewContainer(opts ...ContainerOption) (*Container, error)
  • func (c *Container) Graph() Graph
  • func (c *Container) GraphDOT() string
  • func (c *Container) GraphDOTModules() map[string]string
  • func (c *Container) GraphModules() map[string]Graph
  • func (c *Container) Invoke(consumer any) error
  • func (c *Container) Provide(deps Dependencies) error
  • func (c *Container) Runnables() ([]Runnable, error)
  • func (c *Container) Validate() error
• type ContainerOption
  • func WithDefaultLifecycle() ContainerOption
  • func WithDependencies(d ...Dependencies) ContainerOption
  • func WithMatchings(matchings ...any) ContainerOption
  • func WithModules(modules ...Module) ContainerOption
• type Dependencies
  • func CollectDependencies(deps ...Dependency) Dependencies
  • func NewSingleDependency(constructor any, opts ...DependencyOption) Dependencies
  • func (d Dependencies) List() []Dependency
• type Dependency
  • func Decorate(constructor any, opts ...DependencyOption) Dependency
  • func NewDependency(constructor any, opts ...DependencyOption) Dependency
  • func Replace(constructor any, opts ...DependencyOption) Dependency
  • func (d *Dependency) AddMatchingInterface(as ...any) error
  • func (d *Dependency) Error() error
  • func (d *Dependency) ExposedTypes() []reflect.Type
  • func (d *Dependency) IsRunnable() bool
  • func (d *Dependency) Type() reflect.Type
• type DependencyOption
  • func Private() DependencyOption
  • func WithGroup(group string) DependencyOption
  • func WithKey(key string) DependencyOption
  • func WithMatch(a any) DependencyOption
  • func WithName(name string) DependencyOption
• type Graph
  • func BuildGraph(deps Dependencies) Graph
  • func (g Graph) DOT() string
  • func (g Graph) ProviderIDs() []string
• type GraphToken
• type Hook
• type Lifecycle
  • func NewLifecycle() *Lifecycle
  • func (l *Lifecycle) Append(h Hook)
  • func (l *Lifecycle) Start(ctx context.Context) error
  • func (l *Lifecycle) Stop(ctx context.Context) error
• type Matching
  • func NewMatching(origin any, interfaces ...any) Matching
  • func (m *Matching) Error() error
  • func (m *Matching) Origin() reflect.Type
• type Module
  • func NewModule(name string, dependencies Dependencies) Module
• type Optional
  • func (o *Optional[T]) Get() (T, bool)
• type OverrideInfo
  • func DetectOverrides(deps Dependencies) []OverrideInfo
• type ProviderEdge
• type ProviderInfo
• type ProviderNode
• type Runnable

Types

type Container

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

Container wraps dig.Container with a tiny convenience layer.

func NewContainer

func NewContainer(opts ...ContainerOption) (*Container, error)

func (*Container) Graph

func (c *Container) Graph() Graph

Graph builds a dependency graph for the container root scope (resolved providers only).

func (*Container) GraphDOT

func (c *Container) GraphDOT() string

GraphDOT renders the container graph in DOT (Graphviz) format.

func (*Container) GraphDOTModules

func (c *Container) GraphDOTModules() map[string]string

GraphDOTModules returns DOT graphs for the root and each module scope.

func (*Container) GraphModules

func (c *Container) GraphModules() map[string]Graph

GraphModules builds dependency graphs for the root and each module scope. Module graphs include the root providers plus module-private providers.

func (*Container) Invoke

func (c *Container) Invoke(consumer any) error

func (*Container) Provide

func (c *Container) Provide(deps Dependencies) error

Provide appends dependencies to the container.

func (*Container) Runnables

func (c *Container) Runnables() ([]Runnable, error)

func (*Container) Validate

func (c *Container) Validate() error

Validate checks that all registered dependencies are resolvable without running constructors.

type ContainerOption

type ContainerOption func(c *containerConfig)

func WithDefaultLifecycle

func WithDefaultLifecycle() ContainerOption

WithDefaultLifecycle registers a default Lifecycle in the container.

func WithDependencies

func WithDependencies(d ...Dependencies) ContainerOption

WithDependencies adds dependencies to the container.

func WithMatchings

func WithMatchings(matchings ...any) ContainerOption

WithMatchings applies dig.As mappings automatically for provided dependencies. Accepts pointers to interfaces or Matching instances.

func WithModules

func WithModules(modules ...Module) ContainerOption

WithModules registers module dependencies with optional privacy.

type Dependencies

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

func CollectDependencies

func CollectDependencies(deps ...Dependency) Dependencies

func NewSingleDependency

func NewSingleDependency(constructor any, opts ...DependencyOption) Dependencies

func (Dependencies) List

func (d Dependencies) List() []Dependency

type Dependency

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

func Decorate

func Decorate(constructor any, opts ...DependencyOption) Dependency

Decorate declares a decorator for an existing dependency slot.

func NewDependency

func NewDependency(constructor any, opts ...DependencyOption) Dependency

func Replace

func Replace(constructor any, opts ...DependencyOption) Dependency

Replace declares an explicit replacement for a dependency slot.

func (*Dependency) AddMatchingInterface

func (d *Dependency) AddMatchingInterface(as ...any) error

func (*Dependency) Error

func (d *Dependency) Error() error

func (*Dependency) ExposedTypes

func (d *Dependency) ExposedTypes() []reflect.Type

ExposedTypes returns the types this dependency is exposed as in the container. When matching interfaces are provided (dig.As), only those interfaces are exposed.

func (*Dependency) IsRunnable

func (d *Dependency) IsRunnable() bool

func (*Dependency) Type

func (d *Dependency) Type() reflect.Type

type DependencyOption

type DependencyOption func(*Dependency)

func Private

func Private() DependencyOption

Private marks a dependency as private to its module scope.

func WithGroup

func WithGroup(group string) DependencyOption

WithGroup adds dependency to dig group.

func WithKey

func WithKey(key string) DependencyOption

WithKey attaches a metadata key for diagnostics (no effect on resolution).

func WithMatch

func WithMatch(a any) DependencyOption

WithMatch maps dependency to interface (dig.As).

func WithName

func WithName(name string) DependencyOption

WithName provides dependency under a named key (dig.Name).

type Graph

type Graph struct {
	Providers []ProviderNode
	Edges     []ProviderEdge
}

func BuildGraph

func BuildGraph(deps Dependencies) Graph

BuildGraph builds a dependency graph for the provided dependencies (resolved providers only).

func (Graph) DOT

func (g Graph) DOT() string

DOT renders a dependency graph as DOT (Graphviz) format.

func (Graph) ProviderIDs

func (g Graph) ProviderIDs() []string

type GraphToken

type GraphToken struct {
	Type     string
	Name     string
	Group    string
	Optional bool
	// contains filtered or unexported fields
}

type Hook

type Hook struct {
	OnStart func(context.Context) error
	OnStop  func(context.Context) error
}

type Lifecycle

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

Lifecycle manages start/stop hooks in order (start) and reverse order (stop).

func NewLifecycle

func NewLifecycle() *Lifecycle

func (*Lifecycle) Append

func (l *Lifecycle) Append(h Hook)

func (*Lifecycle) Start

func (l *Lifecycle) Start(ctx context.Context) error

func (*Lifecycle) Stop

func (l *Lifecycle) Stop(ctx context.Context) error

type Matching

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

func NewMatching

func NewMatching(origin any, interfaces ...any) Matching

NewMatching matches concrete type to interfaces (dig.As).

func (*Matching) Error

func (m *Matching) Error() error

func (*Matching) Origin

func (m *Matching) Origin() reflect.Type

type Module

type Module struct {
	Name         string
	Dependencies Dependencies
}

Module groups dependencies and allows marking some as private to the module scope.

func NewModule

func NewModule(name string, dependencies Dependencies) Module

type Optional

type Optional[T any] struct {
	dig.In
	Optional *T `optional:"true"`
}

Optional allows resolving dependency if it exists.

func (*Optional[T]) Get

func (o *Optional[T]) Get() (T, bool)

type OverrideInfo

type OverrideInfo struct {
	Key      string
	Previous ProviderInfo
	Next     ProviderInfo
}

func DetectOverrides

func DetectOverrides(deps Dependencies) []OverrideInfo

DetectOverrides reports explicit replacements (godi.Replace) by slot.

type ProviderEdge

type ProviderEdge struct {
	From     string
	To       string
	Type     string
	Name     string
	Group    string
	Optional bool
	Missing  bool
}

type ProviderInfo

type ProviderInfo struct {
	Index       int
	Constructor string
	File        string
	Line        int
	Type        string
	Name        string
	Group       string
}

type ProviderNode

type ProviderNode struct {
	ID          string
	Key         string
	Type        string
	Name        string
	Group       string
	Kind        string
	Constructor string
	File        string
	Line        int
	Provides    []GraphToken
	Requires    []GraphToken
}

type Runnable

type Runnable struct {
	OnStart func(context.Context) error
	OnStop  func(context.Context) error
}