From ff7c2e4db65695c5a0429bb7375e530258d23e99 Mon Sep 17 00:00:00 2001 From: Ankur Shrivastava Date: Sat, 11 Apr 2026 12:57:06 +0800 Subject: [PATCH 1/3] docs: document stdlib re-exports in errors package Add sections for Is, As, Unwrap, Join, and Cause to the errors howto page now that the errors package re-exports all stdlib error functions. Update the Packages page description to reflect drop-in replacement. --- Packages.md | 2 +- howto/errors.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 58 insertions(+), 2 deletions(-) diff --git a/Packages.md b/Packages.md index 13e2695..e733d5f 100644 --- a/Packages.md +++ b/Packages.md @@ -35,7 +35,7 @@ Interceptors provides a common set of reusable interceptors for grpc services Documentation can be found at [interceptor-docs] ## [Errors] -errors provides an implementation of golang error with stack strace information attached to it, the error objects created by this package are compatible with https://golang.org/pkg/errors/ +A drop-in replacement for the standard `errors` package that adds stack trace capture, gRPC status codes, and error notification support. All standard library functions (`Is`, `As`, `Unwrap`, `Join`) are re-exported. Documentation can be found at [errors-docs] diff --git a/howto/errors.md b/howto/errors.md index 68a0bb8..5e8d567 100644 --- a/howto/errors.md +++ b/howto/errors.md @@ -59,7 +59,6 @@ func somefunction() error { The ColdBrew [errors package] provides a `Wrap` function that can be used to wrap an error with a message. This is useful when you want to add more context to an error. ```go - import ( "github.com/go-coldbrew/errors" ) @@ -76,6 +75,63 @@ func function2() error { } ``` +### Checking errors + +All standard library error functions are re-exported, so you don't need a separate `import "errors"`. Use `errors.Is` to check if an error matches a sentinel value, and `errors.As` to extract a specific error type from the chain: + +```go +import ( + "github.com/go-coldbrew/errors" +) + +// Check if an error matches a sentinel value +if errors.Is(err, sql.ErrNoRows) { + // handle not found +} + +// Extract a specific error type from the chain +var ext errors.ErrorExt +if errors.As(err, &ext) { + fmt.Println("gRPC code:", ext.GRPCStatus().Code()) +} +``` + +### Finding root cause + +Use `errors.Cause` to walk the `Unwrap` chain and find the root cause error. This works on any error, not just ColdBrew errors: + +```go +root := errors.Cause(err) +fmt.Println("root cause:", root) +``` + +For ColdBrew errors, you can also use the `Cause()` method on the `ErrorExt` interface, which returns the same result. + +### Combining errors + +Use `errors.Join` to combine multiple errors into a single error: + +```go +err1 := errors.New("first problem") +err2 := errors.New("second problem") +combined := errors.Join(err1, err2) + +// Both errors are preserved in the chain +errors.Is(combined, err1) // true +errors.Is(combined, err2) // true +``` + +### Unwrapping errors + +Use `errors.Unwrap` to get the immediate parent error in the chain: + +```go +base := errors.New("base") +wrapped := errors.Wrap(base, "context") + +inner := errors.Unwrap(wrapped) // returns base +``` + ## ColdBrew notifier package The ColdBrew [notifier package] provides a simple way to notify errors to different notifiers like [Sentry], [Airbrake], [Rollbar] etc. From c7234c07e9f5b42647b0792d99e359800bed7e10 Mon Sep 17 00:00:00 2001 From: Ankur Shrivastava Date: Sat, 11 Apr 2026 13:34:12 +0800 Subject: [PATCH 2/3] fix: address PR review feedback - Add missing imports (database/sql, fmt) to Checking errors example - Clarify that error notification is in the notifier sub-package --- Packages.md | 2 +- howto/errors.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/Packages.md b/Packages.md index e733d5f..254f554 100644 --- a/Packages.md +++ b/Packages.md @@ -35,7 +35,7 @@ Interceptors provides a common set of reusable interceptors for grpc services Documentation can be found at [interceptor-docs] ## [Errors] -A drop-in replacement for the standard `errors` package that adds stack trace capture, gRPC status codes, and error notification support. All standard library functions (`Is`, `As`, `Unwrap`, `Join`) are re-exported. +A drop-in replacement for the standard `errors` package that adds stack trace capture and gRPC status codes. Standard library helpers (`Is`, `As`, `Unwrap`, `Join`) are re-exported. Error notification is provided by the [Notifier] sub-package below. Documentation can be found at [errors-docs] diff --git a/howto/errors.md b/howto/errors.md index 5e8d567..3539b4c 100644 --- a/howto/errors.md +++ b/howto/errors.md @@ -81,6 +81,9 @@ All standard library error functions are re-exported, so you don't need a separa ```go import ( + "database/sql" + "fmt" + "github.com/go-coldbrew/errors" ) From 22ddbb6bcc9e5d8dd89cc7e95324cec9e280566f Mon Sep 17 00:00:00 2001 From: Ankur Shrivastava Date: Sat, 11 Apr 2026 15:06:24 +0800 Subject: [PATCH 3/3] fix: address round 2 review feedback - Clarify that Cause is ColdBrew-specific, not a stdlib re-export - Wrap example in a function so err is defined - Remove fmt.Println from standalone snippet --- howto/errors.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/howto/errors.md b/howto/errors.md index 3539b4c..1e20ed5 100644 --- a/howto/errors.md +++ b/howto/errors.md @@ -77,7 +77,7 @@ func function2() error { ### Checking errors -All standard library error functions are re-exported, so you don't need a separate `import "errors"`. Use `errors.Is` to check if an error matches a sentinel value, and `errors.As` to extract a specific error type from the chain: +Standard library error helpers (`Is`, `As`, `Unwrap`, `Join`) are re-exported, so you don't need a separate `import "errors"`. Use `errors.Is` to check if an error matches a sentinel value, and `errors.As` to extract a specific error type from the chain: ```go import ( @@ -87,25 +87,26 @@ import ( "github.com/go-coldbrew/errors" ) -// Check if an error matches a sentinel value -if errors.Is(err, sql.ErrNoRows) { - // handle not found -} - -// Extract a specific error type from the chain -var ext errors.ErrorExt -if errors.As(err, &ext) { - fmt.Println("gRPC code:", ext.GRPCStatus().Code()) +func handleQuery(err error) { + // Check if an error matches a sentinel value + if errors.Is(err, sql.ErrNoRows) { + // handle not found + } + + // Extract a specific error type from the chain + var ext errors.ErrorExt + if errors.As(err, &ext) { + fmt.Println("gRPC code:", ext.GRPCStatus().Code()) + } } ``` ### Finding root cause -Use `errors.Cause` to walk the `Unwrap` chain and find the root cause error. This works on any error, not just ColdBrew errors: +ColdBrew also provides `errors.Cause` to walk the `Unwrap` chain and find the root cause error. This works on any error, not just ColdBrew errors: ```go -root := errors.Cause(err) -fmt.Println("root cause:", root) +root := errors.Cause(err) // returns the innermost error in the chain ``` For ColdBrew errors, you can also use the `Cause()` method on the `ErrorExt` interface, which returns the same result.