errors

README

errors

A package that provides enriched errors. It uses the same conventions and extends the Go standard errors package.

Install

go get -u github.com/aukilabs/go-tooling/pkg/errors

Usage

Create

err := errors.New("error message")                      // With a message.
err := errors.Newf("error message with format: %v", 42) // With a formatted message.

Enrich With A Custom Type

err := errors.New("handling http request failed").WithType("httpError")

Enrich With Tags

err := errors.New("handing http request failed").
    WithTag("method", "GET").
    WithTag("path", "/cookies").
    WithTag("code", 401)

Wrap Another Error

err := errors.New("handling http request failed").Wrap(fmt.Errorf("a fake simple http error"))

Compose Multiple Enrichments

err := errors.New("handing http request failed").
    WithType("httpError").
    WithTag("method", "GET").
    WithTag("path", "/cookies").
    WithTag("code", 401).
    Wrap(fmt.Errorf("a fake simple http error"))

Get Error Type

var err error

t := errors.Type(err)

Get Error Tag

var err error

foo := errors.Tag(err, "foo")

Documentation

Index

• Variables
• func As(err error, target any) bool
• func HasType(err error, v string) bool
• func Is(err, target error) bool
• func SetIndentEncoder()
• func SetInlineEncoder()
• func Tag(err error, k string) any
• func Type(err error) string
• func Unwrap(err error) error
• type Error
  • func New(msg string) Error
  • func Newf(msgFormat string, v ...any) Error
  • func (e Error) Error() string
  • func (e Error) Is(err error) bool
  • func (e Error) MarshalJSON() ([]byte, error)
  • func (e Error) Tag(k string) any
  • func (e Error) Type() string
  • func (e Error) Unwrap() error
  • func (e Error) WithTag(k string, v any) Error
  • func (e Error) WithType(v string) Error
  • func (e Error) Wrap(err error) Error

Variables

var (
	// The function used to encode errors and their tags.
	Encoder func(any) ([]byte, error)
)

Functions

func As

func As(err error, target any) bool

As finds the first error in err's chain that matches target, and if one is found, sets target to that error value and returns true. Otherwise, it returns false.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(any) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.

An error type might provide an As method so it can be treated as if it were a different error type.

As panics if target is not a non-nil pointer to either a type that implements error, or to any interface type.

func HasType

func HasType(err error, v string) bool

HasType reports whether any error in err's chain matches the given type.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

An error matches the given type if the error has a method Type() string such that Type() returns a string equal to the given type.

func Is

func Is(err, target error) bool

Is reports whether any error in err's chain matches target.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.

An error type might provide an Is method so it can be treated as equivalent to an existing error. For example, if MyError defines

func (m MyError) Is(target error) bool { return target == fs.ErrExist }

then Is(MyError{}, fs.ErrExist) returns true. See syscall.Errno.Is for an example in the standard library. An Is method should only shallowly compare err and the target and not call Unwrap on either.

func SetIndentEncoder

func SetIndentEncoder()

SetIndentEncoder is a helper function that set the error encoder to a function that uses json.MarshalIndent.

func SetInlineEncoder

func SetInlineEncoder()

SetInlineEncoder is a helper function that set the error encoder to json.Marshal.

func Tag

func Tag(err error, k string) any

Tag returns the first tag value in err's chain that matches the given key.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

An error has a tag when it has a method Tag(string) string such that Tag(k) returns a non-empty string value.

func Type

func Type(err error) string

Type returns the type of the error.

Uses reflect.TypeOf() when the given error does not implements the Error interface.

func Unwrap

func Unwrap(err error) error

Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.

Types

type Error

type Error struct {
	Line        string
	Message     string
	DefinedType string
	Tags        map[string]any
	WrappedErr  error
}

An enriched error.

func New

func New(msg string) Error

New returns an error with the given message that can be enriched with a type and tags.

func Newf

func Newf(msgFormat string, v ...any) Error

Newf returns an error with the given formatted message that can be enriched with a type and tags.

func (Error) Error

func (e Error) Error() string

func (Error) Is

func (e Error) Is(err error) bool

func (Error) MarshalJSON

func (e Error) MarshalJSON() ([]byte, error)

func (Error) Tag

func (e Error) Tag(k string) any

func (Error) Type

func (e Error) Type() string

func (Error) Unwrap

func (e Error) Unwrap() error

func (Error) WithTag

func (e Error) WithTag(k string, v any) Error

func (Error) WithType

func (e Error) WithType(v string) Error

func (Error) Wrap

func (e Error) Wrap(err error) Error