env.go

package env

import (
	"os"
	"strconv"
	"strings"
	"time"
)

// Get returns the environment variable for key or fallback when empty.
// @group Typed getters
// @behavior readonly
//
// Examples use github.com/goforj/godump to illustrate the concrete type.
//
// Example: fallback when unset
//
//	os.Unsetenv("DB_HOST")
//	host := env.Get("DB_HOST", "localhost")
//	env.Dump(host)
//	// #string "localhost"
//
// Example: prefer existing value
//
//	_ = os.Setenv("DB_HOST", "db.internal")
//	host = env.Get("DB_HOST", "localhost")
//	env.Dump(host)
//	// #string "db.internal"
func Get(key, fallback string) string {
	val := os.Getenv(key)
	if len(val) == 0 {
		return fallback
	}
	return val
}

// GetInt parses an int from an environment variable or fallback string.
// @group Typed getters
// @behavior readonly
//
// Example: fallback used
//
//	os.Unsetenv("PORT")
//	port := env.GetInt("PORT", "3000")
//	env.Dump(port)
//	// #int 3000
//
// Example: env overrides fallback
//
//	_ = os.Setenv("PORT", "8080")
//	port = env.GetInt("PORT", "3000")
//	env.Dump(port)
//	// #int 8080
func GetInt(key, fallback string) int {
	val := os.Getenv(key)
	if val != "" {
		if ret, err := strconv.Atoi(val); err == nil {
			return ret
		}
	}
	if fallback != "" {
		if ret, err := strconv.Atoi(fallback); err == nil {
			return ret
		}
	}
	return 0
}

// GetInt64 parses an int64 from an environment variable or fallback string.
// @group Typed getters
// @behavior readonly
//
// Example: parse large numbers safely
//
//	_ = os.Setenv("MAX_SIZE", "1048576")
//	size := env.GetInt64("MAX_SIZE", "512")
//	env.Dump(size)
//	// #int64 1048576
//
// Example: fallback when unset
//
//	os.Unsetenv("MAX_SIZE")
//	size = env.GetInt64("MAX_SIZE", "512")
//	env.Dump(size)
//	// #int64 512
func GetInt64(key, fallback string) int64 {
	val := os.Getenv(key)
	if val != "" {
		if ret, err := strconv.ParseInt(val, 10, 64); err == nil {
			return ret
		}
	}
	if fallback != "" {
		if ret, err := strconv.ParseInt(fallback, 10, 64); err == nil {
			return ret
		}
	}
	return 0
}

// GetUint parses a uint from an environment variable or fallback string.
// @group Typed getters
// @behavior readonly
//
// Example: defaults to fallback when missing
//
//	os.Unsetenv("WORKERS")
//	workers := env.GetUint("WORKERS", "4")
//	env.Dump(workers)
//	// #uint 4
//
// Example: uses provided unsigned value
//
//	_ = os.Setenv("WORKERS", "16")
//	workers = env.GetUint("WORKERS", "4")
//	env.Dump(workers)
//	// #uint 16
func GetUint(key, fallback string) uint {
	val := os.Getenv(key)
	if val != "" {
		if i, err := strconv.ParseUint(val, 10, 32); err == nil {
			return uint(i)
		}
	}
	if fallback != "" {
		if i, err := strconv.ParseUint(fallback, 10, 32); err == nil {
			return uint(i)
		}
	}
	return 0
}

// GetUint64 parses a uint64 from an environment variable or fallback string.
// @group Typed getters
// @behavior readonly
//
// Example: high range values
//
//	_ = os.Setenv("MAX_ITEMS", "5000")
//	maxItems := env.GetUint64("MAX_ITEMS", "100")
//	env.Dump(maxItems)
//	// #uint64 5000
//
// Example: fallback when unset
//
//	os.Unsetenv("MAX_ITEMS")
//	maxItems = env.GetUint64("MAX_ITEMS", "100")
//	env.Dump(maxItems)
//	// #uint64 100
func GetUint64(key, fallback string) uint64 {
	val := os.Getenv(key)
	if val != "" {
		if i, err := strconv.ParseUint(val, 10, 64); err == nil {
			return i
		}
	}
	if fallback != "" {
		if i, err := strconv.ParseUint(fallback, 10, 64); err == nil {
			return i
		}
	}
	return 0
}

