response-kit 1.0.0 → 2.0.0

package/docs/error-response.md

@@ -1,222 +1,703 @@
 # Error Responses
 
-Error helpers make API error responses consistent across your application.
+This document covers all error response helpers in Response Kit v2.
 
 ---
 
-# badRequest()
+## Overview
 
-Status Code:
+Response Kit provides standardized error responses for common HTTP error status codes:
 
-```http
-400 Bad Request
+| Method | Status Code | Use Case |
+|--------|-------------|----------|
+| `badRequest()` | 400 | Invalid request data |
+| `unauthorized()` | 401 | Authentication required |
+| `forbidden()` | 403 | Insufficient permissions |
+| `notFound()` | 404 | Resource not found |
+| `conflict()` | 409 | Resource conflict |
+| `validationError()` | 422 | Validation failures |
+| `internalError()` | 500 | Server errors |
+
+All methods are available in two ways:
+- **Middleware API** (v2): `res.notFound(message)`
+- **Direct API** (v1): `response.notFound(res, message)`
+
+---
+
+## badRequest()
+
+Use when the client sends invalid or malformed request data.
+
+### Using Middleware (Recommended)
+
+```js
+app.use(response.middleware());
+
+app.post('/users', (req, res) => {
+  if (!req.body.email) {
+    return res.badRequest('Email is required');
+  }
+  
+  // Process request...
+});
 ```
 
-Example:
+### Using Direct API
 
 ```js
-response.badRequest(
-  res,
-  "Invalid Request Body"
-);
+app.post('/users', (req, res) => {
+  if (!req.body.email) {
+    return response.badRequest(res, 'Email is required');
+  }
+});
 ```
 
-Output:
+### Response
 
 ```json
 {
   "success": false,
-  "message": "Invalid Request Body",
-  "errors": null
+  "message": "Email is required"
 }
 ```
 
----
+**Status Code:** `400 Bad Request`
 
-# unauthorized()
+### Common Use Cases
 
-Status Code:
+- Missing required parameters
+- Invalid parameter format
+- Malformed JSON payload
+- Invalid query strings
 
-```http
-401 Unauthorized
+### Example
+
+```js
+app.get('/users', response.asyncHandler(async (req, res) => {
+  const { page, limit } = req.query;
+  
+  if (page && isNaN(page)) {
+    return res.badRequest('Page must be a number');
+  }
+  
+  if (limit && (limit < 1 || limit > 100)) {
+    return res.badRequest('Limit must be between 1 and 100');
+  }
+  
+  const users = await User.paginate(page, limit);
+  res.success(users);
+}));
 ```
 
-Example:
+---
+
+## unauthorized()
+
+Use when authentication is required but not provided or invalid.
+
+### Using Middleware
 
 ```js
-response.unauthorized(
-  res,
-  "Invalid Token"
-);
+app.get('/profile', (req, res) => {
+  if (!req.headers.authorization) {
+    return res.unauthorized('Authentication token required');
+  }
+  
+  // Verify token and proceed...
+});
 ```
 
-Output:
+### Response
 
 ```json
 {
   "success": false,
-  "message": "Invalid Token",
-  "errors": null
+  "message": "Authentication token required"
 }
 ```
 
----
+**Status Code:** `401 Unauthorized`
 
-# forbidden()
+### Common Use Cases
 
-Status Code:
+- Missing authentication token
+- Invalid credentials
+- Expired token
+- Invalid API key
 
-```http
-403 Forbidden
+### Example: Protected Route
+
+```js
+function authenticate(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.unauthorized('Invalid or expired token');
+  }
+}
+
+app.get('/profile', authenticate, response.asyncHandler(async (req, res) => {
+  const user = await User.findById(req.user.id);
+  res.success(user);
+}));
 ```
 
-Example:
+---
+
+## forbidden()
+
+Use when the user is authenticated but doesn't have permission.
+
+### Using Middleware
 
 ```js
