Error Handling

Description

Error Handling is a TypeScript module that provides a structured approach to error handling in applications and builds on top of @nuov.io/error-handler. It serves as the error handling layer for the @nuov.io ecosystem.

The ErrorHandling interface is designed for dependency injection. The ErrorHandlingService is an abstract singleton service that implements the ErrorHandler interface and simplifies creating application-wide error handling. The ThrowErrorHandler is a concrete ErrorHandler class that re-throws errors; it is a last resort in error handling.

Installation

npm install @nuov.io/error-handling

Usage

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 {
  type ErrorHandler,
  ErrorHandlingService,
} from "@nuov.io/error-handling";

class ExampleErrorHandlingService extends ErrorHandlingService<ExampleErrorHandlingService> {
  public static initialize(): void {
    const exampleErrorHandlingService: ExampleErrorHandlingService =
      new ExampleErrorHandlingService();
    exampleErrorHandlingService.initialize(exampleErrorHandlingService);
  }

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

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

// Initializing more than once throws an error
ExampleErrorHandlingService.initialize();
// throws: "The property 'ErrorHandlingService.instance' is not undefined."

// Access the singleton
ErrorHandlingService.instance.handleError(new Error("Something went wrong."));

// Create local variable
const errorHandler: ErrorHandler = ErrorHandlingService.instance;

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 { type ErrorHandler, ThrowErrorHandler } from "@nuov.io/error-handling";

const errorHandler: ErrorHandler = new ThrowErrorHandler();
errorHandler.handleError(new Error("This error will be re-thrown"));

Preferential error handling

This example demonstrates how to use this module to achieve preferential error handling:

import {
  type ErrorHandler,
  type ErrorHandling,
  ErrorHandlingService,
  ThrowErrorHandler,
} from "@nuov.io/error-handling";

class SomeService implements ErrorHandler {
  private readonly _errorHandler: ErrorHandler | undefined;

  public constructor(errorHandler?: ErrorHandler | ErrorHandling) {
    // this is intentionally verbose...

    // no ErrorHandler | ErrorHandling
    if (errorHandler === undefined) {
      this._errorHandler = undefined;
    }

    // ErrorHandling
    else if ("errorHandler" in errorHandler) {
      this._errorHandler = errorHandler.errorHandler;
    }

    // ErrorHandler
    else {
      this._errorHandler = errorHandler;
    }
  }

  public something(errorHandler?: ErrorHandler): void {
    try {
      // ...
      // code here
      // ...
    } catch (error: unknown) {
      // function level error handler
      if (errorHandler !== undefined) {
        errorHandler.handleError(error);
      } else {
        // defaults to class level error handler
        this.handleError(error);
      }
    }
  }

  public handleError(error: unknown): void {
    // class level error handler
    if (this._errorHandler !== undefined) {
      this._errorHandler.handleError(error);
    }

    // application level error handler
    else if (ErrorHandlingService.isInitialized) {
      ErrorHandlingService.instance.handleError(error);
    }

    // no error handler - last resort
    else {
      const throwErrorHandler: ErrorHandler = new ThrowErrorHandler();
      throwErrorHandler.handleError(error);
    }
  }
}

ErrorHandler and ErrorHandlerPrototype

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

import {
  type 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 extends ErrorHandlingService<T>> (abstract class)

An abstract singleton base class that implements the ErrorHandler interface to simplify the creation of application-wide error handling services.

Static Properties

| Property | Type | Description | | --------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- | | instance | ErrorHandler | Returns the singleton instance. Throws "The property 'ErrorHandlingService.instance' is undefined." 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 and is designed to be used within a subclass initialize static method. Throws "The property 'ErrorHandlingService.instance' is not undefined." if already initialized by any subclass. |

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. |

License

MIT License