errs

README

errs

This package provides a simple error type that can be used to map errors to HTTP and GRPC status codes.

It is heavily inspired by encore.dev/beta/errs but adds support for GRPC codes.

Usage

• go docs https://pkg.go.dev/github.com/lordvidex/errs
• check the tests for usage and examples

References

• google.golang.org/grpc/codes for grpc codes

Documentation

Index

• Constants
• func Wrap(err error, message string, stacktrace ...any) error
• func WrapCode(err error, message string, code Code, stacktrace ...any) error
• type Builder
  • func B() *Builder
  • func (b *Builder) Code(code Code) *Builder
  • func (b *Builder) Details(details ...any) *Builder
  • func (b *Builder) Err() error
  • func (b *Builder) Msg(msg string) *Builder
  • func (b *Builder) Msgf(format string, parameters ...any) *Builder
• type Code
  • func (c Code) GRPC() codes.Code
  • func (c Code) HTTP() int
  • func (c Code) MarshalJSON() ([]byte, error)
  • func (c Code) String() string
• type Error
  • func (e *Error) Error() string

Examples

• Builder
• Builder.Msgf
• Error.Error

Constants

const CodeSize = 15

CodeSize is the number of codes defined in the STL library. All codes defined by default are mapped from 0 to CodeSize - 1.

Functions

func Wrap

func Wrap(err error, message string, stacktrace ...any) error

func WrapCode

func WrapCode(err error, message string, code Code, stacktrace ...any) error

Types

type Builder

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

Example

b := B().Code(Unknown).Msg("unknown error").Details("details")
err := b.Err()
str, _ := json.Marshal(err)
fmt.Println(string(str))

Output:
{"code":"unknown","message":"unknown error"}

func B

func B() *Builder

B returns a new error builder.

func (*Builder) Code

func (b *Builder) Code(code Code) *Builder

func (*Builder) Details

func (b *Builder) Details(details ...any) *Builder

func (*Builder) Err

func (b *Builder) Err() error

func (*Builder) Msg

func (b *Builder) Msg(msg string) *Builder

func (*Builder) Msgf

func (b *Builder) Msgf(format string, parameters ...any) *Builder

Example

b := B().Code(NotFound).Msgf("file not found: %s, %d", "details", 123)
err := b.Err()
str, _ := json.Marshal(err)
fmt.Println(string(str))

Output:
{"code":"not_found","message":"file not found: details, 123"}

type Code

type Code int

Code is the type that represents an error code. It can map to HTTP and gRPC codes.

const (
	// Unknown is the default error code.
	Unknown Code = iota

	// Canceled indicates the operation was canceled or unavailable because it was cancelled.
	Canceled

	// InvalidArgument is used when the client sends invalid arguments.
	InvalidArgument

	// DeadlineExceeded means operation expired before completion. This doesn't necessarily mean that the operation failed.
	// It is possible that the operation succeeded but the deadline was exceeded.
	DeadlineExceeded

	// Unauthenticated is used when the client is not authenticated.
	Unauthenticated

	// NotFound is used when the requested resource is not found.
	NotFound

	// AlreadyExists is used when the resource already exists.
	AlreadyExists

	// Forbidden is used when the client is not authorized to perform the requested operation.
	Forbidden

	// ResourceExhausted is used when the client has exhausted some resource.
	ResourceExhausted

	// FailedPrecondition is used when the client sends a request that is not allowed in the current state.
	FailedPrecondition

	// Aborted is used when the client sends a request that cannot be completed due to a conflict e.g. a concurrency issue.
	Aborted

	// OutOfRange means that the operation was attempted past the valid range.
	OutOfRange

	// Internal is used when an internal error occurs.
	Internal

	// Unavailable is used when the service cannot be reached due to some network issues.
	Unavailable

	// DataLoss is used when the service has lost some data.
	DataLoss
)

func (Code) GRPC

func (c Code) GRPC() codes.Code

func (Code) HTTP

func (c Code) HTTP() int

func (Code) MarshalJSON

func (c Code) MarshalJSON() ([]byte, error)

func (Code) String

func (c Code) String() string

type Error

type Error struct {
	// Code is the error code of the error. When marshaled to JSON, it will be a string.
	Code Code `json:"code"`

	// Msg is the user-friendly message returned to the client.
	Msg string `json:"message"`

	// Details is the internal error message returned to the developer.
	Details []any `json:"-"`
}

func (*Error) Error

func (e *Error) Error() string

Example

err := B().Code(NotFound).Msg("item not found").Err()
fmt.Println(err.Error())

Output:
not_found: item not found