Node Custom Exception Utility

0.1.2 · active · verified Sun Apr 19

The `custom-exception` package, currently at version 0.1.2, provides a foundational utility for creating custom error classes within Node.js applications. It aims to simplify the process of defining structured, extensible error types beyond the standard JavaScript `Error` object. While still in early development, as indicated by its low version number, it offers a mechanism to differentiate application-specific errors programmatically. Its release cadence is likely irregular, given its nascent stage. Key differentiators typically include boilerplate reduction for custom error inheritance, properties like status codes, and improved stack trace handling, though specifics depend on the full API. Users should anticipate potential API changes as the library evolves towards a stable major release.

Common errors

```
TypeError: Class constructor CustomError cannot be invoked without 'new'
```
cause Attempting to call `CustomError` or a derived class as a function instead of instantiating it with `new`.

fix Always create instances of `CustomError` or its derivatives using `new`, e.g., `throw new CustomError('message');`.
```
MyCustomError is not an instance of CustomError
```
cause This typically occurs in transpiled environments where the prototype chain is not correctly re-established for custom error classes, preventing `instanceof` from working as expected.

fix Ensure `Object.setPrototypeOf(this, MyCustomError.prototype);` is called in your custom error's constructor after `super()`.

Warnings

breaking As the package is at version 0.1.2, its API is considered unstable. Minor or patch releases may introduce breaking changes without prior deprecation warnings. Users should lock package versions and review changes upon upgrade.
Fix: Pin your package version (e.g., `"custom-exception": "0.1.2"`) and manually review the changelog before upgrading to new minor or patch versions.
gotcha When extending `CustomError` in a transpiled environment (e.g., Babel, TypeScript targeting ES5/ES2015), you must explicitly call `Object.setPrototypeOf(this, MyCustomError.prototype)` in the constructor after `super()` to ensure `instanceof` checks work correctly.
Fix: Add `Object.setPrototypeOf(this, MyCustomError.prototype);` to your custom error class constructor after `super(message);`.
gotcha Forgetting to set `this.name` in your custom error class constructor will result in the error name defaulting to 'CustomError' or 'Error' instead of your specific class name.
Fix: Always set `this.name = 'MyCustomError';` in the constructor of your derived error class to ensure accurate error identification.

Install

npm install custom-exception npm
yarn add custom-exception yarn
pnpm add custom-exception pnpm

Imports

CustomError
wrong:
```
const { CustomError } = require('custom-exception');
```
correct:
```
import { CustomError } from 'custom-exception';
```
The library primarily targets modern JavaScript environments. While CommonJS might work via transpilation, direct ESM import is recommended. The API is considered experimental in v0.1.2.
CustomError
wrong:
```
class MyError extends Error { /* ... */ } // Misses custom-exception's features
```
correct:
```
class MyError extends CustomError { /* ... */ }
```
To leverage the library's features, extend the provided `CustomError` class instead of the native `Error`.

Quickstart

Demonstrates defining a custom error by extending `CustomError`, adding custom properties, and catching it with `instanceof` checks.

import { CustomError } from 'custom-exception';

/**
 * Define a custom application-specific error by extending CustomError.
 * This allows for adding custom properties like 'code' or 'data'.
 */
class NotFoundError extends CustomError {
  constructor(message: string, resourceId?: string) {
    super(message);
    this.name = 'NotFoundError';
    this.statusCode = 404; // Custom property
    this.resourceId = resourceId; // Custom property
    // Restore prototype chain for 'instanceof' checks in transpiled environments
    Object.setPrototypeOf(this, NotFoundError.prototype);
  }
}

/**
 * A function that might throw our custom error.
 */
function getUser(userId: string) {
  if (userId === 'nonexistent') {
    throw new NotFoundError(`User with ID '${userId}' not found.`, userId);
  }
  return { id: userId, name: `User ${userId}` };
}

try {
  const user = getUser('nonexistent');
  console.log(user);
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error(`Error: ${error.name} - ${error.message} (Status: ${error.statusCode}, Resource: ${error.resourceId})`);
  } else if (error instanceof CustomError) {
    console.error(`Caught a generic CustomError: ${error.name} - ${error.message}`);
  } else if (error instanceof Error) {
    console.error(`Caught a standard Error: ${error.name} - ${error.message}`);
  }
}

view raw JSON →