v0.1.2 minor refactor, helpers back to private, utility update

2025-11-14 13:02:19 -05:00
parent 7bcd90df3a
commit f4a19aa72a
12 changed files with 178 additions and 53 deletions
--- a/utility.go
+++ b/utility.go
@ -0,0 +1,365 @@
+// FILE: lixenwraith/config/utility.go
+package config
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+	"reflect"
+	"strings"
+	"time"
+
+	"github.com/BurntSushi/toml"
+	"github.com/go-viper/mapstructure/v2"
+)
+
+// Quick creates a fully configured Config instance with a single call
+// This is the recommended way to initialize configuration for most applications
+func Quick(structDefaults any, envPrefix, configFile string) (*Config, error) {
+	cfg := New()
+
+	// Register defaults from struct if provided
+	if structDefaults != nil {
+		if err := cfg.RegisterStruct("", structDefaults); err != nil {
+			return nil, wrapError(ErrTypeMismatch, fmt.Errorf("failed to register defaults: %w", err))
+		}
+	}
+
+	// Load with standard precedence: CLI > Env > File > Default
+	opts := DefaultLoadOptions()
+	opts.EnvPrefix = envPrefix
+
+	err := cfg.loadWithOptions(configFile, os.Args[1:], opts)
+	return cfg, err
+}
+
+// QuickCustom creates a Config with custom options
+func QuickCustom(structDefaults any, opts LoadOptions, configFile string) (*Config, error) {
+	cfg := NewWithOptions(opts)
+
+	// Register defaults from struct if provided
+	if structDefaults != nil {
+		if err := cfg.RegisterStruct("", structDefaults); err != nil {
+			return nil, wrapError(ErrTypeMismatch, fmt.Errorf("failed to register defaults: %w", err))
+		}
+	}
+
+	err := cfg.loadWithOptions(configFile, os.Args[1:], opts)
+	return cfg, err
+}
+
+// MustQuick is like Quick but panics on error
+func MustQuick(structDefaults any, envPrefix, configFile string) *Config {
+	cfg, err := Quick(structDefaults, envPrefix, configFile)
+	if err != nil && !errors.Is(err, ErrConfigNotFound) {
+		panic(fmt.Sprintf("config initialization failed: %v", err))
+	}
+	return cfg
+}
+
+// GenerateFlags creates flag.FlagSet entries for all registered paths
+func (c *Config) GenerateFlags() *flag.FlagSet {
+	fs := flag.NewFlagSet("config", flag.ContinueOnError)
+
+	c.mutex.RLock()
+	defer c.mutex.RUnlock()
+
+	for path, item := range c.items {
+		// Create flag based on default value type
+		switch v := item.defaultValue.(type) {
+		case bool:
+			fs.Bool(path, v, fmt.Sprintf("Config: %s", path))
+		case int64:
+			fs.Int64(path, v, fmt.Sprintf("Config: %s", path))
+		case int:
+			fs.Int(path, v, fmt.Sprintf("Config: %s", path))
+		case float64:
+			fs.Float64(path, v, fmt.Sprintf("Config: %s", path))
+		case string:
+			fs.String(path, v, fmt.Sprintf("Config: %s", path))
+		default:
+			// For other types, use string flag
+			fs.String(path, fmt.Sprintf("%v", v), fmt.Sprintf("Config: %s", path))
+		}
+	}
+
+	return fs
+}
+
+// BindFlags updates configuration from parsed flag.FlagSet
+func (c *Config) BindFlags(fs *flag.FlagSet) error {
+	var errors []error
+	needsInvalidation := false
+
+	fs.Visit(func(f *flag.Flag) {
+		value := f.Value.String()
+		// Let mapstructure handle type conversion
+		if err := c.SetSource(SourceCLI, f.Name, value); err != nil {
+			errors = append(errors, fmt.Errorf("flag %s: %w", f.Name, err))
+		} else {
+			needsInvalidation = true
+		}
+	})
+
+	if needsInvalidation {
+		c.invalidateCache() // Batch invalidation after all flags
+	}
+
+	if len(errors) > 0 {
+		return wrapError(ErrCLIParse, fmt.Errorf("failed to bind %d flags: %w", len(errors), errors[0]))
+	}
+
+	return nil
+}
+
+// Validate checks that all required configuration values are set
+// A value is considered "set" if it differs from its default value
+func (c *Config) Validate(required ...string) error {
+	c.mutex.RLock()
+	defer c.mutex.RUnlock()
+
+	var missing []string
+
+	for _, path := range required {
+		item, exists := c.items[path]
+		if !exists {
+			missing = append(missing, path+" (not registered)")
+			continue
+		}
+
+		// Check if value equals default (indicating not set)
+		if reflect.DeepEqual(item.currentValue, item.defaultValue) {
+			// Check if any source provided a value
+			hasValue := false
+			for _, val := range item.values {
+				if val != nil {
+					hasValue = true
+					break
+				}
+			}
+			if !hasValue {
+				missing = append(missing, path)
+			}
+		}
+	}
+
+	if len(missing) > 0 {
+		return wrapError(ErrValidation, fmt.Errorf("missing required configuration: %s", strings.Join(missing, ", ")))
+	}
+
+	return nil
+}
+
+// Debug returns a formatted string showing all configuration values and their sources
+func (c *Config) Debug() string {
+	c.mutex.RLock()
+	defer c.mutex.RUnlock()
+
+	var b strings.Builder
+	b.WriteString("Configuration Debug Info:\n")
+	b.WriteString(fmt.Sprintf("Precedence: %v\n", c.options.Sources))
+	b.WriteString("Current values:\n")
+
+	for path, item := range c.items {
+		b.WriteString(fmt.Sprintf("  %s:\n", path))
+		b.WriteString(fmt.Sprintf("    Current: %v\n", item.currentValue))
+		b.WriteString(fmt.Sprintf("    Default: %v\n", item.defaultValue))
+
+		for source, value := range item.values {
+			b.WriteString(fmt.Sprintf("    %s: %v\n", source, value))
+		}
+	}
+
+	return b.String()
+}
+
+// Dump writes the current configuration to stdout in TOML format
+func (c *Config) Dump() error {
+	c.mutex.RLock()
+	defer c.mutex.RUnlock()
+
+	nestedData := make(map[string]any)
+	for path, item := range c.items {
+		setNestedValue(nestedData, path, item.currentValue)
+	}
+
+	encoder := toml.NewEncoder(os.Stdout)
+	if err := encoder.Encode(nestedData); err != nil {
+		return wrapError(ErrDecode, err)
+	}
+	return nil
+}
+
+// Clone creates a deep copy of the configuration
+func (c *Config) Clone() *Config {
+	c.mutex.RLock()
+	defer c.mutex.RUnlock()
+
+	clone := &Config{
+		items:    make(map[string]configItem),
+		options:  c.options,
+		fileData: make(map[string]any),
+		envData:  make(map[string]any),
+		cliData:  make(map[string]any),
+	}
+
+	// Deep copy items
+	for path, item := range c.items {
+		newItem := configItem{
+			defaultValue: item.defaultValue,
+			currentValue: item.currentValue,
+			values:       make(map[Source]any),
+		}
+
+		for source, value := range item.values {
+			newItem.values[source] = value
+		}
+
+		clone.items[path] = newItem
+	}
+
+	// Copy cache data
+	for k, v := range c.fileData {
+		clone.fileData[k] = v
+	}
+	for k, v := range c.envData {
+		clone.envData[k] = v
+	}
+	for k, v := range c.cliData {
+		clone.cliData[k] = v
+	}
+
+	return clone
+}
+
+// QuickTyped creates a fully configured Config with a typed target
+func QuickTyped[T any](target *T, envPrefix, configFile string) (*Config, error) {
+	return NewBuilder().
+		WithTarget(target).
+		WithEnvPrefix(envPrefix).
+		WithFile(configFile).
+		Build()
+}
+
+// GetTyped retrieves a configuration value and decodes it into the specified type T
+// It leverages the same decoding hooks as the Scan and AsStruct methods,
+// providing type conversion from strings, numbers, etc.
+func GetTyped[T any](c *Config, path string) (T, error) {
+	var zero T
+
+	rawValue, exists := c.Get(path)
+	if !exists {
+		return zero, wrapError(ErrPathNotFound, fmt.Errorf("path %q not found", path))
+	}
+
+	// Prepare the input map and target struct for the decoder
+	inputMap := map[string]any{"value": rawValue}
+	var target struct {
+		Value T `mapstructure:"value"`
+	}
+
+	// Create a new decoder configured with the same hooks as the main config
+	decoder, err := mapstructure.NewDecoder(&mapstructure.DecoderConfig{
+		Result:           &target,
+		TagName:          c.tagName,
+		WeaklyTypedInput: true,
+		DecodeHook:       c.getDecodeHook(),
+		Metadata:         nil,
+	})
+	if err != nil {
+		return zero, wrapError(ErrDecode, fmt.Errorf("failed to create decoder for path %q: %w", path, err))
+	}
+
+	// Decode the single value.
+	if err := decoder.Decode(inputMap); err != nil {
+		return zero, wrapError(ErrDecode, fmt.Errorf("failed to decode value for path %q into type %T: %w", path, zero, err))
+	}
+
+	return target.Value, nil
+}
+
+// GetTypedWithDefault retrieves a configuration value with a default fallback
+// If the path doesn't exist or isn't set, it sets and returns the default value
+// For simple cases where explicit defaults aren't pre-registered
+func GetTypedWithDefault[T any](c *Config, path string, defaultValue T) (T, error) {
+	// Check if path exists and has a value
+	if _, exists := c.Get(path); exists {
+		// Path exists, try to decode the current value
+		result, err := GetTyped[T](c, path)
+		if err == nil {
+			return result, nil
+		}
+		// Type conversion failed, fall through to set default
+	}
+
+	// Path doesn't exist or value not set - register and set default
+	// This handles the case where the path wasn't pre-registered
+	if err := c.Register(path, defaultValue); err != nil {
+		// Path might already be registered with incompatible type
+		// Try to just set the value
+		if setErr := c.Set(path, defaultValue); setErr != nil {
+			return defaultValue, wrapError(ErrPathNotRegistered, fmt.Errorf("%w : failed to register or set default for path %q", ErrPathNotRegistered, path))
+		}
+	}
+
+	// Set the default value
+	if err := c.Set(path, defaultValue); err != nil {
+		return defaultValue, wrapError(ErrTypeMismatch, fmt.Errorf("%w : failed to set default value for path %q", ErrTypeMismatch, path))
+	}
+
+	return defaultValue, nil
+}
+
+// ScanTyped is a generic wrapper around Scan. It allocates a new instance of type T,
+// populates it with configuration data from the given base path, and returns a pointer to it
+func ScanTyped[T any](c *Config, basePath ...string) (*T, error) {
+	var target T
+	if err := c.Scan(&target, basePath...); err != nil {
+		return nil, err
+	}
+	return &target, nil
+}
+
+// ScanMap decodes a configuration map directly into a target struct
+// without requiring a full Config instance. This is useful for plugin
+// initialization where config data arrives as a map[string]any.
+func ScanMap(configMap map[string]any, target any, tagName ...string) error {
+	// Handle nil map
+	if configMap == nil {
+		configMap = make(map[string]any)
+	}
+
+	// Determine tag name
+	tag := "toml" // default
+	if len(tagName) > 0 && tagName[0] != "" {
+		tag = tagName[0]
+	}
+
+	// Create decoder with standard hooks
+	decoder, err := mapstructure.NewDecoder(&mapstructure.DecoderConfig{
+		Result:           target,
+		TagName:          tag,
+		WeaklyTypedInput: true,
+		DecodeHook: mapstructure.ComposeDecodeHookFunc(
+			jsonNumberHookFunc(),
+			stringToNetIPHookFunc(),
+			stringToNetIPNetHookFunc(),
+			stringToURLHookFunc(),
+			mapstructure.StringToTimeDurationHookFunc(),
+			mapstructure.StringToTimeHookFunc(time.RFC3339),
+			mapstructure.StringToSliceHookFunc(","),
+		),
+		ZeroFields: true,
+	})
+	if err != nil {
+		return wrapError(ErrDecode, fmt.Errorf("decoder creation failed: %w", err))
+	}
+
+	// Decode directly
+	if err := decoder.Decode(configMap); err != nil {
+		return wrapError(ErrDecode, fmt.Errorf("decode failed: %w", err))
+	}
+
+	return nil
+}