Documentation
¶
Overview ¶
Package ers provides some very basic error aggregating and handling tools, as a companion to erc.
The packages are similar, though ers is smaller and has no dependencies outside of a few packages in the standard library, whereas erc is more tightly integrated into fun's ecosystem and programming model.
ers has an API that is equivalent to the standard library errors package, with some additional tools and minor semantic differences.
Index ¶
- func Append(errs []error, es ...error) []error
- func As(err error, target any) bool
- func Cast(e any) error
- func Check(fn func()) (err error)
- func ContextExpired(err error) bool
- func ExtractErrors(in []any) (rest []any, errs []error)
- func GetTime(err error) time.Time
- func Ignore(_ error)
- func Is(err error, targets ...error) bool
- func IsError(err error) bool
- func IsInvariantViolation(r any) bool
- func IsTerminating(err error) bool
- func Join(errs ...error) error
- func New(str string) error
- func NewWithTime(e string) error
- func OK(err error) bool
- func ParsePanic(r any) error
- func RemoveOK(errs []error) []error
- func Safe[T any](fn func() T) (out T, err error)
- func SafeOK[T any](fn func() (T, error)) (out T, ok bool)
- func Unwind(in error) (out []error)
- func Unwrap(err error) error
- func WithTime(err error) error
- func Wrap(err error, annotation ...any) error
- func Wrapf(err error, tmpl string, args ...any) error
- type Error
- type Filter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Cast ¶
Cast converts an untyped/any object into an error, returning nil if the value is not an error or is an error of a nil type.
func Check ¶
func Check(fn func()) (err error)
Check, like Safe, runs a function without arguments that does not produce an error, and, if the function panics, converts it into an error.
func ContextExpired ¶
ContextExpired checks an error to see if it, or any of it's parent contexts signal that a context has expired. This covers both canceled contexts and ones which have exceeded their deadlines.
func ExtractErrors ¶
Extract iterates through a list of untyped objects and removes the errors from the list, returning both the errors and the remaining items.
func GetTime ¶
GetTime unwraps the error looking for an error type that implements the timestamp interface:
interface{ Time() time.Time }
and, if so returns the output of that method. Otherwise, GetTime returns a zeroed time object. Any Error implementation can implement this interface, though the Timestamp type provides a basic implementation.
func Is ¶
Is returns true if the error is one of the target errors, (or one of it's constituent (wrapped) errors is a target error. ers.Is uses errors.Is.
func IsInvariantViolation ¶
IsInvariantViolation returns true if the argument is or resolves to ErrInvariantViolation.
func IsTerminating ¶
IsTerminating returns true if the error is one of the sentinel errors used by fun (and other packages!) to indicate that processing/iteration has terminated. (e.g. context expiration, or io.EOF.)
func Join ¶
Join is analogous to errors.Join, with a few distinctions: if there are zero or only nil errors passed to Join, the returned error is nil. If only one non-nil error is passed to join, it is returned directly. Otherwise or one errors passed to join are aggregated into a single error.
Internally, and contrary to errors.Join, the aggregated error is stored as a stack, and the string (e.g. Error()) form is:
"{top-most error's Error() value} [{bottom-most error's Error() value}] <{size}>"
Use Unwind() to get the full content of the aggregated error message.
func NewWithTime ¶
NewWithTime creates a new error object with the provided string.
func OK ¶
OK returns true when the error is nil, and false otherwise. It should always be inlined, and mostly exists for clarity at call sites in bool/OK check relevant contexts.
func ParsePanic ¶
ParsePanic converts a panic to an error, if it is not, and attaching the ErrRecoveredPanic error to that error. If no panic is detected, ParsePanic returns nil.
func RemoveOK ¶
RemoveOK removes all nil errors from a slice of errors, returning the consolidated slice.
func SafeOK ¶
SafeOK runs a function and returns true if there are no errors and no panics the bool output value is true, otherwise it is false.
func Unwind ¶
Unwind, is a special case of the fun.Unwind operation, that assembles the full "unwrapped" list of all component errors. Supports error implementations where the Unwrap() method returns either error or []error.
func Unwrap ¶
Unwrap is a wrapper around errors.Unwrap to allow ers to be a drop in replacement for errors.
func WithTime ¶
WithTime wraps an error with a timestamp implementation. The output of time.Now will be captured when WithTime returns, and can be accessed via the GetTime method or using the '%+v' formatting argument.
The Timestamp errors, correctly supports errors.Is and errors.As, passing through to the wrapped error.
func Wrap ¶
Wrap produces a wrapped error if the err is non-nil, wrapping the error with the provided annotation. When the error is nil, Wrap returns nil.
This, roughly mirrors the usage "github/pkg/errors.Wrap" but taking advantage of newer standard library error wrapping.
Types ¶
type Error ¶
type Error string
Error is a type alias for building/declaring sentinel errors as constants.
In addition to nil error interface values, the Empty string is, considered equal to nil errors for the purposes of Is(). errors.As correctly handles unwrapping and casting Error-typed error objects.
ErrInvalidInput indicates malformed input. These errors are not generally retriable.
ErrInvariantViolation is the root error of the error object that is the content of all panics produced by the Invariant helper.
ErrLimitExceeded is a constant sentinel error that indicates that a limit has been exceeded. These are generally retriable.
ErrMalformedConfiguration indicates a configuration object that has failed validation.
ErrRecoveredPanic is at the root of any error returned by a function in the fun package that recovers from a panic.
type Filter ¶
Filter provides a way to process error messages, either to remove errors, reformulate, or annotate errors.
func FilterCheck ¶
FilterCheck is an error filter that returns nil when the check is true, and false otherwise.
func FilterConvert ¶
FilterConvert returns the provided "output" error for all non-nil errors, and returns nil otherwise.
func FilterExclude ¶
FilterExclude takes an error and returns nil if the error is nil, or if the error (or one of its wrapped errors,) is in the exclusion list.
func FilterNoop ¶
func FilterNoop() Filter
FilterNoop produces a filter that always returns the original error.
func FilterToRoot ¶
func FilterToRoot() Filter
FilterToRoot produces a filter which always returns only the root/MOST wrapped error present in an error object.
Source Files