response-kit 1.0.0 → 2.0.0

package/docs/pagination.md

@@ -1,138 +1,603 @@
 # Pagination
 
-Pagination helper provides a standard structure for paginated APIs.
+This document covers pagination support in Response Kit v2.
 
 ---
 
-# Why Pagination?
+## Overview
 
-Imagine you have:
+Response Kit provides a `paginate()` helper for sending paginated responses with metadata. It automatically calculates total pages and includes pagination information in the response.
 
-```text
-10000 Users
-50000 Products
-100000 Orders
+**Available as:**
+- **Middleware API** (v2): `res.paginate(data, page, limit, total)`
+- **Direct API** (v1): `response.paginate(res, data, page, limit, total)`
+
+---
+
+## paginate()
+
+### Using Middleware (Recommended)
+
+```js
+app.use(response.middleware());
+
+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();
+  
+  res.paginate(users, page, limit, total);
+}));
+```
+
+### Using Direct API
+
+```js
+app.get('/users', 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();
+  
+  response.paginate(res, users, page, limit, total);
+});
 ```
 
-Returning everything in one request is inefficient.
+### Syntax
 
-Pagination helps return data in chunks.
+**Middleware API:**
+```js
+res.paginate(data, page, limit, total)
+```
+
+**Direct API:**
+```js
+response.paginate(res, data, page, limit, total)
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `data` | array | Yes | Array of items for current page |
+| `page` | number | Yes | Current page number (1-indexed) |
+| `limit` | number | Yes | Number of items per page |
+| `total` | number | Yes | Total number of items across all pages |
+
+### Response Structure
+
+```json
+{
+  "success": true,
+  "data": [
+    { "id": 1, "name": "John Doe" },
+    { "id": 2, "name": "Jane Smith" }
+  ],
+  "pagination": {
+    "page": 1,
+    "limit": 10,
+    "total": 100,
+    "totalPages": 10
+  }
+}
+```
+
+**Status Code:** `200 OK`
+
+### Pagination Metadata
+
+The `pagination` object includes:
+
+- **`page`**: Current page number
+- **`limit`**: Items per page
+- **`total`**: Total number of items
+- **`totalPages`**: Calculated as `Math.ceil(total / limit)`
 
 ---
 
-# Syntax
+## Complete Examples
+
+### Example 1: Basic Pagination
 
 ```js
-response.paginate(
-  res,
-  data,
-  page,
-  limit,
-  total
-);
+const express = require('express');
+const response = require('response-kit');
+
+const app = express();
+app.use(response.middleware());
+
+app.get('/users', response.asyncHandler(async (req, res) => {
+  // Parse query parameters
+  const page = parseInt(req.query.page) || 1;
+  const limit = parseInt(req.query.limit) || 10;
+  
+  // Fetch paginated data
+  const users = await User.find()
+    .skip((page - 1) * limit)
+    .limit(limit);
+  
+  // Get total count
+  const total = await User.countDocuments();
+  
+  // Send paginated response
+  res.paginate(users, page, limit, total);
+}));
+
+app.listen(3000);
+```
+
+**Request:**
+```
+GET /users?page=2&limit=5
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": [
+    { "id": 6, "name": "User 6" },
+    { "id": 7, "name": "User 7" },
+    { "id": 8, "name": "User 8" },
+    { "id": 9, "name": "User 9" },
+    { "id": 10, "name": "User 10" }
+  ],
+  "pagination": {
+    "page": 2,
+    "limit": 5,
+    "total": 50,
+    "totalPages": 10
+  }
+}
 ```
 
 ---
 
-# Example
+### Example 2: Pagination with Filtering
 
 ```js
-app.get("/users", (req, res) => {
+app.get('/users', response.asyncHandler(async (req, res) => {
+  const page = parseInt(req.query.page) || 1;
+  const limit = parseInt(req.query.limit) || 10;
+  const search = req.query.search || '';
+  
+  // Build query
+  const query = search
+    ? { name: { $regex: search, $options: 'i' } }
+    : {};
+  
+  // Fetch filtered and paginated data
+  const users = await User.find(query)
+    .skip((page - 1) * limit)
+    .limit(limit);
+  
+  // Count filtered results
+  const total = await User.countDocuments(query);
+  
+  res.paginate(users, page, limit, total);
+}));
+```
 
