errk

README

errk - Error Handling Library

🔴 Custom Konsultin error handling with tracing, metadata, and error wrapping support.

Installation

go get github.com/konsultin/errk

Quick Start

import "github.com/konsultin/errk"

// Create a new error
err := errk.NewError("USER_NOT_FOUND", "User does not exist")

// With namespace
err := errk.NewError("VALIDATION_FAILED", "Email is invalid",
    errk.WithNamespace("auth"),
)

// Add trace information
err = err.Trace()

// Wrap existing error
err = errk.NewError("CONFIG_ERROR", "Failed to load config").Wrap(originalErr)

// Add metadata
err = err.AddMetadata("user_id", 123)

Features

• Structured Errors - Organize errors with namespace and code
• Error Wrapping - Wrap underlying errors while maintaining context
• Tracing - Automatic trace collection showing error origin
• Metadata - Attach arbitrary data for debugging
• Error Comparison - Works with Go's standard errors.Is()

License

MIT License - see LICENSE

Documentation

Index

• Variables
• func Trace(err error) error
• type Builder
  • func NewBuilder(namespace string, args ...SetOptionFn) *Builder
  • func (b *Builder) CopyError(err *Error, args ...SetOptionFn) *Error
  • func (b *Builder) FallbackError() *Error
  • func (b *Builder) Get(code string) *Error
  • func (b *Builder) Namespace() string
  • func (b *Builder) NewError(code string, message string, args ...SetOptionFn) *Error
• type Error
  • func InternalError() *Error
  • func NewError(code string, message string, args ...SetOptionFn) *Error
  • func Wrap(err error) *Error
  • func (e *Error) AddMetadata(key string, value interface{}) *Error
  • func (e *Error) Code() string
  • func (e *Error) Copy(args ...SetOptionFn) *Error
  • func (e *Error) Error() string
  • func (e *Error) Is(err error) bool
  • func (e *Error) Message() string
  • func (e *Error) Metadata() map[string]interface{}
  • func (e *Error) Namespace() string
  • func (e *Error) Trace(args ...SetOptionFn) *Error
  • func (e *Error) Traces() []string
  • func (e *Error) Unwrap() error
  • func (e *Error) Wrap(err error) *Error
• type SetOptionFn
  • func AddMetadata(key string, value interface{}) SetOptionFn
  • func Errorf(msg string, args ...interface{}) SetOptionFn
  • func FallbackError(err *Error) SetOptionFn
  • func SkipTrace(skip int) SetOptionFn
  • func Source(err error) SetOptionFn
  • func WithHTTPStatus(status int) SetOptionFn
  • func WithMetadata(metadata map[string]interface{}) SetOptionFn
  • func WithNamespace(namespace string) SetOptionFn

Variables

var DuplicateFallbackError = NewError("E_COM_0", "Cannot create new Error that has same code with Fallback Error",
	WithNamespace(pkgNamespace))

Functions

func Trace

func Trace(err error) error

Trace wrap and trace error. If error is not *errx.Error then it will be wrapped into InternalError Else, it will add stack trace to error

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

func NewBuilder

func NewBuilder(namespace string, args ...SetOptionFn) *Builder

func (*Builder) CopyError

func (b *Builder) CopyError(err *Error, args ...SetOptionFn) *Error

CopyError take error input and override the namespace

func (*Builder) FallbackError

func (b *Builder) FallbackError() *Error

FallbackError is getter function to retrieve FallbackError value

func (*Builder) Get

func (b *Builder) Get(code string) *Error

Get retrieve error by Code, if no t exist then return fallback error

func (*Builder) Namespace

func (b *Builder) Namespace() string

Namespace is getter function to retrieve builder namespace

func (*Builder) NewError

func (b *Builder) NewError(code string, message string, args ...SetOptionFn) *Error

NewError create new error and ensure error is unique by it's code

type Error

type Error struct {
	// contains filtered or unexported fields
}

func InternalError

func InternalError() *Error

func NewError

func NewError(code string, message string, args ...SetOptionFn) *Error

NewError initiates a new error instance

func Wrap

func Wrap(err error) *Error

func (*Error) AddMetadata

func (e *Error) AddMetadata(key string, value interface{}) *Error

AddMetadata copy existing error and set new metadata

func (*Error) Code

func (e *Error) Code() string

Code is getter function to retrieve error code value

func (*Error) Copy

func (e *Error) Copy(args ...SetOptionFn) *Error

Copy duplicate error traces. Available options is WithNamespace, WithMetadata and CopySource

func (*Error) Error

func (e *Error) Error() string

Error implement standard go error interface. If source error is exists then it will print error cause

func (*Error) Is

func (e *Error) Is(err error) bool

Is implements function that will be called by errors.Is for error comparison. Actual error namespace and code value must equal with Expected ones

func (*Error) Message

func (e *Error) Message() string

Message is getter function to retrieve message value

func (*Error) Metadata

func (e *Error) Metadata() map[string]interface{}

Metadata is getter function to retrieve metadata value

func (*Error) Namespace

func (e *Error) Namespace() string

Namespace is getter function to retrieve error namespace

func (*Error) Trace

func (e *Error) Trace(args ...SetOptionFn) *Error

func (*Error) Traces

func (e *Error) Traces() []string

Traces is getter function to retrieve traces value

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap implements xerrors.Wrapper interface

func (*Error) Wrap

func (e *Error) Wrap(err error) *Error

type SetOptionFn

type SetOptionFn = func(*options)

func AddMetadata

func AddMetadata(key string, value interface{}) SetOptionFn

func Errorf

func Errorf(msg string, args ...interface{}) SetOptionFn

func FallbackError

func FallbackError(err *Error) SetOptionFn

func SkipTrace

func SkipTrace(skip int) SetOptionFn

func Source

func Source(err error) SetOptionFn

func WithHTTPStatus

func WithHTTPStatus(status int) SetOptionFn

WithHTTPStatus attaches an HTTP status to the error metadata for downstream responders.

func WithMetadata

func WithMetadata(metadata map[string]interface{}) SetOptionFn

func WithNamespace

func WithNamespace(namespace string) SetOptionFn