node-responder 1.0.0 → 1.2.1

package/README.md

@@ -3,11 +3,13 @@
 > Modern, standardized API response middleware for Express.js
 
 [![npm version](https://img.shields.io/npm/v/node-responder.svg)](https://www.npmjs.com/package/node-responder)
+[![npm downloads](https://img.shields.io/npm/dm/node-responder.svg)](https://www.npmjs.com/package/node-responder)
 [![license](https://img.shields.io/npm/l/node-responder.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-supported-blue.svg)](types/index.d.ts)
 [![zero dependencies](https://img.shields.io/badge/dependencies-0-green.svg)]()
 
-Stop writing repetitive `res.status(200).json({ success: true, data: ... })` in every route. `node-responder` adds clean, consistent response helpers directly to Express's `res` object.
+Stop writing repetitive `res.status(200).json({ success: true, data: ... })` in every route.
+`node-responder` adds clean, consistent response helpers directly to Express's `res` object.
 
 ---
 
@@ -16,9 +18,10 @@ Stop writing repetitive `res.status(200).json({ success: true, data: ... })` in
 - ✅ **Zero dependencies** — only Express as a peer dependency
 - ✅ **TypeScript support** — full type definitions included
 - ✅ **ESM + CommonJS** — works with both `require` and `import`
+- ✅ **Request Logger** — logs method, URL, status, and response time to terminal
 - ✅ **Pagination built-in** — `res.paginate()` with full meta
+- ✅ **asyncHandler** — write async routes without try-catch boilerplate
 - ✅ **Consistent format** — every response follows the same structure
-- ✅ **Shorthand methods** — `res.ok()`, `res.notFound()`, `res.unauthorized()` and more
 - ✅ **Node.js 14+** supported
 
 ---
@@ -38,15 +41,14 @@ const express = require("express");
 const responder = require("node-responder");
 
 const app = express();
+app.use(express.json());
 
 // Apply middleware globally
 app.use(responder());
 
 app.get("/user/:id", async (req, res) => {
   const user = await User.findById(req.params.id);
-
   if (!user) return res.notFound("User not found");
-
   return res.ok(user);
 });
 
@@ -57,23 +59,23 @@ app.listen(3000);
 
 ## 📋 Response Format
 
-All responses follow this consistent structure:
+Every response follows the same consistent structure:
 
-**Success:**
+### Success Response
 
 ```json
 {
   "success": true,
   "message": "Success",
-  "data": { ... },
+  "data": { "id": 1, "name": "John" },
   "meta": {
-    "timestamp": "2024-01-15T10:30:00.000Z",
+    "timestamp": "2025-01-15T10:30:00.000Z",
     "statusCode": 200
   }
 }
 ```
 
-**Error:**
+### Error Response
 
 ```json
 {
@@ -82,21 +84,21 @@ All responses follow this consistent structure:
   "data": null,
   "errors": null,
   "meta": {
-    "timestamp": "2024-01-15T10:30:00.000Z",
+    "timestamp": "2025-01-15T10:30:00.000Z",
     "statusCode": 404
   }
 }
 ```
 
-**Paginated:**
+### Paginated Response
 
 ```json
 {
   "success": true,
   "message": "Users fetched",
-  "data": [ ... ],
+  "data": [{ "id": 1 }, { "id": 2 }],
   "meta": {
-    "timestamp": "2024-01-15T10:30:00.000Z",
+    "timestamp": "2025-01-15T10:30:00.000Z",
     "statusCode": 200,
     "pagination": {
       "page": 1,
@@ -112,121 +114,468 @@ All responses follow this consistent structure:
 
 ---
 
-## 📖 API Reference
-
-### Middleware Setup
+## ⚙️ Middleware Setup
 
 ```js
 const responder = require("node-responder");
 
-app.use(responder()); // attach to all routes
-// or
-router.use(responder()); // attach to specific router
+// Apply to all routes
+app.use(responder());
+
+// With logger enabled
+app.use(responder({ logger: true }));
+
+// Apply to a specific router only
+router.use(responder());
 ```
 
+### Options
+
+| Option   | Type      | Default | Description                                                               |
+| -------- | --------- | ------- | ------------------------------------------------------------------------- |
+| `logger` | `boolean` | `false` | Logs each request to terminal with method, URL, status, and response time |
+
+---
+
+## 📖 API Reference
+
+### Quick Reference
+
+| Method                                       | Status | When to use                                |
+| -------------------------------------------- | ------ | ------------------------------------------ |
+| `res.ok(data?, message?)`                    | 200    | Successful GET request                     |
+| `res.created(data?, message?)`               | 201    | New resource created                       |
+| `res.noContent()`                            | 204    | Delete or update with no data to return    |
+| `res.success(data?, message?, statusCode?)`  | custom | Custom success status code                 |
+| `res.badRequest(message?, errors?)`          | 400    | Validation failed                          |
+| `res.unauthorized(message?)`                 | 401    | Not logged in or no token                  |
+| `res.forbidden(message?)`                    | 403    | Logged in but no permission                |
+| `res.notFound(message?)`                     | 404    | Resource does not exist                    |
+| `res.conflict(message?)`                     | 409    | Duplicate data (e.g. email already exists) |
+| `res.unprocessable(message?, errors?)`       | 422    | Business logic validation failed           |
+| `res.tooManyRequests(message?, retryAfter?)` | 429    | Rate limit exceeded                        |
+| `res.serverError(message?)`                  | 500    | Unexpected server-side error               |
+| `res.error(message?, statusCode?, errors?)`  | custom | Custom error status code                   |
+| `res.paginate(data, message?, pagination?)`  | 200    | Paginated list response                    |
+
 ---
 
 ### ✅ Success Methods
 
-| Method                                   | Status | Description      |
-| ---------------------------------------- | ------ | ---------------- |
-| `res.success(data, message, statusCode)` | custom | Generic success  |
-| `res.ok(data, message)`                  | 200    | Standard OK      |
-| `res.created(data, message)`             | 201    | Resource created |
-| `res.noContent()`                        | 204    | No content       |
+---
+
+#### `res.ok(data?, message?)`
+
+**Status: 200** — Use for standard successful GET requests.
 
 ```js
-res.ok({ id: 1, name: "Rahim" });
-res.created({ id: 5 }, "User created successfully");
-res.success(data, "Custom message", 200);
+// With data only
+res.ok({ id: 1, name: "John" });
+
+// With data and custom message
+res.ok({ id: 1, name: "John" }, "User fetched successfully");
+
+// Response:
+// { success: true, message: "User fetched successfully", data: { id: 1, name: "John" }, meta: { statusCode: 200, ... } }
+```
+
+---
+
+#### `res.created(data?, message?)`
+
+**Status: 201** — Use when a new resource has been successfully created.
+
+```js
+const user = await User.create({ name: "John", email: "john@example.com" });
+
+res.created(user);
+
+// With custom message
+res.created(user, "Account created successfully");
+
+// Response:
+// { success: true, message: "Created successfully", data: { ...user }, meta: { statusCode: 201, ... } }
+```
+
+---
+
+#### `res.noContent()`
+
+**Status: 204** — Use after a successful delete or update when no data needs to be returned.
+
+```js
+await User.findByIdAndDelete(req.params.id);
+res.noContent();
+
+// Response: empty body (HTTP 204 No Content)
+```
+
+---
+
+#### `res.success(data?, message?, statusCode?)`
+
+**Status: custom** — Use when you need a custom success status code.
+
+```js
+res.success({ accepted: true }, "Request accepted", 202);
+
+// Response:
+// { success: true, message: "Request accepted", data: { accepted: true }, meta: { statusCode: 202, ... } }
 ```
 
 ---
 
 ### ❌ Error Methods
 
-| Method                                   | Status | Description          |
-| ---------------------------------------- | ------ | -------------------- |
-| `res.error(message, statusCode, errors)` | custom | Generic error        |
-| `res.badRequest(message, errors)`        | 400    | Validation failed    |
-| `res.unauthorized(message)`              | 401    | Not authenticated    |
-| `res.forbidden(message)`                 | 403    | Not authorized       |
-| `res.notFound(message)`                  | 404    | Resource not found   |
-| `res.conflict(message)`                  | 409    | Conflict             |
-| `res.unprocessable(message, errors)`     | 422    | Unprocessable entity |
-| `res.serverError(message)`               | 500    | Server error         |
+---
+
+#### `res.badRequest(message?, errors?)`
+
+**Status: 400** — Use when the request is malformed or validation fails.
+
+```js
+// Simple message
+res.badRequest("Name is required");
+
+// With validation errors object
+res.badRequest("Validation failed", {
+  name: "Name is required",
+  email: "Invalid email format",
+});
+
+// Response:
+// { success: false, message: "Validation failed", data: null, errors: { name: "...", email: "..." }, meta: { statusCode: 400, ... } }
+```
+
+---
+
+#### `res.unauthorized(message?)`
+
+**Status: 401** — Use when the user is not authenticated (no token or invalid token).
+
+```js
+// Default message
+res.unauthorized();
+
+// Custom message
+res.unauthorized("Please login to continue");
+
+// Response:
+// { success: false, message: "Unauthorized", data: null, errors: null, meta: { statusCode: 401, ... } }
+```
+
+---
+
+#### `res.forbidden(message?)`
+
+**Status: 403** — Use when the user is authenticated but does not have permission.
 
 ```js
-res.notFound("Product not found");
-res.unauthorized("Please login first");
-res.badRequest("Validation failed", { email: "Email is required" });
+// Default message
+res.forbidden();
+
+// Custom message
+res.forbidden("You do not have permission to access this resource");
+
+// Response:
+// { success: false, message: "Forbidden", data: null, errors: null, meta: { statusCode: 403, ... } }
+```
+
+---
+
+#### `res.notFound(message?)`
+
+**Status: 404** — Use when a requested resource does not exist.
+
+```js
+const user = await User.findById(req.params.id);
+
+if (!user) {
+  return res.notFound("User not found");
+}
+
+// Response:
+// { success: false, message: "User not found", data: null, errors: null, meta: { statusCode: 404, ... } }
 ```
 
 ---
 
-### 📄 Pagination
+#### `res.conflict(message?)`
+
+**Status: 409** — Use when the request conflicts with existing data (e.g. duplicate email).
 
 ```js
-const users = await User.find().skip(skip).limit(limit);
-const total = await User.countDocuments();
+const exists = await User.findOne({ email: req.body.email });
+
+if (exists) {
+  return res.conflict("Email already registered");
+}
+
+// Response:
+// { success: false, message: "Email already registered", data: null, errors: null, meta: { statusCode: 409, ... } }
+```
+
+---
+
+#### `res.unprocessable(message?, errors?)`
+
+**Status: 422** — Use when the data format is correct but business logic validation fails.
 
-res.paginate(users, "Users fetched", {
-  page: 1,
-  limit: 10,
-  total: total,
+```js
+res.unprocessable("Cannot process this request", {
+  age: "Must be at least 18 years old",
+});
+
+// Response:
+// { success: false, message: "Cannot process this request", data: null, errors: { age: "..." }, meta: { statusCode: 422, ... } }
+```
+
+---
+
+#### `res.tooManyRequests(message?, retryAfter?)`
+
+**Status: 429** — Use when a client exceeds the rate limit.
+
+```js
+// Basic usage
+res.tooManyRequests("Too many requests, please slow down");
+
+// With retryAfter in seconds — sets the Retry-After header automatically
+res.tooManyRequests("Rate limit exceeded", 60);
+
+// Response:
+// Header: Retry-After: 60
+// { success: false, message: "Rate limit exceeded", data: null, errors: null, meta: { statusCode: 429, ... } }
+```
+
+---
+
+#### `res.serverError(message?)`
+
+**Status: 500** — Use when an unexpected server-side error occurs.
+
+```js
+try {
+  await someRiskyOperation();
+} catch (err) {
+  console.error(err);
+  return res.serverError("Something went wrong, please try again later");
+}
+
+// Response:
+// { success: false, message: "Something went wrong, please try again later", data: null, errors: null, meta: { statusCode: 500, ... } }
+```
+
+---
+
+#### `res.error(message?, statusCode?, errors?)`
+
+**Status: custom** — Use when you need a custom error status code.
+
+```js
+res.error("Gone", 410);
+res.error("Validation failed", 400, { field: "required" });
+```
+
+---
+
+### 📄 Pagination — `res.paginate(data, message?, pagination?)`
+
+Use for returning paginated lists with full pagination metadata.
+
+```js
+router.get("/users", async (req, res) => {
+  const page = parseInt(req.query.page) || 1;
+  const limit = parseInt(req.query.limit) || 10;
+  const skip = (page - 1) * limit;
+
+  const [users, total] = await Promise.all([
+    User.find().skip(skip).limit(limit),
+    User.countDocuments(),
+  ]);
+
+  return res.paginate(users, "Users fetched", { page, limit, total });
+});
+
+// Response:
+// {
+//   success: true,
+//   message: "Users fetched",
+//   data: [...users],
+//   meta: {
+//     timestamp: "...",
+//     statusCode: 200,
+//     pagination: {
+//       page: 1, limit: 10, total: 100,
+//       totalPages: 10,
+//       hasNextPage: true,
+//       hasPrevPage: false
+//     }
+//   }
+// }
+```
+
+| Pagination Field | Type     | Description               |
+| ---------------- | -------- | ------------------------- |
+| `page`           | `number` | Current page number       |
+| `limit`          | `number` | Number of items per page  |
+| `total`          | `number` | Total number of documents |
+
+---
+
+### ⚡ asyncHandler
+
+Eliminates try-catch boilerplate from every async route.
+Errors are automatically forwarded to Express's `next(err)`.
+
+```js
+const { asyncHandler } = require("node-responder");
+
+// ❌ Before — repetitive try-catch in every route:
+router.get("/users", async (req, res) => {
+  try {
+    const users = await User.find();
+    res.ok(users);
+  } catch (err) {
+    res.serverError(err.message);
+  }
+});
+
+// ✅ After — clean and concise with asyncHandler:
+router.get(
+  "/users",
+  asyncHandler(async (req, res) => {
+    const users = await User.find(); // errors automatically go to next(err)
+    res.ok(users);
+  }),
+);
+
+// Catch all errors in one global error handler:
+app.use((err, req, res, next) => {
+  console.error(err);
+  res.serverError(err.message);
 });
 ```
 
 ---
 
-## 🔧 Real-World Example (MERN)
+### 📝 Logger — `{ logger: true }`
+
+Logs every incoming request to the terminal with method, URL, status code, and response time.
+
+```js
+app.use(responder({ logger: true }));
+```
+
+Terminal output:
+
+```
+GET     /api/users                          200  23ms  ✔
+POST    /api/users                          201  45ms  ✔
+GET     /api/users/abc123                   404  12ms  ✖
+POST    /api/auth/login                     401  8ms   ✖
+DELETE  /api/products/999                   500  5ms   ✖
+```
+
+**Tip:** Enable logger in development, disable in production:
+
+```js
+app.use(
+  responder({
+    logger: process.env.NODE_ENV !== "production",
+  }),
+);
+```
+
+---
+
+## 🔧 Real-World MERN Example
 
 ```js
 const express = require("express");
 const responder = require("node-responder");
-const router = express.Router();
+const { asyncHandler } = require("node-responder");
 
-router.use(responder());
+const router = express.Router();
+router.use(responder({ logger: true }));
 
-// GET all users with pagination
-router.get("/", async (req, res) => {
-  try {
+// GET /api/users?page=1&limit=10
+router.get(
+  "/",
+  asyncHandler(async (req, res) => {
     const page = parseInt(req.query.page) || 1;
     const limit = parseInt(req.query.limit) || 10;
     const skip = (page - 1) * limit;
 
     const [users, total] = await Promise.all([
-      User.find().skip(skip).limit(limit),
+      User.find().skip(skip).limit(limit).select("-password"),
       User.countDocuments(),
     ]);
 
     return res.paginate(users, "Users fetched", { page, limit, total });
-  } catch (err) {
-    return res.serverError("Failed to fetch users");
-  }
-});
-
-// POST create user
-router.post("/", async (req, res) => {
-  try {
-    const { name, email } = req.body;
-
-    if (!name || !email) {
-      return res.badRequest("Validation failed", {
-        name: !name ? "Name is required" : null,
-        email: !email ? "Email is required" : null,
-      });
+  }),
+);
+
+// GET /api/users/:id
+router.get(
+  "/:id",
+  asyncHandler(async (req, res) => {
+    const user = await User.findById(req.params.id).select("-password");
+    if (!user) return res.notFound("User not found");
+    return res.ok(user, "User fetched");
+  }),
+);
+
+// POST /api/users
+router.post(
+  "/",
+  asyncHandler(async (req, res) => {
+    const { name, email, password } = req.body;
+
+    const errors = {};
+    if (!name) errors.name = "Name is required";
+    if (!email) errors.email = "Email is required";
+    if (!password) errors.password = "Password is required";
+
+    if (Object.keys(errors).length > 0) {
+      return res.badRequest("Validation failed", errors);
     }
 
     const exists = await User.findOne({ email });
     if (exists) return res.conflict("Email already registered");
 
-    const user = await User.create({ name, email });
-    return res.created(user, "User registered successfully");
-  } catch (err) {
-    return res.serverError();
-  }
-});
+    const user = await User.create({ name, email, password });
+
+    return res.created(
+      { id: user._id, name: user.name, email: user.email },
+      "Account created successfully",
+    );
+  }),
+);
+
+// PUT /api/users/:id
+router.put(
+  "/:id",
+  asyncHandler(async (req, res) => {
+    const user = await User.findByIdAndUpdate(req.params.id, req.body, {
+      new: true,
+    });
+    if (!user) return res.notFound("User not found");
+    return res.ok(user, "User updated successfully");
+  }),
+);
+
+// DELETE /api/users/:id
+router.delete(
+  "/:id",
+  asyncHandler(async (req, res) => {
+    const user = await User.findByIdAndDelete(req.params.id);
+    if (!user) return res.notFound("User not found");
+    return res.noContent();
+  }),
+);
+
+module.exports = router;
 ```
 
 ---
@@ -235,19 +584,46 @@ router.post("/", async (req, res) => {
 
 ```ts
 import express from "express";
-import responder from "node-responder";
+import responder, { asyncHandler } from "node-responder";
 
 const app = express();
-app.use(responder());
+app.use(express.json());
+app.use(responder({ logger: true }));
+
+app.get(
+  "/users",
+  asyncHandler(async (req, res) => {
+    const users = await User.find();
+    res.ok(users, "Users fetched");
+  }),
+);
+
+// Global error handler
+app.use(
+  (
+    err: Error,
+    req: express.Request,
+    res: express.Response,
+    next: express.NextFunction,
+  ) => {
+    console.error(err);
+    res.serverError(err.message);
+  },
+);
 
-app.get("/users", async (req, res) => {
-  const users = await User.find();
-  res.ok(users, "Users fetched");
-});
+app.listen(3000);
 ```
 
 ---
 
+## 🔗 Links
+
+- [npm](https://www.npmjs.com/package/node-responder)
+- [GitHub](https://github.com/hammadsadi/node-responder)
+- [Report an Issue](https://github.com/hammadsadi/node-responder/issues)
+
+---
+
 ## 📄 License
 
 MIT © [Hammad Sadi](https://github.com/hammadsadi)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-responder",
-  "version": "1.0.0",
+  "version": "1.2.1",
   "description": "Modern, standardized API response middleware for Express.js — with TypeScript support, pagination, and shorthand methods.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -56,4 +56,4 @@
   "engines": {
     "node": ">=14.0.0"
   }
-}
+}

package/src/index.js

@@ -3,140 +3,282 @@
 /**
  * node-responder
  * Standardized, modern API response middleware for Express.js
- * @author Hammad Sadi
+ * @version 1.1.0
  * @license MIT
  */
 
-/**
- * Creates a success response
- */
-function successResponse(
-  res,
-  data = null,
-  message = "Success",
-  statusCode = 200,
-) {
-  return res.status(statusCode).json({
+//  ANSI Colors
+
+const COLORS = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  cyan: "\x1b[36m",
+};
+
+const isTTY = () => process.stdout && process.stdout.isTTY === true;
+
+const colorize = (str, color) =>
+  isTTY() ? `${color}${str}${COLORS.reset}` : str;
+
+const colorStatus = (code) => {
+  if (code >= 500) return colorize(code, COLORS.red);
+  if (code >= 400) return colorize(code, COLORS.yellow);
+  if (code >= 300) return colorize(code, COLORS.cyan);
+  return colorize(code, COLORS.green);
+};
+
+const colorMethod = (method) => {
+  const m = (method || "UNKNOWN").toUpperCase().padEnd(7);
+  return colorize(m, COLORS.cyan);
+};
+
+const logRequest = (req, statusCode, startTime) => {
+  try {
+    const ms = Date.now() - startTime;
+    const method = colorMethod(req.method);
+    const url = (req.originalUrl || req.url || "/").padEnd(35);
+    const status = colorStatus(statusCode);
+    const time = colorize(`${ms}ms`, COLORS.dim);
+    const icon =
+      statusCode >= 400
+        ? colorize("✖", COLORS.red)
+        : colorize("✔", COLORS.green);
+    process.stdout.write(`  ${method} ${url} ${status}  ${time}  ${icon}\n`);
+  } catch (_) {}
+};
+
+//  Validation helpers
+
+const safeMessage = (val, fallback) => {
+  if (val === undefined || val === null) return fallback;
+  return String(val);
+};
+
+const safeStatus = (val, fallback) => {
+  const n = Number(val);
+  return Number.isFinite(n) && n >= 100 && n <= 599 ? n : fallback;
+};
+
+//  Core response builders
+
+const successResponse = (res, data, message, statusCode) => {
+  const code = safeStatus(statusCode, 200);
+  const msg = safeMessage(message, "Success");
+  const body = data === undefined ? null : data;
+
+  return res.status(code).json({
     success: true,
-    message,
-    data,
+    message: msg,
+    data: body,
     meta: {
       timestamp: new Date().toISOString(),
-      statusCode,
+      statusCode: code,
     },
   });
-}
+};
 
-/**
- * Creates an error response
- */
-function errorResponse(
-  res,
-  message = "Something went wrong",
-  statusCode = 500,
-  errors = null,
-) {
-  return res.status(statusCode).json({
+const errorResponse = (res, message, statusCode, errors) => {
+  const code = safeStatus(statusCode, 500);
+  const msg = safeMessage(message, "Something went wrong");
+  const errs = errors === undefined || errors === null ? null : errors;
+
+  return res.status(code).json({
     success: false,
-    message,
+    message: msg,
     data: null,
-    errors,
+    errors: errs,
     meta: {
       timestamp: new Date().toISOString(),
-      statusCode,
+      statusCode: code,
     },
   });
-}
+};
 
-/**
- * Creates a paginated response
- */
-function paginatedResponse(
-  res,
-  data = [],
-  message = "Success",
-  pagination = {},
-) {
-  const { page = 1, limit = 10, total = 0 } = pagination;
+const paginatedResponse = (res, data, message, pagination) => {
+  const arr = Array.isArray(data) ? data : [];
+  const msg = safeMessage(message, "Success");
+  const p = pagination && typeof pagination === "object" ? pagination : {};
 
-  const totalPages = Math.ceil(total / limit);
+  const page = Math.max(1, parseInt(p.page, 10) || 1);
+  const limit = Math.max(1, parseInt(p.limit, 10) || 10);
+  const total = Math.max(0, parseInt(p.total, 10) || 0);
+  const totalPages = limit > 0 ? Math.ceil(total / limit) : 0;
 
   return res.status(200).json({
     success: true,
-    message,
-    data,
+    message: msg,
+    data: arr,
     meta: {
       timestamp: new Date().toISOString(),
       statusCode: 200,
       pagination: {
-        page: Number(page),
-        limit: Number(limit),
-        total: Number(total),
+        page,
+        limit,
+        total,
         totalPages,
         hasNextPage: page < totalPages,
         hasPrevPage: page > 1,
       },
     },
   });
-}
+};
 
-/**
- * Express middleware — attaches helper methods to res object
- */
-function apiResponse() {
-  return function (req, res, next) {
-    // res.success(data, message, statusCode)
-    res.success = function (
-      data = null,
-      message = "Success",
-      statusCode = 200,
-    ) {
-      return successResponse(res, data, message, statusCode);
+//  asyncHandler
+
+const asyncHandler = (fn) => {
+  if (typeof fn !== "function") {
+    throw new TypeError(
+      `[node-responder] asyncHandler expects a function, got "${typeof fn}"`,
+    );
+  }
+  return (req, res, next) => {
+    try {
+      const result = fn(req, res, next);
+      if (result && typeof result.catch === "function") {
+        result.catch(next);
+      }
+    } catch (err) {
+      next(err);
+    }
+  };
+};
+
+//  Middleware factory
+
+const responder = (options) => {
+  const opts = options && typeof options === "object" ? options : {};
+  const logger = opts.logger === true;
+
+  if (process.env.NODE_ENV !== "production") {
+    const known = ["logger"];
+    for (const key of Object.keys(opts)) {
+      if (!known.includes(key)) {
+        process.stderr.write(
+          `[node-responder] Unknown option "${key}" — valid options: ${known.join(", ")}\n`,
+        );
+      }
+    }
+  }
+
+  return (req, res, next) => {
+    const startTime = Date.now();
+
+    const log = (code) => {
+      if (logger) logRequest(req, code, startTime);
+    };
+
+    //  2xx Success
+
+    res.success = (data, message, statusCode) => {
+      const code = safeStatus(statusCode, 200);
+      log(code);
+      return successResponse(res, data, message, code);
     };
 
-    // res.error(message, statusCode, errors)
-    res.error = function (
-      message = "Something went wrong",
-      statusCode = 500,
-      errors = null,
-    ) {
-      return errorResponse(res, message, statusCode, errors);
+    res.ok = (data, message) => {
+      log(200);
+      return successResponse(res, data, safeMessage(message, "Success"), 200);
     };
 
-    // res.paginate(data, message, pagination)
-    res.paginate = function (data = [], message = "Success", pagination = {}) {
-      return paginatedResponse(res, data, message, pagination);
+    res.created = (data, message) => {
+      log(201);
+      return successResponse(
+        res,
+        data,
+        safeMessage(message, "Created successfully"),
+        201,
+      );
+    };
+
+    res.noContent = () => {
+      log(204);
+      return res.status(204).send();
+    };
+
+    //  4xx / 5xx Error
+
+    res.error = (message, statusCode, errors) => {
+      const code = safeStatus(statusCode, 500);
+      log(code);
+      return errorResponse(res, message, code, errors);
     };
 
-    // Shorthand methods
-    res.ok = (data, message = "Success") =>
-      successResponse(res, data, message, 200);
-    res.created = (data, message = "Created successfully") =>
-      successResponse(res, data, message, 201);
-    res.noContent = () => res.status(204).send();
-
-    res.badRequest = (message = "Bad request", errors = null) =>
-      errorResponse(res, message, 400, errors);
-    res.unauthorized = (message = "Unauthorized") =>
-      errorResponse(res, message, 401);
-    res.forbidden = (message = "Forbidden") => errorResponse(res, message, 403);
-    res.notFound = (message = "Not found") => errorResponse(res, message, 404);
-    res.conflict = (message = "Conflict") => errorResponse(res, message, 409);
-    res.unprocessable = (message = "Unprocessable entity", errors = null) =>
-      errorResponse(res, message, 422, errors);
-    res.serverError = (message = "Internal server error") =>
-      errorResponse(res, message, 500);
+    res.badRequest = (message, errors) => {
+      log(400);
+      return errorResponse(
+        res,
+        safeMessage(message, "Bad request"),
+        400,
+        errors ?? null,
+      );
+    };
+
+    res.unauthorized = (message) => {
+      log(401);
+      return errorResponse(res, safeMessage(message, "Unauthorized"), 401);
+    };
+
+    res.forbidden = (message) => {
+      log(403);
+      return errorResponse(res, safeMessage(message, "Forbidden"), 403);
+    };
+
+    res.notFound = (message) => {
+      log(404);
+      return errorResponse(res, safeMessage(message, "Not found"), 404);
+    };
+
+    res.conflict = (message) => {
+      log(409);
+      return errorResponse(res, safeMessage(message, "Conflict"), 409);
+    };
+
+    res.unprocessable = (message, errors) => {
+      log(422);
+      return errorResponse(
+        res,
+        safeMessage(message, "Unprocessable entity"),
+        422,
+        errors ?? null,
+      );
+    };
+
+    res.tooManyRequests = (message, retryAfter) => {
+      if (retryAfter != null) res.set("Retry-After", String(retryAfter));
+      log(429);
+      return errorResponse(res, safeMessage(message, "Too many requests"), 429);
+    };
+
+    res.serverError = (message) => {
+      log(500);
+      return errorResponse(
+        res,
+        safeMessage(message, "Internal server error"),
+        500,
+      );
+    };
+
+    //  Pagination
+
+    res.paginate = (data, message, pagination) => {
+      log(200);
+      return paginatedResponse(res, data, message, pagination);
+    };
 
     next();
   };
-}
+};
+
+//  Exports
 
-// Named exports
-module.exports = apiResponse;
-module.exports.apiResponse = apiResponse;
+module.exports = responder;
+module.exports.default = responder;
+module.exports.responder = responder;
+module.exports.asyncHandler = asyncHandler;
 module.exports.successResponse = successResponse;
 module.exports.errorResponse = errorResponse;
 module.exports.paginatedResponse = paginatedResponse;
-
-// ESM default export support
-module.exports.default = apiResponse;

package/types/index.d.ts

@@ -1,9 +1,21 @@
-import { Request, Response, NextFunction, RequestHandler } from "express";
+import { RequestHandler, Request, Response, NextFunction } from "express";
 
-export interface Pagination {
-  page?: number;
-  limit?: number;
-  total?: number;
+//  Options
+
+export interface ResponderOptions {
+  /**
+   * When true, logs every request to stdout with method, URL, status, and response time.
+   * @default false
+   */
+  logger?: boolean;
+}
+
+//  Pagination
+
+export interface PaginationInput {
+  page?: number | string;
+  limit?: number | string;
+  total?: number | string;
 }
 
 export interface PaginationMeta {
@@ -15,13 +27,15 @@ export interface PaginationMeta {
   hasPrevPage: boolean;
 }
 
+//  Response shapes
+
 export interface ApiMeta {
   timestamp: string;
   statusCode: number;
   pagination?: PaginationMeta;
 }
 
-export interface ApiSuccessResponse<T = any> {
+export interface ApiSuccessResponse<T = unknown> {
   success: true;
   message: string;
   data: T;
@@ -32,40 +46,42 @@ export interface ApiErrorResponse {
   success: false;
   message: string;
   data: null;
-  errors: any | null;
+  errors: unknown | null;
   meta: ApiMeta;
 }
 
+//  Express augmentation
+
 declare global {
   namespace Express {
     interface Response {
-      /** Send a success response */
-      success<T = any>(
+      // Generic
+      /** Send a success response with optional data, message, and status code */
+      success<T = unknown>(
         data?: T,
         message?: string,
         statusCode?: number,
       ): Response;
-
-      /** Send an error response */
-      error(message?: string, statusCode?: number, errors?: any): Response;
-
-      /** Send a paginated response */
-      paginate<T = any>(
+      /** Send an error response with optional message, status code, and errors */
+      error(message?: string, statusCode?: number, errors?: unknown): Response;
+      /** Send a paginated success response */
+      paginate<T = unknown>(
         data?: T[],
         message?: string,
-        pagination?: Pagination,
+        pagination?: PaginationInput,
       ): Response;
 
-      // Shorthand methods
+      // 2xx
       /** 200 OK */
-      ok<T = any>(data?: T, message?: string): Response;
+      ok<T = unknown>(data?: T, message?: string): Response;
       /** 201 Created */
-      created<T = any>(data?: T, message?: string): Response;
+      created<T = unknown>(data?: T, message?: string): Response;
       /** 204 No Content */
       noContent(): Response;
 
+      // 4xx
       /** 400 Bad Request */
-      badRequest(message?: string, errors?: any): Response;
+      badRequest(message?: string, errors?: unknown): Response;
       /** 401 Unauthorized */
       unauthorized(message?: string): Response;
       /** 403 Forbidden */
@@ -75,18 +91,34 @@ declare global {
       /** 409 Conflict */
       conflict(message?: string): Response;
       /** 422 Unprocessable Entity */
-      unprocessable(message?: string, errors?: any): Response;
+      unprocessable(message?: string, errors?: unknown): Response;
+      /** 429 Too Many Requests — optionally sets Retry-After header */
+      tooManyRequests(message?: string, retryAfter?: number | string): Response;
+
+      // 5xx
       /** 500 Internal Server Error */
       serverError(message?: string): Response;
     }
   }
 }
 
-export declare function apiResponse(): RequestHandler;
+//  Exported functions
+
+/** Express middleware — attaches all response helpers to res */
+export declare function responder(options?: ResponderOptions): RequestHandler;
+
+/** Wraps an async route handler and forwards errors to next() automatically */
+export declare function asyncHandler(
+  fn: (
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ) => Promise<unknown> | unknown,
+): RequestHandler;
 
 export declare function successResponse(
   res: Response,
-  data?: any,
+  data?: unknown,
   message?: string,
   statusCode?: number,
 ): Response;
@@ -95,14 +127,14 @@ export declare function errorResponse(
   res: Response,
   message?: string,
   statusCode?: number,
-  errors?: any,
+  errors?: unknown,
 ): Response;
 
 export declare function paginatedResponse(
   res: Response,
-  data?: any[],
+  data?: unknown[],
   message?: string,
-  pagination?: Pagination,
+  pagination?: PaginationInput,
 ): Response;
 
-export default apiResponse;
+export default responder;