exception-hierarchies_skill

Overview

This skill helps you design and apply TypeScript exception hierarchies so errors are caught at the right abstraction level and handled meaningfully. It prescribes a three-layer model (Application -> Category -> Specific) and practical patterns for wrapping third-party errors and boundary handling. Use it to make error handling predictable, debuggable, and testable.

How this skill works

The skill defines a base ApplicationError with code and context, category subclasses (DomainError, InfrastructureError, ExternalError), and concrete exceptions (ValidationError, NotFoundError, DatabaseError, PaymentGatewayError). It inspects where catches occur and recommends refactoring to catch specific types or let errors propagate to the application boundary. It also shows how to wrap library errors at adapter boundaries and map exceptions to HTTP responses.

When to use it

• When creating custom exception classes for a TypeScript project
• When error handling feels chaotic or catch blocks are too broad
• When refactoring scattered try/catch logic
• When wrapping third-party library errors at adapter boundaries
• When debugging generic catch-alls that hide root causes

Best practices

• Never catch the base ApplicationError except at application boundaries
• Create category exceptions (Domain/Infrastructure/External) to group related failures
• Give specific exceptions meaningful context and readonly fields for structured logging
• Wrap library-specific errors in adapters and throw your application exceptions
• Map exceptions to HTTP status codes only in boundary middleware; keep business code focused on types

Example use cases

• A service layer that distinguishes ValidationError vs BusinessRuleError and re-throws for controller formatting
• A repository adapter that converts pg.DatabaseError into DatabaseError before it reaches domain code
• HTTP error middleware that inspects exception types and returns 400/404/422/502/503 appropriately
• Retry/fallback logic triggered specifically for PaymentGatewayError while other errors propagate
• Refactoring a codebase where many catch blocks log-and-continue into a typed exception hierarchy