node-responder 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+Copyright (c) 2026 hammadsadi
+
+Permission is hereby granted, free of
+charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# node-responder
+
+> 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)
+[![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.
+
+---
+
+## ✨ Features
+
+- ✅ **Zero dependencies** — only Express as a peer dependency
+- ✅ **TypeScript support** — full type definitions included
+- ✅ **ESM + CommonJS** — works with both `require` and `import`
+- ✅ **Pagination built-in** — `res.paginate()` with full meta
+- ✅ **Consistent format** — every response follows the same structure
+- ✅ **Shorthand methods** — `res.ok()`, `res.notFound()`, `res.unauthorized()` and more
+- ✅ **Node.js 14+** supported
+
+---
+
+## 📦 Installation
+
+```bash
+npm install node-responder
+```
+
+---
+
+## 🚀 Quick Start
+
+```js
+const express = require("express");
+const responder = require("node-responder");
+
+const app = express();
+
+// 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);
+});
+
+app.listen(3000);
+```
+
+---
+
+## 📋 Response Format
+
+All responses follow this consistent structure:
+
+**Success:**
+
+```json
+{
+  "success": true,
+  "message": "Success",
+  "data": { ... },
+  "meta": {
+    "timestamp": "2024-01-15T10:30:00.000Z",
+    "statusCode": 200
+  }
+}
+```
+
+**Error:**
+
+```json
+{
+  "success": false,
+  "message": "User not found",
+  "data": null,
+  "errors": null,
+  "meta": {
+    "timestamp": "2024-01-15T10:30:00.000Z",
+    "statusCode": 404
+  }
+}
+```
+
+**Paginated:**
+
+```json
+{
+  "success": true,
+  "message": "Users fetched",
+  "data": [ ... ],
+  "meta": {
+    "timestamp": "2024-01-15T10:30:00.000Z",
+    "statusCode": 200,
+    "pagination": {
+      "page": 1,
+      "limit": 10,
+      "total": 100,
+      "totalPages": 10,
+      "hasNextPage": true,
+      "hasPrevPage": false
+    }
+  }
+}
+```
+
+---
+
+## 📖 API Reference
+
+### Middleware Setup
+
+```js
+const responder = require("node-responder");
+
+app.use(responder()); // attach to all routes
+// or
+router.use(responder()); // attach to specific router
+```
+
+---
+
+### ✅ 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       |
+
+```js
+res.ok({ id: 1, name: "Rahim" });
+res.created({ id: 5 }, "User created successfully");
+res.success(data, "Custom message", 200);
+```
+
+---
+
+### ❌ 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         |
+
+```js
+res.notFound("Product not found");
+res.unauthorized("Please login first");
+res.badRequest("Validation failed", { email: "Email is required" });
+```
+
+---
+
+### 📄 Pagination
+
+```js
+const users = await User.find().skip(skip).limit(limit);
+const total = await User.countDocuments();
+
+res.paginate(users, "Users fetched", {
+  page: 1,
+  limit: 10,
+  total: total,
+});
+```
+
+---
+
+## 🔧 Real-World Example (MERN)
+
+```js
+const express = require("express");
+const responder = require("node-responder");
+const router = express.Router();
+
+router.use(responder());
+
+// GET all users with pagination
+router.get("/", async (req, res) => {
+  try {
+    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 });
+  } 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,
+      });
+    }
+
+    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();
+  }
+});
+```
+
+---
+
+## TypeScript Usage
+
+```ts
+import express from "express";
+import responder from "node-responder";
+
+const app = express();
+app.use(responder());
+
+app.get("/users", async (req, res) => {
+  const users = await User.find();
+  res.ok(users, "Users fetched");
+});
+```
+
+---
+
+## 📄 License
+
+MIT © [Hammad Sadi](https://github.com/hammadsadi)

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "node-responder",
+  "version": "1.0.0",
+  "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",
+  "exports": {
+    ".": {
+      "require": "./src/index.js",
+      "import": "./src/index.js",
+      "types": "./types/index.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "keywords": [
+    "express",
+    "api",
+    "response",
+    "middleware",
+    "rest",
+    "json",
+    "typescript",
+    "mern",
+    "nodejs",
+    "http",
+    "pagination",
+    "standardized",
+    "node-responder",
+    "responder"
+  ],
+  "author": "Hammad Sadi <hammad.sadi@yahoo.com>",
+  "license": "MIT",
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "express": "^4.18.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hammadsadi/node-responder"
+  },
+  "homepage": "https://github.com/hammadsadi/node-responder#readme",
+  "bugs": {
+    "url": "https://github.com/hammadsadi/node-responder/issues"
+  },
+  "files": [
+    "src/",
+    "types/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,142 @@
+"use strict";
+
+/**
+ * node-responder
+ * Standardized, modern API response middleware for Express.js
+ * @author Hammad Sadi
+ * @license MIT
+ */
+
+/**
+ * Creates a success response
+ */
+function successResponse(
+  res,
+  data = null,
+  message = "Success",
+  statusCode = 200,
+) {
+  return res.status(statusCode).json({
+    success: true,
+    message,
+    data,
+    meta: {
+      timestamp: new Date().toISOString(),
+      statusCode,
+    },
+  });
+}
+
+/**
+ * Creates an error response
+ */
+function errorResponse(
+  res,
+  message = "Something went wrong",
+  statusCode = 500,
+  errors = null,
+) {
+  return res.status(statusCode).json({
+    success: false,
+    message,
+    data: null,
+    errors,
+    meta: {
+      timestamp: new Date().toISOString(),
+      statusCode,
+    },
+  });
+}
+
+/**
+ * Creates a paginated response
+ */
+function paginatedResponse(
+  res,
+  data = [],
+  message = "Success",
+  pagination = {},
+) {
+  const { page = 1, limit = 10, total = 0 } = pagination;
+
+  const totalPages = Math.ceil(total / limit);
+
+  return res.status(200).json({
+    success: true,
+    message,
+    data,
+    meta: {
+      timestamp: new Date().toISOString(),
+      statusCode: 200,
+      pagination: {
+        page: Number(page),
+        limit: Number(limit),
+        total: Number(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);
+    };
+
+    // res.error(message, statusCode, errors)
+    res.error = function (
+      message = "Something went wrong",
+      statusCode = 500,
+      errors = null,
+    ) {
+      return errorResponse(res, message, statusCode, errors);
+    };
+
+    // res.paginate(data, message, pagination)
+    res.paginate = function (data = [], message = "Success", pagination = {}) {
+      return paginatedResponse(res, data, message, pagination);
+    };
+
+    // 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);
+
+    next();
+  };
+}
+
+// Named exports
+module.exports = apiResponse;
+module.exports.apiResponse = apiResponse;
+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

@@ -0,0 +1,108 @@
+import { Request, Response, NextFunction, RequestHandler } from "express";
+
+export interface Pagination {
+  page?: number;
+  limit?: number;
+  total?: number;
+}
+
+export interface PaginationMeta {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPrevPage: boolean;
+}
+
+export interface ApiMeta {
+  timestamp: string;
+  statusCode: number;
+  pagination?: PaginationMeta;
+}
+
+export interface ApiSuccessResponse<T = any> {
+  success: true;
+  message: string;
+  data: T;
+  meta: ApiMeta;
+}
+
+export interface ApiErrorResponse {
+  success: false;
+  message: string;
+  data: null;
+  errors: any | null;
+  meta: ApiMeta;
+}
+
+declare global {
+  namespace Express {
+    interface Response {
+      /** Send a success response */
+      success<T = any>(
+        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>(
+        data?: T[],
+        message?: string,
+        pagination?: Pagination,
+      ): Response;
+
+      // Shorthand methods
+      /** 200 OK */
+      ok<T = any>(data?: T, message?: string): Response;
+      /** 201 Created */
+      created<T = any>(data?: T, message?: string): Response;
+      /** 204 No Content */
+      noContent(): Response;
+
+      /** 400 Bad Request */
+      badRequest(message?: string, errors?: any): Response;
+      /** 401 Unauthorized */
+      unauthorized(message?: string): Response;
+      /** 403 Forbidden */
+      forbidden(message?: string): Response;
+      /** 404 Not Found */
+      notFound(message?: string): Response;
+      /** 409 Conflict */
+      conflict(message?: string): Response;
+      /** 422 Unprocessable Entity */
+      unprocessable(message?: string, errors?: any): Response;
+      /** 500 Internal Server Error */
+      serverError(message?: string): Response;
+    }
+  }
+}
+
+export declare function apiResponse(): RequestHandler;
+
+export declare function successResponse(
+  res: Response,
+  data?: any,
+  message?: string,
+  statusCode?: number,
+): Response;
+
+export declare function errorResponse(
+  res: Response,
+  message?: string,
+  statusCode?: number,
+  errors?: any,
+): Response;
+
+export declare function paginatedResponse(
+  res: Response,
+  data?: any[],
+  message?: string,
+  pagination?: Pagination,
+): Response;
+
+export default apiResponse;