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"`
}

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"`
    }

    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

Untagged fields are left at their zero value.

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)

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.