structurederror

README

Structured Error

Structured Error is a little library to help build "structured" errors. For our purposes, a "structured error" is one that has a message, followed by a series of key/value pairs. Each key/value pair is in the form of "key: value", and each pair is seperated by a delimiter. The default delimiter is "-", but it can be changed.

Example

maker := structurederror.New()
err := maker("error message here", "key", "value")
// err == "error message here - key: value"

Arguments

Arguments are either key/value pairs, where the key can be coerced to a string type, an ErrorArg, or a slice of ErrorArgs. An ErrorArg is just a structure with key and value properties.

type ErrorArg struct {
  Key   string
  Value any
}

The ErrorArg struct allows you to do interesting things, like build functions that can parse data and return an ErrorArg. For example:

func ParseTheThing(someImput string) structurederror.ErrorArg {
    // parse the stuff
    return structurederror.ErrorArg{
        Key: "parserOutput",
        Value: "some value",
    }
}

err := maker("some error", ParseTheThing("some input"))
// err == "some error - parserOutput: some input"

You can also use a slice of ErrorArg as an argument to StructuredError. Here is a sample.

func ParseTheThings(someImput string) []structurederror.ErrorArg {
  // parse the stuff
  return []structurederror.ErrorArg{
    {
      Key: "key1",
      Value: "value1",
    },
    {
      Key: "key2",
      Value: "value2",
    },
  }
}

err := maker("some error", ParseTheThings("some input"))
// err == "some error - key1: value1 - key2: value2

Options

The structured error maker can be configured with options. Below are the available options.

WithDelimiter

WithDelimiter allows you to change the delimiter used between key/value pairs. The default value is "-".

maker := structurederror.New(
  structurederror.WithDelimiter(";;"),
)

WithSlog

WithSlog will call the Error() method on a provided logger when the error is created. Here is an example.

logger := slog.New(slog.Default().Handler())

maker := structurederror.New(
  structurederror.WithSlog(logger),
)

err := maker("some error", "key", "value")
// This will output to stdout:
// 2024/11/19 16:22:00 ERROR some error key=value

Included Parsers

Below are some included parsers that can add context to your error.

Http Client Error Parser

This provides a function that takes an *http.Response and will break it down into a slice of ErrorArgs. By default it only includes the status code, but with options, you can include the status line and body.

maker := structurederror.New()

err := maker(
  "some error", 
  httpclientparser.Parse(
    resp,
    httpclientparser.WithStatus(),
    httpclientparser.WithBody(),
  ),
)

// err == "some error - body: HTTP response body goes here - status: 500 Internal Server Error - statusCode: 500"

Documentation

Index

• type ErrorArg
• type ErrorMaker
  • func New(options ...ErrorMakerOption) ErrorMaker
• type ErrorMakerOption
  • func WithDelimiter(delimiter string) ErrorMakerOption
  • func WithSlog(logger *slog.Logger) ErrorMakerOption
• type StructuredError
  • func (se *StructuredError) Error() string

Types

type ErrorArg

type ErrorArg struct {
	Key   string
	Value any
}

type ErrorMaker

type ErrorMaker func(message string, args ...any) *StructuredError

func New

func New(options ...ErrorMakerOption) ErrorMaker

New creates a new error maker. An error maker is a function that accepts an error message and a series of arguments. Args can be either key/value pairs, or an ErrorArg struct. "Key" is expected to be "stringy".

type ErrorMakerOption

type ErrorMakerOption func(*StructuredError)

func WithDelimiter

func WithDelimiter(delimiter string) ErrorMakerOption

WithDelimiter allows you to configure a StructuredError's arg delimiter.

func WithSlog

func WithSlog(logger *slog.Logger) ErrorMakerOption

WithSlog tells the maker to call the provided logger Error method, using Args as key value pairs in the log. This happens when you create the error.

type StructuredError

type StructuredError struct {
	Message string
	Args    map[string]any

	Delimiter string
	Logger    *slog.Logger
}

StructuredError is a way to craft errors using similar semantics to slog.

func (*StructuredError) Error

func (se *StructuredError) Error() string

Error implements the Error value interface.