Exception 🚦

Version 1.1.0

Handle errors with ease

This documentation describes the Exception class, which provides a structured way to handle errors in TypeScript. It includes custom properties such as code, name, and status for more detailed error reporting and debugging.

Table of Contents

• Getting started
• API Reference
  • ExceptionOptions Interface
  • Exception Class
  • Usage Scenarios
• Development
  • ESLint
  • Jest
• Contributing
• Security
• Credits

Overview

The Exception class extends the native JavaScript Error object, adding customizable fields to improve error classification and handling. It also includes a static utility method to check if an object is an instance of the Exception class.

Getting started

Run the following command to start using @alessiofrittoli/exception in your projects:

npm i @alessiofrittoli/exception

or using pnpm

pnpm i @alessiofrittoli/exception

API Reference

ExceptionOptions Interface

The ExceptionOptions interface defines the optional parameters for the Exception class constructor.

Properties

Exception Class

The Exception class extends the Error object and implements the ExceptionOptions interface.

Constructor

The constructor initializes an Exception instance with a custom message and options.

Parameters

Example

import Exception from '@alessiofrittoli/exception'

try {
    throw new Exception( 'Resource not found', {
        code	: 'ERRNOTFOUND',
        status	: 404,
    } )
} catch ( error ) {
    console.error( error )
}

Static Methods

isException

A utility method to check if an object is an instance of the Exception class.

Example

try {
    throw new Exception( 'Something went wrong', { code: 'ERRUNKNOWN' } )
} catch ( error ) {
    if ( Exception.isException( error ) ) {
        // we can safely access `Exception` properties
        console.error( `Error [${ error.code }]: ${ error.message }` )
    } else {
        console.error( error )
    }
}

Usage Scenarios

Custom Error Handling

The Exception class is ideal for creating domain-specific errors with additional metadata, such as error codes and HTTP statuses.

Example

enum ErrorCode
{
    EMPTY_VALUE	= 'ERREMPTYVALUE',
    WRONG_FORMAT= 'ERRWRONGFORMAT',
    EXPIRED		= 'ERREXPIRED',
    TOO_EARLY	= 'ERRTOOEARLY',
    NOT_ALLOWED	= 'ERRNOTALLOWED',
}

try {
    await fetch( ... )
} catch ( error ) {
    // error thrown by the server: Exception( 'Wrong value.', { code: ErrorCode.WRONG_FORMAT, status: 422 } )
    if ( Exception.isException<string, ErrorCode>( error ) ) {
        console.log( error.code ) // `error.code` is type of `ErrorCode`.
    }
}

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build your source code

Run the following command to build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test

# Run tests and watch file changes with jest-environment-jsdom.
pnpm test:jsdom

# Run tests in a CI environment.
pnpm test:ci

# Run tests in a CI environment with jest-environment-jsdom.
pnpm test:ci:jsdom

You can eventually run specific suits like so:

pnpm test:jest
pnpm test:jest:jsdom

Contributing

Contributions are truly welcome!
Please refer to the Contributing Doc for more information on how to start contributing to this project.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email security@alessiofrittoli.it to disclose any security vulnerabilities.

Made with ☕

Alessio Frittoli https://alessiofrittoli.it | info@alessiofrittoli.it