do

func As ¶

func As[Initial any, Alias any](i Injector) error

As declares an alias for a service, allowing it to be retrieved using a different type. This function creates a type alias where the Alias type can be used to retrieve the Initial service. The alias is automatically named using the type name of Alias.

Parameters:

• i: The injector to register the alias in

Returns an error if the alias cannot be created (e.g., type incompatibility or missing service).

Example:

// Register a concrete service
do.Provide(injector, func(i do.Injector) (*PostgresqlDatabase, error) {
    return &PostgresqlDatabase{}, nil
})

// Create an alias so it can be retrieved as an interface
do.As[*PostgresqlDatabase, Database](injector)

// Now both work:
db := do.MustInvoke[*PostgresqlDatabase](injector)
db := do.MustInvoke[Database](injector)

func AsNamed ¶

func AsNamed[Initial any, Alias any](i Injector, initial string, alias string) error

AsNamed declares a named alias for a named service. This function allows you to create aliases with custom names for both the initial service and the alias.

Parameters:

• i: The injector to register the alias in
• initial: The name of the existing service to alias
• alias: The name for the new alias service

Returns an error if the alias cannot be created (e.g., type incompatibility or missing service).

Example:

// Register a service with a custom name
do.ProvideNamed(injector, "my-db", func(i do.Injector) (*PostgresqlDatabase, error) {
    return &PostgresqlDatabase{}, nil
})

// Create an alias with custom names
do.AsNamed[*PostgresqlDatabase, Database](injector, "my-db", "db-interface")

// Retrieve using the alias name
db := do.MustInvokeNamed[Database](injector, "db-interface")

func Bind ¶

func Bind[Initial any, Alias any]() func(Injector)

Bind creates a function that creates a type alias between two types. This function is a convenience wrapper for creating service binding functions that can be used in packages.

Parameters:

• Initial: The original type to bind from
• Alias: The type to bind to (must be implemented by Initial)

Returns a function that creates the type alias when executed. Panics if the binding cannot be created.

Example:

dbBinding := do.Bind[*Database, DatabaseInterface]()

// Global to a package
var Package = do.Package(dbBinding, ...)

func BindNamed ¶

func BindNamed[Initial any, Alias any](initial string, alias string) func(Injector)

BindNamed creates a function that creates a named type alias between two types. This function is a convenience wrapper for creating named service binding functions that can be used in packages.

Parameters:

• initial: The name of the original service
• alias: The name for the alias service
• Initial: The original type to bind from
• Alias: The type to bind to (must be implemented by Initial)

Returns a function that creates the named type alias when executed. Panics if the binding cannot be created.

Example:

dbBinding := do.BindNamed[*Database, DatabaseInterface]("main-db", "db-interface")

// Global to a package
var Package = do.Package(dbBinding, ...)

func Eager ¶

func Eager[T any](value T) func(Injector)

Eager creates a function that registers an eager service using the default service name. This function is a convenience wrapper for creating eager service registration functions that can be used in packages. The service value is provided directly.

Parameters:

• value: The service instance to register eagerly

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

Example:

configService := do.Eager[*Config](&Config{Port: 8080})

// Global to a package
var Package = do.Package(configService)

func EagerNamed ¶

func EagerNamed[T any](serviceName string, value T) func(Injector)

EagerNamed creates a function that registers an eager service with a custom name. This function is a convenience wrapper for creating named eager service registration functions that can be used in packages. The service value is provided directly.

Parameters:

• serviceName: The custom name for the service
• value: The service instance to register eagerly

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

Example:

configService := do.EagerNamed[*Config]("app-config", &Config{Port: 8080})

// Global to a package
var Package = do.Package(configService, ...)

func HealthCheck ¶

func HealthCheck[T any](i Injector) error

HealthCheck returns a service status, using type inference to determine the service name. This function performs a health check on a service by inferring its name from the type T. The service must implement either Healthchecker or HealthcheckerWithContext interface.

Parameters:

• i: The injector containing the service

Returns an error if the health check fails, or nil if the service is healthy.

Example:

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

func HealthCheckNamed ¶

func HealthCheckNamed(i Injector, name string) error

