errors

README

Errors Package

Lib designed to facilitate and standardize how error handling should be done.

It produces CustomError, that encodes useful information about a given error.

It's supposed to flow within the application in detriment of the the default golang error since its Kind and Code attributes are the keys to express its semantic and uniqueness, respectively.

It should be generated once by the peace of code that found the error (because it's where we have more context about the error), and be by passed to the upper layers of the application.

Documentation

Index

• Variables
• func As(err error, target any) bool
• func Is(err, target error) bool
• func IsRetryable(err error) bool
• func NewMissingRequiredDependency(name string) error
• func NewValidationError(desc string) error
• func Unwrap(err error) []error
• func Wrap(err error, msg string, args ...any) error
• type CodeType
  • func Code(err error) CodeType
• type CustomError
  • func New(msg string, args ...any) CustomError
  • func (ce CustomError) Error() string
  • func (ce CustomError) Is(target error) bool
  • func (ce CustomError) Retryable() CustomError
  • func (ce CustomError) Unwrap() []error
  • func (ce CustomError) WithCause(cause error) CustomError
  • func (ce CustomError) WithCode(code CodeType) CustomError
  • func (ce CustomError) WithKind(kind KindType) CustomError
• type KindType
  • func Kind(err error) KindType

Variables

var (
	// ErrResourceNotFound indicates that a desired resource was not found.
	ErrResourceNotFound error = New("resource not found").WithKind(KindNotFound).WithCode("RESOURCE_NOT_FOUND")

	// ErrNotImplemented indicates that a given feature is not implemented yet.
	ErrNotImplemented error = New("feature not implemented yet").WithCode("FEATURE_NOT_IMPLEMENTED")

	// ErrMock is a fake mocked that should be used in test scenarios.
	ErrMock error = New("mocked error").WithCode("MOCKED_ERROR")
)

Functions

func As

func As(err error, target any) bool

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

The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, As examines err followed by a depth-first traversal of its children.

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(interface{}) 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 Is

func Is(err, target error) bool

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

The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, Is examines err followed by a depth-first traversal of its children.

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 IsRetryable

func IsRetryable(err error) bool

IsRetryable reports whether any error in err's tree is retryable.

The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, Is examines err followed by a depth-first traversal of its children.

func NewMissingRequiredDependency

func NewMissingRequiredDependency(name string) error

NewMissingRequiredDependency creates a new error that indicates a missing required dependency. It should be producing at struct constructors.

func NewValidationError

func NewValidationError(desc string) error

NewValidationError creates a Validation error.

func Unwrap

func Unwrap(err error) []error

Unwrap retrieves all the errors that forms the baseline for the given one. It only works in the surface of the error. In other words, it does not evaluates all the err's tree, just its first level.

func Wrap

func Wrap(err error, msg string, args ...any) error

Wrap adds more contextual information into the given error. The new information is handled as a new error which wraps the given error properly.

Types

type CodeType

type CodeType string

CodeType is a string that contains error's code description.

const (
	// CodeUnknown is the default code returned when the application doesn't attach any code into the error.
	CodeUnknown CodeType = "UNKNOWN"
)

func Code

func Code(err error) CodeType

Code retrieves the first non unknown Code in err's tree. CodeUnknown indicates that no Code was set or no CustomError was found in the tree.

The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, Is examines err followed by a depth-first traversal of its children.

type CustomError

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

CustomError is a structure that encodes useful information about a given error.

Kind: Gives semantics for the error. It is expected to be interpreted by transport layers; Code: Defines what the Error actually is, by an unique alias; Retryable: Indicates if the given error may be fixed with a retry execution.

It is designed to work well within a Go Error Tree.

func New

func New(msg string, args ...any) CustomError

New returns a new instance of CustomError with the given message. It uses KindUnknown, CodeUnknown and 'false' by default for Kind, Code and Retryable attributes, respectively.

func (CustomError) Error

func (ce CustomError) Error() string

Error returns CustomError message.

func (CustomError) Is

func (ce CustomError) Is(target error) bool

Is indicates if the current error is equal to the given target one.

func (CustomError) Retryable

func (ce CustomError) Retryable() CustomError

Retryable returns a copy of the CustomError tagged as retryable.

func (CustomError) Unwrap

func (ce CustomError) Unwrap() []error

Unwrap unwraps all internal errors that are baselines for this error.

func (CustomError) WithCause

func (ce CustomError) WithCause(cause error) CustomError

WithCause return a copy of the CustomError with the given Cause attached as the last internal error of this CustomError.

func (CustomError) WithCode

func (ce CustomError) WithCode(code CodeType) CustomError

WithCode return a copy of the CustomError with the given CodeType filled.

func (CustomError) WithKind

func (ce CustomError) WithKind(kind KindType) CustomError

WithKind return a copy of the CustomError with the given KindType filled.

type KindType

type KindType string

KindType is a string that contains error's kind description.

const (
	// KindUnknown is the default kind returned when the application doesn't attach any kind into the error.
	KindUnknown KindType = "UNKNOWN"

	// KindConflict are errors caused by requests with data that conflicts with the current state of the system.
	KindConflict KindType = "CONFLICT"

	// KindInternal are errors caused by some internal fail like failed IO calls or invalid memory states.
	KindInternal KindType = "INTERNAL"

	// KindInvalidInput are errors caused by some invalid values on the input.
	KindInvalidInput KindType = "INVALID_INPUT"

	// KindNotFound are errors caused by any required resources that not exists on the data repository.
	KindNotFound KindType = "NOT_FOUND"

	// KindUnauthenticated are errors caused by an unauthenticated call.
	KindUnauthenticated KindType = "UNAUTHENTICATED"

	// KindUnauthorized are errors caused by an unauthorized call.
	KindUnauthorized KindType = "UNAUTHORIZED"

	// KindResourceExhausted indicates some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
	KindResourceExhausted KindType = "RESOURCE_EXHAUSTED"
)

func Kind

func Kind(err error) KindType

Kind retrieves the first non unknown Kind in err's tree. KindUnknown indicates that no Kind was set or no CustomError was found in the tree.

The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, Is examines err followed by a depth-first traversal of its children.