Release 0.0.3

- add `As` and `AsError`
- cache some escaping variables for `As`
- documentation
- small refactorings

Signed-off-by: Oliver Eikemeier <eikemeier@fillmore-labs.com>

Author: eikemeier

README.md

@@ -7,7 +7,7 @@
 [![Go Report Card](https://goreportcard.com/badge/fillmore-labs.com/exp/errors)](https://goreportcard.com/report/fillmore-labs.com/exp/errors)
 [![License](https://img.shields.io/github/license/fillmore-labs/errors-exp)](https://www.apache.org/licenses/LICENSE-2.0)
 
-`fillmore-labs.com/exp/errors` is an experimental Go library that provides two enhanced, generic alternatives to
+`fillmore-labs.com/exp/errors` is an experimental Go library that provides four enhanced, generic alternatives to
 `errors.As` for inspecting error chains with improved ergonomics and type safety.
 
 ## Motivation
@@ -21,17 +21,19 @@ linter.
 
 ## Function Overview
 
-This library provides two complementary functions:
+This library provides four functions in two complementary pairs, each building on Go's standard `errors.As`:
 
-- **`HasError`** - A drop-in, type-safe replacement for `errors.As` with better ergonomics
-- **`Has`** - An enhanced version that also handles pointer-value type mismatches automatically
+- **`HasError`** - Ergonomic and type-safe, returns the found error.
+- **`Has`** - The `HasError` API plus pointer-value mismatch handling.
 
-| Feature                         | `errors.As` | `HasError` | `Has` |
-| ------------------------------- | ----------- | ---------- | ----- |
-| Generic return type             | ❌          | ✅         | ✅    |
-| No target variable needed       | ❌          | ✅         | ✅    |
-| Interface support               | ✅          | ✅         | ✅    |
-| Pointer-value mismatch handling | ❌          | ❌         | ✅    |
+- **`AsError`** - The classic `errors.As` API with generic type safety.
+- **`As`** - The classic `errors.As` API plus pointer-value mismatch handling.
+
+| Feature                         | `errors.As` | `HasError` | `Has` | `AsError` | `As` |
+| ------------------------------- | ----------- | ---------- | ----- | --------- | ---- |
+| No target variable needed       | ❌          | ✅         | ✅    | ❌        | ❌   |
+| Pointer-value mismatch handling | ❌          | ❌         | ✅    | ❌        | ✅   |
+| Type safe generics              | ❌          | ✅         | ✅    | ✅        | ✅   |
 
 ## `HasError` - Enhanced Ergonomics
 
@@ -128,21 +130,23 @@ func Has[T error](err error) (T, bool)
 
 #### Prevents Common Bugs
 
-This mismatch would silently fail with `errors.As`:
+This mismatch would silently fail with `errors.As`. In the example below, `aes.NewCipher` returns an `aes.KeySizeError`
+value, but the check incorrectly looks for a pointer (`*aes.KeySizeError`):
 
 ```go
   key := []byte("My kung fu is better than yours")
   _, err := aes.NewCipher(key)
 
-  // With errors.As - this check fails silently.
+  // With errors.As, this check for a pointer type fails because the
+  // actual error is a value.
   var kse *aes.KeySizeError
   if errors.As(err, &kse) {
-    fmt.Printf("Wrong AES key size: %d bytes.\n", *kse)
+    // This code is never reached.
   }
 
-  // With Has - the check succeeds.
+  // With Has, the check succeeds because it handles the pointer-value mismatch.
   if kse, ok := Has[*aes.KeySizeError](err); ok {
-    fmt.Printf("AES keys must be 16, 24, or 32 bytes long, got %d bytes.\n", *kse)
+    fmt.Printf("Invalid AES key size: %d bytes. Key must be 16, 24, or 32 bytes.\n", *kse)
   }
 ```
 
@@ -166,6 +170,44 @@ Unlike `errors.As`, interface types provided to `Has` or `HasError` must embed t
   if temp, ok := Has[interface { error; Temporary() bool }](err); ok && temp.Temporary() { /* handle temporary error */ }
 ```
 
+## Classic API with Enhanced Safety
+
+If you prefer the traditional `errors.As` API that uses target variables, this library provides enhanced versions that
+add the same benefits:
+
+### `AsError` - Type-Safe `errors.As`
+
+`AsError` provides generic type safety to prevent target variable type mismatches:
+
+```go
+func AsError[T error](err error, target *T) bool
+
+  // Usage
+  var myErr *MyError
+  if AsError(err, &myErr) {
+    // myErr is guaranteed to be the correct type
+    // No risk of type assertion bugs
+  }
+```
+
+### `As` - Type-Safe with Flexible Matching
+
+`As` combines type safety with the same pointer-value mismatch handling as `Has`:
+
+```go
+func As[T error](err error, target *T) bool
+
+  // Usage
+  var myErr *MyError
+  if As(err, &myErr) {
+    // Also handles pointer-value mismatches automatically
+    // Most robust option with familiar API
+  }
+```
+
+Both functions prevent common type-related bugs while maintaining the familiar `errors.As` API that some developers
+prefer.
+
 ## Migration Guide
 
 ### From `errors.As` to `HasError`
@@ -191,6 +233,13 @@ If you suspect pointer-value mismatches are causing issues, replace `HasError` w
   if myErr, ok := Has[MyError](err); ok { /* ... */ }
 ```
 
+## Further Reading
+
+- Blog: [Understanding Go Error Types: Pointer vs. Value](https://blog.fillmore-labs.com/posts/errors-1/) - Background
+  on pointer-value type mismatches
+- [Go proposal: errors: As with type parameters](http://go.dev/issues/51945) - Community discussion on improving
+  `errors.As` with generics
+
 ## License
 
 This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.

as.go

@@ -0,0 +1,80 @@
+// Copyright 2025 Oliver Eikemeier. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+package errors
+
+// As finds the first error in `err`'s tree that has type `T`, and if one is found,
+// sets target to that error value and returns true. Otherwise, it returns 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, `As` examines `err` followed by a depth-first traversal of its children.
+//
+// An error has the type `T` if the error's value is assignable to `T`, including
+// cases where there are pointer-value mismatches (e.g., if `T` is `*MyError` but
+// the found error is `MyError`, or vice versa), or if the error has a method
+// `As(any) bool` that returns `true`. To accommodate pointer-value mismatches
+// in `As` implementations, `As` tries different variations of the target type.
+// In the latter case, the `As` method is responsible for setting `target`.
+//
+// An error type might provide an `As` method, so it can be treated as if it were a
+// different error type.
+//
+// As panics if `target` is a nil pointer.
+func As[T error](err error, target *T) bool {
+	if target == nil {
+		panic("errors: target cannot be nil")
+	}
+
+	var handler altHandler[T]
+
+	for err := range DepthFirstErrorTree(err) {
+		if result, ok := err.(T); ok {
+			*target = result
+
+			return true
+		}
+
+		if handler == nil {
+			// Lazily initialize the handler only when a direct type assertion fails.
+			handler = newAltHandler(target)
+		}
+
+		if result, ok := handler.handleAssert(err); ok {
+			*target = result
+
+			return true
+		}
+
+		if x, ok := err.(interface{ As(any) bool }); ok {
+			// First, try the standard errors.As contract. This works when T matches
+			// the type expected by the As method.
+			if x.As(target) {
+				return true
+			}
+
+			// If the standard call fails, it might be due to a pointer-vs-value mismatch
+			// between T and the type the As method is designed to handle.
+			if result, ok := handler.handleAs(x); ok {
+				*target = result
+
+				return true
+			}
+		}
+	}
+
+	return false
+}

as_errorsas_test.go

@@ -0,0 +1,85 @@
+// Copyright 2025 Oliver Eikemeier. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+package errors_test
+
+import (
+	"testing"
+
+	. "fillmore-labs.com/exp/errors"
+)
+
+func TestAsAs(t *testing.T) {
+	t.Parallel()
+
+	errValue := MyAsError(8)
+	errPointer := &errValue
+
+	testAsAs(t, "value receiver", errValue)
+	testAsAs(t, "pointer receiver", errPointer)
+}
+
+func testAsAs(t *testing.T, name string, err error) {
+	t.Helper()
+
+	t.Run(name, func(t *testing.T) {
+		t.Parallel()
+
+		t.Run("find MyPointerError", func(t *testing.T) {
+			t.Parallel()
+
+			var e MyPointerError
+			if !As(err, &e) {
+				t.Errorf("Expected to find MyPointerError, but didn't.")
+			} else if e != MyPointerError(8) {
+				t.Errorf("Expected MyPointerError(8), but got %d", int(e))
+			}
+		})
+
+		t.Run("find *MyPointerError", func(t *testing.T) {
+			t.Parallel()
+
+			var e *MyPointerError
+			if !As(err, &e) {
+				t.Errorf("Expected to find *MyPointerError, but didn't.")
+			} else if *e != MyPointerError(8) {
+				t.Errorf("Expected *MyPointerError(8), but got %d", int(*e))
+			}
+		})
+
+		t.Run("find MyValueError", func(t *testing.T) {
+			t.Parallel()
+
+			var e MyValueError
+			if !As(err, &e) {
+				t.Errorf("Expected to find MyValueError, but didn't.")
+			} else if e != MyValueError(8) {
+				t.Errorf("Expected MyValueError(8), but got %d", int(e))
+			}
+		})
+
+		t.Run("find *MyValueError", func(t *testing.T) {
+			t.Parallel()
+
+			var e *MyValueError
+			if !As(err, &e) {
+				t.Errorf("Expected to find *MyValueError, but didn't.")
+			} else if *e != MyValueError(8) {
+				t.Errorf("Expected *MyValueError(8), but got %d", int(*e))
+			}
+		})
+	})
+}