wrap

README

wrap

A small Go package for wrapping errors with extra context in an easy-to-read format.

Run go get hermannm.dev/wrap to add it to your project!

Rationale

Go's fmt.Errorf is a great way to provide context to errors before returning them. However, the common way of using fmt.Errorf("extra context: %w", err) can lead to long and hard-to-read error messages. See the following example, albeit a bit contrived:

failed to register user: user creation failed: invalid user data: invalid username: username exceeds 30 characters

This package's wrap.Error aims to alleviate this, by instead displaying wrapped errors like this:

failed to register user
- user creation failed
- invalid user data
- invalid username
- username exceeds 30 characters

The package also provides wrap.Errorf to use a format string for the wrapping message, and wrap.Errors to wrap multiple errors.

Usage

Basic usage:

err := errors.New("expired token")
wrapped := wrap.Error(err, "user authentication failed")
fmt.Println(wrapped)
// user authentication failed
// - expired token

Wrapped errors can be nested. Wrapping an already wrapped error adds it to the error list, as follows:

wrapped2 := wrap.Error(wrapped, "failed to update username")
fmt.Println(wrapped2)
// failed to update username
// - user authentication failed
// - expired token

wrap.Errorf can be used to create the wrapping message with a format string:

err := errors.New("username already taken")
wrapped := wrap.Errorf(err, "failed to create user with name '%s'", "hermannm")
fmt.Println(wrapped)
// failed to create user with name 'hermannm'
// - username already taken

...and wrap.Errors can be used to wrap multiple errors:

err1 := errors.New("username too long")
err2 := errors.New("invalid email")
wrapped := wrap.Errors("user creation failed", err1, err2)
fmt.Println(wrapped)
// user creation failed
// - username too long
// - invalid email

When combining wrap.Errors and wrap.Error, nested errors are indented as follows:

err1 := errors.New("username too long")
err2 := errors.New("invalid email")
inner := wrap.Errors("user creation failed", err1, err2)
outer := wrap.Error(inner, "failed to register new user")
fmt.Println(outer)
// failed to register new user
// - user creation failed
//   - username too long
//   - invalid email

Documentation

Overview

Package wrap provides utility functions to wrap errors with extra context in an easy-to-read format.

Index

• func Error(wrapped error, message string) error
• func Errorf(wrapped error, messageFormat string, formatArgs ...any) error
• func Errors(message string, wrapped ...error) error

Functions

func Error

func Error(wrapped error, message string) error

Error wraps the given error with a message for context.

The error is displayed on the following format:

err := errors.New("expired token")
wrapped := wrap.Error(err, "user authentication failed")
fmt.Println(wrapped)
// user authentication failed
// - expired token

Wrapped errors can be nested. Wrapping an already wrapped error adds it to the error list, as follows:

err := errors.New("expired token")
inner := wrap.Error(err, "user authentication failed")
outer := wrap.Error(inner, "failed to update username")
fmt.Println(outer)
// failed to update username
// - user authentication failed
// - expired token

The returned error implements the Unwrap method from the standard errors package, so it works with errors.Is and errors.As.

func Errorf

func Errorf(wrapped error, messageFormat string, formatArgs ...any) error

Errorf wraps the given error with a message for context. It forwards the given message format and args to fmt.Sprintf to construct the message.

Example:

err := errors.New("username already taken")
wrapped := wrap.Errorf(err, "failed to create user with name '%s'", "hermannm")
fmt.Println(wrapped)
// failed to create user with name 'hermannm'
// - username already taken

func Errors

func Errors(message string, wrapped ...error) error

Errors wraps the given errors with a message for context.

The error is displayed on the following format:

err1 := errors.New("username too long")
err2 := errors.New("invalid email")
wrapped := wrap.Errors("user creation failed", err1, err2)
fmt.Println(wrapped)
// user creation failed
// - username too long
// - invalid email

When combined with Error, nested wrapped errors are indented as follows:

err1 := errors.New("username too long")
err2 := errors.New("invalid email")
inner := wrap.Errors("user creation failed", err1, err2)
outer := wrap.Error(inner, "failed to register new user")
fmt.Println(outer)
// failed to register new user
// - user creation failed
//   - username too long
//   - invalid email

The returned error implements the Unwrap method from the standard errors package, so it works with errors.Is and errors.As.