errdef is a sophisticated error handling library for Go that introduces a definition-first approach. It enables users to separate error definitions from error instances, ensuring that errors are consistently typed, structured, and uniform. By integrating seamlessly with Go's standard library functions such as errors.Is and errors.As, as well as providing enhanced features like stack traces and detailed error composition, errdef enhances the overall error management experience in Go applications.

Key Features

• Error Constructors: Create errors in various ways, including joining multiple causes while preserving the original context, allowing for flexible error handling.
• Detailed Error Formatting: Easily format errors to include a comprehensive view that showcases the error message, type, fields, stack trace, and wrapped errors using %+v.
• JSON Marshaling: Generate structured JSON output for errors, facilitating easy integration with APIs and logging systems.
• Structured Logging (slog): Implement structured logging with minimal configuration, streamlining error tracking and diagnostics.
• Field Management: The library allows the definition and extraction of strong typed fields, enabling users to attach key detail information to errors and extract it in a type-safe manner.
• Context Integration: Automatically incorporate context-scoped options into errors, enhancing traceability in request handling.
• Redaction: Ensure sensitive information (like emails or tokens) is appropriately masked in logs and serialized outputs using the Redacted wrapper.
• Panic Recovery: Convert panics into structured errors, providing a consistent way to handle unexpected failures.

Usage Example

Here’s a simple example demonstrating the library’s capabilities:

package main

import (
    "context"
    "errors"
    "fmt"
    "github.com/shiwano/errdef"
)

var (
    ErrNotFound = errdef.Define("not_found", errdef.HTTPStatus(404))
    UserID, UserIDFrom = errdef.DefineField[string](https://github.com/shiwano/errdef/blob/main/"user_id")
)

func findUser(ctx context.Context, id string) error {
    return ErrNotFound.With(ctx, UserID(id)).New("user not found")
}

func main() {
    err := findUser(context.TODO(), "u123")
    if errors.Is(err, ErrNotFound) {
        fmt.Println("user not found")
    }
    if userID, ok := UserIDFrom(err); ok {
        fmt.Println("user id:", userID)
    }
}

Performance Insights

errdef maintains strong performance metrics while providing thorough error handling capabilities. Benchmarks indicate that error creation and management do not become bottlenecks in typical applications, allowing developers to focus on maintaining application integrity and clarity.

Contributing

Contributions to errdef are welcomed, with a focus on enhancing functionality and addressing any issues that arise. Interested parties can participate by raising issues or submitting pull requests to the project's GitHub repository.