do

Example:

do.MustShutdown[*Database](injector)

Example ¶

injector := New()

Provide(injector, lifecycleTestServiceProvider)
_, _ = Invoke[*lifecycleTestService](injector)

// This will panic if shutdown fails
MustShutdown[*lifecycleTestService](injector)
fmt.Println("shutdown completed")

Output:

shutdown completed

func MustShutdownNamed ¶

func MustShutdownNamed(i Injector, name string)

MustShutdownNamed stops a named service. It panics on error. This function performs a graceful shutdown on a service with the specified name. If the shutdown fails, this function will panic.

Parameters:

i: The injector containing the service
name: The name of the service to shutdown

Panics if the shutdown fails.

Example:

do.MustShutdownNamed(injector, "main-database")

Example ¶

injector := New()

ProvideNamed(injector, "main-database", lifecycleTestServiceProvider)
_, _ = InvokeNamed[*lifecycleTestService](injector, "main-database")

// This will panic if shutdown fails
MustShutdownNamed(injector, "main-database")
fmt.Println("shutdown completed")

Output:

shutdown completed

func MustShutdownNamedWithContext ¶

func MustShutdownNamedWithContext(ctx context.Context, i Injector, name string)

MustShutdownNamedWithContext stops a named service. It panics on error. This function performs a graceful shutdown on a service with the specified name and context support for timeout and cancellation. If the shutdown fails, this function will panic.

Parameters:

ctx: Context for cancellation and timeout control
i: The injector containing the service
name: The name of the service to shutdown

Panics if the shutdown fails.

Example:

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

do.MustShutdownNamedWithContext(ctx, injector, "main-database")

Example ¶

injector := New()

ProvideNamed(injector, "main-database", lifecycleTestServiceProvider)
_, _ = InvokeNamed[*lifecycleTestService](injector, "main-database")

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// This will panic if shutdown fails
MustShutdownNamedWithContext(ctx, injector, "main-database")
fmt.Println("shutdown completed")

Output:

shutdown completed

func MustShutdownWithContext ¶

func MustShutdownWithContext[T any](ctx context.Context, i Injector)

MustShutdownWithContext stops a service, using type inference to determine the service name. It panics on error. This function performs a graceful shutdown on a service with context support for timeout and cancellation. If the shutdown fails, this function will panic.

Parameters:

ctx: Context for cancellation and timeout control
i: The injector containing the service

Panics if the shutdown fails.

Example:

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

do.MustShutdownWithContext[*Database](ctx, injector)

Example ¶

injector := New()

Provide(injector, lifecycleTestServiceProvider)
_, _ = Invoke[*lifecycleTestService](injector)

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// This will panic if shutdown fails
MustShutdownWithContext[*lifecycleTestService](ctx, injector)
fmt.Println("shutdown completed")

Output:

shutdown completed

func NameOf ¶

func NameOf[T any]() string

NameOf returns the name of the service in the DI container. This is highly discouraged to use this function, as your code should not declare any dependency explicitly.

The function uses type inference to determine the service name based on the generic type parameter T.

Play: https://go.dev/play/p/g549GqBbj-n

Example:

serviceName := do.NameOf[*Database]()

Example ¶

type exampleService struct {
	Name string
}

name := NameOf[*exampleService]()

fmt.Println(name)

Output:

*gitee.com/supos-community-edition/di/v2.exampleService

func Override ¶

func Override[T any](i Injector, provider Provider[T])

Override replaces the service in the DI container, using type inference to determine the service name. Warning: this will not unload/shutdown the previously invoked service.

This function is useful for testing or when you need to replace a service that has already been registered. However, be cautious as it may lead to resource leaks if the original service was already instantiated.

Play: https://go.dev/play/p/g549GqBbj-n

Example ¶

type exampleService struct {
	Name string
}

injector := New()

Provide(injector, func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "test-service"}, nil
})
Override(injector, func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "overridden-service"}, nil
})
service, _ := Invoke[*exampleService](injector)

fmt.Println(service.Name)

Output:

overridden-service

func OverrideNamed ¶

func OverrideNamed[T any](i Injector, name string, provider Provider[T])

OverrideNamed replaces the named service in the DI container. Warning: this will not unload/shutdown the previously invoked service.

This function allows you to replace a specific named service that has already been registered. Use with caution to avoid resource leaks.

Play: https://go.dev/play/p/-gNF1BUEB5Q

Example ¶

type exampleService struct {
	Name string
}

injector := New()

ProvideNamed(injector, "my-service", func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "test-service"}, nil
})
OverrideNamed(injector, "my-service", func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "overridden-named-service"}, nil
})
service, _ := InvokeNamed[*exampleService](injector, "my-service")

fmt.Println(service.Name)

Output:

overridden-named-service

func OverrideNamedTransient ¶

func OverrideNamedTransient[T any](i Injector, name string, provider Provider[T])

OverrideNamedTransient replaces the named factory in the DI container. Warning: this will not unload/shutdown the previously invoked service.

This function allows you to replace a specific named transient service factory. Since transient services are recreated on each request, this is generally safer than overriding lazy or eager services.

Play: https://go.dev/play/p/_wYwBADbCaN

Example ¶

type exampleService struct {
	Name string
}

injector := New()

ProvideNamed(injector, "my-service", func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "test-service"}, nil
})
OverrideNamedTransient(injector, "my-service", func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "overridden-service"}, nil
})
service1, _ := InvokeNamed[*exampleService](injector, "my-service")
service2, _ := InvokeNamed[*exampleService](injector, "my-service")

fmt.Println(service1 != service2)

Output:

true

func OverrideNamedValue ¶

func OverrideNamedValue[T any](i Injector, name string, value T)

OverrideNamedValue replaces the named value in the DI container. Warning: this will not unload/shutdown the previously invoked service.

This function allows you to replace a specific named value service. Use with caution to avoid resource leaks.

Play: https://go.dev/play/p/-gNF1BUEB5Q

Example ¶

type exampleService struct {
	Name string
}

injector := New()

ProvideNamed(injector, "my-service", func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "test-service"}, nil
})
OverrideNamedValue(injector, "my-service", &exampleService{Name: "overridden-named-value-service"})
service, _ := InvokeNamed[*exampleService](injector, "my-service")

fmt.Println(service.Name)

Output:

overridden-named-value-service

func OverrideTransient ¶

func OverrideTransient[T any](i Injector, provider Provider[T])

OverrideTransient replaces the factory in the DI container, using type inference to determine the service name. Warning: this will not unload/shutdown the previously invoked service.

