#findPage method detailed documentation

async findPage(options = {})

{
  items: [
    { /* Document data 1 */ },
    { /* Document data 2 */ },
    // ...
  ],
  pageInfo: {
    hasNext: true,        // Is there a next page?
    hasPrev: false,       // Is there a previous page?
    startCursor: "...",   // Starting cursor (for before paging)
    endCursor: "...",     // end cursor (for after paging)
    currentPage: 1        // Current page number (only exists when using the page parameter)
  },
  totals: {  // Only present if totals is configured
    mode: "sync",         // Statistics mode
    total: 1000,          // Total number of records
    totalPages: 100,      // Total pages
    ts: 1234567890,       // Statistics timestamp
    token: "...",         // Query flag in async mode
    error: "..."          // Error message when statistics fails (optional)
  },
  meta: {  // Only exists when meta: true
    op: "findPage",
    durationMs: 123,
    cacheHit: false
  }
}

const stream = await collection('users').findPage({
  query: { status: 'active' },
  sort: { createdAt: -1 },
  limit: 100,
  stream: true,
  batchSize: 100  // It is recommended to set the appropriate batch size
});

stream.on('data', (doc) => {
  console.log(doc);
});

stream.on('end', () => {
  console.log('Stream ended');
});

stream.on('error', (err) => {
  console.error('Stream error:', err);
});

// Get the first page
const page1 = await collection('orders').findPage({
  query: { status: 'paid' },
  sort: { createdAt: -1 },
  limit: 20
});

console.log('data:', page1.items);
console.log('There is next page:', page1.pageInfo.hasNext);

// Get next page
const page2 = await collection('orders').findPage({
  query: { status: 'paid' },
  sort: { createdAt: -1 },
  limit: 20,
  after: page1.pageInfo.endCursor
});

// Get previous page
const page0 = await collection('orders').findPage({
  query: { status: 'paid' },
  sort: { createdAt: -1 },
  limit: 20,
  before: page2.pageInfo.startCursor
});

// Use bookmark mechanism to jump pages
const page5 = await collection('products').findPage({
  query: { category: 'electronics' },
  sort: { price: 1 },
  limit: 50,
  page: 5,
  jump: {
    step: 10,      // Save bookmarks every 10 pages
    maxHops: 20    // Jump up to 20 times in a row
  }
});

console.log(`No.${page5.pageInfo.currentPage} page data:`, page5.items);

// Use offset to jump pages (small data volume)
const page3 = await collection('products').findPage({
  query: { category: 'books' },
  sort: { title: 1 },
  limit: 50,
  page: 3,
  offsetJump: {
    enable: true,
    maxSkip: 10000
  }
});

// Home page streaming query
const stream1 = await collection('logs').findPage({
  query: { level: 'error' },
  sort: { timestamp: -1 },
  limit: 1000,
  stream: true,
  batchSize: 100
});

let count = 0;
stream1.on('data', (doc) => {
  count++;
  processLog(doc);
});

stream1.on('end', () => {
  console.log(`Processed${count} logs`);
});

stream1.on('error', (err) => {
  console.error('Stream processing error:', err);
});

// Streaming queries using cursors
const firstPage = await collection('logs').findPage({
  query: { level: 'error' },
  sort: { timestamp: -1 },
  limit: 100
});

const stream2 = await collection('logs').findPage({
  query: { level: 'error' },
  sort: { timestamp: -1 },
  limit: 1000,
  after: firstPage.pageInfo.endCursor,
  stream: true,
  batchSize: 100
});

// Get the total number of synchronization
const pageWithTotal = await collection('users').findPage({
  query: { active: true },
  sort: { _id: 1 },
  limit: 20,
  totals: {
    mode: 'sync',
    maxTimeMS: 5000,
    hint: { active: 1 }  // Using index optimization statistics
  }
});

console.log(`total${pageWithTotal.totals.total} records`);
console.log(`common${pageWithTotal.totals.totalPages} Page`);

// Asynchronously obtain the total number (token returned for the first time)
const page1 = await collection('users').findPage({
  query: { active: true },
  sort: { _id: 1 },
  limit: 20,
  totals: { mode: 'async' }
});

