feature: control merging behavior

.gitignore

@@ -1 +1,4 @@
-.env
+.env
+
+# IDE
+.idea

README.md

@@ -518,9 +518,72 @@ func main() {
 	fmt.Printf("name is = `%s`\n", k.String("parent1.child1.name"))
 }
 ```
+### Merge behavior
+#### Default behavior
+The default behavior when you create Koanf this way is: `koanf.New(delim)` that the latest loaded configuration will
+merge with the previous one.
+
+For example:
+`first.yml`
+```yaml
+key: [1,2,3]
+```
+`second.yml`
+```yaml
+key: 'string'
+```
+When `second.yml` is loaded it will override the type of the `first.yml`.
+
+If this behavior is not desired, you can merge 'strictly'. In the same scenario, `Load` will return an error.
+
+```go
+package main
+
+import (
+	"errors"
+	"log"
+
+	"github.com/knadh/koanf"
+	"github.com/knadh/koanf/maps"
+	"github.com/knadh/koanf/parsers/json"
+	"github.com/knadh/koanf/parsers/yaml"
+	"github.com/knadh/koanf/providers/file"
+)
 
+var conf = koanf.Conf{
+	Delim:       ".",
+	StrictMerge: true,
+}
+var k = koanf.NewWithConf(conf)
+
+func main() {
+	yamlPath := "mock/mock.yml"
+	if err := k.Load(file.Provider(yamlPath), yaml.Parser()); err != nil {
+		log.Fatalf("error loading config: %v", err)
+	}
 
-### Order of merge and key case senstivity
+	jsonPath := "mock/mock.json"
+	if err := k.Load(file.Provider(jsonPath), json.Parser()); err != nil {
+		// go version <= v1.12
+		if strictErr := err.(*maps.MergeStrictError); strictErr != nil {
+			log.Fatalf("error merging config %v: %v", jsonPath, err)
+		}
+		// go version > v1.12
+		var strictErr *maps.MergeStrictError
+		if errors.As(err, &strictErr) {
+			log.Fatalf("error merging config %v: %v", jsonPath, err)
+		}
+
+		log.Fatalf("error loading config: %v", err)
+	}
+}
+```
+**Note:** When merging different extensions, each parser can treat his types differently,
+ meaning even though you the load same types there is a probability that it will fail with `StrictMerge: true`.
+
+For example: merging JSON and YAML will most likely fail because JSON treats integers as float64 and YAML treats them as integers.
+
+### Order of merge and key case sensitivity
 
 - Config keys are case-sensitive in koanf. For example, `app.server.port` and `APP.SERVER.port` are not the same.
 - koanf does not impose any ordering on loading config from various providers. Every successive `Load()` or `Load()` merges new config into existing config. That means it is possible to load environment variables first, then files on top of it, and then command line variables on top of it, or any such order.
@@ -533,6 +596,19 @@ Writing Providers and Parsers are easy. See the bundled implementations in the `
 
 ## API
 
+### Instantiation methods
+| Method                          | Description                                                                                                                                                                 | 
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `New(delim string) *Koanf`      | Returns a new instance of Koanf. delim is the delimiter to use when specifying config key paths, for instance a `.` for `parent.child.key` or a `/` for `parent/child/key`. |
+| `NewWithConf(conf Conf) *Koanf` | Returns a new instance of Koanf depending on the `Koanf.Conf` configurations.                                                                                               |
+
+### Structs
+| Struct                          | Description                                                                                                      |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Koanf                           | Koanf is the configuration apparatus.                                                                            |
+| Conf                            | Conf is the Koanf configuration, that includes `Delim` and `StrictMerge`.                                        |
+| UnmarshalConf                   | UnmarshalConf represents configuration options used by `Unmarshal()` to unmarshal conf maps in arbitrary structs |
+
 ### Bundled providers
 
 | Package             | Provider                                                      | Description                                                                                                                                                                           |

koanf.go

@@ -18,7 +18,21 @@ type Koanf struct {
 	confMap     map[string]interface{}
 	confMapFlat map[string]interface{}
 	keyMap      KeyMap
-	delim       string
+	conf        Conf
+}
+
+// Conf is the Koanf configuration.
+type Conf struct {
+	// Delim is the delimiter to use
+	// when specifying config key paths, for instance a . for `parent.child.key`
+	// or a / for `parent/child/key`.
+	Delim string
+
+	// StrictMerge makes the merging behavior strict.
+	// Meaning when loading two files that have the same key,
+	// the first loaded file will define the desired type, and if the second file loads
+	// a different type will cause an error.
+	StrictMerge bool
 }
 
 // KeyMap represents a map of flattened delimited keys and the non-delimited
