errors

README

go-errors

powerful errors library with a simple API that allows:

• accessing all the standard library errors functions
• wrapping of errors
• adding values to errors, in a similar manner to contexts
• including calling function prefix when tag=errcaller is set
• including stacktrace with error when tag=errtrace is set

Documentation

Index

• Constants
• func As(err error, target any) bool
• func AsV2[Type any](err error) Type
• func Is(err error, target error) bool
• func IsV2(err error, targets ...error) bool
• func Join(errs ...error) error
• func New(msg string) error
• func NewAt(skip int, msg string) error
• func Newf(msgf string, args ...interface{}) error
• func Unwrap(err error) error
• func UnwrapV2(err error) []error
• func Value(err error, key any) any
• func WithValue(err error, key any, value any) error
• func Wrap(err error, msg string) error
• func WrapAt(skip int, err error, msg string) error
• func Wrapf(err error, msgf string, args ...interface{}) error
• type Callers
  • func Stacktrace(err error) Callers
  • func (c Callers) MarshalJSON() ([]byte, error)
  • func (c Callers) String() string
• type OnceError
  • func (e *OnceError) IsSet() bool
  • func (e *OnceError) Load() error
  • func (e *OnceError) Reset()
  • func (e *OnceError) Store(err error) bool

Constants

const IncludesCaller = false

IncludesCaller is a compile-time flag used to indicate whether to include calling function prefix on error wrap / creation.

const IncludesStacktrace = false

IncludesStacktrace is a compile-time flag used to indicate whether to include stacktraces on error wrap / creation.

Functions

func As

func As(err error, target any) bool

See: errors.As().

func AsV2

func AsV2[Type any](err error) Type

AsV2 is functionally similar to As(), instead leveraging generics to handle allocation and returning of a concrete generic parameter type.

func Is

func Is(err error, target error) bool

See: errors.Is().

func IsV2

func IsV2(err error, targets ...error) bool

IsV2 calls Is(err, target) for each target within targets.

func Join

func Join(errs ...error) error

See: errors.Join().

func New

func New(msg string) error

New returns a new error created from message.

Note this function cannot be inlined, to ensure expected and consistent behaviour in setting trace / caller info.

func NewAt

func NewAt(skip int, msg string) error

NewAt returns a new error created, skipping 'skip' frames for trace / caller information, from message.

Note this function cannot be inlined, to ensure expected and consistent behaviour in setting trace / caller info.

func Newf

func Newf(msgf string, args ...interface{}) error

Newf returns a new error created from message format and args.

Note this function cannot be inlined, to ensure expected and consistent behaviour in setting trace / caller info.

func Unwrap

func Unwrap(err error) error

See: errors.Unwrap().

func UnwrapV2

func UnwrapV2(err error) []error

UnwrapV2 is functionally similar to Unwrap(), except that it also handles the case of interface{ Unwrap() []error }.

func Value

func Value(err error, key any) any

Value searches for value stored under given key in error chain.

func WithValue

func WithValue(err error, key any, value any) error

WithValue wraps err to store given key-value pair, accessible via Value() function.

func Wrap

func Wrap(err error, msg string) error

Wrap will wrap supplied error within a new error created from message.

Note this function cannot be inlined, to ensure expected and consistent behaviour in setting trace / caller info.

func WrapAt

func WrapAt(skip int, err error, msg string) error

WrapAt wraps error within new error created from message, skipping 'skip' frames for trace / caller information.

Note this function cannot be inlined, to ensure expected and consistent behaviour in setting trace / caller info.

func Wrapf

func Wrapf(err error, msgf string, args ...interface{}) error

Wrapf will wrap supplied error within a new error created from message format and args.

Note this function cannot be inlined, to ensure expected and consistent behaviour in setting trace / caller info.

Types

type Callers

type Callers []runtime.Frame

Callers ...

func Stacktrace

func Stacktrace(err error) Callers

Stacktrace fetches first stored stacktrace of callers from error chain.

func (Callers) MarshalJSON

func (c Callers) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler to provide an easy, simple default.

func (Callers) String

func (c Callers) String() string

String will return a simple string representation of receiving Callers slice.

type OnceError

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

OnceError is an error structure that supports safe multi threaded usage and setting only once (until reset).

func (*OnceError) IsSet

func (e *OnceError) IsSet() bool

IsSet returns whether OnceError has been set.

func (*OnceError) Load

func (e *OnceError) Load() error

Load will load the currently stored error.

func (*OnceError) Reset

func (e *OnceError) Reset()

Reset will reset the OnceError value.

func (*OnceError) Store

func (e *OnceError) Store(err error) bool

Store will safely set the OnceError to value, no-op if nil.