-response.forbidden(
-  res,
-  "Access Denied"
-);
+app.delete('/users/:id', (req, res) => {
+  if (req.user.role !== 'admin') {
+    return res.forbidden('Admin access required');
+  }
+  
+  // Proceed with deletion...
+});
 ```
 
-Output:
+### Response
 
 ```json
 {
   "success": false,
-  "message": "Access Denied",
-  "errors": null
+  "message": "Admin access required"
 }
 ```
 
----
+**Status Code:** `403 Forbidden`
+
+### Common Use Cases
 
-# notFound()
+- Insufficient role/permissions
+- Resource ownership mismatch
+- Account limitations
+- Feature access restrictions
 
-Status Code:
+### Example: Role-Based Access Control
 
-```http
-404 Not Found
+```js
+function requireRole(role) {
+  return (req, res, next) => {
+    if (req.user.role !== role) {
+      return res.forbidden(`${role} access required`);
+    }
+    next();
+  };
+}
+
+app.delete('/posts/:id', 
+  authenticate, 
+  requireRole('admin'),
+  response.asyncHandler(async (req, res) => {
+    await Post.findByIdAndDelete(req.params.id);
+    res.success(null, 'Post deleted successfully');
+  })
+);
 ```
 
-Example:
+---
+
+## notFound()
+
+Use when a requested resource doesn't exist.
+
+### Using Middleware
 
 ```js
-response.notFound(
-  res,
-  "User Not Found"
-);
+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');
+  }
+  
+  res.success(user);
+}));
 ```
 
-Output:
+### Response
 
 ```json
 {
   "success": false,
-  "message": "User Not Found",
-  "errors": null
+  "message": "User not found"
 }
 ```
 
----
+**Status Code:** `404 Not Found`
+
+### Common Use Cases
 
-# conflict()
+- Resource ID doesn't exist
+- Route not found
+- File not found
+- Record deleted
 
-Status Code:
+### Example: 404 Handler
 
-```http
-409 Conflict
+```js
+// Route handlers...
+
+// 404 handler (place at the end)
+app.use((req, res) => {
+  res.notFound(`Route ${req.method} ${req.path} not found`);
+});
 ```
 
-Example:
+---
+
+## conflict()
+
+Use when there's a conflict with the current state of the resource.
+
+### Using Middleware
 
 ```js
-response.conflict(
-  res,
-  "Email Already Exists"
-);
+app.post('/users', response.asyncHandler(async (req, res) => {
+  const existing = await User.findOne({ email: req.body.email });
+  
+  if (existing) {
+    return res.conflict('User with this email already exists');
+  }
+  
+  const user = await User.create(req.body);
+  res.created(user);
+}));
 ```
 
-Output:
+### Response
 
 ```json
 {
   "success": false,
-  "message": "Email Already Exists",
-  "errors": null
+  "message": "User with this email already exists"
 }
 ```
 
+**Status Code:** `409 Conflict`
+
+### Common Use Cases
+
+- Duplicate unique field (email, username)
+- Resource version mismatch
+- Concurrent modification conflict
+- State transition conflict
+
+### Example: Username Availability
+
+```js
+app.post('/check-username', response.asyncHandler(async (req, res) => {
+  const { username } = req.body;
+  
+  const existing = await User.findOne({ username });
+  
+  if (existing) {
+    return res.conflict('Username is already taken');
+  }
+  
+  res.success(null, 'Username is available');
+}));
+```
+
 ---
 
-# internalError()
+## validationError()
 
-Status Code:
+Use when request validation fails. This helper is specifically designed for detailed validation errors.
 
-```http
-500 Internal Server Error
+### Using Middleware
+
+```js
+app.post('/users', response.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';
+  else if (!isValidEmail(email)) errors.email = 'Email is invalid';
+  
+  if (!password) errors.password = 'Password is required';
+  else if (password.length < 8) errors.password = 'Password must be at least 8 characters';
+  
+  if (Object.keys(errors).length > 0) {
+    return res.validationError(errors, 'Validation failed');
+  }
+  
+  const user = await User.create({ name, email, password });
+  res.created(user);
+}));
 ```
 
-Example:
+### Syntax
 