HealthCheckNamed returns a service status for a named service. This function performs a health check on a service with the specified name. The service must implement either Healthchecker or HealthcheckerWithContext interface.

Parameters:

• i: The injector containing the service
• name: The name of the service to health check

Returns an error if the health check fails, or nil if the service is healthy.

Example:

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

func HealthCheckNamedWithContext ¶

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

HealthCheckNamedWithContext returns a service status for a named service with context support. This function performs a health check on a service with the specified name and context support for timeout and cancellation. The service must implement either Healthchecker or HealthcheckerWithContext interface.

Parameters:

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

Returns an error if the health check fails, or nil if the service is healthy.

Example:

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

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

func HealthCheckWithContext ¶

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

HealthCheckWithContext returns a service status, using type inference to determine the service name. This function performs a health check on a service with context support for timeout and cancellation. The service must implement either Healthchecker or HealthcheckerWithContext interface.

Parameters:

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

Returns an error if the health check fails, or nil if the service is healthy.

Example:

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

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

func Invoke ¶

func Invoke[T any](i Injector) (T, error)

Invoke retrieves and instantiates a service from the DI container using type inference. The service will be created if it hasn't been instantiated yet (for lazy services).

Example:

service, err := do.Invoke[*MyService](injector)

func InvokeAs ¶

func InvokeAs[T any](i Injector) (T, error)

InvokeAs invokes a service in the DI container by finding the first service that matches the provided type or interface. This function searches through all registered services to find one that can be cast to the requested type T. It's useful when you want to retrieve a service by interface without explicitly creating aliases.

Parameters:

• i: The injector to search for the service

Returns the service instance and any error that occurred during invocation.

Example:

// Register a concrete service
do.Provide(injector, func(i do.Injector) (*PostgresqlDatabase, error) {
    return &PostgresqlDatabase{}, nil
})

// Retrieve by interface
db, err := do.InvokeAs[Database](injector)

func InvokeNamed ¶

func InvokeNamed[T any](i Injector, name string) (T, error)

InvokeNamed retrieves and instantiates a named service from the DI container. This allows you to retrieve specific named services when multiple services of the same type are registered.

Example:

// Register multiple databases
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
})

// Retrieve specific database
mainDB, err := do.InvokeNamed[*Database](injector, "main-db")
backupDB, err := do.InvokeNamed[*Database](injector, "backup-db")

func InvokeStruct ¶

func InvokeStruct[T any](i Injector) (T, error)

InvokeStruct invokes services located in struct properties. The struct fields must be tagged with `do:""` or `do:"name"`, where `name` is the service name in the DI container. If the service is not found in the DI container, an error is returned. If the service is found but not assignable to the struct field, an error is returned.

Example:

type App struct {
    Database *Database `do:""`
    Logger   *Logger   `do:"app-logger"`
    Config   *Config   `do:""`
}

// Register services
do.Provide(injector, func(i do.Injector) (*Database, error) {
    return &Database{}, nil
})
do.ProvideNamed(injector, "app-logger", func(i do.Injector) (*Logger, error) {
    return &Logger{}, nil
})
do.Provide(injector, func(i do.Injector) (*Config, error) {
    return &Config{}, nil
})

// Invoke struct with injected services
app, err := do.InvokeStruct[App](injector)

func Lazy ¶

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

Lazy creates a function that registers a lazy service using the default service name. This function is a convenience wrapper for creating lazy 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 lazy when executed.

Example:

dbService := do.Lazy[*Database](func(i do.Injector) (*Database, error) {
    return &Database{}, nil
})

// Global to a package
var Package = do.Package(dbService, ...)

func LazyNamed ¶

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

LazyNamed creates a function that registers a lazy service with a custom name. This function is a convenience wrapper for creating named lazy 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 lazy with the specified name when executed.

Example:

dbService := do.LazyNamed[*Database]("main-db", func(i do.Injector) (*Database, error) {
    return &Database{}, nil
})

// Global to a package
var Package = do.Package(dbService)

func MustAs ¶

func MustAs[Initial any, Alias any](i Injector)

