forge-error

A comprehensive and type-safe HTTP error handling library for Node.js and TypeScript applications. forge-error provides a structured, standardized, and consistent approach to defining, throwing, and handling HTTP errors with minimal boilerplate code. With fully typed error classes and built-in support for standardized error responses, it helps you write cleaner, more maintainable error handling logic in your application.

Table of Contents

1. Installation

2. Features

3. Usage

   • Creating Errors
   • Express Integration
   • Async Error Handling
   • Global Error Handler

4. Error Classes

5. Utilities

6. Error Payload Structure

7. Built-in Error Constants

Installation

npm install forge-error
# or
yarn add forge-error
# or
pnpm add forge-error

Features

• Full suite of HTTP error classes (4xx and 5xx)
• Standardized error payload structure
• First-class TypeScript support
• Custom error code and data support
• Utility functions to handle, format, and inspect errors
• Seamless integration with Express.js
• Async controller wrapper for concise error handling

Usage

Creating Errors

You can create errors using one of the built-in error classes or create fully custom errors with ForgeError.

Using a Simple String

import { NotFoundError } from 'forge-error';

throw new NotFoundError('Resource not found');

Using a Detailed Object

import { BadRequestError } from 'forge-error';

throw new BadRequestError({
  message: 'Invalid input data',
  data: {
    field: 'email',
    issue: 'Invalid format'
  },
  errorCode: 'INVALID_EMAIL'
});

Creating a Custom Error

import { ForgeError } from 'forge-error';

throw new ForgeError(
  'Custom error occurred',
  418,
  'CUSTOM_ERROR_CODE',
  { additional: 'context' }
);

Express Integration

You can easily integrate forge-error with your Express.js application to return consistent error responses.

Wrapping Async Controllers

Use handleAsyncRequest to wrap controller logic and eliminate manual try-catch blocks:

import express, { Request, Response } from 'express';
import { handleAsyncRequest } from 'forge-error';

const app = express();

app.post('/login', handleAsyncRequest(async (req: Request, res: Response) => {
  // Your logic here
  res.status(200).json({ message: 'Login successful' });
}));

You can also export wrapped handlers:

// controllers/auth.controller.ts
app.post('/login', loginController);

const loginController = handleAsyncRequest(async (req, res) => {
  // Logic here
});

---

Global Error Handler

Use getForgeErrorPayload to build standardized error responses in your global error middleware:

const app = express();

app.use(routes)

app.use((error, req, res, next) => {
  const { statusCode, errorCode, message, data } = getForgeErrorPayload(error);

  res.status(statusCode).json({
    success: false,
    statusCode,
    errorCode,
    message,
    ...(data ? { data } : {})
  });
});

app.use((req, res) => {
  res.status(404).json({
    success: false,
    statusCode: 404,
    errorCode: 'NOT_FOUND',
    message: 'Resource not found'
  });
})

import { ErrorRequestHandler } from 'express';
import { getForgeErrorPayload } from 'forge-error';

const errorHandler: ErrorRequestHandler = (err, req, res, next) => {
  const { statusCode, errorCode, message, data } = getForgeErrorPayload(err);

  res.status(statusCode).json({
    success: false,
    statusCode,
    errorCode,
    message,
    ...(data ? { data } : {})
  });
};

export { errorHandler };

Error Classes

The library provides predefined error classes corresponding to standard HTTP status codes.

Client Errors (4xx)

import {
  BadRequestError,           // 400
  UnauthorizedError,         // 401
  ForbiddenError,            // 403
  NotFoundError,             // 404
  MethodNotAllowedError,     // 405
  NotAcceptableError,        // 406
  ConflictError,             // 409
  // ... and more
} from 'forge-error';

Server Errors (5xx)

import {
  InternalServerError,       // 500
  NotImplementedError,       // 501
  BadGatewayError,           // 502
  ServiceUnavailableError,   // 503
  GatewayTimeoutError,       // 504
  // ... and more
} from 'forge-error';

Utilities

The package provides several utility functions to handle error payloads. These are divided into two categories:

Type-Specific Utilities (Return undefined for non-matching errors)

import { getErrorPayload, getClientErrorPayload, getServerErrorPayload } from 'forge-error';

