express-error-builder
Version:
Minimal and no setup error builder and producer for express APIs
215 lines (160 loc) • 9.28 kB
Markdown
[](https://choosealicense.com/licenses/mit/)
# 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
```bash
md my-express-app
cd my-express-app
npm install express-error-builder
```
## 💿 Usage/Examples
```javascript
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.
```javascript
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.
```javascript
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
```bash
git clone https://github.com/sandeep-shome/bee-jokes.git
```
Go to the project directory
```bash
cd express-error-builder
```
🔧 Install dependencies
```bash
npm install
```
_You can now explore and modify the package as per your needs._
📦 Build the Project
```bash
npm run build
```
## 🧪 Running Tests
To run tests, run the following command
```bash
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](https://github.com/sandeep-shome)
## 📄 License
[MIT](https://choosealicense.com/licenses/mit/)
## 🙋♂️ Support
For support, email sandeepshome.dev@gmail.com