GitHub - emiliogrv/errors: High-performance structured error handling for Go. Drop-in replacement for errors package with zero-reflection marshalers and logging framework integration.

Overview
Performance
Features
Installation
Usage
Templates
Generator Usage
- Examples
API Reference
Drop-in Replacement Compatibility
- Known Differences
- Compatibility Testing
API Stability
Examples
Contributing
License
Acknowledgments

Overview

This ready-to-use library provides structured error handling for Go applications, designed as a complete drop-in replacement for the standard errors package. It extends standard error functionality with:

Structured attributes for rich error context
Error wrapping and joining with full compatibility with errors.Is, errors.As, and errors.Join
Stack trace capture for debugging
JSON serialization for structured logging
Direct integration with popular logging frameworks (Zap, Zerolog, Logrus, slog)
Customizable code generation for your own logging frameworks

Performance

This library is designed with performance as a core principle. The primary goal is to provide meaningful, structured error messages with maximum performance by:

Avoiding reflection wherever possible - type-safe attribute helpers eliminate runtime reflection overhead
Zero-allocation string building for common error formatting paths
Efficient marshaling - custom marshalers for each logging framework avoid generic reflection-based serialization
Lazy evaluation - error details are only formatted when actually logged or serialized
Minimal allocations - careful memory management to reduce GC pressure

Features

Core Functionality

The library maintains full compatibility with Go's standard errors package while adding powerful structured error handling capabilities:

import errors "github.com/emiliogrv/errors/pkg/full"

err := errors.New("database connection failed").
WithAttrs(
errors.String("host", "localhost"),
errors.Int("port", 5432),
errors.Duration("timeout", 30*time.Second),
).
WithTags("database", "critical").
WithStack(debug.Stack())

Partial Imports

Import only what you need! To avoid pulling all logging framework dependencies into your go.mod, you can import specific logger packages:

// Import only Zap support
import errors "github.com/emiliogrv/errors/pkg/zap"

// Import only slog support
import errors "github.com/emiliogrv/errors/pkg/slog"

// Import only Logrus support
import errors "github.com/emiliogrv/errors/pkg/logrus"

// Import only Zerolog support
import errors "github.com/emiliogrv/errors/pkg/zerolog"

// Import only core functionality (no logger integrations)
import errors "github.com/emiliogrv/errors/pkg/core"

Each partial import includes the core templates plus the specific logger integration, keeping your dependencies minimal.

Custom Template Generation

The library supports custom template generation, allowing you to:

Generate your own logger integrations by providing custom templates
Override default templates to customize behavior
Add new functionality by simply using the -input-dir flag with your template directory

Example:

go run github.com/emiliogrv/errors/cmd/errors_generator \
    -input-dir ./my-templates \
    -output-dir ./generated \
    -formats mylogger,zap

Core templates are always generated regardless of which formats you specify, ensuring base functionality is always available.

Installation

go get github.com/emiliogrv/errors

Usage

Basic Error Creation

import errors "github.com/emiliogrv/errors/pkg/full"

// Simple error
err := errors.New("something went wrong")

// Error with attributes
err := errors.New("failed to process request").
WithAttrs(
errors.String("user_id", "12345"),
errors.Int("retry_count", 3),
errors.Bool("recoverable", true),
)

Error Wrapping

// Wrap errors with context
if err := doSomething(); err != nil {
	return errors.New("operation failed").
		WithErrors(err).
		WithAttrs(errors.String("operation", "doSomething"))
}

// Join multiple errors
err := errors.Join(
	errors.New("validation failed"),
	errors.New("missing required field: email"),
	errors.New("missing required field: name"),
)

Logging Integration

Full Import Example

import (
	errors "github.com/emiliogrv/errors/pkg/full"
	"go.uber.org/zap"
)

func main() {
	err := errors.New("operation failed").
		WithAttrs(errors.Int("code", 500))

	// Zap
	logger, _ := zap.NewProduction()
	logger.Error("error occurred", zap.Any("err", err))

	// JSON marshaling
	jsonData, _ := json.Marshal(err)

	// Logrus
	logrus.WithFields(logrus.Fields{
		"err": err.(*errors.StructuredError).MarshalLogrusFields(),
	}).
		Error("error occurred")
}

