response-kit 1.0.0 → 2.0.0

package/docs/success-response.md

@@ -1,105 +1,181 @@
 # Success Responses
 
+This document covers all success response helpers in Response Kit v2.
+
 Success responses are used when an operation completes successfully.
 
 ---
 
-# success()
+## Overview
+
+Response Kit provides two success response helpers:
+
+1. **`success()`** - General success responses (200)
+2. **`created()`** - Resource creation responses (201)
 
-Use this method when data is fetched successfully.
+Both methods are available in two ways:
+- **Middleware API** (v2): `res.success(data, message)`
+- **Direct API** (v1): `response.success(res, data, message)`
+
+---
 
-## Syntax
+## success()
+
+Use this method when data is fetched or an operation completes successfully.
+
+### Using Middleware (Recommended)
 
 ```js
-response.success(
-  res,
-  data,
-  message
-);
+app.use(response.middleware());
+
+app.get('/users', (req, res) => {
+  const users = [
+    { id: 1, name: 'John Doe' },
+    { id: 2, name: 'Jane Smith' }
+  ];
+
+  res.success(users, 'Users fetched successfully');
+});
 ```
 
-## Example
+### Using Direct API
 
 ```js
-app.get("/users", (req, res) => {
+app.get('/users', (req, res) => {
   const users = [
-    {
-      id: 1,
-      name: "John"
-    }
+    { id: 1, name: 'John Doe' },
+    { id: 2, name: 'Jane Smith' }
   ];
 
-  response.success(
-    res,
-    users,
-    "Users fetched successfully"
-  );
+  response.success(res, users, 'Users fetched successfully');
 });
 ```
 
----
+### Syntax
+
+**Middleware API:**
+```js
+res.success(data, message, statusCode)
+```
 
-## Output
+**Direct API:**
+```js
+response.success(res, data, message, statusCode)
+```
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `data` | any | No | `null` | Response data |
+| `message` | string | No | `'Success'` | Success message |
+| `statusCode` | number | No | `200` | HTTP status code |
+
+### Response Structure
 
 ```json
 {
   "success": true,
   "message": "Users fetched successfully",
   "data": [
-    {
-      "id": 1,
-      "name": "John"
-    }
+    { "id": 1, "name": "John Doe" },
+    { "id": 2, "name": "Jane Smith" }
   ]
 }
 ```
 
----
+**Status Code:** `200 OK`
 
-# created()
+### With Configuration
 
-Use this helper after creating a new resource.
+```js
+response.configure({
+  includeTimestamp: true,
+  includeRequestId: true,
+});
 
-Examples:
+res.success(users, 'Users fetched successfully');
+```
 
-* User Registration
-* Product Creation
-* Order Creation
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Users fetched successfully",
+  "data": [...],
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "requestId": "1705315800000-a1b2c3d4e"
+}
+```
 
----
+### Custom Status Code
 
-## Syntax
+You can override the default 200 status code:
 
 ```js
-response.created(
-  res,
-  data,
-  message
-);
+res.success(data, 'Operation completed', 202);
 ```
 
+**Status Code:** `202 Accepted`
+
 ---
 
-## Example
+## created()
+
+Use this method after successfully creating a new resource.
+
+### Common Use Cases
+
+- User registration
+- Creating a new post/article
+- Adding a new product
+- Creating a new order
+
+### Using Middleware (Recommended)
 
 ```js
