feat: optional root object name

Author: andreev-fn

mapstructure.go

@@ -300,6 +300,10 @@ type DecoderConfig struct {
 	// defaults to "mapstructure"
 	TagName string
 
+	// RootName specifies the name to use for the root element in error messages. For example:
+	//   '<rootName>' has unset fields: <fieldName>
+	RootName string
+
 	// The option of the value in the tag that indicates a field should
 	// be squashed. This defaults to "squash".
 	SquashTagOption string
@@ -465,7 +469,7 @@ func NewDecoder(config *DecoderConfig) (*Decoder, error) {
 // Decode decodes the given raw interface to the target pointer specified
 // by the configuration.
 func (d *Decoder) Decode(input any) error {
-	err := d.decode("", input, reflect.ValueOf(d.config.Result).Elem())
+	err := d.decode(d.config.RootName, input, reflect.ValueOf(d.config.Result).Elem())
 
 	// Retain some of the original behavior when multiple errors ocurr
 	var joinedErr interface{ Unwrap() []error }

mapstructure_test.go

@@ -3675,6 +3675,58 @@ func TestDecode_structArrayDeepMap(t *testing.T) {
 	}
 }
 
+func TestDecoder_RootName(t *testing.T) {
+	t.Parallel()
+
+	input := map[string]any{
+		"surname": "green",
+		"relation": map[string]any{
+			"surname": "black",
+		},
+	}
+
+	var result struct {
+		Name     string `mapstructure:"name"`
+		Relation struct {
+			Name string `mapstructure:"name"`
+		} `mapstructure:"relation"`
+	}
+
+	decoder, err := NewDecoder(&DecoderConfig{
+		ErrorUnset:  true,
+		ErrorUnused: true,
+		Result:      &result,
+		RootName:    "root",
+	})
+	if err != nil {
+		t.Fatalf("err: %s", err)
+	}
+
+	err = decoder.Decode(input)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+
+	expectedErrors := []string{
+		`'root.relation' has invalid keys: surname`,
+		`'root.relation' has unset fields: name`,
+		`'root' has invalid keys: surname`,
+		`'root' has unset fields: name`,
+	}
+
+	failed := false
+
+	for _, expectedErr := range expectedErrors {
+		if !strings.Contains(err.Error(), expectedErr) {
+			failed = true
+		}
+	}
+
+	if failed {
+		t.Errorf("unexpected error message, got: %s", err.Error())
+	}
+}
+
 func stringPtr(v string) *string  { return &v }
 func intPtr(v int) *int           { return &v }
 func uintPtr(v uint) *uint        { return &v }