Error handling tools and best practices for Go libraries and applications

![Emperror](.github/logo.png?raw=true)

[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go#error-handling)

[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/emperror/emperror/CI?style=flat-square)](https://github.com/emperror/emperror/actions?query=workflow%3ACI)
[![Codecov](https://img.shields.io/codecov/c/github/emperror/emperror?style=flat-square)](https://codecov.io/gh/emperror/emperror)
[![Go Report Card](https://goreportcard.com/badge/emperror.dev/emperror?style=flat-square)](https://goreportcard.com/report/emperror.dev/emperror)
![Go Version](https://img.shields.io/badge/go%20version-%3E=1.12-61CFDD.svg?style=flat-square)
[![PkgGoDev](https://pkg.go.dev/badge/mod/emperror.dev/emperror)](https://pkg.go.dev/mod/emperror.dev/emperror)
[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B8125%2Femperror.dev%2Femperror.svg?type=shield)](https://app.fossa.com/projects/custom%2B8125%2Femperror.dev%2Femperror?ref=badge_shield)


**The Emperor takes care of all errors personally.**

Go's philosophy encourages to gracefully handle errors whenever possible,
but some times recovering from an error is not.

In those cases handling the error means making the best effort to record every detail
for later inspection, doing that as high in the application stack as possible.

This project provides tools to make error handling easier.

Read more about the topic here:

- https://dave.cheney.net/2016/04/27/dont-just-check-errors-handle-them-gracefully
- https://8thlight.com/blog/kyle-krull/2018/08/13/exploring-error-handling-patterns-in-go.html
- https://banzaicloud.com/blog/error-handling-go/


## Features

- Various error handling strategies (eg. logging, third-party error services) using a simple interface
- Various helpers related to error handling (recovery from panics, etc)
- [Integrations](https://github.com/emperror?utf8=%E2%9C%93&q=handler-*&type=&language=) with well-known error catchers and libraries:
    - [Logur](https://github.com/logur/logur)
    - [Logrus](https://github.com/sirupsen/logrus)
    - [Sentry](https://sentry.io) [SDK](https://godoc.org/github.com/getsentry/raven-go) (both hosted and on-premise)
    - [Bugsnag](https://bugsnag.com) [SDK](https://godoc.org/github.com/bugsnag/bugsnag-go)
    - [Airbrake](https://airbrake.com) [SDK](https://godoc.org/github.com/airbrake/gobrake) / [Errbit](https://errbit.com/)
    - [Rollbar](https://rollbar.com) [SDK](https://godoc.org/github.com/rollbar/rollbar-go)


## Installation

```bash
go get emperror.dev/emperror
```


## Usage

### Log errors

Logging is one of the most common target to record error events.

Emperror has two logger integrations by default:
- [Logur handler](https://github.com/emperror/handler-logur)
- [Logrus handler](https://github.com/emperror/handler-logrus)


### Annotate errors passing through an error handler

Emperror can annotate errors with details as defined in [emperror.dev/errors](https://github.com/emperror/errors)

```go
package main

import (
	"emperror.dev/emperror"
	"emperror.dev/errors"
)

func main() {
	handler := emperror.WithDetails(newHandler(), "key", "value")

	err := errors.New("error")

	// handled error will receive the handler details
	handler.Handle(err)
}
```

### Panics and recovers

```go
package main

import (
	"emperror.dev/emperror"
	"emperror.dev/errors"
)

func main() {
	var handler emperror.Handler = newHandler()

	// Recover from panics and handle them as errors
	defer emperror.HandleRecover(handler)

	// nil errors will not panic
	emperror.Panic(nil)

	// this will panic if foo returns with a non-nil error
	// useful in main func for initial setup where "if err != nil" does not make much sense
	emperror.Panic(foo())
}

func foo() error {
	return errors.New("error")
}
```

### Filter errors

Sometimes you might not want to handle certain errors that reach the error handler.
A common example is a catch-all error handler in a server. You want to return business errors to the client.

```go
package main

import (
	"emperror.dev/emperror"
	"emperror.dev/errors/match"
)

func main() {
	var handler emperror.Handler = emperror.WithFilter(newHandler(), match.Any{/*any emperror.ErrorMatcher*/})

    // errors matching the provided matcher will not be handled
	handler.Handle(err)
}
```


## 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.

[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B8125%2Femperror.dev%2Femperror.svg?type=large)](https://app.fossa.com/projects/custom%2B8125%2Femperror.dev%2Femperror?ref=badge_large)


emperror

A better way to handle, trace, and log errors in Go. Compatible with the standard error library and github.com/pkg/errors

# eris

[![GoDoc][doc-img]][doc] [![Build][ci-img]][ci] [![GoReport][report-img]][report] [![Coverage Status][cov-img]][cov]

Package `eris` is an error handling library with readable stack traces and flexible formatting support.

`go get github.com/rotisserie/eris`



- [Why you should switch to eris](#why-you-should-switch-to-eris)
- [Using eris](#using-eris)
  * [Creating errors](#creating-errors)
  * [Wrapping errors](#wrapping-errors)
  * [Formatting and logging errors](#formatting-and-logging-errors)
  * [Interpreting eris stack traces](#interpreting-eris-stack-traces)
  * [Inverting the stack trace and error output](#inverting-the-stack-trace-and-error-output)
  * [Inspecting errors](#inspecting-errors)
  * [Formatting with custom separators](#formatting-with-custom-separators)
  * [Writing a custom output format](#writing-a-custom-output-format)
  * [Sending error traces to Sentry](#sending-error-traces-to-sentry)
- [Comparison to other packages (e.g. pkg/errors)](#comparison-to-other-packages-eg-pkgerrors)
  * [Error formatting and stack traces](#error-formatting-and-stack-traces)
- [Migrating to eris](#migrating-to-eris)
- [Contributing](#contributing)



## Why you should switch to eris

This package was inspired by a simple question: what if you could fix a bug without wasting time replicating the issue or digging through the code? With that in mind, this package is designed to give you more control over error handling via error wrapping, stack tracing, and output formatting.

The [example](https://github.com/rotisserie/eris/blob/master/examples/logging/example.go) that generated the output below simulates a realistic error handling scenario and demonstrates how to wrap and log errors with minimal effort. This specific error occurred because a user tried to access a file that can't be located, and the output shows a clear path from the top of the call stack to the source.

```json
{
  "error":{
    "root":{
      "message":"error internal server",
      "stack":[
        "main.main:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:143",
        "main.ProcessResource:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:85",
        "main.ProcessResource:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:82",
        "main.GetRelPath:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:61"
      ]
    },
    "wrap":[
      {
        "message":"failed to get relative path for resource 'res2'",
        "stack":"main.ProcessResource:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:85"
      },
      {
        "message":"Rel: can't make ./some/malformed/absolute/path/data.json relative to /Users/roti/",
        "stack":"main.GetRelPath:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:61"
      }
    ]
  },
  "level":"error",
  "method":"ProcessResource",
  "msg":"method completed with error",
  "time":"2020-01-16T11:20:01-05:00"
}
```

Many of the methods in this package will look familiar if you've used [pkg/errors](https://github.com/pkg/errors) or [xerrors](https://github.com/golang/xerrors), but `eris` employs some additional tricks during error wrapping and unwrapping that greatly improve the readability of the stack trace. This package also takes a unique approach to formatting errors that allows you to write custom formats that conform to your error or log aggregator of choice. You can find more information on the differences between `eris` and `pkg/errors` [here](#comparison-to-other-packages-eg-pkgerrors).

## Using eris

### Creating errors

Creating errors is simple via [`eris.New`](https://pkg.go.dev/github.com/rotisserie/eris#New).

```golang
var (
  // global error values can be useful when wrapping errors or inspecting error types
  ErrInternalServer = eris.New("error internal server")
)

func (req *Request) Validate() error {
  if req.ID == "" {
    // or return a new error at the source if you prefer
    return eris.New("error bad request")
  }
  return nil
}
```

### Wrapping errors

[`eris.Wrap`](https://pkg.go.dev/github.com/rotisserie/eris#Wrap) adds context to an error while preserving the original error.

```golang
relPath, err := GetRelPath("/Users/roti/", resource.AbsPath)
if err != nil {
  // wrap the error if you want to add more context
  return nil, eris.Wrapf(err, "failed to get relative path for resource '%v'", resource.ID)
}
```

### Formatting and logging errors

[`eris.ToString`](https://pkg.go.dev/github.com/rotisserie/eris#ToString) and [`eris.ToJSON`](https://pkg.go.dev/github.com/rotisserie/eris#ToJSON) should be used to log errors with the default format (shown above). The JSON method returns a `map[string]interface{}` type for compatibility with Go's `encoding/json` package and many common JSON loggers (e.g. [logrus](https://github.com/sirupsen/logrus)).

```golang
// format the error to JSON with the default format and stack traces enabled
formattedJSON := eris.ToJSON(err, true)
fmt.Println(json.Marshal(formattedJSON)) // marshal to JSON and print
logger.WithField("error", formattedJSON).Error() // or ideally, pass it directly to a logger

// format the error to a string and print it
formattedStr := eris.ToString(err, true)
fmt.Println(formattedStr)
```

`eris` also enables control over the [default format's separators](#formatting-with-custom-separators) and allows advanced users to write their own [custom output format](#writing-a-custom-output-format).

### Interpreting eris stack traces

Errors created with this package contain stack traces that are managed automatically. They're currently mandatory when creating and wrapping errors but optional when printing or logging. By default, the stack trace and all wrapped layers follow the opposite order of Go's `runtime` package, which means that the original calling method is shown first and the root cause of the error is shown last.

```golang
{
  "root":{
    "message":"error bad request", // root cause
    "stack":[
      "main.main:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:143", // original calling method
      "main.ProcessResource:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:71",
      "main.(*Request).Validate:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:29", // location of Wrap call
      "main.(*Request).Validate:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:28" // location of the root
    ]
  },
  "wrap":[
    {
      "message":"received a request with no ID", // additional context
      "stack":"main.(*Request).Validate:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:29" // location of Wrap call
    }
  ]
}
```

### Inverting the stack trace and error output

If you prefer some other order than the default, `eris` supports inverting both the stack trace and the entire error output. When both are inverted, the root error is shown first and the original calling method is shown last.

```golang
// create a default format with error and stack inversion options
format := eris.NewDefaultStringFormat(eris.FormatOptions{
  InvertOutput: true, // flag that inverts the error output (wrap errors shown first)
  WithTrace: true,    // flag that enables stack trace output
  InvertTrace: true,  // flag that inverts the stack trace output (top of call stack shown first)
})

// format the error to a string and print it
formattedStr := eris.ToCustomString(err, format)
fmt.Println(formattedStr)

// example output:
// error not found
//   main.GetResource:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:52
//   main.ProcessResource:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:76
//   main.main:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:143
// failed to get resource 'res1'
//   main.GetResource:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:52
```

### Inspecting errors

The `eris` package provides a couple ways to inspect and compare error types. [`eris.Is`](https://pkg.go.dev/github.com/rotisserie/eris#Is) returns true if a particular error appears anywhere in the error chain. Currently, it works simply by comparing error messages with each other. If an error contains a particular message (e.g. `"error not found"`) anywhere in its chain, it's defined to be that error type.

```golang
ErrNotFound := eris.New("error not found")
_, err := db.Get(id)
// check if the resource was not found
if eris.Is(err, ErrNotFound) {
  // return the error with some useful context
  return eris.Wrapf(err, "error getting resource '%v'", id)
}
```

[`eris.As`](https://pkg.go.dev/github.com/rotisserie/eris#As) finds the first error in a chain that matches a given target. If there's a match, it sets the target to that error value and returns true.

```golang
var target *NotFoundError
_, err := db.Get(id)
// check if the error is a NotFoundError type
if errors.As(err, &target) {
    // err is a *NotFoundError and target is set to the error's value
    return target
}
```

[`eris.Cause`](https://pkg.go.dev/github.com/rotisserie/eris#Cause) unwraps an error until it reaches the cause, which is defined as the first (i.e. root) error in the chain.

```golang
ErrNotFound := eris.New("error not found")
_, err := db.Get(id)
// compare the cause to some sentinel value
if eris.Cause(err) == ErrNotFound {
  // return the error with some useful context
  return eris.Wrapf(err, "error getting resource '%v'", id)
}
```

### Formatting with custom separators

For users who need more control over the error output, `eris` allows for some control over the separators between each piece of the output via the [`eris.Format`](https://pkg.go.dev/github.com/rotisserie/eris#Format) type. If this isn't flexible enough for your needs, see the [custom output format](#writing-a-custom-output-format) section below. To format errors with custom separators, you can define and pass a format object to [`eris.ToCustomString`](https://pkg.go.dev/github.com/rotisserie/eris#ToCustomString) or [`eris.ToCustomJSON`](https://pkg.go.dev/github.com/rotisserie/eris#ToCustomJSON).

```golang
// format the error to a string with custom separators
formattedStr := eris.ToCustomString(err, Format{
  FormatOptions: eris.FormatOptions{
    WithTrace: true,   // flag that enables stack trace output
  },
  MsgStackSep: "\n",   // separator between error messages and stack frame data
  PreStackSep: "\t",   // separator at the beginning of each stack frame
  StackElemSep: " | ", // separator between elements of each stack frame
  ErrorSep: "\n",      // separator between each error in the chain
})
fmt.Println(formattedStr)

// example output:
// error reading file 'example.json'
//   main.readFile | .../example/main.go | 6
// unexpected EOF
//   main.main | .../example/main.go | 20
//   main.parseFile | .../example/main.go | 12
//   main.readFile | .../example/main.go | 6
```

### Writing a custom output format

`eris` also allows advanced users to construct custom error strings or objects in case the default error doesn't fit their requirements. The [`UnpackedError`](https://pkg.go.dev/github.com/rotisserie/eris#UnpackedError) object provides a convenient and developer friendly way to store and access existing error traces. The `ErrRoot` and `ErrChain` fields correspond to the root error and wrap error chain, respectively. If a root error wraps an external error, that error will be default formatted and assigned to the `ErrExternal` field. If any other error type is unpacked, it will appear in the `ErrExternal` field. You can access all of the information contained in an error via [`eris.Unpack`](https://pkg.go.dev/github.com/rotisserie/eris#Unpack).

```golang
// get the unpacked error object
uErr := eris.Unpack(err)
// send only the root error message to a logging server instead of the complete error trace
sentry.CaptureMessage(uErr.ErrRoot.Msg)
```

### Sending error traces to Sentry

`eris` supports sending your error traces to [Sentry](https://sentry.io/) using the Sentry Go [client SDK](https://github.com/getsentry/sentry-go). You can run the example that generated the following output on Sentry UI using the command `go run examples/sentry/example.go -dsn=<DSN>`.

```
*eris.wrapError: test: wrap 1: wrap 2: wrap 3
  File "main.go", line 19, in Example
    return eris.New("test")
  File "main.go", line 23, in WrapExample
    err := Example()
  File "main.go", line 25, in WrapExample
    return eris.Wrap(err, "wrap 1")
  File "main.go", line 31, in WrapSecondExample
    err := WrapExample()
  File "main.go", line 33, in WrapSecondExample
    return eris.Wrap(err, "wrap 2")
  File "main.go", line 44, in main
    err := WrapSecondExample()
  File "main.go", line 45, in main
    err = eris.Wrap(err, "wrap 3")
```

## Comparison to other packages (e.g. pkg/errors)

### Error formatting and stack traces

Readability is a major design requirement for `eris`. In addition to the JSON output shown above, `eris` also supports formatting errors to a simple string.

```
failed to get resource 'res1'
  main.GetResource:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:52
error not found
  main.main:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:143
  main.ProcessResource:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:76
  main.GetResource:/Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:52
```

The `eris` error stack is designed to be easier to interpret than other error handling packages, and it achieves this by omitting extraneous information and avoiding unnecessary repetition. The stack trace above omits calls from Go's `runtime` package and includes just a single frame for wrapped layers which are inserted into the root error stack trace in the correct order. `eris` also correctly handles and updates stack traces for global error values in a transparent way.

The output of `pkg/errors` for the same error is shown below. In this case, the root error stack trace is incorrect because it was declared as a global value, and it includes several extraneous lines from the `runtime` package. The output is also much more difficult to read and does not allow for custom formatting.

```
error not found
main.init
  /Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:18
runtime.doInit
  /usr/local/Cellar/go/1.13.6/libexec/src/runtime/proc.go:5222
runtime.main
  /usr/local/Cellar/go/1.13.6/libexec/src/runtime/proc.go:190
runtime.goexit
  /usr/local/Cellar/go/1.13.6/libexec/src/runtime/asm_amd64.s:1357
failed to get resource 'res1'
main.GetResource
  /Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:52
main.ProcessResource
  /Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:76
main.main
  /Users/roti/go/src/github.com/rotisserie/eris/examples/logging/example.go:143
runtime.main
  /usr/local/Cellar/go/1.13.6/libexec/src/runtime/proc.go:203
runtime.goexit
  /usr/local/Cellar/go/1.13.6/libexec/src/runtime/asm_amd64.s:1357
```

## Migrating to eris

Migrating to `eris` should be a very simple process. If it doesn't offer something that you currently use from existing error packages, feel free to submit an issue to us. If you don't want to refactor all of your error handling yet, `eris` should work relatively seamlessly with your existing error types. Please submit an issue if this isn't the case for some reason.

Many of your dependencies will likely still use [pkg/errors](https://github.com/pkg/errors) for error handling. When external error types are wrapped with additional context, `eris` creates a new root error that wraps the original external error. Because of this, error inspection should work seamlessly with other error libraries.

## Contributing

If you'd like to contribute to `eris`, we'd love your input! Please submit an issue first so we can discuss your proposal.

-------------------------------------------------------------------------------

Released under the [MIT License].

[MIT License]: LICENSE.txt
[doc-img]: https://pkg.go.dev/badge/github.com/rotisserie/eris
[doc]: https://pkg.go.dev/github.com/rotisserie/eris
[ci-img]: https://github.com/rotisserie/eris/workflows/build/badge.svg
[ci]: https://github.com/rotisserie/eris/actions
[report-img]: https://goreportcard.com/badge/github.com/rotisserie/eris
[report]: https://goreportcard.com/report/github.com/rotisserie/eris
[cov-img]: https://codecov.io/gh/rotisserie/eris/branch/master/graph/badge.svg
[cov]: https://codecov.io/gh/rotisserie/eris

eris

Hackable package that determines responsible source code for an error (and some other fast-debugging features). Pluggable to any logger in-place

# Errlog: reduce debugging time while programming [![Go Report Card](https://goreportcard.com/badge/github.com/snwfdhmp/errlog)](https://goreportcard.com/report/github.com/snwfdhmp/errlog) [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome) [![Documentation](https://godoc.org/github.com/snwfdhmp/errlog?status.svg)](http://godoc.org/github.com/snwfdhmp/errlog) [![GitHub issues](https://img.shields.io/github/issues/snwfdhmp/errlog.svg)](https://github.com/snwfdhmp/errlog/issues) [![license](https://img.shields.io/github/license/snwfdhmp/errlog.svg?maxAge=6000)](https://github.com/snwfdhmp/errlog/LICENSE) 

![Example](https://i.imgur.com/Ulf1RGw.png)

<a href="https://www.buymeacoffee.com/snwfdhmp" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 30px !important;width: 120px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" ></a>

## Introduction

Use errlog to improve error logging and **speed up  debugging while you create amazing code** :

- Highlight source code
- **Detect and point out** which func call is causing the fail
- Pretty stack trace
- **No-op mode** for production
- Easy implementation, adaptable logger
- Plug to any current project without changing you or your teammates habits
- Plug to **your current logging system**

|Go to|
|---|
|[Get started](#get-started)|
|[Documentation](#documentation)|
|[Examples](#example)|
|[Tweaking](#tweak-as-you-need)|
|[Feedbacks](#feedbacks)|
|[Contributions](#contributions)|
|[License](#license-information)|
|[Contributors](#contributors)|

## Get started

### Install

```shell
go get github.com/snwfdhmp/errlog
```

### Usage

Replace your `if err != nil` with `if errlog.Debug(err)` to add debugging informations.

```golang
func someFunc() {
    //...
    if errlog.Debug(err) { // will debug & pass if err != nil, will ignore if err == nil
        return
    }
}
```

In production, call `errlog.DefaultLogger.Disable(true)` to enable no-op (equivalent to `if err != nil`)

## Tweak as you need

You can configure your own logger with the following options :

```golang
type Config struct {
    PrintFunc          func(format string, data ...interface{}) //Printer func (eg: fmt.Printf)
    LinesBefore        int  //How many lines to print *before* the error line when printing source code
    LinesAfter         int  //How many lines to print *after* the error line when printing source code
    PrintStack         bool //Shall we print stack trace ? yes/no
    PrintSource        bool //Shall we print source code along ? yes/no
    PrintError         bool //Shall we print the error of Debug(err) ? yes/no
    ExitOnDebugSuccess bool //Shall we os.Exit(1) after Debug has finished logging everything ? (doesn't happen when err is nil). Will soon be replaced by ExitFunc to enable panic-ing the current goroutine. (if you need this quick, please open an issue)
}
```

> As we don't yet update automatically this README immediately when we add new features, this definition may be outdated. (Last update: 2019/08/07)
> [See the struct definition in godoc.org](https://godoc.org/github.com/snwfdhmp/errlog#Config) for the up to date definition


## Example

### Try yourself

| Name and link | Description |
| --- | --- |
| [Basic](examples/basic/basic.go) | standard usage, quick setup
| [Custom](examples/custom/custom.go) | guided configuration for fulfilling your needs |
| [Disabled](examples/disabled/disabled.go) | how to disable the logging & debugging (eg: for production use) |
| [Failing line far away](examples/failingLineFar/failingLineFar.go) | example of finding the func call that caused the error while it is lines away from the errlog.Debug call |
| [Pretty stack trace](examples/stackTrace/stackTrace.go) | pretty stack trace printing instead of debugging. |

### Just read

#### Basic example

> Note that in the example, you will see some unuseful func. Those are made to generate additional stack trace levels for the sake of example

We're going to use this sample program :

```golang
func main() {
    fmt.Println("Program start")

    wrapingFunc() //call to our important function

    fmt.Println("Program end")
}

func wrapingFunc() {
    someBigFunction() // call some func 
}

func someBigFunction() {
    someDumbFunction() // just random calls
    someSmallFunction() // just random calls
    someDumbFunction() // just random calls

    // Here it can fail, so instead of `if err  != nil` we use `errlog.Debug(err)`
    if err := someNastyFunction(); errlog.Debug(err) {
        return
    }

    someSmallFunction() // just random calls
    someDumbFunction() // just random calls
}

func someSmallFunction() {
    _ = fmt.Sprintf("I do things !")
}

func someNastyFunction() error {
    return errors.New("I'm failing for some reason") // simulate an error
}

func someDumbFunction() bool {
    return false // just random things
}
```


#### Output

![Console Output examples/basic.go](https://i.imgur.com/tOkDgwP.png)


We are able to **detect and point out which line is causing the error**.

### Custom Configuration Example

Let's see what we can do with a **custom configuration.**

```golang
debug := errlog.NewLogger(&errlog.Config{
    // PrintFunc is of type `func (format string, data ...interface{})`
    // so you can easily implement your own logger func.
    // In this example, logrus is used, but any other logger can be used.
    // Beware that you should add '\n' at the end of format string when printing.
    PrintFunc:          logrus.Printf,
    PrintSource:        true, //Print the failing source code
    LinesBefore:        2, //Print 2 lines before failing line
    LinesAfter:         1, //Print 1 line after failing line
    PrintError:         true, //Print the error
    PrintStack:         false, //Don't print the stack trace
    ExitOnDebugSuccess: true, //Exit if err
})
```

> Please note: This definition may be outdated. (Last update: 2019/08/07)
> [See the struct definition in godoc.org](https://godoc.org/github.com/snwfdhmp/errlog#Config) for the up to date definition

#### Output

![Console Output examples/custom.go](https://i.imgur.com/vh2iEnS.png)


### When the failing func call is a few lines away

Even when the func call is a few lines away, there is no problem for finding it.

#### Output

![Source Example: error earlier in the code](https://i.imgur.com/wPBrYqs.png)

## Documentation

Documentation can be found here : [![Documentation](https://godoc.org/github.com/snwfdhmp/errlog?status.svg)](http://godoc.org/github.com/snwfdhmp/errlog)

## Feedbacks

Feel free to open an issue for any feedback or suggestion.

I fix process issues quickly.

## Contributions

We are happy to collaborate with you :

- Ask for a new feature: [Open an issue](https://github.com/snwfdhmp/errlog/issues/new)
- Add your feature: [Open a PR](https://github.com/snwfdhmp/errlog/compare)

When submitting a PR, please apply Effective Go best practices. For more information: https://golang.org/doc/effective_go.html

## License information

Click the following badge to open LICENSE information.

[![license](https://img.shields.io/github/license/snwfdhmp/errlog.svg?maxAge=60000)](https://github.com/snwfdhmp/errlog/LICENSE)

## Contributors

### Major

- [snwfdhmp](https://github.com/snwfdhmp): Author and maintainer
- [chemidy](https://github.com/chemidy): Added important badges

### Minor fixes

- [orisano](https://github.com/orisano)
- [programmingman](https://github.com/programmingman)


errlog

Drop-in replacement for the standard library errors package and github.com/pkg/errors. Provides various error handling primitives

# Emperror: Errors [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go#error-handling)

[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/emperror/errors/CI?style=flat-square)](https://github.com/emperror/errors/actions?query=workflow%3ACI)
[![Codecov](https://img.shields.io/codecov/c/github/emperror/errors?style=flat-square)](https://codecov.io/gh/emperror/errors)
[![Go Report Card](https://goreportcard.com/badge/emperror.dev/errors?style=flat-square)](https://goreportcard.com/report/emperror.dev/errors)
![Go Version](https://img.shields.io/badge/go%20version-%3E=1.12-61CFDD.svg?style=flat-square)
[![PkgGoDev](https://pkg.go.dev/badge/mod/emperror.dev/errors)](https://pkg.go.dev/mod/emperror.dev/errors)
[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B8125%2Femperror.dev%2Ferrors.svg?type=shield)](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).

[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B8125%2Femperror.dev%2Ferrors.svg?type=large)](https://app.fossa.com/projects/custom%2B8125%2Femperror.dev%2Ferrors?ref=badge_large)


errors

Simple golang error handling with classification primitives

![Neuron Logo](logo.svg)

# Errors [![Go Report Card](https://goreportcard.com/badge/github.com/neuronlabs/errors)](https://goreportcard.com/report/github.com/neuronlabs/errors) [![GoDoc](https://godoc.org/github.com/neuronlabs/errors?status.svg)](https://godoc.org/github.com/neuronlabs/errors) [![Build Status](https://travis-ci.com/neuronlabs/errors.svg?branch=master)](https://travis-ci.com/neuronlabs/errors) [![Coverage Status](https://coveralls.io/repos/github/neuronlabs/errors/badge.svg?branch=master)](https://coveralls.io/github/neuronlabs/errors?branch=master) ![License](https://img.shields.io/github/license/neuronlabs/errors.svg)

Package errors provides simple golang error and classification primitives.

* [Class](#class)
* [Interfaces](#interfaces)
* [Error Handling](#error-handling)
* [Example](#example)
* [Links](#links)

## Class

The package defines blazingly fast classification system.
A `Class` is an uint32 wrapper, composed of the `Major`, `Minor` and `Index` subclassifications.
Each subclassifaction has different bitwise length.
A major is composed of 8, minor 10 and index of 14 bits - total 32bits.

Example:

```Class with decimal value of 44205263, in a binary form equals to
 00000010101000101000010011001111 which decomposes into:
 00000010 - major (8 bit)
         1010001010 - minor (10 bit)
                   00010011001111 - index (14 bit)
```

The class concept was inspired by the need of multiple errors
with the same logic but different messages.

A class might be composed in three different ways:

* Major only - the class is Major singleton.
* Major, Minor only - classes that don't need triple subclassification divison.
* Major, Minor, Index - classes that decomposes 

Use `NewMajor` or `MustNewMajor` functions to create `Major`, `NewMinor` or `MustNewMinor` for new `Minor` and `NewIndex` or `MustNewIndex` for new `Index`.



## Interfaces

The package provides simple error handling interfaces and functions.
It allows to create simple and detailed classified errors.

## ClassError

A `ClassError` is the interface that provides error classification with the`Class` method.

## DetailedError

`DetailedError` is the interface used for errors that stores and handles human readable details, contains it's instance id and runtime call operation.
Implements `ClassError`, `Detailer`, `Operationer`, `Indexer`, `error` interfaces.

### Detailer

`Detailer` interface allows to set and get the human readable details - full sentences.

### Operationer

`OperationError` is the interface used to get the runtime operation information.

### Indexer

`Indexer` is the interface used to obtain 'ID' for each error instance.


## Error handling

This package contains two error structure implementations: 

* [Simple Error Structure](#simple-error)
* [Detailed Error Structure](#detailed-error)

### Simple Error

A simple error implements `ClassError` interface. It is lightweight error that contains only a message and it's class.

Created by the `New` and `Newf` functions.

**Example:**
```go
import "github.com/neuronlabs/errors"
// let's assume we have some ClassInvalidRequest already defined.
var ClassInvalidInput errors.Class

func createValue(input int) error {
    if input < 0 {
        return errors.New(ClassInvalidInput, "provided input lower than zero")
    }

    if input > 50 {
        return errors.Newf(ClassInvalidInput, "provided input value: '%d' is not valid", input) 
    }
    // do the logic here
    return nil
}
```

### Detailed Error

The detailed error struct (`detailedError`) implements `DetailedError`.

It contains a lot of information about given error instance:

* Human readable `Details`
* Runtime function call `Operations`
* Unique error instance `ID` 

In order to create detailed error use the `NewDet` or `NewDetf` functions.

### Example

```go
import (
    "fmt"
    "os"

    "github.com/neuronlabs/errors"
)

var (
    ClInputInvalidValue errors.Class
    ClInputNotProvided  errors.Class
)

func init() {
    initClasses()
}

func initClasses() {
    inputMjr := errors.MustNewMajor()
    invalidValueMnr := errors.MustNewMinor(inputMjr)
    ClInputInvalidValue = errors.MustNewMinorClass(inputMjr, invalidValueMnr)
    
    inputNotProvidedMnr := errors.MustNewMinor(inputMjr)
    ClInputNotProvided = errors.MustNewMinorClass(inputMjr, inputNotProvidedMnr)
}


func main() {
    input, err := getInput()
    if err == nil {
        // Everything is fine.
        os.Exit(0)
    }

    if classed, ok := err.(errors.ClassError); ok {
        if classed.Class() == ClInputNotProvided {
            fmt.Println("No required integer arguments provided.")
            os.Exit(1)
        }
    }

    var details string
    detailed, ok := err.(errors.DetailedError)
    if ok {
        details = detailed.Details()
    } else {
        details = err.Error()
    }
    fmt.Printf("Invalid input value provided: '%s'\n", details)
    os.Exit(1)    
}


func checkInput(input int) error {
    if input < 0 {
        err := errors.NewDet(ClassInputInvalidValue, "provided input lower than zero")        
        err.SetDetailsf("The input value provided to the function is invalid. The value must be greater than zero.")
        return err
    }

    if input > 50 {
        err := errors.NewDetf(ClassInvalidInput, "provided input value: '%d' is not valid", input) 
        err.SetDetailsf("The input value: '%d' provided to the function is invalid. The value can't be greater than '50'.", input)
        return err
    }
    // do the logic here
    return nil
}



func getInput() (int, error) {
    if len(os.Args) == 0 {
        return errors.New(ClInputNotProvided, "no input provided")
    }

    input, err := strconv.Atoi(os.Args[0])
    if err != nil {
        err := errors.NewDetf(ClInputInvalidValue, "provided input is not an integer")        
        err.SetDetail(err.Error())
        return 0, err
    }

    if err = checkInput(input); err != nil {
        return 0, err
    }
    return input, nil
}
```

## Links

* [Neuron-Core](https://github.com/neuronlabs/neuron-core)
* [Docs](https://docs.neuronlabs.io/errors)


Go error library with error portability over the network

Drop-in replacement for builtin Go errors. This is a minimal error handling package with custom error types, user friendly messages, Unwrap & Is. With very easy to use and straightforward helper functions.

<p align="center"><img src="https://user-images.githubusercontent.com/1092882/87815217-d864a680-c882-11ea-9c94-24b67f7125fe.png" alt="errors gopher" width="256px"/></p>

[![](https://github.com/naughtygopher/errors/actions/workflows/go.yml/badge.svg?branch=master)](https://github.com/naughtygopher/errors/actions)
[![Go Reference](https://pkg.go.dev/badge/github.com/naughtygopher/errors.svg)](https://pkg.go.dev/github.com/naughtygopher/errors)
[![Go Report Card](https://goreportcard.com/badge/github.com/naughtygopher/errors)](https://goreportcard.com/report/github.com/naughtygopher/errors)
[![Coverage Status](https://coveralls.io/repos/github/naughtygopher/errors/badge.svg?branch=master)](https://coveralls.io/github/naughtygopher/errors?branch=master)
[![](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#error-handling)

# Errors v1.0.0

Errors package is a drop-in replacement of the built-in Go errors package. It lets you create errors of 11 different types,
which should handle most of the use cases. Some of them are a bit too specific for web applications, but useful nonetheless.

Features of this package:

1. Multiple (11) error types
2. Easy handling of User friendly message(s)
3. Stacktrace - formatted, unfromatted, custom format (refer tests in errors_test.go)
4. Retrieve the Program Counters for the stacktrace
5. Retrieve runtime.Frames using `errors.RuntimeFrames(err error)` for the stacktrace
6. HTTP status code and user friendly message (wrapped messages are concatenated) for all error types
7. Helper functions to generate each error type
8. Helper function to get error Type, error type as int, check if error type is wrapped anywhere in chain
9. `fmt.Formatter` support

In case of nested errors, the messages & errors are also looped through the full chain of errors.

### Prerequisites

Go 1.13+

### Available error types

1. TypeInternal - For internal system error. e.g. Database errors
2. TypeValidation - For validation error. e.g. invalid email address
3. TypeInputBody - For invalid input data. e.g. invalid JSON
4. TypeDuplicate - For duplicate content error. e.g. user with email already exists (when trying to register a new user)
5. TypeUnauthenticated - For not authenticated error
6. TypeUnauthorized - For unauthorized access error
7. TypeEmpty - For when an expected non-empty resource, is empty
8. TypeNotFound - For expected resource not found. e.g. user ID not found
9. TypeMaximumAttempts - For attempting the same action more than an allowed threshold
10. TypeSubscriptionExpired - For when a user's 'paid' account has expired
11. TypeDownstreamDependencyTimedout - For when a request to a downstream dependent service times out

Helper functions are available for all the error types. Each of them have 2 helper functions, one which accepts only a string,
and the other which accepts an original error as well as a user friendly message.

All the dedicated error type functions are documented [here](https://pkg.go.dev/github.com/naughtygopher/errors?tab=doc#DownstreamDependencyTimedout).
Names are consistent with the error type, e.g. errors.Internal(string) and errors.InternalErr(error, string)

### User friendly messages

More often than not when writing APIs, we'd want to respond with an easier to undersand user friendly message.
Instead of returning the raw error and log the raw error.

There are helper functions for all the error types. When in need of setting a friendly message, there
are helper functions with the _suffix_ **'Err'**. All such helper functions accept the original error and a string.

```golang
package main

import (
	"fmt"

	"github.com/naughtygopher/errors"
)

func Bar() error {
	return fmt.Errorf("hello %s", "world!")
}

func Foo() error {
	err := Bar()
	if err != nil {
		return errors.InternalErr(err, "bar is not happy")
	}
	return nil
}

func main() {
	err := Foo()

	fmt.Println("err:", err)
	fmt.Println("\nerr.Error():", err.Error())

	fmt.Printf("\nformatted +v: %+v\n", err)
	fmt.Printf("\nformatted v: %v\n", err)
	fmt.Printf("\nformatted +s: %+s\n", err)
	fmt.Printf("\nformatted s: %s\n", err)

	_, msg, _ := errors.HTTPStatusCodeMessage(err)
	fmt.Println("\nmsg:", msg)
}
```

Output

```
err: bar is not happy

err.Error(): /Users/k.balakumaran/go/src/github.com/naughtygopher/errors/cmd/main.go:16: bar is not happy
hello world!bar is not happy

formatted +v: /Users/k.balakumaran/go/src/github.com/naughtygopher/errors/cmd/main.go:16: bar is not happy
hello world!bar is not happy

formatted v: bar is not happy

formatted +s: bar is not happy: hello world!

formatted s: bar is not happy

msg: bar is not happy
```

[Playground link](https://go.dev/play/p/-WzDH46f_U5)

### File & line number prefixed to errors

A common annoyance with Go errors which most people are aware of is, figuring out the origin of the error, especially when there are nested function calls. Ever since error annotation was introduced in Go, a lot of people have tried using it to trace out an errors origin by giving function names, contextual message etc in it. e.g. `fmt.Errorf("database query returned error %w", err)`. However this errors package, whenever you call the Go error interface's `Error() string` function, prints the error prefixed by the filepath and line number. It'd look like `../Users/JohnDoe/apps/main.go:50 hello world` where 'hello world' is the error message.

### HTTP status code & message

The function `errors.HTTPStatusCodeMessage(error) (int, string, bool)` returns the HTTP status code, message, and a boolean value. The boolean is true, if the error is of type \*Error from this package. If error is nested, it unwraps and returns a single concatenated message. Sample described in the 'How to use?' section

## How to use?

A sample was already shown in the user friendly message section, following one would show a few more scenarios.

```golang
package main

import (
	"fmt"
	"net/http"
	"time"

	"github.com/naughtygopher/errors"
	"github.com/naughtygopher/webgo/v6"
	"github.com/naughtygopher/webgo/v6/middleware/accesslog"
)

func bar() error {
	return fmt.Errorf("%s %s", "sinking", "bar")
}

func bar2() error {
	err := bar()
	if err != nil {
		return errors.InternalErr(err, "bar2 was deceived by bar1 :(")
	}
	return nil
}

func foo() error {
	err := bar2()
	if err != nil {
		return errors.InternalErr(err, "we lost bar2!")
	}
	return nil
}

func handler(w http.ResponseWriter, r *http.Request) {
	err := foo()
	if err != nil {
		// log the error on your server for troubleshooting
		fmt.Println(err.Error())
		// respond to request with friendly msg
		status, msg, _ := errors.HTTPStatusCodeMessage(err)
		webgo.SendError(w, msg, status)
		return
	}

	webgo.R200(w, "yay!")
}

func routes() []*webgo.Route {
	return []*webgo.Route{
		{
			Name:    "home",
			Method:  http.MethodGet,
			Pattern: "/",
			Handlers: []http.HandlerFunc{
				handler,
			},
		},
	}
}

func main() {
	router := webgo.NewRouter(&webgo.Config{
		Host:         "",
		Port:         "8080",
		ReadTimeout:  15 * time.Second,
		WriteTimeout: 60 * time.Second,
	}, routes()...)

	router.UseOnSpecialHandlers(accesslog.AccessLog)
	router.Use(accesslog.AccessLog)
	router.Start()
}
```

[webgo](https://github.com/naughtygopher/webgo) was used to illustrate the usage of the function, `errors.HTTPStatusCodeMessage`. It returns the appropriate http status code, user friendly message stored within, and a boolean value. Boolean value is `true` if the returned error of type \*Error.
Since we get the status code and message separately, when using any web framework, you can set values according to the respective framework's native functions. In case of Webgo, it wraps errors in a struct of its own. Otherwise, you could directly respond to the HTTP request by calling `errors.WriteHTTP(error,http.ResponseWriter)`.

Once the app is running, you can check the response by opening `http://localhost:8080` on your browser. Or on terminal

```bash
$ curl http://localhost:8080
{"errors":"we lost bar2!. bar2 was deceived by bar1 :(","status":500} // output
```

And the `fmt.Println(err.Error())` generated output on stdout would be:

```bash
/Users/username/go/src/errorscheck/main.go:28 /Users/username/go/src/errorscheck/main.go:20 sinking bar
```

## Benchmark [2022-01-12]

MacBook Pro (13-inch, 2020, Four Thunderbolt 3 ports), 32 GB 3733 MHz LPDDR4X

```bash
$ go version
go version go1.19.5 darwin/amd64

$ go test -benchmem -bench .
goos: darwin
goarch: amd64
pkg: github.com/naughtygopher/errors
cpu: Intel(R) Core(TM) i7-1068NG7 CPU @ 2.30GHz
Benchmark_Internal-8                            	 1526194	       748.8 ns/op	    1104 B/op	       2 allocs/op
Benchmark_Internalf-8                           	 1281465	       944.0 ns/op	    1128 B/op	       3 allocs/op
Benchmark_InternalErr-8                         	 1494351	       806.7 ns/op	    1104 B/op	       2 allocs/op
Benchmark_InternalGetError-8                    	  981162	      1189 ns/op	    1528 B/op	       6 allocs/op
Benchmark_InternalGetErrorWithNestedError-8     	  896322	      1267 ns/op	    1544 B/op	       6 allocs/op
Benchmark_InternalGetMessage-8                  	 1492812	       804.2 ns/op	    1104 B/op	       2 allocs/op
Benchmark_InternalGetMessageWithNestedError-8   	 1362092	       886.3 ns/op	    1128 B/op	       3 allocs/op
Benchmark_HTTPStatusCodeMessage-8               	27494096	        41.38 ns/op	      16 B/op	       1 allocs/op
BenchmarkHasType-8                              	100000000	        10.50 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	github.com/naughtygopher/errors	15.006s
```

## Contributing

More error types, customization, features, multi-errors; PRs & issues are welcome!

## The gopher

The gopher used here was created using [Gopherize.me](https://gopherize.me/). Show some love to Go errors like our gopher lady here!


An ergonomic mechanism for wrapping errors in order to facilitate structured metadata and context for error values

![header](./docs/header.png)

[![GoDoc](https://pkg.go.dev/badge/github.com/Southclaws/fault)](https://pkg.go.dev/github.com/Southclaws/fault?tab=doc)
[![Go Report Card](https://goreportcard.com/badge/github.com/Southclaws/fault)](https://goreportcard.com/report/github.com/Southclaws/fault)
[![codecov](https://codecov.io/gh/Southclaws/fault/branch/main/graph/badge.svg?token=U06OABVKm3)](https://codecov.io/gh/Southclaws/fault)

> Used in production at [Storyden](https://github.com/Southclaws/storyden) - an open source forum+wiki written in Go!

Fault provides an extensible yet ergonomic mechanism for wrapping errors. It implements this as a kind of middleware style pattern of simple functions called **decorators**: `func(error) error`. A decorator simply wraps an error within another error, much like many libraries do.

What this facilitates is a simple, minimal and (most important) _composable_ collection of error handling utilities designed to help you **diagnose problems** in your application logic without the need for overly verbose stack traces.

This is achieved by annotating errors with **structured** metadata instead of just gluing strings of text together. This approach plays nicely with structured logging tools as well as the existing Go errors ecosystem.

- [Usage](#usage)
  - [Wrapping errors](#wrapping-errors)
  - [Handling errors](#handling-errors)
- [Utilities](#utilities)
  - [`fmsg`](#fmsg)
  - [`fctx`](#fctx)
  - [`ftag`](#ftag)
- [Appendix](#appendix)

## Usage

You can gradually adopt Fault into your codebase as it plays nicely with the existing Go error management ecosystem.

### Wrapping errors

Wrapping errors as you ascend the call stack is essential to providing your team with adequate context when something goes wrong.

Simply wrap your errors as you would with any library:

```go
if err != nil {
    return fault.Wrap(err)
}
```

What this gives you is basic stack traces. The philosophy behind stack traces provided by Fault is that you only care about relevant code locations. You do not need `runtime/proc.go` in your stack traces unless you're actually working on the Go compiler or some crazy low level tooling. A fault stack trace looks like this when formatted with `%+v`:

```
stdlib sentinel error
    /Users/southclaws/Work/fault/fault_test.go:34
failed to call function
    /Users/southclaws/Work/fault/fault_test.go:43
    /Users/southclaws/Work/fault/fault_test.go:52
```

And of course all of this information is accessible in a structured way so you can serialise it how you want for your logging stack of choice. Fault aims to be unopinionated about presentation.

But what if you want to add context? With pkg/errors and similar libraries, you often use `errors.Wrap(err, "failed to do something")` to add a bit of context to a wrapped error.

Fault provides something much more powerful, a mechanism to compose many wrappers together. The `Wrap` API in Fault accepts any number of functions that wrap the error with the signature `func(error) error` so the possibilities are endless.

```go
if err != nil {
    return fault.Wrap(err, fmsg.With("failed to do a thing"))
}
```

This is how you add a message to an error in the same way you would with pkg/errors. Now this is quite verbose, lots of typing involved and if this is all you're going to do, you don't need to use Fault, you can just use `fmt.Errorf` and `%w`.

The power comes when you make use of some of the additional packages available as part of Fault:

```go
if err != nil {
    return fault.Wrap(err,
        fctx.With(ctx), // decorate the error with key-value metadata from context
        ftag.With(ftag.NotFound), // categorise the error as a "not found"
        fmsg.With("failed to do something", "There was a technical error while retrieving your account"), // provide an end-user message
    )
}
```

You can also build your own utilities that work with the Fault option pattern. This is covered later in this document.

### Handling errors

Wrapping errors is only half the story, eventually you'll need to actually
_handle_ the error (and no, `return err` is not "handling" an error, it's
saying "I don't know what to do! Caller, you deal with this!".)

Utilities will provide their own way of extracting information from an error but Fault provides the `Flatten` function which allows you to access a simple stack trace and a reference to the root cause error.

```go
chain := Flatten(err)
```

#### `chain.Root`

This is the root cause of the error chain. In other words, the error that was either created with `errors.New` (or similar) or some external error from another library not using Fault.

#### `chain.Errors`

This is the list of wrapped errors in the chain where the first item is the wrapper of the root cause.

![error chain diagram](./docs/chain.png)

## Utilities

Fault provides some utilities in subpackages to help you annotate and diagnose problems easily. Fault started its life as a single huge kitchen-sink style library but it quickly became quite bloated and developers rarely used everything it provided. This inspired the simple modular option-style design and each useful component was split into its own package.

It's worth noting that all of these utilities can be used on their own. If you don't want to use Fault's wrapping or stack traces you can simply import a library and use its `Wrap` function.

### `fmsg`

![end-user error example](./docs/fmsg.png)

This simple utility gives you the ability to decorate error chains with a separate set of messages intended for both developers and end-users to read.

The error messages returned by `.Error()` are always intended for developers to read. They are rarely exposed to end-users. When they are, it's usually fairly confusing and not a great user-experience.

You can use `fmsg.With` (or `fmsg.Withf` if you need formatted string) to wrap an error with an extra string of text, just like pkg/errors and similar:

```go
extraContext := "extra context"
err := errors.New("root")
err = fault.Wrap(err, fmsg.With("one"))
err = fault.Wrap(err, fmsg.Withf("two (%s)", extraContext))
err = fault.Wrap(err, fmsg.With("three"))
fmt.Println(err)
// three: two (extra context): one: root
```

As with any simple error wrapping library, the `.Error()` function simply joins these messages together with `:`.

However, in order to provide useful end-user error descriptions, you can use `fmsg.WithDesc`:

```go
if err != nil {
    return fault.Wrap(err,
        fmsg.WithDesc("permission denied", "The post is not accessible from this account."),
    )
}
```

Once you're ready to render the human-readable errors to end-users, you simply call `GetIssue`:

```go
issues := GetIssue(err)
// "The post is not accessible from this account."
```

Multiple wrapped issues are conjoined with a single space. Issue messages should end in a punctuation mark such as a period.

```go
if err != nil {
    return fault.Wrap(err,
        fmsg.With("permission denied", "The category cannot be edited."),
    )
}

// later on

if err != nil {
    return fault.Wrap(err,
        fmsg.With("move post failed", "Could not move post to the specified category."),
    )
}
```

Yields:

```go
issues := GetIssue(err)
// "Could not move post to the specified category. The category cannot be edited."
```

Which, while it reads much nicer than `move post failed: permission denied`, both messages are valuable to their individual target audiences.

Further reading on the topic of human-friendly error messages in [this article](https://wix-ux.com/when-life-gives-you-lemons-write-better-error-messages-46c5223e1a2f).

### `fctx`

![fctx example](./docs/fctx.png)

Error context is the missing link between the context package and errors. Contexts often contain bits of metadata about a call stack in large scale applications. Things like trace IDs, request IDs, user IDs, etc.

The problem is, once an error occurs and the stack starts to "unwind" (chained returns until the error is truly "handled" somewhere) the information stored in a context has already gone.

fctx gives you two tools to help understand the actual _context_ around a problem.

#### Add metadata to a context

First, you decorate contexts with key-value data. Strings only and no nesting for simplicity.

```go
ctx = fctx.WithMeta(ctx, "trace_id", traceID)
```

This stores the `traceID` value into the context. Conflicting keys will overwrite.

Note that while this function may look similar to `context.WithValue` in concept, it differs since it permits you to access _all_ of the key-value as a single object for iterating later. When using `context.WithValue` you must know the exact keys. Now you could store a map but in order to add items to that map you would need to first read the map out, check if it exists, insert your key-value data and write it back.

#### Decorate errors with context metadata

When something goes wrong, all that metadata stored in a context can be copied into an error.

```go
if err != nil {
    return fault.Wrap(err,
        fctx.With(ctx),
    )
}
```

#### Access metadata for logging

When your error chain is handled, you most likely want to log what happened. You can access key-value metadata from an error using `Unwrap`:

```go
ec := fctx.Unwrap(err)
logger.Error("http handler failed", ec)
```

The `Unwrap` function returns a simple `map[string]string` value which you can use with your favourite structured logging tool. Now, instead of your logs looking like this:

```json
{
  "error": "failed to create post 'My new post' in thread '1647152' by user '@southclaws' database connection refused"
}
```

Which is an absolute nightmare to search for when every error is worded differently...

They look like this:

```json
{
  "error": "failed to create post: database connection refused",
  "metadata": {
    "title": "My new post",
    "thread_id": "1647152",
    "user_id": "@southclaws"
  }
}
```

Which is an absolute godsend when things go wrong.

### `ftag`

This utility simply annotates an entire error chain with a single string. This facilitates categorising error chains with a simple token that allows mapping errors to response mechanisms such as HTTP status codes or gRPC status codes.

You can use the included error kinds which cover a wide variety of common categories of error or you can supply your own set of constants for your team/codebase.

```go
if err != nil {
    return fault.Wrap(err,
        ftag.With(ftag.NotFound),
    )
}
```

Once you've annotated an error chain, you can use it later to determine which HTTP status to respond with:

```go
ek := ftag.Get(err)
// ftag.NotFound = "NOT_FOUND"

switch ek {
  case ftag.NotFound:
    return http.StatusNotFound
  // others...
  default:
    return http.StatusInternalServerError
}
```

This removes the need to write verbose and explicit `errors.Is` checks on the error type to determine which type of HTTP status code to respond with.

Since the type `Kind` is just an alias to string, you can pass anything and switch on it.

## Appendix

### Rationale

The reason Fault came into existence was because I found nesting calls to various `Wrap` APIs was really awkward to write and read. The Golang errors ecosystem is diverse but unfortunately, composing together many small error related tools remains awkward due to the simple yet difficult to extend patterns set by the Golang standard library and popular error packages.

For example, to combine pkg/errors, tracerr and fctx you'd have to write:

```
fctx.Wrap(errors.Wrap(tracerr.Wrap(err), "failed to get user"), ctx)
```

Which is a bit of a nightmare to write (many nested calls) and a nightmare to read (not clear where the arguments start and end for each function). Because of this, it's not common to compose together libraries from the ecosystem.

### Prior art

Building on the shoulders of giants, as is the open source way. Here are some great libraries I goodartistscopygreatartistssteal'd from:

- https://github.com/rotisserie/eris
- https://github.com/cockroachdb/logtags
- https://github.com/cockroachdb/errors/tree/master/contexttags
- https://pkg.go.dev/google.golang.org/grpc/status

### Why "Fault"?

Because the word error is overused.

![errors everywhere](./docs/errors.png)


Fault

Go (golang) package for representing a list of errors as a single error

# go-multierror

[![CircleCI](https://img.shields.io/circleci/build/github/hashicorp/go-multierror/master)](https://circleci.com/gh/hashicorp/go-multierror)
[![Go Reference](https://pkg.go.dev/badge/github.com/hashicorp/go-multierror.svg)](https://pkg.go.dev/github.com/hashicorp/go-multierror)
![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/hashicorp/go-multierror)

[circleci]: https://app.circleci.com/pipelines/github/hashicorp/go-multierror
[godocs]: https://pkg.go.dev/github.com/hashicorp/go-multierror

> **Note**: As of Go 1.20, the standard library provides [`errors.Join`](https://pkg.go.dev/errors#Join) which offers similar functionality for combining multiple errors. **For new projects, we recommend using `errors.Join` from the standard library.** This package provides additional features like custom formatting, the `Group` pattern for concurrent error collection, and utility functions (`Append`, `Flatten`, `Prefix`).

## Migrating to `errors.Join`

**Basic error aggregation:**
```go
// Before (go-multierror)
var result error
result = multierror.Append(result, err1)
result = multierror.Append(result, err2)
return result

// After (stdlib)
var errs []error
if err1 != nil {
    errs = append(errs, err1)
}
if err2 != nil {
    errs = append(errs, err2)
}
if len(errs) > 0 {
    return errors.Join(errs...)
}
return nil
```

**Custom formatting:**
```go
// go-multierror allows custom formatting
// With stdlib, wrap the joined error with a custom type if needed
type FormattedError struct {
    errs []error
}

func (e *FormattedError) Error() string {
    // Your custom format here
    return fmt.Sprintf("multiple errors: %v", e.errs)
}

func (e *FormattedError) Unwrap() []error {
    return e.errs
}
```

**Concurrent error collection (Group):**
```go
// golang.org/x/sync/errgroup returns only the first error:
import "golang.org/x/sync/errgroup"

g := new(errgroup.Group)
g.Go(func() error { return task1() })
g.Go(func() error { return task2() })
err := g.Wait() // Returns first error only

// To collect ALL errors like multierror.Group does, use a mutex:
type ErrorCollector struct {
    mu   sync.Mutex
    errs []error
}

func (ec *ErrorCollector) Add(err error) {
    if err != nil {
        ec.mu.Lock()
        ec.errs = append(ec.errs, err)
        ec.mu.Unlock()
    }
}

func (ec *ErrorCollector) Err() error {
    ec.mu.Lock()
    defer ec.mu.Unlock()
    if len(ec.errs) == 0 {
        return nil
    }
    return errors.Join(ec.errs...)
}
```

---

`go-multierror` is a package for Go that provides a mechanism for
representing a list of `error` values as a single `error`.

This allows a function in Go to return an `error` that might actually
be a list of errors. If the caller knows this, they can unwrap the
list and access the errors. If the caller doesn't know, the error
formats to a nice human-readable format.

`go-multierror` is compatible with the Go standard library
[errors](https://golang.org/pkg/errors/) package, supporting the
`As`, `Is`, and `Unwrap` functions for error introspection. Note that `Unwrap` 
returns errors one at a time via chaining, unlike `errors.Join` which 
implements the newer `Unwrap() []error` signature (Go 1.20+).

## Installation and Docs

Install using `go get github.com/hashicorp/go-multierror`.

Full documentation is available at
https://pkg.go.dev/github.com/hashicorp/go-multierror

### Requires go version 1.13 or newer

`go-multierror` requires go version 1.13 or newer. Go 1.13 introduced
[error wrapping](https://golang.org/doc/go1.13#error_wrapping), which
this library takes advantage of.

If you need to use an earlier version of go, you can use the
[v1.0.0](https://github.com/hashicorp/go-multierror/tree/v1.0.0)
tag, which doesn't rely on features in go 1.13.

If you see compile errors that look like the below, it's likely that
you're on an older version of go:

```
/go/src/github.com/hashicorp/go-multierror/multierror.go:112:9: undefined: errors.As
/go/src/github.com/hashicorp/go-multierror/multierror.go:117:9: undefined: errors.Is
```

## Usage

go-multierror is easy to use and purposely built to be unobtrusive in
existing Go applications/libraries that may not be aware of it.

**Building a list of errors**

The `Append` function is used to create a list of errors. This function
behaves a lot like the Go built-in `append` function: it doesn't matter
if the first argument is nil, a `multierror.Error`, or any other `error`,
the function behaves as you would expect.

```go
var result error

if err := step1(); err != nil {
	result = multierror.Append(result, err)
}
if err := step2(); err != nil {
	result = multierror.Append(result, err)
}

return result
```

**Customizing the formatting of the errors**

By specifying a custom `ErrorFormat`, you can customize the format
of the `Error() string` function:

```go
var result *multierror.Error

// ... accumulate errors here, maybe using Append

if result != nil {
	result.ErrorFormat = func([]error) string {
		return "errors!"
	}
}
```

**Accessing the list of errors**

`multierror.Error` implements `error` so if the caller doesn't know about
multierror, it will work just fine. But if you're aware a multierror might
be returned, you can use type switches to access the list of errors:

```go
if err := something(); err != nil {
	if merr, ok := err.(*multierror.Error); ok {
		// Use merr.Errors
	}
}
```

You can also use the standard [`errors.Unwrap`](https://golang.org/pkg/errors/#Unwrap)
function. This will continue to unwrap into subsequent errors until none exist.

**Extracting an error**

The standard library [`errors.As`](https://golang.org/pkg/errors/#As)
function can be used directly with a multierror to extract a specific error:

```go
// Assume err is a multierror value
err := somefunc()

// We want to know if "err" has a "RichErrorType" in it and extract it.
var errRich RichErrorType
if errors.As(err, &errRich) {
	// It has it, and now errRich is populated.
}
```

**Checking for an exact error value**

Some errors are returned as exact errors such as the [`ErrNotExist`](https://golang.org/pkg/os/#pkg-variables)
error in the `os` package. You can check if this error is present by using
the standard [`errors.Is`](https://golang.org/pkg/errors/#Is) function.

```go
// Assume err is a multierror value
err := somefunc()
if errors.Is(err, os.ErrNotExist) {
	// err contains os.ErrNotExist
}
```

**Returning a multierror only if there are errors**

If you build a `multierror.Error`, you can use the `ErrorOrNil` function
to return an `error` implementation only if there are errors to return:

```go
var result *multierror.Error

// ... accumulate errors here

// Return the `error` only if errors were added to the multierror, otherwise
// return nil since there are no errors.
return result.ErrorOrNil()
```


go-multierror

Error handling with context, stack trace and source fragments

oops

The most simple error wrapper with awesome performance and minimal memory overhead

[![Build Status](https://travis-ci.com/PumpkinSeed/errors.svg?branch=master)](https://travis-ci.com/PumpkinSeed/errors)
[![Go Report Card](https://goreportcard.com/badge/github.com/PumpkinSeed/errors)](https://goreportcard.com/report/github.com/PumpkinSeed/errors)
[![Documentation](https://godoc.org/github.com/PumpkinSeed/errors?status.svg)](http://godoc.org/github.com/PumpkinSeed/errors)
[![Gocover](http://gocover.io/_badge/github.com/PumpkinSeed/errors)](http://gocover.io/github.com/PumpkinSeed/errors)

# Errors

Simple error package for Go with minimal allocation and high performance. Optimized to keep error on function stack.

### Motivation

I found out that the available error packages too complex for the simple purpose or not achieve the simple goal.

### Purpose & Goal

Maintain an error chain (some kind of list of errors), and let the system to check whether the error's type caused the actual error or not.

### Usage

```go
package main

import (
    stderrors "errors"

    "github.com/PumpkinSeed/errors"
)

var ErrGlobal = errors.New("global err")
var ErrGlobal2 = errors.New("global err 2")
var ErrNotUsed = errors.New("not used err")

func main() {
    err := f3()
    
    stderrors.Is(err, ErrGlobal) // true
    stderrors.Is(err, ErrGlobal2) // true
    stderrors.Is(err, ErrNotUsed) // false

    println(err.Error()) // "global err 2: global err: string1"
}

func f1() error {
    return errors.New("string1")
}

func f2() error {
    return errors.Wrap(f1(), ErrGlobal)
}

func f3() error {
    return errors.Wrap(f2(), ErrGlobal2)
}
```  


A simple utility package for exception handling with try-catch in Golang

![Exception](gopher.png)

![Go test workflow](https://github.com/rbrahul/exception/actions/workflows/go.yaml/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/rbrahul/exception)](https://goreportcard.com/report/github.com/rbrahul/exception)
[![codecov](https://codecov.io/gh/rbrahul/exception/branch/main/graph/badge.svg?token=CW54A6HWS6)](https://codecov.io/gh/rbrahul/exception)
[![Go Reference](https://pkg.go.dev/badge/github.com/rbrahul/exception.svg)](https://pkg.go.dev/github.com/rbrahul/exception)

## Go Try Catch Exception Handler
By design, Go doesn't offer any mechanism for Exception handling. But Programmers from different backgrounds like Java, C++, Php can be sceptical about the decision. Exception handling with *Try Catch Finally* is well adapted in all the modern languages. To ease the pain, this library offers utility functions for Exception Handling, which will help programmers to write Go code with *Try-Catch-Finally* approach.

### This is how you can throw Exception and handle within Catch:

```go
 import(
     e "github.com/rbrahul/exception"
 )

...
    e.Try(func() {
        data := getValue() // get me the value from Allions
        if data != 100 {
		    e.Throw(e.AssertionError("Expected value is not same as 100"))
        }
	})
    .Catch(e.In(e.AssertionErrorType, e.ValueErrorType), func(excep *Exception) {
        fmt.Println("Message:",excep.Message)
        fmt.Println("Exception Type:",excep.Type)
        fmt.Println("Here is the Stack Trace:",excep.StackTrace)
    })
    .Catch(nil, func(excep *Exception) {
        fmt.Println("I'll be executed as fallback:",excep.Message)
    })
    .Finally(func() {
		fmt.Println("I have been executing always to clean the world!")
	})
    .Run()
...
```

### Throwing a custom exception

You have to define a exception variable with ExceptionType.

```go
const SomethingWentWrongError  e.ExceptionType = "SomethingWentWrongError"
```

Now you have to initialize and throw your exception via e.New constructor. You can pass a proper error message as optional argument.

```go
    e.Try(func() {
        e.Throw(e.New(SomethingWentWrongError, "Something went worng!"))
	})
    .Catch(e.In(SomethingWentWrongError), func(excep *Exception) {
        fmt.Println("Message:",excep.Message)
        fmt.Println("Exception Type:",excep.Type)
    })
    .Finally(func() {
		fmt.Println("I'm Gonna fix it!")
	})
    .Run()
```

### You can wrap any panic with try-catch and recover it elegently

```go
    e.Try(func() {
        panic("I'm gonna panic but don't worry")
	})
    .Catch(nil, func(excep *Exception) {
        fmt.Println("I knew you are gonna catch me :p", excep.Message)
    })
    .Run()
```


exception

A Simple Yet Highly Powerful Package For Error Handling

[![Go Report Card](https://goreportcard.com/badge/github.com/SonicRoshan/falcon)](https://goreportcard.com/report/github.com/SonicRoshan/falcon) [![GoDoc](https://godoc.org/github.com/SonicRoshan/falcon?status.svg)](https://godoc.org/github.com/SonicRoshan/falcon) [![GoCover](https://gocover.io/_badge/github.com/SonicRoshan/falcon)](https://gocover.io/github.com/SonicRoshan/falcon)
# Falcon
Minimal And Efficient Error Handling In Go


## Simple Example
```go
errHandler := falcon.NewErrorHandler()

errHandler.AddHandler(func(err error, data ...interface{}) interface{} {
    fmt.Println("Generic Error Occured")
    return SomeData
})

errHandler.AddHandler(func(err error, data ...interface{}) interface{} {
    fmt.Println("Error Of Type CustomErrorType Occured")
    return SomeData
}, CustomErrorType{})

SomeData := errHandler.Check(err, SomeRandomData1, SomeRandomData2)
// Data passed after the err will be passed to handlers
```




Falcon

Package for representing a list of errors as a single error

# multierr [![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov]

`multierr` allows combining one or more Go `error`s together.

## Features

- **Idiomatic**:
  multierr follows best practices in Go, and keeps your code idiomatic.
    - It keeps the underlying error type hidden,
      allowing you to deal in `error` values exclusively.
    - It provides APIs to safely append into an error from a `defer` statement.
- **Performant**:
  multierr is optimized for performance:
    - It avoids allocations where possible.
    - It utilizes slice resizing semantics to optimize common cases
      like appending into the same error object from a loop.
- **Interoperable**:
  multierr interoperates with the Go standard library's error APIs seamlessly:
    - The `errors.Is` and `errors.As` functions *just work*.
- **Lightweight**:
  multierr comes with virtually no dependencies.

## Installation

```bash
go get -u go.uber.org/multierr@latest
```

## Status

Stable: No breaking changes will be made before 2.0.

-------------------------------------------------------------------------------

Released under the [MIT License].

[MIT License]: LICENSE.txt
[doc-img]: https://pkg.go.dev/badge/go.uber.org/multierr
[doc]: https://pkg.go.dev/go.uber.org/multierr
[ci-img]: https://github.com/uber-go/multierr/actions/workflows/go.yml/badge.svg
[cov-img]: https://codecov.io/gh/uber-go/multierr/branch/master/graph/badge.svg
[ci]: https://github.com/uber-go/multierr/actions/workflows/go.yml
[cov]: https://codecov.io/gh/uber-go/multierr


multierr

Golang errors with stack trace and source fragments

# Golang Errors with Stack Trace and Source Fragments

[![GoDoc](https://godoc.org/github.com/ztrue/tracerr?status.svg)](https://godoc.org/github.com/ztrue/tracerr)
[![Report](https://goreportcard.com/badge/github.com/ztrue/tracerr)](https://goreportcard.com/report/github.com/ztrue/tracerr)
[![Coverage Status](https://coveralls.io/repos/github/ztrue/tracerr/badge.svg?branch=master)](https://coveralls.io/github/ztrue/tracerr?branch=master)

Tired of uninformative error output? Probably this will be more convenient:

![Output](output.png)

## Example

```go
package main

import (
	"io/ioutil"

	"github.com/ztrue/tracerr"
)

func main() {
	if err := read(); err != nil {
		tracerr.PrintSourceColor(err)
	}
}

func read() error {
	return readNonExistent()
}

func readNonExistent() error {
	_, err := ioutil.ReadFile("/tmp/non_existent_file")
	// Add stack trace to existing error, no matter if it's nil.
	return tracerr.Wrap(err)
}
```

Find more executable examples in [examples](examples) dir.

## How to Use

### Import

```go
import "github.com/ztrue/tracerr"
```

### Create New Error

```go
err := tracerr.New("some error")
```

Or:

```go
err := tracerr.Errorf("some error %d", num)
```

### Add Stack Trace to Existing Error

> If `err` is `nil` then it still be `nil` with no stack trace added.

```go
err = tracerr.Wrap(err)
```

### Print Error and Stack Trace

> Stack trace will be printed only if `err` is of type `tracerr.Error`, otherwise just error text will be shown.

This will print error message and stack trace if any:

```go
tracerr.Print(err)
```

This will add source code:

```go
tracerr.PrintSource(err)
```

It's able to set up number of lines of code to display for each frame, which is `6` by default:

```go
tracerr.PrintSource(err, 9)
```

Or to set up number of lines before and after traced line:

```go
tracerr.PrintSource(err, 5, 2)
```

The same, but with color, which is much more useful:

```go
tracerr.PrintSourceColor(err)
```

```go
tracerr.PrintSourceColor(err, 9)
```

```go
tracerr.PrintSourceColor(err, 5, 2)
```

### Save Output to Variable

It's also able to save output to variable instead of printing it, which works the same way:

```go
text := tracerr.Sprint(err)
```

```go
text := tracerr.SprintSource(err)
```

```go
text := tracerr.SprintSource(err, 9)
```

```go
text := tracerr.SprintSource(err, 5, 2)
```

### Get Stack Trace

> Stack trace will be empty if `err` is not an instance of `tracerr.Error`.

```go
frames := tracerr.StackTrace(err)
```

Or if `err` is of type `tracerr.Error`:

```go
frames := err.StackTrace()
```

### Get Original Error

> Unwrapped error will be `nil` if `err` is `nil` and will be the same error if `err` is not an instance of `tracerr.Error`.

```go
err = tracerr.Unwrap(err)
```

Or if `err` is of type `tracerr.Error`:

```go
err = err.Unwrap()
```

## Performance

Benchmarks for creating a new error with a stack trace of different depth:

```
GOMAXPROCS=1 go test -bench=. -benchmem
goos: linux
goarch: amd64
pkg: github.com/ztrue/tracerr
cpu: Intel(R) Core(TM) i7-14700KF
BenchmarkNew/5           4500129               267.1 ns/op           256 B/op          4 allocs/op
BenchmarkNew/10          3325456               359.5 ns/op           256 B/op          4 allocs/op
BenchmarkNew/20          1000000              1001 ns/op             576 B/op          5 allocs/op
BenchmarkNew/40           538689              2171 ns/op            1216 B/op          6 allocs/op
PASS
ok      github.com/ztrue/tracerr        5.246s
```


tracerr

Drop-in replacement for builtin Go errors. This is a minimal error handling package with custom error types, user friendly messages, Unwrap & Is. With very easy to use and straightforward helper functions

<p align="center"><img src="https://user-images.githubusercontent.com/1092882/87815217-d864a680-c882-11ea-9c94-24b67f7125fe.png" alt="errors gopher" width="256px"/></p>

[![](https://github.com/naughtygopher/errors/actions/workflows/go.yml/badge.svg?branch=master)](https://github.com/naughtygopher/errors/actions)
[![Go Reference](https://pkg.go.dev/badge/github.com/naughtygopher/errors.svg)](https://pkg.go.dev/github.com/naughtygopher/errors)
[![Go Report Card](https://goreportcard.com/badge/github.com/naughtygopher/errors?cache_updated=2025-07-04)](https://goreportcard.com/report/github.com/naughtygopher/errors)
[![Coverage Status](https://coveralls.io/repos/github/naughtygopher/errors/badge.svg?branch=master&cache_updated=2025-07-04)](https://coveralls.io/github/naughtygopher/errors?branch=master)
[![](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#error-handling)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/creativecreature/sturdyc/blob/master/LICENSE)

# Errors v1.3.1

Errors package is a drop-in replacement of the built-in Go errors package. It lets you create errors of 14 different types,
which should handle most of the use cases. Some of them are a bit too specific for web applications, but useful nonetheless.

Features of this package:

1. Multiple (14) error types
2. Easy handling of User friendly message(s)
3. Stacktrace - formatted, unfromatted, custom format (refer tests in errors_test.go)
4. Retrieve the Program Counters for the stacktrace
5. Retrieve runtime.Frames using `errors.RuntimeFrames(err error)` for the stacktrace
6. HTTP status code and user friendly message (wrapped messages are concatenated) for all error types
7. GRPC status code and user friendly message (wrapped messages are concatenated) for all error types
8. Helper functions to generate each error type
9. Helper function to get error Type, error type as int, check if error type is wrapped anywhere in chain
10. . `fmt.Formatter` support

In case of nested errors, the messages & errors are also looped through the full chain of errors.

### Available error types

1. TypeInternal - For internal system error. e.g. Database errors
2. TypeValidation - For validation error. e.g. invalid email address
3. TypeInputBody - For invalid input data. e.g. invalid JSON
4. TypeDuplicate - For duplicate content error. e.g. user with email already exists (when trying to register a new user)
5. TypeUnauthenticated - For not authenticated error
6. TypeUnauthorized - For unauthorized access error
7. TypeEmpty - For when an expected non-empty resource, is empty
8. TypeNotFound - For expected resource not found. e.g. user ID not found
9. TypeMaximumAttempts - For attempting the same action more than an allowed threshold
10. TypeSubscriptionExpired - For when a user's 'paid' account has expired
11. TypeDownstreamDependencyTimedout - For when a request to a downstream dependent service times out
12. TypeNotImplemented - For when the requested function cannot be fullfilled because of incapability
13. TypeContextTimedout - For when the Go context has timed out
14. TypeContextCancelled - For when the Go context has been cancelled

Helper functions are available for all the error types. Each of them have 3 helper functions, one which accepts only a string,
another which accepts an original error as well as a user friendly message, and one which accepts format string along with arguments.

All the dedicated error type functions are documented [here](https://pkg.go.dev/github.com/naughtygopher/errors?tab=doc#DownstreamDependencyTimedout).
Names are consistent with the error type, e.g. errors.Internal(string) and errors.InternalErr(error, string)

### User friendly messages

More often than not when writing APIs, we'd want to respond with an easier to undersand user friendly message.
Instead of returning the raw error, just log the raw error.

There are helper functions for all the error types. When in need of setting a friendly message for an existing error, there
are helper functions with the _suffix_ **'Err'**. All such helper functions accept the original error and a string.

```golang
package main

import (
	"fmt"

	"github.com/naughtygopher/errors"
)

func Bar() error {
	return fmt.Errorf("hello %s", "world!")
}

func Foo() error {
	err := Bar()
	if err != nil {
		return errors.InternalErr(err, "bar is not happy")
	}
	return nil
}

func main() {
	err := Foo()

	fmt.Println("err:", err)
	fmt.Println("\nerr.Error():", err.Error())

	fmt.Printf("\nformatted +v: %+v\n", err)
	fmt.Printf("\nformatted v: %v\n", err)
	fmt.Printf("\nformatted +s: %+s\n", err)
	fmt.Printf("\nformatted s: %s\n", err)

	_, msg, _ := errors.HTTPStatusCodeMessage(err)
	fmt.Println("\nmsg:", msg)
}
```

Output

```
err: bar is not happy

err.Error(): /Users/k.balakumaran/go/src/github.com/naughtygopher/errors/cmd/main.go:16: bar is not happy
hello world!bar is not happy

formatted +v: /Users/k.balakumaran/go/src/github.com/naughtygopher/errors/cmd/main.go:16: bar is not happy
hello world!bar is not happy

formatted v: bar is not happy

formatted +s: bar is not happy: hello world!

formatted s: bar is not happy

msg: bar is not happy
```

[Playground link](https://go.dev/play/p/OiLegJ9Xxc9)

### File & line number prefixed to errors

A common annoyance with Go errors which most people are aware of is, figuring out the origin of the error, especially when there are nested function calls.
Annotations help a lot by being able to provide contextual message to errors. e.g. `fmt.Errorf("database query returned error %w", err)`.
However in this package, the `Error() string` function (Go error interface method), prints the error prefixed by the filepath and line number. It'd look like `../Users/JohnDoe/apps/main.go:50 hello world` where 'hello world' is the error message.

### HTTP/GRPC status code & message

The functions `errors.HTTPStatusCodeMessage(error) (int, string, bool), errors.GRPCStatusCodeMessage(error) (int, string, bool)` returns the HTTP/GRPC status code, message, and a boolean value. The boolean is true, if the error is of type \*Error from this package. If error is nested, it unwraps and returns a single concatenated message. Sample described in the 'How to use?' section.

## How to use?

Other than the functions explained earlier in the _**User friendly messages**_ section, more examples are provided below.

```golang
package main

import (
	"fmt"
	"net/http"
	"time"

	"github.com/naughtygopher/errors"
	"github.com/naughtygopher/webgo/v6"
	"github.com/naughtygopher/webgo/v6/middleware/accesslog"
)

func bar() error {
	return fmt.Errorf("%s %s", "sinking", "bar")
}

func bar2() error {
	err := bar()
	if err != nil {
		return errors.InternalErr(err, "bar2 was deceived by bar1 :(")
	}
	return nil
}

func foo() error {
	err := bar2()
	if err != nil {
		return errors.InternalErr(err, "we lost bar2!")
	}
	return nil
}

func handler(w http.ResponseWriter, r *http.Request) {
	err := foo()
	if err != nil {
		// log the error on your server for troubleshooting
		fmt.Println(err.Error())
		// respond to request with friendly msg
		status, msg, _ := errors.HTTPStatusCodeMessage(err)
		webgo.SendError(w, msg, status)
		return
	}

	webgo.R200(w, "yay!")
}

func routes() []*webgo.Route {
	return []*webgo.Route{
		{
			Name:    "home",
			Method:  http.MethodGet,
			Pattern: "/",
			Handlers: []http.HandlerFunc{
				handler,
			},
		},
	}
}

func main() {
	router := webgo.NewRouter(&webgo.Config{
		Host:         "",
		Port:         "8080",
		ReadTimeout:  15 * time.Second,
		WriteTimeout: 60 * time.Second,
	}, routes()...)

	router.UseOnSpecialHandlers(accesslog.AccessLog)
	router.Use(accesslog.AccessLog)
	router.Start()
}
```

[webgo](https://github.com/naughtygopher/webgo) was used to illustrate the usage of the function, `errors.HTTPStatusCodeMessage`. It returns the appropriate http status code, user friendly message stored within, and a boolean value. Boolean value is `true` if the returned error of type \*Error.
Since we get the status code and message separately, when using any web framework, you can set values according to the respective framework's native functions. In case of Webgo, it wraps errors in a struct of its own. Otherwise, you could directly respond to the HTTP request by calling `errors.WriteHTTP(error,http.ResponseWriter)`.

Once the app is running, you can check the response by opening `http://localhost:8080` on your browser. Or on terminal

```bash
$ curl http://localhost:8080
{"errors":"we lost bar2!. bar2 was deceived by bar1 :(","status":500} // output
```

And the `fmt.Println(err.Error())` generated output on stdout would be:

```bash
/Users/username/go/src/errorscheck/main.go:28 /Users/username/go/src/errorscheck/main.go:20 sinking bar
```

## Benchmark [2025-07-03]

Macbook Air 13-inch, M3, 2024, Memory: 24 GB

```bash
$ go version
go version go1.24.4 darwin/arm64

$ go test -benchmem -bench .
goos: darwin
goarch: arm64
pkg: github.com/naughtygopher/errors
cpu: Apple M3
Benchmark_Internal-8                            	 3650916	       321.7 ns/op	    1104 B/op	       2 allocs/op
Benchmark_Internalf-8                           	 3155463	       378.9 ns/op	    1128 B/op	       3 allocs/op
Benchmark_InternalErr-8                         	 3866085	       312.2 ns/op	    1104 B/op	       2 allocs/op
Benchmark_InternalGetError-8                    	 1983544	       608.0 ns/op	    1576 B/op	       6 allocs/op
Benchmark_InternalGetErrorWithNestedError-8     	 2419369	       497.8 ns/op	    1592 B/op	       6 allocs/op
Benchmark_InternalGetMessage-8                  	 3815074	       316.1 ns/op	    1104 B/op	       2 allocs/op
Benchmark_InternalGetMessageWithNestedError-8   	 3470449	       342.2 ns/op	    1128 B/op	       3 allocs/op
Benchmark_HTTPStatusCodeMessage-8               	40540940	        29.12 ns/op	      16 B/op	       1 allocs/op
BenchmarkHasType-8                              	100000000	        11.44 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	github.com/naughtygopher/errors	13.805s
```

## Contributing

More error types, customization, features, multi-errors; PRs & issues are welcome!

## The gopher

The gopher used here was created using [Gopherize.me](https://gopherize.me/). Show some love to Go errors like our gopher lady here!


A feature rich error package with stack traces, composition of errors and more

[![Github Actions Build Status](https://github.com/joomcode/errorx/workflows/CI/badge.svg)](https://github.com/joomcode/errorx/actions)
[![GoDoc](https://img.shields.io/static/v1?label=godev&message=reference&color=00add8)](https://pkg.go.dev/github.com/joomcode/errorx?tab=doc)
[![Report Card](https://goreportcard.com/badge/github.com/joomcode/errorx)](https://goreportcard.com/report/github.com/joomcode/errorx)
[![gocover.io](https://gocover.io/_badge/github.com/joomcode/errorx)](https://gocover.io/github.com/joomcode/errorx)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#error-handling)

## Highlights

The *errorx* library provides error implementation and error-related utilities. 
Library features include (but are not limited to):
* Stack traces 
* Composability of errors
* Means to enhance error both with stack trace and with message
* Robust type and trait checks

## Introduction

Conventional approach towards errors in *Go* is quite limited.

The typical case implies an error being created at some point:
```go
return errors.New("now this is unfortunate")
```

Then being passed along with a no-brainer:
```go
if err != nil {
  return err
}
```

And, finally, handled by printing it to the log file:
```go
log.Printf("Error: %s", err)
```

It doesn't take long to find out that quite often this is not enough. There's little fun in solving the issue when everything a developer is able to observe is a line in the log that looks like one of those:
> Error: EOF

> Error: unexpected '>' at the beginning of value

> Error: wrong argument value

An *errorx* library makes an approach to create a toolset that would help remedy this issue with these considerations in mind:
* No extra care should be required for an error to have all the necessary debug information; it is the opposite that may constitute a special case
* There must be a way to distinguish one kind of error from another, as they may imply or require a different handling in user code
* Errors must be composable, and patterns like ```if err == io.EOF``` defeat that purpose, so they should be avoided
* Some context information may be added to the error along the way, and there must be a way to do so without altering the semantics of the error
* It must be easy to create an error, add some context to it, check for it
* A kind of error that requires a special treatment by the caller *is* a part of a public API; an excessive amount of such kinds is a code smell

As a result, the goal of the library is to provide a brief, expressive syntax for a conventional error handling and to discourage usage patterns that bring more harm than they're worth.

Error-related, negative codepath is typically less well tested, though of, and may confuse the reader more than its positive counterpart. Therefore, an error system could do well without too much of a flexibility and unpredictability.

# errorx

With *errorx*, the pattern above looks like this:

```go
return errorx.IllegalState.New("unfortunate")
```
```go
if err != nil {
  return errorx.Decorate(err, "this could be so much better")
}
```
```go
log.Printf("Error: %+v", err)
```

An error message will look something like this:

```
Error: this could be so much better, cause: common.illegal_state: unfortunate
 at main.culprit()
	main.go:21
 at main.innocent()
	main.go:16
 at main.main()
	main.go:11
  ```

Now we have some context to our little problem, as well as a full stack trace of the original cause - which is, in effect, all that you really need, most of the time. ```errorx.Decorate``` is handy to add some info which a stack trace does not already hold: an id of the relevant entity, a portion of the failed request, etc. In all other cases, the good old ```if err != nil {return err}``` still works for you.

And this, frankly, may be quite enough. With a set of standard error types provided with *errorx* and a syntax to create your own (note that a name of the type is a good way to express its semantics), the best way to deal with errors is in an opaque manner: create them, add information and log as some point. Whenever this is sufficient, don't go any further. The simpler, the better.

## Error check

If an error requires special treatment, it may be done like this:
```go
// MyError = MyErrors.NewType("my_error")
if errorx.IsOfType(err, MyError) {
  // handle
}
```

Note that it is never a good idea to inspect a message of an error. Type check, on the other hand, is sometimes OK, especially if this technique is used inside of a package rather than forced upon API users.

An alternative is a mechanisms called **traits**:
```go
// the first parameter is a name of new error type, the second is a reference to existing trait
TimeoutElapsed       = MyErrors.NewType("timeout", errorx.Timeout())
```

Here, ```TimeoutElapsed``` error type is created with a Timeout() trait, and errors may be checked against it:
```go
if errorx.HasTrait(err, errorx.Timeout()) {
  // handle
}
```

Note that here a check is made against a trait, not a type, so any type with the same trait would pass it. Type check is more restricted this way and creates tighter dependency if used outside of an originating package. It allows for some little flexibility, though: via a subtype feature a broader type check can be made.

## Wrap

The example above introduced ```errorx.Decorate()```, a syntax used to add message as an error is passed along. This mechanism is highly non-intrusive: any properties an original error possessed, a result of a  ```Decorate()``` will possess, too.

Sometimes, though, it is not the desired effect. A possibility to make a type check is a double edged one, and should be restricted as often as it is allowed. The bad way to do so would be to create a new error and to pass an ```Error()``` output as a message. Among other possible issues, this would either lose or duplicate the stack trace information.

A better alternative is:
```go
return MyError.Wrap(err, "fail")
```

With ```Wrap()```, an original error is fully retained for the log, but hidden from type checks by the caller.

See ```WrapMany()``` and ```DecorateMany()``` for more sophisticated cases.

## Stack traces

As an essential part of debug information, stack traces are included in all *errorx* errors by default.

When an error is passed along, the original stack trace is simply retained, as this typically takes place along the lines of the same frames that were originally captured. When an error is received from another goroutine, use this to add frames that would otherwise be missing:

```go
return errorx.EnhanceStackTrace(<-errorChan, "task failed")
```

Result would look like this:
```
Error: task failed, cause: common.illegal_state: unfortunate
 at main.proxy()
	main.go:17
 at main.main()
	main.go:11
 ----------------------------------
 at main.culprit()
	main.go:26
 at main.innocent()
	main.go:21
  ```

On the other hand, some errors do not require a stack trace. Some may be used as a control flow mark, other are known to be benign. Stack trace could be omitted by not using the ```%+v``` formatting, but the better alternative is to modify the error type:

```go
ErrInvalidToken    = AuthErrors.NewType("invalid_token").ApplyModifiers(errorx.TypeModifierOmitStackTrace)
```

This way, a receiver of an error always treats it the same way, and it is the producer who modifies the behaviour. Following, again, the principle of opacity.

Other relevant tools include ```EnsureStackTrace(err)``` to provide an error of unknown nature with a stack trace, if it lacks one.

### Stack traces benchmark

As performance is obviously an issue, some measurements are in order. The benchmark is provided with the library. In all of benchmark cases, a very simple code is called that does nothing but grows a number of frames and immediately returns an error.

Result sample, MacBook Pro Intel Core i7-6920HQ CPU @ 2.90GHz 4 core:

name | runs | ns/op | note
------ | ------: | ------: | ------
BenchmarkSimpleError10                    | 20000000 |     57.2 | simple error, 10 frames deep
BenchmarkErrorxError10                    | 10000000 |      138 | same with errorx error
BenchmarkStackTraceErrorxError10          |  1000000 |     1601 | same with collected stack trace
BenchmarkSimpleError100                   |  3000000 |      421 | simple error, 100 frames deep
BenchmarkErrorxError100                   |  3000000 |      507 | same with errorx error
BenchmarkStackTraceErrorxError100         |   300000 |     4450 | same with collected stack trace
BenchmarkStackTraceNaiveError100-8         	   | 2000 |	    588135 | same with naive debug.Stack() error implementation
BenchmarkSimpleErrorPrint100              |  2000000 |      617 | simple error, 100 frames deep, format output
BenchmarkErrorxErrorPrint100              |  2000000 |      935 | same with errorx error
BenchmarkStackTraceErrorxErrorPrint100    |    30000 |    58965 | same with collected stack trace
BenchmarkStackTraceNaiveErrorPrint100-8    	   | 2000 |	    599155 | same with naive debug.Stack() error implementation

Key takeaways:
 * With deep enough call stack, trace capture brings **10x slowdown**
 * This is an absolute **worst case measurement, no-op function**; in a real life, much more time is spent doing actual work
 * Then again, in real life code invocation does not always result in error, so the overhead is proportional to the % of error returns
 * Still, it pays to omit stack trace collection when it would be of no use
 * It is actually **much more expensive to format** an error with a stack trace than to create it, roughly **another 10x**
 * Compared to the most naive approach to stack trace collection, error creation it is **100x** cheaper with errorx
 * Therefore, it is totally OK to create an error with a stack trace that would then be handled and not printed to log
 * Realistically, stack trace overhead is only painful either if a code is very hot (called a lot and returns errors often) or if an error is used as a control flow mechanism and does not constitute an actual problem; in both cases, stack trace should be omitted

## More

See [godoc](https://godoc.org/github.com/joomcode/errorx) for other *errorx* features:
* Namespaces
* Type switches
* ```errorx.Ignore```
* Trait inheritance
* Dynamic properties
* Panic-related utils
* Type registry
* etc.


errorx

A library to create your custom error builders producing structured errors with metadata from different sources and optional stacktraces

# MetaErr

[![GoDoc](https://pkg.go.dev/badge/github.com/quantumcycle/metaerr)](https://pkg.go.dev/github.com/quantumcycle/metaerr?tab=doc)
[![Go Report Card](https://goreportcard.com/badge/github.com/quantumcycle/metaerr)](https://goreportcard.com/report/github.com/quantumcycle/metaerr)
[![codecov](https://codecov.io/gh/quantumcycle/metaerr/graph/badge.svg?token=3EFILQUGE9)](https://codecov.io/gh/quantumcycle/metaerr)

Metaerr is a golang package to create or wrap errors with custom metadata and location.

This library requires Golang 1.21+.

## Why

I used github.com/pkg/errors before, and the stack traces were extensive (like Java) and not very useful. Then, I came across the [Fault library](https://github.com/Southclaws/fault), which was amazing, but the way I wanted to use it clashed with some of the opinions embedded in the library.
There is also [samber oops library](https://github.com/samber/oops), but the problem was that it's not extendable to have custom metadata.

This is why I decided to create this simple library. It utilizes the same "stack trace" model as Fault, in the sense that you will see the stack pertaining to the locations of error creation, but also adds regular stacktraces on top of that as an option.

The next feature it offers is the ability to add any number of key-value metadata entries to each error, including wrapped errors. This is useful if you want to attach metadata at the time of error creation and then leverage that metadata during resolution. A common use case is having a generic HTTP error handler for an API that can use the metadata to determine the HTTP status or construct an error payload to send to the user. Another use case would be logging and alerting. If you convert the metadata into fields in a JSON logger, you could have different alerting rules for logged ERRORS based on the metadata; for example, errors with the metadata tag containing "security" could trigger an immediate alert.

## Install

```
go get -u github.com/quantumcycle/metaerr
```

## Usage

Metaerr can be used with the Go standard errors package, and they are also compatible with error wrapping introduced in Go 1.13.

There is 2 ways to use the library. Using the errors directly, or using the builder. **The builder approach is recommended.**

### using the errors directly

To create an new MetaErr from a string, use

```golang
err := metaerr.New("failure")
```

To create a new MetaErr by wrapping an existing error, use

```golang
err := metaerr.Wrap(err, "failure")
```

The if you want to add metadata, you first create the metadata, and pass it as an option.

```golang
//Create an metadata called ErrorCode
var ErrorCode = metaerr.StringMeta("error_code")

func main() {
	rootCause := metaerr.New("failure", metaerr.WithMeta(ErrorCode("x01"))
	err := metaerr.Wrap(rootCause, "cannot fetch content")
	fmt.Printf("%+v", err)
}
```
will print
```
cannot fetch content
        at .../quantumcycle/metaerr/cmd/main.go:12
failure [error_code=x01]
        at .../quantumcycle/metaerr/cmd/main.go:11

```

### using the builder

Using the errors directly is ok, but it's a bit verbose just to create errors. Using the builder is a better approach 
and reduce boilerplate.

To use the builder, just create an instance of the builder with the relevant options for you, and then use it.
```golang
package main

import (
	"fmt"
	"github.com/quantumcycle/metaerr"
)

var errors = metaerr.NewBuilder(metaerr.WithStackTrace(0, 2))
var ErrorCode = metaerr.StringMeta("error_code")

func main() {
	err := errors.Meta(ErrorCode("test")).Newf("failure with user %s", "test")
	fmt.Printf("%+v\n", err)
}
```

### creating your own customized builder

The builder this library provides can be use as a standalone builder, but you should consider creating your own builder
by decorating the provided builder. The reason is that it's still very verbose to pass each instance of the metadata
when creating an error.

Look at [this file](./example/errors/builder.go) for an example of a builder with 2 possible metadata (errorCode and 
tags), and [this file](./example/main.go) as an example of using this builder.

The builder is immutable/thread safe, so you can have a base builder and then call `.Context(ctx)` on it without impacting the
rest of your code using the same builder. It does share the same metadata slice though, but there is no way to modify
the slice after creation, so it's safe.

### Getting the err message, location, and metadata

In the example above, we use the Printf formatting to display the error, metadata and location all in one gulp. 
You can however use the provided helper function to get the individual parts

```golang
err := metaerr.New("failure")
err.Error() //returns failure
merr := metaerr.AsMetaErr(err)
merr.Location() //returns .../mysource/mypackage/file.go:22

// will print error_code:x01
meta := metaerr.GetMeta(err, false)
for k, values := range meta {
  for _, val := range values {
    fmt.Println(k + ":" + val)
  }
}

```

### Options

You can provide options to modify the errors during creation. 

#### WithMeta

This is the main option you would be using. It allows you to add metadata to the error. You can add as many metadata as you want.
The library propose 4 built-in metadata builders:
- StringMeta: to add a string metadata
- StringsMeta: to add a slice of string metadata
- StringerMeta: to add any type that implements the Stringer interface as metadata
- StringMetaFromContext: to add a string metadata from a context (see `WithContext` below)

#### WithLocationSkip
By default, when creating an error, Metaerr will skip all stack frames related to metaerr to determine the error's creation location. 
This works well when you call Metaerr directly at the place where the error is created in your codebase. However, there is a use case 
where you use a factory, or your own builder to create errors. In this case, if you use the standard `metaerr.New` function, the reported 
location will be the line where metaerr is called to create the error, which may be within your error factory or builder function. 
You probably don't want to have all your locations pointing to the same line. To address this, you can use the `metaerr.WithLocationSkip` 
option to add additional call stack skips to determine the location. Here is an example:

```golang
package main

import (
	"fmt"

	"github.com/quantumcycle/metaerr"
)

var Tag = metaerr.StringMeta("tag")

func CreateDatabaseError(reason string) error {
	return metaerr.New(reason, metaerr.WithLocationSkip(1), metaerr.WithMeta(Tag("database")))
}

func main() {
	dbErr := CreateDatabaseError("no such table [User]")
	fmt.Printf("%+v", dbErr)
}

```

which will output

```
no such table [User] [tag=database]
        at .../github.com/quantumcycle/metaerr/cmd/main.go:16
```

Without the `WithLocationSkip` option, the reported location would be line 12, inside the `CreateDatabaseError` function. 
Having all our errors pointing to this specific line would ne useless.

#### WithStacktrace

Usually the error creation location is enough to get by and find the context during which the error was created, but if 
the error is created in some central location called from multiple places, it might be useful to have a stacktrace to be 
able to find the caller that led to the error creation.
For these cases, use `WithStacktrace`, either when creating the error or when wrapping an existing error. When doing so, 
it will print something like this
```
failure
	at .../github.com/quantumcycle/metaerr/errors_test.go:46   //<-- this is the error default location
    at .../github.com/quantumcycle/metaerr/errors_test.go:64   //<-- this is added by the WithStacktrace option
    at .../github.com/quantumcycle/metaerr/errors_test.go:297  //<-- this is added by the WithStacktrace option
```

#### WithContext

This option allows you to attach a context to the error. Then you can use `StringMetaFromContext` to retrieve data from
the context and set some metadata. This is useful if for example you have a user in your context and want to add user
information to each error.

The Best Go Libraries For Error Handling (18)

emperror

eris

errlog

errors

errors

errors

errors

Fault

go-multierror

oops

errors

exception

Falcon

multierr

tracerr

errors

errorx

metaerr