errs

errs

import "github.com/brpaz/lib-go/errs"

Package errs provides a structured, transport-agnostic error type for domain and application layers.

Errors carry a machine-readable Code, a human-readable Message, optional per-field validation failures, and optional internal metadata. They contain no HTTP-specific concepts — the HTTP layer maps codes to status codes.

Usage

// standard constructors
errs.NotFound("user not found")
errs.InvalidInput("bad request", errs.NewFieldError("email", errs.CodeRequired, "required"))

// app-specific codes
errs.New("EMAIL_ALREADY_EXISTS", "email is already taken")

// attach internal context (never exposed to clients)
errs.Internal("unexpected error").WithCause(dbErr).WithMeta("user_id", id)

// errors.As traversal works through fmt.Errorf wrapping
wrapped := fmt.Errorf("UserService.GetByID: %w", errs.NotFound("user not found"))
var e *errs.Error
errors.As(wrapped, &e) // true

Index

• Constants
• type Error
  • func Conflict(message string) *Error
  • func Forbidden(message string) *Error
  • func Internal(message string) *Error
  • func InvalidInput(message string, fields ...FieldError) *Error
  • func New(code, message string) *Error
  • func NotFound(message string) *Error
  • func RateLimitExceeded(message string) *Error
  • func Unauthorized(message string) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
  • func (e *Error) WithCause(err error) *Error
  • func (e *Error) WithFields(fields ...FieldError) *Error
  • func (e *Error) WithMeta(key string, val any) *Error
• type FieldError
  • func NewFieldError(field, code, message string) FieldError
  • func NewFieldErrorWithParams(field, code, message string, params map[string]any) FieldError

Constants

Standard error codes.

const (
    CodeNotFound       = "not_found"
    CodeUnauthorized   = "unauthorized"
    CodeForbidden      = "forbidden"
    CodeInvalidInput   = "invalid_input"
    CodeConflict       = "conflict"
    CodeInternalServer = "internal_error"
    CodeRateLimit      = "rate_limit_exceeded"
)

type Error

Error is a structured domain error carrying a machine-readable Code, a human-readable Message, optional per-field validation failures, and optional internal metadata. It contains no HTTP-specific concepts.

type Error struct {
    Code    string
    Message string
    Fields  []FieldError
    Meta    map[string]any
    // contains filtered or unexported fields
}

func Conflict

func Conflict(message string) *Error

Conflict returns an Error with CodeConflict.

func Forbidden

func Forbidden(message string) *Error

Forbidden returns an Error with CodeForbidden.

func Internal

func Internal(message string) *Error

Internal returns an Error with CodeInternalServer. Attach the real cause with WithCause so it can be logged without leaking internals.

func InvalidInput

func InvalidInput(message string, fields ...FieldError) *Error

InvalidInput returns an Error with CodeInvalidInput and optional field errors.

func New

func New(code, message string) *Error

New constructs an Error with the given code and message. Use this for application-specific codes not covered by the standard constructors.

func NotFound

func NotFound(message string) *Error

NotFound returns an Error with CodeNotFound.

func RateLimitExceeded

func RateLimitExceeded(message string) *Error

RateLimitExceeded returns an Error with CodeRateLimit.

func Unauthorized

func Unauthorized(message string) *Error

Unauthorized returns an Error with CodeUnauthorized.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

func (*Error) Unwrap

func (e *Error) Unwrap() error

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

func (*Error) WithCause

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

WithCause attaches an underlying error for internal logging without exposing it to clients.

func (*Error) WithFields

func (e *Error) WithFields(fields ...FieldError) *Error

WithFields appends field-level validation errors.

func (*Error) WithMeta

func (e *Error) WithMeta(key string, val any) *Error

WithMeta attaches a key/value pair for internal logging. Meta is never serialised to API responses.

type FieldError

FieldError describes a validation failure for a single field. It carries no HTTP-specific concepts.

type FieldError struct {
    Field   string
    Code    string
    Message string
    Params  map[string]any
}

func NewFieldError

func NewFieldError(field, code, message string) FieldError

NewFieldError constructs a FieldError without params.

func NewFieldErrorWithParams

func NewFieldErrorWithParams(field, code, message string, params map[string]any) FieldError

NewFieldErrorWithParams constructs a FieldError with extra context params (e.g. min_length, max).

Generated by gomarkdoc