This function replaces an existing transient service factory with a new one. Since transient services are recreated on each request, this is generally safer than overriding lazy or eager services.

Play: https://go.dev/play/p/_wYwBADbCaN

Example ¶

type exampleService struct {
	Name string
}

injector := New()

Provide(injector, func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "test-service"}, nil
})
OverrideTransient(injector, func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "overridden-service"}, nil
})
service1, _ := Invoke[*exampleService](injector)
service2, _ := Invoke[*exampleService](injector)

fmt.Println(service1 != service2)

Output:

true

func OverrideValue ¶

func OverrideValue[T any](i Injector, value T)

OverrideValue replaces the value in the DI container, using type inference to determine the service name. Warning: this will not unload/shutdown the previously invoked service.

This function replaces an existing value service with a new one. The old value will not be properly cleaned up if it was already instantiated.

Play: https://go.dev/play/p/-gNF1BUEB5Q

Example ¶

type exampleService struct {
	Name string
}

injector := New()

Provide(injector, func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "test-service"}, nil
})
OverrideValue(injector, &exampleService{Name: "overridden-value-service"})
service, _ := Invoke[*exampleService](injector)

fmt.Println(service.Name)

Output:

overridden-value-service

func Package ¶

func Package(services ...func(i Injector)) func(Injector)

Package creates a function that executes multiple service registration functions. This function is used to group related service registrations into reusable packages that can be applied to any injector instance.

Parameters:

services: Variable number of service registration functions to execute

Returns a function that can be passed to New(), NewWithOpts(), or Scope() to register all services.

Play: https://go.dev/play/p/kmf8aOVyj96

Example:

	 // pkg/database/package.go
		// Create a global `Package` variable
		var Package = do.Package(
		    do.Lazy[*Database](func(i do.Injector) (*Database, error) {
		        return &Database{}, nil
		    }),
		    do.Lazy[*ConnectionPool](func(i do.Injector) (*ConnectionPool, error) {
		        return &ConnectionPool{}, nil
		    }),
         ...
		)

	 // main.go
		// Apply the package to an injector
		injector := do.New(database.Package)

func Provide ¶

func Provide[T any](i Injector, provider Provider[T])

Provide registers a service in the DI container, using type inference. The service will be lazily instantiated when first requested.

Play: https://go.dev/play/p/4JutUJ5Rqau

Example:

do.Provide(injector, func(i do.Injector) (*MyService, error) {
    return &MyService{...}, nil
})

Example ¶

type exampleService struct {
	Name string
}

injector := New()

Provide(injector, func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "test-service"}, nil
})
service, err := Invoke[*exampleService](injector)

fmt.Println(err)
fmt.Println(service.Name)

Output:

<nil>
test-service

func ProvideNamed ¶

func ProvideNamed[T any](i Injector, name string, provider Provider[T])

ProvideNamed registers a named service in the DI container. This allows you to register multiple services of the same type with different names for disambiguation.

The service will be lazily instantiated when first requested.

Play: https://go.dev/play/p/9JuTQhLGIlh

Example:

do.ProvideNamed(injector, "main-db", func(i do.Injector) (*Database, error) {
    return &Database{URL: "postgres://main.acme.dev:5432/db"}, nil
})
do.ProvideNamed(injector, "backup-db", func(i do.Injector) (*Database, error) {
    return &Database{URL: "postgres://backup.acme.dev:5432/db"}, nil
})

Example ¶

type exampleService struct {
	Name string
}

injector := New()

ProvideNamed(injector, "my-service", func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "test-service"}, nil
})
service, err := InvokeNamed[*exampleService](injector, "my-service")

fmt.Println(err)
fmt.Println(service.Name)

Output:

<nil>
test-service

func ProvideNamedTransient ¶

func ProvideNamedTransient[T any](i Injector, name string, provider Provider[T])

ProvideNamedTransient registers a named factory in the DI container. This allows you to register multiple transient services of the same type with different names for disambiguation.

The service will be recreated each time it is requested, providing a fresh instance.

Example:

// Each invocation creates a new instance
do.ProvideNamedTransient(injector, "request-id", func(i do.Injector) (string, error) {
    return uuid.New().String(), nil
})

// First invocation
id1, _ := do.InvokeNamed[string](injector, "request-id")
// Second invocation - different instance
id2, _ := do.InvokeNamed[string](injector, "request-id")

fmt.Println(id1 != id2) // Output: true

Example ¶

type exampleService struct {
	Name string
}

injector := New()

ProvideNamedTransient(injector, "transient-service", func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "test-service"}, nil
})
service1, _ := InvokeNamed[*exampleService](injector, "transient-service")
service2, _ := InvokeNamed[*exampleService](injector, "transient-service")

fmt.Println(service1 != service2)

Output:

true

func ProvideNamedValue ¶

func ProvideNamedValue[T any](i Injector, name string, value T)

ProvideNamedValue registers a named value in the DI container. This allows you to register multiple values of the same type with different names for disambiguation.

The value is immediately available and will not be recreated on each request.

Example:

do.ProvideNamedValue(injector, "app-config", &Config{Port: 8080})
do.ProvideNamedValue(injector, "db-config", &Config{Port: 5432})

Example ¶

type exampleService struct {
	Name string
}

injector := New()

service := &exampleService{Name: "named-eager-service"}
ProvideNamedValue(injector, "my-eager-service", service)
retrieved, err := InvokeNamed[*exampleService](injector, "my-eager-service")

fmt.Println(err)
fmt.Println(retrieved.Name)

Output:

<nil>
named-eager-service

func ProvideTransient ¶

func ProvideTransient[T any](i Injector, provider Provider[T])

ProvideTransient registers a factory in the DI container, using type inference to determine the service name. The service will be recreated each time it is requested, providing a fresh instance.

Play: https://go.dev/play/p/hzOJwtNXwT9

Example:

// Each invocation creates a new instance
do.ProvideTransient(injector, func(i do.Injector) (string, error) {
    return uuid.New().String(), nil
})

// First invocation
id1, _ := do.Invoke[string](injector)
// Second invocation - different instance
id2, _ := do.Invoke[string](injector)

fmt.Println(id1 != id2) // Output: true

Example ¶

type exampleService struct {
	Name string
}

injector := New()

ProvideTransient(injector, func(i Injector) (*exampleService, error) {
	return &exampleService{Name: "test-service"}, nil
})
service1, _ := Invoke[*exampleService](injector)
service2, _ := Invoke[*exampleService](injector)

fmt.Println(service1 != service2)

