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 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 IsExpiredContext(err error) bool
- func IsInvariantViolation(r any) bool
- func IsTerminating(err error) bool
- func Join(errs ...error) error
- func New(str string) error
- func NewInvariantViolation(args ...any) error
- func NewWithTime(e string) error
- func Ok(err error) bool
- func ParsePanic(r any) error
- func Recover(ob func(error))
- func RemoveOk(errs []error) []error
- func Strings(errs []error) []string
- func Unwind(in error) []error
- func Unwrap(err error) error
- func When(cond bool, val any) error
- func Whenf(cond bool, tmpl string, args ...any) error
- func WithRecoverCall(fn func()) (err error)
- func WithRecoverDo[T any](fn func() T) (out T, err error)
- func WithRecoverOk[T any](fn func() (T, error)) (out T, ok bool)
- func WithTime(err error) error
- func Wrap(err error, annotation ...any) error
- func WrapRecoverCall(fn func()) func() error
- func WrapRecoverDo[T any](fn func() T) func() (T, error)
- func WrapRecoverOk[T any](fn func() (T, error)) func() (T, bool)
- func Wrapf(err error, tmpl string, args ...any) error
- type Error
- type Filter
- type Stack
- func (e *Stack) Add(errs ...error)
- func (e *Stack) As(target any) bool
- func (e *Stack) CheckProducer() func() (error, bool)
- func (e *Stack) Error() string
- func (e *Stack) Future() func() error
- func (e *Stack) Handler() func(err error)
- func (e *Stack) Is(err error) bool
- func (e *Stack) Len() int
- func (e *Stack) Ok() bool
- func (e *Stack) Push(err error)
- func (e *Stack) Resolve() error
- func (e *Stack) Unwind() []error
- func (e *Stack) Unwrap() error
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 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 IsExpiredContext ¶ added in v0.10.5
IsExpiredContext 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 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 takes a slice of errors and converts it into an *erc.Stack typed error. This operation has several advantages relative to using errors.Join(): if you call ers.Join repeatedly on the same error set of errors the resulting error is convertable
func NewInvariantViolation ¶ added in v0.10.5
NewInvariantViolation creates a new error object, which always includes
func NewWithTime ¶
NewWithTime creates a new error object with the provided string.
func Ok ¶ added in v0.10.9
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 Recover ¶ added in v0.10.4
func Recover(ob func(error))
Recovery catches a panic, turns it into an error and passes it to the provided observer function.
func RemoveOk ¶ added in v0.10.9
RemoveOk removes all nil errors from a slice of errors, returning the consolidated slice.
func Strings ¶ added in v0.10.4
Strings renders (using the Error() method) a slice of errors into a slice of their string values.
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.
If an error type implements interface{ Unwind() []error }, this takes precedence over Unwrap when unwinding errors, to better support the Stack type and others where the original error is nested within the unwrapped error objects.
func Unwrap ¶
Unwrap is a wrapper around errors.Unwrap to allow ers to be a drop in replacement for errors.
func When ¶ added in v0.10.4
When constructs an ers.Error-typed error value IF the conditional is true, and returns nil otherwise.
func Whenf ¶ added in v0.10.4
Whenf constructs an error (using fmt.Errorf) IF the conditional is true, and returns nil otherwise.
func WithRecoverCall ¶ added in v0.10.8
func WithRecoverCall(fn func()) (err error)
WithRecoverCall runs a function without arguments that does not produce an error and, if the function panics, converts it into an error.
func WithRecoverDo ¶ added in v0.10.8
WithRecoverDo runs a function with a panic handler that converts the panic to an error.
func WithRecoverOk ¶ added in v0.10.9
WithRecoverOk 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 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.
func WrapRecoverCall ¶ added in v0.10.8
func WrapRecoverCall(fn func()) func() error
WrapRecoverCall wraps a function without arguments that does not produce an error with one that does produce an error. When called, the new function will never panic but returns an error if the input function panics.
func WrapRecoverDo ¶ added in v0.10.8
WrapRecoverDo wraps a function that returns a single value, with one that returns that argument and an error if the underlying function panics.
func WrapRecoverOk ¶ added in v0.10.9
WrapRecoverOk takes a function that returns an error and a value, and returns a wrapped function that also catches any panics in the input function, and returns the value and a boolean that is true if the input function does not return an error or panic.
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.
ErrCurrentOpAbort is used to signal that a retry function or other looping operation that the loop should exit. ErrCurrentOpAbort should be handled like "break", and should not be returned to callers or aggregated with other errors.
ErrCurrentOpSkip is used to signal that a retry function or other looping loop should continue. In most cases, this error should not be returned to callers or aggregated with other errors.
ErrImmutabilityViolation is an returned by some operations or invariant violations when an operation attempts to modify logically immutable value.
ErrInvalidInput indicates malformed input. These errors are not generally retriable.
ErrInvalidRuntimeType signals a type error encountered at runtime. Typically included as a component in an aggregate invariant violation error.
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.
func (Error) Err ¶ added in v0.10.4
Err returns the Error object as an error object (e.g. that implements the error interface.) Provided for more ergonomic conversions.
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.
type Stack ¶ added in v0.10.4
type Stack struct {
// contains filtered or unexported fields
}
Stack represents the error type returned by an ErrorCollector when it has more than one error. The implementation provides support for errors.Unwrap and errors.Is, and provides an Errors() method which returns a slice of the constituent errors for additional use.
func AsStack ¶ added in v0.10.5
AsStack takes an error and converts it to a stack if possible, if the error is an ers.Stack then this is a passthrough, and errors that implement {Unwind() []error} or {Unwrap() []error}, though preferring Unwind, are added individually to the stack.
For errors that provide the Unwind/Unwrap method, if these methods return empty slices of errors, then AsStack will return nil.
func (*Stack) Add ¶ added in v0.10.5
Add is a thin wrapper around Push, that adds each error supplied as an argument individually to the stack.
This leads to a curios, semantic: using the Unwrap() method (and casting; but not the unwind method!), the values returned for each layer are also *ers.Stack values: if you were to call Add any of these objects, you would end up with sort of tree-like assortment of objects which may yield surprising result. At the same time, if you have a reference to one of these stack objects, future calls to Add() on the "outer" stack will have no bearing on "inner" Stack objects.
func (*Stack) As ¶ added in v0.10.4
As calls errors.As on the underlying error to provied compatibility with errors.As, which takes advantage of this interface.
func (*Stack) CheckProducer ¶ added in v0.10.4
CheckProducer provides a pull-based iterator function for iterating through the errors (without Stack object wrappers.) The output function yields errors: the boolean return
func (*Stack) Error ¶ added in v0.10.4
Error produces the aggregated error strings from this method. If the error at the current layer is nil.
func (*Stack) Future ¶ added in v0.10.5
Future provides a fun.Future[error] typed function (though because ers is upstream of the root-fun package, it is not explicitly typed as such.) which will resolve the stack.
func (*Stack) Handler ¶ added in v0.10.5
Handler provides a fun.Handler[error] typed function (though because ers is upstream of the root-fun package, it is not explicitly typed as such.) which will Add errors to the stack.
func (*Stack) Is ¶ added in v0.10.4
Is calls errors.Is on the underlying error to provied compatibility with errors.Is, which takes advantage of this interface.
func (*Stack) Len ¶ added in v0.10.4
Len returns the depth of the stack beneath the current level. This value isn't updated as additional errors are pushed onto the stack.
func (*Stack) Ok ¶ added in v0.10.9
Ok returns true if the Stack object contains no errors and false otherwise.
func (*Stack) Push ¶ added in v0.10.4
Push adds an error to the current stack. If one stack is pushed onto another, the first stack's errors are unwound and pushed individually to the stack. If the error object implements the {Unwind() []error}, or {Unwrap() []error} interfaces, then these are also pushed individually to the stack, all other errors are added individually to the stack. The Stack.Is() and Stack.As implementations support identfying all errors included in the stack even if one of the individual errors is itself wrapped (e.g. one wrapped using fmt.Errorf and %w.)
The stack object is not safe for concurrent access (use the error collector in the `erc` package for a higher level interface to the Stack object that includes a mutex,) but, Stack objects are implemented as a linked list and not modified after use, which may make them easier to reason about.
func (*Stack) Resolve ¶ added in v0.10.6
Resolve, mirroring the interface of erc.Collector, returns the error (always a Stack object containing the aggregate errors,) in the case that stack object contains errors, and nil otherwise.
Source Files