if (page1.totals.total === null) {
  console.log('In total calculation, token:', page1.totals.token);

  // Query again later to get results
  setTimeout(async () => {
    const page1Again = await collection('users').findPage({
      query: { active: true },
      sort: { _id: 1 },
      limit: 20,
      totals: { mode: 'async' }
    });

    if (page1Again.totals.total !== null) {
      console.log(`total:${page1Again.totals.total}`);
    } else {
      console.log('Statistics are still in progress...');
    }
  }, 1000);
}

// Basic execution plan (queryPlanner mode)
const explainResult = await collection('orders').findPage({
  query: { status: 'paid' },
  sort: { createdAt: -1 },
  limit: 20,
  explain: true  // or 'queryPlanner'
});

console.log('query plan:', JSON.stringify(explainResult, null, 2));
console.log('index used:', explainResult.queryPlanner?.winningPlan);

// Get detailed execution statistics (executionStats mode)
const statsResult = await collection('orders').findPage({
  query: { status: 'paid', amount: { $gt: 1000 } },
  sort: { createdAt: -1 },
  limit: 50,
  hint: { status: 1, createdAt: -1 },
  explain: 'executionStats'
});

console.log('Execution statistics:');
console.log('  - Number of scanned documents:', statsResult.executionStats.totalDocsExamined);
console.log('  - Return the number of documents:', statsResult.executionStats.nReturned);
console.log('  - Execution time:', statsResult.executionStats.executionTimeMillis, 'ms');
console.log('  - Index usage:', statsResult.executionStats.executionStages);

// Analyze all alternative plans (allPlansExecution mode)
const allPlansResult = await collection('products').findPage({
  query: { category: 'electronics', price: { $lt: 500 } },
  sort: { price: 1 },
  limit: 30,
  explain: 'allPlansExecution'
});

console.log('All alternative query plans:', allPlansResult.executionStats.allPlansExecution);

// Explain combined with cursor paging
const cursorExplain = await collection('orders').findPage({
  query: { status: 'completed' },
  sort: { completedAt: -1 },
  limit: 20,
  after: 'eyJzIjp7ImNvbXBsZXRlZEF0IjotMSwiX2lkIjoxfSwiYSI6eyJjb21wbGV0ZWRBdCI6eyIkZGF0ZSI6IjIwMjUtMDEtMTVUMTA6MDA6MDAuMDAwWiJ9LCJfaWQiOiI2Nzg5YWJjZDEyMzQ1Njc4OTBhYmNkZWYifX0=',
  explain: 'executionStats'
});

console.log('Cursor paging execution plan:', cursorExplain.executionStats);

try {
  const result = await collection('orders').findPage({
    query: { status: 'paid' },
    sort: { createdAt: -1 },
    limit: 50,
    page: 1000,
    jump: { maxHops: 10 }
  });
} catch (error) {
  if (error.code === 'JUMP_TOO_FAR') {
    console.error('Page jump distance is too far:', error.details);
    // Solution: Increase maxHops or use offsetJump
    const result = await collection('orders').findPage({
      query: { status: 'paid' },
      sort: { createdAt: -1 },
      limit: 50,
      page: 1000,
      jump: { maxHops: 50 }  // increase limit
    });
  } else if (error.code === 'VALIDATION_ERROR') {
    console.error('Parameter error:', error.details);
  } else {
    console.error('Other errors:', error);
  }
}

// Create composite indexes for common queries
await collection('orders').createIndex({ status: 1, createdAt: -1 });

// Use hint in findPage to specify the index
const result = await collection('orders').findPage({
  query: { status: 'paid' },
  sort: { createdAt: -1 },
  limit: 20,
  hint: { status: 1, createdAt: -1 }
});

// Instance-level configuration bookmarks and caching
const msq = new MonSQLize({
  type: 'mongodb',
  databaseName: 'mydb',
  config: { uri: 'mongodb://localhost:27017' },
  bookmarks: {
    step: 10,           // Save bookmarks every 10 pages
    maxHops: 20,        // Jump up to 20 times in a row
    ttlMs: 6 * 3600000, // Bookmark cache 6 hours
    maxPages: 10000     // Cache up to 10,000 pages of bookmarks
  },
  cache: {
    maxEntries: 100000, // Maximum number of cache entries
    enableStats: true   // Enable statistics
  }
});

// Enable caching at query level
const result = await collection('products').findPage({
  query: { category: 'electronics' },
  sort: { price: 1 },
  limit: 20,
  cache: 60000  // Cache for 1 minute
});

