response-kit 1.0.0 → 2.0.0

package/README.md

@@ -1,26 +1,30 @@
-![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)
+![npm](https://img.shields.io/npm/v/response-kit)
+![downloads](https://img.shields.io/npm/dm/response-kit)
+![license](https://img.shields.io/npm/l/response-kit)
+![build](https://img.shields.io/badge/build-passing-brightgreen)
 
-# Response Kit
+# Response Kit v2.0 🚀
 
-A lightweight, developer-friendly utility for standardized API responses in Express.js and Node.js applications.
+A production-grade, lightweight API response utility for **Express.js** and **Node.js** applications.
 
-Stop writing repetitive response code in every project.
+Version 2 brings **middleware support**, **global configuration**, **async handlers**, and a **scalable architecture** while maintaining **100% backward compatibility** with v1.
 
-## Features
+---
+
+## ✨ Why Response Kit?
 
-* Standard Success Responses
-* Standard Error Responses
-* Validation Error Handling
-* Pagination Support
-* TypeScript Support
-* ESM + CommonJS Support
-* Lightweight & Zero Dependencies
+✅ **Standardized API responses** across your entire application  
+✅ **Express middleware** for cleaner route handlers  
+✅ **Global configuration** - customize once, apply everywhere  
+✅ **Async handler** - eliminate repetitive try-catch blocks  
+✅ **TypeScript support** with comprehensive type definitions  
+✅ **Zero dependencies** - lightweight and fast  
+✅ **Production-ready** - follows SOLID principles and clean architecture  
+✅ **Backward compatible** - upgrade from v1 without breaking changes  
 
 ---
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install response-kit
@@ -28,206 +32,352 @@ npm install response-kit
 
 ---
 
-## Quick Start
+## 🎯 Quick Start
 
-### CommonJS
+### Method 1: Using Middleware (Recommended - v2)
 
 ```js
-const response = require("response-kit");
+const express = require('express');
+const response = require('response-kit');
+
+const app = express();
+
+// Attach response helpers to res object
+app.use(response.middleware());
+
+app.get('/user/:id', async (req, res) => {
+  const user = await getUserById(req.params.id);
+  
+  if (!user) {
+    return res.notFound('User not found');
+  }
+  
+  return res.success(user, 'User fetched successfully');
+});
+
+app.listen(3000);
 ```
 
-### ESM
+### Method 2: Direct Function Calls (v1 - Still Supported)
 
 ```js
-import response from "response-kit";
+const response = require('response-kit');
+
+app.get('/user/:id', async (req, res) => {
+  const user = await getUserById(req.params.id);
+  
+  if (!user) {
+    return response.notFound(res, 'User not found');
+  }
+  
+  return response.success(res, user, 'User fetched successfully');
+});
 ```
 
 ---
 
-## Basic Usage
+## 🔧 Configuration
+
+### Global Configuration
 
-### Success Response
+Configure once, apply everywhere:
 
 ```js
-app.get("/user", (req, res) => {
-  const user = {
-    id: 1,
-    name: "John Doe",
-    email: "john@example.com"
-  };
-
-  response.success(
-    res,
-    user,
-    "User fetched successfully"
-  );
+const response = require('response-kit');
+
+response.configure({
+  successKey: 'success',        // Key for success status
+  dataKey: 'data',              // Key for response data
+  messageKey: 'message',        // Key for messages
+  errorKey: 'errors',           // Key for error details
+  includeTimestamp: true,       // Add timestamp to responses
+  includeRequestId: true,       // Add request ID to responses
+  includeMeta: false,           // Add request metadata
 });
 ```
 
-Output
+**Example Response with Configuration:**
 
 ```json
 {
   "success": true,
-  "message": "User fetched successfully",
+  "message": "User created successfully",
   "data": {
     "id": 1,
-    "name": "John Doe",
-    "email": "john@example.com"
-  }
+    "name": "John Doe"
+  },
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "requestId": "1705315800000-a1b2c3d4e"
+}
+```
+
+### Custom Keys Example
+
+```js
+response.configure({
+  successKey: 'status',
+  dataKey: 'result',
+  messageKey: 'msg',
+  errorKey: 'validationErrors',
+});
+```
+
+**Output:**
+
+```json
+{
+  "status": true,
+  "msg": "Success",
+  "result": { "id": 1 }
 }
 ```
 
 ---
 
-### Created Response
+## 🎭 Middleware Usage
+
+### Basic Setup
 
 ```js
-app.post("/user", (req, res) => {
-  const user = {
-    id: 1,
-    name: "John Doe"
-  };
-
-  response.created(
-    res,
-    user,
-    "User created successfully"
-  );
+const express = require('express');
+const response = require('response-kit');
+
+const app = express();
+
+// Apply middleware globally
+app.use(response.middleware());
+
+// Now all routes have access to response helpers via res object
+app.get('/users', (req, res) => {
+  res.success(users, 'Users fetched successfully');
+});
+```
+
+### Available Methods on `res` Object
+
+After applying middleware, the following methods are available:
+
+- `res.success(data, message, statusCode)`
+- `res.created(data, message)`
+- `res.badRequest(message)`
+- `res.unauthorized(message)`
+- `res.forbidden(message)`
+- `res.notFound(message)`
+- `res.conflict(message)`
+- `res.internalError(message)`
+- `res.validationError(errors, message)`
+- `res.paginate(data, page, limit, total)`
+
+---
+
+## 🔄 Async Handler
+
+Eliminate repetitive try-catch blocks in your route handlers.
+
+### Without Async Handler ❌
+
+```js
+app.get('/users/:id', async (req, res) => {
+  try {
+    const user = await User.findById(req.params.id);
+    return res.success(user);
+  } catch (error) {
+    return res.internalError(error.message);
+  }
 });
 ```
 
-Status Code
+### With Async Handler ✅
+
+```js
+app.get('/users/:id', response.asyncHandler(async (req, res) => {
+  const user = await User.findById(req.params.id);
+  return res.success(user);
+}));
+```
+
+Any errors thrown inside the handler are automatically caught and passed to Express error handling middleware.
+
+### Complete Example with Error Handler
+
+```js
+const express = require('express');
+const response = require('response-kit');
+
+const app = express();
+
+app.use(response.middleware());
+
+// Routes with async handler
+app.get('/users/:id', response.asyncHandler(async (req, res) => {
+  const user = await User.findById(req.params.id);
+  
+  if (!user) {
+    return res.notFound('User not found');
+  }
+  
+  return res.success(user);
+}));
+
+// Global error handler
+app.use((err, req, res, next) => {
+  console.error(err.stack);
+  res.internalError(err.message || 'Something went wrong');
+});
 
-```text
-201 Created
+app.listen(3000);
 ```
 
 ---
 
-## Error Responses
+## 📖 API Reference
+
+### Success Responses
 
-### Bad Request
+#### `success(data, message, statusCode)`
+
+Send a successful response.
 
 ```js
-response.badRequest(
-  res,
-  "Invalid Request"
+res.success(
+  { id: 1, name: 'John' },
+  'User fetched successfully',
+  200
 );
 ```
 
-Output
-
+**Response:**
 ```json
 {
-  "success": false,
-  "message": "Invalid Request",
-  "errors": null
+  "success": true,
+  "message": "User fetched successfully",
+  "data": { "id": 1, "name": "John" }
 }
 ```
 
----
+#### `created(data, message)`
 
-### Unauthorized
+Send a 201 Created response.
 
 ```js
-response.unauthorized(
-  res,
-  "Invalid Token"
+res.created(
+  { id: 1, name: 'John' },
+  'User created successfully'
 );
 ```
 
+**Status Code:** `201`
+
 ---
 
-### Forbidden
+### Error Responses
+
+#### `badRequest(message)`
+
+Send a 400 Bad Request response.
 
 ```js
-response.forbidden(
-  res,
-  "Access Denied"
-);
+res.badRequest('Invalid input data');
 ```
 
----
+**Status Code:** `400`
 
-### Not Found
+#### `unauthorized(message)`
+
+Send a 401 Unauthorized response.
 
 ```js
-response.notFound(
-  res,
-  "User Not Found"
-);
+res.unauthorized('Invalid credentials');
 ```
 
----
+**Status Code:** `401`
 
-### Conflict
+#### `forbidden(message)`
+
+Send a 403 Forbidden response.
 
 ```js
-response.conflict(
-  res,
-  "Email Already Exists"
-);
+res.forbidden('Access denied');
 ```
 
----
+**Status Code:** `403`
 
-### Internal Server Error
+#### `notFound(message)`
+
+Send a 404 Not Found response.
 
 ```js
-response.internalError(
-  res,
-  "Something Went Wrong"
-);
+res.notFound('User not found');
 ```
 
----
+**Status Code:** `404`
 
-## Validation Error
+#### `conflict(message)`
+
+Send a 409 Conflict response.
 
 ```js
-response.validationError(
-  res,
-  {
-    email: "Email is required",
-    password: "Password is required"
-  }
-);
+res.conflict('Email already exists');
 ```
 
-Output
+**Status Code:** `409`
+
+#### `internalError(message)`
+
+Send a 500 Internal Server Error response.
+
+```js
+res.internalError('Database connection failed');
+```
+
+**Status Code:** `500`
+
+---
+
+### Validation Errors
+
+#### `validationError(errors, message)`
 
+Send a 422 Unprocessable Entity response with validation errors.
+
+```js
+res.validationError({
+  email: 'Email is required',
+  password: 'Password must be at least 8 characters'
+}, 'Validation failed');
+```
+
+**Response:**
 ```json
 {
   "success": false,
-  "message": "Validation Failed",
+  "message": "Validation failed",
   "errors": {
     "email": "Email is required",
-    "password": "Password is required"
+    "password": "Password must be at least 8 characters"
   }
 }
 ```
 
+**Status Code:** `422`
+
 ---
 
-## Pagination
+### Pagination
+
+#### `paginate(data, page, limit, total)`
+
+Send a paginated response.
 
 ```js
-response.paginate(
-  res,
-  users,
-  1,
-  10,
-  100
-);
+res.paginate(users, 1, 10, 100);
 ```
 
-Output
-
+**Response:**
 ```json
 {
   "success": true,
-  "data": [],
+  "data": [...],
   "pagination": {
     "page": 1,
     "limit": 10,
@@ -239,55 +389,316 @@ Output
 
 ---
 
-## 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   |
+## 🔄 Migration Guide (v1 to v2)
 
----
+### Good News: Zero Breaking Changes! 🎉
 
-## TypeScript
+All v1 APIs work exactly as before. You can upgrade and adopt v2 features gradually.
 
-Type definitions are included.
+### Step 1: Update Package
 
-```ts
-import response from "response-kit";
+```bash
+npm install response-kit@latest
+```
 
-response.success(res, user);
+### Step 2: Keep Using v1 API (Optional)
+
+```js
+// This still works perfectly
+response.success(res, data, message);
+response.notFound(res, 'Not found');
 ```
 
-No additional setup required.
+### Step 3: Gradually Adopt v2 Features
+
+#### Add Middleware
+
+```js
+app.use(response.middleware());
+
+// Now you can use
+res.success(data, message);
+res.notFound('Not found');
+```
+
+#### Add Configuration
+
+```js
+response.configure({
+  includeTimestamp: true,
+  includeRequestId: true,
+});
+```
+
+#### Use Async Handler
+
+```js
+app.get('/users', response.asyncHandler(async (req, res) => {
+  const users = await User.find();
+  res.success(users);
+}));
+```
+
+### Migration Examples
+
+#### Before (v1):
+
+```js
+app.get('/users/:id', async (req, res) => {
+  try {
+    const user = await User.findById(req.params.id);
+    if (!user) {
+      return response.notFound(res, 'User not found');
+    }
+    return response.success(res, user);
+  } catch (error) {
+    return response.internalError(res, error.message);
+  }
+});
+```
+
+#### After (v2):
+
+```js
+app.use(response.middleware());
+
+app.get('/users/:id', response.asyncHandler(async (req, res) => {
+  const user = await User.findById(req.params.id);
+  if (!user) {
+    return res.notFound('User not found');
+  }
+  return res.success(user);
+}));
+```
 
 ---
 
-## Examples
+## 💡 Complete Examples
 
-Check examples folder for complete working examples.
+### Example 1: RESTful User API
 
-```bash
-examples/
-├── commonjs-example.js
-└── esm-example.js
+```js
+const express = require('express');
+const response = require('response-kit');
+
+const app = express();
+app.use(express.json());
+app.use(response.middleware());
+
+// Configure globally
+response.configure({
+  includeTimestamp: true,
+  includeRequestId: true,
+});
+
+// Get all users with pagination
+app.get('/users', response.asyncHandler(async (req, res) => {
+  const page = parseInt(req.query.page) || 1;
+  const limit = parseInt(req.query.limit) || 10;
+  
+  const users = await User.find()
+    .skip((page - 1) * limit)
+    .limit(limit);
+  
+  const total = await User.countDocuments();
+  
+  return res.paginate(users, page, limit, total);
+}));
+
+// Get user by ID
+app.get('/users/:id', response.asyncHandler(async (req, res) => {
+  const user = await User.findById(req.params.id);
+  
+  if (!user) {
+    return res.notFound('User not found');
+  }
+  
+  return res.success(user, 'User fetched successfully');
+}));
+
+// Create new user
+app.post('/users', response.asyncHandler(async (req, res) => {
+  const { email, name, password } = req.body;
+  
+  // Validation
+  if (!email || !name || !password) {
+    return res.validationError({
+      email: !email ? 'Email is required' : undefined,
+      name: !name ? 'Name is required' : undefined,
+      password: !password ? 'Password is required' : undefined,
+    });
+  }
+  
+  // Check if user exists
+  const existingUser = await User.findOne({ email });
+  if (existingUser) {
+    return res.conflict('User with this email already exists');
+  }
+  
+  // Create user
+  const user = await User.create({ email, name, password });
+  
+  return res.created(user, 'User created successfully');
+}));
+
+// Update user
+app.put('/users/:id', response.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.success(user, 'User updated successfully');
+}));
+
+// Delete user
+app.delete('/users/:id', response.asyncHandler(async (req, res) => {
+  const user = await User.findByIdAndDelete(req.params.id);
+  
+  if (!user) {
+    return res.notFound('User not found');
+  }
+  
+  return res.success(null, 'User deleted successfully');
+}));
+
+// Global error handler
+app.use((err, req, res, next) => {
+  console.error(err.stack);
+  res.internalError(err.message || 'Internal server error');
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+### Example 2: Authentication API
+
+```js
+const express = require('express');
+const response = require('response-kit');
+const jwt = require('jsonwebtoken');
+
+const app = express();
+app.use(express.json());
+app.use(response.middleware());
+
+// Login
+app.post('/auth/login', response.asyncHandler(async (req, res) => {
+  const { email, password } = req.body;
+  
+  if (!email || !password) {
+    return res.badRequest('Email and password are required');
+  }
+  
+  const user = await User.findOne({ email });
+  
+  if (!user || !await user.comparePassword(password)) {
+    return res.unauthorized('Invalid credentials');
+  }
+  
+  const token = jwt.sign({ id: user._id }, process.env.JWT_SECRET);
+  
+  return res.success({ token, user }, 'Login successful');
+}));
+
+// Protected route
+app.get('/profile', authenticateToken, response.asyncHandler(async (req, res) => {
+  const user = await User.findById(req.user.id);
+  
+  if (!user) {
+    return res.notFound('User not found');
+  }
+  
+  return res.success(user);
+}));
+
+// Middleware
+function authenticateToken(req, res, next) {
+  const token = req.headers['authorization']?.split(' ')[1];
+  
+  if (!token) {
+    return res.unauthorized('Access token required');
+  }
+  
+  try {
+    req.user = jwt.verify(token, process.env.JWT_SECRET);
+    next();
+  } catch (error) {
+    return res.forbidden('Invalid or expired token');
+  }
+}
+
+app.listen(3000);
 ```
 
 ---
 
-## License
+## 📚 Documentation
 
-MIT
+- [Getting Started](./docs/getting-started.md)
+- [Success Responses](./docs/success-response.md)
+- [Error Responses](./docs/error-response.md)
+- [Pagination](./docs/pagination.md)
 
 ---
 
-## Author
+## 🤝 Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+---
+
+## 📝 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for release notes.
+
+---
+
+## 📄 License
+
+MIT © [Piyush Yadav](https://github.com/piyush72yaduvanshi)
+
+---
+
+## 🌟 Features Summary
+
+| Feature | v1 | v2 |
+|---------|----|----|
+| Success/Error responses | ✅ | ✅ |
+| Pagination | ✅ | ✅ |
+| TypeScript support | ✅ | ✅ |
+| Express middleware | ❌ | ✅ |
+| Global configuration | ❌ | ✅ |
+| Async handler | ❌ | ✅ |
+| Request ID tracking | ❌ | ✅ |
+| Timestamp support | ❌ | ✅ |
+| Custom response keys | ❌ | ✅ |
+| Backward compatible | - | ✅ |
+
+---
+
+## 🚀 Why Upgrade to v2?
+
+1. **Cleaner Code**: Middleware reduces boilerplate
+2. **Flexible Configuration**: Customize response structure globally
+3. **Better Error Handling**: Async handler eliminates try-catch blocks
+4. **Production Features**: Request IDs, timestamps, metadata
+5. **Modern Architecture**: SOLID principles, scalable structure
+6. **Zero Risk**: 100% backward compatible with v1
+
+---
+
+## ⭐ Show Your Support
+
+If you find this package helpful, please give it a star on [GitHub](https://github.com/piyush72yaduvanshi/api-response-kit)!
+
+---
 
-Piyush Yadav
+**Built with ❤️ by developers, for developers.**