serrors

KO | EN

gitlite — search

#python #react #go #android #machine-learning #rust #deep-learning #linux #macos #java #awesome #kubernetes #vue #awesome-list

(★ 10)

Structured errors for Go: sentinel hierarchies, typed data, custom formatting, and slog integration.

serrors 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# `serrors` - Structured Errors for Go

[![CI](https://github.com/MarwanAlsoltany/serrors/actions/workflows/ci.yml/badge.svg)](https://github.com/MarwanAlsoltany/serrors/actions/workflows/ci.yml)
[![Go Reference](https://pkg.go.dev/badge/github.com/MarwanAlsoltany/serrors.svg)](https://pkg.go.dev/github.com/MarwanAlsoltany/serrors)
[![Go Report Card](https://goreportcard.com/badge/github.com/MarwanAlsoltany/serrors)](https://goreportcard.com/report/github.com/MarwanAlsoltany/serrors)
[![Coverage](https://codecov.io/gh/MarwanAlsoltany/serrors/branch/master/graph/badge.svg)](https://codecov.io/gh/MarwanAlsoltany/serrors)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://raw.githubusercontent.com/MarwanAlsoltany/serrors/master/LICENSE)

Go's standard error handling is minimal by design. It provides `errors.New`, `fmt.Errorf`, `errors.Unwrap`, `errors.Join`, `errors.Is`, `errors.As`, and then gets out of the way. For small programs, that is exactly right. For larger systems built from multiple layers and packages, the minimal approach leaves much to be desired and several practical problems unsolved.

The key insight the standard library encodes — and that many codebases fail to act on — is that <u>**errors are values**</u>. Unlike exceptions, they are not just signals that "something went wrong"; they carry meaning, context, and identity that can be inspected, matched, and acted upon programmatically. `fmt.Errorf` with `%w` gets partway there, but it stops at wrapping: the resulting value carries the chain but exposes none of the structure. `serrors` exists to fill that gap. It takes that idea to its logical conclusion: errors are first-class, typed, structured values with an identity, an operation chain, attached data, and a formatting contract.

The name follows the same convention as `slog` to `log`: the `s` stands for *structured*. Just as `slog` brought key-value context to logging, `serrors` brings structure, hierarchy, custom formatting, and inspection to errors without breaking compatibility with the standard library or introducing foreign concepts.

`serrors` is opinionated. It makes deliberate choices about error message format, delimiter conventions, and the shape of the public API. If any of those choices fit your codebase well, `serrors` will be a natural starting point. If they conflict with existing conventions, the formatting pipeline is customizable enough to accommodate most requirements, and the library is small enough to fork or vendor if deeper changes are needed. This is the kind of library you'll know when you need it, it is not meant for every use case.

## The Problem

### 1. Errors lose context as they travel up the stack

A common Go pattern is:

```go
if err != nil {
    return fmt.Errorf("database connect: %w", err)
}
```

This works, but there is no standard way to extract `"database connect"` programmatically. If the failed operation needs to be logged or reacted upon, the code must parse the error string. If tests or middleware need to match on the operation, they cannot do so reliably.

### 2. Flat sentinel errors do not compose

The standard approach to sentinel errors is:

```go
var ErrNotFound         = errors.New("not found")
var ErrUserNotFound     = errors.New("user not found")
var ErrPermissionDenied = errors.New("permission denied")
```

These are flat, independent values. There is no way to express that `ErrUserNotFound` is a specialization of `ErrNotFound`. A caller that wants to handle all "not found" variants must enumerate every sentinel explicitly. Adding a new one requires updating every `errors.Is` check that should cover it, a maintenance problem that grows with the error tree and application complexity.

### 3. There is no standard format for error messages

`fmt.Errorf("%w: %s", ErrBase, "detail")` is the de-facto way to attach detail to a sentinel at runtime. It returns a `*fmt.wrapError`, not a structured type. The standard library imposes no structure on the resulting string, so every package invents its own conventions. When the underlying error already contains a label prefix, wrapping it again produces `"app: op: app: nested op: cause"`; a doubled label with no way to strip it. There is also no way to register a custom formatter for a third-party error type that appears somewhere deep in the chain.

### 4. Structured data cannot be attached to an error without a custom type

Errors that carry context (a request ID, a host name, a retry count) have no standard home for that data. The options are to embed the values in the error string (losing machine-readability), or to define a bespoke error struct for every context type (boilerplate at every layer of the stack). Neither composes well across package boundaries.

### 5. There is no call-site location without a debugger

By the time an error reaches a log statement or a top-level handler, there is no record of which file and line it came from. The only options are to print a full stack trace on every error (noise) or to manually attach caller information (boilerplate that is easy to forget).

### 6. Logging a rich error requires inspection boilerplate

There is no standard way to pass a structured error to `slog` and get key-value output. The typical pattern is a chain of `errors.As` calls that extract fields and build attributes manually; duplicating structure that is already inside the error and coupling the logging code to the error's internals.

## The Solution

`serrors` solves these problems with a small set of composable ideas:

1. **Domain isolation**: a `Domain` owns a label and formatting chain and produces all its `*Error` values. Two concerns using `serrors` share no state unless they explicitly share a `Domain` instance.
2. **Structured errors**: `Error` carries an `Op` string (the operation/operator/component name), an underlying `Err`, and an optional `Data` field for structured context. `Data` is **invisible** to `Error()` but fully **accessible** for logging and programmatic inspection.
3. **Sentinel hierarchy API** (`Sentinel`, `Derive`, `Detail`, `Detailf`): replaces flat `errors.New` and `fmt.Errorf` wrappers for static package-level error variables, giving every node a parent it automatically matches via `errors.Is`.
4. **Three-layer formatting pipeline** (`FormatFunc`, `Delimiters`, `Formatter`): controls how individual leaf errors render, how ops and labels are joined, and how the final string is assembled; each layer is independently customizable per domain.
5. **Opt-in stack traces** via `CaptureStackTrace()`, passed as the `data` argument to `WrapWith`. No global flag; a trace is captured only where explicitly requested, stored as a typed `StackTrace` in `Error.Data` like any other context.
6. **Native `slog` integration**: `*Error` implements `slog.LogValuer`. Passing an error to any slog call automatically emits its message and all structured `Data` as grouped attributes, no manual extraction needed.

Everything produced by `serrors` is compatible with the standard library: `errors.Is`, `errors.As` (and `errors.AsType[T]`), and `errors.Unwrap` all work as expected.

## API Design Philosophy

`serrors` keeps its API surface small, built around a few orthogonal primitives rather than a wide family of convenience wrappers.

Many error libraries grow by layering `With*` helpers for every wrapping variation, which fragments the API and increases cognitive load. `serrors` instead provides `Domain.Sentinel`, `Domain.Wrap`, `Domain.WrapWith`, `Error.Derive`, `Error.Detail`, and domain-level configuration; primitives expressive enough to cover common use cases without narrowly scoped helpers for every variation.

This keeps the package lightweight:

* **Conceptually**: fewer entry points, consistent mental model.
* **Practically**: less API surface to learn, document, and maintain.
* **Operationally**: no hidden behavior, no global switches, no implicit overhead.

When additional control is needed, it comes through explicit mechanisms (structured `Data`, domain-scoped formatters, and delimiter configuration) not by expanding the function set.

## Compared to Existing Packages

`serrors` sits in the same space as `github.com/pkg/errors`, `go.uber.org/multierr`, `github.com/cockroachdb/errors`, and the Kubernetes error helpers, but consolidates their most useful ideas into a single domain-scoped model: hierarchical sentinels, structured data, opt-in stack traces, customizable formatting, and standard library interoperability.

Unlike those libraries, `serrors` is deliberately the lightest: no global switches, no mandatory stack-trace overhead, no hidden framework behavior. Errors are created and extended explicitly, no implicit annotation, automatic wrapping, or background propagation of context.

`serrors` does not replace the standard library or impose a new error model. It extends the existing one, remaining fully compatible with `error`, `fmt.Errorf`, `errors.Is`, and `errors.As`. It can be introduced incrementally: used where structure and inspection are needed, and set aside where they are not. Every `*Error` value produced by `serrors`:

* Satisfies the `error` interface.
* Works with `errors.Is` and `errors.As*` out of the box.
* Chains correctly with `errors.Unwrap`.
* Composes with `errors.Join` results.

## Installation

```sh
go get github.com/MarwanAlsoltany/serrors
```

## Examples

Runnable, self-verifying examples covering all major patterns are in [`example_test.go`](./example_test.go). They are compiled and executed on every `go test ./...` run and are rendered automatically on [pkg.go.dev](https://pkg.go.dev/github.com/MarwanAlsoltany/serrors) alongside the API documentation.

## Quick Start

This package supports two modes of operation: package-level functions on a default domain (suitable for most small applications), and explicit `Domain` instances for library authors or multi-domain applications that need isolated error namespaces.

**Example** (package-level, using the default domain):

```go
import (
    "database/sql"

_ "github.com/lib/pq"
    "github.com/MarwanAlsoltany/serrors"
)

func openDB(dsn string) error {
    db, err := sql.Open("postgres", dsn)
    if err != nil {
        // wrap a low-level error with operation context
        return serrors.Wrap("database open", err)
    }
    return db.Ping()
}
```

The error message will be:

```txt
error: database open: dial tcp: connection refused
```

The label (`"error"`) is the default. Can be freely changed to match some package:

> **Note:** The default label `"error"` is deliberately non-idiomatic. It is meant to stand out and prompt replacement with a meaningful name.

```go
func init() { serrors.SetDefault(serrors.New("my-app")) }
// or omitted entirely with serrors.New("")
```

Now the same error reads:

```txt
my-app: database open: dial tcp: connection refused
```

## Sentinel Hierarchies

This is where `serrors` diverges most visibly from the standard library to provide a better experience for static sentinels.

With the standard library, sentinels are typically defined as `var ErrX = errors.New("x")`, which means they are flat and cannot express parent-child relationships.

A typical package declares its error tree once, at the package level, and everything else uses those sentinels. With `serrors` the whole tree is composed of `*Error` values (satisfying `error` interface), which means every node is inspectable and participates in `errors.Is` traversal automatically. Making it possible to catch not only operation failures but complete component/subsystem failure by matching on a root sentinel.

```go
var domain = serrors.New("my-app")

// top-level sentinels: domain.Sentinel() creates an *Error with no parent
// which serves as a root for its subtree
var (
    ErrAuth     = domain.Sentinel("auth")
    ErrNetwork  = domain.Sentinel("network")
    ErrDatabase = domain.Sentinel("database")
)

// child sentinels: Err*.Derive() creates an *Error that wraps its parent (top-level sentinel)
var (
    ErrAuthExpired = ErrAuth.Derive("token expired")
    ErrAuthInvalid = ErrAuth.Derive("token invalid")

ErrNetworkDial    = ErrNetwork.Derive("dial")
    ErrNetworkTLSHand = ErrNetwork.Derive("tls handshake")

ErrDatabaseConnect = ErrDatabase.Derive("connect")
    ErrDatabaseTimeout = ErrDatabase.Derive("timeout")
    ErrDatabaseQuery   = ErrDatabase.Derive("query")
)

// leaf detail: .Detail() and .Detailf() wrap an *Error with a plain message string,
// useful when a specific error string is needed but not a named sentinel
return ErrNetworkDial.Detail("connection refused")
return ErrDatabaseConnect.Detailf("timed out after %ds", int(timeout/time.Second))
```

Every node in this tree automatically satisfies:

```go
errors.Is(ErrDatabaseTimeout, ErrDatabase) // true
errors.Is(ErrDatabaseConnect, ErrDatabase) // true
errors.Is(ErrDatabaseQuery, ErrDatabase) // true
errors.Is(ErrDatabase, domain.Root()) // true
```

The full hierarchy is provided for free, with no need for custom `Is` methods or manual wrapping.

### `Derive` vs. `Detail`/`Detailf`

| | `Derive(op)` | `Detail(msg)` / `Detailf(fmt, args...)` |
| --- | ------------ | -------------------------------------- |
| Return value | `*Error` | `error` |
| `errors.Is` inspectable | yes | yes |
| `errors.As` inspectable | yes, `Op` field | yes, parent `*Error.Op` only (detail text is plain string) |
| Wrapping with `%w` | no | `Detailf` only |
| Participates in formatters | yes | no (plain `fmt.Errorf` wrap) |
| Best used for | named sentinels in error tree | one-off detail on a leaf |

The `error` return type for `Detail*` is intentional: the message does not belong on `*Error.Op`, which is structurally an operation name, not a message string. `Detailf` also delegates to `fmt.Errorf` internally, making `*Error` impossible to return without reimplementing `%w` semantics. See the `Detail` source doc comment for the full rationale.

`Detailf` supports `%w`, so any wrapped error remains reachable via `errors.Is` and `errors.As`:

```go
err := ErrService.Detailf("query failed: %w", pkgErr)
// errors.Is(err, pkgErr) == true
```

The rule of thumb: if the error appears as a package-level `var`, use `Error.Derive`. For adding a runtime detail to an existing sentinel at the call-site, use `Error.Detail*`, or `Domain.Wrap*`.

## Wrapping Runtime Errors

For errors that are not static sentinels but carry runtime context, use `Wrap` and `Wrapf`:

```go
func (s *Store) QueryUser(id string) (*User, error) {
    row := s.db.QueryRow("SELECT * FROM users WHERE id = $1", id)
    if err := row.Scan(...); err != nil {
        // wrap the database error under the "query user" operation
        return nil, domain.Wrap("query user", err)
    }
    return user, nil
}

func (s *Store) CreateUser(u *User) error {
    if err := validate(u); err != nil {
        // formatted detail message
        return domain.Wrapf("create user", "validation failed for email %q: %w", u.Email, err)
    }
    // ...
}
```

`Wrap` also supports multiple errors in a single call (delegates to `errors.Join` internally):

```go
var errs []error
for _, item := range batch {
    if err := process(item); err != nil {
        errs = append(errs, err)
    }
}
// returns nil if errs is empty or all-nil, no guard needed
return domain.Wrap("process batch", errs...)
```

The output for a multi-error result is a compact single-line (unlike the default multi-line `errors.Join` format):

> The `":"` and `";"` delimiters are configurable via `WithDelimiters`.

```txt
my-app: process batch: item 2: invalid; item 5: not found; item 9: timed out
```

### Attaching Structured Data

Use `WrapWith` and `WrapWithf` to attach arbitrary structured context to an error without embedding it in the error string. The data is stored in `Error.Data` and is retrievable programmatically, but is ***intentionally*** excluded from `Error.Error()`, keeping messages clean while still providing rich context for logging and inspection.

```go
type ConnCtx struct {
    Host    string
    Attempt int
}

// optional: implement slog.LogValuer for automatic slog expansion
func (c ConnCtx) LogValue() slog.Value {
    return slog.GroupValue(
        slog.String("host", c.Host),
        slog.Int("attempt", c.Attempt),
    )
}

func dial(host string, attempt int) error {
    conn, err := net.Dial("tcp", host)
    if err != nil {
        return domain.WrapWith("dial", ConnCtx{host, attempt}, err)
    }
    return nil
}
```

Raw `[]slog.Attr` slices are also accepted directly:

```go
return domain.WrapWith("dial",
    []slog.Attr{slog.String("host", host), slog.Int("attempt", n)},
    err,
)
```

See the next section for how to retrieve and log the attached data.

## Inspecting Errors

All standard library inspection tools work unchanged:

```go
// check for a sentinel (works at any depth in the chain)
if errors.Is(err, ErrDatabase) {
    log.Warn("database error", "err", err)
}

// extract the operation name
var opErr *serrors.Error
if errors.As(err, &opErr) {
    metrics.Increment("errors", "op", opErr.Op)
}

// check for a concrete underlying type
if pkgErr := errors.AsType[*pkg.Error](err); pkgErr != nil {
    if pkgErr.Code == "123" {
        return ErrSomeError
    }
}
```

Because `*Error` implements `Unwrap()`, the entire standard library chain-walking machinery traverses it correctly and as one would expect.

`serrors` also provides a set of one-liner helpers that avoid the boilerplate of declaring a temporary variable and calling `errors.As` manually:

```go
// extract the first *Error in the chain without a temporary variable
if e, ok := serrors.AsError(err); ok {
    metrics.Increment("errors", "op", e.Op)
    // e.Domain is also accessible, the Domain that produced the error
}

// first non-nil Data of the given type in the chain
ctx, ok := serrors.AnyDataAs[ConnCtx](err)

// all non-nil Data values of the given type in the chain, outermost first
ctxs := serrors.AllDataAs[any](err)

// walk the full chain
serrors.Walk(err, func(e *serrors.Error) bool {
    fmt.Println(e.Op, e.Data)
    return true
})

// check whether an error belongs to a specific domain
if domain.Contains(err) {
    // equivalent to errors.Is(err, domain.Root())
}
```

### Accessing Structured Data

`Error.Data` is the structured context attached via `WrapWith`/`WrapWithf`. It is not part of the error string, so it must be retrieved programmatically.

**Direct type assertion**, when only one layer of context is expected:

```go
var opErr *serrors.Error
if errors.As(err, &opErr) && opErr.Data != nil {
    if errCtx, ok := opErr.Data.(ConnCtx); ok {
        log.Printf("failed on host %q (attempt=%d)", errCtx.Host, errCtx.Attempt)
    }
}
```

**`AllDataAs`**: collects typed `Data` from every `*Error` node in the chain, outermost first. Useful when multiple wrapping layers each attach context of the same type:

```go
for _, ctx := range serrors.AllDataAs[ConnCtx](err) {
    fmt.Printf("context: %+v\n", ctx)
}
// use serrors.AllDataAs[any](err) to collect all Data values regardless of type
```

**`LogAttrs`**: the slog-oriented counterpart to `AllDataAs`. Walks the chain and converts each `Data` value to `[]slog.Attr` according to these rules:

* `[]slog.Attr`: returned verbatim.
* `slog.LogValuer`: that resolves to a group, the group's attributes are inlined.
* Any other type: wrapped as a single `slog.Any(...)` attribute under the key `DataKey` (`"data"`).

```go
slog.LogAttrs(ctx, slog.LevelError, "dial failed",
    append(serrors.LogAttrs(err), slog.String("err", err.Error()))...,
)
// -> level=ERROR msg="dial failed" host=db attempt=2 err="service: dial: connection refused"
```

`*Error` also implements `slog.LogValuer` directly, so passing it as an slog attribute value is idiomatic and produces the same structured output when `Data` is present; no explicit `LogAttrs` call needed:

```go
// no Data anywhere in chain -> plain string value
slog.Error("dial failed", "err", wrappedErr)
// -> err="service: dial: connection refused"

// with Data -> slog group nested under the key
slog.Error("dial failed", "err", wrappedErr)
// -> err.message="service: dial: connection refused" err.host=db err.attempt=2
```

## Stack Traces

Stack traces are opt-in by design. There is no global flag to activate; a trace is captured only where the consumer explicitly asks for it by passing `CaptureStackTrace()` as the `data` argument to `WrapWith`:

```go
err := domain.WrapWith("op", serrors.CaptureStackTrace(), cause)
```

The returned `StackTrace` is stored in `Error.Data` like any other structured context. The standard inspection API retrieves it, no special functions are needed:

```go
stacks := serrors.AllDataAs[serrors.StackTrace](err)
for _, st := range stacks {
    for _, f := range st.Frames() {
        fmt.Printf("%s:%d %s\n", f.File, f.Line, f.Function)
    }
}
```

### Depth/Skip Control for Helper Wrappers

When `CaptureStackTrace` is called inside a helper function rather than at the actual error site, the helper's frame appears at the top of the trace. Use `CaptureStackTraceN(depth, skip)` and pass 1 for each wrapper layer between the call site and `CaptureStackTraceN`:

```go
func wrapWithTrace(op string, cause error) error {
    // skip=1 removes wrapWithTrace from the top of the stack trace
    return domain.WrapWith(op, serrors.CaptureStackTraceN(serrors.DefaultStackDepth, 1), cause)
}
```

For the common case (i.e. default depth, direct call) `CaptureStackTrace()` is sufficient (captures 32 frames).

### Slog Integration

`StackTrace` implements `slog.LogValuer` as well. When it is stored as `Error.Data`, `LogAttrs` and `Error.LogValue` automatically expand it into a single semicolon-separated string attribute under the key `StackTraceKey` (`"stack"`):

```go
slog.Error("request failed", "err", wrappedErr)
// -> err.message="service: op: cause" err.stack="github.com/user/app/store.go:42 main.openDB; github.com/user/app/main.go:17 main.run"
```

The single-line format is **intentional**, human-readable, searchable, and free of multi-line stack-dump noise.

> **Note:** Build-environment prefixes are stripped from file paths: module cache -> `module@version/file.go`, main module -> `module/file.go`, stdlib -> `package/file.go`.

## Domain Isolation

Each `Domain` has its own label and formatting chain, fully isolated from every other domain. Two packages that both depend on `serrors` share no state:

```go
// in package A:
var domainA = serrors.New("package-a")

serrors.RegisterTypedFormatFunc(domainA, func(e *MyErrorA) string {
    return fmt.Sprintf("A: %s", e.Detail)
})

// in package B:
var domainB = serrors.New("package-b")

serrors.RegisterTypedFormatFunc(domainB, func(e *MyErrorB) string {
    return fmt.Sprintf("B: %s", e.Info)
})
```

Package A's format function never sees Package B's errors and vice versa. The application that imports both can add its own format functions to either domain or to the default one.

### A Complete Library Setup

```go
package library

import (
    "github.com/MarwanAlsoltany/serrors"
)

var domain = serrors.New("my-library")

// exported root for downstream errors.Is checks
var ErrLibrary = domain.Root()

// public error hierarchy
var (
    ErrConfig        = domain.Sentinel("config")
    ErrConfigMissing = ErrConfig.Derive("missing")
    ErrConfigInvalid = ErrConfig.Derive("invalid")

ErrIO         = domain.Sentinel("io")
    ErrIORead     = ErrIO.Derive("read")
    ErrIOWrite    = ErrIO.Derive("write")
    ErrIONotFound = ErrIO.Derive("not found")
)

func init() {
    // register a format function for a third-party
    // error type specific to this library
    serrors.RegisterTypedFormatFunc(domain, func(e *os.PathError) string {
        return fmt.Sprintf("path %q: %s", e.Path, e.Err)
    })
}
```

Consumers of `library` can check:

```go
errors.Is(err, library.ErrConfigMissing) // true; also matches ErrConfig and ErrLibrary
```

### Copying and Extending Domains

Two methods create a new `Domain` derived from an existing one, plus one composable `Option`. They differ in whether a root link is established:

| | `With(opts...)` | `Sub(label, opts...)` |
| --- | --------------- | --------------------- |
| Copies label + config | yes | yes |
| Applies new options | yes | yes |
| Root relationship | independent (no is-a link) | linked (is-a: child root wraps parent root) |
| `errors.Is(childErr, parent.Root())` | false | **true** |
| Best used for | snapshots, reconfigured sibling domain | sub-component inheriting error identity |

This allows for creating intricately structured domain hierarchies with shared or independent configuration as needed.

#### `With`

Returns a copy of the domain with its own independent root sentinel and any provided options applied. Changes to the child (formatters, etc.) do not affect the original. Calling `With` with no options is equivalent to a full clone.

```go
// exact copy, independent root
copy := domain.With()

// peer with a different label but same formatting config
peer := domain.With(serrors.WithLabel("other-service"))
```

#### `Sub`

Creates a sub-domain (child) whose root sentinel wraps the parent's root, establishing an is-a relationship. Errors produced by the child automatically satisfy `errors.Is(err, parent.Root())`. The child inherits the parent's (base's) config (format functions, delimiters, formatter); its label is set by the required `label` argument, not inherited.

```go
var main = serrors.New("main", serrors.WithFormatFunc(sharedFormatter))
var sub = main.Sub("sub-component")

err := sub.Wrap("op", errors.New("x"))
errors.Is(err, sub.Root())  // true
errors.Is(err, main.Root()) // true   <- is-a link
```

#### `WithBase`

The composable option counterpart to `Sub`. Use it with `New` or `With` when the label is set separately or when combining multiple options:

```go
// same effect as main.Sub("sub-component")
sub := serrors.New("sub-component", serrors.WithBase(main))

// start fresh (no config inheritance) with an is-a link and custom delimiters
sub := serrors.New("sub-component", serrors.WithBase(main), serrors.WithDelimiters(custom))
```

Unlike `Sub`, `WithBase` does not set a label; the label is whatever the domain already has or is set explicitly by `WithLabel`.

## Error Formatting

`serrors` produces flat error messages that are a blend of idiomatic Go style and opinionated single-line structure. The messages are friendly to structured log systems, easy to grep, and avoid the multi-line stack-trace noise that plagues some error libraries.

The formatting pipeline has three independent customization points, each operating at a different layer:

| Layer | API | Controls |
| ----- | --- | -------- |
| Leaf text | `FormatFunc` (via `WithFormatFunc`, `RegisterFormatFunc`, `RegisterTypedFormatFunc`) | How individual non-`*Error` errors (i.e. non-`serrors` errors) are rendered into text (i.e. final error string) |
| Delimiters | `Delimiters` (via `WithDelimiters`, `With*Delimiter`) | The delimiter strings that join label, ops, tail, and joined errors |
| Full assembly | `Formatter` (via `WithFormatter`) | The complete output; receives raw structured data and returns the final error string |

Not every application needs all three layers. Start with the narrowest tool and only reach for the next when the previous is insufficient:

1. **`FormatFunc`** is the right choice in most cases. It controls how individual non-`*Error` error types render their text without affecting message structure. This is all most applications ever need.
2. **`Delimiters`** is the right choice when only the separator convention needs to change. It requires no function and has no runtime cost.
3. **`Formatter`** is a last resort. Use it only when the delimiter-based assembly cannot produce the required format; for example, when output must follow an external schema.

To understand why both `FormatFunc` and `Formatter` exist, it helps to know how the default format is assembled. The formatter walks the `*Error` chain collecting ops, then reaches the innermost non-`*Error` error i.e. the **leaf**. The leaf is formatted into a string called the **tail**. The final output is the label, followed by the op chain, followed by the tail, each joined by delimiters:

```txt
<label><delimiter.label><op1><delimiter.part><opN>...<delimiter.part><tail>
```

### Default Format

The default formatter assembles messages in this shape:

```txt
<label>: [<ancestor-op>: ...] <op>: <underlying>
```

When the domain label is empty, the label and its delimiter are omitted entirely:

```txt
[<ancestor-op>: ...] <op>: <underlying>
```

This mirrors how an empty `Op` is silently omitted from the chain. An empty label is valid and can be set via `New("")` or `WithLabel("")` when no prefix is desired.

The three delimiter strings used are:

| Delimiter | Default | Role |
| --------- | ------- | ---- |
| `Label` | `": "` | Between the domain label and the first op or message |
| `Part` | `": "` | Between individual ops and between the last op and the tail |
| `Join` | `"; "` | Between children of a multi-error (`errors.Join`) aggregate |

For a chain like `ErrConfigMissing` above:

```txt
library: config: missing
```

For a wrapped runtime error under `ErrIORead`:

```txt
library: io: read: open /etc/app.conf: no such file or directory
```

For multiple aggregated errors:

```txt
library: io: read: open /etc/a.conf: no such file or directory; open /etc/b.conf: permission denied
```

### Format Functions

Format functions are consulted in reverse registration order; the **last** registered format function to return `ok=true` wins (last-match semantics), this allows overriding previous format functions. If no format function matches — including for foreign types (`fmt.Errorf`, `errors.New`, third-party errors) that may appear anywhere in the chain — the error's own `Error()` method is used as a fallback.

Three ways to register a `FormatFunc` are available, each suited to a different scenario:

#### At Construction Time (`WithFormatFunc`)

**Usage:** When the format function is known at domain setup time and should be part of the domain's permanent configuration. Construction-time format functions are inherited by `Sub` and `With` child domains and cannot be removed after the domain is created. Call `WithFormatFunc` multiple times to register multiple format functions.

```go
domain := serrors.New("app",
    serrors.WithFormatFunc(func(err error) (string, bool) {
        var pkgErr *pkg.Error
        if !errors.As(err, &pkgErr) {
            return "", false
        }
        return fmt.Sprintf("pkg(%s): %s", pkgErr.Code, pkgErr.Message), true
    }),
)
// app: query: pkg(123): something went wrong
```

#### At Runtime - Manual (`RegisterFormatFunc`)

**Usage:** When the format function needs to be registered or unregistered dynamically after the domain is created, or when a single function handles multiple error types. Returns an unregister function so the format function can be unregistered cleanly (e.g. in tests).

```go
unregister := domain.RegisterFormatFunc(func(err error) (string, bool) {
    pkgErr, ok := err.(*pkg.Error)
    if !ok {
        return "", false
    }
    return fmt.Sprintf("pkg-%s: %s", pkgErr.Code, pkgErr.Message), true
})
defer unregister()
```

> **Note:** `RegisterFormatFunc` can be used to register a catch-all format function that handles multiple types in one place, but it requires manual type assertions and nil checks.

#### At Runtime - Type-Safe (`RegisterTypedFormatFunc`)

**Usage:** When only a single concrete error type needs a format function. The generic wrapper handles the type assertion and nil check automatically. The nil check matters here: in Go, a `*pkg.Error` nil stored in an `error` interface is not nil at the interface level, so a naive format function could panic. `serrors` detects and skips typed nils before calling the format function.

```go
unregister := serrors.RegisterTypedFormatFunc(domain, func(err *pkg.Error) string {
    return fmt.Sprintf("pkg: %s (code=%s)", err.Message, err.Code)
})
defer unregister()
```

### Customizing Delimiters

**Usage:** When the default `": "` / `"; "` delimiters clash with surrounding conventions. For example, a log pipeline that already uses `": "` as a field delimiter, or a display format that prefers arrow-separated chains.

Call `WithDelimiters` to replace all three delimiters at once:

```go
domain := serrors.New("service", serrors.WithDelimiters(serrors.Delimiters{
    Label: " | ",
    Part:  " > ",
    Join:  " & ",
}))
// service | op1 > op2 > underlying
// service | op > err a & err b & err c   (multi-error)
```

Individual helpers are also available when only one field needs to change:

```go
domain := serrors.New(
    "service",
    serrors.WithLabelDelimiter(" | "),
    serrors.WithPartDelimiter(" > "),
    serrors.WithJoinDelimiter(" & "),
)
```

### Custom Formatter

**Usage:** When the delimiter-based assembly model is not expressive enough. For example, when the output format must follow an external schema, or when ops should be encoded differently from the tail (e.g. as a path prefix rather than a colon-separated chain).

Implement the `Formatter` interface (or use the `FormatterFunc` adapter) to take full control of the final string. The `Format` method receives the leaf error and a `FormatSpec` containing format specification data:

* `spec.Label`: The domain label string.
* `spec.Ops`: The ordered ops slice, ancestor-first.
* `spec.Delimiters`: The domain's configured delimiters.
* `spec.Apply(err)`: Formats any error through the domain's `FormatFunc` chain, applying last-match semantics and falling back to `err.Error()`. Use this to format both the leaf error and any children of an `errors.Join` aggregate.

```go
domain := serrors.New("app",
    serrors.WithFormatter(serrors.FormatterFunc(func(err error, spec serrors.FormatSpec) string {
        if len(spec.Ops) == 0 {
            return fmt.Sprintf("[%s] %s", spec.Label, spec.Apply(err))
        }
        return fmt.Sprintf("[%s/%s] %s", spec.Label, strings.Join(spec.Ops, "/"), spec.Apply(err))
    })))
// [app/op1/op2] underlying error message
```

Use `DefaultFormatter()` as a base when you only want to wrap or post-process the output rather than replacing it entirely:

```go
base := serrors.DefaultFormatter()
domain := serrors.New("app",
    serrors.WithFormatter(serrors.FormatterFunc(func(err error, spec serrors.FormatSpec) string {
        return "[" + base.Format(err, spec) + "]"
    })))
// [app: op: underlying]
```

### Using All Three Together

For the most control and to produce any output format, combine a `FormatFunc`, `Delimiters`, and a full `Formatter`. Each controls a distinct layer:

```go
domain := serrors.New("app",
    // 1. leaf text: custom format for a third-party error type
    serrors.WithFormatFunc(func(err error) (string, bool) {
        var pkgErr *pkg.Error
        if !errors.As(err, &pkgErr) {
            return "", false
        }
        return fmt.Sprintf("pkg(%s): %s", pkgErr.Code, pkgErr.Message), true
    }),
    // 2. delimiters: non-default delimiters (applied inside spec.Apply(err))
    serrors.WithDelimiters(serrors.Delimiters{Label: " | ", Part: " > ", Join: " & "}),
    // 3. full assembly: custom top-level structure
    //    spec.Apply(err) returns "pkg(123): ..." with " & " for multi-errors
    serrors.WithFormatter(serrors.FormatterFunc(func(err error, spec serrors.FormatSpec) string {
        return fmt.Sprintf("[%s] %s: %s", spec.Label, strings.Join(spec.Ops, "/"), spec.Apply(err))
    })),
)
// [app] op1/op2: pkg(123): something went wrong
```

## Concurrency

All `Domain` operations are safe for concurrent use with the following guidance:

* **Error formatting** (`err.Error()`, `e.LogValue()`) is always safe, with no restrictions.
* `Register*FormatFunc` is safe for concurrent use, including concurrent calls on the same domain. Calling it once at program startup (typically in `init()`) is conventional but not required.
* `Domain`'s `Sentinel`/`Wrap*`/`WrapWith*`, and `Error`'s `Derive`/`Detail*`; are safe to call from any goroutine at any time.

## API Reference

### Package-Level (default domain)

```go
// the default domain instance for package-level functions
Default() *Domain
// replace the default domain with a custom one
SetDefault(d *Domain)
// replace the default domain with a fresh stock domain (for tests only)
Reset()
// create a new named sentinel on the default domain
Sentinel(op string) *Error
// wrap one or more errors with an operation context
Wrap(op string, errs ...error) error
// wrap with formatted detail
Wrapf(op string, format string, args ...any) error
// wrap with structured data
WrapWith(op string, data any, errs ...error) error
// wrap with structured data and formatted detail
WrapWithf(op string, data any, format string, args ...any) error
// register a format function for the default domain
// see also RegisterTypedFormatFunc for a type-safe alternative
RegisterFormatFunc(fn FormatFunc) func()
```

### Domain Methods

```go
// create a new error domain with the given label and optional options
serrors.New(label string, opts ...Option) *Domain

// the root sentinel for this domain, parent of all sentinels of the domain
d.Root() *Error
// create a new sentinel error with the given operation name
d.Sentinel(op string) *Error
// get the label of this domain
d.Label() string
// reports whether err belongs to this domain (true when errors.Is(err, d.Root()))
d.Contains(err error) bool
// wrap one or more errors with an operation context
d.Wrap(op string, errs ...error) error
// wrap with formatted detail
d.Wrapf(op string, format string, args ...any) error
// wrap with structured data
d.WrapWith(op string, data any, errs ...error) error
// wrap with structured data and formatted detail
d.WrapWithf(op string, data any, format string, args ...any) error
// register a FormatFunc for this domain; returns an unregister function
d.RegisterFormatFunc(fn FormatFunc) func()
// create a new domain by copying the receiver and applying opts; independent root (no is-a link)
d.With(opts ...Option) *Domain
// create a sub domain with a new label that inherits the parent's root sentinel hierarchy (is-a link)
d.Sub(label string, opts ...Option) *Domain
```

### Domain Options

```go
// set the domain label (useful in With to rename without an is-a link)
WithLabel(label string) Option
// establish an is-a link to base: errors from this domain satisfy errors.Is against base.Root()
WithBase(base *Domain) Option
// set all three delimiter strings at once
WithDelimiters(d Delimiters) Option
// set only the label delimiter (between domain label and first op/tail)
WithLabelDelimiter(delim string) Option
// set only the part delimiter (between ops and tail in the default assembly)
WithPartDelimiter(delim string) Option
// set only the join delimiter (between errors.Join children)
WithJoinDelimiter(delim string) Option
// append a FormatFunc to the chain at construction time; can be called multiple times
WithFormatFunc(fn FormatFunc) Option
// set a full-control Formatter (replaces default delimiter-based assembly)
// use FormatterFunc to wrap a plain function
WithFormatter(f Formatter) Option
```

### Error Type and Methods

Type:

```go
type Error struct {
    Op     string   // operation/operator/component name
    Err    error    // underlying error
    Data   any      // optional structured context attached via WrapWith/WrapWithf; nil for sentinels and plain Wrap calls
    Domain *Domain  // domain this error belongs to; nil uses Default() at formatting/Is time (nil-means-default)
}
```

Methods:

```go
// typed child sentinel, same domain
e.Derive(op string) *Error
// plain leaf with literal message
e.Detail(msg string) error
// plain leaf with formatted message; supports %w for inner error wrapping
e.Detailf(format string, args ...any) error
// implements error interface (Data is not included in the string representation)
e.Error() string
// single-error unwrap
e.Unwrap() error
// matches root sentinel of domain (and ancestor roots for Sub)
e.Is(target error) bool
// implements slog.LogValuer; returns a plain string when no Data is present,
// or a slog group (message + all Data attrs) when at least one node carries Data
e.LogValue() slog.Value
```

### Standalone Functions

```go
// top-level generic function for registering a typed format function on a specific domain
RegisterTypedFormatFunc[T error](d *Domain, fn func(T) string) func()

// walk chain calling fn for each *Error node, outermost first; return false from fn to stop early
Walk(err error, fn func(*Error) bool)
// extract the first *Error from the chain; ok=false if none found
AsError(err error) (*Error, bool)
// first Data value in the chain assignable to T; ok=false if none found
AnyDataAs[T any](err error) (T, bool)
// walk chain, collect Data values assignable to T, outermost first
AllDataAs[T any](err error) []T

// walk chain, collect Data as slog attrs, outermost first
LogAttrs(err error) []slog.Attr

// capture the current goroutine's call stack, up to DefaultStackDepth frames
CaptureStackTrace() StackTrace
// like CaptureStackTrace but with explicit frame limit and skip count
CaptureStackTraceN(depth, skip int) StackTrace

// return the built-in Formatter; useful as a base for wrapping the default output
DefaultFormatter() Formatter
// format err using d's pipeline; useful for testing custom formatting configurations
FormatError(d *Domain, err error) string
```

### Types

```go
// StackTrace holds raw program counters captured at a call site
type StackTrace []uintptr
// resolve the raw program counters to human-readable runtime.Frame values
st.Frames() []runtime.Frame
// implements slog.LogValuer; emits all frames as a semicolon-separated string
// under StackTraceKey ("stack") in a slog group
st.LogValue() slog.Value

// FormatFunc formats a single error to a compact string representation;
// return ("", false) when the format function does not handle the given type
type FormatFunc func(error) (s string, ok bool)

// Formatter is the full-control interface for assembling an error's string representation
type Formatter interface {
    Format(err error, spec FormatSpec) string
}
// FormatterFunc adapts a plain function to the Formatter interface
type FormatterFunc func(err error, spec FormatSpec) string

// FormatSpec carries the formatting pipeline for a domain snapshot
type FormatSpec struct {
    Label      string       // domain label, e.g. "my-app"; can be empty
    Ops        []string     // operation chain, ancestor-first
    Delimiters Delimiters   // the domain's configured delimiter strings
}

// Apply formats err through the domain's FormatFunc chain; falls back to err.Error()
(spec FormatSpec).Apply(err error) string

// Delimiters controls the three delimiter strings used when formatting errors
type Delimiters struct {
    Label string // between domain label and first op/tail; default ": "
    Part  string // between individual ops and between last op and tail; default ": "
    Join  string // between children of an errors.Join aggregate; default "; "
}
```

### Constants

```go
DefaultStackDepth = 32        // default frame limit used by CaptureStackTrace
DataKey           = "data"    // slog attribute key used when Data is wrapped as a fallback slog.Any attribute
MessageKey        = "message" // slog attribute key for the error message in Error.LogValue groups
StackTraceKey     = "stack"   // slog attribute key for the stack trace in StackTrace.LogValue groups
```

## License

See [LICENSE](./LICENSE).

serrors

serrors 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

serrors

serrors 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README