jety/README.md

JETY

JSON, ENV, TOML, YAML

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.26.2 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 (Set > env > config file > 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: Set() > environment > config file > defaults

Nested Configuration

For nested config structures like:

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

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

Use Sub() to get a scoped ConfigManager for a nested section:

cloud := jety.Sub("services")
if cloud != nil {
    inner := cloud.Sub("cloud")
    if inner != nil {
        varValue := inner.GetString("var")      // "xyz"
        timeout := inner.GetDuration("timeout")  // 30s
    }
}

Or access nested values directly with GetStringMap and type assertions:

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

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 both defaults and config file values for registered keys (keys that appear in defaults or the config file).

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
Sub(key)	Get scoped sub-config
Get(key)	Get raw value
GetString(key)	Get as string
GetInt(key)	Get as int
GetInt64(key)	Get as int64
GetFloat64(key)	Get as float64
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]any
IsSet(key)	Check if key has a value
AllKeys()	List all known keys
AllSettings()	Get all values as a map
Unmarshal(target)	Unmarshal config to struct
UnmarshalKey(key, target)	Unmarshal a key to struct

Environment

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

Struct Unmarshaling

Unmarshal your configuration directly into Go structs:

type Config struct {
    Host    string `json:"host"`
    Port    int    `json:"port"`
    Debug   bool   `json:"debug"`
}

jety.SetConfigFile("config.json")
jety.SetConfigType("json")
jety.ReadInConfig()

var cfg Config
if err := jety.Unmarshal(&cfg); err != nil {
    log.Fatal(err)
}

For nested sections, use UnmarshalKey:

type DatabaseConfig struct {
    Host string `json:"host"`
    Port int    `json:"port"`
    Name string `json:"name"`
}

var dbCfg DatabaseConfig
if err := jety.UnmarshalKey("database", &dbCfg); err != nil {
    log.Fatal(err)
}

Struct tags use json:"..." since the unmarshaling uses JSON round-trip internally. Dot notation works with UnmarshalKey for deeply nested values (e.g., "services.api").

License

See LICENSE file.