configx

Documentation

Overview

Package configx loads layered configuration — TOML files, an optional local overlay, environment-variable overrides, and defaults — into typed structs.

Index

• func Configure(envPrefix string, cfgs ...Configurable) error
• func ReadAndValidate(r Reader, cfg Configurable) error
• type Configurable
• type Reader
  • func NewMapReader(values map[string]any) Reader
  • func NewViperConfigReader(envPrefix string) (Reader, error)
• type Setter
• type Validator

Functions

func Configure

func Configure(envPrefix string, cfgs ...Configurable) error

Configure creates a single Reader and calls ReadConfig on each Configurable in order. Use NewViperConfigReader when you need to reuse the same parsed config across multiple calls.

func ReadAndValidate

func ReadAndValidate(r Reader, cfg Configurable) error

ReadAndValidate calls cfg.ReadConfig and, when cfg also implements Validator, its Validate method. It is the single seam that pairs reading with validation so every entry point (Configure, host.App) enforces Validate identically.

Types

type Configurable

type Configurable interface {
	ReadConfig(Reader) error
}

Configurable is implemented by any type that can populate itself from a Reader. ReadConfig is called on each registered value in order.

type Reader

type Reader interface {
	SetDefault(key string, value any)
	Read(key string, dest any) error
	ReadMap(key string) map[string]any
	ReadAll(dest any) error
}

Reader wraps a reader instance and exposes config-reading operations to Configurable implementations.

func NewMapReader

func NewMapReader(values map[string]any) Reader

NewMapReader returns an in-memory Reader seeded from values — a nested map mirroring the config-file layout, for example:

configx.NewMapReader(map[string]any{
    "app": map[string]any{"name": "billing", "shutdownDelay": "5s"},
    "log": map[string]any{"level": "debug"},
})

Seeded values win over SetDefault, and string values decode into typed fields exactly as the file reader does (so "5s" populates a time.Duration). Environment variables and the filesystem are ignored: the map is authoritative. A nil or empty values map yields a reader that returns only the defaults each Configurable registers.

func NewViperConfigReader

func NewViperConfigReader(envPrefix string) (Reader, error)

NewViperConfigReader creates a Reader. Use this to hold a single reader across multiple Configure calls (e.g. in App.configReader) so the config file is only read once.

type Setter

type Setter interface {
	Set(key string, value any)
}

Setter is an optional interface a Reader may implement to accept programmatic override values that win over its other layers — config files, environment variables, and defaults. Both the Viper file reader (NewViperConfigReader) and the map reader (NewMapReader) implement it; host.WithConfigValue relies on it to inject settings in code.

type Validator

type Validator interface {
	Validate() error
}

Validator is an optional interface a Configurable may implement to check its values once they have been read. When a Configurable also implements it, Configure and host.App call Validate immediately after ReadConfig and fail startup with the wrapped error — catching invalid settings (an empty DSN, an out-of-range port) at boot instead of at first use.