MustAs declares an alias for a service and panics if an error occurs. This is a convenience function that wraps As and panics on error.

Parameters:

• i: The injector to register the alias in

Panics if the alias cannot be created (e.g., type incompatibility or missing service).

Example:

do.MustAs[*PostgresqlDatabase, Database](injector)

func MustAsNamed ¶

func MustAsNamed[Initial any, Alias any](i Injector, initial string, alias string)

MustAsNamed declares a named alias for a named service and panics if an error occurs. This is a convenience function that wraps AsNamed and panics on error.

Parameters:

• i: The injector to register the alias in
• initial: The name of the existing service to alias
• alias: The name for the new alias service

Panics if the alias cannot be created (e.g., type incompatibility or missing service).

Example:

do.MustAsNamed[*PostgresqlDatabase, Database](injector, "my-db", "db-interface")

func MustInvoke ¶

func MustInvoke[T any](i Injector) T

MustInvoke retrieves and instantiates a service from the DI container using type inference. If the service cannot be retrieved or instantiated, it panics.

This function is useful when you're certain the service exists and want to avoid error handling in your code.

Example:

service := do.MustInvoke[*MyService](injector)

func MustInvokeAs ¶

func MustInvokeAs[T any](i Injector) T

MustInvokeAs invokes a service in the DI container by finding the first service that matches the provided type or interface. This function panics if an error occurs during invocation. It's useful when you want to retrieve a service by interface without explicitly creating aliases.

Parameters:

• i: The injector to search for the service

Returns the service instance. Panics if the service cannot be found or invoked.

Example:

// Register a concrete service
do.Provide(injector, func(i do.Injector) (*PostgresqlDatabase, error) {
    return &PostgresqlDatabase{}, nil
})

// Retrieve by interface
db := do.MustInvokeAs[Database](injector)

func MustInvokeNamed ¶

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

MustInvokeNamed retrieves and instantiates a named service from the DI container. If the service cannot be retrieved or instantiated, it panics.

This function is useful when you're certain the named service exists and want to avoid error handling in your code.

Example:

service := do.MustInvokeNamed[*MyService](injector, "my-service")

func MustInvokeStruct ¶

func MustInvokeStruct[T any](i Injector) T

MustInvokeStruct invokes services located in struct properties and panics on error. The struct fields must be tagged with `do:""` or `do:"name"`, where `name` is the service name in the DI container. If the service is not found in the DI container, it panics. If the service is found but not assignable to the struct field, it panics.

Example:

type App struct {
    Database *Database `do:""`
    Logger   *Logger   `do:"app-logger"`
    Config   *Config   `do:""`
}

// Register services
do.Provide(injector, func(i do.Injector) (*Database, error) {
    return &Database{}, nil
})
do.ProvideNamed(injector, "app-logger", func(i do.Injector) (*Logger, error) {
    return &Logger{}, nil
})
do.Provide(injector, func(i do.Injector) (*Config, error) {
    return &Config{}, nil
})

// Invoke struct with injected services (panics on error)
app := do.MustInvokeStruct[App](injector)

func MustShutdown ¶

func MustShutdown[T any](i Injector)

MustShutdown stops a service, using type inference to determine the service name. It panics on error. This function performs a graceful shutdown on a service by inferring its name from the type T. If the shutdown fails, this function will panic.

Parameters:

• i: The injector containing the service

Panics if the shutdown fails.

Example:

do.MustShutdown[*Database](injector)

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")

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")

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)

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.

Example:

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

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.

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.

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.

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.

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.

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.

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.

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.

Example:

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

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.

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
})

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

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})

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.

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

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.

Example:

ProvideValue(injector, &MyService{})

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.

Example:

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

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.

Example:

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

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)
}

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.

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)
}

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.

Example:

loggerService := do.Transient[*Logger](func(i do.Injector) (*Logger, error) {
    return &Logger{}, nil
})

// Global to a package
var Package = do.Package(loggerService, ...)

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.

Example:

loggerService := do.TransientNamed[*Logger]("request-logger", func(i do.Injector) (*Logger, error) {
    return &Logger{}, nil
})

// Global to a package
var Package = do.Package(loggerService, ...)