// GetFloat parses a float64 from an environment variable or fallback string.
// @group Typed getters
// @behavior readonly
//
// Example: override threshold
//
//	_ = os.Setenv("THRESHOLD", "0.82")
//	threshold := env.GetFloat("THRESHOLD", "0.75")
//	env.Dump(threshold)
//	// #float64 0.82
//
// Example: fallback with decimal string
//
//	os.Unsetenv("THRESHOLD")
//	threshold = env.GetFloat("THRESHOLD", "0.75")
//	env.Dump(threshold)
//	// #float64 0.75
func GetFloat(key, fallback string) float64 {
	val := os.Getenv(key)
	if val != "" {
		if f, err := strconv.ParseFloat(val, 64); err == nil {
			return f
		}
	}
	if fallback != "" {
		if f, err := strconv.ParseFloat(fallback, 64); err == nil {
			return f
		}
	}
	return 0
}

// GetBool parses a boolean from an environment variable or fallback string.
// @group Typed getters
// @behavior readonly
//
// Accepted values: true/false, 1/0, t/f (case-insensitive). Invalid entries fall back.
//
// Example: numeric truthy
//
//	_ = os.Setenv("DEBUG", "1")
//	debug := env.GetBool("DEBUG", "false")
//	env.Dump(debug)
//	// #bool true
//
// Example: fallback string
//
//	os.Unsetenv("DEBUG")
//	debug = env.GetBool("DEBUG", "false")
//	env.Dump(debug)
//	// #bool false
func GetBool(key, fallback string) bool {
	val := os.Getenv(key)
	if val != "" {
		if ret, err := strconv.ParseBool(val); err == nil {
			return ret
		}
	}
	if fallback != "" {
		if ret, err := strconv.ParseBool(fallback); err == nil {
			return ret
		}
	}
	return false
}

// GetDuration parses a Go duration string (e.g. "5s", "10m", "1h").
// @group Typed getters
// @behavior readonly
//
// Example: override request timeout
//
//	_ = os.Setenv("HTTP_TIMEOUT", "30s")
//	timeout := env.GetDuration("HTTP_TIMEOUT", "5s")
//	env.Dump(timeout)
//	// #time.Duration 30s
//
// Example: fallback when unset
//
//	os.Unsetenv("HTTP_TIMEOUT")
//	timeout = env.GetDuration("HTTP_TIMEOUT", "5s")
//	env.Dump(timeout)
//	// #time.Duration 5s
func GetDuration(key, fallback string) time.Duration {
	val := os.Getenv(key)
	if val != "" {
		if d, err := time.ParseDuration(val); err == nil {
			return d
		}
	}
	if fallback != "" {
		if d, err := time.ParseDuration(fallback); err == nil {
			return d
		}
	}
	return 0
}

// GetSlice splits a comma-separated string into a []string with trimming.
// @group Typed getters
// @behavior readonly
//
// Example: trimmed addresses
//
//	_ = os.Setenv("PEERS", "10.0.0.1, 10.0.0.2")
//	peers := env.GetSlice("PEERS", "")
//	env.Dump(peers)
//	// #[]string [
//	//  0 => "10.0.0.1" #string
//	//  1 => "10.0.0.2" #string
//	// ]
//
// Example: empty becomes empty slice
//
//	os.Unsetenv("PEERS")
//	peers = env.GetSlice("PEERS", "")
//	env.Dump(peers)
//	// #[]string []
func GetSlice(key, fallback string) []string {
	val := Get(key, fallback)
	if val == "" {
		return []string{}
	}

	parts := strings.Split(val, ",")
	for i := range parts {
		parts[i] = strings.TrimSpace(parts[i])
	}
	return parts
}

// GetMap parses key=value pairs separated by commas into a map.
// @group Typed getters
// @behavior readonly
//
// Example: parse throttling config
//
//	_ = os.Setenv("LIMITS", "read=10, write=5, burst=20")
//	limits := env.GetMap("LIMITS", "")
//	env.Dump(limits)
//	// #map[string]string [
//	//  "burst" => "20" #string
//	//  "read"  => "10" #string
//	//  "write" => "5" #string
//	// ]
//
// Example: returns empty map when unset or blank
//
//	os.Unsetenv("LIMITS")
//	limits = env.GetMap("LIMITS", "")
//	env.Dump(limits)
//	// #map[string]string []
func GetMap(key, fallback string) map[string]string {
	val := Get(key, fallback)
	m := map[string]string{}

	if strings.TrimSpace(val) == "" {
		return m
	}

	pairs := strings.Split(val, ",")
	for _, p := range pairs {
		kv := strings.SplitN(strings.TrimSpace(p), "=", 2)
		if len(kv) == 2 {
			m[kv[0]] = kv[1]
		}
	}

	return m
}