// Bad: tens of millions of data use sync mode
const result = await collection('logs').findPage({
  query: { level: 'error' },
  sort: { timestamp: -1 },
  limit: 50,
  totals: { mode: 'sync' }  // It may take several seconds or even time out
});

// Small data size (< 100,000) - use sync mode
const smallResult = await collection('categories').findPage({
  query: { active: true },
  sort: { name: 1 },
  limit: 30,
  totals: {
    mode: 'sync',
    maxTimeMS: 2000,
    hint: { active: 1 }  // Using indexes to speed up statistics
  }
});

// Large data volumes - using async mode
async function getPaginatedDataWithTotal(query, page) {
  const result = await collection('orders').findPage({
    query,
    sort: { createdAt: -1 },
    limit: 50,
    page,
    totals: {
      mode: 'async',
      maxTimeMS: 5000,
      ttlMs: 600000  // Caching for 10 minutes
    }
  });

  // First request: total is null, return token
  if (result.totals && result.totals.total === null) {
    console.log('The total is being calculated...', result.totals.token);
  } else if (result.totals && result.totals.total !== null) {
    console.log(`common${result.totals.total} strip,${result.totals.totalPages} Page`);
  }

  return result;
}

// Scenarios where totals are not required - no statistics (best performance)
const noTotalResult = await collection('feeds').findPage({
  query: { userId: currentUserId },
  sort: { createdAt: -1 },
  limit: 20,
  after: lastCursor
  // Without setting totals, use hasNext to determine whether there is more data.
});

console.log('and more:', noTotalResult.pageInfo.hasNext);

// 1. Set appropriate batchSize
const stream1 = await collection('orders').findPage({
  query: { year: 2024 },
  sort: { createdAt: 1 },
  limit: 1000000,
  stream: true,
  batchSize: 1000,  // 1000 items per batch
  allowDiskUse: true  // Large data volumes allow disk usage
});

let processedCount = 0;
stream1.on('data', (doc) => {
  // Only process the current document, no accumulation
  processOrder(doc);
  processedCount++;

  if (processedCount % 10000 === 0) {
    console.log(`Processed${processedCount} orders`);
  }
});

stream1.on('end', () => {
  console.log(`Processing completed! total: ${processedCount}`);
});

// 2. Export large amounts of data to files
const fs = require('fs');
const { Transform } = require('stream');

async function exportToCSV() {
  const stream = await collection('users').findPage({
    query: { registered: true },
    sort: { registeredAt: 1 },
    limit: 500000,
    stream: true,
    batchSize: 1000,
    pipeline: [
      { $project: { email: 1, name: 1, registeredAt: 1 } }
    ]
  });

  const csvTransform = new Transform({
    objectMode: true,
    transform(doc, encoding, callback) {
      const row = `${doc._id},${doc.email},${doc.name},${doc.registeredAt}\n`;
      callback(null, row);
    }
  });

  const writeStream = fs.createWriteStream('users_export.csv');
  writeStream.write('id,email,name,registeredAt\n');

  stream.pipe(csvTransform).pipe(writeStream);

  await new Promise((resolve, reject) => {
    writeStream.on('finish', resolve);
    writeStream.on('error', reject);
  });

  console.log('Export completed');
}

// Bad: Jump to page 500 but the step size is too big
const result = await collection('products').findPage({
  query: { category: 'books' },
  sort: { publishDate: -1 },
  limit: 50,
  page: 500,
  jump: {
    step: 100,  // Step size too large, page 500 has no bookmarks
    maxHops: 10  // The limit is too small to reach
  }
});
// May throw JUMP_TOO_FAR error

// 1. Frequent page jump scenarios - dense bookmarks
const result1 = await collection('products').findPage({
  query: { category: 'books' },
  sort: { publishDate: -1 },
  limit: 50,
  page: 500,
  jump: {
    step: 5,       // Save bookmarks every 5 pages
    maxHops: 50,   // 50 jumps allowed
    ttlMs: 12 * 3600000  // Cached for 12 hours
  }
});

// 2. Small amount of data - use offset to jump pages
const result2 = await collection('categories').findPage({
  query: { active: true },
  sort: { name: 1 },
  limit: 20,
  page: 15,
  offsetJump: {
    enable: true,
    maxSkip: 10000  // The amount of data is less than 10,000
  }
});