+**Middleware API:**
 ```js
-response.internalError(
-  res,
-  "Something Went Wrong"
-);
+res.validationError(errors, message)
 ```
 
-Output:
+**Direct API:**
+```js
+response.validationError(res, errors, message)
+```
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `errors` | object | No | `{}` | Validation error details |
+| `message` | string | No | `'Validation Failed'` | Error message |
+
+### Response
 
 ```json
 {
   "success": false,
-  "message": "Something Went Wrong",
-  "errors": null
+  "message": "Validation failed",
+  "errors": {
+    "name": "Name is required",
+    "email": "Email is invalid",
+    "password": "Password must be at least 8 characters"
+  }
 }
 ```
 
+**Status Code:** `422 Unprocessable Entity`
+
+### Example: Complex Validation
+
+```js
+app.post('/register', response.asyncHandler(async (req, res) => {
+  const { username, email, password, confirmPassword, age } = req.body;
+  
+  const errors = {};
+  
+  // Username validation
+  if (!username) {
+    errors.username = 'Username is required';
+  } else if (username.length < 3) {
+    errors.username = 'Username must be at least 3 characters';
+  } else if (!/^[a-zA-Z0-9_]+$/.test(username)) {
+    errors.username = 'Username can only contain letters, numbers, and underscores';
+  }
+  
+  // Email validation
+  if (!email) {
+    errors.email = 'Email is required';
+  } else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+    errors.email = 'Invalid email format';
+  }
+  
+  // Password validation
+  if (!password) {
+    errors.password = 'Password is required';
+  } else if (password.length < 8) {
+    errors.password = 'Password must be at least 8 characters';
+  } else if (!/(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/.test(password)) {
+    errors.password = 'Password must contain uppercase, lowercase, and number';
+  }
+  
+  // Confirm password
+  if (password !== confirmPassword) {
+    errors.confirmPassword = 'Passwords do not match';
+  }
+  
+  // Age validation
+  if (!age) {
+    errors.age = 'Age is required';
+  } else if (age < 18) {
+    errors.age = 'You must be at least 18 years old';
+  }
+  
+  if (Object.keys(errors).length > 0) {
+    return res.validationError(errors);
+  }
+  
+  // Proceed with registration...
+  const user = await User.create({ username, email, password, age });
+  res.created(user, 'Registration successful');
+}));
+```
+
 ---
 
-# validationError()
+## internalError()
 
-Used when user input validation fails.
+Use for unexpected server errors.
 
-Example:
+### Using Middleware
 
 ```js
-response.validationError(
-  res,
-  {
-    email: "Email is required",
-    password: "Password is required"
-  }
-);
+app.get('/users', response.asyncHandler(async (req, res) => {
+  const users = await User.find(); // If this throws, async handler catches it
+  res.success(users);
+}));
+
+// Global error handler
+app.use((err, req, res, next) => {
+  console.error('Error:', err);
+  res.internalError(err.message || 'Internal server error');
+});
 ```
 
