Feature/cursor pagination demo

[OsejiFabian]

Changes proposed

What were you told to do?

Add a cursor-pagination demo at app/api/routes-f/paginate-demo/route.ts. Use a bundled dataset of ~500 fake records to demonstrate opaque cursor pagination.

What did you do?

Files Created

• app/api/routes-f/paginate-demo/route.ts - Main API endpoint implementing GET handler with cursor pagination
• app/api/routes-f/paginate-demo/_lib/types.ts - TypeScript interfaces for requests, responses, and data structures
• app/api/routes-f/paginate-demo/_lib/helpers.ts - Helper functions for data generation, cursor encoding/decoding, and pagination logic
• app/api/routes-f/paginate-demo/__tests__/route.test.ts - Comprehensive unit tests covering all functionality
• app/api/routes-f/paginate-demo/test-manual.js - Manual testing script for validation

Implementation Details

• API Endpoint: GET /api/routes-f/paginate-demo?cursor=...&limit=20 returns { data: [...], next_cursor: string|null, has_more: boolean }
• Opaque Cursors: Base64-encoded JSON objects containing created_at and id for client-side opacity
• Dataset: 500 fake records with realistic data (names, emails, categories, statuses, scores)
• Validation: Default limit 20, max 100, proper error handling for invalid cursors and parameters
• Stable Ordering: Composite key ordering (created_at DESC, id ASC) ensures consistent pagination
• Error Handling: 400 status for invalid inputs, 500 for unexpected errors
• Testing: Full unit test coverage including cursor round-trip, edge cases, invalid cursors, and full dataset traversal

Key Features

✅ Cursor is opaque (base64) and round-trips cleanly
✅ No duplicates or skips across pages
✅ Invalid cursors return 400
✅ Tests cover full traversal of dataset
✅ All files scoped to app/api/routes-f/paginate-demo/ as required

[x] - Correct; marked as done
[X] - Correct; marked as done
[ ] - Correct; marked as not done

[] - Not Correct; syntax error
[ x] - Not Correct; space between the brackets
-->

• My code follows the code style of this project.
• This PR does not contain plagiarized content.
• The title and description of the PR is clear and explains the approach.
• I am making a pull request against the main branch (left side).
• My commit messages styles matches our requested structure.
• My code additions will fail neither code linting checks nor unit test.
• I am only making changes to files I was requested to.

Closes #568

[vercel]

Someone is attempting to deploy a commit to the david's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@OsejiFabian Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits