envconfig

func Assert ¶ added in v0.2.0

func Assert(opts ...AssertOpt) error

Assert runs all provided validation checks and collects any errors that occur. If any validation fails, it returns an ErrValidation containing all failures. If all validations pass, it returns nil.

Assert is designed to be used with validation helper functions like NotEmpty, Range, etc. All validations are executed regardless of failures, allowing users to see all validation issues at once rather than fixing them one at a time.

Example:

func (cfg Config) Validate() error {
    return Assert(
        NotEmpty(cfg.APIKey, "API_KEY"),
        Range(cfg.Port, 1, 65535, "PORT"),
        OneOf(cfg.Environment, "ENVIRONMENT", "dev", "staging", "production"),
    )
}

func EnvFileLookup ¶

func EnvFileLookup(filePath string) func(string) (string, bool)

EnvFileLookup returns a lookup function that reads environment variables from a .env file. It panics if a file cannot be read. The .env file should have lines in the format KEY=VALUE. Comments starting with # are ignored. Empty lines are ignored. Notes:

• If both the .env file and OS environment define a key, the OS environment value wins (current behavior).
• Lines like `export KEY=VALUE` are supported.

func IgnoreEmptyEnvLookup ¶

func IgnoreEmptyEnvLookup(key string) (string, bool)

IgnoreEmptyEnvLookup wraps os.LookupEnv but treats empty values as unset. If the variable is present but "", it returns ok == false.

func Read ¶

func Read[T any](holder *T, lookupEnv ...func(string) (string, bool)) error

Read populates holder (a pointer to struct) using the provided lookup function to resolve values.

Usage:

type C struct {
  Port int    `env:"PORT" envDefault:"8080"`
  TLS  struct {
    Enabled bool   `env:"ENABLED"`
    Cert    string `env:"CERT" envRequired:"true"`
  } `envPrefix:"TLS"` // effective keys: TLS_ENABLED, TLS_CERT
}
var cfg C
if err := envconfig.Read(&cfg); err != nil { log.Fatal(err) }

Lookup source:

By default Read uses os.LookupEnv. You may pass a custom lookup function,
e.g., envconfig.Read(&cfg, myLookup) where myLookup has signature func(string) (string, bool).

Tags (per field):

• `env:"NAME"` : the environment variable name for this field. Use `env:"-"` to skip the field entirely.
• `envDefault:"VAL"` : fallback used only when the variable is UNSET (i.e., lookup returns ok == false). If the variable is present but empty ("", ok == true), the empty value is used and default does NOT apply.
• `envRequired:"true"`: if the variable is UNSET and no envDefault is provided, Read returns an error. Only the literal "true" enables this behavior.
• `envPrefix:"PFX"` : for struct-typed fields (including embedded/ anonymous ones). Applies a prefix to all descendant leaf env names. Prefixes are joined with "_". Example: `envPrefix:"DB"` -> DB_HOST, DB_PORT.

Embedded vs named struct fields:

• Embedded (anonymous) struct fields are treated "flat" by default (no extra prefix). To prefix an embedded subtree, put `envPrefix` on the embedded field.
• Named struct fields may also carry `envPrefix:"PFX"`; they must NOT also have an `env` tag.

Whole-struct (single-key) decoding:

If a struct-typed field (or embedded struct) has an effective prefix PFX_,
and the holder type implements one of the standard decoders below, a single
env variable named "PFX" (without the trailing underscore) can be used to
populate the entire struct at once. When present, this whole-struct value
takes precedence and field-by-field decoding is skipped.
Supported decoders:
  - encoding.TextUnmarshaler
  - encoding.BinaryUnmarshaler
  - json.Unmarshaler

Supported field types:

• primitives: string, bool, all int/uint sizes, float32/64
• time.Duration (parsed via time.ParseDuration)
• arrays, slices: comma-separated values (e.g. "a,b,c")
• maps: comma-separated k=v pairs (e.g. "k1=v1,k2=v2"); split on first "="
• pointers to any supported type (allocated as needed)
• any type implementing encoding.TextUnmarshaler / BinaryUnmarshaler / json.Unmarshaler

Precedence per leaf field:

1. If lookupEnv returns (value, ok==true), that value is used as-is (even if value is the empty string "").
2. Else, if `envDefault` is present, it is used.
3. Else, if `envRequired:"true"`, Read returns an error.
4. Else, the field is left at its zero value.

Validation & errors:

• holder must be a non-nil pointer to a struct.
• Non-embedded struct fields must have either `env` or `envPrefix` (or be explicitly skipped with `env:"-"`); otherwise an error is returned.
• Struct fields must not specify both `env` and `envPrefix`.
• `envPrefix` must not be empty when present.
• Parsing/conversion failures return errors that include the env key.
• Unsupported leaf types (that do not implement a supported unmarshal interface) cause an error.
• any type can implement Validator interface, and it will be called as soon as value if populated.

Note on empties:

An env var that is present but empty (lookup ok == true, value == "") is
considered "set": it suppresses `envDefault` and does not trigger
`envRequired`. If you want defaulting on empty strings, use IgnoreEmptyEnvLookup,
which wraps os.LookupEnv and treats empty values as unset (returns ok == false when value == "").