Feat/helper paginated list

[Unclebaffa]

Summary

I've successfully implemented the buildListResponse helper for consistent paginated list response envelopes. Here's what was delivered:

✅ Acceptance Criteria Met

1. Returns correct envelope shape with all meta fields

   • ✅ Helper returns { data, meta: { total, hasMore, nextCursor } } structure
   • ✅ All meta fields are properly included in the response

2. nextCursor absent when not provided

   • ✅ When nextCursor is undefined, it's completely omitted from the output (not serialized)
   • ✅ Test: "omits nextCursor from output when undefined" verifies this
   • ✅ Test: "does not serialize nextCursor when not provided" confirms JSON serialization behavior

3. Empty data array returns correct shape

   • ✅ Empty arrays return { data: [], meta: { total: 0, hasMore: false } }
   • ✅ Multiple tests cover empty array scenarios
   • ✅ Test: "returns correct shape for empty data array" validates the structure

📦 Deliverables

1. Helper Implementation (src/utils/list-response.utils.ts)

   • Generic buildListResponse<T>() function
   • TypeScript interfaces: ListResponseMeta and ListResponse<T>
   • Comprehensive JSDoc documentation with examples

2. Comprehensive Unit Tests (src/utils/list-response.utils.test.ts)

   • 20 test cases covering all scenarios:
     • With cursor (cursor pagination)
     • Without cursor (offset pagination)
     • Empty data arrays
     • Type safety
     • Meta field validation
     • Edge cases

3. Documentation (docs/list-response-helper.md)

   • Usage guide with practical examples
   • Migration guide showing before/after patterns
   • Response shape examples
   • Key behaviors explained

The helper is ready to be used across all paginated list endpoints to ensure consistent response envelope shapes!

Closes #508

[drips-wave]

@Unclebaffa 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