xerrs

go-xerrs

A structured error handling package for Go applications with HTTP status mapping, error chaining, and stack trace support.

Installation

go get github.com/hotfixfirst/go-xerrs

Or with a specific version:

go get github.com/hotfixfirst/go-xerrs@v1.0.0

Quick Start

import "github.com/hotfixfirst/go-xerrs"

// Create a simple error
err := xerrs.New("something went wrong")

// Create a validation error with chaining
err := xerrs.New("invalid email format").AsInvalidFormat()

// Wrap an existing error with auto-detection
err := xerrs.Wrap(gorm.ErrRecordNotFound, "user not found")
// Automatically detects as NOT_FOUND with HTTP 404

Features

Error Creation

Functions

Examples

// Simple error
err := xerrs.New("database connection failed")
// [INTERNAL] INTERNAL_ERROR: database connection failed

// Structured error
err := xerrs.NewAppError(
    xerrs.ErrorTypeValidation,
    xerrs.CodeInvalidInput,
    "email is required",
)
// [VALIDATION] INVALID_INPUT: email is required

// Error with details
err := xerrs.New("validation failed").
    WithDetails("field 'email' must be a valid email address")

Error Chaining

Convert errors to specific types using fluent API methods.

Validation Errors (400 Bad Request)

Authentication Errors (401 Unauthorized)

Authorization Errors (403 Forbidden)

Not Found Errors (404 Not Found)

Conflict Errors (409 Conflict)

Rate Limit Errors (429 Too Many Requests)

Internal Errors (500 Internal Server Error)

External Service Errors (502 Bad Gateway)

Service Unavailable Errors (503 Service Unavailable)

Chaining Examples

// Validation error
err := xerrs.New("email is invalid").AsInvalidFormat()
// [VALIDATION] INVALID_FORMAT: email is invalid (HTTP 400)

// Authentication error
err := xerrs.New("session expired").AsTokenExpired()
// [AUTHENTICATION] TOKEN_EXPIRED: session expired (HTTP 401)

// Not found error
err := xerrs.New("user not found").AsResourceNotFound()
// [NOT_FOUND] RESOURCE_NOT_FOUND: user not found (HTTP 404)

// Custom code
err := xerrs.New("custom error").AsValidationWithCode("CUSTOM_CODE")
// [VALIDATION] CUSTOM_CODE: custom error (HTTP 400)

Error Wrapping

Wrap existing errors with automatic type and code detection.

Auto-Detection Support

Wrapping Examples

// Wrap with auto-detection
err := xerrs.Wrap(gorm.ErrRecordNotFound, "user not found")
// Type: NOT_FOUND, Code: RESOURCE_NOT_FOUND, HTTP: 404

// Wrap and convert
err := xerrs.Wrap(originalErr, "validation failed").AsInvalidInput()

// Re-wrapping preserves type
firstErr := xerrs.New("not found").AsResourceNotFound()
reWrapped := xerrs.Wrap(firstErr, "user lookup failed")
// Type is preserved as NOT_FOUND

HTTP Status Mapping

Error types automatically map to HTTP status codes.

err := xerrs.New("not found").AsResourceNotFound()
status := err.GetHTTPStatus() // 404

// Override status
err := xerrs.New("custom").WithHTTPStatus(422)
status := err.GetHTTPStatus() // 422

Configuration Methods

Inspection Methods

Helper Functions

Stack Traces

Built-in stack trace support via cockroachdb/errors.

err := xerrs.New("something failed")

// Get full stack trace
trace := err.GetStackTrace()

// Get stack trace as lines
lines := err.GetStackTraceLines()
for _, line := range lines {
    fmt.Println(line)
}

Error Codes

Validation Codes

• VALIDATION_ERROR, INVALID_INPUT, REQUIRED_FIELD, INVALID_FORMAT, INVALID_RANGE

Authentication Codes

• INVALID_CREDENTIALS, TOKEN_EXPIRED, TOKEN_INVALID, LOGIN_REQUIRED, AUTH_REQUIRED

Authorization Codes

• ACCESS_DENIED, INSUFFICIENT_PERMISSIONS, RESOURCE_FORBIDDEN, INSUFFICIENT_ROLE

Resource Codes

• RESOURCE_NOT_FOUND, RESOURCE_EXISTS

Internal Codes

• INTERNAL_ERROR, DATABASE_ERROR, DATABASE_CONNECTION, DATABASE_CONSTRAINT, INTERNAL_TIMEOUT, CONFIGURATION_ERROR, OPERATION_CANCELED

External Codes

• EXTERNAL_ERROR, EXTERNAL_TIMEOUT, EXTERNAL_UNAVAILABLE, SERVICE_UNAVAILABLE

Rate Limit Codes

• RATE_LIMIT_EXCEEDED

Runnable Examples

See the _examples directory for runnable examples:

• basic - Basic error creation and configuration
• chaining - Fluent error type conversion
• wrapping - Error wrapping and auto-detection

License

MIT License - see LICENSE for details.