proposal: errors: add Errors as a standard way to represent multiple errors as a single error

[marksalpeter]

Description

It is common practice in golang to return an error from a func in the event of a problem during its execution (e.g. func myFunc() error { ... }).

However, there are a few cases, such as field validation on a struct, where it is useful to return multiple errors from a function (e.g. func validate(m *Model) []error). Sometimes these errors need to be 'bubbled up' through a call stack that only returns one error. So, I find myself having to re-implement custom errors that represent many errors in each of my projects.

I think a generic solution could be added to the standard libraries' errors package that serves this purpose.

Example Implementation

I've updated the example implementation to incorporate the feedback from @neild and @D1CED

package util

import (
	"fmt"
)

// Errors are many errors that can be represented as a single error
type Errors interface {
	Errors() []error
	error
}

// NewErrors combine many errors into a single error
func NewErrors(errs ...error) error {
	if lenErrs := len(errs); lenErrs == 0 {
		return nil
	} else if lenErrs == 1 {
		return errs[0]
	}
	var es manyErrors
	for _, err := range errs {
		// Merge many slices of errors into a single slice
		if errs, ok := err.(Errors); ok {
			es = append(es, errs.Errors()...)
			continue
		}
		es = append(es, err)
	}
	return es
}

// manyErrors combines many errors into a single error
type manyErrors []error

// Is works with errors.Is
func (es errors) Is(find error) bool {
        for _, e := range es {
                if Is(e, find) {
                        return true
                }
        }
        return false
}       

// As works with errors.As
func (es errors) As(find interface{}) bool {
        for _, e := range es {
                if As(e, find) {
                        return true
                }
        }
        return false
}

// Errors implements the Errors interface
func (es manyErrors) Errors() []error {
	return []error(es)
}

// Error implements the error interface
func (es manyErrors) Error() string {
	return fmt.Sprintf("[%v", []error(es))
}

Example Usage

import "errors"

type Model struct {
	FieldOne   string `json:"field_one"`
	FieldTwo   string `json:"field_two"`
	FieldThree string `json:"field_three"`
}

func (m *Model) Validate() error {
	var errs []error
	if len(m.FieldOne) < 1 {
		errs = append(errs, errors.New("'field_one' is required"))
	}
	if len(m.FieldTwo) < 1 {
		errs = append(errs, errors.New("'field_two' is required"))
	}
	if len(m.FieldThree) < 1 {
		errs = append(errs, errors.New("'field_three' is required"))
	}
	return errors.NewErrors(errs...)
}

Conclusion

Whether or not this proposal is accepted, I'm curious how others have approached this problem in the past and if there's already a commonly referenced solution that I'm unfamiliar with. Thanks 🙏

[neild]

If err contains multiple errors, what does errors.Is(err, fs.ErrExist) return?

• true if all errors in err are fs.ErrExist?
• true if at least one error in err is fs.ErrExist?
• always false?

If we use errors.As to convert a multierror value to a *os.PathError, does it:

• return true if at least one error in err is an *os.PathError, and extract one of the *os.PathErrors?
• return true if the only error in err is an *os.PathError?
• always return false?

[marksalpeter]

Thanks for the feedback @neild! Handling wrapped errors certainly complicates things.

Full disclosure: I don't generally use wrapped errors in production, so I would defer to the wisdom of those who do.

That said, here are my thoughts:

I think errors.Is can either remain as is (always false) or be modified to return true if at least one error in err is fs.ErrExists - whichever seems more useful or backwards compatible. If the former is deemed better, then it will be up to developers to use Contains instead of Is when they intend to check multiple errors. If the latter is deemed better, then we can combine the logic in Contains with the logic inside of Is and remove the Contains method altogether.

The errors.As implementation should match the behavior of errors.Is. So, if its decided that errors.Is should always return false, then so should errors.As. If it's decided that errors.Is should return true, then errors.As should return true and copy the first *os.PathError that it finds. In this case, the order of the errors in the slice returned by Errors.Errors() would be significant.

If all of the *os.PathErrors are required from the err, we could modify As to handle something like As(err, NewErrors(nilTypeOneErr, nilTypeTwoErr, nilTypeThreeErr)). Then, theoretically, we would be able to extract multiple errors (potentially of multiple types) from a single call to the As func without the addition of any other methods.

Which way would you prefer @neild, @D1CED?

[marksalpeter]

Thinking some more about your questions, maybe there's a simpler solution that wouldn't require modifying errors.Is or errors.As:

// Errors are many errors that can be represented as a single error
type Errors interface {
	Errors() []error
	error
}

