Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/emperror/errors
Drop-in replacement for the standard library errors package and github.com/pkg/errors
https://github.com/emperror/errors
error errors stacktrace
Last synced: about 2 months ago
JSON representation
Drop-in replacement for the standard library errors package and github.com/pkg/errors
- Host: GitHub
- URL: https://github.com/emperror/errors
- Owner: emperror
- License: mit
- Created: 2019-07-09T13:02:52.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-06-20T01:43:12.000Z (over 2 years ago)
- Last Synced: 2024-10-01T12:11:17.667Z (3 months ago)
- Topics: error, errors, stacktrace
- Language: Go
- Homepage: https://emperror.dev/errors
- Size: 177 KB
- Stars: 196
- Watchers: 4
- Forks: 13
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - errors - Drop-in replacement for the standard library errors package and github.com/pkg/errors. Provides various error handling primitives. (Error Handling / Search and Analytic Databases)
- awesome-go-extra - errors - in replacement for the standard library errors package and github.com/pkg/errors|154|11|10|2019-07-09T13:02:52Z|2022-06-20T01:43:12Z| (Error Handling / Advanced Console UIs)
README
# Emperror: Errors [](https://github.com/avelino/awesome-go#error-handling)
[](https://github.com/emperror/errors/actions?query=workflow%3ACI)
[](https://codecov.io/gh/emperror/errors)
[](https://goreportcard.com/report/emperror.dev/errors)
[](https://pkg.go.dev/mod/emperror.dev/errors)
[](https://app.fossa.com/projects/custom%2B8125%2Femperror.dev%2Ferrors?ref=badge_shield)
**Drop-in replacement for the standard library `errors` package and [github.com/pkg/errors](https://github.com/pkg/errors).**
This is a single, lightweight library merging the features of standard library `errors` package
and [github.com/pkg/errors](https://github.com/pkg/errors). It also backports a few features
(like Go 1.13 error handling related features).
Standard library features:
- `New` creates an error with stack trace
- `Unwrap` supports both Go 1.13 wrapper (`interface { Unwrap() error }`) and **pkg/errors** causer (`interface { Cause() error }`) interface
- Backported `Is` and `As` functions
[github.com/pkg/errors](https://github.com/pkg/errors) features:
- `New`, `Errorf`, `WithMessage`, `WithMessagef`, `WithStack`, `Wrap`, `Wrapf` functions behave the same way as in the original library
- `Cause` supports both Go 1.13 wrapper (`interface { Unwrap() error }`) and **pkg/errors** causer (`interface { Cause() error }`) interface
Additional features:
- `NewPlain` creates a new error without any attached context, like stack trace
- `Sentinel` is a shorthand type for creating [constant error](https://dave.cheney.net/2016/04/07/constant-errors)
- `WithStackDepth` allows attaching stack trace with a custom caller depth
- `WithStackDepthIf`, `WithStackIf`, `WrapIf`, `WrapIff` only annotate errors with a stack trace if there isn't one already in the error chain
- Multi error aggregating multiple errors into a single value
- `NewWithDetails`, `WithDetails` and `Wrap*WithDetails` functions to add key-value pairs to an error
- Match errors using the `match` package
## Installation
```bash
go get emperror.dev/errors
```
## Usage
```go
package main
import "emperror.dev/errors"
// ErrSomethingWentWrong is a sentinel error which can be useful within a single API layer.
const ErrSomethingWentWrong = errors.Sentinel("something went wrong")
// ErrMyError is an error that can be returned from a public API.
type ErrMyError struct {
Msg string
}
func (e ErrMyError) Error() string {
return e.Msg
}
func foo() error {
// Attach stack trace to the sentinel error.
return errors.WithStack(ErrSomethingWentWrong)
}
func bar() error {
return errors.Wrap(ErrMyError{"something went wrong"}, "error")
}
func main() {
if err := foo(); err != nil {
if errors.Cause(err) == ErrSomethingWentWrong { // or errors.Is(ErrSomethingWentWrong)
// handle error
}
}
if err := bar(); err != nil {
if errors.As(err, &ErrMyError{}) {
// handle error
}
}
}
```
Match errors:
```go
package main
import (
"emperror.dev/errors"
"emperror.dev/errors/match"
)
// ErrSomethingWentWrong is a sentinel error which can be useful within a single API layer.
const ErrSomethingWentWrong = errors.Sentinel("something went wrong")
type clientError interface{
ClientError() bool
}
func foo() error {
// Attach stack trace to the sentinel error.
return errors.WithStack(ErrSomethingWentWrong)
}
func main() {
var ce clientError
matcher := match.Any{match.As(&ce), match.Is(ErrSomethingWentWrong)}
if err := foo(); err != nil {
if matcher.MatchError(err) {
// you can use matchers to write complex conditions for handling (or not) an error
// used in emperror
}
}
}
```
## Development
Contributions are welcome! :)
1. Clone the repository
1. Make changes on a new branch
1. Run the test suite:
```bash
./pleasew build
./pleasew test
./pleasew gotest
./pleasew lint
```
1. Commit, push and open a PR
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.
Certain parts of this library are inspired by (or entirely copied from) various third party libraries.
Their licenses can be found in the [Third Party License File](LICENSE_THIRD_PARTY).
[](https://app.fossa.com/projects/custom%2B8125%2Femperror.dev%2Ferrors?ref=badge_large)