// 1. Get payload for any forge error
const error1 = new NotFoundError('Resource not found');
const payload1 = getErrorPayload(error1);
// Returns: { message: 'Resource not found', statusCode: 404, errorCode: 'NOT_FOUND' }

const error2 = new Error('Regular error');
const payload2 = getErrorPayload(error2);
// Returns: undefined

// 2. Get payload only for client errors (4xx)
const clientError = new NotFoundError('Not found');
const clientPayload = getClientErrorPayload(clientError);
// Returns: { message: 'Not found', statusCode: 404, errorCode: 'NOT_FOUND' }

const serverError = new InternalServerError('Server error');
const wrongPayload = getClientErrorPayload(serverError);
// Returns: undefined

// 3. Get payload only for server errors (5xx)
const serverPayload = getServerErrorPayload(serverError);
// Returns: { message: 'Server error', statusCode: 500, errorCode: 'INTERNAL_SERVER_ERROR' }

Guaranteed Payload Utilities (Always return a payload)

import { 
  getForgeClientErrorPayload, 
  getForgeServerErrorPayload, 
  getForgeErrorPayload 
} from 'forge-error';

// 1. Always get a client error payload
const error = new Error('Unknown error');
const clientPayload = getForgeClientErrorPayload(error);
// Returns: { 
//   message: 'Unknown error', 
//   statusCode: 400,          // Default client error status
//   errorCode: 'BAD_REQUEST'  // Default client error code
// }

// 2. Always get a server error payload
const serverPayload = getForgeServerErrorPayload(error);
// Returns: {
//   message: 'Unknown error',
//   statusCode: 500,                  // Default server error status
//   errorCode: 'INTERNAL_SERVER_ERROR' // Default server error code
// }

// 3. Always get a generic error payload (uses server error defaults)
const genericPayload = getForgeErrorPayload(error);
// Returns: {
//   message: 'Unknown error',
//   statusCode: 500,
//   errorCode: 'INTERNAL_SERVER_ERROR'
// }

// Common usage in Express error handler:
app.use((error, req, res, next) => {
  // Will always return a valid error response
  const { statusCode, ...payload } = getForgeErrorPayload(error);
  res.status(statusCode).json(payload);
});

import { isClientError, isServerError, isBaseError } from 'forge-error';

const error = new NotFoundError('Resource not found');

isClientError(error);  // true
isServerError(error);  // false
isBaseError(error);    // true

Error Payload Structure

All forge errors return a standardized structure:

{
  message: string;      // Human-readable error message
  statusCode: number;   // HTTP status code
  errorCode: string;    // Error identifier
  data?: object;        // Optional additional context
}

This format is useful for consistent API responses, logging, and debugging.

Error Handling Example

try {
  // Your code here
  throw new BadRequestError('Invalid input');
} catch (error) {
  if (error instanceof BadRequestError) {
    const payload = error.buildErrorPayload();
    // Handle the error with standardized payload
    console.log(payload);
    /*
    {
      message: 'Invalid input',
      statusCode: 400,
      errorCode: 'BAD_REQUEST'
    }
    */
  }
}

Built-in Error Constants

The library includes a comprehensive set of predefined HTTP error types with their default values. You can override these defaults using a detailed object.

