multierr

README

multierr

Provides an idiomatic Append function for errors, allowing to combine multiple errors into one.

Basically the whole API is:

err = multierr.Append(err, someFuncThatFails())
err = multierr.Append(err, anotherFuncThatFails())

Printing the error results in something like:

2 errors occurred:
(1) some failure
(2) another failure

Among other cases, this is especially useful in failable deferred funcs to avoid silently ignoring cleanup errors:

func sprinkleMagicDust() (err error) {
    d := &Dummy{}
    defer func() {
        err = multierr.Append(err, d.Close())
    }()

return d.DoSomeMagic()
}

Unlike other overly complicated multierror packages, this one does not even expose its multierror type, and will only use it when you actually end up with more than a single error to return.

The returned multierror type supports errors.Is and errors.As by delegating to each of the suberrors it contains.

License

© 2020-2021, Andrey Tarantsov. Published under the MIT License.

Documentation

Overview

Package multierr provides an idiomatic Append function for errors, allowing to combine multiple errors into one.

Basically the whole API is:

err = multierr.Append(err, someFuncThatFails())

Among other use cases, this is especially useful in failable deferred funcs to avoid silently ignoring cleanup errors:

func sprinkleMagicDust() (err error) {
	d := &Dummy{}
	defer func() {
		err = multierr.Append(err, d.Close())
	}()

	return d.DoSomeMagic()
}

Unlike many other multierror packages, this one does not even expose its multierror type, and will only use it when you actually end up with more than a single error to return.

The returned multierror type supports errors.Is and errors.As by delegating to each of the suberrors it contains.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/andreyvit/multierr"
)

func main() {
	fmt.Println(sprinkleMagicDust())

}

func sprinkleMagicDust() (err error) {
	d := &Dummy{}
	defer func() {
		err = multierr.Append(err, d.Close())
	}()

	return d.DoSomeMagic()
}

type Dummy struct{}

func (d Dummy) DoSomeMagic() error {
	return errors.New("magic not available")
}
func (d Dummy) Close() error {
	return errors.New("close: whoopsie")
}

Output:

2 errors occurred:
(1) magic not available
(2) close: whoopsie

Example (Is)

package main

import (
	"errors"
	"fmt"

	"github.com/andreyvit/multierr"
)

var (
	oops     = errors.New("oops")
	whoops   = errors.New("whoops")
	whoopsie = errors.New("whoopsie")
)

func main() {
	var err error
	err = multierr.Append(err, oops)
	err = multierr.Append(err, whoopsie)

	fmt.Println(errors.Is(err, oops))
	fmt.Println(errors.Is(err, whoops))
	fmt.Println(errors.Is(err, whoopsie))

}

Output:

true
false
true

Example (MultipleErrors)

package main

import (
	"errors"
	"fmt"

	"github.com/andreyvit/multierr"
)

var (
	oops     = errors.New("oops")
	whoops   = errors.New("whoops")
	whoopsie = errors.New("whoopsie")
)

func main() {
	var err error
	err = multierr.Append(err, oops)
	err = multierr.Append(err, whoops)
	err = multierr.Append(err, whoopsie)

	fmt.Println(err)
}

Output:

3 errors occurred:
(1) oops
(2) whoops
(3) whoopsie

Example (NilError)

package main

import (
	"fmt"

	"github.com/andreyvit/multierr"
)

func main() {
	var err error
	fmt.Println(len(multierr.All(err)))
}

Output:

0

Example (SingleError)

package main

import (
	"errors"
	"fmt"

	"github.com/andreyvit/multierr"
)

var oops = errors.New("oops")

func main() {
	var err error
	err = multierr.Append(err, oops)

	fmt.Println(err)
	fmt.Println(err == oops)
	fmt.Println(len(multierr.All(err)))
}

Output:

oops
true
1

Index

• Variables
• func All(err error) []error
• func Append(dest error, err error) error
• func DefaultFormatMessage(errs []error) string
• func ForEach(err error, f func(err error))
• func Len(err error) int

Examples

• Package
• Package (Is)
• Package (MultipleErrors)
• Package (NilError)
• Package (SingleError)

Variables

var FormatMessage func(errs []error) string = DefaultFormatMessage

FormatMessage is a function used to format a string with multiple error messages. You can replace it if your project calls for a different format. Note that this is a global setting and should be left to the end user to decide.

Functions

func All

func All(err error) []error

Returns all suberrors within err. If err is not a multierror type, returns []error{err}. If err is nil, returns nil.

func Append

func Append(dest error, err error) error

Append joins the given error values into a single error. If both are non-nil, wraps them into a multierror type (which is a typed []error slice), otherwise returns one of the arguments.

Append(nil, nil) == nil
Append(nil, someErr) == someErr
Append(someErr, nil) == someErr
Append(someErr, anotherErr) == []error{someErr, anotherErr}

Either (or both) of the arguments can be multierror types, which are properly joined together. In this case, Append assumes that it's fine to modify either of the arguments.

func DefaultFormatMessage

func DefaultFormatMessage(errs []error) string

DefaultFormatMessage performs the default formatting of multiple error messages.

func ForEach

func ForEach(err error, f func(err error))

ForEach calls f with each suberror in the given error. If err is not a multierror type, calls f(err). If err is nil, does not call f.

func Len

func Len(err error) int

Returns the number of suberrors within err. If err is not a multierror type, returns 1. If err is nil, returns 0.