Error Shield

A comprehensive error handling utility for Node.js & Express.js applications. Provides structured error handling, formatting, and Express.js middleware support.

Features

• 🎯 Custom Error Class - Extendable AppError class with status codes and context
• 📦 Error Formatting - Consistent error formatting with customizable options
• 🔄 Async Handler - Wrapper for async functions to catch errors
• 🚀 Express Middleware - Ready-to-use Express.js error handler middleware
• 🛠️ Error Creators - Pre-built error creators for common HTTP status codes
• 📝 TypeScript Support - Full TypeScript definitions included

Installation

npm install error-shield

Usage

Basic Usage

const { AppError, handleError, ErrorCreators } = require("error-shield");

// Create a custom error
const error = new AppError("Something went wrong", 500, "CUSTOM_ERROR", {
  userId: 123,
  action: "updateProfile",
});

// Handle and format error
const errorDetails = handleError(error, {
  includeStack: true,
  includeTimestamp: true,
});

console.log(errorDetails);

Using Error Creators

const { ErrorCreators } = require("error-shield");

// Bad Request (400)
throw ErrorCreators.badRequest("Invalid input provided", { field: "email" });

// Unauthorized (401)
throw ErrorCreators.unauthorized("Authentication required");

// Not Found (404)
throw ErrorCreators.notFound("User not found", { userId: 123 });

// Validation Error (422)
throw ErrorCreators.validationError("Email is required", { field: "email" });

Express.js Middleware

const express = require("express");
const { expressErrorHandler, ErrorCreators } = require("error-shield");

const app = express();

// Your routes
app.get("/users/:id", async (req, res, next) => {
  const user = await getUserById(req.params.id);
  if (!user) {
    throw ErrorCreators.notFound("User not found", { userId: req.params.id });
  }
  res.json(user);
});

// Error handler middleware (must be last)
app.use(
  expressErrorHandler({
    includeStack: process.env.NODE_ENV !== "production",
    includeTimestamp: true,
  }),
);

app.listen(3000);

Async Handler Wrapper

const { asyncHandler } = require("error-shield");

// Wrap async route handlers
app.get(
  "/api/data",
  asyncHandler(async (req, res) => {
    const data = await fetchData();
    res.json(data);
  }),
);

Custom Logger

const { handleError } = require("error-shield");

const errorDetails = handleError(error, {
  logger: (errorDetails) => {
    // Custom logging logic
    console.error("Error occurred:", errorDetails);
    // Send to logging service, etc.
  },
});

API Reference

AppError

Custom error class that extends the native Error class.

class AppError extends Error {
  code?: string;
  statusCode?: number;
  context?: Record<string, any>;
  isOperational: boolean;
}

Constructor:

• message: string - Error message
• statusCode: number - HTTP status code (default: 500)
• code?: string - Error code
• context?: Record<string, any> - Additional context

formatError(error, options?)

Formats an error into a structured object.

Parameters:

• error: Error | AppError - The error to format
• options: ErrorHandlerOptions - Formatting options

Returns: ErrorDetails

handleError(error, options?)

Handles errors with optional logging and formatting.

Parameters:

• error: Error | AppError - The error to handle
• options: ErrorHandlerOptions - Handler options

Returns: ErrorDetails

asyncHandler(fn)

Wraps an async function to catch errors.

Parameters:

• fn: Function - Async function to wrap

Returns: Wrapped function

expressErrorHandler(options?)

Creates an Express.js error handler middleware.

Parameters:

• options: ErrorHandlerOptions - Handler options

Returns: Express middleware function

ErrorCreators

Pre-built error creators for all standard HTTP error status codes:

4xx Client Errors:

5xx Server Errors:

TypeScript Support

This package includes full TypeScript definitions:

import { AppError, ErrorCreators, handleError } from "error-shield";

const error: AppError = ErrorCreators.notFound("User not found");
const details = handleError(error);

License

ISC

Author

Gopinath Kathirvel