errors

README

errors

nice replacement for pkg/errors

Fork of xerrors with explicit Wrap instead of %w with no stack trace.

go get github.com/peczenyj/errors

errors.Wrap(err, "message")

Why

• Using Wrap is the most explicit way to wrap errors
• Wrapping with fmt.Errorf("foo: %w", err) is implicit, redundant and error-prone
• Parsing "foo: %w" is implicit, redundant and slow
• The pkg/errors and xerrors are not maintainted
• The cockroachdb/errors is too big
• The errors has no Wrap
• The go-faster/errors demands call errors.DisableTrace or build tag noerrtrace to disable stack traces.

If you don't need stack traces, this is the right tool for you.

The motivation behind this package is: if you are using pkg/errors or go-faster/errors should be easier to swich to this package by just change the import (when you can't switch to the standard errors).

It means, if your code is already using method such as Wrap or Wrapf, they are available.

Same for WithMessage and WithMessagef (however, here it is just an alias to Wrap and Wrapf).

The useful function Into from go-faster/errors is also available.

Features

Feature	errors	pkg/errors	go-faster/errors	peczenyj/errors
error constructors (New, Errorf)	✔	✔	✔	✔
error causes (Cause / Unwrap)		✔	✔	✔
type safety (Into)			✔	✔
errors.As(), errors.Is()	✔	✔	✔	✔
support stack traces		✔	✔	no, by desing

|

Motivation

If your project wants to minimize external dependencies and does not need stack traces on every error or failure, this is a acceptable alternative.

When migrating from some github.com/<your favorite repository>/errors to the standard lib errors, we can see that our code rely on non-standard functions such as Wrap or Wrapf that demands more changes than just update the import.

However, helper function such as Wrap or Wrapf are useful, since it highlight the error and automatically ignores nil values.

It means we can choose between:

data, err := io.ReadAll(r)
if err != nil {
        return errors.Wrap(err, "read failed") // add context
}
...

And a more simple approach:

data, err := io.ReadAll(r)

return data, errors.Wrap(err, "read failed") // will return nil if err is nil

werrors

You can keep using standard errors and import the github.com/peczenyj/errors/werrors to have access to some extra functions such as Wrap, Wrapf, WithMessage, WithMessagef, Cause and Into.

It is a more minimalistic approach.

go get github.com/peczenyj/errors/werrors

werrors.Wrap(err, "message")

Documentation

Index

• Variables
• func As(err error, target any) bool
• func Cause(err error) error
• func Errorf(format string, args ...any) error
• func Into[T error](err error) (val T, ok bool)
• func Is(err, target error) bool
• func Join(errs ...error) error
• func New(text string) error
• func Unwrap(err error) error
• func WithMessage(err error, message string) error
• func WithMessagef(err error, format string, args ...any) error
• func Wrap(err error, message string) error
• func Wrapf(err error, format string, args ...any) error

Examples

• Cause
• Into
• New
• WithMessage
• Wrap

Variables

var ErrUnsupported = errors.ErrUnsupported

ErrUnsupported indicates that a requested operation cannot be performed, because it is unsupported. requires minimum go 1.21.

Functions

func As

func As(err error, target any) bool

As finds the first error in err's tree that matches target, and if one is found, sets target to that error value and returns true. Otherwise, it returns false.

func Cause

func Cause(err error) error

Cause returns the underlying cause of the error, if possible. An error value has a cause if it implements the following interface:

type causer interface {
       Cause() error
}

If the error does not implement Cause, we will call Unwrap in a loop until find the original error. If the error is nil, nil will be returned without further investigation.

Example

package main

import (
	"fmt"

	"github.com/peczenyj/errors"
)

func fn() error {
	e1 := errors.New("error")
	e2 := errors.Wrap(e1, "inner")
	e3 := errors.Wrap(e2, "middle")

	return errors.Wrap(e3, "outer")
}

func main() {
	err := fn()
	fmt.Println(err)
	fmt.Println(errors.Cause(err))

}

Output:

outer: middle: inner: error
error

func Errorf

func Errorf(format string, args ...any) error

Errorf formats according to a format specifier and returns the string as a value that satisfies error.

func Into

func Into[T error](err error) (val T, ok bool)

Into finds the first error in err's chain that matches target type T, and if so, returns it.

Into is type-safe alternative to As.

this function was ported from https://github.com/go-faster/errors

Example

package main

import (
	"fmt"

	"github.com/peczenyj/errors"
)

type timeoutError struct {
	err error
}

func (te *timeoutError) Error() string {
	return "timeout: " + te.err.Error()
}

func (te *timeoutError) Timeout() bool {
	return true
}

type TimeoutError interface {
	Timeout() bool
	error
}

func main() {
	err := errors.New("ops")
	err = &timeoutError{err}
	err = errors.Wrap(err, "unexpected")

	if terr, ok := errors.Into[TimeoutError](err); ok {
		fmt.Println(terr)
	}

}

Output:

timeout: ops

func Is

func Is(err, target error) bool

Is reports whether any error in err's tree matches target.

func Join

func Join(errs ...error) error

Join returns an error that wraps the given errors. requires minimum go 1.20.

func New

func New(text string) error

New returns an error that formats as the given text.

Example

package main

import (
	"fmt"

	"github.com/peczenyj/errors"
)

func main() {
	err := errors.New("whoops")
	fmt.Println(err)

}

Output:

whoops

func Unwrap

func Unwrap(err error) error

Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.

func WithMessage

func WithMessage(err error, message string) error

WithMessage is an alias to Wrap.

Example

package main

import (
	"fmt"

	"github.com/peczenyj/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.WithMessage(cause, "oh noes")
	fmt.Println(err)

}

Output:

oh noes: whoops

func WithMessagef

func WithMessagef(err error, format string, args ...any) error

WithMessagef is an alias to Wrapf.

func Wrap

func Wrap(err error, message string) error

Wrap returns an error annotating err, it is the equivalent to

fmt.Errorf("%s: %w", message, err)

If err is nil, Wrap returns nil.

Example

package main

import (
	"fmt"

	"github.com/peczenyj/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.Wrap(cause, "oh noes")
	fmt.Println(err)

}

Output:

oh noes: whoops

func Wrapf

func Wrapf(err error, format string, args ...any) error

Wrapf returns an formatted error annotating err, it is the equivalent to

message := fmt.Sprintf(format, args...)
fmt.Errorf("%s: %w", message, err)

If err is nil, Wrapf returns nil.