errkit

package module
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 12, 2024 License: Apache-2.0 Imports: 8 Imported by: 22

README

Usage:

Creation

When creating an error, we can use one of the following ways. All errors created this way will capture the current line and filename.

    // Creation of error with some message.
    someError := errkit.New("Sample of std error")
    
    // Creation of error with some additional details
    anotherError := errkit.New("Some error with details", "TextDetail", "Text value", "NumericDetail", 123)

Sometimes it could be useful to create predefined errors. Such errors will not capture the stack.

var (
    ErrNotFound := errkit.NewSentinelErr("Not found")
    ErrAlreadyExists := errkit.NewSentinelErr("Already exists")
)

func Foo() error {
    ...
    return ErrNotFound
}

Wrapping

Adding stack trace

If you are interested in adding information about the line and filename where the sentinel error happened, you can do the following:

NOTE: While the WithStack will return nil if passed err equals nil, we do not consider this good practice and recommend checking the err value before invocation.

func Foo() error {
    ...
    err := errkit.WithStack(ErrNotFound)
    return err
}

func Bar() error {
    err := Foo()
    if err != nil && errkit.Is(err, ErrNotFound) {
        fmt.Println("Resource not found, do nothing")
        return nil
    }
    ...
}
Adding error cause information

Sometimes you might be interested in returning a sentinel error, but also add some cause error to it, in such cases you can do the following:

NOTE: While the WithCause will return nil if passed err equals nil, we do not consider this good practice and recommend checking the err value before invocation.

func FetchSomething(ID string) error {
    err := doSomething() // Here we have an error 
    if err != nil { // At this step we decide that in such a case we'd like to say that the resource is not found
        return errkit.WithCause(ErrNotFound, err)
    }
    
    return nil
}

func FooBar() error {
    err := FetchSomething()
    if err == nil {
        return nil
    }
    
    if errkit.Is(err, ErrNotFound) {
        return nil // Not found is an expected scenario here, do nothing
    }
    
    // Errors other than NotFound should be returned as is
    return err
}
Wrapping an error with a high-level message

Sometimes you might want to add some high-level information to an error before passing it up to the invoker.

NOTE: While the Wrap will return nil if passed err equals nil, we do not consider this good practice and recommend checking the err value before invocation.

func LoadProfile() error {
    err := makeAnApiCall()
    if err != nil {
        return errkit.Wrap(err, "Unable to load profile")
    }
    return nil
}

Unwrapping errors

If needed, you can always get the wrapped error using the standard errors.Unwrap method, it also has an alias errkit.Unwrap

    var (
		ErrSomething = errkit.NewSentinelErr("Some error")
    )   

    wrappedError := errkit.Wrap(ErrSomething, "Wrapped error")

    err := errors.Unwrap(wrappedError)
    if err != ErrSomething {
        return errors.New("Unable to unwrap error cause")
    }
Matching an errors

You can use standard errors matching methods like errors.Is and errors.As, they also have aliases errkit.Is and errkit.As

    // testErrorType which implements std error interface
    type testErrorType struct {
        message string
    }
	
    var (
        ErrTestType = newTestError("Sample error of custom type")
    )

    wrappedTestError := errkit.Wrap(ErrTestType, "Wrapped TEST error")
    if !errors.Is(wrappedTestError, ErrTestType) {
        return errors.New("error is not implementing requested type")
    }

    var asErr *testErrorType
    if !errors.As(origErr, &asErr) {
        return errors.New("unable to cast error to its cause")
    }

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	Is             = errors.Is
	As             = errors.As
	Unwrap         = errors.Unwrap
	NewSentinelErr = errors.New
)

Make an aliases for errors.Is, errors.As, errors.Unwrap To avoid additional imports

Functions

func Append

func Append(err1, err2 error) error

Append creates a new combined error from err1, err2. If either error is nil, then the other error is returned.

func MarshalErrkitErrorToJSON

func MarshalErrkitErrorToJSON(err *errkitError) ([]byte, error)

func New

func New(message string, details ...any) error

New returns an error with the given message.

func WithCause

func WithCause(err, cause error, details ...any) error

WithCause adds a cause to the given pure error. It returns nil when passed error is nil.

Intended for use when a function wants to return a well known error, but at the same time wants to add a reason E.g.:

var ErrNotFound = errkit.NewSentinelErr("Resource not found") ...

func SomeFunc() error {
  ...
  err := DoSomething()
  if err != nil {
     return errkit.WithCause(ErrNotFound, err)
  }
  ...
}

func WithStack

func WithStack(err error, details ...any) error

WithStack wraps the given error with a struct that when serialized to JSON will return a JSON object with the error message and error stack data.

Returns nil when nil is passed.

var ErrWellKnownError = errors.New("Well-known error")
...
if someCondition {
    return errkit.WithStack(ErrWellKnownError)
}

func Wrap

func Wrap(err error, message string, details ...any) error

Wrap returns a new errkitError that has the given message and err as the cause.

Types

type ErrorDetails

type ErrorDetails map[string]any

func ToErrorDetails

func ToErrorDetails(details []any) ErrorDetails

ToErrorDetails accepts either an even size array which contains pais of key/value or array of one element of ErrorDetails type. Result of function is an ErrorDetails

type ErrorList

type ErrorList []error

func (ErrorList) As

func (e ErrorList) As(target any) bool

As allows error.As to work against any error in the list.

func (ErrorList) Error

func (e ErrorList) Error() string

func (ErrorList) Is

func (e ErrorList) Is(target error) bool

Is allows error.Is to work against any error in the list.

func (ErrorList) MarshalJSON

func (e ErrorList) MarshalJSON() ([]byte, error)

func (ErrorList) String

func (e ErrorList) String() string

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL