feat: add EnvCollector for dynamic environment variables

  Add EnvCollector interface for handling env vars that can't be expressed
  via struct tags (e.g., USER_1, PASS_1, USER_2, PASS_2). Types implementing
  EnvCollector receive an EnvGetter with Lookup, ReadValue, and Read methods.

  Breaking changes:
  - Custom unmarshalers (TextUnmarshaler, etc.) now require `env` tag, not `envPrefix`
  - Removed whole-struct decoding via envPrefix (was buggy, returned nil-wrapped errors)

  Other changes:
  - Add pointer validation in EnvGetter.ReadValue
  - Fix README: OS env takes precedence over .env file, not vice versa
  - Update README with EnvCollector docs and improved custom lookup example
  - Remove stale whole-struct decoding documentation

Author: IAmRadek

README.md

@@ -44,7 +44,7 @@ type HTTPServer struct {
 
 func (cfg HTTPServer) Validate() error {
 	return envconfig.Assert(
-		envconfig.OneOf(cfg.Env, "ENVIRONMENT", "production", "prod"),
+		envconfig.OneOf(cfg.Env, "ENV", "production", "prod"),
 		envconfig.Not(
 			envconfig.Range(cfg.Port, 0, 1023, "PORT"),
 			"PORT: must not be a reserved port (0-1023)",
@@ -94,7 +94,7 @@ type App struct {
 
 func main() {
 	var cfg App
-	
+
 	if err := envconfig.Read(&cfg, envconfig.EnvFileLookup(".env")); err != nil {
 		panic(err)
 	}
@@ -104,22 +104,75 @@ func main() {
 ```
 
 Notes:
-- If both the .env file and the OS define a key, the .env value wins for that lookup.
+
+- If both the .env file and the OS define a key, the OS environment value wins.
 - EnvFileLookup panics if the file cannot be read.
 
 ## Tags
 
 Add struct field tags to control how values are loaded:
-- `env`: the env variable name. Use env:"-" to skip a field.
+
+- `env`: the env variable name. Use `env:"-"` to skip a field.
 - `envDefault`: fallback value if the variable is not set.
 - `envRequired:"true"`: marks the field as required, returns error when not set, and no default provided.
-- `envPrefix`: only for struct-typed fields; prepends a prefix (with underscore) for all nested fields under that struct.
+- `envPrefix`: for struct-typed fields; prepends a prefix (with underscore) for all nested fields under that struct.
 
 Precedence per field:
+
 1. Value from lookupEnv(name)
 2. envDefault (if present)
 3. Error if `envRequired:"true"`
 
+
+## Dynamic Environment Variables
+
+For environment variables that can't be expressed via struct tags, like numbered sequences (USER_1, PASS_1, USER_2, PASS_2) – implement the EnvCollector interface:
+
+```go
+package main
+
+import (
+	"github.com/struct0x/envconfig"
+)
+
+type Config struct {
+	Credentials Credentials `envPrefix:"CREDS"`
+}
+
+type Credentials []Credential
+
+type Credential struct {
+	User string `env:"USER"`
+	Pass string `env:"PASS"`
+}
+
+func (c *Credentials) CollectEnv(prefix string, env envconfig.EnvGetter) error {
+	// Read IDs from CREDS=0,1,2 
+	var ids []string
+	if err := env.ReadValue(prefix, &ids); err != nil {
+		return err
+	}
+
+	for _, id := range ids {
+		var cred Credential
+		// Reads CREDS_0_USER, CREDS_0_PASS, etc.                                                                                                                                                                                                                                                                                                                                                                              
+		if err := env.Read(prefix+"_"+id, &cred); err != nil {
+			return err
+		}
+		*c = append(*c, cred)
+	}
+	return nil
+}
+
+```
+
+Fields implementing EnvCollector must use envPrefix (not env). 
+The EnvGetter provides three methods: 
+- Lookup for raw access, 
+- ReadValue for parsing single values, and 
+- Read for populating nested structs with full tag support.
+
+
 ### Examples
 
 Basic tags:
@@ -177,42 +230,66 @@ type T struct {
 
 If a value cannot be parsed into the target type, `Read` returns a descriptive error.
 
-## Custom lookup (probably don't need this)
+## Custom lookup (For Secret Managers, Vaults, etc.)
 
-You can provide any lookup function with signature `func(string) (string, bool)` —
-for example, a map-based lookup in tests:
+By default, Read uses os.LookupEnv, for more advanced use cases like reading values from secret managers like AWS Secret Manager, HashiCorp Vault you can provide a custom lookup function:
 
 ```go
 package main
 
 import (
-	"github.com/struct0x/envconfig"
+  "context"
+  "os"
+  "log/slog"
+
+  "github.com/struct0x/envconfig"
 )
 
-func mapLookup(m map[string]string) func(string) (string, bool) {
-	return func(k string) (string, bool) { v, ok := m[k]; return v, ok }
+type SecretResolver struct {
+  startingCtx context.Context
+  sm          SecretManager
+}
+
+func (s *SecretResolver) Lookup(key string) (string, bool) {
+  val, ok := os.LookupEnv(key)
+  if s.isSecret(val) {
+    val, err := s.sm.ResolveSecret(s.startingCtx, val)
+    if err != nil {
+      slog.Error("missing value", "err", err)
+      return "", false
+    }
+    return val, true
+  }
+
+  // fallback to standard lookup
+  return val, ok
 }
 
 type C struct {
-	N int `env:"N"`
+  N int `env:"N"`
 }
 
 func main() {
-	var c C
-	_ = envconfig.Read(&c, mapLookup(map[string]string{"N": "42"}))
+  sm := &SecretResolver{ /*...*/ }
+	
+  var c C
+  _ = envconfig.Read(&c, sm.Lookup)
 }
+
 ```
 
+Error handling is your responsibility, use `envRequired` to ensure values are present regardless of lookup failures.
+
 ## Error handling
 
 `Read` returns an error when:
+
 - The holder is not a non-nil pointer to a struct
 - A required field is missing and no default is provided
 - A value cannot be parsed into the target type
 
 Errors include the env variable name and context to aid debugging.
 
-
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

envconfig.go

@@ -11,6 +11,8 @@ import (
 	"time"
 )
 
+type LookupEnv = func(string) (string, bool)
+
 // Read populates holder (a pointer to struct) using the provided lookup function to resolve values.
 //
 // Usage:
@@ -52,18 +54,6 @@ import (
 //   - Named struct fields may also carry `envPrefix:"PFX"`; they must NOT
 //     also have an `env` tag.
 //
-// Whole-struct (single-key) decoding:
-//
-//	If a struct-typed field (or embedded struct) has an effective prefix PFX_,
-//	and the holder type implements one of the standard decoders below, a single
-//	env variable named "PFX" (without the trailing underscore) can be used to
-//	populate the entire struct at once. When present, this whole-struct value
-//	takes precedence and field-by-field decoding is skipped.
-//	Supported decoders:
-//	  - encoding.TextUnmarshaler
-//	  - encoding.BinaryUnmarshaler
-//	  - json.Unmarshaler
-//
 // Supported field types:
 //   - primitives: string, bool, all int/uint sizes, float32/64
 //   - time.Duration (parsed via time.ParseDuration)
@@ -96,7 +86,7 @@ import (
 //	considered "set": it suppresses `envDefault` and does not trigger
 //	`envRequired`. If you want defaulting on empty strings, use IgnoreEmptyEnvLookup,
 //	which wraps os.LookupEnv and treats empty values as unset (returns ok == false when value == "").
-func Read[T any](holder *T, lookupEnv ...func(string) (string, bool)) error {
+func Read[T any](holder *T, lookupEnv ...LookupEnv) error {
 	lookupEnvFunc := os.LookupEnv
 	if len(lookupEnv) >= 1 {
 		lookupEnvFunc = lookupEnv[0]
@@ -119,13 +109,60 @@ type Validator interface {
 	Validate() error
 }
 
-func read(le func(string) (string, bool), prefix string, holder any) error {
-	if len(prefix) > 0 {
-		if err, ok := tryUnmarshalKnownInterface(le, prefix, holder); ok {
-			return fmt.Errorf("envconfig: %q prefix failed to populate: %w", prefix, err)
-		}
+// EnvGetter provides a convenient way to get values from env variables.
+// It is passed to EnvCollector.CollectEnv to allow a custom env collection.
+// Under the hood it uses the provided Lookup in Read function.
+type EnvGetter interface {
+	// Lookup performs a raw lookup for an environment variable.
+	Lookup(key string) (string, bool)
+
+	// ReadValue parses a single environment variable into target.
+	// Target must be a pointer.
+	ReadValue(key string, target any) error
+
+	// Read populates target struct with the given prefix.
+	Read(prefix string, target any) error
+}
+
+type getter struct {
+	lookup LookupEnv
+}
+
+func (g *getter) Lookup(key string) (string, bool) {
+	return g.lookup(key)
+}
+
+func (g *getter) ReadValue(key string, target any) error {
+	v := reflect.ValueOf(target)
+	if v.Kind() != reflect.Ptr {
+		return fmt.Errorf("%q not a pointer", v.Type())
+	}
+
+	val, ok := g.lookup(key)
+	if !ok {
+		return nil
 	}
 
+	return setValue(v, val)
+}
+
+func (g *getter) Read(prefix string, target any) error {
+	return read(g.lookup, prefix+"_", target)
+}
+
+// EnvCollector is an advanced interface for collecting custom environment variables
+// that can't be easily expressed via struct tags.
+// For example, a custom collector can handle environment variables with complex
+// naming conventions like USER_1, PASS_1, USER_2, PASS_2.
+//
+// Fields implementing EnvCollector MUST have the `envPrefix` tag (not `env`).
+// See TestEnvCollector for a concrete example.
+type EnvCollector interface {
+	// CollectEnv is called with the computed prefix and an EnvGetter for reading env values.
+	CollectEnv(prefix string, env EnvGetter) error
+}
+
+func read(le func(string) (string, bool), prefix string, holder any) error {
 	holderPtr := reflect.ValueOf(holder)
 	holderValue := holderPtr.Elem()
 	fields := reflect.VisibleFields(holderValue.Type())
@@ -155,6 +192,23 @@ func read(le func(string) (string, bool), prefix string, holder any) error {
 			fieldVal = fieldVal.Elem()
 		}
 
+		if field.PkgPath == "" && fieldVal.CanAddr() {
+			if collector, ok := fieldVal.Addr().Interface().(EnvCollector); ok {
+				if hasEnv {
+					return fmt.Errorf("envconfig: %q implements EnvCollector, use \"envPrefix\" instead of env", field.Name)
+				}
+				if pref == "" {
+					return fmt.Errorf("envconfig: %q implements EnvCollector with empty \"envPrefix\"", field.Name)
+				}
+
+				get := &getter{lookup: le}
+				if err := collector.CollectEnv(prefix+pref, get); err != nil {
+					return fmt.Errorf("envconfig: %q CollectEnv failed: %w", field.Name, err)
+				}
+				continue
+			}
+		}
+
 		if field.Anonymous {
 			if hasEnv {
 				return fmt.Errorf("envconfig: %q is embedded use \"envPrefix\" to add prefix or remove \"env\" to treat struct flat", field.Name)
@@ -220,40 +274,6 @@ func read(le func(string) (string, bool), prefix string, holder any) error {
 	return nil
 }
 
-func tryUnmarshalKnownInterface(le func(string) (string, bool), prefix string, holder any) (error, bool) {
-	if i, ok := holder.(encoding.TextUnmarshaler); ok {
-		envValue, ok := le(prefix[:len(prefix)-1])
-		if !ok {
-			return nil, true
-		}
-
-		if err := i.UnmarshalText([]byte(envValue)); err != nil {
-			return err, true
-		}
-	}
-	if i, ok := holder.(encoding.BinaryUnmarshaler); ok {
-		envValue, ok := le(prefix[:len(prefix)-1])
-		if !ok {
-			return nil, true
-		}
-
-		if err := i.UnmarshalBinary([]byte(envValue)); err != nil {
-			return err, true
-		}
-	}
-	if i, ok := holder.(json.Unmarshaler); ok {
-		envValue, ok := le(prefix[:len(prefix)-1])
-		if !ok {
-			return nil, true
-		}
-
-		if err := i.UnmarshalJSON([]byte(envValue)); err != nil {
-			return err, true
-		}
-	}
-	return nil, false
-}
-
 var durationType = reflect.TypeOf(time.Duration(0))
 
 func setValue(inp reflect.Value, value string) error {