-  const users = [
-    {
-      id: 1,
-      name: "John"
-    },
-    {
-      id: 2,
-      name: "Jane"
-    }
-  ];
-
-  response.paginate(
-    res,
-    users,
-    1,
-    10,
-    100
+**Request:**
+```
+GET /users?page=1&limit=10&search=john
+```
+
+---
+
+### Example 3: Pagination with Sorting
+
+```js
+app.get('/posts', response.asyncHandler(async (req, res) => {
+  const page = parseInt(req.query.page) || 1;
+  const limit = parseInt(req.query.limit) || 10;
+  const sortBy = req.query.sortBy || 'createdAt';
+  const sortOrder = req.query.sortOrder === 'asc' ? 1 : -1;
+  
+  const posts = await Post.find()
+    .sort({ [sortBy]: sortOrder })
+    .skip((page - 1) * limit)
+    .limit(limit)
+    .populate('author', 'name email');
+  
+  const total = await Post.countDocuments();
+  
+  res.paginate(posts, page, limit, total);
+}));
+```
+
+**Request:**
+```
+GET /posts?page=1&limit=20&sortBy=title&sortOrder=asc
+```
+
+---
+
+### Example 4: Advanced Pagination Helper
+
+Create a reusable pagination helper:
+
+```js
+// helpers/pagination.js
+async function paginateModel(Model, page, limit, filter = {}, sort = {}) {
+  const skip = (page - 1) * limit;
+  
+  const [data, total] = await Promise.all([
+    Model.find(filter)
+      .sort(sort)
+      .skip(skip)
+      .limit(limit),
+    Model.countDocuments(filter)
+  ]);
+  
+  return { data, total };
+}
+
+module.exports = { paginateModel };
+```
+
+**Usage:**
+
+```js
+const { paginateModel } = require('./helpers/pagination');
+
+app.get('/users', response.asyncHandler(async (req, res) => {
+  const page = parseInt(req.query.page) || 1;
+  const limit = parseInt(req.query.limit) || 10;
+  
+  const { data, total } = await paginateModel(
+    User,
+    page,
+    limit,
+    { active: true },
+    { createdAt: -1 }
   );
+  
+  res.paginate(data, page, limit, total);
+}));
+```
 
-});
+---
+
+### Example 5: Pagination with Validation
+
+```js
+app.get('/products', response.asyncHandler(async (req, res) => {
+  const page = parseInt(req.query.page) || 1;
+  const limit = parseInt(req.query.limit) || 10;
+  
+  // Validation
+  if (page < 1) {
+    return res.badRequest('Page must be greater than 0');
+  }
+  
+  if (limit < 1 || limit > 100) {
+    return res.badRequest('Limit must be between 1 and 100');
+  }
+  
+  const products = await Product.find()
+    .skip((page - 1) * limit)
+    .limit(limit);
+  
+  const total = await Product.countDocuments();
+  
+  res.paginate(products, page, limit, total);
+}));
 ```
 
 ---
 
-# Output
+### Example 6: Cursor-Based Pagination Alternative
 
+For cursor-based pagination (useful for large datasets):
+
+```js
+app.get('/posts/cursor', response.asyncHandler(async (req, res) => {
+  const limit = parseInt(req.query.limit) || 10;
+  const cursor = req.query.cursor; // Last seen ID
+  
+  const query = cursor ? { _id: { $gt: cursor } } : {};
+  
+  const posts = await Post.find(query)
+    .sort({ _id: 1 })
+    .limit(limit + 1); // Fetch one extra to check if there's a next page
+  
+  const hasMore = posts.length > limit;
+  const data = hasMore ? posts.slice(0, limit) : posts;
+  const nextCursor = hasMore ? data[data.length - 1]._id : null;
+  
+  res.success({
+    data,
+    cursor: {
+      next: nextCursor,
+      hasMore
+    }
+  });
+}));
+```
+
+---
+
+## Pagination Patterns
+
+### Pattern 1: Offset-Based (Default)
+
+```js
+// Using skip and limit
+const skip = (page - 1) * limit;
+const data = await Model.find().skip(skip).limit(limit);
+```
+
+**Pros:**
+- Simple to implement
+- Direct page access
+- Familiar to users
+
+**Cons:**
+- Performance degrades with large offsets
+- Data consistency issues with concurrent updates
+
+---
+
+### Pattern 2: Cursor-Based
+
+```js
+// Using a cursor (last seen ID)
+const data = await Model.find({ _id: { $gt: cursor } })
+  .limit(limit);
+```
+
+**Pros:**
+- Better performance for large datasets
+- Consistent results
+- No skipped/duplicate items
+
+**Cons:**
+- Can't jump to arbitrary pages
+- Requires indexed cursor field
+
+---
+
+## Best Practices
+
+### ✅ Do's
+
+- Validate page and limit parameters
+- Set reasonable default and maximum limits
+- Use efficient database queries (indexes)
+- Count totals efficiently (consider caching for large datasets)
+- Return empty array for out-of-range pages
+
+```js
+// ✅ Good
+const page = Math.max(1, parseInt(req.query.page) || 1);
+const limit = Math.min(100, Math.max(1, parseInt(req.query.limit) || 10));
+
+// Use indexes
+await User.createIndex({ createdAt: -1 });
+
+// Empty result for out-of-range page
+if (page > totalPages) {
+  return res.paginate([], page, limit, total);
+}
+```
+
+### ❌ Don'ts
+
+- Don't allow unlimited page sizes
+- Don't skip validation
+- Don't use pagination for very large datasets without optimization
+- Don't fetch all data and paginate in memory
+
+```js
+// ❌ Bad
+const limit = parseInt(req.query.limit); // No validation!
+
+// ❌ Bad - fetches everything
+const allUsers = await User.find();
+const paginated = allUsers.slice((page - 1) * limit, page * limit);
+```
+
+---
+
+## With Configuration
+
+Pagination respects global configuration:
+
+```js
+response.configure({
+  dataKey: 'items',
+  includeTimestamp: true,
+});
+
+res.paginate(users, 1, 10, 100);
+```
+
+**Response:**
 ```json
 {
   "success": true,
-  "data": [
-    {
-      "id": 1,
-      "name": "John"
-    },
-    {
-      "id": 2,
-      "name": "Jane"
-    }
-  ],
+  "items": [...],
   "pagination": {
     "page": 1,
     "limit": 10,
     "total": 100,
     "totalPages": 10
-  }
+  },
+  "timestamp": "2024-01-15T10:30:00.000Z"
 }
 ```
 
 ---
 