Output:

true

func ProvideValue ¶

func ProvideValue[T any](i Injector, value T)

ProvideValue registers a value in the DI container, using type inference to determine the service name. The value is immediately available and will not be recreated on each request.

Play: https://go.dev/play/p/5TOSiI-c17Y

Example:

ProvideValue(injector, &MyService{})

Example ¶

type exampleService struct {
	Name string
}

injector := New()

service := &exampleService{Name: "eager-service"}
ProvideValue(injector, service)
retrieved, err := Invoke[*exampleService](injector)

fmt.Println(err)
fmt.Println(retrieved.Name)

Output:

<nil>
eager-service

func Shutdown ¶

func Shutdown[T any](i Injector) error

Shutdown stops a service, using type inference to determine the service name. This function performs a graceful shutdown on a service by inferring its name from the type T. The service must implement one of the Shutdowner interfaces.

Parameters:

i: The injector containing the service

Returns an error if the shutdown fails, or nil if the shutdown was successful.

Play: https://go.dev/play/p/uOvsiVWa9_R

Example:

err := do.Shutdown[*Database](injector)
if err != nil {
    log.Printf("Database shutdown failed: %v", err)
}

Example ¶

injector := New()

Provide(injector, lifecycleTestServiceProvider)
_, _ = Invoke[*lifecycleTestService](injector)

err := Shutdown[*lifecycleTestService](injector)
fmt.Println(err)

Output:

<nil>

func ShutdownNamed ¶

func ShutdownNamed(i Injector, name string) error

ShutdownNamed stops a named service. This function performs a graceful shutdown on a service with the specified name. The service must implement one of the Shutdowner interfaces.

Parameters:

i: The injector containing the service
name: The name of the service to shutdown

Returns an error if the shutdown fails, or nil if the shutdown was successful.

Play: https://go.dev/play/p/qAaIo5dWz7J

Example:

err := do.ShutdownNamed(injector, "main-database")
if err != nil {
    log.Printf("Main database shutdown failed: %v", err)
}

Example ¶

injector := New()

ProvideNamed(injector, "main-database", lifecycleTestServiceProvider)
_, _ = InvokeNamed[*lifecycleTestService](injector, "main-database")

err := ShutdownNamed(injector, "main-database")
fmt.Println(err)

Output:

<nil>

func ShutdownNamedWithContext ¶

func ShutdownNamedWithContext(ctx context.Context, i Injector, name string) error

ShutdownNamedWithContext stops a named service with context support. This function performs a graceful shutdown on a service with the specified name and context support for timeout and cancellation. The service must implement one of the Shutdowner interfaces.

Parameters:

ctx: Context for cancellation and timeout control
i: The injector containing the service
name: The name of the service to shutdown

Returns an error if the shutdown fails, or nil if the shutdown was successful.

Example:

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

err := do.ShutdownNamedWithContext(ctx, injector, "main-database")
if err != nil {
    log.Printf("Main database shutdown failed: %v", err)
}

Example ¶

injector := New()

ProvideNamed(injector, "main-database", lifecycleTestServiceProvider)
_, _ = InvokeNamed[*lifecycleTestService](injector, "main-database")

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

err := ShutdownNamedWithContext(ctx, injector, "main-database")
fmt.Println(err)

Output:

<nil>

func ShutdownWithContext ¶

func ShutdownWithContext[T any](ctx context.Context, i Injector) error

ShutdownWithContext stops a service, using type inference to determine the service name. This function performs a graceful shutdown on a service with context support for timeout and cancellation. The service must implement one of the Shutdowner interfaces.

Parameters:

ctx: Context for cancellation and timeout control
i: The injector containing the service

Returns an error if the shutdown fails, or nil if the shutdown was successful.

Play: https://go.dev/play/p/qAaIo5dWz7J

Example:

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

err := do.ShutdownWithContext[*Database](ctx, injector)
if err != nil {
    log.Printf("Database shutdown failed: %v", err)
}

Example ¶

injector := New()

Provide(injector, lifecycleTestServiceProvider)
_, _ = Invoke[*lifecycleTestService](injector)

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

err := ShutdownWithContext[*lifecycleTestService](ctx, injector)
fmt.Println(err)

Output:

<nil>

func Transient ¶

func Transient[T any](p Provider[T]) func(Injector)

Transient creates a function that registers a transient service using the default service name. This function is a convenience wrapper for creating transient service registration functions that can be used in packages.

Parameters:

p: The provider function that creates the service instance

Returns a function that registers the service as transient when executed.

Play: https://go.dev/play/p/M6-wd1qt-GZ

Example:

// Global to a package
var Package = do.Package(
	do.Transient[*Logger](func(i do.Injector) (*Logger, error) {
    	return &Logger{}, nil
	})
)

func TransientNamed ¶

func TransientNamed[T any](serviceName string, p Provider[T]) func(Injector)

TransientNamed creates a function that registers a transient service with a custom name. This function is a convenience wrapper for creating named transient service registration functions that can be used in packages.

Parameters:

serviceName: The custom name for the service
p: The provider function that creates the service instance

Returns a function that registers the service as transient with the specified name when executed.

Play: https://go.dev/play/p/d9IJOAbKRUH

Example:

// Global to a package
var Package = do.Package(
	do.TransientNamed[*Logger]("request-logger", func(i do.Injector) (*Logger, error) {
    	return &Logger{}, nil
	})
)

Types ¶

type DAG ¶

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

DAG represents a Directed Acyclic Graph of services, tracking dependencies and dependents. This type manages the relationships between services to ensure proper initialization order and detect circular dependencies.

The DAG maintains two maps:

dependencies: Maps each service to the services it depends on
dependents: Maps each service to the services that depend on it

Fields:

mu: Read-write mutex for thread-safe access to the graph
dependencies: Map of services to their dependencies
dependents: Map of services to their dependents

type ExplainInjectorOutput ¶

type ExplainInjectorOutput struct {
	ScopeID   string                       `json:"scope_id"`
	ScopeName string                       `json:"scope_name"`
	DAG       []ExplainInjectorScopeOutput `json:"dag"`
}

ExplainInjectorOutput contains detailed information about an injector and its scope hierarchy. This struct provides a comprehensive view of the injector's scope tree, including all services and their relationships.

func ExplainInjector ¶

func ExplainInjector(scope Injector) ExplainInjectorOutput

ExplainInjector returns a human readable description of the injector, with services and scope tree. This function provides a comprehensive view of the injector's structure, including all scopes, services, and their relationships in a hierarchical format.

