conform

Conform - Declarative Configuration & Validation for Go

🎯 Why Conform?

Stop juggling multiple libraries. Conform unifies configuration loading, type conversion, and validation into a single, declarative interface.

Before Conform ❌

// Load config
viper.SetConfigFile("config.yaml")
viper.ReadInConfig()

// Unmarshal
var cfg Config
viper.Unmarshal(&cfg)

// Validate
validate := validator.New()
if err := validate.Struct(cfg); err != nil {
    // Parse errors...
}

// Type conversion? Manual!
port, _ := strconv.Atoi(viper.GetString("port"))
timeout, _ := time.ParseDuration(viper.GetString("timeout"))

With Conform ✅

type Config struct {
    Port     int           `conform:"env=PORT,default=8080,validate=gte:1024"`
    Timeout  time.Duration `conform:"env=TIMEOUT,default=30s"`
    Database string        `conform:"env=DB_URL,required,validate=url"`
}

cfg, err := conform.LoadGeneric[Config](conform.FromEnv())
// ✨ Done! Type-safe, validated, ready to use.

One struct tag. One function call. Zero boilerplate.

✨ Features

🎯 Core Features

• 🏷️ Declarative Configuration - Everything in struct tags, zero boilerplate
• 🚀 Type-Safe Generics - Full type safety with Go 1.21+ generics
• 🔄 Multi-Source Support - Environment variables, files (YAML/JSON/TOML), Consul, custom sources
• ✅ Built-in Validation - 25+ validators out of the box (email, URL, IP, numeric ranges, regex, etc.)
• 🔧 Smart Type Coercion - Automatic conversion for bool, time.Duration, []int, time.Time, map[string]int
• 📦 Nested Structs - Full support with automatic prefix handling
• 🔥 Hot Reload - Watch for changes and reload automatically
• 💬 Beautiful Errors - Detailed error messages with field paths, suggestions, and locations
• 🌍 Environment-Specific - Load different configs for dev/staging/prod
• 🔐 Variable Substitution - ${VAR_NAME:-default} syntax in config values and file paths

🎨 What Makes Conform Different?

📦 Installation

go get github.com/alicanli1995/conform

🚀 Quick Start

Basic Example

package main

import (
    "fmt"
    "os"
    
    "github.com/alicanli1995/conform"
)

type Config struct {
    Port     int    `conform:"env=APP_PORT,default=8080,validate=gte:1024"`
    Host     string `conform:"env=APP_HOST,default=localhost,validate=hostname"`
    Database string `conform:"env=DATABASE_URL,required,validate=url"`
}

func main() {
    os.Setenv("APP_PORT", "3000")
    os.Setenv("DATABASE_URL", "postgres://localhost/mydb")
    
    cfg, err := conform.LoadGeneric[Config](conform.FromEnv())
    if err != nil {
        panic(err) // Beautiful error messages!
    }
    
    fmt.Printf("Server: %s:%d\n", cfg.Host, cfg.Port)
}

📖 Documentation

Multi-Source Support

Load from multiple sources with automatic priority (first source wins):

cfg, err := conform.LoadGeneric[Config](
    conform.FromEnv(),                    // Highest priority
    conform.FromFile("secrets.json"),     // Second priority
    conform.FromFile("config.yaml"),      // Third priority
    conform.FromConsul("service/config"), // Fourth priority
)
// Priority: env > consul > json > yaml > defaults

Environment-Specific Configuration

Perfect for dev/staging/production environments:

type Config struct {
    Database struct {
        Host string `conform:"file=database.host,default=localhost"`
        Port int    `conform:"file=database.port,default=5432"`
    }
}

// Development
devCfg, _ := conform.LoadGeneric[Config](
    conform.WithEnvironment("development"),
    conform.FromFile("config.${ENV}.yaml"), // Loads config.development.yaml
)

// Production
prodCfg, _ := conform.LoadGeneric[Config](
    conform.WithEnvironment("production"),
    conform.FromFile("config.${ENV}.yaml"), // Loads config.production.yaml
)

Variable Substitution

Use ${VAR_NAME:-default} syntax in config values:

type Config struct {
    DatabaseURL string `conform:"env=DB_URL,default=postgres://${DB_USER:-postgres}:${DB_PASSWORD}@${DB_HOST:-localhost}:${DB_PORT:-5432}/${DB_NAME:-mydb}"`
    APIURL      string `conform:"env=API_URL,default=https://api.${ENV:-dev}.example.com"`
}

Smart Type Coercion

Automatic conversion for complex types:

type Config struct {
    // String "true" → bool true
    Debug bool `conform:"env=DEBUG"`
    
    // String "30s" → time.Duration
    Timeout time.Duration `conform:"env=TIMEOUT"`
    
    // String "1,2,3" → []int{1,2,3}
    IDs []int `conform:"env=IDS,separator=,"`
    
    // String "1=one,2=two" → map[int]string{1:"one", 2:"two"}
    Mapping map[int]string `conform:"env=MAPPING"`
    
    // String "2024-01-01" → time.Time
    StartDate time.Time `conform:"env=START,format=2006-01-02"`
}

Beautiful Error Messages

Get detailed, actionable error messages:

cfg, err := conform.LoadGeneric[Config](conform.FromEnv())
if err != nil {
    fmt.Println(err)
    // Output:
    // ❌ Configuration validation failed:
    //
    // 1. Port (APP_PORT): value 80 is too small
    //    Got: 80
    //    Location: env var APP_PORT
    //    💡 Suggestion: Use a value >= 1024 (e.g. 8080)
    //
    // 2. Database.URL (DB_URL): invalid URL format
    //    Got: "not-a-url"
    //    Expected: valid URL with scheme
    //    💡 Suggestion: Format should be: https://example.com
}

