customerror

Documentation

Overview

Package customerror provides the base block to create custom errors, and some built-in custom errors. Custom errors standardizes errors across applications. It provides context - a `Message` to an optional `Err`. Additionally a `Code` - for example "E1010", and `StatusCode` can be provided.

Static Errors:

Custom static errors such as `ErrMissingID` can easily be created, and re-used. Just create that, for example, with the `NewMissingError` built-in.

Dynamic Errors:

Allows to create in-place custom errors.

Examples:

See `example_test.go` or the Example section of the GoDoc documention.

Index

• func NewFailedToError(message string, code string, err error) error
• func NewInvalidError(message string, code string, err error) error
• func NewMissingError(message string, code string, err error) error
• func NewRequiredError(message string, code string, err error) error
• func Wrap(customError, err error) error
• type CustomError
  • func New(message, code string, statusCode int, err error) *CustomError
  • func (cE *CustomError) Error() string
  • func (cE *CustomError) SetStatusCode(code int) *CustomError
  • func (err *CustomError) Unwrap() error

Examples

• New

Functions

func NewFailedToError

func NewFailedToError(message string, code string, err error) error

NewFailedToError is the building block for errors usually thrown when some action failed, e.g: "Failed to create host". Default status code is `500`.

Note: Status code can be redefined, call `SetStatusCode`.

func NewInvalidError

func NewInvalidError(message string, code string, err error) error

NewInvalidError is the building block for errors usually thrown when something fail validation, e.g: "Invalid port". Default status code is `400`.

Note: Status code can be redefined, call `SetStatusCode`.

func NewMissingError

func NewMissingError(message string, code string, err error) error

NewMissingError is the building block for errors usually thrown when required information is missing, e.g: "Missing host". Default status code is `400`.

Note: Status code can be redefined, call `SetStatusCode`.

func NewRequiredError

func NewRequiredError(message string, code string, err error) error

NewRequiredError is the building block for errors usually thrown when required information is missing, e.g: "Port is required". Default status code is `400`.

Note: Status code can be redefined, call `SetStatusCode`.

func Wrap

func Wrap(customError, err error) error

Wrap `customError` around `err`.

Types

type CustomError

type CustomError struct {
	// Code can be any custom code, e.g.: E1010.
	Code string `json:"code"`

	// Err optionally wraps the original error.
	Err error `json:"-"`

	// Human readable message. Minimum length: 3.
	Message string `json:"message" validate:"required,gte=3"`

	// StatusCode is a valid HTTP status code, e.g.: 404.
	StatusCode int `json:"-"`
}

CustomError is the base block to create custom errors. It provides context - a `Message` to an optional `Err`. Additionally a `Code` - for example "E1010", and `StatusCode` can be provided.

func New

func New(message, code string, statusCode int, err error) *CustomError

New creates custom errors. `message` is required. Failing to satisfy that will throw a fatal error.

Example

Demonstrates how to create static, and dynamic custom errors, also how to check, and instrospect custom errors.

// Custom static error definition.
var ErrMissingID = NewMissingError("id", "E1010", nil)

// Some function, for demo purpose.
var SomeFunc = func(id string) error {
	if id == "" {
		// Usage of the custom static error.
		return ErrMissingID
	}

	// Dynamic custom error.
	return NewFailedToError("write to disk", "E1523", nil)
}

// Case: Without `id`, retuns `ErrMissingID`.
if err := SomeFunc(""); err != nil {
	fmt.Println(errors.Is(err, ErrMissingID)) // true

	var cE *CustomError
	if errors.As(err, &cE) {
		fmt.Println(cE.StatusCode) // 400
	}

	fmt.Println(err) // E1010: missing id (400 - Bad Request)
}

// Case: With `id`, retuns dynamic error.
if err := SomeFunc("12345"); err != nil {
	var cE *CustomError
	if errors.As(err, &cE) {
		fmt.Println(cE.StatusCode) // 500
	}

	fmt.Println(err) // E1523: failed to write to disk (500 - Internal Server Error)
}

Output:
true
400
E1010: missing id (400 - Bad Request)
500
E1523: failed to write to disk (500 - Internal Server Error)

func (*CustomError) Error

func (cE *CustomError) Error() string

Error interface implementation returns the properly formatted error message.

func (*CustomError) SetStatusCode

func (cE *CustomError) SetStatusCode(code int) *CustomError

SetStatusCode sets the status code.

Note: Calling this on a static error is dangerous as it will change the status code of all its references!

func (*CustomError) Unwrap

func (err *CustomError) Unwrap() error

Unwrap interface implementation returns inner error.