relax

package module
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 18, 2026 License: MIT Imports: 4 Imported by: 0

README

Relax

CI codecov Go Report Card pkg.go.dev Go Version License

Don't panic - just relax.

relax is a focused library for panic-based error propagation inside trusted internal layers.

The goal is simple: let deep internal code fail fast, recover once at a clear boundary, and keep the outward-facing surface of your package in normal Go error form.

It is not a replacement for Go's error model. It is a tool for the parts of a codebase where repeated error forwarding adds noise, but the intermediate layers have no real recovery decision to make.

Installation

go get github.com/luckyman42/relax

import "github.com/luckyman42/relax"

Quick Start

package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

type User struct {
	Name string
}

func fetchUser(id int) (User, error) {
	return User{}, errors.New("database unavailable")
}

func HandleRequest(id int) error {
	return relax.CheckError(func() error {
		user := relax.FailOnError(fetchUser(id))
		fmt.Println(user.Name)
		return nil
	})
}

The mental model is straightforward:

  • inside trusted internal code, use FailOnError* or FailWith
  • at the first boundary that should return a normal Go error, use a Check* helper

Why

Go's explicit error handling is one of the language's strengths. It is especially good at API boundaries, where each caller should decide what to do with the failure.

The problem appears in long internal call chains where intermediate layers do not have anything meaningful to add. In a chain like A -> B -> C -> D -> E, if only A should decide how to handle an error produced by E, then B, C, and D often end up doing nothing except forwarding the same error upward.

That usually turns into repeated boilerplate like this:

value, err := next()
if err != nil {
	return err
}

With relax, the same flow can stay linear:

func A() error {
	return relax.CheckFailer(B)
}

func B() { C() }

func C() { D() }

func D() {
	relax.FailWith(E())
}

func E() error {
	return errors.New("storage unavailable")
}

If E returned (T, error) instead, D would typically use relax.FailOnError(E()).

The key point is that B and C do not need to participate in forwarding a failure that only A intends to handle anyway.

Flow Overview

The diagram below shows the core idea of relax: deep internal code fails once, the failure unwinds through trusted layers unchanged, and the outer boundary converts it back into a normal Go error.

sequenceDiagram
	participant Caller
	participant A as Boundary A
	participant B as Layer B
	participant C as Layer C
	participant D as Layer D
	participant E as Layer E

	Caller->>A: call
	A->>B: call
	B->>C: call
	C->>D: call
	D->>E: call
	E-->>D: return error
	D->>D: FailWith(err)
	D--xC: panic(Failer)
	C--xB: panic(Failer)
	B--xA: panic(Failer)
	A->>A: CheckFailer / CheckError / CheckResult
	A-->>Caller: return error

Public API

Failure Propagation

Use these helpers inside trusted internal layers when a failure should immediately unwind to an outer boundary.

func FailWith(err error, keyVals ...any)

func FailOnError[T any](v T, err error) T
func FailOnError2[T1, T2 any](v1 T1, v2 T2, err error) (T1, T2)
func FailOnError3[T1, T2, T3 any](v1 T1, v2 T2, v3 T3, err error) (T1, T2, T3)

FailWith throws an error immediately. The FailOnError* helpers are convenience wrappers for the common Go shapes that already return an error.

Recovery Boundaries

Use these helpers at the edge of the internal call chain, where you want panic-based propagation converted back into ordinary Go errors.

func CheckFailer(fn func()) error
func CheckError(fn func() error) error

func CheckValue[T any](fn func() T) (T, error)
func CheckValue2[T1, T2 any](fn func() (T1, T2)) (T1, T2, error)
func CheckValue3[T1, T2, T3 any](fn func() (T1, T2, T3)) (T1, T2, T3, error)

func CheckResult[T any](fn func() (T, error)) (T, error)
func CheckResult2[T1, T2 any](fn func() (T1, T2, error)) (T1, T2, error)
func CheckResult3[T1, T2, T3 any](fn func() (T1, T2, T3, error)) (T1, T2, T3, error)

func HandleFailer(fn func(), onError func(error))
Supported Function Shapes

