core

Go module with set of core packages every Go project needs. Minimal API, battle-tested, strictly versioned and with only two transient dependencies-- davecgh/go-spew and google/go-cmp.

Maintained by experienced Go developers, including author of the Efficient Go book.

Import it using go get github.com/efficientgo/core@latest.

This module contains packages around the following functionalities:

NOTE: Click on each package to see usage examples in pkg.go.dev!

Error Handling

• github.com/efficientgo/core/errors is an improved and minimal version of the popular pkg/errors package (archived) allowing reliable wrapping of errors with stacktrace. Unfortunately, the standard library recommended error wrapping using %+w is prone to errors and does not support stacktraces. For example:

var (
err=errors.New("root error while doing A")
wrapped=errors.Wrap(err, "while doing B")
) 

• github.com/efficientgo/core/merrors implements type safe collection of multiple errors. It presentings them in a unified way as a single error interface.

funcCloseAll(closers []io.Closer) error {
errs:=merrors.New()
for_, c:=rangeclosers {
errs.Add(c.Close())
}
returnerrs.Err()
}

• github.com/efficientgo/core/errcapture offers readable and robust error handling in defer statement using Go return arguments.

funcDoAndClose(f*os.File) (errerror) {
defererrcapture.Do(&err, f.Close, "close file at the end")
// Do something...iferr:=do(); err!=nil {
returnerr
}
returnnil
} 

• github.com/efficientgo/core/logerrcapture is similar to errcapture, but instead of appending potential error it logs it using logger interface.

funcDoAndClose(f*os.File, logger logerrcapture.Logger) error {
deferlogerrcapture.Do(logger, f.Close, "close file at the end")
// Do something...iferr:=do(); err!=nil {
returnerr
}
returnnil
} 

Waiting and Retrying

• github.com/efficientgo/core/runutil offers Retry and Repeat functions which is often need in Go production code (e.g. repeating operation periodically) as well as tests (e.g. waiting on eventual results instead of sleeping).

// Repeat every 1 second until context is done (e.g. cancel or timeout) or// function returns error.err:=runutil.Repeat(1*time.Second, ctx.Done(), func() error {
// ...returnerr// Ups, error - don't repeat anymore!
})
// Retry every 1 second until context is done (e.g. cancel or timeout) or// function returns nil.err:=runutil.Retry(1*time.Second, ctx.Done(), func() error {
// ...returnnil// Done, no need to retry!
}) 

• github.com/efficientgo/core/backoff offers backoff timers which increases wait time on every retry, incredibly useful in distributed system timeout functionalities.

Testing

• github.com/efficientgo/core/testutil is a minimal testing utility with only few functions like Assert, Ok, NotOk for errors and Equals. It's an alternative to testify project which has a bit more bloated interface and larger dependencies.

funcTestSomething(t*testing.T) {
got, err:=something()
testutil.Ok(t, err)
testutil.Equals(t, expected, got, "expected different thing from something")
}

Initial Authors

• @bisakhmondal (errors package).
• @bwplotka
• @GiedriusS (errcapture and logerrcapture)