feat: implement idiomatic error handling with As function

[yordis]

No description provided.

[coderabbitai]

Warning

Rate limit exceeded

@yordis has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 1 minutes and 32 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 730ca18 and 22004ce.

📒 Files selected for processing (3)

• error.go (1 hunks)
• error_test.go (1 hunks)
• example_test.go (1 hunks)

Walkthrough

Adds an unexported trogonError interface (Is(error) bool) and an exported As(err error, target trogonError) (*TrogonError, bool) helper that verifies a match via target.Is and extracts *TrogonError via errors.As; includes tests and an example.

Changes

Cohort / File(s)	Summary
Error API & core error.go	Adds unexported trogonError interface with Is(error) bool and introduces As(err error, target trogonError) (*TrogonError, bool) which calls target.Is(err) then errors.As to extract *TrogonError.
Tests error_test.go	Adds TestAs (subtests for matching, non-matching, non-TrogonError, WithChanges, direct TrogonError) and TestInternalMethods validating internal delegation and Is behavior.
Examples example_test.go	Adds ExampleAs_idiomaticErrorHandling() showing idiomatic As usage: template creation, error instantiation, As extraction, WithChanges, and expected output.
Module file go.mod	Listed in manifest; no functional changes.

Sequence Diagram(s)

sequenceDiagram
    participant Caller
    participant AsFn as As(err, target)
    participant Target as trogonError (Is)
    participant ErrorsPkg as errors.As
    participant Trogon as *TrogonError

    Caller->>AsFn: As(err, target)
    AsFn->>Target: target.Is(err)
    alt target.Is == true
        Target-->>AsFn: true
        AsFn->>ErrorsPkg: errors.As(err, **Trogon)
        ErrorsPkg-->>AsFn: found *TrogonError
        AsFn-->>Caller: return *TrogonError, true
    else target.Is == false
        Target-->>AsFn: false
        AsFn-->>Caller: return nil, false
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I hopped through lines to find the trace,
Matched a template, then pulled its face,
With As I nudged the error near,
Added metadata, quick and clear,
Hooray — no more chasing in the race.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Description Check	❓ Inconclusive	No pull request description was provided by the author. While the check is intentionally lenient and should pass as long as a description is not completely off-topic, the absence of any description makes it impossible to assess whether it relates to the changeset. Without descriptive content to evaluate, we cannot conclusively determine if this criterion is met or not.	The author should consider adding a brief description explaining the motivation, implementation details, or usage of the new As function and how it improves error handling in this package. Even a few sentences describing the purpose and benefits would help reviewers understand the intent behind the changes.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "feat: implement idiomatic error handling with As function" directly and clearly describes the main change in the changeset. The PR introduces a new As function that consolidates error matching and extraction, along with comprehensive tests and examples demonstrating this idiomatic error handling pattern. The title is specific, concise, and uses conventional commit formatting without unnecessary noise. It accurately captures the primary purpose of the changes from the developer's perspective.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 45736e2 and 09386e6.

📒 Files selected for processing (3)

• error.go (1 hunks)
• error_test.go (1 hunks)
• example_test.go (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• error_test.go
• example_test.go

🔇 Additional comments (2)

error.go (2)

897-899: LGTM! Clean interface design.

The unexported trogonError interface is a sound design choice that constrains the As function's target parameter to library-defined types (*TrogonError and *ErrorTemplate) while keeping the API flexible.

---

901-912: LGTM! Clear documentation with helpful example.

The documentation effectively explains the function's purpose and provides a practical usage example. After fixing the wrapped error issue, consider adding a note that this works with both direct and wrapped TrogonErrors.

[Copilot]

Pull Request Overview

This PR introduces a new As function that provides idiomatic error handling by combining error matching and extraction in a single operation. The function simplifies the pattern of checking if an error matches a template and extracting its TrogonError representation.

Key changes:

• Added new As function that accepts an error and a target (TrogonError or ErrorTemplate) and returns the matched TrogonError with a boolean indicator
• Introduced internal trogonError interface to support polymorphic matching behavior
• Added comprehensive test coverage for various matching scenarios including wrapped errors

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
error.go	Implements the new As function and trogonError interface for idiomatic error matching
error_test.go	Adds comprehensive test suite covering matching, wrapping, and change patterns for the As function
example_test.go	Demonstrates the new idiomatic error handling pattern using the As function

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}