The built-in helpers cover the function shapes that come up most often in application code:

  • func() -> CheckFailer
  • func() error -> CheckError
  • func() T -> CheckValue
  • func() (T1, T2) -> CheckValue2
  • func() (T1, T2, T3) -> CheckValue3
  • func() (T, error) -> CheckResult
  • func() (T1, T2, error) -> CheckResult2
  • func() (T1, T2, T3, error) -> CheckResult3
  • (T, error) -> FailOnError
  • (T1, T2, error) -> FailOnError2
  • (T1, T2, T3, error) -> FailOnError3

Support intentionally stops at three non-error return values. Go does not provide a generic abstraction for arbitrary function return arity, so supporting 4+ values would require adding a new exported helper for each additional shape. For those cases, prefer wrapping the values in a struct or dedicated result type and returning fewer parameters through CheckValue or CheckResult.

Utilities
type Failer struct {
	Err       error
	Stack     []byte
	Timestamp time.Time
	Context   map[string]any
}

func ConvertToFailer(err error) Failer
func IsFailer(err error) bool

Most application code does not need to work with Failer directly. It is primarily useful when you want the captured stack trace, timestamp, or structured context.

Example: Adding Context

FailWith can attach structured metadata to the failure as it moves upward:

if err := saveUser(user); err != nil {
	relax.FailWith(err,
		"user_id", user.ID,
		"operation", "save_user",
	)
}

If the error is already a Failer, the context is merged instead of wrapping it again.

Working With Underlying Errors

You do not need to know anything about relax.Failer to access the original domain error.

Failer implements Unwrap(), so errors.As and errors.Is work against the inner error as usual.

type ValidationError struct {
	Field string
}

func (e *ValidationError) Error() string {
	return fmt.Sprintf("invalid %s", e.Field)
}

_, err := relax.CheckValue(func() string {
	relax.FailWith(&ValidationError{Field: "email"})
	return ""
})

var target *ValidationError
if errors.As(err, &target) {
	fmt.Println(target.Field)
}

In normal application code this is usually the right approach. Match the original error type you care about and ignore Failer completely.

You only need Failer itself when you want access to its extra data:

  • Stack
  • Timestamp
  • Context

Goroutines

For goroutines, make the goroutine boundary explicit and use HandleFailer inside the go statement:

go relax.HandleFailer(func() {
	user := relax.FailOnError(loadUser(id))
	syncUser(user)
}, func(err error) {
	log.Printf("worker failed: %v", err)
})

This keeps ownership of the goroutine launch in your code while still giving you a safe error boundary.

HandleFailer recovers only Failer panics and forwards them to onError. Any non-Failer panic is re-panicked unchanged. That means programmer bugs and runtime faults still fail loudly instead of being silently converted into ordinary errors.

Passing a nil onError handler panics immediately.

flowchart TD
	Start["go HandleFailer(fn, onError)"] --> Run[run worker code]
	Run -->|success| Exit[goroutine exits]
	Run -->|FailWith / FailOnError| Panic[panic Failer]
	Panic --> Recover[HandleFailer recovers]
	Recover --> Forward["onError(err)"]
	Run -->|non-Failer panic| Repanic[re-panic unchanged]

Design Guarantees

relax is intentionally small and opinionated.

It guarantees the following behavior:

  • only Failer panics are recovered
  • non-Failer panics propagate unchanged
  • the original error is preserved through Unwrap()
  • stack traces are captured when the failure is created
  • existing Failer values are not double-wrapped
  • errors.Is and errors.As continue to work normally

When It Fits Well

relax is a good fit for:

  • service-layer orchestration
  • request and command pipelines
  • background jobs and workers
  • CLI execution flows
  • deep internal call chains where the middle layers only forward failures

It is usually a poor fit for:

  • exported public APIs
  • low-level reusable libraries consumed by others
  • hot performance-critical loops
  • ordinary control flow where explicit error handling is clearer

Package Examples

Runnable examples live in example_test.go and are also published through pkg.go.dev.

Reusable Agent Skill

A self-contained AI skill lives in .github/skills/relax/. It includes the full API surface so agents can generate correct code without access to this source.

Copy the folder to use it elsewhere:

  • <project>/.github/skills/relax/
  • <project>/.agents/skills/relax/
  • ~/.copilot/skills/relax/
  • ~/.agents/skills/relax/

Testing

go test ./...

go test -v ./...

go test -bench=. ./...

License

MIT - see LICENSE.

Documentation

Overview

Package relax provides small helpers for structured, typed panic-based propagation inside well-defined internal boundaries.

