docs.go

package wraperrors

/*
wraperrors provides a simple interface to work with wrap errors. A wrap error has two errors:
- A wrapper error
- A wrapped error

The wrapper error is suposed to be generated by a higher level part of the code and provide more general information,
whereas the wrapped error is supposed to have more specific details about the actual error.

You can create a new wrap error:

```go
wrappedErr := errors.New("unexpected character '/'")
wrapperErr := errors.New("bad request")
wrapErr := wraperrors.New(wrapperErr, wrappedErr)
```

The package also provides a SimpleError type which is useful to create wrap errors that will have the simple error as
the wrapper.

The main difference between wraperrors and standard wrap errors (`fmt.Errorf("something went wrong: %w", err1)`)
is that wraperrors allow to compare the wrapper error regardless of the wrapped error(s):

```go
// package xxx
func GetSomethingFromTheInternet() ([]byte, error) { ... }

// package yyy
const (
	BadRequestError = wraperrors.SimpleError("bad request error")
	ConnectionError = wraperrors.SimpleError("temporal error, try later")
	InternalError   = wraperrors.SimpleError("internal error")
)

// F processes some stuff from the internet. It can return three possible wrap errors
func F() error {
	sth, err := xxx.GetSomethingFromTheInternet()
	if errors.Is(err, xxx.ConnectionTimeOut) {
		return ConnectionError.Wrap(err)
	} else if errors.Is(err, xxx.UnexpectedCharacter) || errors.Is(err, xxx.MissingArguments) {
		return BadRequestError.Wrap(err)
	} else if err != nil {
		return InternalError.Wrap(err)
	}

	// do something with sth

	return nil
}

// package zzz
func G() {
	err := yyy.F()
	if errors.Is(err, ConnectionError) {
		// retry after timeout
	} else if errors.Is(err, BadRequestError) {
		// logic for bad request
	} else {
		// logic for internal error
	}
}
```
*/