errorz

Documentation

Overview

Package errorz provides various utilities for working with errors.

Index

• func As[T any](err error) (T, bool)
• func Assertf(cond bool, format string, a ...any)
• func Catch0(f func() error) (outErr error)
• func Catch0Ctx(ctx context.Context, f func(ctx context.Context) error) (outErr error)
• func Catch1[T any](f func() (T, error)) (outV T, outErr error)
• func Catch1Ctx[T any](ctx context.Context, f func(ctx context.Context) (T, error)) (outV T, outErr error)
• func Catch2[T1 any, T2 any](f func() (T1, T2, error)) (outV1 T1, outV2 T2, outErr error)
• func Catch2Ctx[T1 any, T2 any](ctx context.Context, f func(ctx context.Context) (T1, T2, error)) (outV1 T1, outV2 T2, outErr error)
• func Catch3[T1 any, T2 any, T3 any](f func() (T1, T2, T3, error)) (outV1 T1, outV2 T2, outV3 T3, outErr error)
• func Catch3Ctx[T1 any, T2 any, T3 any](ctx context.Context, f func(ctx context.Context) (T1, T2, T3, error)) (outV1 T1, outV2 T2, outV3 T3, outErr error)
• func Errorf(format string, a ...any) error
• func IgnoreClose(c io.Closer)
• func MaybeGetMetadata[T any](err error, k any) (T, bool)
• func MaybeMustWrap(err error, outerErrs ...error)
• func MaybeSetMetadata(err error, k, v any)
• func MaybeWrap(err error, outerErrs ...error) error
• func MaybeWrapRecover(r any, outerErrs ...error) error
• func MustClose(c io.Closer)
• func MustErrorf(format string, a ...any)
• func MustGetMetadata[T any](err error, k any) T
• func MustWrap(innerErr error, outerErrs ...error)
• func SDump(err error) string
• func Unwrap(err error) []error
• func Wrap(err error, outerErrs ...error) error
• func WrapRecover(r any, outerErrs ...error) error
• type ErrorDetails
• type ErrorHTTPStatus
• type ErrorName
• type Frame
  • func NewFrame(frameFunction, file string, line int) *Frame
• type Frames
  • func GetFrames(err error) Frames
  • func (f Frames) ToSummaries() []string
• type Summary
  • func GetSummary(err error, includeComponents bool) *Summary
• type UnwrapMulti
• type UnwrapSingle

Functions

func As

func As[T any](err error) (T, bool)

As provides a more handy implementation of errors.As using generics.

func Assertf

func Assertf(cond bool, format string, a ...any)

Assertf is like MustErrorf if cond is false, does nothing otherwise.

func Catch0

func Catch0(f func() error) (outErr error)

Catch0 catches panics in a "func() error" closure.

func Catch0Ctx

func Catch0Ctx(ctx context.Context, f func(ctx context.Context) error) (outErr error)

Catch0Ctx catches panics in a "func(context.Context) error" closure.

func Catch1

func Catch1[T any](f func() (T, error)) (outV T, outErr error)

Catch1 catches panics in a "func() (T, error)" closure.

func Catch1Ctx

func Catch1Ctx[T any](ctx context.Context, f func(ctx context.Context) (T, error)) (outV T, outErr error)

Catch1Ctx catches panics in a "func(context.Context) (T, error)" closure.

func Catch2

func Catch2[T1 any, T2 any](f func() (T1, T2, error)) (outV1 T1, outV2 T2, outErr error)

Catch2 catches panics in a "func() (T1, T2, error)" closure.

func Catch2Ctx

func Catch2Ctx[T1 any, T2 any](
	ctx context.Context,
	f func(ctx context.Context) (T1, T2, error),
) (outV1 T1, outV2 T2, outErr error)

Catch2Ctx catches panics in a "func(context.Context) (T1, T2, error)" closure.

func Catch3

func Catch3[T1 any, T2 any, T3 any](f func() (T1, T2, T3, error)) (outV1 T1, outV2 T2, outV3 T3, outErr error)

Catch3 catches panics in a "func() (T1, T2, T3, error)" closure.

func Catch3Ctx

func Catch3Ctx[T1 any, T2 any, T3 any](
	ctx context.Context,
	f func(ctx context.Context) (T1, T2, T3, error),
) (outV1 T1, outV2 T2, outV3 T3, outErr error)

Catch3Ctx catches panics in a "func(context.Context) (T1, T2, T3, error)" closure.

func Errorf

func Errorf(format string, a ...any) error

Errorf creates an error and wraps it.

func IgnoreClose

func IgnoreClose(c io.Closer)

