errorx

Documentation

Overview

Package errorx provides generic error handling primitives with code-based classification and type-level domain isolation. It has zero external dependencies.

Error[Code] wraps an error with a typed integer code and optional cause chain. Chain-aware query functions (IsCode, ContainsCode) traverse the errors.Unwrap chain, penetrating across different Code type nodes.

Sentinel[D] uses a phantom type parameter to create domain-isolated sentinel errors that are distinguishable at compile time while remaining plain strings at runtime.

Index

• func ContainsCode[Code ErrCodeConstraint](err error, code Code) bool
• func IsCode[Code ErrCodeConstraint](err error, code Code) bool
• type ErrCodeConstraint
• type Error
  • func New[Code ErrCodeConstraint](code Code, message string) *Error[Code]
  • func Newf[Code ErrCodeConstraint](code Code, format string, args ...any) *Error[Code]
  • func Wrap[Code ErrCodeConstraint](cause error, code Code, message string) *Error[Code]
  • func Wrapf[Code ErrCodeConstraint](cause error, code Code, format string, args ...any) *Error[Code]
  • func (e *Error[Code]) Error() string
  • func (e *Error[Code]) Unwrap() error
• type Sentinel
  • func NewSentinel[D any](message string) Sentinel[D]
  • func NewSentinelf[D any](format string, args ...any) Sentinel[D]
  • func (e Sentinel[D]) Error() string

Functions

func ContainsCode

func ContainsCode[Code ErrCodeConstraint](err error, code Code) bool

ContainsCode reports whether any Error with the same Code type anywhere in the chain has the specified code value. Unlike IsCode which checks only the outermost match, ContainsCode searches the entire chain by stepping through each matched Error's Cause.

func IsCode

func IsCode[Code ErrCodeConstraint](err error, code Code) bool

IsCode reports whether the outermost Error in err's chain matching the same Code type has the specified code value. errors.As traverses the full Unwrap chain, penetrating across different Code type nodes.

Types

type ErrCodeConstraint

type ErrCodeConstraint interface {
	~int
}

ErrCodeConstraint constrains error code types to int-based types. Convention: reserve code value 0 as "unset/default" and start iota at 1. This keeps the zero value of any Code type semantically safe — an uninitialized Error[Code] will not accidentally carry a meaningful code.

type Error

type Error[Code ErrCodeConstraint] struct {
	Code    Code
	Message string
	Cause   error // nil = leaf, non-nil = wrapped
}

Error is a generic coded error with optional cause chain. When Cause is nil, it represents a leaf error. When Cause is non-nil, it wraps an underlying error.

func New

func New[Code ErrCodeConstraint](code Code, message string) *Error[Code]

New creates a leaf Error with the given code and message.

func Newf

func Newf[Code ErrCodeConstraint](code Code, format string, args ...any) *Error[Code]

Newf creates a leaf Error with a formatted message.

func Wrap

func Wrap[Code ErrCodeConstraint](cause error, code Code, message string) *Error[Code]

Wrap wraps an existing error with a code and message. If cause is nil, returns nil.

func Wrapf

func Wrapf[Code ErrCodeConstraint](cause error, code Code, format string, args ...any) *Error[Code]

Wrapf wraps an existing error with a code and formatted message. If cause is nil, returns nil.

func (*Error[Code]) Error

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

Error implements the error interface.

func (*Error[Code]) Unwrap

func (e *Error[Code]) Unwrap() error

Unwrap returns the underlying cause, enabling errors.Is/As chain traversal.

type Sentinel

type Sentinel[D any] string

Sentinel is a generic string-based sentinel error type. The phantom type parameter D provides type-level domain separation without affecting the runtime representation — it is still just a string.

func NewSentinel

func NewSentinel[D any](message string) Sentinel[D]

NewSentinel creates a new Sentinel error with the given message.

func NewSentinelf

func NewSentinelf[D any](format string, args ...any) Sentinel[D]

NewSentinelf creates a new Sentinel error with a formatted message.

func (Sentinel[D]) Error

func (e Sentinel[D]) Error() string

Error implements the error interface.