clean-error-maker

A lightweight, production-ready utility for creating consistent, structured HTTP errors in Node.js and Express applications.

Designed to standardize error handling across APIs with minimal setup.

✨ Features

• ✅ Custom HttpError class
• ✅ Predefined HTTP error helpers (400–500)
• ✅ Clean, consistent JSON error responses
• ✅ Optional error codes & extra data
• ✅ Express error-handling middleware
• ✅ Environment-aware stack traces
• ✅ Zero dependencies

📦 Installation

npm install clean-error-maker

🚀 Quick Start

Throwing a predefined HTTP error

const { notFound } = require("clean-error-maker");

throw notFound("User not found");

🧠 Core Concepts

HttpError

All errors are instances of a custom HttpError class, extending JavaScript’s native Error while adding HTTP-specific metadata.

Each error contains:

• status – HTTP status code
• message – human-readable description
• success – always false
• timestamp – ISO timestamp
• optional code – application-level error code
• optional data – extra contextual data

📘 Usage Guide

1️⃣ Predefined Error Helpers (Recommended)

const {
  badRequest,
  unauthorized,
  forbidden,
  notFound,
  conflict,
  internal,
} = require("clean-error-maker");

throw badRequest("Invalid email format");
throw unauthorized("Login required");
throw notFound("Resource not found");

These helpers automatically set:

• Correct HTTP status
• Standard error code
• Consistent error shape

2️⃣ Creating a Custom HttpError

const { HttpError } = require("clean-error-maker");

throw new HttpError(
  422,
  "Validation failed",
  "VALIDATION_ERROR",
  { field: "email" }
);

3️⃣ Express.js Error Middleware (Recommended)

clean-error-maker provides a ready-to-use Express error-handling middleware.

Setup

const express = require("express");
const { notFound } = require("clean-error-maker");
const errorHandler = require("clean-error-maker/middleware");

const app = express();

app.get("/user/:id", (req, res) => {
  throw notFound("User does not exist");
});

app.use(errorHandler);

🧾 Example JSON Response

{
  "success": false,
  "status": 404,
  "message": "User not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-12-22T15:00:10.000Z"
}

In development mode, stack traces are automatically included.

🎯 Why Use clean-error-maker?

• Enforces a single error format across your API
• Reduces repetitive error-handling code
• Makes Express error handling predictable
• Clean separation between business logic and response formatting
• Easy to extend and maintain

🧩 Ideal For

• REST APIs
• Express.js applications
• Microservices
• Production-ready backend systems

📌 Versioning

This package follows Semantic Versioning.

• Breaking changes → MAJOR
• New features → MINOR
• Bug fixes → PATCH

📄 License

MIT License