-# Explanation
+## Client-Side Usage
+
+### Using Axios
+
+```js
+async function fetchUsers(page = 1, limit = 10) {
+  const response = await axios.get('/users', {
+    params: { page, limit }
+  });
+  
+  return response.data;
+}
+
+// Usage
+const result = await fetchUsers(2, 20);
+console.log(result.data); // Users array
+console.log(result.pagination.totalPages); // Total pages
+```
+
+### Using Fetch API
+
+```js
+async function fetchUsers(page = 1, limit = 10) {
+  const url = `/users?page=${page}&limit=${limit}`;
+  const response = await fetch(url);
+  return response.json();
+}
+```
 
-| Property   | Description           |
-| ---------- | --------------------- |
-| page       | Current page          |
-| limit      | Items per page        |
-| total      | Total records         |
-| totalPages | Total pages available |
+### React Example
+
+```jsx
+import { useState, useEffect } from 'react';
+
+function UserList() {
+  const [users, setUsers] = useState([]);
+  const [pagination, setPagination] = useState({});
+  const [page, setPage] = useState(1);
+  
+  useEffect(() => {
+    fetchUsers(page).then(result => {
+      setUsers(result.data);
+      setPagination(result.pagination);
+    });
+  }, [page]);
+  
+  return (
+    <div>
+      <ul>
+        {users.map(user => (
+          <li key={user.id}>{user.name}</li>
+        ))}
+      </ul>
+      
+      <div>
+        <button 
+          disabled={page === 1}
+          onClick={() => setPage(page - 1)}
+        >
+          Previous
+        </button>
+        
+        <span>
+          Page {pagination.page} of {pagination.totalPages}
+        </span>
+        
+        <button 
+          disabled={page === pagination.totalPages}
+          onClick={() => setPage(page + 1)}
+        >
+          Next
+        </button>
+      </div>
+    </div>
+  );
+}
+```
 
 ---
 
-# MongoDB Example
+## Performance Optimization
+
+### 1. Use Database Indexes
 
 ```js
-const page = Number(req.query.page) || 1;
-const limit = Number(req.query.limit) || 10;
+// MongoDB
+await User.createIndex({ createdAt: -1 });
+await User.createIndex({ name: 1 });
 
-const skip = (page - 1) * limit;
+// Significantly improves pagination performance
+```
 
-const users = await User.find()
-  .skip(skip)
-  .limit(limit);
+### 2. Cache Total Counts
 
-const total = await User.countDocuments();
+```js
+const cache = new Map();
+
+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);
+  
+  // Cache total count for 5 minutes
+  let total = cache.get('user_count');
+  if (!total) {
+    total = await User.countDocuments();
+    cache.set('user_count', total);
+    setTimeout(() => cache.delete('user_count'), 5 * 60 * 1000);
+  }
+  
+  res.paginate(users, page, limit, total);
+}));
+```
+
+### 3. Use Lean Queries
 
-response.paginate(
-  res,
-  users,
-  page,
-  limit,
-  total
-);
+```js
+// Mongoose - return plain objects instead of documents
+const users = await User.find()
+  .lean() // Faster, less memory
+  .skip((page - 1) * limit)
+  .limit(limit);
 ```
 
 ---
 
-# Best Practices
+## TypeScript
 
-✅ Always return pagination object
+```typescript
+import { ExtendedResponse } from 'response-kit';
+import { Request } from 'express';
 
-✅ Include total count
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
 
-✅ Use page & limit query parameters
+app.get('/users', async (req: Request, res: ExtendedResponse) => {
+  const page = parseInt(req.query.page as string) || 1;
+  const limit = parseInt(req.query.limit as string) || 10;
+  
+  const users: User[] = await User.find()
+    .skip((page - 1) * limit)
+    .limit(limit);
+  
+  const total = await User.countDocuments();
+  
+  res.paginate(users, page, limit, total);
+});
+```
+
+---
 
-✅ Keep response structure consistent
+## Related
 
-This makes frontend pagination implementation much easier.
+- [Success Responses](./success-response.md)
+- [Error Responses](./error-response.md)
+- [Getting Started](./getting-started.md)