-Output:
+### Response
 
 ```json
 {
   "success": false,
-  "message": "Validation Failed",
-  "errors": {
-    "email": "Email is required",
-    "password": "Password is required"
+  "message": "Database connection failed"
+}
+```
+
+**Status Code:** `500 Internal Server Error`
+
+### Common Use Cases
+
+- Database connection errors
+- Unexpected exceptions
+- Third-party API failures
+- File system errors
+
+### Example: Global Error Handler
+
+```js
+const express = require('express');
+const response = require('response-kit');
+
+const app = express();
+
+app.use(response.middleware());
+
+// Routes...
+
+// Global error handler (must be last)
+app.use((err, req, res, next) => {
+  console.error('Unhandled error:', err);
+  
+  // Don't expose internal error details in production
+  const message = process.env.NODE_ENV === 'production'
+    ? 'Internal server error'
+    : err.message;
+  
+  res.internalError(message);
+});
+```
+
+---
+
+## Complete Example
+
+Here's a complete CRUD API with proper error handling:
+
+```js
+const express = require('express');
+const response = require('response-kit');
+
+const app = express();
+
+app.use(express.json());
+app.use(response.middleware());
+
+// Get all users
+app.get('/users', response.asyncHandler(async (req, res) => {
+  const users = await User.find();
+  res.success(users, 'Users fetched successfully');
+}));
+
+// 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');
+  }
+  
+  res.success(user);
+}));
+
+// Create user
+app.post('/users', response.asyncHandler(async (req, res) => {
+  const { name, email, password } = req.body;
+  
+  // Validation
+  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.validationError(errors);
+  }
+  
+  // Check for duplicate
+  const existing = await User.findOne({ email });
+  if (existing) {
+    return res.conflict('Email already exists');
   }
+  
+  // Create
+  const user = await User.create({ name, email, password });
+  res.created(user, 'User created successfully');
+}));
+
+// Update user
+app.put('/users/:id', 
+  authenticate, 
+  response.asyncHandler(async (req, res) => {
+    const user = await User.findById(req.params.id);
+    
+    if (!user) {
+      return res.notFound('User not found');
+    }
+    
+    // Check ownership
+    if (user._id.toString() !== req.user.id && req.user.role !== 'admin') {
+      return res.forbidden('You can only update your own profile');
+    }
+    
+    Object.assign(user, req.body);
+    await user.save();
+    
+    res.success(user, 'User updated successfully');
+  })
+);
+
+// Delete user
+app.delete('/users/:id', 
+  authenticate,
+  requireRole('admin'),
+  response.asyncHandler(async (req, res) => {
+    const user = await User.findByIdAndDelete(req.params.id);
+    
+    if (!user) {
+      return res.notFound('User not found');
+    }
+    
+    res.success(null, 'User deleted successfully');
+  })
+);
+
+// 404 handler
+app.use((req, res) => {
+  res.notFound('Endpoint not found');
+});
+
+// Error handler
+app.use((err, req, res, next) => {
+  console.error(err);
+  res.internalError(err.message);
+});
+
+app.listen(3000);
+```
+
+---
+
+## Best Practices
+
+### ✅ Do's
+
+- Use specific error methods for each scenario
+- Provide clear, actionable error messages
+- Return validation errors as objects with field-level details
+- Implement global error handler for uncaught errors
+- Log errors server-side for debugging
+
+```js
+// ✅ Good
+if (!user) {
+  return res.notFound('User with ID ' + id + ' not found');
 }
+
+res.validationError({
+  email: 'Email format is invalid',
+  age: 'Age must be at least 18'
+});
+```
+
+### ❌ Don'ts
+
+- Don't expose sensitive error details to clients
+- Don't use generic messages for all errors
+- Don't return stack traces in production
+- Don't forget to return after sending error response
+
+```js
+// ❌ Bad
+res.internalError(err.stack); // Exposes internal details
+
+if (!user) {
+  res.notFound('Not found');
+  // Missing return - code continues executing!
+}
+
+res.badRequest('Error'); // Too generic
 ```
 
 ---
 
-# Best Practices
+## With Configuration
+
+Error responses also respect global configuration:
+
+```js
+response.configure({
+  successKey: 'status',
+  messageKey: 'msg',
+  errorKey: 'validationErrors',
+  includeTimestamp: true,
+});
+
+res.validationError({ email: 'Required' });
+```
+
+**Response:**
+```json
+{
+  "status": false,
+  "msg": "Validation Failed",
+  "validationErrors": {
+    "email": "Required"
+  },
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+```
+
+---
+
+## TypeScript
+
+```typescript
+import { ExtendedResponse } from 'response-kit';
+import { Request } from 'express';
+
+app.get('/users/:id', async (req: Request, res: ExtendedResponse) => {
+  const user = await User.findById(req.params.id);
+  
+  if (!user) {
+    return res.notFound('User not found');
+  }
+  
+  res.success(user);
+});
+```
+
+---
 
-Use:
+## Related
 
-* 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
+- [Success Responses](./success-response.md)
+- [Pagination](./pagination.md)
+- [Getting Started](./getting-started.md)