Use `FailWith` and `FailOnError*` to escalate errors with optional key/value context without changing function signatures. Use `Check*` helpers at boundary points to recover `Failer` panics back into normal `error` values.

See the package examples in `example_test.go` for runnable usage samples.

Example (ErrorsAs) 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

type userNotFoundError struct {
	ID int
}

func (e *userNotFoundError) Error() string {
	return fmt.Sprintf("user %d not found", e.ID)
}

func main() {
	_, err := relax.CheckValue(func() string {
		relax.FailWith(&userNotFoundError{ID: 42})
		return ""
	})

	var target *userNotFoundError
	fmt.Println(errors.As(err, &target))
	fmt.Println(target.ID)

}

Output:
true
42
Example (QuickStart) 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	err := relax.CheckFailer(func() {
		relax.FailWith(errors.New("database unavailable"))
	})

	fmt.Println(err)

}

Output:
database unavailable
Example (RealisticServiceFlow) 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	E := func() error {
		return errors.New("storage unavailable")
	}

	D := func() {
		relax.FailWith(E())
	}

	C := func() { D() }
	B := func() { C() }
	A := func() error { return relax.CheckFailer(B) }

	fmt.Println(A())

}

Output:
storage unavailable

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckError added in v0.5.0 

func CheckError(fn func() error) (err error)

CheckError executes fn which returns only an error.

If fn returns a non-nil error, it is returned unchanged. If fn panics with a Failer, the panic is recovered and converted into an error. Any other panic is re-panicked unchanged.

CheckError is used for command-style functions where no value is returned, but execution may still fail.

Example 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	loadUser := func(id int) (string, error) {
		return "", errors.New("user not found")
	}

	err := relax.CheckError(func() error {
		_ = relax.FailOnError(loadUser(99))
		return nil
	})

	fmt.Println(err)

}

Output:
user not found

func CheckFailer added in v0.5.0 

func CheckFailer(fn func()) (err error)

CheckFailer executes fn and returns any error produced during execution.

If fn panics with a Failer, the panic is recovered and converted into an error. Any other panic is re-panicked unchanged.

CheckFailer is intended for functions that do not return a value but may fail, and where failures should be handled as errors instead of panics.

Example 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	err := relax.CheckFailer(func() {
		relax.FailWith(errors.New("something failed"))
	})

	fmt.Println(err)

}

Output:
something failed

func CheckResult added in v0.5.0 

func CheckResult[T any](fn func() (T, error)) (result T, err error)

CheckResult executes fn which returns a value and an error.

If fn returns a non-nil error, it is returned unchanged. If fn panics with a Failer, the panic is recovered and converted into an error. Any other panic is re-panicked unchanged.

CheckResult is used when the underlying function already follows Go's (T, error) convention but still needs panic-to-error boundary protection.

Example 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	value, err := relax.CheckResult(func() (int, error) {
		if true {
			relax.FailWith(errors.New("calculation failed"))
		}

		return 42, nil
	})

	fmt.Println(value)
	fmt.Println(err)

}

Output:
0
calculation failed

func CheckResult2 added in v0.5.0 

func CheckResult2[T1, T2 any](fn func() (T1, T2, error)) (result1 T1, result2 T2, err error)

CheckResult2 executes fn which returns two values and an error.

Example 
package main

import (
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	left, right, err := relax.CheckResult2(func() (int, string, error) {
		return 7, "ok", nil
	})

	fmt.Println(left)
	fmt.Println(right)
	fmt.Println(err == nil)

}

Output:
7
ok
true

func CheckResult3 added in v0.5.0 

func CheckResult3[T1, T2, T3 any](fn func() (T1, T2, T3, error)) (result1 T1, result2 T2, result3 T3, err error)

CheckResult3 executes fn which returns three values and an error.

Example 
package main

import (
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	major, minor, patch, err := relax.CheckResult3(func() (int, int, int, error) {
		return 1, 2, 3, nil
	})

	fmt.Println(major)
	fmt.Println(minor)
	fmt.Println(patch)
	fmt.Println(err == nil)

}

Output:
1
2
3
true

func CheckValue added in v0.5.0 

func CheckValue[T any](fn func() T) (result T, err error)

CheckValue executes fn and converts its execution into a checked call.

If fn completes successfully, its return value is returned and err is nil. If fn panics with a Failer, the panic is recovered and converted into an error. Any other panic is re-panicked unchanged.

