README
¶
github.com/Nigel2392/errors
A comprehensive utility package for error handling in Go. It provides a rich, structured error type that supports error codes, multiple related errors, and underlying causes, while seamlessly integrating with and extending the capabilities of both standard errors and github.com/pkg/errors.
Features
- Structured Errors: The
Errorstruct allows you to define errors with specificGoCodeconstants, clear messages, and underlying reasons. - Error Codes: Easily categorize and identify errors by their code rather than relying strictly on string matching.
- Cause Tracking: Chain errors and preserve the original cause using
WithCauseorWrap. - Related Errors: Store multiple related errors alongside the primary error.
- Drop-in Utility: Provides top-level wrapper functions for common operations like
Is,As,AsType,Wrap,Unwrap,Join, andCauseby leveraginggithub.com/pkg/errorsand standard libraryerrors.
Installation
go get [github.com/Nigel2392/errors](https://github.com/Nigel2392/errors)
Usage
Creating Structured Errors
Create an error with a specific code and message:
package main
import (
"fmt"
"os"
myerrors "github.com/Nigel2392/errors"
)
const ErrNotFound myerrors.GoCode = "NotFound"
func main() {
err := myerrors.New(ErrNotFound, "user could not be located in the database")
fmt.Println(err.Error())
err2 = err.Wrap("wrapped")
fmt.Println(err.Error())
fmt.Println(err2.Error())
f, err := os.Open(...)
if err != nil && errors.Is(err, os.ErrNotExist) {
err = ErrNotFound.WithCause(err)
}
}
Adding Context and Causes
Attach underlying causes to your structured errors without losing the initial code context:
package main
import (
"database/sql"
myerrors "github.com/Nigel2392/errors"
)
func getUser() error {
err := sql.ErrNoRows
// Create a base error, then attach the sql error as the reason
baseErr := myerrors.New("DB_ERROR", "failed to fetch user")
return baseErr.WithCause(err)
}
Using Wrapper Utilities
You can use the package as a drop-in replacement for standard errors and github.com/pkg/errors:
package main
import (
"fmt"
myerrors "github.com/Nigel2392/errors"
)
func main() {
err1 := myerrors.New("ERR_1", "first error")
err2 := myerrors.New("ERR_2", "second error")
// Join multiple errors
joined := myerrors.Join(err1, err2)
// Wrap an error with a stack trace
wrapped := myerrors.Wrap(joined, "additional context")
fmt.Println(wrapped)
}
Documentation
¶
Index ¶
- func As(err error, target interface{}) bool
- func AsType[ERROR error](err error) (ERROR, bool)
- func Cause(err error) error
- func Is(err error, target error) bool
- func Join(errs ...error) error
- func Unwrap(err error) error
- func WithMessage(err error, message string) error
- func WithMessagef(err error, format string, args ...interface{}) error
- func Wrap(err error, message string) error
- func Wrapf(err error, format string, args ...interface{}) error
- type AbstractError
- type Error
- type GoCode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func As ¶
As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true.
The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(interface{}) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.
As will panic if target is not a non-nil pointer to either a type that implements error, or to any interface type. As returns false if err is nil.
func AsType ¶ added in v1.0.4
AsType finds the first error in err's tree that matches the type E, and if one is found, returns that error value and true. Otherwise, it returns the zero value of E and false.
The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, AsType examines err followed by a depth-first traversal of its children.
An error err matches the type E if the type assertion err.(E) holds, or if the error has a method As(any) bool such that err.As(target) returns true when target is a non-nil *E. In the latter case, the As method is responsible for setting target.
func Cause ¶
Cause returns the underlying cause of the error, if possible. An error value has a cause if it implements the following interface:
type causer interface {
Cause() error
}
If the error does not implement Cause, the original error will be returned. If the error is nil, nil will be returned without further investigation.
func Is ¶
Is reports whether any error in err's tree matches target. The target must be comparable.
The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, Is examines err followed by a depth-first traversal of its children.
An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.
An error type might provide an Is method so it can be treated as equivalent to an existing error. For example, if MyError defines
func (m MyError) Is(target error) bool { return target == fs.ErrExist }
then Is(MyError{}, fs.ErrExist) returns true. See syscall.Errno.Is for an example in the standard library. An Is method should only shallowly compare err and the target and not call Unwrap on either.
func Join ¶
Join returns an error that wraps the given errors. Any nil error values are discarded. Join returns nil if every value in errs is nil. The error formats as the concatenation of the strings obtained by calling the Error method of each element of errs, with a newline between each string.
A non-nil error returned by Join implements the Unwrap() []error method. The errors may be inspected with Is and As.
func Unwrap ¶
Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.
Unwrap only calls a method of the form "Unwrap() error". In particular Unwrap does not unwrap errors returned by Join.
func WithMessage ¶
WithMessage annotates err with a new message. If err is nil, WithMessage returns nil.
func WithMessagef ¶
WithMessagef annotates err with the format specifier. If err is nil, WithMessagef returns nil.
Types ¶
type AbstractError ¶ added in v1.0.2
type AbstractError[ERROR AbstractError[ERROR]] interface { error Cause() error Is(chk error) bool // allows returning nil on nil error // // this does mean other methods called afterwards on a nil // error will panic. WithCause(reason error) AbstractError[ERROR] Unwrap() error Wrap(message string) ERROR Wrapf(format string, args ...any) ERROR }
func Errorf ¶
func Errorf(code GoCode, format string, args ...interface{}) AbstractError[Error]
Errorf formats according to a format specifier and returns the string as a value that satisfies error.
func Exec ¶ added in v1.0.2
func Exec[ERROR AbstractError[ERROR], T1 any, T2 error](_err ERROR, exec func() (T1, error)) (T1, AbstractError[ERROR])
Source Files