typedenv

README

TypedEnv

Type-safe environment configuration for Go.

type Config struct {
    Host     string        `env:"HOST"`
    Port     int           `env:"PORT"`
    Timeout  time.Duration `env:"TIMEOUT"`
    LogLevel slog.Level    `env:"LOG_LEVEL"`
}

cfg, err := typedenv.Load[Config]()

Unparseable and missing key values are returned in one error.

Features

• Looks up only the keys you declare
• Keeps raw values out of errors
• No use of the unsafe package
• No panics
• No .env support promotes explicit sourcing

Installation

go get github.com/saas-craft/typedenv

Usage

package main

import (
    "fmt"
    "log"
    "net/url"
    "time"

    "github.com/saas-craft/typedenv"
)

func main() {
    type config struct {
        AppHost    string        `env:"HOST"`
        AppPort    int           `env:"PORT"`
        Timeout    time.Duration `env:"TIMEOUT"`
        ServiceURL url.URL       `env:"SERVICE_URL"`
        LogLevel   slog.Level    `env:"LOG_LEVEL"`
    }

    cfg, err := typedenv.Load[config]()
    if err != nil {
        log.Fatalf("load config: %v", err)
    }

    fmt.Println(cfg)
}

Supported Types

Go Type	Example value
string	hello
bool	true, false, 1, 0
int, int8, int16, int32, int64	-42
uint, uint8, uint16, uint32, uint64	42
float32, float64	3.14
time.Duration	1h30m, 500ms, 2s
url.URL	https://saascraft.com/v1
encoding.TextUnmarshaler (e.g. slog.Level)	debug

Untagged fields are left at their zero value.

Constraints

• No support for named time.Duration wrapper types, which can't be distinguished from integers

License

SaasCraft TypedEnv is licensed under the MIT License - see LICENSE for details.

Documentation

Overview

Package typedenv decodes OS environment variables into a struct

Index

• Variables
• func Load[S any]() (S, error)

Examples

• Load

Variables

var (
	ErrNotStruct       = errors.New("expected struct")
	ErrUnexportedField = errors.New("unexported field")
	ErrNotFound        = errors.New("variable not found for key")
	ErrParse           = errors.New("invalid value")
	ErrUnsupportedType = errors.New("unsupported type")
)

Functions

func Load

func Load[S any]() (S, error)

Load reads operating system environment variables into a new instance of S, which must be a struct. Exported fields tagged with `env:"KEY"` are populated by looking up KEY in the environment; untagged fields are left at their zero value.

Supported field types: string, bool, the int and uint families, the float family, time.Duration, and url.URL.

Load returns an error if a tagged variable is missing from the environment, fails to parse, or targets an unexported field. Errors from multiple fields are joined.

Example

type config struct {
	Host     string        `env:"HOST"`
	Port     int           `env:"PORT"`
	Timeout  time.Duration `env:"TIMEOUT"`
	LogLevel slog.Level    `env:"LOG_LEVEL"`
}

os.Setenv("HOST", "localhost")
os.Setenv("PORT", "8080")
os.Setenv("TIMEOUT", "1s")
os.Setenv("LOG_LEVEL", "debug")

cfg, err := Load[config]()
if err != nil {
	log.Fatalf("load config: %v", err)
}

fmt.Printf("%#v\n", cfg)

Output:
typedenv.config{Host:"localhost", Port:8080, Timeout:1000000000, LogLevel:-4}