Merge pull request #96

errors: introduce ErrUnreachable, NewUnreachableError() and NewUnreachableErrorf()

Author: karasz

README.md

@@ -111,6 +111,15 @@ can be used:
 * `Panicf()`,
 * and `PanicWrap`.
 
+### Unreachable conditions
+
+An `ErrUnreachable` is an _error_ that indicates something impossible happened, and
+it's wrapped as a `PanicError` including callstack when using the helpers that allow
+to wrap an extra error and cause note, optionally formatted.
+
+* `NewUnreachableError()`
+* `NewUnreachableErrorf()`
+
 ### Miscellaneous error related
 
 * CoalesceError

errors.go

@@ -21,6 +21,8 @@ var (
 	ErrUnknown = errors.New("unknown")
 	// ErrNilReceiver indicates a method was called over a nil instance
 	ErrNilReceiver = errors.New("nil receiver")
+	// ErrUnreachable indicates something impossible happened
+	ErrUnreachable = errors.New("unreachable")
 )
 
 var (

panicerror.go

@@ -106,3 +106,28 @@ func PanicWrap(err error, note string) {
 func PanicWrapf(err error, format string, args ...any) {
 	panic(NewPanicWrapf(1, err, format, args...))
 }
+
+// NewUnreachableErrorf creates a new annotated ErrUnreachable with callstack.
+func NewUnreachableErrorf(skip int, err error, format string, args ...any) error {
+	return NewUnreachableError(skip+1, err, fmt.Sprintf(format, args...))
+}
+
+// NewUnreachableError creates a new annotated ErrUnreachable with callstack.
+func NewUnreachableError(skip int, err error, note string) error {
+	if err == ErrUnreachable {
+		err = nil
+	}
+
+	switch {
+	case err == nil && note == "":
+		return NewPanicError(skip+1, ErrUnreachable)
+	case err == nil:
+		return NewPanicWrap(skip+1, ErrUnreachable, note)
+	case note != "":
+		err = Wrap(err, note)
+	}
+
+	return NewPanicError(skip+1, &CompoundError{
+		Errs: []error{ErrUnreachable, err},
+	})
+}