A lightweight Go configuration management library supporting JSON, ENV, TOML, and YAML formats. It provides viper-like AutomaticEnv functionality with fewer dependencies. Originally built to support grlx.

Installation

go get github.com/taigrr/jety

Requires Go 1.25.5 or later.

Quick Start

package main

import "github.com/taigrr/jety"

func main() {
    // Set defaults
    jety.SetDefault("port", 8080)
    jety.SetDefault("host", "localhost")

    // Environment variables are loaded automatically
    // e.g., PORT=9000 overrides the default

    // Read from config file
    jety.SetConfigFile("config.toml")
    jety.SetConfigType("toml")
    if err := jety.ReadInConfig(); err != nil {
        // handle error
    }

    // Get values (config file > env > default)
    port := jety.GetInt("port")
    host := jety.GetString("host")
}

Features

Multiple formats: JSON, TOML, YAML
Automatic env loading: Environment variables loaded on init
Prefix filtering: Filter env vars by prefix (e.g., MYAPP_)
Case-insensitive keys: Keys normalized to lowercase
Type coercion: Getters handle type conversion gracefully
Thread-safe: Safe for concurrent access
Config precedence: config file > environment > defaults

Nested Configuration

For nested config structures like:

[services.cloud]
var = "xyz"
timeout = "30s"

[services.cloud.auth]
client_id = "abc123"

Access nested values using GetStringMap and type assertions:

services := jety.GetStringMap("services")
cloud := services["cloud"].(map[string]any)
varValue := cloud["var"].(string)  // "xyz"

// For deeper nesting
auth := cloud["auth"].(map[string]any)
clientID := auth["client_id"].(string)  // "abc123"

Environment Variable Overrides

Environment variables use uppercase keys. For nested config, the env var name is the key in uppercase:

# Override top-level key
export PORT=9000

# For nested keys, use the full key name in uppercase
export SERVICES_CLOUD_VAR=override_value

With a prefix:

cm := jety.NewConfigManager().WithEnvPrefix("MYAPP_")

export MYAPP_PORT=9000
export MYAPP_SERVICES_CLOUD_VAR=override_value

Note: Environment variables override defaults but config files take highest precedence.

Migration Guide

From v0.x to v1.x

Breaking Changes

WriteConfig() now returns error

// Before
jety.WriteConfig()

// After
if err := jety.WriteConfig(); err != nil {
    // handle error
}
// Or if you want to ignore the error:
_ = jety.WriteConfig()

Go 1.25.5 minimum required

Update your Go version or pin to an older jety release.

Non-Breaking Improvements

Getters (GetBool, GetInt, GetDuration) now return zero values instead of panicking on unknown types
Added int64 support in GetInt, GetIntSlice, and GetDuration
Improved env var parsing (handles values containing =)

API

Configuration

Function	Description
`SetConfigFile(path)`	Set config file path
`SetConfigDir(dir)`	Set config directory
`SetConfigName(name)`	Set config file name (without extension)
`SetConfigType(type)`	Set config type: `"toml"`, `"yaml"`, `"json"`
`ReadInConfig()`	Read config file
`WriteConfig()`	Write config to file

Values

Function	Description
`Set(key, value)`	Set a value
`SetDefault(key, value)`	Set a default value
`Get(key)`	Get raw value
`GetString(key)`	Get as string
`GetInt(key)`	Get as int
`GetBool(key)`	Get as bool
`GetDuration(key)`	Get as time.Duration
`GetStringSlice(key)`	Get as []string
`GetIntSlice(key)`	Get as []int
`GetStringMap(key)`	Get as map[string]string

Environment

Function	Description
`WithEnvPrefix(prefix)`	Filter env vars by prefix (strips prefix from keys)
`SetEnvPrefix(prefix)`	Set prefix for env var lookups

License

See LICENSE file.