Partial Import Example

import (
	errors "github.com/emiliogrv/errors/pkg/zap" // Only Zap dependency
	"go.uber.org/zap"
)

func main() {
	err := errors.New("operation failed").
		WithAttrs(errors.Int("code", 500))

	logger, _ := zap.NewProduction()
	logger.Error("error occurred", zap.Any("err", err))
}

Custom Template Example

Create your custom template (e.g., tmpl/mylogger.tmpl):

// Code generated by errors_generator; DO NOT EDIT.
// Generated at {{ .Date }}
// Version {{ .Version }}

package {{ .PackageName }}

// MarshalMyLogger is the implementation for MyLogger.
func (receiver *StructuredError) MarshalMyLogger() error {
    // Your custom marshaling logic here
    return nil
}

Generate code:

go run github.com/emiliogrv/errors/cmd/errors_generator \
    -input-dir ./tmpl \
    -output-dir ./generated \
    -formats mylogger

Templates

Core Templates

Core templates are always generated and provide the fundamental error handling functionality:

Template	Description
`attr.go`	Type-safe attribute helpers (String, Int, Bool, Time, Duration, etc.)
`common.go`	Common utilities and depth control for marshaling
`error.go`	Core `StructuredError` type and basic methods
`join.go`	`Join` and `JoinIf` functions for combining errors
`json.go`	JSON marshaling/unmarshaling support
`map.go`	Map representation for generic structured output
`string.go`	String formatting and `Error()` method implementation
`wrap.go`	`Unwrap`, `Is`, and `As` methods for error wrapping

Logger Templates

Additional templates for specific logging framework integrations:

Package	Templates	Dependencies
`pkg/full`	Core + Zap + Zerolog + Logrus + slog	All logger dependencies
`pkg/zap`	Core + Zap	`go.uber.org/zap`
`pkg/zerolog`	Core + Zerolog	`github.com/rs/zerolog`
`pkg/logrus`	Core + Logrus	`github.com/sirupsen/logrus`
`pkg/slog`	Core + slog	Standard library only
`pkg/core`	Core only	No external dependencies

Template Overriding

You can override any default template by providing a template with the same name in your input directory:

# Override the default zap.tmpl with your custom version
go run github.com/emiliogrv/errors/cmd/errors_generator \
    -input-dir ./my-templates \
    -output-dir ./generated \
    -formats zap

If my-templates/zap.tmpl exists, it will replace the built-in Zap template.

Generator Usage

The code generator supports various options:

go run github.com/emiliogrv/errors/cmd/errors_generator [options]

Options:
  -formats string
        Comma-separated list of formats to generate, or 'all' to generate all formats (default: core)
  -help
        Show this help message
  -input-dir string
        Path to user templates directory (optional)
  -output-dir string
        Output directory for generated files
  -export-dir string
        Export default templates to the specified directory and exit
  -package string
        Package name for generated code (default: errors) (default "errors")
  -test-gen string
        Test generation level: none, flex, strict (default: none) (default "none")
  -with-gen-header
        Include generated message in generated code (default: true) (default true)

Examples

# Export default templates for customization
go run github.com/emiliogrv/errors/cmd/errors_generator -export-dir ./my-templates

# Generate core templates only
go run github.com/emiliogrv/errors/cmd/errors_generator -output-dir ./pkg/core

# Generate with Zap support
go run github.com/emiliogrv/errors/cmd/errors_generator \
    -output-dir ./pkg/zap \
    -formats zap

# Generate all available formats
go run github.com/emiliogrv/errors/cmd/errors_generator \
    -output-dir ./pkg/full \
    -formats all

# Generate with custom templates
go run github.com/emiliogrv/errors/cmd/errors_generator \
    -input-dir ./my-templates \
    -output-dir ./generated \
    -formats mylogger,zap

# Generate with tests
go run github.com/emiliogrv/errors/cmd/errors_generator \
    -output-dir ./pkg/full \
    -formats all \
    -test-gen strict