Parameters:

scope: The injector to explain

Returns a detailed explanation of the injector's structure and contents.

Example:

explanation := do.ExplainInjector(injector)
fmt.Println(explanation.String())

Play: https://go.dev/play/p/mRs4Q7TJ5jj

Output example:

Scope ID: root
Scope name: Root Scope

DAG:
 |\_ Root Scope (ID: root)
 |   * 😴 Database
 |   * 🔁 Config
 |   |\_ API Scope (ID: api)
 |   |   * 🏭 Logger
 |   |   * 🔗 DatabaseInterface

Example ¶

injector := New()

ProvideNamedValue(injector, "value", 42)
ProvideNamed(injector, "service1", newExplainTestService)
ProvideNamedValue(injector, "service2", "value")

explanation := ExplainInjector(injector)
fmt.Println(explanation.ScopeName)
fmt.Println(len(explanation.DAG))

Output:

[root]
1

func (*ExplainInjectorOutput) String ¶

func (id *ExplainInjectorOutput) String() string

String returns a formatted string representation of the injector explanation. This method provides a human-readable description of the injector including its scope hierarchy and all services in a tree-like format.

Returns a formatted string describing the injector and its scope hierarchy.

type ExplainInjectorScopeOutput ¶

type ExplainInjectorScopeOutput struct {
	ScopeID   string                         `json:"scope_id"`
	ScopeName string                         `json:"scope_name"`
	Scope     Injector                       `json:"scope"`
	Services  []ExplainInjectorServiceOutput `json:"services"`
	Children  []ExplainInjectorScopeOutput   `json:"children"`

	IsAncestor bool `json:"is_ancestor"`
	IsChildren bool `json:"is_children"`
}

ExplainInjectorScopeOutput contains information about a single scope in the injector hierarchy. This struct represents a scope and its services, along with its position in the scope tree.

func (*ExplainInjectorScopeOutput) String ¶

func (ids *ExplainInjectorScopeOutput) String() string

String returns a formatted string representation of the scope. This method provides a human-readable description of the scope including its services and child scopes.

Returns a formatted string describing the scope.

type ExplainInjectorServiceOutput ¶

type ExplainInjectorServiceOutput struct {
	ServiceName      string        `json:"service_name"`
	ServiceType      ServiceType   `json:"service_type"`
	ServiceTypeIcon  string        `json:"service_type_icon"`
	ServiceBuildTime time.Duration `json:"service_build_time,omitempty"`
	IsHealthchecker  bool          `json:"is_healthchecker"`
	IsShutdowner     bool          `json:"is_shutdowner"`
}

ExplainInjectorServiceOutput contains information about a service in the scope explanation. This struct provides details about a service's type, capabilities, and lifecycle state.

func (*ExplainInjectorServiceOutput) String ¶

func (idss *ExplainInjectorServiceOutput) String() string

String returns a formatted string representation of the service. This method provides a human-readable description of the service including its type icon and capabilities indicators.

Returns a formatted string describing the service.

type ExplainServiceDependencyOutput ¶

type ExplainServiceDependencyOutput struct {
	ScopeID   string                           `json:"scope_id"`
	ScopeName string                           `json:"scope_name"`
	Service   string                           `json:"service"`
	Recursive []ExplainServiceDependencyOutput `json:"recursive"`
}

ExplainServiceDependencyOutput contains information about a service dependency relationship. This struct represents either a dependency (service this depends on) or a dependent (service that depends on this) in the dependency graph.

Fields:

ScopeID: The unique identifier of the scope containing the related service
ScopeName: The human-readable name of the scope containing the related service
Service: The name of the related service
Recursive: Nested dependency relationships (for transitive dependencies)

func (*ExplainServiceDependencyOutput) String ¶

func (sdd *ExplainServiceDependencyOutput) String() string

String returns a formatted string representation of the dependency relationship. This method provides a human-readable description of the dependency, including nested recursive dependencies with proper indentation.

Returns a formatted string describing the dependency relationship.

type ExplainServiceOutput ¶

type ExplainServiceOutput struct {
	ScopeID          string                           `json:"scope_id"`
	ScopeName        string                           `json:"scope_name"`
	ServiceName      string                           `json:"service_name"`
	ServiceType      ServiceType                      `json:"service_type"`
	ServiceBuildTime time.Duration                    `json:"service_build_time,omitempty"`
	Invoked          *stacktrace.Frame                `json:"invoked"`
	Dependencies     []ExplainServiceDependencyOutput `json:"dependencies"`
	Dependents       []ExplainServiceDependencyOutput `json:"dependents"`
}

ExplainServiceOutput contains detailed information about a service for debugging and analysis. This struct provides comprehensive information about a service's location, type, dependencies, and lifecycle state.

func ExplainNamedService ¶

func ExplainNamedService(scope Injector, name string) (description ExplainServiceOutput, ok bool)

ExplainNamedService returns a human readable description of the service by name. This function provides detailed information about a service including its scope, type, dependencies, and lifecycle state. The service must be registered before calling this function.

Parameters:

scope: The injector to search for the service
name: The name of the service to explain

Returns a service explanation and a boolean indicating if the service was found. The boolean is false if the service is not found.

Note: Please call Invoke[T] before ExplainNamedService[T] to ensure that the service is registered.

Play: https://go.dev/play/p/GTcGyPFC8IB

Example:

// First invoke the service to ensure it's registered
	db := do.MustInvokeNamed[*Database](injector, "main-db")

// Then explain it
	explanation, found := do.ExplainNamedService(injector, "main-db")
	if found {
	    fmt.Println(explanation.String())
	}

Example ¶

injector := New()

ProvideNamedValue(injector, "value", 42)
ProvideNamed(injector, "my-service", newExplainTestService)
_, _ = InvokeNamed[*explainTestService](injector, "my-service")

explanation, found := ExplainNamedService(injector, "my-service")

// to prevent flakiness
explanation.ScopeID = "980e2f60-d340-4776-86dd-6aa1d3c27860"
explanation.ServiceBuildTime = 10 * time.Millisecond
explanation.Invoked = &stacktrace.Frame{
	Function: "newExplainTestService",
	File:     "di_explain_example_test.go", // remove absolute path
	Line:     42,
}

fmt.Println(found)
fmt.Println(explanation.ServiceName)
fmt.Println(explanation.ServiceType)
fmt.Println(explanation.String())

Output:

true
my-service
lazy

Scope ID: 980e2f60-d340-4776-86dd-6aa1d3c27860
Scope name: [root]