Error Class	Status Code	Error Code	Default Message
4xx Client Errors
BadRequestError	400	BAD_REQUEST	The request could not be processed due to invalid syntax or parameters
UnauthorizedError	401	UNAUTHORIZED	Authentication is required to access this resource
PaymentRequiredError	402	PAYMENT_REQUIRED	Payment is required to access this resource
ForbiddenError	403	FORBIDDEN	You do not have permission to access this resource
NotFoundError	404	NOT_FOUND	The requested resource could not be found
MethodNotAllowedError	405	METHOD_NOT_ALLOWED	The requested HTTP method is not allowed for this resource
NotAcceptableError	406	NOT_ACCEPTABLE	The requested content type cannot be served by this resource
ProxyAuthenticationRequiredError	407	PROXY_AUTHENTICATION_REQUIRED	Proxy server authentication is required
RequestTimeoutError	408	REQUEST_TIMEOUT	The server timed out waiting for the request
ConflictError	409	CONFLICT	The request conflicts with the current state
GoneError	410	GONE	The requested resource is no longer available
LengthRequiredError	411	LENGTH_REQUIRED	Content-Length header is required
PreconditionFailedError	412	PRECONDITION_FAILED	One or more conditions failed
PayloadTooLargeError	413	PAYLOAD_TOO_LARGE	Request payload exceeds the limit
URITooLongError	414	URI_TOO_LONG	Request URI exceeds the maximum length
UnsupportedMediaTypeError	415	UNSUPPORTED_MEDIA_TYPE	The content type is not supported
RangeNotSatisfiableError	416	RANGE_NOT_SATISFIABLE	The requested range cannot be satisfied
ExpectationFailedError	417	EXPECTATION_FAILED	Server cannot meet the requirements
TeapotError	418	IM_A_TEAPOT	I'm a teapot
SessionExpiredError	419	SESSION_EXPIRED	Your session has expired. Please refresh and try again
RateLimitError	420	RATE_LIMIT_EXCEEDED	Request rate limit has been exceeded
MisdirectedRequestError	421	MISDIRECTED_REQUEST	The request was sent to a server unable to produce a response
UnprocessableEntityError	422	UNPROCESSABLE_ENTITY	The request was well-formed but invalid
LockedError	423	RESOURCE_LOCKED	The requested resource is currently locked
FailedDependencyError	424	FAILED_DEPENDENCY	The request failed due to the failure of a previous request
TooEarlyError	425	TOO_EARLY	The server is not ready to process the request
UpgradeRequiredError	426	UPGRADE_REQUIRED	Client must upgrade to a different protocol version
PreconditionRequiredError	428	PRECONDITION_REQUIRED	This request requires preconditions to be specified
TooManyRequestsError	429	TOO_MANY_REQUESTS	Rate limit exceeded
RequestHeaderFieldsTooLargeError	431	REQUEST_HEADERS_TOO_LARGE	Request header fields exceed maximum size
NoResponseError	444	NO_RESPONSE	Server returned no information and closed the connection
RetryWithError	449	RETRY_WITH	The request should be retried after performing the appropriate action
BlockedByWindowsParentalControlsError	450	BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS	Access denied by Windows parental controls
LegallyRestrictedError	451	LEGALLY_RESTRICTED	Access denied for legal reasons
RequestHeaderTooLargeError	494	REQUEST_HEADER_TOO_LARGE	Request header is too large
SSLCertificateError	495	SSL_CERTIFICATE_ERROR	SSL/TLS certificate validation error
SSLCertificateRequiredError	496	SSL_CERTIFICATE_REQUIRED	A valid SSL/TLS certificate is required
HTTPRequestSentToHTTPSPortError	497	HTTP_REQUEST_SENT_TO_HTTPS_PORT	An HTTP request was sent to an HTTPS port
InvalidTokenError	498	INVALID_TOKEN	The token provided is invalid or has expired
TokenRequiredError	499	TOKEN_REQUIRED	A valid token is required to access this resource
ClientClosedRequestError	499	CLIENT_CLOSED_REQUEST	Client closed the request before the server could respond
5xx Server Errors
InternalServerError	500	INTERNAL_SERVER_ERROR	An unexpected error occurred
NotImplementedError	501	NOT_IMPLEMENTED	Not implemented
BadGatewayError	502	BAD_GATEWAY	Invalid response from upstream server
ServiceUnavailableError	503	SERVICE_UNAVAILABLE	Service temporarily unavailable
GatewayTimeoutError	504	GATEWAY_TIMEOUT	Gateway timeout
HTTPVersionNotSupportedError	505	HTTP_VERSION_NOT_SUPPORTED	HTTP version not supported
VariantAlsoNegotiatesError	506	VARIANT_ALSO_NEGOTIATES	Server configuration error in content negotiation
InsufficientStorageError	507	INSUFFICIENT_STORAGE	Insufficient storage space to complete the request
LoopDetectedError	508	LOOP_DETECTED	Request processing stopped due to infinite loop detection
BandwidthLimitExceededError	509	BANDWIDTH_LIMIT_EXCEEDED	Server bandwidth limit has been exceeded
NotExtendedError	510	NOT_EXTENDED	Server requires additional extensions to fulfill the request
NetworkAuthenticationRequiredError	511	NETWORK_AUTHENTICATION_REQUIRED	Network authentication is required

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.