// 3. Detect page jump errors and degrade them
async function robustPagination(page) {
  try {
    return await collection('products').findPage({
      query: { inStock: true },
      sort: { updatedAt: -1 },
      limit: 50,
      page,
      jump: { step: 10, maxHops: 20 }
    });
  } catch (error) {
    if (error.code === 'JUMP_TOO_FAR') {
      console.log('The page jump distance is too far, try using offset mode');
      return await collection('products').findPage({
        query: { inStock: true },
        sort: { updatedAt: -1 },
        limit: 50,
        page,
        offsetJump: { enable: true, maxSkip: 100000 }
      });
    }
    throw error;
  }
}

// ❌ Error: cannot be used simultaneously
await collection('orders').findPage({
  page: 5,
  after: 'cursor123'  // mistake!
});

// ✅ Correct: Select a mode
await collection('orders').findPage({
  page: 5  // Page jump mode
});
// or
await collection('orders').findPage({
  after: 'cursor123'  // Cursor paging
});

// First page
const page1 = await collection('orders').findPage({
  query: { status: 'paid' },
  sort: { createdAt: -1 },
  limit: 20
});

// Next page
const page2 = await collection('orders').findPage({
  query: { status: 'paid' },
  sort: { createdAt: -1 },
  limit: 20,
  after: page1.pageInfo.endCursor
});

// Return to previous page
const backToPage1 = await collection('orders').findPage({
  query: { status: 'paid' },
  sort: { createdAt: -1 },
  limit: 20,
  before: page2.pageInfo.startCursor  // Use before + startCursor
});

// Solution: Get the total number first, then stream it
const firstPage = await collection('logs').findPage({
  query: { level: 'error' },
  sort: { timestamp: -1 },
  limit: 100,
  totals: { mode: 'sync' }
});

console.log(`common${firstPage.totals.total} records`);

// Then use streaming to process all the data
const stream = await collection('logs').findPage({
  query: { level: 'error' },
  sort: { timestamp: -1 },
  limit: firstPage.totals.total,
  stream: true,
  batchSize: 1000
});

const result = await collection('products').findPage({
  query: { category: 'books' },
  sort: { price: 1 },
  limit: 50,
  page: 10
});

if (!result.pageInfo.hasNext) {
  console.log('Already the last page');
} else {
  console.log('There is more data');
}

let cursor = null;
let pageNum = 1;

while (true) {
  const result = await collection('orders').findPage({
    query: { status: 'paid' },
    sort: { createdAt: -1 },
    limit: 100,
    after: cursor
  });

  console.log(`No.${pageNum} Page: ${result.items.length} strip`);

  if (!result.pageInfo.hasNext) {
    console.log('All data processed');
    break;
  }

  cursor = result.pageInfo.endCursor;
  pageNum++;
}

const result = await collection('products').findPage({
  query: { category: 'electronics' },
  sort: { price: 1 },
  limit: 50,
  page: 200,
  jump: {
    step: 10,
    maxHops: 50  // increase to 50
  }
});

const result = await collection('products').findPage({
  query: { category: 'electronics' },
  sort: { price: 1 },
  limit: 50,
  page: 200,
  jump: {
    step: 5,  // Save bookmarks every 5 pages
    maxHops: 20
  }
});

try {
  const result = await collection('products').findPage({
    query: { category: 'electronics' },
    sort: { price: 1 },
    limit: 50,
    page: 200,
    jump: { step: 10, maxHops: 20 }
  });
} catch (error) {
  if (error.code === 'JUMP_TOO_FAR') {
    // Downgrade to offset mode
    const result = await collection('products').findPage({
      query: { category: 'electronics' },
      sort: { price: 1 },
      limit: 50,
      page: 200,
      offsetJump: { enable: true, maxSkip: 100000 }
    });
  }
}

const result = await collection('orders').findPage({
  query: { year: 2024 },
  sort: { createdAt: -1 },
  limit: 50,
  totals: {
    mode: 'async',
    ttlMs: 1800000,  // Caching for 30 minutes
    maxTimeMS: 10000
  }
});

// Create index
await collection('orders').createIndex({ year: 1 });

// Use hint to specify index
const result = await collection('orders').findPage({
  query: { year: 2024 },
  sort: { createdAt: -1 },
  limit: 50,
  totals: {
    mode: 'sync',
    hint: { year: 1 },  // Speed ​​up using indexes
    maxTimeMS: 3000
  }
});

// Home page query: get total number
const firstPageResult = await collection('products').findPage({
  query: { inStock: true },
  sort: { updatedAt: -1 },
  limit: 50,
  page: 1,
  totals: { mode: 'async' }
});

