Go Foundation - API Reference

pkg/di/container.go:59-65

func New() *Container

{
	return &Container{
		services:  make(map[reflect.Type]*serviceEntry),
		named:     make(map[string]any),
		resolving: make(map[reflect.Type]struct{}),
	}
}

S

struct

Builder

Builder constructs a Container with validation.

pkg/di/container.go:68-74

type Builder struct

Methods

Build

Method

Build creates a Container and validates all registrations. Returns an error if any registered type has unresolvable dependencies.

Returns

*Container

error

func (*Builder) Build() (*Container, error)
{
	c := New()
	b.mu.RLock()
	for k, v := range b.services {
		cp := *v
		c.services[k] = &cp
	}
	for k, v := range b.named {
		c.named[k] = v
	}
	b.mu.RUnlock()

	if errs := c.validate(); len(errs) > 0 {
		return c, fmt.Errorf("di: build validation failed: %v", errs)
	}
	return c, nil
}

MustBuild

Method

MustBuild is like Build but panics on validation errors.

Returns

*Container

func (*Builder) MustBuild() *Container
{
	c, err := b.Build()
	if err != nil {
		panic(err.Error())
	}
	return c
}

Provide

Method

Parameters

name string

instance any

func (*Builder) Provide(name string, instance any)
{
	contracts.MustVerify(instance)
	b.mu.Lock()
	b.named[name] = instance
	b.mu.Unlock()
}

Fields

Name	Type	Description
services	map[reflect.Type]*serviceEntry
named	map[string]any
mu	sync.RWMutex
validated	bool
buildErrors	[]error

F

function

NewBuilder

NewBuilder creates a new Builder.

Returns

pkg/di/container.go:77-82

func NewBuilder() *Builder

{
	return &Builder{
		services: make(map[reflect.Type]*serviceEntry),
		named:    make(map[string]any),
	}
}

F

function

Register

Register adds a service factory to the builder.

Parameters

b

factory

func() T

lifetime

...Lifetime

pkg/di/container.go:85-94

func Register[T any](b *Builder, factory func() T, lifetime ...Lifetime)

{
	lt := Singleton
	if len(lifetime) > 0 {
		lt = lifetime[0]
	}
	typ := reflect.TypeOf((*T)(nil)).Elem()
	b.mu.Lock()
	b.services[typ] = &serviceEntry{lifetime: lt, factory: factory, concreteType: typ}
	b.mu.Unlock()
}

F

function

RegisterAs

RegisterAs registers a service factory resolving to a different concrete type.

Parameters

b

factory

func() T

lifetime

...Lifetime

pkg/di/container.go:97-106

func RegisterAs[T any](b *Builder, factory func() T, lifetime ...Lifetime)

{
	lt := Singleton
	if len(lifetime) > 0 {
		lt = lifetime[0]
	}
	typ := reflect.TypeOf((*T)(nil)).Elem()
	b.mu.Lock()
	b.services[typ] = &serviceEntry{lifetime: lt, factory: factory, concreteType: typ}
	b.mu.Unlock()
}

F

function

RegisterInstance

RegisterInstance registers a pre-created instance as a singleton.

Parameters

b

instance

T

pkg/di/container.go:109-120

func RegisterInstance[T any](b *Builder, instance T)

{
	typ := reflect.TypeOf((*T)(nil)).Elem()
	b.mu.Lock()
	b.services[typ] = &serviceEntry{
		lifetime:     Singleton,
		concreteType: typ,
		factory:      func() T { return instance },
		built:        true,
		instance:     instance,
	}
	b.mu.Unlock()
}

F

function

RegisterImpl

RegisterImpl registers a concrete type T that satisfies interface I.

Parameters

b

lifetime

...Lifetime

pkg/di/container.go:123-133

func RegisterImpl[I, T any](b *Builder, lifetime ...Lifetime)