Service name: my-service
Service type: lazy
Service build time: 10ms
Invoked: di_explain_example_test.go:newExplainTestService:42

Dependencies:
* value from scope [root]

Dependents:

func ExplainService ¶

func ExplainService[T any](i Injector) (description ExplainServiceOutput, ok bool)

ExplainService returns a human readable description of the service. This function provides detailed information about a service including its scope, type, dependencies, and lifecycle state. The service must be registered before calling this function.

Parameters:

i: The injector to search for the service

Returns a service explanation and a boolean indicating if the service was found. The boolean is false if the service is not found.

Note: Please call Invoke[T] before ExplainService[T] to ensure that the service is registered.

Play: https://go.dev/play/p/Eii-vX9Rc-a

Example:

// First invoke the service to ensure it's registered
	db := do.MustInvoke[*Database](injector)

// Then explain it
	explanation, found := do.ExplainService[*Database](injector)
	if found {
		fmt.Println(explanation.String())
	}

Example ¶

injector := New()

ProvideNamedValue(injector, "value", 42)
Provide(injector, newExplainTestService)
_, _ = Invoke[*explainTestService](injector)

explanation, found := ExplainService[*explainTestService](injector)

// to prevent flakiness
explanation.ScopeID = "980e2f60-d340-4776-86dd-6aa1d3c27860"
explanation.ServiceBuildTime = 10 * time.Millisecond
explanation.Invoked = &stacktrace.Frame{
	Function: "newExplainTestService",
	File:     "di_explain_example_test.go", // remove absolute path
	Line:     42,
}

fmt.Println(found)
fmt.Println(explanation.ServiceName)
fmt.Println(explanation.ServiceType)
fmt.Println(explanation.String())

Output:

true
*gitee.com/supos-community-edition/di/v2.explainTestService
lazy

Scope ID: 980e2f60-d340-4776-86dd-6aa1d3c27860
Scope name: [root]

Service name: *gitee.com/supos-community-edition/di/v2.explainTestService
Service type: lazy
Service build time: 10ms
Invoked: di_explain_example_test.go:newExplainTestService:42

Dependencies:
* value from scope [root]

Dependents:

func (*ExplainServiceOutput) String ¶

func (sd *ExplainServiceOutput) String() string

String returns a formatted string representation of the service explanation. This method provides a human-readable description of the service including its scope, type, build time, and dependency relationships.

Returns a formatted string describing the service.

type Healthchecker ¶

type Healthchecker interface {
	HealthCheck() error
}

Healthchecker is an interface that services can implement to provide health checking capabilities. Services implementing this interface can be health-checked by the DI container to ensure they are functioning correctly.

The HealthCheck method should perform a quick check to verify the service is healthy. It should return nil if the service is healthy, or an error describing the health issue.

Example:

type Database struct {
    conn *sql.DB
}

func (db *Database) HealthCheck() error {
    return db.conn.Ping()
}

type HealthcheckerWithContext ¶

type HealthcheckerWithContext interface {
	HealthCheck(context.Context) error
}

HealthcheckerWithContext is an interface that services can implement to provide health checking capabilities with context support. This allows for timeout and cancellation control during health checks.

The HealthCheck method should perform a quick check to verify the service is healthy. It should respect the provided context for cancellation and timeout. It should return nil if the service is healthy, or an error describing the health issue.

Example:

type Database struct {
    conn *sql.DB
}

func (db *Database) HealthCheck(ctx context.Context) error {
    return db.conn.PingContext(ctx)
}

type Injector ¶

type Injector interface {

	// ID returns the unique identifier of the injector.
	ID() string

	// Name returns the human-readable name of the injector.
	Name() string

	// Scope creates a new child scope with the given name.
	// Optional package functions can be provided to execute during scope creation.
	Scope(string, ...func(Injector)) *Scope

	// RootScope returns the root scope of the injector hierarchy.
	RootScope() *RootScope

	// Ancestors returns the list of all parent scopes in order from immediate parent to root.
	Ancestors() []*Scope

	// Children returns the list of immediate child scopes.
	Children() []*Scope

	// ChildByID searches for a child scope by its unique ID across the entire scope hierarchy.
	ChildByID(string) (*Scope, bool)

	// ChildByName searches for a child scope by its name across the entire scope hierarchy.
	ChildByName(string) (*Scope, bool)

	// ListProvidedServices returns all services available in the current scope and all its ancestor scopes.
	ListProvidedServices() []ServiceDescription

	// ListInvokedServices returns only the services that have been actually invoked in the current scope and its ancestors.
	ListInvokedServices() []ServiceDescription

	// HealthCheck performs health checks on all services in the current scope and its ancestors.
	HealthCheck() map[string]error

	// HealthCheckWithContext performs health checks with context support for cancellation and timeouts.
	HealthCheckWithContext(context.Context) map[string]error

	// Shutdown gracefully shuts down the injector and all its descendant scopes.
	Shutdown() *ShutdownReport

	// ShutdownWithContext gracefully shuts down the injector and all its descendant scopes with context support.
	ShutdownWithContext(context.Context) *ShutdownReport
	// contains filtered or unexported methods
}

Injector is the main interface for dependency injection containers. It provides methods for service registration, resolution, lifecycle management, and scope hierarchy management.

The Injector interface is implemented by both RootScope and Scope types, allowing for a consistent API across different levels of the scope hierarchy.

type InjectorOpts ¶

type InjectorOpts struct {
	// HookBeforeRegistration is called before a service is registered in a scope.
	// This hook can be used for validation, logging, or other pre-registration tasks.
	HookBeforeRegistration []func(scope *Scope, serviceName string)

	// HookAfterRegistration is called after a service is successfully registered in a scope.
	// This hook can be used for logging, metrics collection, or other post-registration tasks.
	HookAfterRegistration []func(scope *Scope, serviceName string)

	// HookBeforeInvocation is called before a service is invoked (instantiated).
	// This hook can be used for logging, metrics, or other pre-invocation tasks.
	HookBeforeInvocation []func(scope *Scope, serviceName string)

	// HookAfterInvocation is called after a service is invoked, with the result error.
	// This hook can be used for logging, metrics collection, or error handling.
	HookAfterInvocation []func(scope *Scope, serviceName string, err error)

	// HookBeforeShutdown is called before a service is shut down.
	// This hook can be used for cleanup preparation or logging.
	HookBeforeShutdown []func(scope *Scope, serviceName string)

	// HookAfterShutdown is called after a service is shut down, with the result error.
	// This hook can be used for logging, metrics collection, or error handling.
	HookAfterShutdown []func(scope *Scope, serviceName string, err error)

	// Logf is the logging function used by the DI container for internal logging.
	// If not provided, no logging will occur. This function should handle the format
	// string and arguments similar to fmt.Printf.
	Logf func(format string, args ...any)

	// HealthCheckParallelism controls the number of concurrent health checks that can run simultaneously.
	// Default: all health checks run in parallel (unlimited).
	// Setting this to a positive number limits the concurrency for better resource management.
	HealthCheckParallelism uint

	// HealthCheckGlobalTimeout sets a global timeout for all health check operations.
	// This timeout applies to the entire health check process across all services.
	// Default: no timeout (health checks can run indefinitely).
	HealthCheckGlobalTimeout time.Duration

	// HealthCheckTimeout sets a timeout for individual service health checks.
	// This timeout applies to each service's health check method.
	// Default: no timeout (individual health checks can run indefinitely).
	HealthCheckTimeout time.Duration

	// StructTagKey specifies the tag key used for struct field injection.
	// Default: "do" (see DefaultStructTagKey constant).
	// This allows customization of the struct tag format for injection.
	StructTagKey string
}

