errs

README

go-errs

More informative errors in go, including stack traces, error timestamp, arbitrary key-value pairs of debug info, and human-friendly error message.

Usage

See errs_test.go for example usage.

Docs

See https://godoc.org/github.com/marcuswestin/go-errs

TODO

• Add human-friendly error codes, a la https://gist.github.com/prschmid/4447660

Documentation

Overview

Package errs improves on the standard `error` by encapsulating stack traces, timestamps, optional internal information, and optional public user-facing messages.

Usage

Create an empty error with stack trace and timestamp:

err := errs.New(nil)
err.Time() // time.Time at time of creation
err.Stack() // output from debug.Stack() at time of creation

Create an error with associated internal info and a user-facing message:

userEmail := "user@example.com"
emailExists := checkIfEmailExists(userEmail)
if emailExists {
  err := errs.New(errs.Info{ "Email":userEmail }, userEmail, "is already taken. Try another!")
  return err
}
...
err.Info("Email") // "user@example.com"
err.PublicMsg() // "user@example.com is already taken. Try another!"

Wrap a standard error:

err := errors.New("An error")
err = errs.Wrap(err, errs.Info{"Foo": "Bar"}, "User message")
...
err.WrappedErr().Error() == "An error"

Index

• type Err
  • func Format(info Info, format string, argv ...interface{}) Err
  • func IsErr(err error) (Err, bool)
  • func New(info Info, publicMsg ...interface{}) Err
  • func UserError(info Info, publicMsg ...interface{}) Err
  • func Wrap(wrapErr error, info Info, publicMsg ...interface{}) Err
• type Info

Types

type Err

type Err interface {
	// Error is an alias for LogString.
	// (errs.Err implements the error interface).
	Error() string

	// Stack returns the result of debug.Stack() from the time when this Err was created.
	Stack() []byte

	// Time returns the time.Time at which this Err was created.
	Time() time.Time

	// If errs.Wrap was used then WrappedError returns the wrapped error.
	WrappedError() error

	// If errs.Wrap or errs.New was called with any publicMsg values
	// then PublicMsg returns a string representation of those values.
	// This is useful for bubbling up user-facing message strings,
	// e.g `errs.New(nil, userEmail, "is already taken. Try another!")`
	PublicMsg() string

	// If errs.Wrap or errs.New was called with an errs.Info object
	// then Info("Foo") return the value of errs.Info{"Foo":...}
	// This is useful for bubbling up internal-facing info,
	// e.g `errs.Wrap(sqlError, { "SqlString":sqlStr, "SqlArgs":sqlArgs })`
	Info(name string) interface{}

	// AllInfo returns all info key-value-pairs passed through errs.New or errs.Wrap
	AllInfo() Info

	// LogString returns a string suitable for logging
	LogString() string

	// IsUserError returns false if it was created with errs.UserError.
	// Useful for e.g escaping out of a call stack but not logging it as
	// an unexpected/critical error,
	// e.g `errs.UserError(nil, "Wrong username/password")`
	IsUserError() bool
}

Err is a richer error interface

func Format

func Format(info Info, format string, argv ...interface{}) Err

Format creates and wraps an error with the given error string. Equivalent to: `errs.Wrap(fmt.Errorf(format, args...))`

func IsErr

func IsErr(err error) (Err, bool)

IsErr checks if err is an errs.Err, and return it as an errs.Err if it is. This is equivalent to err.(errs.Err)

func New

func New(info Info, publicMsg ...interface{}) Err

New creates a new Err with the given Info and optional public message

func UserError

func UserError(info Info, publicMsg ...interface{}) Err

UserError creates an errs.Err which returns true for IsUserError(). See Err.IsUserError

func Wrap

func Wrap(wrapErr error, info Info, publicMsg ...interface{}) Err

Wrap the given error in an errs.Err. If err is nil, Wrap returns nil. Use Err.WrappedError for direct access to the wrapped error.

type Info

type Info map[string]interface{}

Info allows for associating key-value-pair info with an error for debugging, e.g `errs.Wrap(sqlError, { "SqlString":sqlStr, "SqlArgs":sqlArgs })`