Implementing Custom Error Classes in TypeScript: Best Practices and Solutions

Challenges and Solutions for Extending the Error Class in TypeScript

When creating custom error classes in TypeScript, developers often encounter a common issue: even with proper use of extends Error syntax, instanceof checks may return false. This problem stems from a breaking change introduced in TypeScript 2.1, which affects the inheritance behavior of built-in objects like Error, Array, and Map. In earlier versions, TypeScript's compiled output could lead to incorrect prototype chain setup, breaking the expected behavior of instanceof.

Core Solution: Explicitly Setting the Prototype

To address this, the TypeScript documentation recommends explicitly setting the prototype in the constructor of custom error classes. Here is a basic example:

class CustomError extends Error {
    constructor(message: string) {
        super(message);
        // Explicitly set the prototype to ensure instanceof works correctly
        Object.setPrototypeOf(this, CustomError.prototype);
    }
}

By calling Object.setPrototypeOf(this, CustomError.prototype), we ensure that the instance's prototype chain correctly points to the custom error class, rather than directly to the built-in Error prototype. This approach is necessary in TypeScript 2.1 and later to maintain compatibility with JavaScript runtimes.

Implementing the HttpRequestError Class

Based on this principle, we can create a feature-rich HttpRequestError class for handling HTTP request failures. This class not only extends Error but also adds custom properties (e.g., URL, response status code, and response body) and methods to provide detailed error information.

class HttpRequestError extends Error {
    public readonly url: string;
    public readonly statusCode: number;
    public readonly responseBody: string;

    constructor(url: string, statusCode: number, responseBody: string, message?: string) {
        // Construct a detailed error message
        const errorMessage = message || `Http request to ${url} failed with status code ${statusCode}`;
        super(errorMessage);
        
        // Set custom properties
        this.url = url;
        this.statusCode = statusCode;
        this.responseBody = responseBody;
        
        // Explicitly set the prototype
        Object.setPrototypeOf(this, HttpRequestError.prototype);
        
        // Optional: ensure the stack trace includes the error name
        this.name = 'HttpRequestError';
    }
    
    // Custom method for formatted output
    public getDetailedReport(): string {
        return `Http request to ${this.url} failed with status code ${this.statusCode} and message: ${this.message}\nResponse body: ${this.responseBody}`;
    }
}

In this implementation, the constructor accepts URL, status code, response body, and an optional error message as parameters. It uses this information to build a descriptive error message, passed to the parent Error class via super(). Custom properties (url, statusCode, responseBody) are properly initialized, and Object.setPrototypeOf ensures the prototype chain is set correctly. Additionally, we override the name property for clear identification in stack traces and add a getDetailedReport method to generate formatted error reports.

Usage Example and Error Handling

After creating an instance of HttpRequestError, we can leverage TypeScript's type system and error-handling mechanisms to manage these errors gracefully. Here is an example of usage:

try {
    // Simulate an HTTP request failure
    throw new HttpRequestError(
        'http://example.com',
        500,
        'Something went wrong',
        'Internal server error'
    );
} catch (error) {
    if (error instanceof HttpRequestError) {
        // Type-safe access to custom properties
        console.error(error.getDetailedReport());
        console.error('URL:', error.url);
        console.error('Status code:', error.statusCode);
        
        // Stack trace is available
        console.error(error.stack);
    } else {
        // Handle other types of errors
        console.error('Unexpected error:', error);
    }
}

In this example, we throw an HttpRequestError instance and use instanceof in the catch block for checking. Since we explicitly set the prototype, the instanceof check correctly returns true, allowing safe access to custom properties and methods. The error instance also inherits the stack property from Error, providing a full stack trace for debugging.

Best Practices and Considerations

When implementing custom error classes, following these best practices ensures robustness and maintainability:

1. Always Set the Prototype Explicitly: In TypeScript 2.1 and later, using Object.setPrototypeOf(this, CustomError.prototype) is key to ensuring instanceof works correctly. Omitting this step can lead to inconsistent behavior that is hard to debug.
2. Provide Meaningful Error Messages: Error messages should be clear, descriptive, and include sufficient context (e.g., URL, status code) to help developers quickly identify issues. Avoid generic messages like "Something went wrong".
3. Maintain Stack Trace Integrity: By calling super(message) and ensuring the error name is set correctly, you preserve useful stack traces. This is crucial for debugging in production environments.
4. Leverage TypeScript's Type Safety: Custom error classes allow you to add typed properties, which can catch errors at compile time and improve code reliability. For example, statusCode can be defined as a number type to prevent misuse.
5. Consider Backward Compatibility: If your project needs to support older TypeScript or JavaScript environments, test the behavior of custom error classes to ensure compatibility. In some environments, additional polyfills or workarounds may be necessary.

Additionally, when handling errors, it is advisable to categorize them as recoverable or non-recoverable and design error-handling logic accordingly. For HttpRequestError, you might want to implement different recovery strategies based on status codes (e.g., 404 vs 500).

Conclusion

Creating custom error classes in TypeScript is a powerful feature that can significantly enhance error handling and debugging. By understanding the changes in TypeScript 2.1 regarding extending built-in objects and adopting the solution of explicitly setting prototypes, developers can build robust custom error types like HttpRequestError. These classes not only provide type-safe properties and methods but also ensure the correctness of instanceof checks and stack traces. Combined with best practices such as providing meaningful error messages and maintaining compatibility, custom error classes become an essential tool for building reliable TypeScript applications. Through the examples and explanations in this article, we hope you feel more confident in implementing and using custom error-handling mechanisms in your projects.