InjectorOpts contains all configuration options for the dependency injection container. These options control logging, hooks, health checks, and other behavioral aspects of the DI container.

type Provider ¶

type Provider[T any] func(Injector) (T, error)

Provider is a function type that creates and returns a service instance of type T. This is the core abstraction for service creation in the dependency injection container.

The provider function receives an Injector instance that can be used to resolve dependencies for the service being created.

Example:

func NewMyService(i do.Injector) (*MyService, error) {
    db := do.MustInvoke[*Database](i)
    config := do.MustInvoke[*Config](i)
    return &MyService{DB: db, Config: config}, nil
}

// Register the provider
do.Provide(injector, NewMyService)

type RootScope ¶

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

RootScope is the top-level scope in the dependency injection container hierarchy. It serves as the entry point for all DI operations and manages the overall container lifecycle.

Key responsibilities:

Service registration and resolution
Child scope management
Health check coordination
Shutdown orchestration
Dependency graph management

func New ¶

func New(packages ...func(Injector)) *RootScope

New creates a new dependency injection container with default options. This is the primary entry point for creating a new DI container.

Parameters:

packages: Optional package functions to execute during initialization

Returns a new RootScope instance ready for service registration.

Play: https://go.dev/play/p/-Fvet5zLoVY

Example:

injector := do.New()
do.Provide(injector, func(i do.Injector) (*MyService, error) {
    return &MyService{}, nil
})

Example ¶

injector := New()

ProvideNamedValue(injector, "PG_URI", "postgres://user:pass@host:5432/db")
uri, err := InvokeNamed[string](injector, "PG_URI")

fmt.Println(uri)
fmt.Println(err)

Output:

postgres://user:pass@host:5432/db
<nil>

func NewWithOpts ¶

func NewWithOpts(opts *InjectorOpts, packages ...func(Injector)) *RootScope

NewWithOpts creates a new dependency injection container with custom options. This allows you to configure logging, hooks, health check settings, and other options.

Parameters:

opts: Configuration options for the injector
packages: Optional package functions to execute during initialization

Returns a new RootScope instance with the specified configuration.

Play: https://go.dev/play/p/SmhFpWZGKUw

Example:

opts := &do.InjectorOpts{
    Logf: func(format string, args ...any) {
        log.Printf(format, args...)
    },
    HealthCheckParallelism: 10,
}
injector := do.NewWithOpts(opts)

Example ¶

injector := NewWithOpts(&InjectorOpts{
	HookAfterShutdown: []func(scope *Scope, serviceName string, err error){
		func(scope *Scope, serviceName string, err error) {
			fmt.Printf("service shutdown: %s\n", serviceName)
		},
	},
})

ProvideNamed(injector, "PG_URI", func(i Injector) (string, error) {
	return "postgres://user:pass@host:5432/db", nil
})
MustInvokeNamed[string](injector, "PG_URI")
report := injector.Shutdown()
fmt.Println(report.Succeed)
fmt.Println(len(report.Errors))

Output:

service shutdown: PG_URI
true
0

func (*RootScope) AddAfterInvocationHook ¶

func (s *RootScope) AddAfterInvocationHook(hook func(*Scope, string, error))

AddAfterInvocationHook adds a hook that will be called after a service is invoked.

Example ¶

injector := New()

injector.AddAfterInvocationHook(func(scope *Scope, serviceName string, err error) {
	fmt.Printf("invoked service: %s, error: %v\n", serviceName, err)
})

ProvideNamedValue(injector, "test", "value")
_, _ = InvokeNamed[string](injector, "test")

Output:

invoked service: test, error: <nil>

func (*RootScope) AddAfterRegistrationHook ¶

func (s *RootScope) AddAfterRegistrationHook(hook func(*Scope, string))

AddAfterRegistrationHook adds a hook that will be called after a service is registered.

Example ¶

injector := New()

injector.AddAfterRegistrationHook(func(scope *Scope, serviceName string) {
	fmt.Printf("registered service: %s\n", serviceName)
})

ProvideNamedValue(injector, "test", "value")

Output:

registered service: test

func (*RootScope) AddAfterShutdownHook ¶

func (s *RootScope) AddAfterShutdownHook(hook func(*Scope, string, error))

AddAfterShutdownHook adds a hook that will be called after a service is shutdown.

Play: https://go.dev/play/p/FFKDcV0hMJx

Example ¶

injector := New()

injector.AddAfterShutdownHook(func(scope *Scope, serviceName string, err error) {
	fmt.Printf("shut down service: %s, error: %v\n", serviceName, err)
})

ProvideNamedValue(injector, "test", "value")
_ = injector.Shutdown()

Output:

shut down service: test, error: <nil>

func (*RootScope) AddBeforeInvocationHook ¶

func (s *RootScope) AddBeforeInvocationHook(hook func(*Scope, string))

AddBeforeInvocationHook adds a hook that will be called before a service is invoked.

Example ¶

injector := New()

injector.AddBeforeInvocationHook(func(scope *Scope, serviceName string) {
	fmt.Printf("invoking service: %s\n", serviceName)
})

ProvideNamedValue(injector, "test", "value")
_, _ = InvokeNamed[string](injector, "test")

Output:

invoking service: test

func (*RootScope) AddBeforeRegistrationHook ¶

func (s *RootScope) AddBeforeRegistrationHook(hook func(*Scope, string))