// NewErrors combine many errors into a single error
func NewErrors(errs ...error) Errors {
	if len(errs) == 0 {
		return nil
	}
	var es errors
	for _, err := range errs {
		// Merge many slices of errors into a single slice
		if errs, ok := err.(Errors); ok {
			es = append(es, errs.Errors()...)
			continue
		}
		es = append(es, err)
	}
	return es
}

// errors combines many errors into a single error
type errors []error

// Unwrap works with errors.Unwrap
func (es errors) Unwrap() error {
	if len(es) > 0 {
		return es[1:]
	}
	return nil
}

// Is works with errors.Is
func (es errors) Is(err error) bool {
	if len(es) == 0 {
		return err != nil
	}
	return err.Error() == es[0].Error()
}

// Errors implements the Errors interface
func (es errors) Errors() []error {
	return []error(es)
}

// Error implements the error interface
func (es errors) Error() string {
	return fmt.Sprintf("%v", []error(es))
}

Thoughts @neild, @D1CED?

[D1CED]

First let me start out by saying that there seems to be a clear need for this feature as seen by looking for 'multi error' on pkg.go.dev.
From the ones I skimmed through none had (documented) support for As or Is.
Providing the most information possible is still the right call here IMO. If we don't provide Is and As the users have to explicitly check for the Errors interface. One issue here you also targeted is that of performance. On a very large error slice Is and As would be (multiple) linear searches. Not great. A more efficient implementation here would be fairly difficult I assume.

[D1CED]

@marksalpeter Your implementation of Is and Unwrap is incorrect here. For example if Errors only contains a single error Unwrap discards it instead of returning it unwrapped and Is does a string comparison on just the first error?!

[marksalpeter]

@D1CED My apologies. As I said before, I'm unfamiliar with the use case. My understanding of Unwrap is that it returns one frame down the error "call stack". So for example errors.Is would call err.Is and if that failed, it would call err.Unwrap until err.Is returns true. How is it supposed to be implemented?

[D1CED]

Uh, I think my statement above was partially incorrect. Your implementation kind of does work when changing the comparison. But it seems like we have a very different idea here. My suggested implementation would be

package errors

func (es errors) Is(find error) bool {
        for _, e := range es {
                if Is(e, find) {
                        return true
                }
        }
        return false
}       

func (es errors) As(find interface{}) bool {
        for _, e := range es {
                if As(e, find) {
                        return true
                }
        }
        return false
}

and I'd not implement an Unwrap method at all.

Edit: Got a little confused with the names here. The package is called errors and type is called errors. Maybe we should call it multiError as this seems to be a common name.

[D1CED]

One small feature I found when looking at other implementations is that if there is exactly one error it is simply returned unwrapped. This should be considered here too.

[marksalpeter]

@D1CED I'm not sure that recursively calling errors.Is or errors.As like this is necessary, wise or even correct. Keep in mind, errors.As will be calling errors.errors.As and errors.Is will be calling errors.errors.Is. I'll have to think about this some more.

[marksalpeter]

@D1CED You can see on line 90 of wrap.go that errors.errors.Unwrap will be called until errors.errors.As succeeds. So therefore, I think a more correct implementation of errors.errors.As would be

// As works with errors.As
func (es errors) As(target interface{}) bool {
	if len(es) == 0 {
		return false
	}
	err := es[0]
	val := reflectlite.ValueOf(target)
	targetType := val.Type()
	if reflectlite.TypeOf(err).AssignableTo(targetType) {
		val.Elem().Set(reflectlite.ValueOf(err))
		return true
	}
	return false
}

I also think the version of errors.errors.Is I wrote would pass any tests of errors.Is functionality you subjected it to.

[marksalpeter]

I've added the example implementations of As and Is to the original example in the proposal with a note at the top. Thanks again for pointing out this use case @neild 🙏

[marksalpeter]

Uh, I think my statement above was partially incorrect. Your implementation kind of does work when changing the comparison. But it seems like we have a very different idea here. My suggested implementation would be

package errors

func (es errors) Is(find error) bool {
        for _, e := range es {
                if Is(e, find) {
                        return true
                }
        }
        return false
}       

func (es errors) As(find interface{}) bool {
        for _, e := range es {
                if As(e, find) {
                        return true
                }
        }
        return false
}

and I'd not implement an Unwrap method at all.

Edit: Got a little confused with the names here. The package is called errors and type is called errors. Maybe we should call it multiError as this seems to be a common name.

Ok, so I traced this and the recursive call is definitely more correct than either of my previous attempts. Sorry about that 😅.

I still think we can use Uwrap to treat the []errors like any other stack of errors instead of looping over the slice in the func. I've included the changes in the example at the top. Let me know what you think @D1CED