ierrors

Documentation

Overview

Package ierrors provides an easy way to wrap context to the error of the standard library, as well as support for multiple errors.

Declaring an error

This is the most usual way of using the package, there are two options: the first consists of using ierrors.New(""), specifying the message of the error, and the ierrors.MultiError structure whichs supports multiple errors.

- ierror: is the structure created by the ierrors.New() and consists of a message and an errorCode, the second parameter can be added when instantiating an ierror after the New func call. An example of its usage would be `ierrors.New("cli subcommand %v error", subcommandName).InvalidArgs()`.

- MultiError: structure which is composed of an errorCode and a slice of error interfaces, it contains the methods Add(error) and Empty(). Which can be used to handle error requests that are comming from a set of goroutines.

Some functionalities that are contained within this package are:

- Wrap/Unwrap functions: handles the addition and removal of context to an error, meaning that if desired the developer can provide extra information to the error he can simply use `ierrors.Wrap(err, "on operation X")`.

- Marshal/Unmarshal: the ierror structure declared by this package have custom functions that are called when using json.Marshal or json.Unmarshal, meaning that when creating a error it can be parsed into json and yaml format, allowing the transfer of error information via http.

- New: as described previously is used to handle the creation of errors, one difference from the standard package is that this func accepts strings and other errors as a parameter. Meaning that one could create a inspr error from another error of an external pkg.

Some examples of the usage of the `New` func are:

• ierrors.New("my_custom_err")
• ierrors.New("error on the URL %v and route %v", myURL, routeName)
• ierrors.New(io.EOF) // error defined in the standard library io pkg

- ierror.is(): an internal func that is called when using the standard library errors.Is function. This allows us to not lose the original error and compare it at any point of our code. For example when using the error below:

errWithWrapping := ierrors.Wrap(io.EOF, "func X", "file Y")

We can still check at any point if the base of the error is an io.EOF, that is done by simply calling errors.Is(errWithWrapping, io.EOF). No matter how many wrappers you attach to the original error the contents can still be compared to another error.

Index

• func FormatError(err error) string
• func HasCode(err error, code ErrCode) bool
• func New(value interface{}, args ...interface{}) *ierror
• func Unwrap(err error) error
• func Wrap(err error, msgs ...string) error
• type ErrCode
  • func Code(err error) ErrCode
• type MultiError
  • func (e *MultiError) Add(err error)
  • func (e *MultiError) Empty() bool
  • func (e *MultiError) Error() (ret string)

Functions

func FormatError

func FormatError(err error) string

FormatError is a simple function with the intention of handling the default ierror Error() format into something more presentable.

Meaning that the error

"file X : func Y : <base_error> " will be converted into:

file X

func Y
<base_error>

func HasCode

func HasCode(err error, code ErrCode) bool

HasCode tries to convert the error interface to an ierror structure and then assert if the structure contains the ErrCode provided as an argument

func New

func New(value interface{}, args ...interface{}) *ierror

New is the function used to create an ierror, it accepts an interface{} since an ierror can be created from one of the following:

- A string value - An error interface

If none of the above are provided as a argument the function will return nil.

One useful way of handling errors from an external pkg is to use this function to translate it to an ierror, allowing the customization of the ErrCode.

Some examples of the usage of the `New` func are:

• ierrors.New("my_custom_err")
• ierrors.New("error on the URL %v and route %v", myURL, routeName)
• ierrors.New(io.EOF) // error defined in the standard library io pkg

func Unwrap

func Unwrap(err error) error

Unwrap is a err function that removes the last wrap done to the err stack and if that was the last error in the stack it will return nil. It is capable of handling both the standard golang error as well as the insprError structure.

func Wrap

func Wrap(err error, msgs ...string) error

Wrap is responsible for adding extra context to an error, this is done by stacking error messages that give the receiver of the error the path of the error occurrence

Types

type ErrCode

type ErrCode uint32

ErrCode is error codes for inspr errors

const (
	Unknown ErrCode = 1 << iota
	NotFound
	AlreadyExists
	InternalServer
	InvalidName
	InvalidApp
	InvalidChannel
	InvalidType
	InvalidFile
	InvalidArgs
	BadRequest
	InvalidToken
	ExpiredToken
	Unauthorized
	Forbidden
	ExternalPkg
)

Error codes for inspr errors

func Code

func Code(err error) ErrCode

Code is a function that tries to convert the error interface to an ierror structure and returns its code value

type MultiError

type MultiError struct {
	Errors []error `yaml:"errors" json:"slices"`
	Code   ErrCode `yaml:"code" json:"code"`
}

MultiError is a type that handles multiple errors that can happen in a process

func (*MultiError) Add

func (e *MultiError) Add(err error)

Add adds an error to the multi error

func (*MultiError) Empty

func (e *MultiError) Empty() bool

Empty returns if there is no error in the multierror

func (*MultiError) Error

func (e *MultiError) Error() (ret string)

Error return the errors in the multierror concatenated with new lines