konfig

README

konfig

Spring-inspired configuration management for Go - Simple, type-safe, and blazingly fast.

⚡ Quick Start

go get github.com/mfenderov/konfig

1. Create your config struct:

type Config struct {
    Server struct {
        Port string `konfig:"port" default:"8080"`
        Host string `konfig:"host" default:"localhost"`
    } `konfig:"server"`
    Database struct {
        URL  string `konfig:"url" default:"postgres://localhost/myapp"`
        Pool int    `konfig:"pool" default:"10"`
    } `konfig:"database"`
}

2. Load configuration:

var config Config
err := konfig.LoadInto(&config)
// Done! Your struct is populated with type-safe configuration

3. Use with profiles:

go run app.go -p prod  # Loads application-prod.yaml

🎯 Why konfig?

Feature	konfig	Others
Type Safety	✅ Compile-time struct validation	❌ Runtime string lookups
Profile Support	✅ Built-in dev/prod/test profiles	❌ Manual environment handling
Zero Dependencies	✅ Just stdlib + yaml	❌ Heavy dependency chains
Spring-like	✅ Familiar application.yaml pattern	❌ Custom configuration styles
Env Variable Integration	✅ Automatic substitution & overrides	❌ Manual env handling

📁 Configuration Files

# application.yaml (default)
server:
  port: ${PORT:8080}
  host: ${HOST:0.0.0.0}

