feat: add common error interface

Signed-off-by: Mark Sagi-Kazar <mark.sagikazar@gmail.com>
go-viper · sagikazarmark · Jun 16, 2025 · Jun 16, 2025 · Jun 16, 2025 · Jun 16, 2025
commit 9661f6d07c319da00ae0508d99df5f3f0c3953bd
diff --git a/errors.go b/errors.go
@@ -5,6 +5,17 @@ import (
 	"reflect"
 )
 
+// Error interface is implemented by all errors emitted by mapstructure.
+//
+// Errors from underlying libraries MAY not be wrapped.
+//
+// Use [errors.As] to check if an error implements this interface.
+type Error interface {
+	error
+
+	mapstructure()
+}
+
 // DecodeError is a generic error type that holds information about
 // a decoding error together with the name of the field that caused the error.
 type DecodeError struct {
@@ -28,30 +39,39 @@ func (e *DecodeError) Unwrap() error {
 }
 
 func (e *DecodeError) Error() string {
-	return fmt.Sprintf("'%s' %s", e.name, e.err)
+	return fmt.Sprintf("decoding '%s': %s", e.name, e.err)
 }
 
+func (*DecodeError) mapstructure() {}
+
 // ParseError is an error type that indicates a value could not be parsed
 // into the expected type.
 type ParseError struct {
 	Expected reflect.Value
-	Value    interface{}
+	Value    any
 	Err      error
 }
 
 func (e *ParseError) Error() string {
-	return fmt.Sprintf("cannot parse '%s' as '%s': %s",
-		e.Value, e.Expected.Type(), e.Err)
+	return fmt.Sprintf("cannot parse '%s' as '%s': %s", e.Value, e.Expected.Type(), e.Err)
 }
 
+func (*ParseError) mapstructure() {}
+
 // UnconvertibleTypeError is an error type that indicates a value could not be
 // converted to the expected type.
 type UnconvertibleTypeError struct {
 	Expected reflect.Value
-	Value    interface{}
+	Value    any
 }
 
 func (e *UnconvertibleTypeError) Error() string {
-	return fmt.Sprintf("expected type '%s', got unconvertible type '%s', value: '%v'",
-		e.Expected.Type(), reflect.TypeOf(e.Value), e.Value)
+	return fmt.Sprintf(
+		"expected type '%s', got unconvertible type '%s', value: '%v'",
+		e.Expected.Type(),
+		reflect.TypeOf(e.Value),
+		e.Value,
+	)
 }
+
+func (*UnconvertibleTypeError) mapstructure() {}