Hot Reload

Watch for configuration changes automatically:

watcher, err := conform.Watch[Config](func(newCfg Config) {
    log.Printf("Config reloaded: %+v", newCfg)
    // Update your application state here
}, conform.FromEnv(), conform.FromFile("config.yaml"))

// Thread-safe access
cfg := watcher.Get()

// Stop watching
defer watcher.Stop()

Custom Validators

Register your own validation rules:

conform.RegisterValidator("strong_password", func(val interface{}, params []string) error {
    str := val.(string)
    if len(str) < 12 {
        return fmt.Errorf("password must be at least 12 characters")
    }
    if !hasSpecialChar(str) {
        return fmt.Errorf("password must contain special character")
    }
    return nil
})

type Config struct {
    Password string `conform:"env=PASSWORD,validate=strong_password"`
}

Custom Converters

Convert to custom types:

type CustomType string

conform.RegisterConverter(
    reflect.TypeOf(CustomType("")),
    func(s string) (interface{}, error) {
        return CustomType("custom_" + s), nil
    },
)

type Config struct {
    Custom CustomType `conform:"env=CUSTOM"`
}

Nested Configuration

Full support for nested structs with automatic prefix handling:

type DatabaseConfig struct {
    Host string `conform:"env=HOST,default=localhost"`
    Port int    `conform:"env=PORT,default=5432"`
}

type AppConfig struct {
    Name     string         `conform:"env=APP_NAME,default=MyApp"`
    Database DatabaseConfig `conform:"prefix=DB_"`
}

// Environment variables:
// DB_HOST=db.example.com
// DB_PORT=5432

File Configuration

Support for YAML, JSON, and TOML:

type Config struct {
    Server struct {
        Host string `conform:"file=server.host,default=localhost"`
        Port int    `conform:"file=server.port,default=8080"`
    }
}

// YAML
cfg, _ := conform.LoadGeneric[Config](conform.FromFile("config.yaml"))

// TOML
cfg, _ := conform.LoadGeneric[Config](conform.FromFile("config.toml"))

// JSON
cfg, _ := conform.LoadGeneric[Config](conform.FromFile("config.json"))

📚 Tag Reference

Source Tags

Type Conversion Tags

Validation Tags

✅ Built-in Validators

Numeric Validators

• min:value - Minimum value/length
• max:value - Maximum value/length
• gte:value - Greater than or equal
• lte:value - Less than or equal
• eq:value - Equal to
• ne:value - Not equal to

String Validators

• email - Valid email address
• url - Valid URL (use url:https for HTTPS only)
• ip - Valid IP address (IPv4 or IPv6)
• hostname - Valid hostname
• alphanum - Only letters and digits
• alpha - Only letters
• numeric - Only digits
• regex:pattern - Match regex pattern
• oneof:val1:val2 - One of the specified values
• len:length - Exact length

Password Validators

• has_upper - Contains uppercase letter
• has_lower - Contains lowercase letter
• has_digit - Contains digit
• has_special - Contains special character

General

• required - Field is required

🔧 Advanced Usage

Multiple File Sources

cfg, err := conform.LoadGeneric[Config](
    conform.FromFile("config.yaml"),
    conform.FromFile("secrets.yaml"),
    conform.FromEnv(),
)

Custom Sources

type CustomSource struct{}

func (c *CustomSource) Get(key string) (string, bool) {
    // Your implementation
    return value, found
}

cfg, err := conform.LoadGeneric[Config](
    conform.WithSource(&CustomSource{}),
)

Slices and Arrays

type Config struct {
    Hosts []string `conform:"env=HOSTS,separator=|"`
    Ports []int    `conform:"env=PORTS,separator=,"`
}

// HOSTS=host1|host2|host3
// PORTS=8080,8081,8082

Maps

type Config struct {
    // String "key1=value1,key2=value2" → map[string]string
    StringMap map[string]string `conform:"env=STRING_MAP"`
    
    // String "1=one,2=two" → map[int]string
    IntMap map[int]string `conform:"env=INT_MAP"`
}

Time Parsing

type Config struct {
    StartTime time.Time `conform:"env=START_TIME,format=2006-01-02T15:04:05Z"`
    BirthDate time.Time `conform:"env=BIRTH_DATE,format=2006-01-02"`
}

// START_TIME=2024-01-01T00:00:00Z
// BIRTH_DATE=1990-05-15

🔧 CLI Tool

Validate configuration files without running your application:

# Install
go install github.com/alicanli1995/conform/cmd/conform-validate@latest

# Validate a config file
conform-validate -config=config.yaml -struct=config.go -struct-name=Config

📚 Examples

Comprehensive examples available in the examples directory:

• Basic Usage - Getting started
• Generic API - Type-safe loading
• File Configuration - YAML, JSON, TOML examples
• Environment-Specific - Dev/staging/prod configs
• Advanced Features - Complex scenarios
• Custom Converters & Validators - Extending Conform
• Hot Reload - Dynamic configuration
• Beautiful Errors - Error handling
• Real-World Config - Production-ready example

🏗️ Architecture

Conform consists of four main components:

1. Parser - Parses struct tags and extracts configuration metadata
2. Converter - Converts string values to typed Go values
3. Validator - Validates values against declarative rules
4. Loader - Orchestrates loading from multiple sources with priority

📄 License

MIT License - see LICENSE file for details.