jety

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). Nested env vars like SERVICES_CLOUD_VAR also apply to dot-notation lookups, GetStringMap, AllSettings, Unmarshal, and UnmarshalKey.

API

Configuration

Values

Environment

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.