CheckValue is intended for boundary layers (such as HTTP handlers or goroutine entry points) where panics of type Failer should be translated into errors.

Example

Because Failer implements Unwrap, callers can inspect the returned error directly with errors.As without knowing about relax.Failer. 

package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func fetchUser(id int) (string, error) {
	return "", errors.New("database unavailable")
}

func main() {
	profile, err := relax.CheckValue(func() string {
		return relax.FailOnError(fetchUser(42))
	})

	fmt.Println(profile == "")
	fmt.Println(err)

}

Output:
true
database unavailable

func CheckValue2 added in v0.5.0 

func CheckValue2[T1, T2 any](fn func() (T1, T2)) (result1 T1, result2 T2, err error)

CheckValue2 executes fn and converts its execution into a checked call for two returned values.

Example 
package main

import (
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	left, right, err := relax.CheckValue2(func() (int, string) {
		return 7, "ok"
	})

	fmt.Println(left)
	fmt.Println(right)
	fmt.Println(err == nil)

}

Output:
7
ok
true

func CheckValue3 added in v0.5.0 

func CheckValue3[T1, T2, T3 any](fn func() (T1, T2, T3)) (result1 T1, result2 T2, result3 T3, err error)

CheckValue3 executes fn and converts its execution into a checked call for three returned values.

Example 
package main

import (
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	major, minor, patch, err := relax.CheckValue3(func() (int, int, int) {
		return 1, 2, 3
	})

	fmt.Println(major)
	fmt.Println(minor)
	fmt.Println(patch)
	fmt.Println(err == nil)

}

Output:
1
2
3
true

func FailOnError added in v0.5.0 

func FailOnError[T any](v T, err error) T

FailOnError returns `v` if `err == nil`; otherwise it throws the error via `FailWith(err)`.

This reduces error-forwarding boilerplate inside internal call chains where panic-based propagation is acceptable. Prefer explicit returns in public APIs.

Example 
package main

import (
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	loadProfile := func() (string, error) {
		return "alice", nil
	}

	profile := relax.FailOnError(loadProfile())

	fmt.Println(profile)

}

Output:
alice

func FailOnError2 added in v0.5.0 

func FailOnError2[T1, T2 any](v1 T1, v2 T2, err error) (T1, T2)

FailOnError2 returns v1 and v2 if err == nil; otherwise it throws the error via FailWith(err).

Example 
package main

import (
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	loadName := func() (string, string, error) {
		return "Ada", "Lovelace", nil
	}

	first, last := relax.FailOnError2(loadName())

	fmt.Println(first)
	fmt.Println(last)

}

Output:
Ada
Lovelace

func FailOnError3 added in v0.5.0 

func FailOnError3[T1, T2, T3 any](v1 T1, v2 T2, v3 T3, err error) (T1, T2, T3)

FailOnError3 returns v1, v2 and v3 if err == nil; otherwise it throws the error via FailWith(err).

Example 
package main

import (
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	loadVersion := func() (int, int, int, error) {
		return 1, 2, 3, nil
	}

	major, minor, patch := relax.FailOnError3(loadVersion())

	fmt.Println(major)
	fmt.Println(minor)
	fmt.Println(patch)

}

Output:
1
2
3

func FailWith added in v0.2.0 

func FailWith(err error, keyVals ...any)

FailWith panics with a `Failer` that wraps `err`.

If `err` is already a `Failer` (value or pointer) it will be re-panicked directly; in that case any provided key/value pairs are merged into the existing `Failer.Context`. If `err` is nil, `FailWith` is a no-op.

The `keyVals` are interpreted as alternating key, value pairs. Keys are stringified using `fmt.Sprint`; an odd number of `keyVals` is allowed and the final key will be assigned a `nil` value.

Example 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	err := relax.CheckFailer(func() {
		relax.FailWith(errors.New("save failed"))
	})

	var failer relax.Failer
	if errors.As(err, &failer) {
		fmt.Println(failer.Err)
	}

}

Output:
save failed
Example (Context) 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	err := relax.CheckFailer(func() {
		relax.FailWith(errors.New("save failed"),
			"user_id", 42,
			"operation", "save_user",
		)
	})

	var failer relax.Failer
	if errors.As(err, &failer) {
		fmt.Println(failer.Err)
		fmt.Println(failer.Context["user_id"])
		fmt.Println(failer.Context["operation"])
	}

}

