Error Handling

Description

Error Handling is a TypeScript module that provides a structured approach to error handling in applications. It builds on top of @nuov.io/error-handler and offers an abstract singleton service (ErrorHandlingService) for managing application-wide error handling, a ready-to-use ThrowErrorHandler that re-throws errors, and an ErrorHandling interface for dependency injection. It is designed to be extended by concrete implementations and serves as the error handling layer for the @nuov.io ecosystem.

Installation

npm install @nuov.io/error-handling

Usage

Using ThrowErrorHandler

ThrowErrorHandler is a concrete error handler that simply re-throws any error passed to it. It is useful as a default handler or in testing scenarios.

import { ThrowErrorHandler } from '@nuov.io/error-handling';

const handler = new ThrowErrorHandler();
handler.handleError(new Error('This error will be re-thrown'));

Extending ErrorHandlingService

ErrorHandlingService is an abstract singleton base class. Extend it to create a custom error handling service, initialize it once at application startup, and access the instance anywhere via the static instance getter.

import { ErrorHandlingService } from '@nuov.io/error-handling';

class AnErrorHandlingService extends ErrorHandlingService<AnErrorHandlingService> {
  private constructor() {
    super();
  }

  public static initialize(): void {
    const anErrorHandlingService: AnErrorHandlingService =
      new AnErrorHandlingService();
    anErrorHandlingService.initialize(anErrorHandlingService);
  }

  public override handleError(error: unknown): void {
    // Custom error handling logic here
  }
}

// Initialize once at startup
AnErrorHandlingService.initialize();

Using ErrorHandlingService

import { ErrorHandlingService } from '@nuov.io/error-handling';

class MyService {
  public doWork(): void {
    try {
      // ... work ...
    } catch (error) {
      // Access the singleton instance anywhere
      ErrorHandlingService.instance.handleError(error);
    }
  }
}

Re-exported types

This package also re-exports ErrorHandler and ErrorHandlerPrototype from @nuov.io/error-handler for convenience.

import { ErrorHandler, ErrorHandlerPrototype } from '@nuov.io/error-handling';

API Reference

ErrorHandling (interface)

A contract for classes that expose an error handler.

| Property | Type | Description | | ----------------------- | -------------- | --------------------------- | | readonly errorHandler | ErrorHandler | The error handler instance. |

ErrorHandlingService<T> (abstract class)

An abstract singleton base class for application-wide error handling services.

Static Properties

| Property | Type | Description | | --------------- | -------------- | ------------------------------------------------------------------- | | instance | ErrorHandler | Returns the singleton instance. Throws an error if not initialized. | | isInitialized | boolean | Returns true if the service has been initialized. |

Protected Methods

| Method | Returns | Description | | ------------------------------------- | ------- | -------------------------------------------------------------------- | | initialize(errorHandlingService: T) | void | Sets the singleton instance. Throws an error if already initialized. |

Abstract Methods

| Method | Returns | Description | | ----------------------------- | ------- | ----------------------------------------------------- | | handleError(error: unknown) | void | Handles the error. Must be implemented by subclasses. |

ThrowErrorHandler (class)

A concrete error handler that re-throws any error passed to it. Extends ErrorHandlerPrototype.

Constructor

new ThrowErrorHandler();

Methods

| Method | Returns | Description | | ----------------------------- | ------- | ----------------------------- | | handleError(error: unknown) | void | Re-throws the provided error. |

Features

• Singleton pattern — ErrorHandlingService enforces a single, application-wide error handler
• Dependency injection ready — ErrorHandling interface decouples consumers from concrete implementations
• Ready-to-use handler — ThrowErrorHandler provides a zero-config handler that re-throws errors
• Extensible — designed to be subclassed for custom error handling strategies (logging, reporting, etc.)
• TypeScript-first — full type definitions included
• ESM-only — distributed as an ES module

License

MIT License