IgnoreClose calls io.Closer.Close, ignoring the returned error. Handy for the "defer Close" pattern.

func MaybeGetMetadata

func MaybeGetMetadata[T any](err error, k any) (T, bool)

MaybeGetMetadata tries to get the given metadata key from the error.

func MaybeMustWrap

func MaybeMustWrap(err error, outerErrs ...error)

MaybeMustWrap is like MustWrap, but does nothing if called with a nil error.

func MaybeSetMetadata

func MaybeSetMetadata(err error, k, v any)

MaybeSetMetadata sets the given metadata (k, v) on the error if it has been wrapped, does nothing otherwise.

func MaybeWrap

func MaybeWrap(err error, outerErrs ...error) error

MaybeWrap is like Wrap, but returns nil if called with a nil error.

func MaybeWrapRecover

func MaybeWrapRecover(r any, outerErrs ...error) error

MaybeWrapRecover is like WrapRecover but returns nil if called with a nil value.

func MustClose

func MustClose(c io.Closer)

MustClose calls io.Closer.Close, panicking in case of error. Handy for the "defer Close" pattern.

func MustErrorf

func MustErrorf(format string, a ...any)

MustErrorf is like Errorf but panics with the wrapped error instead of returning it.

func MustGetMetadata

func MustGetMetadata[T any](err error, k any) T

MustGetMetadata gets the given metadata key from the error, panics if not found or wrong type.

func MustWrap

func MustWrap(innerErr error, outerErrs ...error)

MustWrap is like Wrap, but panics with the wrapped error instead of returning it.

func SDump

func SDump(err error) string

SDump converts the error to a string representation for debug purposes.

func Unwrap

func Unwrap(err error) []error

Unwrap is similar to errors.Unwrap but works for errors implementing either UnwrapSingle and UnwrapMulti.

func Wrap

func Wrap(err error, outerErrs ...error) error

Wrap wraps the given errors.

func WrapRecover

func WrapRecover(r any, outerErrs ...error) error

WrapRecover takes a recovered value and converts it to a wrapped error.

Types

type ErrorDetails

type ErrorDetails interface {
	// GetErrorDetails returns some human-readable information about an error.
	GetErrorDetails() map[string]any
}

ErrorDetails can be implemented by errors to export some additional, human-readable information about the error.

type ErrorHTTPStatus

type ErrorHTTPStatus interface {
	// GetErrorHTTPStatus returns an HTTP status associated with an error.
	GetErrorHTTPStatus() int
}

ErrorHTTPStatus can be implemented by errors to attach an HTTP status to themselves.

type ErrorName

type ErrorName interface {
	// GetErrorName returns a human-readable name describing an error.
	GetErrorName() string
}

ErrorName can be implemented by errors to return a name different from their Go type.

type Frame

type Frame struct {
	Summary       string `json:"summary,omitempty"`
	Location      string `json:"location,omitempty"`
	ShortLocation string `json:"shortLocation,omitempty"`
	Package       string `json:"fullPackage,omitempty"`
	ShortPackage  string `json:"package,omitempty"`
	Function      string `json:"function,omitempty"`
	FileAndLine   string `json:"fileAndLine,omitempty"`
	File          string `json:"file,omitempty"`
	Line          int    `json:"line,omitempty"`
}

Frame describes a frame.

func NewFrame

func NewFrame(frameFunction, file string, line int) *Frame

NewFrame initializes a new frame.

type Frames

type Frames []*Frame

Frames describes a stack of frames.

func GetFrames

func GetFrames(err error) Frames

GetFrames returns the frames from the error, or the current frames the error is not wrapped or is nil.

func (Frames) ToSummaries

func (f Frames) ToSummaries() []string

ToSummaries converts the frames to a slice of frame summaries.

type Summary

type Summary struct {
	Name       string         `json:"name,omitempty"`
	Message    string         `json:"message,omitempty"`
	HTTPStatus int            `json:"httpStatus,omitempty"`
	Details    map[string]any `json:"details,omitempty"`
	Components []*Summary     `json:"components,omitempty"`
}

Summary presents an error in human-readable, debug form.

func GetSummary

func GetSummary(err error, includeComponents bool) *Summary

GetSummary returns a summary of the error.

type UnwrapMulti

type UnwrapMulti interface {
	// Unwrap returns one or more wrapped errors, if any, nil otherwise.
	Unwrap() []error
}

UnwrapMulti describes a method which returns multiple errors.

type UnwrapSingle

type UnwrapSingle interface {
	// Unwrap returns a single wrapped error, if any, nil otherwise.
	Unwrap() error
}

UnwrapSingle describes a method which returns a single error.