flaw

README

Flaw

Go errors with contextual info.

Usage

Checkout the example directory for usage example with zerolog.

Documentation

Index

• type Flaw
  • func From(err error) *Flaw
  • func (f *Flaw) Append(payload P, payloads ...P) *Flaw
  • func (f *Flaw) Error() string
  • func (f *Flaw) Join(err error) *Flaw
• type JoinedError
• type P
• type Record
• type StackTrace

Types

type Flaw

type Flaw struct {
	// Inner is the error string that was passed in during initialization.
	Inner string
	// JoinedErrors is the list of optional (nil-able) errors
	// joined into the error while traversing the stack back,
	// usually in the same function initiated the error.
	JoinedErrors []JoinedError
	// Records contains contextual information in order the error traversed the stack up,
	// i.e., the first item in the slice is the first record attached to the error,
	// and the last item is the most recent attached record.
	Records    []Record
	StackTrace []StackTrace
}

func From

func From(err error) *Flaw

From creates a Flaw instance from an existing error. You can append contextual information to it using the Flaw.Append function immediately after instantiation, or by the caller function, after making sure the returned error is of type Flaw (using errors.As), It panics if err is nil.

func (*Flaw) Append

func (f *Flaw) Append(payload P, payloads ...P) *Flaw

Append appends contextual information to Flaw instance. It can be called immediately after instantiation using From, or by the parent caller function, after making sure the returned error is of type Flaw (using errors.As). It panics if payload is nil. Elements in payloads will be merged into payload in order they are provided, thus duplicate keys will be overwritten.

func (*Flaw) Error

func (f *Flaw) Error() string

Error satisfies builtin error interface type. It returns the inner error string.

func (*Flaw) Join

func (f *Flaw) Join(err error) *Flaw

Join joins the error to the flaw as a JoinedError item. Usually, used in failed defer calls where the deferred function fails with another error, and it is desired to capture the information of the error, and attach it to the original error.

type JoinedError

type JoinedError struct {
	// Message is the result of joined error Error method call.
	Message string
	// CallerStackTrace is the error generator stack trace,
	// which in a very rare case can be nil. See [runtime.CallersFrames],
	// and [runtime.Callers] for more information on when this might happen.
	CallerStackTrace *StackTrace
}

type P

type P map[string]any

P is shorthand for Record.Payload type

type Record

type Record struct {
	Function string
	Payload  P
}

type StackTrace

type StackTrace struct {
	// Line is the file line number of the location in this frame.
	// For non-leaf frames, this will be the location of a call.
	// This may be zero, if not known.
	Line int
	// File is the file name of the location in this frame.
	// For non-leaf frames, this will be the location of a call.
	// This may be the empty string if not known.
	File string
	// Function is the package path-qualified function name of
	// this call frame. If non-empty, this string uniquely
	// identifies a single function in the program.
	// This may be the empty string if not known.
	Function string
}