@@ -55,10 +69,23 @@ type UnmarshalConf struct {
 // or a / for `parent/child/key`.
 func New(delim string) *Koanf {
 	return &Koanf{
-		delim:       delim,
 		confMap:     make(map[string]interface{}),
 		confMapFlat: make(map[string]interface{}),
 		keyMap:      make(KeyMap),
+		conf: Conf{
+			Delim:       delim,
+			StrictMerge: false,
+		},
+	}
+}
+
+// NewWithConf returns a new instance of Koanf based on the Conf.
+func NewWithConf(conf Conf) *Koanf {
+	return &Koanf{
+		confMap:     make(map[string]interface{}),
+		confMapFlat: make(map[string]interface{}),
+		keyMap:      make(KeyMap),
+		conf: conf,
 	}
 }
 
@@ -94,8 +121,7 @@ func (ko *Koanf) Load(p Provider, pa Parser) error {
 		}
 	}
 
-	ko.merge(mp)
-	return nil
+	return ko.merge(mp)
 }
 
 // Keys returns the slice of all flattened keys in the loaded configuration
@@ -164,8 +190,8 @@ func (ko *Koanf) Cut(path string) *Koanf {
 		out = v
 	}
 
-	n := New(ko.delim)
-	n.merge(out)
+	n := New(ko.conf.Delim)
+	_ = n.merge(out)
 	return n
 }
 
@@ -176,27 +202,26 @@ func (ko *Koanf) Copy() *Koanf {
 
 // Merge merges the config map of a given Koanf instance into
 // the current instance.
-func (ko *Koanf) Merge(in *Koanf) {
-	ko.merge(in.Raw())
+func (ko *Koanf) Merge(in *Koanf) error {
+	return ko.merge(in.Raw())
 }
 
 // MergeAt merges the config map of a given Koanf instance into
 // the current instance as a sub map, at the given key path.
 // If all or part of the key path is missing, it will be created.
 // If the key path is `""`, this is equivalent to Merge.
-func (ko *Koanf) MergeAt(in *Koanf, path string) {
+func (ko *Koanf) MergeAt(in *Koanf, path string) error {
 	// No path. Merge the two config maps.
 	if path == "" {
-		ko.Merge(in)
-		return
+		return ko.Merge(in)
 	}
 
 	// Unflatten the config map with the given key path.
 	n := maps.Unflatten(map[string]interface{}{
 		path: in.Raw(),
-	}, ko.delim)
+	}, ko.conf.Delim)
 
-	ko.merge(n)
+	return ko.merge(n)
 }
 
 // Marshal takes a Parser implementation and marshals the config map into bytes,
@@ -242,7 +267,7 @@ func (ko *Koanf) UnmarshalWithConf(path string, o interface{}, c UnmarshalConf)
 	mp := ko.Get(path)
 	if c.FlatPaths {
 		if f, ok := mp.(map[string]interface{}); ok {
-			fmp, _ := maps.Flatten(f, nil, ko.delim)
+			fmp, _ := maps.Flatten(f, nil, ko.conf.Delim)
 			mp = fmp
 		}
 	}
@@ -270,8 +295,8 @@ func (ko *Koanf) Delete(path string) {
 	maps.Delete(ko.confMap, p)
 
 	// Update the flattened version as well.
-	ko.confMapFlat, ko.keyMap = maps.Flatten(ko.confMap, nil, ko.delim)
-	ko.keyMap = populateKeyParts(ko.keyMap, ko.delim)
+	ko.confMapFlat, ko.keyMap = maps.Flatten(ko.confMap, nil, ko.conf.Delim)
+	ko.keyMap = populateKeyParts(ko.keyMap, ko.conf.Delim)
 }
 
 // Get returns the raw, uncast interface{} value of a given key path
@@ -327,7 +352,7 @@ func (ko *Koanf) Slices(path string) []*Koanf {
 			continue
 		}
 
-		k := New(ko.delim)
+		k := New(ko.conf.Delim)
 		k.Load(confmap.Provider(v, ""), nil)
 		out = append(out, k)
 	}
@@ -365,13 +390,22 @@ func (ko *Koanf) MapKeys(path string) []string {
 	return out
 }
 
