express-unified-response

!express
!typescript

🚀 Express Smart Response & Error Toolkit

A production-ready response, error handling, and pagination toolkit for Express + Mongoose APIs.
It enforces consistent API responses, centralized error handling, and powerful pagination with minimal boilerplate.

✨ FEATURES

$3

- Standard success, created, updated, deleted responses
- Configurable response keys (success, data, meta, message, error)
- Built-in REST semantics (204 No Content, 201 Created, etc.)

$3

- Custom AppError hierarchy
- Automatic conversion of Mongoose errors (Validation, Cast, Duplicate Key).
- Handles JWT, File Upload, and Axios errors automatically.
- Safe defaults for production (no stack leaks)

$3

- Paginate standard Mongoose queries and aggregation pipelines.
- Supports DTO / Transform functions to clean data.
- Enforces maxLimit automatically to protect your database.

$3

Methods are attached directly to the res object: res.success(), res.created(), res.updated(), res.deleted(), res.list(), res.paginateQuery(), res.paginateAggregate().

$3

- Rename response keys
- Customize pagination labels
- Control REST defaults
- Plug in custom logging
- Enable/disable stack traces

📦 Installation

``bash
npm install express-unified-response
`

> Requirements

- Node.js ≥ 20
- Express
- Mongoose

🔧 Basic Setup

`js
import express from "express";
import {
createResponseMiddleware,
createErrorMiddleware,
} from "express-unified-response";

const app = express();

app.use(express.json());

// Attach response helpers
app.use(createResponseMiddleware());

// Your routes go here...

// Central error handler (must be last)
app.use(createErrorMiddleware());

export default app;
`

🟢 USING RESPONSE HELPERS

The library follows two intuitive argument patterns:

Standard: (Data, Message, Options)

Paginated: (Data/Model, Options, Message)

$3

`js
// Simple usage
res.success(user, "User fetched successfully");

// With Transform (DTO) and Silent Logging
res.success(user, "OK", {
transform: (u) => ({ id: u._id, name: u.name }),
silent: true,
});

res.created(newUser, "User created");
`

$3

The toolkit handles REST semantics automatically. If data is provided, it returns 200. If data is null/empty, it returns 204.

`js
// Returns 200 + Body
res.updated(updatedUser, "User updated");

// Returns 204 No Content (No body)
res.updated(null);

// Message-only: Returns 200 + Message (Skips data when 1st arg is null/undefined/_)
res.updated(null, "Password changed successfully");

res.deleted(null, "User deleted");
`

$3

Standardizes array responses. Non-paginated lists still receive a meta block for frontend consistency.

`js
res.list(
users,
{
paginate: true,
page: 1,
limit: 10,
transform: (u) => ({ id: u._id, name: u.name }),
},
"Users fetched successfully"
);
`

$3

`js
await res.paginateQuery(
UserModel,
{
page: 1,
limit: 10,
filter: { isActive: true },
populate: "profile",
transform: (doc) => ({ id: doc._id, email: doc.email }),
},
"Active users fetched"
);

await res.paginateAggregate(
UserModel,
{
pipeline: [{ $match: { score: { $gt: 80 } } }],
transform: (doc) => ({ id: doc._id, score: doc.score }),
},
"High scorers fetched"
);
`

❌ THROWING ERRORS

You can throw custom errors anywhere in your logic; the error middleware will catch and format them.

`js
import { NotFoundError } from "express-unified-response";

app.get("/users/:id", async (req, res) => {
const user = await User.findById(req.params.id);
if (!user) throw new NotFoundError("User not found");
res.success(user);
});
`

$3

$3

You don't always have to throw these manually. The middleware automatically detects and converts:

- Mongoose: ValidationError, CastError, and DuplicateKey (11000) are converted to their respective 400 classes.
- JWT: TokenExpiredError and JsonWebTokenError are mapped to 401.
- Multer: File size limits and unexpected fields are mapped to FileUploadError.

🔐 Utility: Async Handler (No Try/Catch)

The toolkit provides a asyncHandler utility to catch async errors without try-catch blocks.

`js
import { asyncHandler } from "express-unified-response";

app.get(
"/users",
asyncHandler(async (req, res) => {
const users = await User.find();
res.list(users);
})
);
`

⚙️ Full Configuration

`js
const config = {
keys: {
successKey: "success",
dataKey: "data",
metaKey: "meta",
messageKey: "msg",
errorKey: "err",
},
pagination: {
defaults: {
page: 1,
limit: 10,
maxLimit: 50, // safe limit for paginated lists, limit can never exceed this
},
labels: {
nextPage: "next",
prevPage: "prev",
totalDocs: "totalItems",
docs: "items",
totalPages: "totalPages",
limit: "perPage",
page: "currentPage",
hasPrevPage: "hasPrev",
hasNextPage: "hasNext",
},
},
restDefaults: {
deleteReturnsNoContent: true, // true for 204, false for 200
updateReturnsBody: true, // true for 200, false for 204
nonPaginatedMaxItems: 1000, // safe limit for non-paginated lists
},
logger: {
onSuccess: (req, status, duration) =>
console.log(✔ ${req.method} ${status} (${duration}ms)),
onError: (req, err, status) => console.error(✖ ${err.code} [${status}]),
},
routeNotFound: true,
error: {
exposeStack: ${process.env.NODE_ENV} !== "production",
exposeErrorName: false,
defaultErrorMessage: "An unexpected error occurred",
},
};
app.use(createResponseMiddleware(config));
app.use(createErrorMiddleware(config));
`

> Note: Pass the same config to createErrorMiddleware(config). to make them consistent.

📤 Response Examples

Success List (Paginated)

`json
{
"success": true,
"data": [{ "id": "123", "score": 90 }],
"meta": {
"currentPage": 1,
"totalItems": 1,
"totalPages": 1,
"hasNextPage": false
}
}
`

Error

`json
{
"success": false,
"msg": "Validation failed",
"err": {
"code": "VALIDATION_ERROR",
"details": [{ "field": "email", "message": "Required" }]
}
}
``

📜 License

MIT License

📝 Credits

- Sayantan Chakraborty

🌟 Star this project on GitHub


Made with ❤️ by Sayantan Chakraborty