Output:
save failed
42
save_user
Example (Function) 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	badFun := func() error {
		return errors.New("Failer error")
	}

	err := relax.CheckFailer(func() {
		relax.FailWith(badFun())
	})

	var failer relax.Failer
	if errors.As(err, &failer) {
		fmt.Println(failer.Err)
	}

}

Output:
Failer error

func HandleFailer added in v0.5.0 

func HandleFailer(fn func(), onError func(error))

HandleFailer executes fn inside a CheckFailer boundary and forwards any recovered Failer as a standard error to onError.

HandleFailer is useful for explicit failure-handling boundaries where panic-based propagation is used internally, but failures must be handled locally instead of escaping the current execution flow.

Only panics carrying a Failer are recovered. Any other panic is re-panicked unchanged.

onError must not be nil. Passing a nil handler causes HandleFailer to panic immediately.

Example: 

relax.HandleFailer(func() {
    process()
}, logger.Error)

In this example, if process panics with a Failer, the panic is recovered and forwarded to logger.Error as a standard error. Any other panic from process is re-panicked unchanged. Could be safely used at the entry point of a goroutine, worker loop, or background job:

go relax.HandleFailer(process, logger.Error)

HandleFailer is especially useful at goroutine entry points, worker loops, background jobs, and asynchronous execution boundaries.

Example 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	relax.HandleFailer(func() {
		relax.FailWith(errors.New("worker failed"))
	}, func(err error) {
		fmt.Println(err)
	})

}

Output:
worker failed
Example (Goroutine) 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	done := make(chan struct{})

	go relax.HandleFailer(func() {
		relax.FailWith(errors.New("worker failed"))
	}, func(err error) {
		fmt.Println(err)
		close(done)
	})

	<-done

}

Output:
worker failed

func IsFailer added in v0.3.0 

func IsFailer(err error) bool

IsFailer reports whether `err` is a `Failer` value or wraps a `Failer`.

Example 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	failer := relax.ConvertToFailer(errors.New("failure"))

	fmt.Println(relax.IsFailer(failer))
	fmt.Println(relax.IsFailer(errors.New("normal error")))

}

Output:
true
false

Types

type Failer added in v0.2.0 

type Failer struct {
	Err       error
	Stack     []byte
	Timestamp time.Time
	Context   map[string]any
}

Failer is the public, exported representation of a thrown failure.

A `Failer` preserves the original `error` (Err), a captured stack trace (Stack), the time it was created (Timestamp), and an optional map[string]any Context for arbitrary key/value metadata. The library uses `Failer` values to implement structured panic-based propagation inside trusted internal call chains: callers may `panic` a `Failer` (via `FailWith` or `Failer.Fail`) and a `CheckValue` boundary will convert that panic back into a returned `error`.

Example 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	err := relax.CheckFailer(func() {
		failer := relax.ConvertToFailer(errors.New("repository failed"))

		failer.Fail(
			"repository", "users",
			"operation", "find",
		)
	})

	var failer relax.Failer
	if errors.As(err, &failer) {
		fmt.Println(failer.Err)
		fmt.Println(failer.Context["repository"])
	}

}

Output:
repository failed
users

func ConvertToFailer added in v0.2.0 

func ConvertToFailer(err error) Failer

ConvertToFailer converts any error into a `Failer` value.

If `err` is already a `Failer` (or wraps one), the underlying `Failer` is returned unchanged. Otherwise a new `Failer` is created capturing the current stack trace and timestamp.

Example 
package main

import (
	"errors"
	"fmt"

	"github.com/luckyman42/relax"
)

func main() {
	err := errors.New("boom")

	failer := relax.ConvertToFailer(err)

	fmt.Println(failer.Err)
	fmt.Println(failer.Timestamp.IsZero())
	fmt.Println(len(failer.Stack) > 0)

}

Output:
boom
false
true

func (Failer) Error added in v0.2.0 

func (f Failer) Error() string

Error returns the underlying error message for this Failer.

func (Failer) Fail added in v0.2.0 

func (f Failer) Fail(keyVals ...any)

Fail throw this Failer. If extra key/value pairs are provided, they are merged into the Failer context. This avoids wrapping a Failer inside another Failer when rethrowing.

func (Failer) Unwrap added in v0.2.0 

func (f Failer) Unwrap() error

Unwrap returns the underlying error for compatibility with errors.As and errors.Is.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.