response-kit 1.0.0 → 2.0.0

package/docs/getting-started.md

@@ -1,8 +1,10 @@
-# Getting Started
+# Getting Started with Response Kit v2
 
-This guide will help you integrate API Response Kit into your Express.js application.
+This guide will help you get started with Response Kit v2, covering installation, basic setup, and common usage patterns.
 
-## Step 1: Install Package
+---
+
+## Installation
 
 ```bash
 npm install response-kit
@@ -10,74 +12,470 @@ npm install response-kit
 
 ---
 
-## Step 2: Import Package
+## Basic Setup
+
+### Method 1: Using Middleware (Recommended)
+
+The middleware approach is the cleanest and most modern way to use Response Kit.
+
+```js
+const express = require('express');
+const response = require('response-kit');
+
+const app = express();
+
+// Parse JSON bodies
+app.use(express.json());
+
+// Attach response helpers to res object
+app.use(response.middleware());
+
+// Now you can use response helpers directly on res
+app.get('/users', (req, res) => {
+  const users = [{ id: 1, name: 'John' }];
+  res.success(users, 'Users fetched successfully');
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+### Method 2: Direct Function Calls (v1 Compatible)
+
+If you prefer the original API or are migrating from v1:
+
+```js
+const express = require('express');
+const response = require('response-kit');
+
+const app = express();
+app.use(express.json());
+
+app.get('/users', (req, res) => {
+  const users = [{ id: 1, name: 'John' }];
+  response.success(res, users, 'Users fetched successfully');
+});
+
+app.listen(3000);
+```
+
+---
+
+## Configuration
+
+### Global Configuration
 
-### CommonJS
+Configure Response Kit once at application startup:
 
 ```js
-const response = require("response-kit");
+const response = require('response-kit');
+
+response.configure({
+  successKey: 'success',
+  dataKey: 'data',
+  messageKey: 'message',
+  errorKey: 'errors',
+  includeTimestamp: true,
+  includeRequestId: true,
+  includeMeta: false,
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `successKey` | string | `'success'` | Key name for success status |
+| `dataKey` | string | `'data'` | Key name for response data |
+| `messageKey` | string | `'message'` | Key name for messages |
+| `errorKey` | string | `'errors'` | Key name for error details |
+| `includeTimestamp` | boolean | `false` | Add ISO timestamp to responses |
+| `includeRequestId` | boolean | `false` | Add request ID to responses |
+| `includeMeta` | boolean | `false` | Add request metadata (method, path) |
+| `timestampKey` | string | `'timestamp'` | Key name for timestamp |
+| `requestIdKey` | string | `'requestId'` | Key name for request ID |
+| `metaKey` | string | `'meta'` | Key name for metadata |
+
+### Example with Custom Keys
+
+```js
+response.configure({
+  successKey: 'status',
+  dataKey: 'result',
+  messageKey: 'msg',
+});
+
+// Response output:
+// {
+//   "status": true,
+//   "msg": "Success",
+//   "result": { ... }
+// }
 ```
 
-### ESM
+---
+
+## Using the Middleware
+
+### Basic Usage
 
 ```js
-import response from "response-kit";
+const express = require('express');
+const response = require('response-kit');
+
+const app = express();
+
+// Apply middleware globally
+app.use(response.middleware());
+
+// All routes now have enhanced res object
+app.get('/api/status', (req, res) => {
+  res.success({ status: 'healthy' }, 'API is running');
+});
+
+app.get('/api/error', (req, res) => {
+  res.badRequest('Invalid request');
+});
 ```
 
+### Available Methods
+
+After applying middleware, these methods are available on `res`:
+
+**Success Responses:**
+- `res.success(data, message, statusCode)`
+- `res.created(data, message)`
+
+**Error Responses:**
+- `res.badRequest(message)`
+- `res.unauthorized(message)`
+- `res.forbidden(message)`
+- `res.notFound(message)`
+- `res.conflict(message)`
+- `res.internalError(message)`
+
+**Special Responses:**
+- `res.validationError(errors, message)`
+- `res.paginate(data, page, limit, total)`
+
 ---
 
-## Step 3: Create Express Server
+## Using Async Handler
+
+The async handler eliminates the need for repetitive try-catch blocks.
+
+### Without Async Handler
+
+```js
+app.get('/users/:id', async (req, res) => {
+  try {
+    const user = await User.findById(req.params.id);
+    
+    if (!user) {
+      return res.notFound('User not found');
+    }
+    
+    return res.success(user);
+  } catch (error) {
+    return res.internalError(error.message);
+  }
+});
+```
+
+### With Async Handler
 
 ```js
-const express = require("express");
-const response = require("response-kit");
+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);
+}));
+```
+
+### Error Handling with Async Handler
+
+The async handler automatically catches errors and passes them to Express error handling middleware:
+
+```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.use(response.middleware());
+
+// Routes with async handler
+app.get('/users', response.asyncHandler(async (req, res) => {
+  const users = await User.find(); // Any error here is caught
+  res.success(users);
+}));
+
+// Global error handler
+app.use((err, req, res, next) => {
+  console.error(err.stack);
+  res.internalError(err.message || 'Something went wrong');
 });
 