// Subsequent pages: No total count
const otherPageResult = await collection('products').findPage({
  query: { inStock: true },
  sort: { updatedAt: -1 },
  limit: 50,
  page: 5
  // Do not set totals to save performance
});

// explain mode: only returns the execution plan
const explainResult = await collection('orders').findPage({
  query: { status: 'paid' },
  sort: { createdAt: -1 },
  limit: 20,
  explain: 'executionStats'
});

console.log(explainResult);
// Output: { queryPlanner: {...}, executionStats: {...} }
// There are no items, pageInfo and other fields

// Normal query mode: return data
const dataResult = await collection('orders').findPage({
  query: { status: 'paid' },
  sort: { createdAt: -1 },
  limit: 20
});

console.log(dataResult);
// Output: { items: [...], pageInfo: {...} }

// Update data
await collection('products').updateOne(
  { _id: productId },
  { $set: { price: 99 } }
);

// Manual invalidation of cache
await collection('products').invalidate('findPage');

// or invalidate all read caches for this collection
await collection('products').invalidate();

// Both queries use the same cache
const r1 = await collection('products').findPage({
  query: { category: 'books' },
  sort: { price: 1 },
  limit: 20,
  cache: 60000
});

const r2 = await collection('products').findPage({
  query: { category: 'books' },
  sort: { price: 1 },
  limit: 20,
  cache: 60000
});
// r2 will hit r1's cache

// This query will use a different cache (different query)
const r3 = await collection('products').findPage({
  query: { category: 'electronics' },  // different
  sort: { price: 1 },
  limit: 20,
  cache: 60000
});

// The pipeline only processes the 20 returned documents
const result = await collection('orders').findPage({
  query: { status: 'completed' },
  sort: { completedAt: -1 },
  limit: 20,
  page: 1,
  pipeline: [
    {
      $lookup: {
        from: 'users',
        localField: 'userId',
        foreignField: '_id',
        as: 'user'
      }
    },
    { $unwind: '$user' },
    {
      $project: {
        orderId: 1,
        amount: 1,
        'user.name': 1,
        'user.email': 1
      }
    }
  ]
});

// result.items contains 20 pieces of order data processed by the pipeline
// Contains associated user information

import { useState, useEffect } from 'react';

function OrderList() {
  const [orders, setOrders] = useState([]);
  const [cursor, setCursor] = useState(null);
  const [hasMore, setHasMore] = useState(true);
  const [loading, setLoading] = useState(false);

  const loadMore = async () => {
    if (loading || !hasMore) return;

    setLoading(true);
    try {
      const response = await fetch('/api/orders', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          query: { status: 'paid' },
          sort: { createdAt: -1 },
          limit: 20,
          after: cursor
        })
      });

      const result = await response.json();

      setOrders(prev => [...prev, ...result.items]);
      setCursor(result.pageInfo.endCursor);
      setHasMore(result.pageInfo.hasNext);
    } catch (error) {
      console.error('Loading failed:', error);
    } finally {
      setLoading(false);
    }
  };

  // initial load
  useEffect(() => {
    loadMore();
  }, []);

  return (
    <div>
      {orders.map(order => (
        <div key={order._id}>{order.orderId}</div>
      ))}

      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          {loading ? 'loading...' : 'load more'}
        </button>
      )}

      {!hasMore && <div>No more data</div>}
    </div>
  );
}

app.post('/api/orders', async (req, res) => {
  try {
    const { query, sort, limit, after } = req.body;

    const result = await collection('orders').findPage({
      query,
      sort,
      limit: Math.min(limit, 100),  // Limit maximum
      after
    });

    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Scenario 1: Get the user’s first 10 orders -> use find
const recentOrders = await collection('orders').find(
  { userId: '123' },
  {
    sort: { createdAt: -1 },
    limit: 10
  }
);

// Scenario 2: Browse all orders by page -> use findPage
const ordersPage = await collection('orders').findPage({
  query: { userId: '123' },
  sort: { createdAt: -1 },
  limit: 20,
  after: cursor
});

// Scenario 3: Export large amounts of data -> use findPage streaming mode
const exportStream = await collection('orders').findPage({
  query: { year: 2024 },
  sort: { createdAt: 1 },
  limit: 1000000,
  stream: true,
  batchSize: 1000
});