API Reference

Core Types

`StructuredError`

type StructuredError struct {
	Message string   // Primary error message
	Attrs   []Attr   // Structured attributes
	Errors  []error  // Wrapped errors
	Tags    []string // Categorical labels
	Stack   []byte   // Stack trace (optional)
}

`Attr`

type Attr struct {
	Key   string
	Value any
	Type  Type
}

Core Functions

New(message string) *StructuredError - Create a new structured error
Join(errs ...error) error - Join multiple errors (nil-safe)
JoinIf(errs ...error) error - Join errors only if first is non-nil
Is(err, target error) bool - Check error equality (alias to errors.Is)
As(err error, target any) bool - Type assertion (alias to errors.As)
Unwrap(err error) error - Unwrap single error (alias to errors.Unwrap)

Attribute Helpers

Type-safe helpers for common types:

String(key, value string) Attr
Int(key string, value int) Attr
Int64(key string, value int64) Attr
Uint64(key string, value uint64) Attr
Float64(key string, value float64) Attr
Bool(key string, value bool) Attr
Time(key string, value time.Time) Attr
Duration(key string, value time.Duration) Attr
Any(key string, value any) Attr
Object(key string, attrs ...Attr) Attr

Each helper also has a plural version (e.g., Ints, Strings, Bools) for slices.

Methods

`*StructuredError` Methods

WithAttrs(attrs ...Attr) *StructuredError - Add attributes
WithErrors(errors ...error) *StructuredError - Set wrapped errors
WithTags(tags ...string) *StructuredError - Add tags
WithStack(stack []byte) *StructuredError - Set stack trace
PrependErrors(errors ...error) *StructuredError - Add errors at the beginning
AppendErrors(errors ...error) *StructuredError - Add errors at the end
Error() string - Implement error interface
Unwrap() []error - Implement multi-unwrapper interface
MarshalJSON() ([]byte, error) - JSON marshaling
UnmarshalJSON(data []byte) error - JSON unmarshaling

Configuration

// Set maximum depth for error marshaling (default: 100)
errors.SetMaxDepthMarshal(depth int)

// Get current maximum depth
errors.MaxDepthMarshal() int

Drop-in Replacement Compatibility

This library is designed as a complete drop-in replacement for Go's standard errors package. You can replace:

import "errors"

with:

import errors "github.com/emiliogrv/errors/pkg/full"

And your existing code will continue to work as expected.

Known Differences

While this library maintains full API compatibility with the standard errors package, there are some behavioral differences to be aware of:

1. Text Loss with Nested `fmt.Errorf` Wrappers

When using fmt.Errorf to wrap a StructuredError, the text is preserved in the fmt.Errorf wrapper. However, if that wrapped error is then added to another StructuredError via WithErrors() or Join(), the fmt.Errorf wrapper text is lost because the marshaling extracts the inner StructuredError directly:

base := errors.New("base error")
wrapped := fmt.Errorf("text example %w", base)

// Text is preserved when calling wrapped.Error() directly:
fmt.Println(wrapped.Error()) // Output: "text example (message=base error)"

// But text is lost when nested in another StructuredError:
nested := errors.New("outer").WithErrors(wrapped)
fmt.Println(nested.Error())
// Output: (message=outer),
//         (errors=[
//             (message=base error)
//         ])
// The "text example" part is lost

Workaround: Use structured error capabilities directly instead of mixing fmt.Errorf with WithErrors():

base := errors.New("base error")
wrapped := errors.New("text example").WithErrors(base)
// Now "text example" is preserved in the error chain

2. String Output Format

The string representation of errors created with this package may differ from standard errors when using structured features:

Standard errors.New(): Produces identical output to errors.New() from the standard library
With structured features: Using WithErrors(), WithAttrs(), etc. produces a different format that includes the structured information

// These produce identical string output:
stdErr := stderrors.New("error message")
customErr := errors.New("error message")

// These produce different string output:
stdWrapped := fmt.Errorf("wrapper: %w", stderrors.New("base"))
customWrapped := errors.New("wrapper").WithErrors(errors.New("base"))