-app.listen(5000);
+app.listen(3000);
 ```
 
 ---
 
-## Step 4: Run Application
+## Complete Example
 
-```bash
-node app.js
+Here's a complete example showing all features:
+
+```js
+const express = require('express');
+const response = require('response-kit');
+
+const app = express();
+
+// Middleware
+app.use(express.json());
+app.use(response.middleware());
+
+// Configuration
+response.configure({
+  includeTimestamp: true,
+  includeRequestId: true,
+});
+
+// Mock database
+const users = [
+  { id: 1, name: 'John Doe', email: 'john@example.com' },
+  { id: 2, name: 'Jane Smith', email: 'jane@example.com' },
+];
+
+// Get all users
+app.get('/users', (req, res) => {
+  res.success(users, 'Users fetched successfully');
+});
+
+// Get user by ID
+app.get('/users/:id', response.asyncHandler(async (req, res) => {
+  const user = users.find(u => u.id === parseInt(req.params.id));
+  
+  if (!user) {
+    return res.notFound('User not found');
+  }
+  
+  res.success(user, 'User found');
+}));
+
+// Create user
+app.post('/users', response.asyncHandler(async (req, res) => {
+  const { name, email } = req.body;
+  
+  // Validation
+  if (!name || !email) {
+    return res.validationError({
+      name: !name ? 'Name is required' : undefined,
+      email: !email ? 'Email is required' : undefined,
+    });
+  }
+  
+  // Check for existing email
+  const existing = users.find(u => u.email === email);
+  if (existing) {
+    return res.conflict('Email already exists');
+  }
+  
+  // Create user
+  const newUser = {
+    id: users.length + 1,
+    name,
+    email,
+  };
+  
+  users.push(newUser);
+  
+  res.created(newUser, 'User created successfully');
+}));
+
+// Update user
+app.put('/users/:id', response.asyncHandler(async (req, res) => {
+  const user = users.find(u => u.id === parseInt(req.params.id));
+  
+  if (!user) {
+    return res.notFound('User not found');
+  }
+  
+  Object.assign(user, req.body);
+  
+  res.success(user, 'User updated successfully');
+}));
+
+// Delete user
+app.delete('/users/:id', response.asyncHandler(async (req, res) => {
+  const index = users.findIndex(u => u.id === parseInt(req.params.id));
+  
+  if (index === -1) {
+    return res.notFound('User not found');
+  }
+  
+  users.splice(index, 1);
+  
+  res.success(null, 'User deleted successfully');
+}));
+
+// Global error handler
+app.use((err, req, res, next) => {
+  console.error('Error:', err);
+  res.internalError(err.message || 'Internal server error');
+});
+
+// 404 handler
+app.use((req, res) => {
+  res.notFound('Route not found');
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server running on port ${PORT}`);
+});
+```
+
+---
+
+## Best Practices
+
+### 1. Use Middleware
+
+The middleware approach is cleaner and more maintainable:
+
+```js
+// ✅ Good
+app.use(response.middleware());
+app.get('/users', (req, res) => {
+  res.success(users);
+});
+
+// ❌ Acceptable but verbose
+app.get('/users', (req, res) => {
+  response.success(res, users);
+});
+```
+
+### 2. Configure Early
+
+Set up configuration before defining routes:
+
+```js
+const response = require('response-kit');
+
+// Configure first
+response.configure({
+  includeTimestamp: true,
+});
+
+// Then set up app
+const app = express();
+app.use(response.middleware());
 ```
 
-Visit
+### 3. Use Async Handler
+
+Always use async handler for async routes:
+
+```js
+// ✅ Good
+app.get('/users', response.asyncHandler(async (req, res) => {
+  const users = await User.find();
+  res.success(users);
+}));
 
-```text
-http://localhost:5000
+// ❌ Risky - unhandled promise rejection
+app.get('/users', async (req, res) => {
+  const users = await User.find();
+  res.success(users);
+});
 ```
 
-Response
+### 4. Global Error Handler
+
+Always implement a global error handler:
 
-```json
-{
-  "success": true,
-  "message": "Server Running Successfully",
-  "data": {
-    "project": "API Response Kit"
+```js
+app.use((err, req, res, next) => {
+  console.error(err.stack);
+  res.internalError(err.message);
+});
+```
+
+### 5. Validation First
+
+Validate input before processing:
+
+```js
+app.post('/users', response.asyncHandler(async (req, res) => {
+  // Validate first
+  if (!req.body.email) {
+    return res.validationError({ email: 'Email is required' });
   }
-}
+  
+  // Then process
+  const user = await User.create(req.body);
+  res.created(user);
+}));
 ```
 
 ---
 
 ## Next Steps
 
-* Learn Success Responses
-* Learn Error Responses
-* Learn Validation Errors
-* Learn Pagination
+- Read about [Success Responses](./success-response.md)
+- Learn about [Error Responses](./error-response.md)
+- Explore [Pagination](./pagination.md)
+- Check out [Complete Examples](../examples/)
+
+---
+
+## Troubleshooting
+
+### Middleware Not Working
+
+Make sure you're applying middleware before your routes:
+
+```js
+// ✅ Correct order
+app.use(response.middleware());
+app.get('/users', (req, res) => res.success(users));
+
+// ❌ Wrong order
+app.get('/users', (req, res) => res.success(users));
+app.use(response.middleware()); // Too late!
+```
+
+### TypeScript Errors
+
+Make sure you have the latest type definitions:
+
+```bash
+npm install response-kit@latest
+```
+
+Then use the extended response type:
+
+```typescript
+import { ExtendedResponse } from 'response-kit';
+
+app.get('/users', (req, res: ExtendedResponse) => {
+  res.success(users);
+});
+```
+
+---
+
+## Support
+
+If you encounter issues or have questions:
+
+1. Check the [documentation](../README.md)
+2. Look at [examples](../examples/)
+3. Open an issue on [GitHub](https://github.com/piyush72yaduvanshi/api-response-kit/issues)