// GetMapInt parses key=int pairs separated by commas into a map.
// Invalid, missing, or non-positive values fall back to defaultValue.
// @group Typed getters
// @behavior readonly
//
// Example: parse worker queue weights
//
//	_ = os.Setenv("QUEUE_WEIGHTS", "critical=6, default=3, low=1")
//	weights := env.GetMapInt("QUEUE_WEIGHTS", "", 1)
//	env.Dump(weights)
//	// #map[string]int [
//	//  "critical" => 6 #int
//	//  "default"  => 3 #int
//	//  "low"      => 1 #int
//	// ]
//
// Example: invalid values use defaultValue
//
//	os.Unsetenv("QUEUE_WEIGHTS")
//	weights = env.GetMapInt("QUEUE_WEIGHTS", "critical=,default=0,low=nope,misc", 2)
//	env.Dump(weights)
//	// #map[string]int [
//	//  "critical" => 2 #int
//	//  "default"  => 2 #int
//	//  "low"      => 2 #int
//	//  "misc"     => 2 #int
//	// ]
func GetMapInt(key, fallback string, defaultValue int) map[string]int {
	val := Get(key, fallback)
	m := map[string]int{}

	if defaultValue <= 0 {
		defaultValue = 1
	}

	if strings.TrimSpace(val) == "" {
		return m
	}

	pairs := strings.Split(val, ",")
	for _, p := range pairs {
		entry := strings.TrimSpace(p)
		if entry == "" {
			continue
		}

		kv := strings.SplitN(entry, "=", 2)
		name := strings.TrimSpace(kv[0])
		if name == "" {
			continue
		}

		parsed := defaultValue
		if len(kv) == 2 {
			if n, err := strconv.Atoi(strings.TrimSpace(kv[1])); err == nil && n > 0 {
				parsed = n
			}
		}

		m[name] = parsed
	}

	return m
}

// GetEnum ensures the environment variable's value is in the allowed list.
// @group Typed getters
// @behavior readonly
//
// Returns fallback when the environment value is not in the allowed slice.
//
// Example: accept only staged environments
//
//	_ = os.Setenv("APP_ENV", "production")
//	appEnv := env.GetEnum("APP_ENV", "local", []string{"local", "staging", "production"})
//	env.Dump(appEnv)
//	// #string "production"
//
// Example: fallback when unset
//
//	os.Unsetenv("APP_ENV")
//	appEnv = env.GetEnum("APP_ENV", "local", []string{"local", "staging", "production"})
//	env.Dump(appEnv)
//	// #string "local"
func GetEnum(key, fallback string, allowed []string) string {
	val := Get(key, fallback)
	for _, a := range allowed {
		if val == a {
			return val
		}
	}
	for _, a := range allowed {
		if fallback == a {
			return fallback
		}
	}
	return fallback
}

// MustGet returns the value of key or panics if missing/empty.
// @group Typed getters
// @behavior panic
//
// Example: required secret
//
//	_ = os.Setenv("API_SECRET", "s3cr3t")
//	secret := env.MustGet("API_SECRET")
//	env.Dump(secret)
//	// #string "s3cr3t"
//
// Example: panic on missing value
//
//	os.Unsetenv("API_SECRET")
//	secret = env.MustGet("API_SECRET") // panics: env variable missing: API_SECRET
func MustGet(key string) string {
	val := os.Getenv(key)
	if val == "" {
		panic("env variable missing: " + key)
	}
	return val
}

// MustGetInt panics if the value is missing or not an int.
// @group Typed getters
// @behavior panic
//
// Example: ensure numeric port
//
//	_ = os.Setenv("PORT", "8080")
//	port := env.MustGetInt("PORT")
//	env.Dump(port)
//	// #int 8080
//
// Example: panic on bad value
//
//	_ = os.Setenv("PORT", "not-a-number")
//	_ = env.MustGetInt("PORT") // panics when parsing
func MustGetInt(key string) int {
	return GetInt(key, "")
}

// MustGetBool panics if missing or invalid.
// @group Typed getters
// @behavior panic
//
// Example: gate features explicitly
//
//	_ = os.Setenv("FEATURE_ENABLED", "true")
//	enabled := env.MustGetBool("FEATURE_ENABLED")
//	env.Dump(enabled)
//	// #bool true
//
// Example: panic on invalid value
//
//	_ = os.Setenv("FEATURE_ENABLED", "maybe")
//	_ = env.MustGetBool("FEATURE_ENABLED") // panics when parsing
func MustGetBool(key string) bool {
	return GetBool(key, "")
}