errors: add AsType

Fixes #51945

Author: jub0bs

api/next/51945.txt

@@ -0,0 +1 @@
+pkg errors, func AsType[$0 error](error) ($0, bool) #51945

src/errors/errors.go

@@ -41,6 +41,11 @@
 //
 // because the former will succeed if err wraps [io/fs.ErrExist].
 //
+// [AsType] examines the tree of its argument looking for an error whose
+// type matches its type argument. If it succeeds, it returns the
+// corresponding value of that type and true. Otherwise, it returns the
+// zero value of that type and false.
+//
 // [As] examines the tree of its first argument looking for an error that can be
 // assigned to its second argument, which must be a pointer. If it succeeds, it
 // performs the assignment and returns true. Otherwise, it returns false. The form
@@ -57,6 +62,7 @@
 //	}
 //
 // because the former will succeed if err wraps an [*io/fs.PathError].
+// Prefer [AsType] instead.
 package errors
 
 // New returns an error that formats as the given text.

src/errors/example_test.go

@@ -102,6 +102,44 @@ func ExampleAs() {
 	// Failed at path: non-existing
 }
 
+func ExampleAsType() {
+	if _, err := os.Open("non-existing"); err != nil {
+		if pathError, ok := errors.AsType[*fs.PathError](err); ok {
+			fmt.Println("Failed at path:", pathError.Path)
+		} else {
+			fmt.Println(err)
+		}
+	}
+	// Output:
+	// Failed at path: non-existing
+}
+
+type timeout interface{ Timeout() bool }
+
+// In some cases, the result's desired type is an interface other than
+// error. Consider the interface type declared as follows:
+//
+//	type timeout interface{ Timeout() bool }
+//
+// Because timeout doesn't satisfy the error type constraint, you cannot
+// simply use timeout as type argument. Instead, use an interface type
+// that embeds both timeout and error.
+func ExampleAsType_other() {
+	if _, err := os.Open("non-existing"); err != nil {
+		type target interface {
+			timeout
+			error
+		}
+		if t, ok := errors.AsType[target](err); ok {
+			fmt.Println("Timed out:", t.Timeout())
+		} else {
+			fmt.Println(err)
+		}
+	}
+	// Output:
+	// Timed out: false
+}
+
 func ExampleUnwrap() {
 	err1 := errors.New("error1")
 	err2 := fmt.Errorf("error2: [%w]", err1)

src/errors/wrap.go

@@ -94,6 +94,10 @@ func is(err, target error, targetComparable bool) bool {
 //
 // As panics if target is not a non-nil pointer to either a type that implements
 // error, or to any interface type.
+//
+// [AsType] is semantically equivalent to [As], with one caveat: the argument to [As]
+// needs not implement the error interface. Consider using [AsType] instead of [As];
+// it's more ergonomic, type-safe, and performant.
 func As(err error, target any) bool {
 	if err == nil {
 		return false
@@ -145,3 +149,59 @@ func as(err error, target any, targetVal reflectlite.Value, targetType reflectli
 }
 
 var errorType = reflectlite.TypeOf((*error)(nil)).Elem()
+
+// AsType finds the first error in err's tree that matches the type E, and
+// if one is found, returns that error value and true. Otherwise, it
+// returns the zero value of E and false.
+//
+// The tree consists of err itself, followed by the errors obtained by
+// repeatedly calling its Unwrap() error or Unwrap() []error method. When
+// err wraps multiple errors, AsType examines err followed by a
+// depth-first traversal of its children.
+//
+// An error e matches the type E if the type assertion e.(E) holds, or if
+// the error has a method As(any) bool such that e.As(target) returns
+// true when target is a non-nil *E. In the latter case, the As method is
+// responsible for setting target.
+func AsType[E error](err error) (_ E, ok bool) {
+	if err == nil {
+		return
+	}
+	var pe *E // lazily initialized
+	return asType(err, &pe)
+}
+
+func asType[E error](err error, ppe **E) (_ E, ok bool) {
+	for {
+		if e, ok := err.(E); ok {
+			return e, true
+		}
+		if x, ok := err.(interface{ As(any) bool }); ok {
+			if *ppe == nil {
+				*ppe = new(E)
+			}
+			if x.As(*ppe) {
+				return **ppe, true
+			}
+		}
+		switch x := err.(type) {
+		case interface{ Unwrap() error }:
+			err = x.Unwrap()
+			if err == nil {
+				return
+			}
+		case interface{ Unwrap() []error }:
+			for _, err := range x.Unwrap() {
+				if err == nil {
+					continue
+				}
+				if x, ok := asType(err, ppe); ok {
+					return x, true
+				}
+			}
+			return
+		default:
+			return
+		}
+	}
+}

src/errors/wrap_test.go

@@ -239,6 +239,123 @@ func TestAsValidation(t *testing.T) {
 	}
 }
 
+func TestAsType(t *testing.T) {
+	var errT errorT
+	var errP *fs.PathError
+	type timeout interface {
+		Timeout() bool
+		error
+	}
+	_, errF := os.Open("non-existing")
+	poserErr := &poser{"oh no", nil}
+
+	testAsType(t,
+		nil,
+		errP,
+		false,
+	)
+	testAsType(t,
+		wrapped{"pitied the fool", errorT{"T"}},
+		errorT{"T"},
+		true,
+	)
+	testAsType(t,
+		errF,
+		errF,
+		true,
+	)
+	testAsType(t,
+		errT,
+		errP,
+		false,
+	)
+	testAsType(t,
+		wrapped{"wrapped", nil},
+		errT,
+		false,
+	)
+	testAsType(t,
+		&poser{"error", nil},
+		errorT{"poser"},
+		true,
+	)
+	testAsType(t,
+		&poser{"path", nil},
+		poserPathErr,
+		true,
+	)
+	testAsType(t,
+		poserErr,
+		poserErr,
+		true,
+	)
+	testAsType(t,
+		errors.New("err"),
+		timeout(nil),
+		false,
+	)
+	testAsType(t,
+		errF,
+		errF.(timeout),
+		true)
+	testAsType(t,
+		wrapped{"path error", errF},
+		errF.(timeout),
+		true,
+	)
+	testAsType(t,
+		multiErr{},
+		errT,
+		false,
+	)
+	testAsType(t,
+		multiErr{errors.New("a"), errorT{"T"}},
+		errorT{"T"},
+		true,
+	)
+	testAsType(t,
+		multiErr{errorT{"T"}, errors.New("a")},
+		errorT{"T"},
+		true,
+	)
+	testAsType(t,
+		multiErr{errorT{"a"}, errorT{"b"}},
+		errorT{"a"},
+		true,
+	)
+	testAsType(t,
+		multiErr{multiErr{errors.New("a"), errorT{"a"}}, errorT{"b"}},
+		errorT{"a"},
+		true,
+	)
+	testAsType(t,
+		multiErr{wrapped{"path error", errF}},
+		errF.(timeout),
+		true,
+	)
+	testAsType(t,
+		multiErr{nil},
+		errT,
+		false,
+	)
+}
+
+type compError interface {
+	comparable
+	error
+}
+
+func testAsType[E compError](t *testing.T, err error, want E, wantOK bool) {
+	t.Helper()
+	name := fmt.Sprintf("AsType[%T](Errorf(..., %v))", want, err)
+	t.Run(name, func(t *testing.T) {
+		got, gotOK := errors.AsType[E](err)
+		if gotOK != wantOK || got != want {
+			t.Fatalf("got %v, %t; want %v, %t", got, gotOK, want, wantOK)
+		}
+	})
+}
+
 func BenchmarkIs(b *testing.B) {
 	err1 := errors.New("1")
 	err2 := multiErr{multiErr{multiErr{err1, errorT{"a"}}, errorT{"b"}}}
@@ -260,6 +377,15 @@ func BenchmarkAs(b *testing.B) {
 	}
 }
 
+func BenchmarkAsType(b *testing.B) {
+	err := multiErr{multiErr{multiErr{errors.New("a"), errorT{"a"}}, errorT{"b"}}}
+	for range b.N {
+		if _, ok := errors.AsType[errorT](err); !ok {
+			b.Fatal("AsType failed")
+		}
+	}
+}
+
 func TestUnwrap(t *testing.T) {
 	err1 := errors.New("1")
 	erra := wrapped{"wrap 2", err1}