{
	lt := Singleton
	if len(lifetime) > 0 {
		lt = lifetime[0]
	}
	iTyp := reflect.TypeOf((*I)(nil)).Elem()
	tTyp := reflect.TypeOf((*T)(nil)).Elem()
	b.mu.Lock()
	b.services[iTyp] = &serviceEntry{lifetime: lt, factory: nil, concreteType: tTyp}
	b.mu.Unlock()
}

F

function

RegisterFromFunc

RegisterFromFunc registers a type using a constructor function whose
parameters are auto-resolved from the container at resolution time.
T is the return type. The constructor must accept resolvable types.
Build() validates that all parameter types are registered.
RegisterFromFunc registers a service by constructor function with dependency injection.

Parameters

b

constructor

any

lifetime

...Lifetime

pkg/di/container.go:140-166

func RegisterFromFunc[T any](b *Builder, constructor any, lifetime ...Lifetime)

{
	lt := Singleton
	if len(lifetime) > 0 {
		lt = lifetime[0]
	}
	typ := reflect.TypeOf((*T)(nil)).Elem()

	ctorType := reflect.TypeOf(constructor)
	if ctorType.Kind() != reflect.Func {
		panic("di: RegisterFromFunc requires a function")
	}
	if ctorType.NumOut() == 0 {
		panic("di: RegisterFromFunc: constructor must return a value")
	}

	paramTypes := make([]reflect.Type, ctorType.NumIn())
	for i := 0; i < ctorType.NumIn(); i++ {
		paramTypes[i] = ctorType.In(i)
	}

	b.mu.Lock()
	b.services[typ] = &serviceEntry{
		lifetime: lt, factory: nil, concreteType: typ,
		constructor: constructor, paramTypes: paramTypes,
	}
	b.mu.Unlock()
}

F

function

ResolveType

ResolveType resolves a service from the container, panicking on failure.

Parameters

c

Returns

T

pkg/di/container.go:259-265

func ResolveType[T any](c *Container) T

{
	result, err := tryResolveType(c, reflect.TypeOf((*T)(nil)).Elem())
	if err != nil {
		panic(err.Error())
	}
	return result.Interface().(T)
}

F

function

TryResolveType

TryResolveType resolves a service from the container, returning an error on failure.

Parameters

c

Returns

T

error

pkg/di/container.go:268-275

func TryResolveType[T any](c *Container) (T, error)

{
	var zero T
	result, err := tryResolveType(c, reflect.TypeOf((*T)(nil)).Elem())
	if err != nil {
		return zero, err
	}
	return result.Interface().(T), nil
}

F

function

tryResolveType

Parameters

c

typ

reflect.Type

Returns

error

pkg/di/container.go:277-354

func tryResolveType(c *Container, typ reflect.Type) (reflect.Value, error)

{
	c.mu.RLock()
	entry, ok := c.services[typ]
	c.mu.RUnlock()

	if !ok {
		if c.parent != nil {
			return tryResolveType(c.parent, typ)
		}
		return reflect.Value{}, &ResolveError{Type: typ}
	}

	c.muResolve.Lock()
	if _, resolving := c.resolving[typ]; resolving {
		c.muResolve.Unlock()
		return reflect.Value{}, fmt.Errorf("di: circular dependency detected for type %v", typ)
	}
	c.resolving[typ] = struct{}{}
	c.muResolve.Unlock()

	defer func() {
		c.muResolve.Lock()
		delete(c.resolving, typ)
		c.muResolve.Unlock()
	}()

	switch entry.lifetime {
	case Singleton:
		if entry.built {
			return reflect.ValueOf(entry.instance), nil
		}
		c.mu.Lock()
		if entry.built {
			c.mu.Unlock()
			return reflect.ValueOf(entry.instance), nil
		}
		c.mu.Unlock()
		result, err := invokeEntry(c, entry)
		if err != nil {
			return reflect.Value{}, err
		}
		c.mu.Lock()
		entry.instance = result.Interface()
		entry.built = true
		c.mu.Unlock()
		c.trackCloser(entry.instance)
		return result, nil
	case Transient:
		result, err := invokeEntry(c, entry)
		if err != nil {
			return reflect.Value{}, err
		}
		c.trackCloser(result.Interface())
		return result, nil
	case Scoped:
		if entry.built {
			return reflect.ValueOf(entry.instance), nil
		}
		c.mu.Lock()
		if entry.built {
			c.mu.Unlock()
			return reflect.ValueOf(entry.instance), nil
		}
		c.mu.Unlock()
		result, err := invokeEntry(c, entry)
		if err != nil {
			return reflect.Value{}, err
		}
		c.mu.Lock()
		entry.instance = result.Interface()
		entry.built = true
		c.mu.Unlock()
		c.trackCloser(entry.instance)
		return result, nil
	default:
		return reflect.Value{}, &ResolveError{Type: typ}
	}
}