-func (ko *Koanf) merge(c map[string]interface{}) {
+func (ko *Koanf) merge(c map[string]interface{}) error{
 	maps.IntfaceKeysToStrings(c)
-	maps.Merge(c, ko.confMap)
+	if ko.conf.StrictMerge {
+		err := maps.MergeStrict(c, ko.confMap)
+		if err != nil {
+			return err
+		}
+	} else {
+		maps.Merge(c, ko.confMap)
+	}
 
 	// Maintain a flattened version as well.
-	ko.confMapFlat, ko.keyMap = maps.Flatten(ko.confMap, nil, ko.delim)
-	ko.keyMap = populateKeyParts(ko.keyMap, ko.delim)
+	ko.confMapFlat, ko.keyMap = maps.Flatten(ko.confMap, nil, ko.conf.Delim)
+	ko.keyMap = populateKeyParts(ko.keyMap, ko.conf.Delim)
+
+	return nil
 }
 
 // toInt64 takes an interface value and if it is an integer type,

koanf_test.go

@@ -14,6 +14,7 @@ import (
 	"time"
 
 	"github.com/knadh/koanf"
+	"github.com/knadh/koanf/maps"
 	"github.com/knadh/koanf/parsers/dotenv"
 	"github.com/knadh/koanf/parsers/hcl"
 	"github.com/knadh/koanf/parsers/json"
@@ -712,6 +713,32 @@ func TestRaw_JsonTypes(t *testing.T) {
 	}
 }
 
+func TestMergeStrictError(t *testing.T) {
+	var (
+		assert = assert.New(t)
+	)
+
+	ks := koanf.NewWithConf(koanf.Conf{
+		Delim:       delim,
+		StrictMerge: true,
+	})
+
+	assert.Nil(ks.Load(confmap.Provider(map[string]interface{}{
+		"parent2": map[string]interface{}{
+			"child2": map[string]interface{}{
+				"grandchild2": map[string]interface{}{
+					"ids": 123,
+				},
+			},
+		},
+	}, delim), nil))
+
+	err := ks.Load(file.Provider(mockYAML), yaml.Parser())
+	assert.Error(err)
+	assert.IsType(&maps.MergeStrictError{}, err)
+	assert.True(strings.HasPrefix(err.Error(), "incorrect types at key parent2.child2.grandchild2"))
+}
+
 func TestMergeAt(t *testing.T) {
 	var (
 		assert = assert.New(t)

maps/maps.go

@@ -6,9 +6,22 @@ package maps
 import (
 	"fmt"
 	"github.com/mitchellh/copystructure"
+	"reflect"
 	"strings"
 )
 
+type MergeStrictError struct {
+	Errors []error
+}
+
+func (m *MergeStrictError) Error() string {
+	var msg string
+	for _, err := range m.Errors {
+		msg += fmt.Sprintf("%v\n", err.Error())
+	}
+	return msg
+}
+
 // Flatten takes a map[string]interface{} and traverses it and flattens
 // nested children into keys delimited by delim.
 //
@@ -132,6 +145,51 @@ func Merge(a, b map[string]interface{}) {
 	}
 }
 
+func MergeStrict(a, b map[string]interface{}) error {
+	mergeError := MergeStrictError{Errors: []error{}}
+	mergeStrict(a, b, &mergeError, "")
+	if len(mergeError.Errors) > 0 {
+		return &mergeError
+	}
+	return nil
+}
+
+func mergeStrict(a, b map[string]interface{}, mergeError *MergeStrictError, fullKey string) {
+	for key, val := range a {
+		// Does the key exist in the target map?
+		// If no, add it and move on.
+		bVal, ok := b[key]
+		if !ok {
+			b[key] = val
+			continue
+		}
+
+		newFullKey := key
+		if fullKey != "" {
+			newFullKey = fmt.Sprintf("%v.%v", fullKey, key)
+		}
+
+		// If the incoming val is not a map, do a direct merge between the same types.
+		if _, ok := val.(map[string]interface{}); !ok {
+			if reflect.TypeOf(b[key]) == reflect.TypeOf(val) {
+				b[key] = val
+			} else {
+				err := fmt.Errorf("incorrect types at key %v, type %T != %T", fullKey, b[key], val)
+				mergeError.Errors = append(mergeError.Errors, err)
+			}
+			continue
+		}
+
+		// The source key and target keys are both maps. Merge them.
+		switch v := bVal.(type) {
+		case map[string]interface{}:
+			mergeStrict(val.(map[string]interface{}), v, mergeError, newFullKey)
+		default:
+			b[key] = val
+		}
+	}
+}
+
 // Delete removes the entry present at a given path, from the map. The path
 // is the key map slice, for eg:, parent.child.key -> [parent child key].
 // Any empty, nested map on the path, is recursively deleted.