ci: add test workflow with race detector and staticcheck

- Extract parseEnv() to deduplicate env parsing in NewConfigManager,
  WithEnvPrefix, and SetEnvPrefix (was 3 copies of the same logic).
- Add doc comments to ConfigMap, ConfigManager, NewConfigManager,
  WithEnvPrefix, SetEnvPrefix, IsSet, AllKeys, AllSettings.
- Rename configType parameter in SetConfigType to avoid shadowing
  the configType type.

.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version: ["1.24", "1.26"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+      - run: go test -race -count=1 ./...
+      - run: go vet ./...
+      - run: go install honnef.co/go/tools/cmd/staticcheck@latest && staticcheck ./...

default.go

@@ -67,3 +67,35 @@ func GetStringMap(key string) map[string]any {
 func GetStringSlice(key string) []string {
 	return defaultConfigManager.GetStringSlice(key)
 }
+
+func Get(key string) any {
+	return defaultConfigManager.Get(key)
+}
+
+func SetBool(key string, value bool) {
+	defaultConfigManager.SetBool(key, value)
+}
+
+func SetString(key string, value string) {
+	defaultConfigManager.SetString(key, value)
+}
+
+func SetConfigDir(path string) {
+	defaultConfigManager.SetConfigDir(path)
+}
+
+func WithEnvPrefix(prefix string) *ConfigManager {
+	return defaultConfigManager.WithEnvPrefix(prefix)
+}
+
+func IsSet(key string) bool {
+	return defaultConfigManager.IsSet(key)
+}
+
+func AllKeys() []string {
+	return defaultConfigManager.AllKeys()
+}
+
+func AllSettings() map[string]any {
+	return defaultConfigManager.AllSettings()
+}

getters.go

@@ -7,15 +7,24 @@ import (
 	"time"
 )
 
+// resolve looks up a key in combinedConfig, falling back to envConfig.
+func (c *ConfigManager) resolve(key string) (ConfigMap, bool) {
+	lower := strings.ToLower(key)
+	if v, ok := c.combinedConfig[lower]; ok {
+		return v, true
+	}
+	if v, ok := c.envConfig[lower]; ok {
+		return v, true
+	}
+	return ConfigMap{}, false
+}
+
 func (c *ConfigManager) Get(key string) any {
 	c.mutex.RLock()
 	defer c.mutex.RUnlock()
-	v, ok := c.combinedConfig[strings.ToLower(key)]
+	v, ok := c.resolve(key)
 	if !ok {
-		v, ok = c.envConfig[strings.ToLower(key)]
-		if !ok {
-			return nil
-		}
+		return nil
 	}
 	return v.Value
 }
@@ -23,12 +32,9 @@ func (c *ConfigManager) Get(key string) any {
 func (c *ConfigManager) GetBool(key string) bool {
 	c.mutex.RLock()
 	defer c.mutex.RUnlock()
-	v, ok := c.combinedConfig[strings.ToLower(key)]
+	v, ok := c.resolve(key)
 	if !ok {
-		v, ok = c.envConfig[strings.ToLower(key)]
-		if !ok {
-			return false
-		}
+		return false
 	}
 	val := v.Value
 	switch val := val.(type) {
@@ -54,12 +60,9 @@ func (c *ConfigManager) GetBool(key string) bool {
 func (c *ConfigManager) GetDuration(key string) time.Duration {
 	c.mutex.RLock()
 	defer c.mutex.RUnlock()
-	v, ok := c.combinedConfig[strings.ToLower(key)]
+	v, ok := c.resolve(key)
 	if !ok {
-		v, ok = c.envConfig[strings.ToLower(key)]
-		if !ok {
-			return 0
-		}
+		return 0
 	}
 	val := v.Value
 	switch val := val.(type) {
@@ -89,12 +92,9 @@ func (c *ConfigManager) GetDuration(key string) time.Duration {
 func (c *ConfigManager) GetString(key string) string {
 	c.mutex.RLock()
 	defer c.mutex.RUnlock()
-	v, ok := c.combinedConfig[strings.ToLower(key)]
+	v, ok := c.resolve(key)
 	if !ok {
-		v, ok = c.envConfig[strings.ToLower(key)]
-		if !ok {
-			return ""
-		}
+		return ""
 	}
 
 	switch val := v.Value.(type) {
@@ -108,12 +108,9 @@ func (c *ConfigManager) GetString(key string) string {
 func (c *ConfigManager) GetStringMap(key string) map[string]any {
 	c.mutex.RLock()
 	defer c.mutex.RUnlock()
-	v, ok := c.combinedConfig[strings.ToLower(key)]
+	v, ok := c.resolve(key)
 	if !ok {
-		v, ok = c.envConfig[strings.ToLower(key)]
-		if !ok {
-			return nil
-		}
+		return nil
 	}
 	switch val := v.Value.(type) {
 	case map[string]any:
@@ -126,12 +123,9 @@ func (c *ConfigManager) GetStringMap(key string) map[string]any {
 func (c *ConfigManager) GetStringSlice(key string) []string {
 	c.mutex.RLock()
 	defer c.mutex.RUnlock()
-	v, ok := c.combinedConfig[strings.ToLower(key)]
+	v, ok := c.resolve(key)
 	if !ok {
-		v, ok = c.envConfig[strings.ToLower(key)]
-		if !ok {
-			return nil
-		}
+		return nil
 	}
 	switch val := v.Value.(type) {
 	case []string:
@@ -155,12 +149,9 @@ func (c *ConfigManager) GetStringSlice(key string) []string {
 func (c *ConfigManager) GetInt(key string) int {
 	c.mutex.RLock()
 	defer c.mutex.RUnlock()
-	v, ok := c.combinedConfig[strings.ToLower(key)]
+	v, ok := c.resolve(key)
 	if !ok {
-		v, ok = c.envConfig[strings.ToLower(key)]
-		if !ok {
-			return 0
-		}
+		return 0
 	}
 	switch val := v.Value.(type) {
 	case int:
@@ -187,12 +178,9 @@ func (c *ConfigManager) GetInt(key string) int {
 func (c *ConfigManager) GetIntSlice(key string) []int {
 	c.mutex.RLock()
 	defer c.mutex.RUnlock()
-	v, ok := c.combinedConfig[strings.ToLower(key)]
+	v, ok := c.resolve(key)
 	if !ok {
-		v, ok = c.envConfig[strings.ToLower(key)]
-		if !ok {
-			return nil
-		}
+		return nil
 	}
 	switch val := v.Value.(type) {
 	case []int:

jety.go

@@ -22,23 +22,25 @@ const (
 type (
 	configType string
 
+	// ConfigMap holds a configuration entry with its original key name and value.
 	ConfigMap struct {
 		Key   string
 		Value any
 	}
 
+	// ConfigManager manages layered configuration from defaults, files,
+	// environment variables, and programmatic overrides.
 	ConfigManager struct {
-		configName       string
-		configPath       string
-		configFileUsed   string
-		configType       configType
-		overrideConfig   map[string]ConfigMap
-		fileConfig       map[string]ConfigMap
-		defaultConfig    map[string]ConfigMap
-		envConfig        map[string]ConfigMap
-		combinedConfig   map[string]ConfigMap
-		mutex            sync.RWMutex
-		explicitDefaults bool
+		configName     string
+		configPath     string
+		configFileUsed string
+		configType     configType
+		overrideConfig map[string]ConfigMap
+		fileConfig     map[string]ConfigMap
+		defaultConfig  map[string]ConfigMap
+		envConfig      map[string]ConfigMap
+		combinedConfig map[string]ConfigMap
+		mutex          sync.RWMutex
 	}
 )
 
@@ -47,40 +49,47 @@ var (
 	ErrConfigFileEmpty    = errors.New("config file is empty")
 )
 
-func NewConfigManager() *ConfigManager {
-	cm := ConfigManager{}
-	cm.envConfig = make(map[string]ConfigMap)
-	cm.overrideConfig = make(map[string]ConfigMap)
-	cm.fileConfig = make(map[string]ConfigMap)
-	cm.defaultConfig = make(map[string]ConfigMap)
-	cm.combinedConfig = make(map[string]ConfigMap)
-	envSet := os.Environ()
-	for _, env := range envSet {
+// parseEnv reads environment variables, optionally filtering by prefix,
+// and returns a map keyed by lowercased (and prefix-stripped) variable names.
+func parseEnv(prefix string) map[string]ConfigMap {
+	result := make(map[string]ConfigMap)
+	for _, env := range os.Environ() {
 		key, value, found := strings.Cut(env, "=")
 		if !found {
 			continue
 		}
-		lower := strings.ToLower(key)
-		cm.envConfig[lower] = ConfigMap{Key: key, Value: value}
+		if prefix != "" {
+			stripped, ok := strings.CutPrefix(key, prefix)
+			if !ok {
+				continue
+			}
+			key = stripped
+		}
+		result[strings.ToLower(key)] = ConfigMap{Key: key, Value: value}
 	}
-	return &cm
+	return result
 }
 
+// NewConfigManager creates a new ConfigManager with all environment
+// variables loaded. Use [ConfigManager.WithEnvPrefix] or
+// [ConfigManager.SetEnvPrefix] to filter by prefix.
+func NewConfigManager() *ConfigManager {
+	return &ConfigManager{
+		envConfig:      parseEnv(""),
+		overrideConfig: make(map[string]ConfigMap),
+		fileConfig:     make(map[string]ConfigMap),
+		defaultConfig:  make(map[string]ConfigMap),
+		combinedConfig: make(map[string]ConfigMap),
+	}
+}
+
+// WithEnvPrefix filters environment variables to only those starting with
+// the given prefix, stripping the prefix from key names. Returns the
+// ConfigManager for chaining.
 func (c *ConfigManager) WithEnvPrefix(prefix string) *ConfigManager {
 	c.mutex.Lock()
 	defer c.mutex.Unlock()
-	envSet := os.Environ()
-	c.envConfig = make(map[string]ConfigMap)
-	for _, env := range envSet {
-		key, value, found := strings.Cut(env, "=")
-		if !found {
-			continue
-		}
-		if withoutPrefix, ok := strings.CutPrefix(key, prefix); ok {
-			lower := strings.ToLower(withoutPrefix)
-			c.envConfig[lower] = ConfigMap{Key: withoutPrefix, Value: value}
-		}
-	}
+	c.envConfig = parseEnv(prefix)
 	return c
 }
 
@@ -90,10 +99,48 @@ func (c *ConfigManager) ConfigFileUsed() string {
 	return c.configFileUsed
 }
 
-func (c *ConfigManager) UseExplicitDefaults(enable bool) {
-	c.mutex.Lock()
-	defer c.mutex.Unlock()
-	c.explicitDefaults = enable
+// IsSet checks whether a key has been set in any configuration source.
+func (c *ConfigManager) IsSet(key string) bool {
+	c.mutex.RLock()
+	defer c.mutex.RUnlock()
+	lower := strings.ToLower(key)
+	if _, ok := c.combinedConfig[lower]; ok {
+		return true
+	}
+	_, ok := c.envConfig[lower]
+	return ok
+}
+
+// AllKeys returns all keys from all configuration sources, deduplicated.
+func (c *ConfigManager) AllKeys() []string {
+	c.mutex.RLock()
+	defer c.mutex.RUnlock()
+	seen := make(map[string]struct{})
+	var keys []string
+	for k := range c.combinedConfig {
+		if _, ok := seen[k]; !ok {
+			seen[k] = struct{}{}
+			keys = append(keys, k)
+		}
+	}
+	for k := range c.envConfig {
+		if _, ok := seen[k]; !ok {
+			seen[k] = struct{}{}
+			keys = append(keys, k)
+		}
+	}
+	return keys
+}
+
+// AllSettings returns all settings as a flat map of key to value.
+func (c *ConfigManager) AllSettings() map[string]any {
+	c.mutex.RLock()
+	defer c.mutex.RUnlock()
+	result := make(map[string]any, len(c.combinedConfig))
+	for k, v := range c.combinedConfig {
+		result[k] = v.Value
+	}
+	return result
 }
 
 func (c *ConfigManager) collapse() {
@@ -107,8 +154,10 @@ func (c *ConfigManager) collapse() {
 	for k, v := range c.fileConfig {
 		ccm[k] = v
 	}
-	for k := range c.defaultConfig {
-		if v, ok := c.envConfig[k]; ok {
+	for k, v := range c.envConfig {
+		if _, inDefaults := c.defaultConfig[k]; inDefaults {
+			ccm[k] = v
+		} else if _, inFile := c.fileConfig[k]; inFile {
 			ccm[k] = v
 		}
 	}
@@ -121,6 +170,9 @@ func (c *ConfigManager) collapse() {
 func (c *ConfigManager) WriteConfig() error {
 	c.mutex.RLock()
 	defer c.mutex.RUnlock()
+	if c.configFileUsed == "" {
+		return errors.New("no config file specified")
+	}
 	flattenedConfig := make(map[string]any)
 	for _, v := range c.combinedConfig {
 		flattenedConfig[v.Key] = v.Value
@@ -142,8 +194,10 @@ func (c *ConfigManager) WriteConfig() error {
 		}
 		defer f.Close()
 		enc := yaml.NewEncoder(f)
-		err = enc.Encode(flattenedConfig)
-		return err
+		if err = enc.Encode(flattenedConfig); err != nil {
+			return err
+		}
+		return enc.Close()
 	case ConfigTypeJSON:
 		f, err := os.Create(c.configFileUsed)
 		if err != nil {
@@ -157,10 +211,10 @@ func (c *ConfigManager) WriteConfig() error {
 	}
 }
 
-func (c *ConfigManager) SetConfigType(configType string) error {
+func (c *ConfigManager) SetConfigType(ct string) error {
 	c.mutex.Lock()
 	defer c.mutex.Unlock()
-	switch configType {
+	switch ct {
 	case "toml":
 		c.configType = ConfigTypeTOML
 	case "yaml":
@@ -168,29 +222,17 @@ func (c *ConfigManager) SetConfigType(configType string) error {
 	case "json":
 		c.configType = ConfigTypeJSON
 	default:
-		return fmt.Errorf("config type %s not supported", configType)
+		return fmt.Errorf("config type %s not supported", ct)
 	}
 	return nil
 }
 
+// SetEnvPrefix filters environment variables to only those starting with
+// the given prefix, stripping the prefix from key names.
 func (c *ConfigManager) SetEnvPrefix(prefix string) {
 	c.mutex.Lock()
 	defer c.mutex.Unlock()
-	// Re-read environment variables, stripping the prefix from matching keys.
-	// This mirrors WithEnvPrefix behavior so that prefixed env vars are
-	// accessible by their unprefixed key name.
-	envSet := os.Environ()
-	c.envConfig = make(map[string]ConfigMap)
-	for _, env := range envSet {
-		key, value, found := strings.Cut(env, "=")
-		if !found {
-			continue
-		}
-		if withoutPrefix, ok := strings.CutPrefix(key, prefix); ok {
-			lower := strings.ToLower(withoutPrefix)
-			c.envConfig[lower] = ConfigMap{Key: withoutPrefix, Value: value}
-		}
-	}
+	c.envConfig = parseEnv(prefix)
 }
 
 func (c *ConfigManager) ReadInConfig() error {
@@ -233,33 +275,33 @@ func (c *ConfigManager) ReadInConfig() error {
 }
 
 func readFile(filename string, fileType configType) (map[string]any, error) {
-	fileData := make(map[string]any)
-	if d, err := os.Stat(filename); os.IsNotExist(err) {
-		return nil, ErrConfigFileNotFound
-	} else if d.Size() == 0 {
+	f, err := os.Open(filename)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, ErrConfigFileNotFound
+		}
+		return nil, err
+	}
+	defer f.Close()
+
+	info, err := f.Stat()
+	if err != nil {
+		return nil, err
+	}
+	if info.Size() == 0 {
 		return nil, ErrConfigFileEmpty
 	}
 
+	fileData := make(map[string]any)
 	switch fileType {
 	case ConfigTypeTOML:
-		_, err := toml.DecodeFile(filename, &fileData)
+		_, err := toml.NewDecoder(f).Decode(&fileData)
 		return fileData, err
 	case ConfigTypeYAML:
-		f, err := os.Open(filename)
-		if err != nil {
-			return nil, err
-		}
-		defer f.Close()
-		d := yaml.NewDecoder(f)
-		err = d.Decode(&fileData)
+		err := yaml.NewDecoder(f).Decode(&fileData)
 		return fileData, err
 	case ConfigTypeJSON:
-		f, err := os.Open(filename)
-		if err != nil {
-			return nil, err
-		}
-		defer f.Close()
-		err = json.NewDecoder(f).Decode(&fileData)
+		err := json.NewDecoder(f).Decode(&fileData)
 		return fileData, err
 	default:
 		return nil, fmt.Errorf("config type %s not supported", fileType)

jety_test.go

@@ -760,17 +760,6 @@ func TestPackageLevelFunctions(t *testing.T) {
 	}
 }
 
-func TestUseExplicitDefaults(t *testing.T) {
-	cm := NewConfigManager()
-	cm.UseExplicitDefaults(true)
-
-	// Just verify it doesn't panic and the field is set
-	cm.SetDefault("key", "value")
-	if got := cm.GetString("key"); got != "value" {
-		t.Errorf("GetString(key) = %q, want %q", got, "value")
-	}
-}
-
 func TestSetString(t *testing.T) {
 	cm := NewConfigManager()
 	cm.SetString("name", "test")
@@ -1397,3 +1386,83 @@ func TestPrecedenceChain(t *testing.T) {
 		t.Errorf("extra: got %q, want defaultextra (default)", got)
 	}
 }
+
+func TestIsSet(t *testing.T) {
+	cm := NewConfigManager()
+	cm.Set("exists", "yes")
+
+	if !cm.IsSet("exists") {
+		t.Error("IsSet(exists) = false, want true")
+	}
+	if cm.IsSet("nope") {
+		t.Error("IsSet(nope) = true, want false")
+	}
+}
+
+func TestAllKeys(t *testing.T) {
+	cm := NewConfigManager()
+	cm.SetDefault("a", 1)
+	cm.Set("b", 2)
+
+	keys := cm.AllKeys()
+	found := make(map[string]bool)
+	for _, k := range keys {
+		found[k] = true
+	}
+	if !found["a"] || !found["b"] {
+		t.Errorf("AllKeys() = %v, want to contain a and b", keys)
+	}
+}
+
+func TestAllSettings(t *testing.T) {
+	cm := NewConfigManager()
+	cm.Set("port", 8080)
+	cm.Set("host", "localhost")
+
+	settings := cm.AllSettings()
+	if settings["port"] != 8080 || settings["host"] != "localhost" {
+		t.Errorf("AllSettings() = %v", settings)
+	}
+}
+
+func TestEnvOverridesFileWithoutDefault(t *testing.T) {
+	// Bug fix: env should override file even when no default is set for that key
+	os.Setenv("HOST", "envhost")
+	defer os.Unsetenv("HOST")
+
+	dir := t.TempDir()
+	configFile := filepath.Join(dir, "config.yaml")
+	if err := os.WriteFile(configFile, []byte("host: filehost"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cm := NewConfigManager()
+	cm.SetConfigFile(configFile)
+	if err := cm.SetConfigType("yaml"); err != nil {
+		t.Fatal(err)
+	}
+	if err := cm.ReadInConfig(); err != nil {
+		t.Fatal(err)
+	}
+
+	// No SetDefault("host", ...) was called — env should still win
+	if got := cm.GetString("host"); got != "envhost" {
+		t.Errorf("GetString(host) = %q, want envhost (env overrides file even without default)", got)
+	}
+}
+
+func TestPackageLevelIsSet(t *testing.T) {
+	defaultConfigManager = NewConfigManager()
+	Set("x", 1)
+	if !IsSet("x") {
+		t.Error("IsSet(x) = false")
+	}
+}
+
+func TestPackageLevelGet(t *testing.T) {
+	defaultConfigManager = NewConfigManager()
+	Set("key", "val")
+	if Get("key") != "val" {
+		t.Error("Get(key) failed")
+	}
+}

setters.go

@@ -33,14 +33,14 @@ func (c *ConfigManager) SetDefault(key string, value any) {
 	defer c.mutex.Unlock()
 	lower := strings.ToLower(key)
 	c.defaultConfig[lower] = ConfigMap{Key: key, Value: value}
-	if _, ok := c.overrideConfig[lower]; !ok {
-		if envVal, ok := c.envConfig[lower]; ok {
-			c.overrideConfig[lower] = ConfigMap{Key: key, Value: envVal.Value}
-			c.combinedConfig[lower] = ConfigMap{Key: key, Value: envVal.Value}
-		} else {
-			c.combinedConfig[lower] = ConfigMap{Key: key, Value: value}
-		}
+	// Update combinedConfig respecting precedence: override > env > file > default
+	if v, ok := c.overrideConfig[lower]; ok {
+		c.combinedConfig[lower] = v
+	} else if v, ok := c.envConfig[lower]; ok {
+		c.combinedConfig[lower] = ConfigMap{Key: key, Value: v.Value}
+	} else if v, ok := c.fileConfig[lower]; ok {
+		c.combinedConfig[lower] = v
 	} else {
-		c.combinedConfig[lower] = c.overrideConfig[lower]
+		c.combinedConfig[lower] = ConfigMap{Key: key, Value: value}
 	}
 }