AddBeforeRegistrationHook adds a hook that will be called before a service is registered.

Example ¶

injector := New()

injector.AddBeforeRegistrationHook(func(scope *Scope, serviceName string) {
	fmt.Printf("registering service: %s\n", serviceName)
})

ProvideNamedValue(injector, "test", "value")

Output:

registering service: test

func (*RootScope) AddBeforeShutdownHook ¶

func (s *RootScope) AddBeforeShutdownHook(hook func(*Scope, string))

AddBeforeShutdownHook adds a hook that will be called before a service is shutdown.

Play: https://go.dev/play/p/FFKDcV0hMJx

Example ¶

injector := New()

injector.AddBeforeShutdownHook(func(scope *Scope, serviceName string) {
	fmt.Printf("shutting down service: %s\n", serviceName)
})

ProvideNamedValue(injector, "test", "value")
_ = injector.Shutdown()

Output:

shutting down service: test

func (*RootScope) Ancestors ¶

func (s *RootScope) Ancestors() []*Scope

Ancestors returns an empty slice since the root scope has no ancestors.

func (*RootScope) ChildByID ¶

func (s *RootScope) ChildByID(id string) (*Scope, bool)

ChildByID searches for a child scope by its unique ID across the entire scope hierarchy.

func (*RootScope) ChildByName ¶

func (s *RootScope) ChildByName(name string) (*Scope, bool)

ChildByName searches for a child scope by its name across the entire scope hierarchy.

func (*RootScope) Children ¶

func (s *RootScope) Children() []*Scope

Children returns the list of immediate child scopes.

func (*RootScope) Clone ¶

func (s *RootScope) Clone() *RootScope

Clone clones injector with provided services but not with invoked instances.

Play: https://go.dev/play/p/DqIlXhZ8c4t

Example ¶

injector := New()
ProvideNamedValue(injector, "test", "value")

clone := injector.Clone()
services := clone.ListProvidedServices()

fmt.Println(len(services))
fmt.Println(services[0].Service)

Output:

1
test

func (*RootScope) CloneWithOpts ¶

func (s *RootScope) CloneWithOpts(opts *InjectorOpts) *RootScope

CloneWithOpts clones injector with provided services but not with invoked instances, with options.

Play: https://go.dev/play/p/fT-v63fbFk5

Example ¶

injector := New()
ProvideNamedValue(injector, "test", "value")

clone := injector.CloneWithOpts(&InjectorOpts{
	HookAfterShutdown: []func(scope *Scope, serviceName string, err error){
		func(scope *Scope, serviceName string, err error) {
			fmt.Printf("shutdown: %s\n", serviceName)
		},
	},
})

_ = clone.Shutdown()

Output:

shutdown: test

func (*RootScope) HealthCheck ¶

func (s *RootScope) HealthCheck() map[string]error

HealthCheck performs health checks on all services in the root scope and all its descendant scopes.

func (*RootScope) HealthCheckWithContext ¶

func (s *RootScope) HealthCheckWithContext(ctx context.Context) map[string]error

HealthCheckWithContext performs health checks with context support for cancellation and timeouts.

func (*RootScope) ID ¶

func (s *RootScope) ID() string

ID returns the unique identifier of the root scope.

func (*RootScope) InstanceForEach ¶

func (s *RootScope) InstanceForEach(cb func(string, *Scope, any) bool)

func (*RootScope) ListInvokedServices ¶

func (s *RootScope) ListInvokedServices() []ServiceDescription

ListInvokedServices returns all services that have been invoked in the root scope and all its descendant scopes.

func (*RootScope) ListProvidedServices ¶

func (s *RootScope) ListProvidedServices() []ServiceDescription

ListProvidedServices returns all services available in the root scope and all its descendant scopes.

func (*RootScope) Name ¶

func (s *RootScope) Name() string

Name returns the name of the root scope.

func (*RootScope) RootScope ¶

func (s *RootScope) RootScope() *RootScope

RootScope returns the root scope itself (this instance).

func (*RootScope) Scope ¶

func (s *RootScope) Scope(name string, p ...func(Injector)) *Scope

Scope creates a new child scope under the root scope.

func (*RootScope) ServiceExists ¶

func (s *RootScope) ServiceExists(name string) bool

func (*RootScope) ServiceGet ¶

func (s *RootScope) ServiceGet(name string) (any, bool)

func (*RootScope) Shutdown ¶

func (s *RootScope) Shutdown() *ShutdownReport

Shutdown gracefully shuts down the root scope and all its descendant scopes.

func (*RootScope) ShutdownOnSignals ¶

func (s *RootScope) ShutdownOnSignals(signals ...os.Signal) (os.Signal, *ShutdownReport)

ShutdownOnSignals listens for the provided signals in order to gracefully stop services. It will block until receiving any of these signals. If no signal is provided, syscall.SIGTERM and os.Interrupt will be handled by default.

Example ¶

// This example is commented out because it would block waiting for signals
// injector := New()
// signal, errors := injector.ShutdownOnSignals(syscall.SIGINT, syscall.SIGTERM)
// fmt.Println(signal)
// fmt.Println(errors.Len())

func (*RootScope) ShutdownOnSignalsWithContext ¶

func (s *RootScope) ShutdownOnSignalsWithContext(ctx context.Context, signals ...os.Signal) (os.Signal, *ShutdownReport)

ShutdownOnSignalsWithContext listens for the provided signals in order to gracefully stop services. It will block until receiving any of these signals. If no signal is provided, syscall.SIGTERM and os.Interrupt will be handled by default.

Example ¶

// This example is commented out because it would block waiting for signals
// injector := New()
// ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
// defer cancel()
// signal, errors := injector.ShutdownOnSignalsWithContext(ctx, syscall.SIGINT, syscall.SIGTERM)
// fmt.Println(signal)
// fmt.Println(errors.Len())

func (*RootScope) ShutdownWithContext ¶

func (s *RootScope) ShutdownWithContext(ctx context.Context) *ShutdownReport

ShutdownWithContext gracefully shuts down the root scope and all its descendant scopes with context support. This method ensures proper cleanup of the health check pool and all registered services.

type Scope ¶

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

Scope represents a dependency injection container that can contain services and child scopes. Scopes form a hierarchical tree structure where child scopes can access services from their parent scopes, but not vice versa.

Key features:

Hierarchical service resolution (child scopes can access parent services)
Isolated service registration (services in child scopes don't affect parents)
Thread-safe operations
Service lifecycle management (health checks, shutdown)
Observability and debugging support

func (*Scope) Ancestors ¶

func (s *Scope) Ancestors() []*Scope

Ancestors returns the list of all parent scopes in order from immediate parent to root. This is useful for understanding the scope hierarchy and for operations that need to traverse up the scope tree.

Returns an empty slice for the root scope, and a slice of parent scopes for child scopes, ordered from immediate parent to root.

Play: https://go.dev/play/p/e_oxd7b-q9h

Example ¶

injector := New()
apiScope := injector.Scope("api")
userScope := apiScope.Scope("user")
ancestors := userScope.Ancestors()

fmt.Println(len(ancestors))
fmt.Println(ancestors[0].Name())

Output:

2
api

func (*Scope) ChildByID ¶

func (s *Scope) ChildByID(id string) (*Scope, bool)

ChildByID searches for a child scope by its unique ID across the entire scope hierarchy. This method performs a recursive search through all descendant scopes.

Parameters:

id: The unique ID of the scope to find

Returns the found scope and true if found, or nil and false if not found.

Example ¶

injector := New()
apiScope := injector.Scope("api")
userScope := apiScope.Scope("user")

child, found := apiScope.ChildByID(userScope.ID())
fmt.Println(found)
fmt.Println(child.Name())

Output:

true
user

func (*Scope) ChildByName ¶

func (s *Scope) ChildByName(name string) (*Scope, bool)

ChildByName searches for a child scope by its name across the entire scope hierarchy. This method performs a recursive search through all descendant scopes.

Parameters:

name: The name of the scope to find

Returns the found scope and true if found, or nil and false if not found.

Example ¶

injector := New()
apiScope := injector.Scope("api")
_ = apiScope.Scope("user")

child, found := apiScope.ChildByName("user")
fmt.Println(found)
fmt.Println(child.Name())

Output:

true
user

func (*Scope) Children ¶

func (s *Scope) Children() []*Scope

Children returns the list of immediate child scopes. This method only returns direct children, not grandchildren or deeper descendants.

Returns a slice of child scopes. The order is not guaranteed to be stable.

Example ¶

injector := New()
apiScope := injector.Scope("api")
_ = apiScope.Scope("user")
_ = apiScope.Scope("admin")
children := apiScope.Children()

fmt.Println(len(children))

Output:

2

func (*Scope) HealthCheck ¶

func (s *Scope) HealthCheck() map[string]error

HealthCheck performs health checks on all services in the current scope and its ancestors that implement the Healthchecker interface.

Returns a map of service names to error values. A nil error indicates a successful health check.

Play: https://go.dev/play/p/pJcJGOF5zeK

Example ¶

injector := New()
scope := injector.Scope("api")

ProvideNamed(scope, "db", scopeDbServiceProvider)
_, _ = InvokeNamed[*scopeDbService](scope, "db")
health := scope.HealthCheck()

fmt.Println(len(health))

Output:

1

func (*Scope) HealthCheckWithContext ¶

func (s *Scope) HealthCheckWithContext(ctx context.Context) map[string]error

HealthCheckWithContext performs health checks on all services in the current scope and its ancestors that implement the Healthchecker interface, with context support for cancellation and timeouts.

Parameters:

ctx: Context for cancellation and timeout control

Returns a map of service names to error values. A nil error indicates a successful health check.

Play: https://go.dev/play/p/pJcJGOF5zeK

Example ¶

injector := New()
scope := injector.Scope("api")

ProvideNamed(scope, "db", scopeDbServiceProvider)
_, _ = InvokeNamed[*scopeDbService](scope, "db")

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

health := scope.HealthCheckWithContext(ctx)
fmt.Println(len(health))

Output:

1

func (*Scope) ID ¶

func (s *Scope) ID() string

ID returns the unique identifier of the scope. This ID is generated using UUID and is immutable throughout the scope's lifetime.

Example ¶

injector := New()
scope := injector.Scope("api")

fmt.Println(scope.ID() != "")

Output:

true

func (*Scope) InstanceForEach ¶

func (s *Scope) InstanceForEach(cb func(name string, scope *Scope, service any) bool)

func (*Scope) ListInvokedServices ¶

func (s *Scope) ListInvokedServices() []ServiceDescription

ListInvokedServices returns only the services that have been actually invoked (instantiated) in the current scope and its ancestors. This is useful for understanding which services are actually being used and for debugging dependency issues.

Returns a slice of ServiceDescription objects representing only the invoked services.

Play: https://go.dev/play/p/pJcJGOF5zeK

Example ¶

type Configuration struct {
	Port int
}

injector := New()
scope := injector.Scope("api")

ProvideNamedValue(scope, "config", Configuration{Port: 8080})
_, _ = InvokeNamed[Configuration](scope, "config")
services := scope.ListInvokedServices()

fmt.Println(len(services))
fmt.Println(services[0].Service)

Output:

1
config

func (*Scope) ListProvidedServices ¶

func (s *Scope) ListProvidedServices() []ServiceDescription

ListProvidedServices returns all services available in the current scope and all its ancestor scopes. This provides a complete view of the service hierarchy, showing all services that can be accessed from the current scope.

Returns a slice of ServiceDescription objects representing all available services, including those inherited from parent scopes.

Play: https://go.dev/play/p/e_oxd7b-q9h

Example ¶

type Configuration struct {
	Port int
}

injector := New()
scope := injector.Scope("api")

ProvideNamedValue(scope, "config", Configuration{Port: 8080})
services := scope.ListProvidedServices()

fmt.Println(len(services))
fmt.Println(services[0].Service)

Output:

1
config

func (*Scope) Name ¶

func (s *Scope) Name() string

Name returns the human-readable name of the scope. This name is provided when creating the scope and is immutable.

Example ¶

injector := New()
scope := injector.Scope("api")

fmt.Println(scope.Name())

Output:

api

func (*Scope) RootScope ¶

func (s *Scope) RootScope() *RootScope

RootScope returns the root scope of the scope hierarchy. All scopes in a hierarchy share the same root scope, regardless of their depth.

Example ¶

injector := New()
apiScope := injector.Scope("api")
userScope := apiScope.Scope("user")
root := userScope.RootScope()

fmt.Println(root.Name())

Output:

[root]

func (*Scope) Scope ¶

func (s *Scope) Scope(name string, packages ...func(Injector)) *Scope

Scope creates a new child scope with the given name. Child scopes inherit access to services from their parent scopes, but services registered in child scopes are not accessible to parents.

Parameters:

name: The name for the new child scope (must be unique within the parent)
packages: Optional package functions to execute in the new scope

Returns the newly created child scope.