From a47526df456380300e4fa39f63ca42be5825c138 Mon Sep 17 00:00:00 2001 From: Josue Giron Date: Sat, 21 Nov 2026 19:07:25 +0000 Subject: [PATCH] feat: add Detail accessor and deprecate Wrapper Detail returns the text of the wrapped cause, which log reads for its debug attribute. The exported Wrapper field ties the public API to github.com/go-errors/errors; it is deprecated in favor of Detail, StackTrace and StackTraceStr and will be removed in v0.8.0 (ERR-07). Co-Authored-By: Claude Opus 5.5 --- README.md | 4 +++- errors.go | 27 ++++++++++++++++++++++++--- errors_test.go | 38 ++++++++++++++++++++++++++++++++++++++ example_test.go | 11 +++++++++++ 4 files changed, 76 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 407d65f..2a9276a 100644 --- a/README.md +++ b/README.md @@ -157,7 +157,9 @@ Built-in codes carry kinds: `ValRequired`, `ValFormat` and `AppValidation` are v ## Stack Traces -`StackTraceStr` returns a text stack trace. `StackTrace` returns a `slog.Value` group that can be attached to structured logs. Stack traces can contain source paths and function names, so keep them in internal logs only. +`StackTraceStr` returns a text stack trace. `StackTrace` returns a `slog.Value` group that can be attached to structured logs. `Detail` returns the text of the wrapped cause without the error's own code and friendly message (a wrapped `*Error` keeps its own `[code](message)` prefix). Stack traces and details can contain source paths, function names and other implementation details, so keep them in internal logs only. + +The exported `Wrapper` field is deprecated since v0.7.0 and will be removed in v0.8.0: use `Detail` for the cause's text and `StackTrace` or `StackTraceStr` for the stack. ```go slog.Error("operation failed", "error", err, "stack", err.(*jerrors.Error).StackTrace()) diff --git a/errors.go b/errors.go index 0579fab..c0b6bf3 100644 --- a/errors.go +++ b/errors.go @@ -11,6 +11,11 @@ import ( // Error wraps another error with a stack trace, optional friendly message, and optional code. type Error struct { + // Wrapper holds the wrapped cause and the stack trace captured with it. + // + // Deprecated: use Detail for the wrapped cause's text and StackTrace or + // StackTraceStr for the stack trace. Wrapper exposes + // github.com/go-errors/errors and will be removed in v0.8.0. Wrapper *errors.Error Message string // A non-technical, user-friendly message describing the error. cause error @@ -20,6 +25,22 @@ type Error struct { defined bool } +// Detail returns the full text of the error this Error wraps, without this +// Error's own code and friendly message: the formatted text for New and NewC, +// the sentinel's message for Wrap of a Define sentinel, and otherwise the text +// of the wrapped error, which includes its own code prefix and message when it +// is an *Error. It returns "" for a nil receiver and for an error without a +// stack trace, such as a Define sentinel. +// Like the stack trace, it can contain implementation details; keep it in +// internal logs and return PublicMessage to users. +func (err *Error) Detail() string { + if err == nil || err.Wrapper == nil { + return "" + } + + return err.Wrapper.Error() +} + // StackTraceStr returns the stack trace captured when this Error was created. func (err *Error) StackTraceStr() string { if err == nil || err.Wrapper == nil { @@ -34,11 +55,11 @@ func (err *Error) StackTraceStr() string { buffer.WriteString(err.Message) buffer.WriteString("\n\n") buffer.WriteString("ยท Cause: ") - buffer.WriteString(err.Wrapper.Error()) + buffer.WriteString(err.Detail()) buffer.WriteString("\n\n") } else { buffer.WriteString("\n\n") - buffer.WriteString(err.Wrapper.Error()) + buffer.WriteString(err.Detail()) buffer.WriteString("\n\n") } @@ -146,7 +167,7 @@ func (err *Error) prefix() string { // the same code, its own prefix and the separator after it are cut from its // text, and onlyPrefix reports that nothing else was left to print. func (err *Error) wrappedText() (text string, onlyPrefix bool) { - full := err.Wrapper.Error() + full := err.Detail() inner, ok := err.Wrapper.Err.(*Error) if !ok || inner == nil || !sameCode(inner.Code, err.Code) { return full, false diff --git a/errors_test.go b/errors_test.go index 86991a8..9373d91 100644 --- a/errors_test.go +++ b/errors_test.go @@ -616,3 +616,41 @@ func expectedFrameTexts(err *Error) (string, []slog.Attr) { } return buffer.String(), attrs } + +func TestDetailReturnsWrappedCauseText(t *testing.T) { + inner := NewC(codes.AppValidation, "title is empty") + tests := []struct { + name string + err error + want string + }{ + {name: "New", err: New("disk %s", "full"), want: "disk full"}, + {name: "NewC", err: NewC(codes.AppValidation, "title is empty"), want: "title is empty"}, + {name: "Wrap of a plain error", err: Wrap(stderrors.New("timeout")), want: "timeout"}, + {name: "With", err: With(stderrors.New("timeout"), "loading board"), want: "timeout"}, + {name: "WithC", err: WithC(stderrors.New("timeout"), codes.AppProcessing, "loading board"), want: "timeout"}, + {name: "WrapC of an *Error without cause", err: WrapC(inner, codes.AppProcessing), want: inner.Error()}, + {name: "WrapC of an *Error wraps its cause", err: WrapC(With(stderrors.New("timeout"), "loading"), codes.AppProcessing), want: "timeout"}, + {name: "With of an *Error", err: With(inner, "saving"), want: inner.Error()}, + {name: "Wrap of a Define sentinel", err: Wrap(errDefinedTitleRequired), want: "title is required"}, + {name: "Define sentinel has no detail", err: errDefinedTitleRequired, want: ""}, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + got := test.err.(*Error).Detail() + + if got != test.want { + t.Fatalf("Expected %q, got %q", test.want, got) + } + }) + } +} + +func TestDetailOfNilErrorIsEmpty(t *testing.T) { + var err *Error + + if got := err.Detail(); got != "" { + t.Fatalf("Expected empty detail, got %q", got) + } +} diff --git a/example_test.go b/example_test.go index 12496da..7401e80 100644 --- a/example_test.go +++ b/example_test.go @@ -37,3 +37,14 @@ func ExampleKindOf() { // validation // true } + +func ExampleError_Detail() { + err := jerrors.With(stderrors.New("connection refused"), "loading board") + + var coded *jerrors.Error + if stderrors.As(err, &coded) { + fmt.Println(coded.Detail()) + } + // Output: + // connection refused +}