golazy.dev – golazy.dev / lazyerrors Index | Files

package lazyerrors 

import "golazy.dev/lazyerrors"

Package lazyerrors records caller context and backtraces on ordinary Go errors.

Use New at the point where application code knows what operation failed: 

return lazyerrors.New("load post %q: %w", postID, err)

New formats the message like fmt.Errorf, captures the caller's stack, and prefixes Error with the first recorded function. A controller method that returns the error above might therefore render or log a message such as "posts.PostsController.Show: load post \"hello\": not found". The prefix is meant to answer "where was this error created?" without requiring every caller to repeat its own function name in the message.

Wrapping works the same way as fmt.Errorf. If the format string contains one %w, the returned error implements Unwrap() error. If it contains multiple %w verbs, the returned error implements Unwrap() []error. That means errors.Is and errors.As keep working for the original cause while the lazyerrors wrapper adds the caller prefix and backtrace.

The backtrace is intentionally small and application-facing. It starts at the caller of New, stores up to the internal frame limit, and is exposed through a Backtrace() []Frame method. There is no exported concrete error type; code that needs the trace should use errors.As with a local interface: 

var traced interface {
	Backtrace() []lazyerrors.Frame
}
if errors.As(err, &traced) {
	frames := traced.Backtrace()
	_ = frames
}

Frame.String returns a compact "function file:line" string for logs, while the Function, File, and Line fields remain available to render richer output. Backtrace returns a copy, so callers may sort or trim the returned slice without mutating the error.

In a GoLazy application, lazycontroller's error handling recognizes any error with Backtrace() []lazyerrors.Frame. When detail errors are enabled, the default error view receives the formatted error and backtrace data so it can show the source frames. lazyapp wires that controller error handling and the app error views into the HTTP stack; application code only needs to return or report the lazyerrors.New error from its controllers or services. Production error pages still hide details unless the app explicitly enables detailed errors.

The package is also useful outside GoLazy. It depends only on the standard library, preserves normal wrapping semantics, and can be used in services, CLIs, workers, or tests that want errors with caller context and an inspectable stack without adopting the rest of the framework.

Functions

func New

New formats an error like fmt.Errorf, prefixes it with the caller name, and records a backtrace beginning at the caller. 

func New(format string, args ...any) error

Types