README.md

vice

Standard bad behaviours for Go error values

Introduction

Introduction | Examples | Usage | Contributing

🚧 Disclaimer: vice is alpha quality software. The API may change without warning between revisions. 🚧

vice provides bad behaviours for the new Go 2/1.13+ error values.

Examples

Introduction | Examples | Usage | Contributing

Create an error that implements NotFound() bool:

vice.New(vice.NotFound, "user not found")

Wrap an existing error, and add Timeout() bool:

vice.Wrap(err, vice.Timeout, "request timed out")

For complete examples and usage, see the GoDoc documentation.

Usage

Introduction | Examples | Usage | Contributing

vice defines common types of errors, as seen in existing packages, as expressed through methods on the errors of the form:

BehaviourName() bool // returns true

Errors of these types can be created and checked by vice. When used with Go 2 error value wrapping, intermediate code layers don't have to know about the behaviours or types of errors, and may add additional information, without altering how the error is handled in the topmost layer:

// Create an error when your database can't find a user record
err := vice.New(vice.NotFound, "user not found")

// many intermediate layers of code, passing the error on, and wrapping it
// ...

// In your central request handler middleware
if vice.Is(err, vice.NotFound) {
	// respond appropriately to the client
}

Building APIs on vice

vice/skip implements the vice API with an additional skip argument, allowing creation of APIs on top of vice that will not report themselves in error caller frames.

Contributing

Introduction | Examples | Usage | Contributing

I would love your help!

vice is still a work in progress. You can help by:

• Opening a pull request to resolve an open issue.
• Adding a feature or enhancement of your own! If it might be big, please open an issue first so we can discuss it.
• Improving this README or adding other documentation to vice.
• Letting me know if you're using vice.