express-error-builder

⚠️ Note: This project may be deprecated in the future if it no longer receives updates or maintenance.

express-error-builder is a lightweight and extensible utility for building standardized, structured, and informative error responses in express REST APIs.

It helps developers enforce consistency across express API error outputs with optional logging, metadata, and internationalization support.

Ideal for use in Express framework, it simplifies debugging, improves client-side error handling, and integrates seamlessly with production-ready APIs.

⬇️ Installation

Install express-error-builder with npm

md my-express-app
cd my-express-app
npm install express-error-builder

💿 Usage/Examples

import { produceErrorResponse } from 'express-error-builder';
import express from 'express';

const app = express();
app.get('/api/error', (req, res) => {
  //...
  produceErrorResponse(res, {
    statusCode: 400,
    error: 'validation_error',
    code: 'VALIDATION_ERROR',
    message: 'Validation failed!',
  });
});

🧰 Functions/Methods

Usage and paramter list of all avilable functions

errorJsonBuilder()

Builds a standardized error response object for APIs.

import { errorJsonBuilder } from 'express-error-builder';
import express from 'express';

const app = express();
app.get('/api/error', (req, res) => {
  //...
  errorJsonBuilder({
    statusCode: 400,
    error: 'validation_error',
    code: 'VALIDATION_ERROR',
    message: 'Validation failed!',
  });

  /*Output {
  statusCode: 400,
  error: 'validation_error',
  code: 'VALIDATION_ERROR',
  message: 'Validation failed!',
  } */
});

| Parameter | Type | Required | Description | | :--------------- | :------------------------ | :------- | :------------------------------------------------------ | | statusCode | number | true | HTTP status code (e.g., 400, 500). | | code | string | true | Internal error code identifier. | | message | string | true | Developer-readable error message. | | error | string | true | Summary of the error (e.g., "Bad Request"). | | hint | string | false | Optional hint or resolution guide for developers. | | stack | string | false | Optional stack trace (useful in dev environments). | | type | string | false | Optional URI reference for error type (RFC 7807 style). | | instance | string | false | Optional unique error instance identifier. | | docsLink | string | false | Optional link to API or error documentation. | | suggestions | string | false | Optional suggestions to fix the error. | | retryable | boolean | false | Whether the operation can be retried. | | timestamp | Date | string | false | Timestamp of the error (default: now). | | path | string | false | Request path where the error occurred. | | requestId | string | false | Request identifier for tracing. | | clientMessage | string | false | User-friendly message for clients. | | localizedMessage | Object.<string, string> | false | Translated messages keyed by locale (e.g., { en, fr }). | | metaData | Object.<string, string> | false | Optional metadata to provide additional context. | | additional | * | false | Any additional custom data. |

produceErrorResponse()

Produces a standardized error response for Express APIs and logs the error conditionally.

import { produceErrorResponse } from 'express-error-builder';
import express from 'express';

const app = express();
app.get('/api/error', (req, res) => {
  //...
  produceErrorResponse(res, {
    statusCode: 400,
    error: 'validation_error',
    code: 'VALIDATION_ERROR',
    message: 'Validation failed!',
  });

  /*Output response for GET /api/error {
  statusCode: 400,
  error: 'validation_error',
  code: 'VALIDATION_ERROR',
  message: 'Validation failed!',
  } */
});

| Parameter | Type | Required | Description | | :----------------- | :-------------------------------- | :------- | :------------------------------------------------------- | | response | Response | true | Express response object used to send the error response. | | statusCode | number | true | HTTP status code (e.g., 400, 500). | | code | string | true | Internal error code. | | message | string | true | Developer-readable error message. | | error | string | true | Short error title (e.g., "Bad Request"). | | hint | string | false | Developer hint for fixing the error. | | stack | string | false | Stack trace (useful for debugging). | | type | string | false | URI reference that identifies the error type. | | instance | string | false | Unique error instance identifier. | | docsLink | string | false | Link to documentation related to the error. | | suggestions | string | false | Suggestions for resolving the issue. | | retryable | boolean | false | Indicates whether the request can be retried. | | timestamp | Date | string | false | When the error occurred. Defaults to now. | | path | string | false | The request path that triggered the error. | | requestId | string | false | Unique identifier for the request. | | clientMessage | string | false | User-friendly message intended for the client. | | localizedMessage | Object.<string, string> | false | Translations for different locales. | | metaData | Object.<string, string> | false | Any metadata to include in the response. | | additional | * | false | Additional custom data. | | logMessage | boolean | false | Whether to log the error to the console. | | logLevel | "info" | "warn" | "error" | false | Level of the log (controls color). |

🤝 Contribution

Contributions are welcome and appreciated! If you have suggestions for improvements, feel free to open an issue or submit a pull request. Let’s make bee-jokes better together! 🐝✨

🚀 Run Locally

Clone the project

git clone https://github.com/sandeep-shome/bee-jokes.git

Go to the project directory

cd express-error-builder

🔧 Install dependencies

npm install

You can now explore and modify the package as per your needs.

📦 Build the Project

npm run build

🧪 Running Tests

To run tests, run the following command

npm run test

🧩 Features

• No setup
• Open source
• Accepting contributions

🧱 Tech Stack

Node, Typescript, Tsup, Eslint, Husky, Prettier

📎Appendix

express-error-builder is an open-source project developed and maintained by a solo developer with a passion for clean code, creativity, and community-driven tools.

You're welcome to explore, use, and contribute to the project! Whether it's fixing a bug, suggesting a feature, or improving the documentation — your contributions are highly appreciated.

Feel free to check out the GitHub repository and join in making this project better for everyone. Let's build something fun together! 💡

👨‍💻 Authors

@Sandeep Shome

📄 License

MIT

🙋‍♂️ Support

For support, email [email protected]