express-error-toolkit

!typescript
!minified
!minified gzip

👉 View on npm

A lightweight, production-ready error handling toolkit for Express.js applications — written in TypeScript with full support for both CommonJS and ESM.

If you like the project, please give the project a GitHub ⭐

It provides:

- Custom error classes (NotFoundError, BadRequestError, ValidationError, etc.)
- Express middleware: globalErrorHandler, notFoundHandler
- An asyncHandler utility to handle async errors without boilerplate
- A httpError() factory function to create custom error instances easily
- isCustomAPIError() type guard for safe error type checks

---

✨ Features

- ✅ Type-safe custom error classes
- ✅ Centralized error-handling middleware
- ✅ Async error wrapper for route handlers
- ✅ Built-in 404 (Not Found) handler
- ✅ Factory method for generating custom errors
- ✅ Type guard for runtime error checking
- ✅ Out-of-the-box support for both CJS and ESM

---

🚀 Installation Guide

You can install express-error-toolkit using your favorite package manager.

Using npm

``bash
npm install express-error-toolkit
`

Using yarn

`bash
yarn add express-error-toolkit
`

Using pnpm

`bash
pnpm add express-error-toolkit
`

> ⚙️ Requires Node.js v14 or higher.
> ℹ️ Make sure you have express installed in your project, as this toolkit is built specifically to enhance Express.js error handling.

---

📁 Usage

$3

`ts
import express from 'express';
import { asyncHandler } from 'express-error-toolkit';

const app = express();

app.get(
'/users/:id',
asyncHandler(async (req, res) => {
// Your async code here
throw new Error('Something went wrong!');
})
);
`

---

$3

`ts
import { NotFoundError, BadRequestError } from 'express-error-toolkit';

app.get('/test', (req, res) => {
throw new NotFoundError('User not found');
});
`

Each custom error automatically sets the correct statusCode and name.

You can also pass optional errorDetails as a string, object, or leave it out:

`ts
throw new BadRequestError('Invalid data', { field: 'email' });
throw new BadRequestError('Invalid input', 'Missing required field');
throw new BadRequestError('Generic client error');
`

---

$3

`ts
import { notFoundHandler } from 'express-error-toolkit';

app.use(notFoundHandler);
`

This will throw a NotFoundError with the method and route info.

---

$3

`ts
import { globalErrorHandler } from 'express-error-toolkit';

app.use(globalErrorHandler);
`

By default, the handler includes the stack trace and logs the error in development.
In production (NODE_ENV=production), both are automatically suppressed for safety.

---

$3

To enhance developer experience during debugging, this toolkit uses ANSI escape codes — no external dependencies like chalk required — to make console logs more readable.

Each part of the error log is styled using a traffic light-inspired color scheme:

- 🔴 Error Status & Message – Red
- 🟡 Error Details – Yellow (optional; string or object)
- 🟢 Stack Trace – Green (shown only if available and enabled)

> 🖼️ Example: Here's how the console might look in development mode:

!Colored error output preview

---

#### ✨ Customizing the Intro Line

By default, an introductory line ("Even the best code breaks sometimes! Let's debug...") is displayed before each error block.

You can control this with the introLine option:

`ts
import { setErrorOptions } from 'express-error-toolkit';

// Disable the intro line
setErrorOptions({
introLine: false
});

// Customize the intro line
setErrorOptions({
introLine: '🚨 Debugging session begins here...'
});
`

---

$3

You can configure the error handling behavior (e.g., hide stack traces and disable console logging even in development) using either:

`.env
SHOW_STACK=false
LOG_ERROR=false
`

or directly in your code:

`ts
import { setErrorOptions } from 'express-error-toolkit';

setErrorOptions({
showStack: false,
logError: false
});
`

This overrides the default behavior (based on NODE_ENV or .env file).

---

$3

`ts
import { httpError } from 'express-error-toolkit';

throw httpError('Something custom', 418);
`

You can also pass optional errorDetails as a string, object, or leave it out:

`ts
throw httpError('Expectation failed', 417, { reason: 'The server could not meet the Expect header requirements' });
throw httpError('Failed Dependency', 424, 'This request relies on a previous request that failed' );
throw httpError('Unavailable for legal reason', 451);
`

---

$3

`ts
import { isCustomAPIError } from 'express-error-toolkit';

if (isCustomAPIError(err)) {
console.log(err.statusCode, err.message);
// your rest of the code
}
`

---

🔧 Custom Error Classes Available

| Error Class | Default Message | Status Code |
|------------------------|-------------------------|-------------|
| BadRequestError | Bad Request | 400 |
| UnauthorizedError | Unauthorized | 401 |
| ForbiddenError | Forbidden | 403 |
| NotFoundError | Not Found | 404 |
| ConflictError | Conflict | 409 |
| ValidationError | Unprocessable Entity | 422 |
| TooManyRequestsError | Too Many Requests | 429 |
| CustomAPIError | Internal Server Error | 500 |

---

📂 Directory Structure

`
├── src/
│ ├── error/
│ │ ├── BadRequestError.ts
│ │ ├── NotFoundError.ts
│ │ └── ...
│ ├── global-error-handler.ts
│ ├── async-handler.ts
│ ├── http-error.ts
│ └── index.ts
├── example/
│ └── index.ts
├── __tests__/
│ └── *.test.ts
`

---

🛠 Build & Compatibility

- Fully written in TypeScript
- Outputs:
- CommonJS: dist/index.cjs
- ESM: dist/index.js
- Types: dist/index.d.ts

---

📃 License

MIT © Rashedin Islam

---

🙌 Acknowledgements

This project includes http-status-toolkit`, also created by me.

🤝 Contribution

We welcome contributions! Please check out the Contributing Guide.

Links

- GitHub: dev-rashedin
- Portfolio: rashedin.dev

---

Made with ❤️ by Rashedin Islam