Merge pull request #8 from KARTIKrocks/feature-config

add config module

Author: KARTIKrocks

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-02-25
+
+### Added
+
+- **config** — New `config` package: load application configuration from environment variables, `.env` files, and JSON config files into typed Go structs
+- **config** — `Load(dst, ...Option)` populates a struct from sources in priority order (env vars > .env file > JSON file > default tags) and validates with `request.ValidateStruct`
+- **config** — `MustLoad(dst, ...Option)` calls `Load` and panics on error, for use in `main`/`init`
+- **config** — Struct tags: `env:"VAR_NAME"` maps fields to env vars, `default:"value"` sets fallbacks, `validate:"..."` reuses existing request validators
+- **config** — Options: `WithPrefix(p)` for prefixed env vars (e.g., `APP_PORT`), `WithEnvFile(path)` for `.env` files, `WithJSONFile(path)` for JSON base config, `WithRequired()` to error on missing files
+- **config** — Supported types: `string`, `bool`, `int/int8/16/32/64`, `uint` variants, `float32/64`, `time.Duration`, `[]string`, `[]int`
+- **config** — Nested struct support: automatically flattened to env var names (e.g., `DB.Host` → `DB_HOST`)
+- **config** — `.env` file parsing: comments, blank lines, quoted values (single/double), inline comments
+- **config** — JSON config flattening: nested objects become underscore-separated uppercase keys
+- **config** — Structured error messages using `*errors.Error` for parse errors, validation failures, and missing files
+
 ## [0.7.0] - 2026-02-25
 
 ### Added

README.md

@@ -15,6 +15,7 @@ A production-ready Go toolkit for building REST APIs. Zero mandatory dependencie
 - **`router`** — Route grouping with `.Get()`/`.Post()` method helpers, prefix groups, and per-group middleware on top of `http.ServeMux`
 - **`server`** — Graceful shutdown wrapper with signal handling, lifecycle hooks, and TLS support
 - **`health`** — Health check endpoint builder with dependency checks, timeouts, and liveness/readiness probes
+- **`config`** — Load configuration from env vars, `.env` files, and JSON files into typed structs with validation
 - **`sqlbuilder`** — Fluent SQL query builder for PostgreSQL, MySQL, and SQLite with JOINs, CTEs, UNION, upsert, and `request` package integration
 - **`apitest`** — Fluent test helpers for recording and asserting HTTP handler responses
 
@@ -567,6 +568,50 @@ fmt.Println(resp.Status) // "healthy", "degraded", or "unhealthy"
 }
 ```
 
+### config
+
+Load application configuration from environment variables, `.env` files, and JSON config files into typed Go structs.
+
+```go
+import "github.com/KARTIKrocks/apikit/config"
+
+type AppConfig struct {
+    Host     string        `env:"HOST"      default:"localhost"  validate:"required"`
+    Port     int           `env:"PORT"      default:"8080"       validate:"required,min=1,max=65535"`
+    Debug    bool          `env:"DEBUG"     default:"false"`
+    DBUrl    string        `env:"DB_URL"    validate:"required,url"`
+    LogLevel string        `env:"LOG_LEVEL" default:"info"       validate:"oneof=debug info warn error"`
+    Timeout  time.Duration `env:"TIMEOUT"   default:"30s"`
+    Tags     []string      `env:"TAGS"`
+}
+
+var cfg AppConfig
+config.MustLoad(&cfg,
+    config.WithPrefix("APP"),           // reads APP_HOST, APP_PORT, etc.
+    config.WithEnvFile(".env"),          // load .env file (won't override real env vars)
+    config.WithJSONFile("config.json"), // JSON as base layer
+)
+
+// Sources are applied in priority order:
+// 1. Environment variables (highest)
+// 2. .env file
+// 3. JSON file
+// 4. default:"..." tags (lowest)
+```
+
+Nested structs are flattened automatically:
+
+```go
+type Config struct {
+    DB struct {
+        Host string `env:"HOST" default:"localhost"`
+        Port int    `env:"PORT" default:"5432"`
+    }
+}
+
+// Reads DB_HOST, DB_PORT (or APP_DB_HOST, APP_DB_PORT with WithPrefix("APP"))
+```
+
 ### sqlbuilder
 
 Fluent SQL query builder for PostgreSQL, MySQL, and SQLite. Produces `(string, []any)` pairs — no `database/sql` dependency.

config/config.go

@@ -0,0 +1,113 @@
+package config
+
+import (
+	stderrors "errors"
+	"fmt"
+
+	"github.com/KARTIKrocks/apikit/errors"
+	"github.com/KARTIKrocks/apikit/request"
+)
+
+// Option configures the behavior of Load.
+type Option func(*options)
+
+type options struct {
+	prefix   string
+	envFile  string
+	jsonFile string
+	required bool
+}
+
+// WithPrefix sets a prefix for all environment variable lookups.
+// For example, WithPrefix("APP") causes field with env:"PORT" to read APP_PORT.
+func WithPrefix(prefix string) Option {
+	return func(o *options) {
+		o.prefix = prefix
+	}
+}
+
+// WithEnvFile loads environment variables from a file (e.g., ".env").
+// Values from the file do not override existing environment variables.
+func WithEnvFile(path string) Option {
+	return func(o *options) {
+		o.envFile = path
+	}
+}
+
+// WithJSONFile loads configuration from a JSON file as the base layer.
+// Environment variables and .env values take precedence over JSON values.
+func WithJSONFile(path string) Option {
+	return func(o *options) {
+		o.jsonFile = path
+	}
+}
+
+// WithRequired causes Load to return an error if any specified files
+// (env file or JSON file) do not exist.
+func WithRequired() Option {
+	return func(o *options) {
+		o.required = true
+	}
+}
+
+// Load populates dst from environment variables, optional .env files, and
+// optional JSON config files, then validates the result using struct tags.
+//
+// dst must be a non-nil pointer to a struct.
+//
+// Sources are applied in priority order (high to low):
+//  1. Environment variables
+//  2. .env file values (do not override existing env vars)
+//  3. JSON file values
+//  4. default:"..." struct tags
+func Load(dst any, opts ...Option) error {
+	o := &options{}
+	for _, opt := range opts {
+		opt(o)
+	}
+
+	// Load JSON file (base layer).
+	var jsonValues map[string]string
+	if o.jsonFile != "" {
+		var err error
+		jsonValues, err = loadJSONFile(o.jsonFile, o.required)
+		if err != nil {
+			return err
+		}
+	}
+
+	// Load .env file into a map (does not modify process environment).
+	var envFileValues map[string]string
+	if o.envFile != "" {
+		var err error
+		envFileValues, err = loadEnvFile(o.envFile, o.required)
+		if err != nil {
+			return err
+		}
+	}
+
+	// Resolve all values into the struct.
+	if err := resolve(dst, o.prefix, envFileValues, jsonValues); err != nil {
+		return err
+	}
+
+	// Validate using request package tag validators.
+	if err := request.ValidateStruct(dst); err != nil {
+		// Wrap the validation error with config context.
+		var apiErr *errors.Error
+		if stderrors.As(err, &apiErr) {
+			return errors.Validation("config: validation failed", apiErr.Fields)
+		}
+		return err
+	}
+
+	return nil
+}
+
+// MustLoad calls Load and panics if an error occurs.
+// It is intended for use in main() or init() functions.
+func MustLoad(dst any, opts ...Option) {
+	if err := Load(dst, opts...); err != nil {
+		panic(fmt.Sprintf("config: %v", err))
+	}
+}