database:
  url: ${DATABASE_URL:postgres://localhost/myapp}
  pool: ${DB_POOL:10}

# application-prod.yaml (production overrides)
server:
  port: 443
database:
  pool: 50

🚀 Advanced Features

Environment Variable Substitution

database:
  url: ${DATABASE_URL:postgres://localhost/default}  # Uses env var or default
  password: ${DB_PASSWORD}  # Required env var (fails if missing)

Nested Configuration

type Config struct {
    App struct {
        Name    string `konfig:"name" default:"MyApp"`
        Version string `konfig:"version" default:"1.0.0"`
        Features struct {
            Auth     bool `konfig:"auth" default:"true"`
            Metrics  bool `konfig:"metrics" default:"false"`
        } `konfig:"features"`
    } `konfig:"application"`
}

Profile-Aware Code

if konfig.IsProdProfile() {
    // Production-specific logic
    enableHTTPS()
} else if konfig.IsDevProfile() {
    // Development helpers
    enableDebugMode()
}

📚 API Reference

Core Functions

konfig.LoadInto(&config)     // Load into struct (recommended)
konfig.Load()                // Load into environment variables
konfig.LoadFrom("file.yaml") // Load specific file

// Profile helpers
konfig.GetProfile()          // Current active profile
konfig.IsDevProfile()        // Check if dev profile
konfig.IsProdProfile()       // Check if prod profile

Struct Tags

type Config struct {
    Port string `konfig:"server.port" default:"8080"`
    //            ^^^^^^^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^
    //            Configuration key      Default value
}

🔍 Examples

See examples/ for complete working examples:

cd examples
go run simple_example.go                              # Basic usage
go run simple_example.go -p dev                      # With dev profile  
go run simple_example.go struct_config_example.go    # Advanced features

🏆 Project Quality

konfig maintains high standards through systematic simplification:

• 🧪 100% test coverage - 6 focused test files covering all functionality
• ⚡ Performance optimized - 3 essential benchmarks measuring real scenarios
• 📖 Clear documentation - Concise, example-driven approach
• 🎯 31% complexity reduction - Achieved through merciless simplification
• ✅ Zero functionality loss - All features preserved during optimization

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with tests
4. Submit a Pull Request

📄 License

MIT License - see LICENSE file for details.

---

Made with ❤️ for the Go community | Documentation | Examples | Contributing

Documentation

Overview

Package konfig provides a Spring Framework-inspired configuration management system for Go applications.

konfig supports YAML-based configuration files, profile-specific configurations, environment variable substitution, and struct-based configuration loading with type safety.

Basic usage:

err := konfig.Load()
if err != nil {
    log.Fatal(err)
}
port := os.Getenv("server.port")

Struct-based configuration:

type Config struct {
    Port string `konfig:"server.port" default:"8080"`
}
var cfg Config
err := konfig.LoadInto(&cfg)

Index

• func ClearEnv()
• func GetEnv(key string) string
• func GetProfile() string
• func IsDevProfile() bool
• func IsProdProfile() bool
• func IsProfile(profile string) bool
• func Load() error
• func LoadFrom(pathToConfigFile string) error
• func LoadInto(config interface{}) error
• func ResetProfileInitialized()
• func SetEnv(key string, value string) error

Functions

func ClearEnv

func ClearEnv()

ClearEnv deletes all environment variables. This is primarily used for testing purposes and should be used with caution.

func GetEnv

func GetEnv(key string) string

GetEnv retrieves the value of the environment variable named by the key. This is a convenience wrapper around os.Getenv for consistency with konfig's API.

func GetProfile

func GetProfile() string

GetProfile returns the currently active profile name.

The profile is determined by command-line flags (-p or --profile). Returns an empty string if no profile is active.

Example:

profile := konfig.GetProfile()
if profile != "" {
    fmt.Printf("Active profile: %s\n", profile)
} else {
    fmt.Println("No active profile")
}

func IsDevProfile

func IsDevProfile() bool

IsDevProfile returns true if the current active profile is "dev".

The profile is determined by command-line flags (-p or --profile).

Example:

if konfig.IsDevProfile() {
    // Development-specific logic
    fmt.Println("Running in development mode")
}

func IsProdProfile

func IsProdProfile() bool

IsProdProfile returns true if the current active profile is "prod".

The profile is determined by command-line flags (-p or --profile).

Example:

if konfig.IsProdProfile() {
    // Production-specific logic
    fmt.Println("Running in production mode")
}

func IsProfile

func IsProfile(profile string) bool

IsProfile returns true if the current active profile matches the given name.

This is useful for checking custom profile names beyond "dev" and "prod".

Example:

if konfig.IsProfile("staging") {
    // Staging-specific logic
    fmt.Println("Running in staging mode")
}

func Load

func Load() error

Load initializes konfig by loading configuration from default sources.

It first loads the base configuration file (resources/application.yaml or .yml), then loads any active profile-specific configuration (e.g., resources/application-dev.yaml). Profile-specific values override base configuration values.

Configuration keys are flattened into dot notation and set as environment variables, making them accessible via os.Getenv() or the GetEnv() function.

The active profile is determined by command-line flags (-p or --profile).

Example:

err := konfig.Load()
if err != nil {
    log.Fatal("Failed to load configuration:", err)
}

port := os.Getenv("server.port")
dbURL := os.Getenv("database.url")

func LoadFrom

func LoadFrom(pathToConfigFile string) error

LoadFrom loads configuration from a specific YAML file.

Unlike Load(), this function only loads the specified file and does not attempt to load default application.yaml or profile-specific files.

The configuration keys are flattened and set as environment variables, just like with Load().

Example:

err := konfig.LoadFrom("config/custom.yaml")
if err != nil {
    log.Fatal("Failed to load custom config:", err)
}

customValue := os.Getenv("custom.setting")

func LoadInto

func LoadInto(config interface{}) error

LoadInto loads configuration into a Go struct using struct tags for type-safe configuration access.

This function first calls Load() to initialize konfig, then uses reflection to populate the provided struct based on `konfig` and `default` struct tags.

Struct Tag Usage:

• `konfig:"key.path"` - Maps the field to a configuration key (supports dot notation)
• `default:"value"` - Provides a default value if the configuration key is not set
• Fields without `konfig` tags are ignored

The config parameter must be a pointer to a struct. Nested structs are supported and will be populated recursively.

Example:

type DatabaseConfig struct {
    Host     string `konfig:"host" default:"localhost"`
    Port     string `konfig:"port" default:"5432"`
    Password string `konfig:"password"`
}

type Config struct {
    AppName  string         `konfig:"app.name" default:"MyApp"`
    Database DatabaseConfig `konfig:"database"`
}

var cfg Config
err := konfig.LoadInto(&cfg)
if err != nil {
    log.Fatal("Failed to load config:", err)
}

fmt.Printf("App: %s, DB: %s:%s\n", cfg.AppName, cfg.Database.Host, cfg.Database.Port)

func ResetProfileInitialized

func ResetProfileInitialized()

ResetProfileInitialized resets the profile initialization state. This function is primarily used in tests to ensure clean state between test runs.

func SetEnv

func SetEnv(key string, value string) error

SetEnv sets the value of the environment variable named by the key. This is a convenience wrapper around os.Setenv for consistency with konfig's API.