errutil

Documentation

Overview

Package errutil implements some useful extensions to the stdlib Go errors package, in the same spirit of packages like ioutil/httputil.

Utilities include:

- An error type that makes it easy to work with const error sentinels. - An easy way to wrap a list of errors together. - An easy way to reduce a list of errors.

Flexible enough that you can do your own wrapping/merging logic but in a functional/simple way.

Index

• func Chain(errs ...error) error
• func Reduce(r Reducer, errs ...error) error
• type Error
  • func (e Error) Error() string
• type Reducer

Examples

• Chain
• Error
• Reduce

Functions

func Chain

func Chain(errs ...error) error

Chain creates a chain of errors suitable to be used with Go's Unwrap interface through functions like errors.Is and errors.As. Chaining order will be the same as the order of the arguments, the first error is the head wrapping up the next one, and so goes on.

An empty list of errors will return a nil error.

Example

package main

import (
	"errors"
	"fmt"

	"codeberg.org/madlambda/spells/errutil"
)

func main() {
	// Declare your error sentinels using errutil.Error
	const (
		layer1Err errutil.Error = "layer1Err"
		layer2Err errutil.Error = "layer2Err"
		layer3Err errutil.Error = "layer3Err"
	)

	// Chain the errors
	err := errutil.Chain(layer1Err, layer2Err, layer3Err)

	// Checking programmatically for the underlying error
	// Users of your API handle the sentinels opaquely
	fmt.Println(errors.Is(err, layer1Err))
	fmt.Println(errors.Is(err, layer2Err))
	fmt.Println(errors.Is(err, layer3Err))
	fmt.Println(err)

}

Output:
true
true
true
layer1Err: layer2Err: layer3Err

func Reduce

func Reduce(r Reducer, errs ...error) error

Reduce will reduce all errors to a single one using the provided reduce function.

If errs is empty it returns nil, if errs has a single err (len(errs) == 1) it will return the err itself.

Nil errors on the errs args will be filtered out initially, before reducing, so you can expect errors passed to the reducer to be always non-nil.

But if the reducer function itself returns nil, then the returned nil won't be filtered and will be passed as an argument on the next reducing step.

Example

package main

import (
	"fmt"

	"codeberg.org/madlambda/spells/errutil"
)

func main() {
	// call multiple functions that may return an error
	// but none of them should interrupt overall computation
	var i int
	someFunc := func() error {
		i++
		return fmt.Errorf("error %d", i)
	}

	var errs []error

	errs = append(errs, someFunc())
	errs = append(errs, someFunc())
	errs = append(errs, someFunc())

	err := errutil.Reduce(func(err1, err2 error) error {
		return fmt.Errorf("%v,%v", err1, err2)
	}, errs...)

	fmt.Println(err)

}

Output:
error 1,error 2,error 3

Types

type Error

type Error string

Error implements the Go's error interface in the simplest way possible, allowing initialization error sentinels to be done at compile time as constants. It does so by using a string as it's base type.

Example

package main

import (
	"errors"
	"fmt"

	"codeberg.org/madlambda/spells/errutil"
)

func main() {
	// Declare your error sentinels using errutil.Error
	const (
		someError errutil.Error = "someError"
	)

	// You add some context to the sentinel error
	wrappedErr := fmt.Errorf("wrapping up: %w", someError)

	// Checking programmatically for the underlying error
	// Users of your API handle the sentinel opaquely
	fmt.Println(errors.Is(wrappedErr, someError))

}

Output:
true

func (Error) Error

func (e Error) Error() string

Error return a string representation of the error.

type Reducer

type Reducer func(error, error) error

Reducer reduces 2 errors into one