F

function

invokeEntry

Parameters

c

entry

*serviceEntry

Returns

error

pkg/di/container.go:385-394

func invokeEntry(c *Container, entry *serviceEntry) (reflect.Value, error)

{
	if entry.constructor != nil && entry.paramTypes != nil {
		return invokeConstructor(c, entry)
	}
	if entry.factory != nil {
		results := reflect.ValueOf(entry.factory).Call(nil)
		return results[0], nil
	}
	return constructValue(c, entry.concreteType)
}

F

function

invokeConstructor

Parameters

c

entry

*serviceEntry

Returns

error

pkg/di/container.go:396-408

func invokeConstructor(c *Container, entry *serviceEntry) (reflect.Value, error)

{
	ctorVal := reflect.ValueOf(entry.constructor)
	args := make([]reflect.Value, len(entry.paramTypes))
	for i, pt := range entry.paramTypes {
		resolved, err := resolveByType(c, pt)
		if err != nil {
			return reflect.Value{}, fmt.Errorf("di: cannot resolve param %d (%v) of constructor for %v: %w", i, pt, entry.concreteType, err)
		}
		args[i] = resolved
	}
	results := ctorVal.Call(args)
	return results[0], nil
}

F

function

constructValue

Parameters

c

typ

reflect.Type

Returns

error

pkg/di/container.go:410-453

func constructValue(c *Container, typ reflect.Type) (reflect.Value, error)

{
	if typ.Kind() == reflect.Ptr {
		typ = typ.Elem()
	}
	if typ.Kind() != reflect.Struct {
		return reflect.Value{}, fmt.Errorf("di: auto-construction requires struct type, got %v", typ)
	}

	val := reflect.New(typ)

	ctorVal := val.MethodByName("Init")
	if ctorVal.IsValid() {
		ctorType := ctorVal.Type()
		args := make([]reflect.Value, ctorType.NumIn())
		for i := 0; i < ctorType.NumIn(); i++ {
			resolved, err := resolveByType(c, ctorType.In(i))
			if err != nil {
				return reflect.Value{}, fmt.Errorf("di: cannot resolve param %d of Init: %w", i, err)
			}
			args[i] = resolved
		}
		ctorVal.Call(args)
	} else {
		elem := val.Elem()
		for i := 0; i < typ.NumField(); i++ {
			field := typ.Field(i)
			tag := field.Tag.Get("inject")
			if tag == "" && !field.Anonymous {
				continue
			}
			fieldVal := elem.Field(i)
			if !fieldVal.CanSet() || !field.IsExported() {
				continue
			}
			resolved, err := resolveByType(c, fieldVal.Type())
			if err != nil {
				return reflect.Value{}, fmt.Errorf("di: cannot resolve field %s: %w", field.Name, err)
			}
			fieldVal.Set(resolved)
		}
	}

	return val, nil
}

F

function

resolveByType

Parameters

c

typ

reflect.Type

Returns