response-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piyush Yadav
+
+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 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,293 @@
+![npm](https://img.shields.io/npm/v/api-response-kit)
+![downloads](https://img.shields.io/npm/dm/api-response-kit)
+![license](https://img.shields.io/npm/l/api-response-kit)
+
+# Response Kit
+
+A lightweight, developer-friendly utility for standardized API responses in Express.js and Node.js applications.
+
+Stop writing repetitive response code in every project.
+
+## Features
+
+* Standard Success Responses
+* Standard Error Responses
+* Validation Error Handling
+* Pagination Support
+* TypeScript Support
+* ESM + CommonJS Support
+* Lightweight & Zero Dependencies
+
+---
+
+## Installation
+
+```bash
+npm install response-kit
+```
+
+---
+
+## Quick Start
+
+### CommonJS
+
+```js
+const response = require("response-kit");
+```
+
+### ESM
+
+```js
+import response from "response-kit";
+```
+
+---
+
+## Basic Usage
+
+### Success Response
+
+```js
+app.get("/user", (req, res) => {
+  const user = {
+    id: 1,
+    name: "John Doe",
+    email: "john@example.com"
+  };
+
+  response.success(
+    res,
+    user,
+    "User fetched successfully"
+  );
+});
+```
+
+Output
+
+```json
+{
+  "success": true,
+  "message": "User fetched successfully",
+  "data": {
+    "id": 1,
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+
+---
+
+### Created Response
+
+```js
+app.post("/user", (req, res) => {
+  const user = {
+    id: 1,
+    name: "John Doe"
+  };
+
+  response.created(
+    res,
+    user,
+    "User created successfully"
+  );
+});
+```
+
+Status Code
+
+```text
+201 Created
+```
+
+---
+
+## Error Responses
+
+### Bad Request
+
+```js
+response.badRequest(
+  res,
+  "Invalid Request"
+);
+```
+
+Output
+
+```json
+{
+  "success": false,
+  "message": "Invalid Request",
+  "errors": null
+}
+```
+
+---
+
+### Unauthorized
+
+```js
+response.unauthorized(
+  res,
+  "Invalid Token"
+);
+```
+
+---
+
+### Forbidden
+
+```js
+response.forbidden(
+  res,
+  "Access Denied"
+);
+```
+
+---
+
+### Not Found
+
+```js
+response.notFound(
+  res,
+  "User Not Found"
+);
+```
+
+---
+
+### Conflict
+
+```js
+response.conflict(
+  res,
+  "Email Already Exists"
+);
+```
+
+---
+
+### Internal Server Error
+
+```js
+response.internalError(
+  res,
+  "Something Went Wrong"
+);
+```
+
+---
+
+## Validation Error
+
+```js
+response.validationError(
+  res,
+  {
+    email: "Email is required",
+    password: "Password is required"
+  }
+);
+```
+
+Output
+
+```json
+{
+  "success": false,
+  "message": "Validation Failed",
+  "errors": {
+    "email": "Email is required",
+    "password": "Password is required"
+  }
+}
+```
+
+---
+
+## Pagination
+
+```js
+response.paginate(
+  res,
+  users,
+  1,
+  10,
+  100
+);
+```
+
+Output
+
+```json
+{
+  "success": true,
+  "data": [],
+  "pagination": {
+    "page": 1,
+    "limit": 10,
+    "total": 100,
+    "totalPages": 10
+  }
+}
+```
+
+---
+
+## API Reference
+
+| Method            | Description               |
+| ----------------- | ------------------------- |
+| success()         | Send success response     |
+| created()         | Send 201 created response |
+| badRequest()      | Send 400 response         |
+| unauthorized()    | Send 401 response         |
+| forbidden()       | Send 403 response         |
+| notFound()        | Send 404 response         |
+| conflict()        | Send 409 response         |
+| internalError()   | Send 500 response         |
+| validationError() | Send validation errors    |
+| paginate()        | Send paginated response   |
+
+---
+
+## TypeScript
+
+Type definitions are included.
+
+```ts
+import response from "response-kit";
+
+response.success(res, user);
+```
+
+No additional setup required.
+
+---
+
+## Examples
+
+Check examples folder for complete working examples.
+
+```bash
+examples/
+├── commonjs-example.js
+└── esm-example.js
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+## Author
+
+Piyush Yadav

package/docs/error-response.md

@@ -0,0 +1,222 @@
+# Error Responses
+
+Error helpers make API error responses consistent across your application.
+
+---
+
+# badRequest()
+
+Status Code:
+
+```http
+400 Bad Request
+```
+
+Example:
+
+```js
+response.badRequest(
+  res,
+  "Invalid Request Body"
+);
+```
+
+Output:
+
+```json
+{
+  "success": false,
+  "message": "Invalid Request Body",
+  "errors": null
+}
+```
+
+---
+
+# unauthorized()
+
+Status Code:
+
+```http
+401 Unauthorized
+```
+
+Example:
+
+```js
+response.unauthorized(
+  res,
+  "Invalid Token"
+);
+```
+
+Output:
+
+```json
+{
+  "success": false,
+  "message": "Invalid Token",
+  "errors": null
+}
+```
+
+---
+
+# forbidden()
+
+Status Code:
+
+```http
+403 Forbidden
+```
+
+Example:
+
+```js
+response.forbidden(
+  res,
+  "Access Denied"
+);
+```
+
+Output:
+
+```json
+{
+  "success": false,
+  "message": "Access Denied",
+  "errors": null
+}
+```
+
+---
+
+# notFound()
+
+Status Code:
+
+```http
+404 Not Found
+```
+
+Example:
+
+```js
+response.notFound(
+  res,
+  "User Not Found"
+);
+```
+
+Output:
+
+```json
+{
+  "success": false,
+  "message": "User Not Found",
+  "errors": null
+}
+```
+
+---
+
+# conflict()
+
+Status Code:
+
+```http
+409 Conflict
+```
+
+Example:
+
+```js
+response.conflict(
+  res,
+  "Email Already Exists"
+);
+```
+
+Output:
+
+```json
+{
+  "success": false,
+  "message": "Email Already Exists",
+  "errors": null
+}
+```
+
+---
+
+# internalError()
+
+Status Code:
+
+```http
+500 Internal Server Error
+```
+
+Example:
+
+```js
+response.internalError(
+  res,
+  "Something Went Wrong"
+);
+```
+
+Output:
+
+```json
+{
+  "success": false,
+  "message": "Something Went Wrong",
+  "errors": null
+}
+```
+
+---
+
+# validationError()
+
+Used when user input validation fails.
+
+Example:
+
+```js
+response.validationError(
+  res,
+  {
+    email: "Email is required",
+    password: "Password is required"
+  }
+);
+```
+
+Output:
+
+```json
+{
+  "success": false,
+  "message": "Validation Failed",
+  "errors": {
+    "email": "Email is required",
+    "password": "Password is required"
+  }
+}
+```
+
+---
+
+# Best Practices
+
+Use:
+
+* badRequest() for invalid requests
+* unauthorized() for invalid authentication
+* forbidden() for permission issues
+* notFound() when resource doesn't exist
+* conflict() for duplicate data
+* validationError() for validation failures
+* internalError() for server errors

package/docs/getting-started.md

@@ -0,0 +1,83 @@
+# Getting Started
+
+This guide will help you integrate API Response Kit into your Express.js application.
+
+## Step 1: Install Package
+
+```bash
+npm install response-kit
+```
+
+---
+
+## Step 2: Import Package
+
+### CommonJS
+
+```js
+const response = require("response-kit");
+```
+
+### ESM
+
+```js
+import response from "response-kit";
+```
+
+---
+
+## Step 3: Create Express Server
+
+```js
+const express = require("express");
+const response = require("response-kit");
+
+const app = express();
+
+app.get("/", (req, res) => {
+  response.success(
+    res,
+    {
+      project: "API Response Kit"
+    },
+    "Server Running Successfully"
+  );
+});
+
+app.listen(5000);
+```
+
+---
+
+## Step 4: Run Application
+
+```bash
+node app.js
+```
+
+Visit
+
+```text
+http://localhost:5000
+```
+
+Response
+
+```json
+{
+  "success": true,
+  "message": "Server Running Successfully",
+  "data": {
+    "project": "API Response Kit"
+  }
+}
+```
+
+---
+
+## Next Steps
+
+* Learn Success Responses
+* Learn Error Responses
+* Learn Validation Errors
+* Learn Pagination

package/docs/pagination.md

@@ -0,0 +1,138 @@
+# Pagination
+
+Pagination helper provides a standard structure for paginated APIs.
+
+---
+
+# Why Pagination?
+
+Imagine you have:
+
+```text
+10000 Users
+50000 Products
+100000 Orders
+```
+
+Returning everything in one request is inefficient.
+
+Pagination helps return data in chunks.
+
+---
+
+# Syntax
+
+```js
+response.paginate(
+  res,
+  data,
+  page,
+  limit,
+  total
+);
+```
+
+---
+
+# Example
+
+```js
+app.get("/users", (req, res) => {
+
+  const users = [
+    {
+      id: 1,
+      name: "John"
+    },
+    {
+      id: 2,
+      name: "Jane"
+    }
+  ];
+
+  response.paginate(
+    res,
+    users,
+    1,
+    10,
+    100
+  );
+
+});
+```
+
+---
+
+# Output
+
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": 1,
+      "name": "John"
+    },
+    {
+      "id": 2,
+      "name": "Jane"
+    }
+  ],
+  "pagination": {
+    "page": 1,
+    "limit": 10,
+    "total": 100,
+    "totalPages": 10
+  }
+}
+```
+
+---
+
+# Explanation
+
+| Property   | Description           |
+| ---------- | --------------------- |
+| page       | Current page          |
+| limit      | Items per page        |
+| total      | Total records         |
+| totalPages | Total pages available |
+
+---
+
+# MongoDB Example
+
+```js
+const page = Number(req.query.page) || 1;
+const limit = Number(req.query.limit) || 10;
+
+const skip = (page - 1) * limit;
+
+const users = await User.find()
+  .skip(skip)
+  .limit(limit);
+
+const total = await User.countDocuments();
+
+response.paginate(
+  res,
+  users,
+  page,
+  limit,
+  total
+);
+```
+
+---
+
+# Best Practices
+
+✅ Always return pagination object
+
+✅ Include total count
+
+✅ Use page & limit query parameters
+
+✅ Keep response structure consistent
+
+This makes frontend pagination implementation much easier.

package/docs/success-response.md

@@ -0,0 +1,133 @@
+# Success Responses
+
+Success responses are used when an operation completes successfully.
+
+---
+
+# success()
+
+Use this method when data is fetched successfully.
+
+## Syntax
+
+```js
+response.success(
+  res,
+  data,
+  message
+);
+```
+
+## Example
+
+```js
+app.get("/users", (req, res) => {
+  const users = [
+    {
+      id: 1,
+      name: "John"
+    }
+  ];
+
+  response.success(
+    res,
+    users,
+    "Users fetched successfully"
+  );
+});
+```
+
+---
+
+## Output
+
+```json
+{
+  "success": true,
+  "message": "Users fetched successfully",
+  "data": [
+    {
+      "id": 1,
+      "name": "John"
+    }
+  ]
+}
+```
+
+---
+
+# created()
+
+Use this helper after creating a new resource.
+
+Examples:
+
+* User Registration
+* Product Creation
+* Order Creation
+
+---
+
+## Syntax
+
+```js
+response.created(
+  res,
+  data,
+  message
+);
+```
+
+---
+
+## Example
+
+```js
+app.post("/users", (req, res) => {
+  const user = {
+    id: 1,
+    name: "John"
+  };
+
+  response.created(
+    res,
+    user,
+    "User created successfully"
+  );
+});
+```
+
+---
+
+## Output
+
+```json
+{
+  "success": true,
+  "message": "User created successfully",
+  "data": {
+    "id": 1,
+    "name": "John"
+  }
+}
+```
+
+---
+
+## Status Code
+
+```http
+201 Created
+```
+
+---
+
+# Best Practices
+
+✅ Use success() for fetching data
+
+✅ Use created() for creating resources
+
+❌ Don't use success() after creating resources
+
+❌ Don't manually write JSON responses if using API Response Kit

package/index.d.ts

@@ -0,0 +1,56 @@
+export function success(
+  res: any,
+  data?: any,
+  message?: string,
+  statusCode?: number
+): any;
+
+export function created(
+  res: any,
+  data?: any,
+  message?: string
+): any;
+
+export function badRequest(
+  res: any,
+  message?: string
+): any;
+
+export function unauthorized(
+  res: any,
+  message?: string
+): any;
+
+export function forbidden(
+  res: any,
+  message?: string
+): any;
+
+export function notFound(
+  res: any,
+  message?: string
+): any;
+
+export function conflict(
+  res: any,
+  message?: string
+): any;
+
+export function internalError(
+  res: any,
+  message?: string
+): any;
+
+export function validationError(
+  res: any,
+  errors?: object,
+  message?: string
+): any;
+
+export function paginate(
+  res: any,
+  data: any[],
+  page: number,
+  limit: number,
+  total: number
+): any;

package/package.json

@@ -0,0 +1,51 @@
+{
+"name": "response-kit",
+"version": "1.0.0",
+"description": "Standardized API response utility for Node.js and Express.js",
+"main": "./src/index.js",
+"types": "./index.d.ts",
+"exports": {
+".": {
+"require": "./src/index.js",
+"import": "./src/index.js",
+"types": "./index.d.ts"
+}
+},
+"files": [
+"src",
+"docs",
+"index.d.ts",
+"README.md",
+"LICENSE"
+],
+"scripts": {
+"lint": "eslint .",
+"format": "prettier --write ."
+},
+"keywords": [
+"express",
+"nodejs",
+"api",
+"response",
+"response-helper",
+"api-response",
+"backend"
+],
+"author": "Piyush Yadav",
+"license": "MIT",
+"type": "commonjs",
+"repository": {
+"type": "git",
+"url": "git+https://github.com/piyush72yaduvanshi/api-response-kit.git"
+},
+"bugs": {
+"url": "https://github.com/piyush72yaduvanshi/api-response-kit/issues"
+},
+"homepage": "https://github.com/piyush72yaduvanshi/api-response-kit#readme",
+"devDependencies": {
+"eslint": "^10.5.0",
+"jest": "^30.4.2",
+"prettier": "^3.8.4",
+"typescript": "^6.0.3"
+}
+}

package/src/error.js

@@ -0,0 +1,41 @@
+const sendError = (
+  res,
+  statusCode,
+  message,
+  errors = null
+) => {
+  return res.status(statusCode).json({
+    success: false,
+    message,
+    errors,
+  });
+};
+
+const badRequest = (res, msg = "Bad Request") =>
+  sendError(res, 400, msg);
+
+const unauthorized = (res, msg = "Unauthorized") =>
+  sendError(res, 401, msg);
+
+const forbidden = (res, msg = "Forbidden") =>
+  sendError(res, 403, msg);
+
+const notFound = (res, msg = "Not Found") =>
+  sendError(res, 404, msg);
+
+const conflict = (res, msg = "Conflict") =>
+  sendError(res, 409, msg);
+
+const internalError = (
+  res,
+  msg = "Internal Server Error"
+) => sendError(res, 500, msg);
+
+module.exports = {
+  badRequest,
+  unauthorized,
+  forbidden,
+  notFound,
+  conflict,
+  internalError,
+};

package/src/index.js

@@ -0,0 +1,6 @@
+module.exports = {
+  ...require("./success"),
+  ...require("./error"),
+  ...require("./validation"),
+  ...require("./pagination"),
+};

package/src/pagination.js

@@ -0,0 +1,22 @@
+const paginate = (
+  res,
+  data,
+  page,
+  limit,
+  total
+) => {
+  return res.status(200).json({
+    success: true,
+    data,
+    pagination: {
+      page,
+      limit,
+      total,
+      totalPages: Math.ceil(total / limit),
+    },
+  });
+};
+
+module.exports = {
+  paginate,
+};

package/src/success.js

@@ -0,0 +1,25 @@
+const success = (
+  res,
+  data = null,
+  message = "Success",
+  statusCode = 200
+) => {
+  return res.status(statusCode).json({
+    success: true,
+    message,
+    data,
+  });
+};
+
+const created = (
+  res,
+  data = null,
+  message = "Created Successfully"
+) => {
+  return success(res, data, message, 201);
+};
+
+module.exports = {
+  success,
+  created,
+};

package/src/validation.js

@@ -0,0 +1,15 @@
+const validationError = (
+  res,
+  errors = {},
+  message = "Validation Failed"
+) => {
+  return res.status(422).json({
+    success: false,
+    message,
+    errors,
+  });
+};
+
+module.exports = {
+  validationError,
+};