Simple, type-safe dependency injection with lifecycle management for Go applications. No code generation, no reflection magic.

go get github.com/petabytecl/gaz

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/petabytecl/gaz"
)

type Server struct {
	addr string
}

func (s *Server) OnStart(ctx context.Context) error {
	fmt.Println("server starting on", s.addr)
	return nil
}

func (s *Server) OnStop(ctx context.Context) error {
	fmt.Println("server stopped")
	return nil
}

func main() {
	app := gaz.New()

	// Register a singleton provider using the type-safe For[T]() API
	err := gaz.For[*Server](app.Container()).Provider(func(c *gaz.Container) (*Server, error) {
		return &Server{addr: ":8080"}, nil
	})
	if err != nil {
		log.Fatal(err)
	}

	if err := app.Build(); err != nil {
		log.Fatal(err)
	}

	if err := app.Run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

• Type-safe container - Compile-time type checking via generics
• Singleton and transient scopes - One instance or new instance per resolution
• Lifecycle hooks - OnStart/OnStop interfaces for startup/shutdown logic
• Discovery - ResolveAll[T] and ResolveGroup[T] for plugin-style architectures
• Module organization - Group related providers into reusable modules

• Graceful shutdown - Configurable timeout with per-hook limits and signal handling
• Configuration loading - YAML/JSON/TOML files, environment variables, CLI flags
• Struct validation - validate tags with go-playground/validator
• Cobra CLI integration - Build CLI apps with dependency injection
• Background workers - Supervised workers with restart, circuit breaker, lifecycle integration

• gRPC Server - Interceptors, service discovery, native health checks, opt-in reflection
• HTTP Server - Configurable timeouts, graceful shutdown
• Vanguard - Unified server: gRPC, Connect, gRPC-Web, REST on a single port
• OpenTelemetry - TracerProvider with OTLP export and server instrumentation
• Health checks - Readiness/liveness probes, gRPC health protocol, builtin checks

• Logger flags - --log-level, --log-format, --log-output, --log-add-source
• Config flags - --config, --env-prefix, --config-strict with XDG auto-search

App is the high-level API for building applications. It manages the container, configuration, lifecycle, and signal handling:

app := gaz.New()

// Register services using the type-safe For[T]() API
gaz.For[*Database](app.Container()).Provider(NewDatabase)
gaz.For[*UserService](app.Container()).Provider(NewUserService)

app.Build()
app.Run(ctx)

Container is the low-level DI container. Use it directly for testing or advanced scenarios:

c := gaz.NewContainer()
gaz.For[*Database](c).Provider(NewDatabase)
c.Build()
db, _ := gaz.Resolve[*Database](c)

// Singleton (default): one instance for container lifetime
gaz.For[*Database](c).Provider(NewDatabase)

// Transient: new instance on every resolution
gaz.For[*Request](c).Transient().Provider(NewRequest)

// Eager: singleton instantiated at Build() time
gaz.For[*ConnectionPool](c).Eager().Provider(NewConnectionPool)

// Instance: register a pre-built value
gaz.For[*Config](c).Instance(cfg)

Services implementing Starter or Stopper interfaces get automatic lifecycle management:

type Starter interface {
	OnStart(context.Context) error
}

type Stopper interface {
	OnStop(context.Context) error
}

Hooks are called in dependency order (dependencies start first, stop last).

• Getting Started - First application walkthrough
• Concepts - DI fundamentals, scopes, lifecycle
• Configuration - Config loading, env vars, validation
• Validation - Struct tags and custom validators
• Advanced - Modules, testing, Cobra integration
• Troubleshooting - Common issues and solutions

See the examples directory:

• basic - Minimal working application
• http-server - HTTP server with graceful shutdown
• config-loading - Configuration files and environment variables
• lifecycle - Services with OnStart/OnStop hooks
• modules - Organizing providers into modules
• cobra-cli - CLI application with Cobra
• background-workers - Background task processing
• discovery - Plugin-style architecture with ResolveAll
• vanguard - Unified server: gRPC, Connect, gRPC-Web, REST on a single port
• microservice - Complete microservice with health, workers, eventbus

MIT