1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
# core
[](https://pkg.go.dev/github.com/efficientgo/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](https://github.com/davecgh/go-spew) and [google/go-cmp](https://github.com/google/go-cmp).
Maintained by experienced Go developers, including author of the [Efficient Go book](https://www.oreilly.com/library/view/efficient-go/9781098105709/).
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](https://pkg.go.dev/github.com/efficientgo/core/errors) is an improved and minimal version of the popular [`pkg/errors`](https://github.com/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:
```go
var (
err = errors.New("root error while doing A")
wrapped = errors.Wrap(err, "while doing B")
)
```
* [github.com/efficientgo/core/merrors](https://pkg.go.dev/github.com/efficientgo/core/merrors) implements type safe collection of multiple errors. It presentings them in a unified way as a single `error` interface.
```go
func CloseAll(closers []io.Closer) error {
errs := merrors.New()
for _, c := range closers {
errs.Add(c.Close())
}
return errs.Err()
}
```
* [github.com/efficientgo/core/errcapture](https://pkg.go.dev/github.com/efficientgo/core/errcapture) offers readable and robust error handling in defer statement using Go return arguments.
```go
func DoAndClose(f *os.File) (err error) {
defer errcapture.Do(&err, f.Close, "close file at the end")
// Do something...
if err := do(); err != nil {
return err
}
return nil
}
```
* [github.com/efficientgo/core/logerrcapture](https://pkg.go.dev/github.com/efficientgo/core/logerrcapture) is similar to `errcapture`, but instead of appending potential error it logs it using logger interface.
```go
func DoAndClose(f *os.File, logger logerrcapture.Logger) error {
defer logerrcapture.Do(logger, f.Close, "close file at the end")
// Do something...
if err := do(); err != nil {
return err
}
return nil
}
```
## Waiting and Retrying
* [github.com/efficientgo/core/runutil](https://pkg.go.dev/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).
```go
// 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 {
// ...
return err // 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 {
// ...
return nil // Done, no need to retry!
})
```
* [github.com/efficientgo/core/backoff](https://pkg.go.dev/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](https://pkg.go.dev/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](https://github.com/stretchr/testify) project which has a bit more bloated interface and larger dependencies.
```go
func TestSomething(t *testing.T) {
got, err := something()
testutil.Ok(t, err)
testutil.Equals(t, expected, got, "expected different thing from something")
}
```
## Initial Authors
* [`@bisakhmondal`](https://github.com/bisakhmondal) (`errors` package).
* [`@bwplotka`](https://bwplotka.dev)
* [`@GiedriusS`](https://github.com/GiedriusS) (`errcapture` and `logerrcapture`)
|
