errors

Documentation

Overview

Package errors implements structured validation as well as error translations.

Index

• type ErrorCode
• type ValidationError
  • func Errorf(code ErrorCode, ctx context.Context, key string, args ...interface{}) ValidationError
  • func New(code ErrorCode, path, message string) ValidationError
  • func NewCoercionError(ctx context.Context, expected, received string) ValidationError
  • func NewRangeError(ctx context.Context, target string) ValidationError
• type ValidationErrorCollection
  • func Collection(errs ...ValidationError) ValidationErrorCollection
  • func (collection ValidationErrorCollection) All() []ValidationError
  • func (collection ValidationErrorCollection) Error() string
  • func (collection ValidationErrorCollection) First() ValidationError
  • func (collection ValidationErrorCollection) For(path string) ValidationErrorCollection
  • func (collection ValidationErrorCollection) Size() int
  • func (collection ValidationErrorCollection) Unwrap() []error

Types

type ErrorCode

type ErrorCode string

Error codes allow identifying of the error without having to do string comparison.

All user defined and module errors should have a number greater than 1000.

const (
	CodeUnknown    ErrorCode = "UNKNOWN"    // The cause of the validation error was not specified.
	CodeInternal   ErrorCode = "INTERNAL"   // An internal error occurred. We may know the reason but should not convey that to the user.
	CodeTimeout    ErrorCode = "TIMEOUT"    // The request timed out before validation could be completed.
	CodeCancelled  ErrorCode = "CANCELED"   // The request was cancelled before it could be completed.
	CodeType       ErrorCode = "TYPE"       // Unable to coerce a value to the correct type.
	CodeRange      ErrorCode = "RANGE"      // The data falls outside the range allowed by the type.
	CodeRequired   ErrorCode = "REQUIRED"   // Value is required to not be nil.
	CodeUnexpected ErrorCode = "UNEXPECTED" // Value was not expected to be defined.
	CodeMin        ErrorCode = "MIN"        // Value does not satisfy minimum constraints.
	CodeMax        ErrorCode = "MAX"        // Value does not satisfy maximum constraints.
	CodePattern    ErrorCode = "PATTERN"    // Value does not match an expected pattern or expression.
	CodeExpired    ErrorCode = "EXPIRED"    // Value has expired
	CodeForbidden  ErrorCode = "DENIED"     // Value is in a list of forbidden values.
	CodeNotAllowed ErrorCode = "NOTALLOWED" // Value is not one of the allowed values.
	CodeEncoding   ErrorCode = "ENCODING"   // Value is not encoded correctly.
)

type ValidationError

type ValidationError interface {
	Code() ErrorCode // Code returns the error code.
	Path() string    // Path returns the full path to the error in the data structure.
	Error() string   // Error returns the error message.
}

ValidationError stores information necessary to identify where the validation error is, as well as implementing the Error interface to work with standard errors.

func Errorf

func Errorf(code ErrorCode, ctx context.Context, key string, args ...interface{}) ValidationError

Errorf instantiates a new error given context and a format string. This uses message.Sprintf to format the message.

func New

func New(code ErrorCode, path, message string) ValidationError

New instantiates a validator error given a code, path, and message.

func NewCoercionError

func NewCoercionError(ctx context.Context, expected, received string) ValidationError

NewCoercionError creates a new ValidationError with the CodeType code given an expected and received type name.

Use when you expected one type and received another.

func NewRangeError

func NewRangeError(ctx context.Context, target string) ValidationError

NewCoercionError creates a new ValidationError with the CodeRange code given a a target data type.

Use when you understand the provided type and can convert from it but there is too much data to be contained in the new type.

For example, converting from int to int8 is ok if the value is less than 128 but anything higher cannot be converted and should throw an error.

type ValidationErrorCollection

type ValidationErrorCollection []ValidationError

ValidationErrorCollection implements a standard Error interface and also ValidationErrorCollection interface while preserving the validation data.

func Collection

func Collection(errs ...ValidationError) ValidationErrorCollection

Collection takes one or more ValidationError pointers and creates a new instance of a collection.

func (ValidationErrorCollection) All

func (collection ValidationErrorCollection) All() []ValidationError

All returns an array of all the errors in the collection. If there is more than one error, the order they are returned is not guaranteed to be deterministic.

Deprecated: All is deprecated and will be removed in v1.0.0. Use as you would a normal slice or call Unwrap instead.

func (ValidationErrorCollection) Error

func (collection ValidationErrorCollection) Error() string

Error implements the standard Error interface to return a string.

If there is more than one error, only the first will be returned and the total count will also be returned with the string.

When possible you should use the ValidationError object since this method loses contextual data.

If there is more than one error, which error is displayed is not guaranteed to be deterministic.

An empty collection should never be returned from a function. Return nil instead. This method panics if called on an empty collection.

func (ValidationErrorCollection) First

func (collection ValidationErrorCollection) First() ValidationError

First returns only the first error. If there is more than one error, the error returned is not guaranteed to be deterministic.

func (ValidationErrorCollection) For

func (collection ValidationErrorCollection) For(path string) ValidationErrorCollection

For returns a new collection containing only errors for a specific path.

func (ValidationErrorCollection) Size

func (collection ValidationErrorCollection) Size() int

Size returns the number of errors in the collection.

Deprecated: Size is deprecated and will be removed in v1.0.0. Use len(collection) instead.

func (ValidationErrorCollection) Unwrap

func (collection ValidationErrorCollection) Unwrap() []error

Unwrap implements the wrapped Error interface to return an array of errors.

An empty collection should never be returned from a function. Return nil instead. This method panics if called on an empty collection.