errors

README

errors

Package errors provides simple error handling primitives. Although Go has a good error handling approach, sometimes it is difficult to handle them appropiatly. This package has been created for such purpose, allowing to define differents errors types and use them in the entire application.

go get github.com/matiasvarela/errors

Defining errors types

First of all, it has to be defined the differents types of errors that are going to be used in the application. This could be done as global variables somewhere in the project using the function errors.Define which receive an internal code and generate a new error type.

In the following example all the error types definitions are being done in a package called 'apperrors'.

package apperrors

var (
    Internal := errors.Define("internal")
    NotFound := errors.Define("not_found")
    InvalidInput := errors.Define("invalid_input")
)

Creating a new error

The funcion errors.New creates a new error based on a previously defined error. For example, if we want to return a not found error we can do it as follow.

return errors.New(NotFound, nil, "the resource has not been found")

Let us see a more interested example:

type Person struct {
    ID      string
    Name    string
    Email   string
}

// GetPerson retrieves the person with the given id
func GetPerson(id string) (Person, error) {
    person := Person{}

    err := db.QueryRow("SELECT id, name, email FROM people WHERE id = ?", id).Scan(&person.ID, &person.Name, &person.Email)
    if err == sql.ErrNoRows {
        return Person{}, errors.New(apperrors.NotFound, err, "person has not been found in the database")
    } else if err != nil {
        return Person{}, errors.New(apperrors.Internal, err, "get person from database has failed")
    }

    return person, nil
}

Wrapping an error

The function errors.Wrap wraps an error with a new message but keeps the same error type. In some cases, we actually want to do is to return an error of the same type but with a different message, so for those such cases this function is intented to be used.

func GetPersonEmail(id string) (string, error) {
    person, err := GetPerson(id)
    if err != nil {
        return "", errors.Wrap(err, "the person could not be retrieve")
    }

    return person.Email, nil 
}

Is

The function errors.Is checks if a given error is an error of some type.

func GetPersonEmail(id string) (string, error) {
    person, err := GetPerson(id)
    if errors.Is(err, apperrors.NotFound) {
        return "", nil
    } else if err != nil {
        return errors.Wrap(err, "get person has failed")
    }

    return person.Email, nil
}

Error() and String()

There are two functions that allows us to print the error information: errors.Error and errors.String. The first one only returns the error message and the second one returns a string with the underlying information such as the internal code and the stacktrace among others.

func main() {
    email, err := GetPersonEmail("123")
    if err != nil {
        log.Error(errors.String(err))
        println("error: "+err.Error())
    }

    println("the person e-mail is"+email)
}

If the person is not found, then the following output will be printed in the console.

error: the person could not be retrieve

And the following log is printed

the person could not be retrieve | [err_code: not_found] | SRC: .../persons.go:17 | CAUSE: {person has not been found in the database | [err_code: not_found] | SRC: .../db.go:45}

Author

• Matías Varela · mtsvrl@gmail.com

License

MIT

Documentation

Overview

Package errors provides easy to use error handling primitives.

Index

• Variables
• func Cause(e error) error
• func CauseMessage(e error) string
• func Code(e error) string
• func Data(e error) interface{}
• func Is(e error, target error) bool
• func New(theType Error, cause error, message string, causeMessage string) error
• func NewWithData(theType Error, cause error, message string, causeMessage string, ...) error
• func String(e error) string
• func Wrap(e error, message string) error
• func WrapWithData(e error, message string, data interface{}) error
• type Error
  • func Define(code string) Error
  • func (e Error) Error() string

Variables

var (
	DefaultError = Define("default_error")
)

Functions

func Cause

func Cause(e error) error

Cause retrieves the cause of the given error

func CauseMessage

func CauseMessage(e error) string

CauseMessage retrieves the cause message of the given error

func Code

func Code(e error) string

Code retrieves the error internal code of a given error.

func Data

func Data(e error) interface{}

Data retrieves the data of a given error or nil if it do not have such data.

func Is

func Is(e error, target error) bool

Is verify if a given error has the same time of the given target error. The target parameter should be an error previously defined with the Define function.

func New

func New(theType Error, cause error, message string, causeMessage string) error

New creates a new error.

func NewWithData

func NewWithData(theType Error, cause error, message string, causeMessage string, data interface{}) error

NewWithData creates a new error with data.

func String

func String(e error) string

String returns an string containing all the subyascent information about the given error.

func Wrap

func Wrap(e error, message string) error

Wrap wraps an error with a message.

func WrapWithData

func WrapWithData(e error, message string, data interface{}) error

WrapWithData wraps an error and add extra data

Types

type Error

type Error struct {
	// contains filtered or unexported fields
}

func Define

func Define(code string) Error

Define define a new error base model.

func (Error) Error

func (e Error) Error() string