3. `Unwrap()` and Serialization Behavior

This package implements the multi-error unwrapper interface (Unwrap() []error), while fmt.Errorf with %w implements the single-error unwrapper interface (Unwrap() error). The key difference is in how StructuredError serializes wrapped errors:

fmt.Errorf("text %w", err) on its own:
- Preserves all text when calling .Error()
- Example: fmt.Errorf("text example %w", err).Error() shows "text example: <err message>"
- Implements single-error unwrapper interface
fmt.Errorf wrapped in StructuredError:
- When StructuredError serializes the error, it calls Unwrap() to extract the inner error
- fmt.Errorf ignores the wrapping text when unwrapped, returning only the inner error
- Result: The wrapping text is lost during StructuredError serialization
- Example: errors.New("outer").WithErrors(fmt.Errorf("text example %w", err)) loses "text example"
WithErrors() wrapped errors:
- Preserves all text and structure during serialization
- Does not lose context when unwrapped by another StructuredError
- Implements the multi-unwrap interface for error chaining
- Maintains full context in both the error chain and string output

For example:

// fmt.Errorf preserves text on its own
wrapped1 := fmt.Errorf("text example %w", errors.New("base error"))
fmt.Println(wrapped1.Error()) // => "text example: base error" ✓

// But text is lost when StructuredError unwraps it
wrapped2 := errors.New("outer").WithErrors(wrapped1)
fmt.Println(wrapped2.Error()) // => "(message=outer), (errors=[(message=base error)])" - loses "text example" ✗

// WithErrors preserves all text
wrapped3 := errors.New("wrapper").WithErrors(errors.New("base error"))
fmt.Println(wrapped3.Error()) // => "(message=wrapper), (errors=[(message=base error)])" ✓

Compatibility Testing

The library includes comprehensive compatibility tests to ensure drop-in replacement behavior. See pkg/full/compatibility_test.go for detailed test cases covering:

String output comparison between standard and structured errors
errors.Is() behavior with both error types
errors.As() behavior for extracting StructuredError
errors.Unwrap() behavior with single and multi-unwrap interfaces
errors.Join() compatibility
Nil error handling
fmt.Errorf behavior with %w verb
The known text loss when nesting fmt.Errorf wrapped errors in WithErrors()

API Stability

⚠️ Pre-1.0 Notice: The library API is essentially complete but may undergo changes before version 1.0. While we strive to maintain backward compatibility, breaking changes may occur in minor versions (0.x.y) until the 1.0 release.

Once version 1.0 is released, the API will follow semantic versioning strictly.

Examples

Complete examples are available in the examples/ directory:

full import - Full import with all logger integrations
partial import - Partial import (Zap only)
custom tmpl - Custom template generation

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Acknowledgments

This library is designed to be a drop-in replacement for Go's standard errors package while providing enhanced functionality for modern application development.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
cmd/errors_generator		cmd/errors_generator
examples		examples
internal/template		internal/template
pkg		pkg
.editorconfig		.editorconfig
.gitignore		.gitignore
.golangci.yaml		.golangci.yaml
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

License

emiliogrv/errors

Folders and files

Latest commit

History

Repository files navigation

Overview

Performance

Features

Core Functionality

Partial Imports

Custom Template Generation

Installation

Usage

Basic Error Creation

Error Wrapping

Logging Integration

Full Import Example

Partial Import Example

Custom Template Example

Templates

Core Templates

Logger Templates

Template Overriding

Generator Usage

Examples

API Reference

Core Types

StructuredError

Attr

Core Functions

Attribute Helpers

Methods

*StructuredError Methods

Configuration

Drop-in Replacement Compatibility

Known Differences

1. Text Loss with Nested fmt.Errorf Wrappers

2. String Output Format

3. Unwrap() and Serialization Behavior

Compatibility Testing

API Stability

Examples

Contributing

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Languages

`StructuredError`

`Attr`

`*StructuredError` Methods

1. Text Loss with Nested `fmt.Errorf` Wrappers

3. `Unwrap()` and Serialization Behavior

Packages