-app.post("/users", (req, res) => {
-  const user = {
-    id: 1,
-    name: "John"
-  };
+app.use(response.middleware());
 
-  response.created(
-    res,
-    user,
-    "User created successfully"
-  );
+app.post('/users', response.asyncHandler(async (req, res) => {
+  const user = await User.create({
+    name: req.body.name,
+    email: req.body.email,
+  });
+
+  res.created(user, 'User created successfully');
+}));
+```
+
+### Using Direct API
+
+```js
+app.post('/users', async (req, res) => {
+  const user = await User.create(req.body);
+  
+  response.created(res, user, 'User created successfully');
 });
 ```
 
----
+### Syntax
+
+**Middleware API:**
+```js
+res.created(data, message)
+```
 
-## Output
+**Direct API:**
+```js
+response.created(res, data, message)
+```
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `data` | any | No | `null` | Created resource data |
+| `message` | string | No | `'Created Successfully'` | Success message |
+
+### Response Structure
 
 ```json
 {
@@ -107,27 +183,216 @@ app.post("/users", (req, res) => {
   "message": "User created successfully",
   "data": {
     "id": 1,
-    "name": "John"
+    "name": "John Doe",
+    "email": "john@example.com"
   }
 }
 ```
 
+**Status Code:** `201 Created`
+
+---
+
+## Examples
+
+### Example 1: Fetching User Profile
+
+```js
+app.get('/profile', response.asyncHandler(async (req, res) => {
+  const user = await User.findById(req.user.id);
+  
+  res.success(user, 'Profile fetched successfully');
+}));
+```
+
+### Example 2: Creating a Blog Post
+
+```js
+app.post('/posts', response.asyncHandler(async (req, res) => {
+  const { title, content } = req.body;
+  
+  const post = await Post.create({
+    title,
+    content,
+    author: req.user.id,
+  });
+  
+  res.created(post, 'Post created successfully');
+}));
+```
+
+### Example 3: Updating a Resource
+
+```js
+app.put('/users/:id', response.asyncHandler(async (req, res) => {
+  const user = await User.findByIdAndUpdate(
+    req.params.id,
+    req.body,
+    { new: true }
+  );
+  
+  res.success(user, 'User updated successfully');
+}));
+```
+
+### Example 4: Success Without Data
+
+```js
+app.post('/logout', (req, res) => {
+  req.session.destroy();
+  
+  res.success(null, 'Logged out successfully');
+});
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Logged out successfully",
+  "data": null
+}
+```
+
+### Example 5: Custom Response Keys
+
+```js
+response.configure({
+  successKey: 'status',
+  dataKey: 'result',
+  messageKey: 'msg',
+});
+
+res.success({ count: 10 }, 'Data retrieved');
+```
+
+**Response:**
+```json
+{
+  "status": true,
+  "msg": "Data retrieved",
+  "result": { "count": 10 }
+}
+```
+
 ---
 
-## Status Code
+## Best Practices
 
-```http
-201 Created
+### ✅ Do's
+
+- Use `success()` for GET requests and general operations
+- Use `created()` for POST requests that create resources
+- Provide meaningful success messages
+- Use consistent message patterns across your API
+- Include relevant data in the response
+
+```js
+// ✅ Good
+res.success(user, 'User fetched successfully');
+res.created(post, 'Post created successfully');
+```
+
+### ❌ Don'ts
+
+- Don't use `success()` after creating resources (use `created()`)
+- Don't send empty or generic messages
+- Don't include sensitive data in responses
+- Don't manually write JSON if using Response Kit
+
+```js
+// ❌ Bad
+response.success(res, user, ''); // Empty message
+res.success({ password: 'secret123' }); // Sensitive data
+res.json({ success: true, data: user }); // Manual JSON
 ```
 
 ---
 
-# Best Practices
+## TypeScript
 
-✅ Use success() for fetching data
+Response Kit includes full TypeScript support:
 
-✅ Use created() for creating resources
+```typescript
+import response, { ExtendedResponse } from 'response-kit';
+import { Request } from 'express';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+app.get('/users/:id', async (req: Request, res: ExtendedResponse) => {
+  const user: User = await User.findById(req.params.id);
+  
+  res.success(user, 'User fetched successfully');
+});
+```
+
+---
+
+## Advanced Usage
+
+### Conditional Success Responses
+
+```js
+app.get('/search', response.asyncHandler(async (req, res) => {
+  const results = await searchDatabase(req.query.q);
+  
+  if (results.length === 0) {
+    return res.success([], 'No results found');
+  }
+  
+  res.success(results, `Found ${results.length} results`);
+}));
+```
+
+### Success with Additional Metadata
+
+```js
+response.configure({
+  includeMeta: true,
+});
+
+res.success(users, 'Users fetched');
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Users fetched",
+  "data": [...],
+  "meta": {
+    "method": "GET",
+    "path": "/users"
+  }
+}
+```
+
+### Nested Data Structures
+
+```js
+app.get('/dashboard', response.asyncHandler(async (req, res) => {
+  const data = {
+    stats: {
+      users: 150,
+      posts: 320,
+      comments: 1240
+    },
+    recentActivity: [...],
+    notifications: [...]
+  };
+  
+  res.success(data, 'Dashboard data fetched');
+}));
+```
+
+---
 
-❌ Don't use success() after creating resources
+## Related
 
-❌ Don't manually write JSON responses if using API Response Kit
+- [Error Responses](./error-response.md)
+- [Pagination](./pagination.md)
+- [Getting Started](./getting-started.md)

package/index.d.ts

@@ -1,56 +1,158 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+
+/**
+ * Configuration Options
+ */
+export interface ResponseConfig {
+  successKey?: string;
+  dataKey?: string;
+  messageKey?: string;
+  errorKey?: string;
+  includeTimestamp?: boolean;
+  includeRequestId?: boolean;
+  includeMeta?: boolean;
+  timestampKey?: string;
+  requestIdKey?: string;
+  metaKey?: string;
+}
+
+/**
+ * Extended Express Response with response helpers
+ */
+export interface ExtendedResponse extends Response {
+  success(data?: any, message?: string, statusCode?: number): Response;
+  created(data?: any, message?: string): Response;
+  badRequest(message?: string): Response;
+  unauthorized(message?: string): Response;
+  forbidden(message?: string): Response;
+  notFound(message?: string): Response;
+  conflict(message?: string): Response;
+  internalError(message?: string): Response;
+  validationError(errors?: object, message?: string): Response;
+  paginate(data: any[], page: number, limit: number, total: number): Response;
+}
+
+/**
+ * V1 API - Backward Compatible Functions
+ */
 export function success(
-  res: any,
+  res: Response,
   data?: any,
   message?: string,
   statusCode?: number
-): any;
+): Response;
 
 export function created(
-  res: any,
+  res: Response,
   data?: any,
   message?: string
-): any;
+): Response;
 
 export function badRequest(
-  res: any,
+  res: Response,
   message?: string
-): any;
+): Response;
 
 export function unauthorized(
-  res: any,
+  res: Response,
   message?: string
-): any;
+): Response;
 
 export function forbidden(
-  res: any,
+  res: Response,
   message?: string
-): any;
+): Response;
 
 export function notFound(
-  res: any,
+  res: Response,
   message?: string
-): any;
+): Response;
 
 export function conflict(
-  res: any,
+  res: Response,
   message?: string
-): any;
+): Response;
 
 export function internalError(
-  res: any,
+  res: Response,
   message?: string
-): any;
+): Response;
 
 export function validationError(
-  res: any,
+  res: Response,
   errors?: object,
   message?: string
-): any;
+): Response;
 
 export function paginate(
-  res: any,
+  res: Response,
   data: any[],
   page: number,
   limit: number,
   total: number
-): any;
+): Response;
+
+/**
+ * V2 API - New Features
+ */
+
+/**
+ * Configure global response settings
+ */
+export function configure(options: ResponseConfig): void;
+
+/**
+ * Get current configuration
+ */
+export function getConfig(): ResponseConfig;
+
+/**
+ * Reset configuration to defaults
+ */
+export function resetConfig(): void;
+
+/**
+ * Express middleware that attaches response helpers to res object
+ */
+export function middleware(): (
+  req: Request,
+  res: Response,
+  next: NextFunction
+) => void;
+
+/**
+ * Async handler wrapper for Express routes
+ */
+export function asyncHandler<T = any>(
+  fn: (
+    req: Request,
+    res: ExtendedResponse,
+    next: NextFunction
+  ) => Promise<T>
+): RequestHandler;
+
+/**
+ * Default export with all functions
+ */
+declare const response: {
+  // V1 API
+  success: typeof success;
+  created: typeof created;
+  badRequest: typeof badRequest;
+  unauthorized: typeof unauthorized;
+  forbidden: typeof forbidden;
+  notFound: typeof notFound;
+  conflict: typeof conflict;
+  internalError: typeof internalError;
+  validationError: typeof validationError;
+  paginate: typeof paginate;
+  
+  // V2 API
+  configure: typeof configure;
+  getConfig: typeof getConfig;
+  resetConfig: typeof resetConfig;
+  middleware: typeof middleware;
+  asyncHandler: typeof asyncHandler;
+};
+
+export default response;