Initial commit

2025-11-29 18:22:25 +08:00
commit c3294f28aa
60 changed files with 10297 additions and 0 deletions
--- a/skills/implementing-query-pagination/SKILL.md
+++ b/skills/implementing-query-pagination/SKILL.md
@@ -0,0 +1,213 @@
+---
+name: implementing-query-pagination
+description: Implement cursor-based or offset pagination for Prisma queries. Use for datasets 100k+, APIs with page navigation, or infinite scroll/pagination mentions.
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash
+version: 1.0.0
+---
+
+# QUERIES-pagination: Efficient Pagination Strategies
+
+Teaches correct Prisma 6 pagination patterns with guidance on cursor vs offset trade-offs and performance implications.
+
+<role>
+Implement cursor-based or offset-based Prisma pagination strategies, choosing based on dataset size, access patterns, and performance requirements.
+</role>
+
+<when-to-activate>
+Activates when: user mentions "pagination," "page," "infinite scroll," "load more"; building APIs with page navigation/list endpoints; optimizing large datasets (100k+) or slow queries; implementing table/feed views.
+</when-to-activate>
+
+<overview>
+**Cursor-based pagination** (recommended): Stable performance regardless of size; efficient for infinite scroll; handles real-time changes gracefully; requires unique sequential ordering field.
+
+**Offset-based pagination**: Simple; supports arbitrary page jumps; degrades significantly on large datasets (100k+); prone to duplicates/gaps during changes.
+
+\*\*Core principle: Default to cursor. Use offset only for
+
+small (<10k), static datasets requiring arbitrary page access.\*\*
+</overview>
+
+<workflow>
+## Pagination Strategy Workflow
+
+**Phase 1: Choose Strategy**
+
+- Assess dataset size: <10k (either), 10k–100k (prefer cursor), >100k (require cursor)
+- Assess access: sequential (cursor); arbitrary jumps (offset); infinite scroll (cursor); traditional pagination (cursor)
+- Assess volatility: frequent inserts/deletes (cursor); static (either)
+
+**Phase 2: Implement**
+
+- **Cursor**: select unique ordering field (id, createdAt+id); implement take+cursor+skip; return next cursor; handle edges
+- **Offset**: implement take+skip; calculate total pages if needed; validate bounds; document limitations
+
+**Phase 3: Optimize & Validate**
+
+- Add indexes on ordering field(s); test with realistic dataset size; measure performance; document pagination metadata in response
+  </workflow>
+
+<decision-matrix>
+## Pagination Strategy Decision Matrix
+
+| Criterion                | Cursor            | Offset          | Winner     |
+| ------------------------ | ----------------- | --------------- | ---------- |
+| Dataset > 100k           | Stable O(n)       | O(skip+n)       | **Cursor** |
+| Infinite scroll          | Natural           | Poor            | **Cursor** |
+| Page controls (1,2,3...) | Workaround needed | Natural         | Offset     |
+| Jump to page N           | Not supported     | Supported       | Offset     |
+| Real-time data           | No duplicates     | Duplicates/gaps | **Cursor** |
+| Total count needed       | Extra query       | Same query      | Offset     |
+| Complexity               | Medium            | Low             | Offset     |
+| Mobile feed              | Natural           | Poor            | **Cursor** |
+| Admin table (<10k)       | Overkill          | Simple          | Offset     |
+| Search results           | Good              | Acceptable      | **Cursor** |
+
+**Guidelines:** (1) Default cursor for user-facing lists; (2) Use offset only for small admin tables, total-count requirements, or arbitrary page jumping in internal tools; (3) Never use offset for feeds, timelines, >100k datasets, infinite scroll, real-time data.
+</decision-matrix>
+
+<cursor-pagination>
+## Cursor-Based Pagination
+
+Cursor pagination uses a pointer to a specific record as the starting point for the next page.
+
+### Basic Pattern
+
+```typescript
+async function getPosts(cursor?: string, pageSize: number = 20) {
+  const posts = await prisma.post.findMany({
+    take: pageSize,
+    skip: cursor ? 1 : 0,
+    cursor: cursor ? { id: cursor } : undefined,
+    orderBy: { id: 'asc' },
+  });
+
+  return {
+    data: posts,
+    nextCursor: posts.length === pageSize ? posts[posts.length - 1].id : null,
+  };
+}
+```
+
+### Composite Cursor for Non-Unique Ordering
+
+For non-unique fields (createdAt, score), combine with unique field:
+
+```typescript
+async function getPostsByDate(cursor?: { createdAt: Date; id: string }, pageSize: number = 20) {
+  const posts = await prisma.post.findMany({
+    take: pageSize,
+    skip: cursor ? 1 : 0,
+    cursor: cursor ? { createdAt_id: cursor } : undefined,
+    orderBy: [{ createdAt: 'desc' }, { id: 'asc' }],
+  });
+
+  const lastPost = posts[posts.length - 1];
+  return {
+    data: posts,
+    nextCursor:
+      posts.length === pageSize ? { createdAt: lastPost.createdAt, id: lastPost.id } : null,
+  };
+}
+```
+
+**Schema requirement:**
+
+```prisma
+model Post {
+  id        String   @id @default(cuid())
+  createdAt DateTime @default(now())
+  @@index([createdAt, id])
+}
+```
+
+### Performance
+
+- **Time complexity**: O(n) where n=pageSize (independent of total dataset size); first and subsequent pages identical
+- **Index requirement**: Critical; without index causes full table scan
+- **Memory**: Constant (only pageSize records)
+- **Data changes**: No duplicates/missing records across pages; new records appear in correct position
+
+</cursor-pagination>
+
+<offset-pagination>
+## Offset-Based Pagination
+
+Offset pagination skips a numeric offset of records.
+
+### Basic Pattern
+
+```typescript
+async function getPostsPaged(page: number = 1, pageSize: number = 20) {
+  const skip = (page - 1) * pageSize;
+  const [posts, total] = await Promise.all([
+    prisma.post.findMany({ skip, take: pageSize, orderBy: { createdAt: 'desc' } }),
+    prisma.post.count(),
+  ]);
+
+  return {
+    data: posts,
+    pagination: { page, pageSize, totalPages: Math.ceil(total / pageSize), totalRecords: total },
+  };
+}
+```
+
+### Performance Degradation
+
+**Complexity**: Page 1 O(pageSize); Page N O(N×pageSize)—linear degradation
+
+**Real-world example** (1M records, pageSize 20):
+
+- Page 1 (skip 0): ~5ms
+- Page 1,000 (skip 20k): ~150ms
+- Page 10,000 (skip 200k): ~1,500ms
+- Page 50,000 (skip 1M): ~7,500ms
+
+Database must scan and discard skipped rows despite indexes.
+
+### When Acceptable
+
+Use only when: (1) dataset <10k OR deep pages rare; (2) arbitrary page access required; (3) total count needed; (4) infrequent data changes. Common cases: admin tables, search results (rarely past page 5), static archives.
+</offset-pagination>
+
+<validation>
+## Validation
+
+1. **Index verification**: Schema has index on ordering field(s); for cursor use `@@index([field1, field2])`; run `npx prisma format`
+
+2. **Performance testing**:
+
+   ```typescript
+   console.time('First page');
+   await getPosts(undefined, 20);
+   console.timeEnd('First page');
+   console.time('Page 100');
+   await getPosts(cursor100, 20);
+   console.timeEnd('Page 100');
+   ```
+
+   Cursor: both ~similar (5–50ms); Offset: verify acceptable for your use case
+
+3. **Edge cases**: first page, last page (<pageSize results), empty results, invalid cursor/page, concurrent modifications
+
+4. **API contract**: response includes pagination metadata; nextCursor null when done; hasMore accurate; page numbers
+
+validated (>0); consistent ordering across pages; unique fields in composite cursors
+</validation>
+
+<constraints>
+**MUST**: Index cursor field(s); validate pageSize (max 100); handle empty results; return pagination metadata; use consistent ordering; include unique fields in composite cursors
+
+**SHOULD**: Default cursor for user-facing lists; limit offset to <100k datasets; document pagination strategy; test realistic sizes; consider caching total count
+
+**NEVER**: Use offset for >100k datasets, infinite scroll, feeds/timelines, real-time data; omit indexes; allow unlimited pageSize; use non-unique sole cursor; modify ordering between requests
+</constraints>
+
+---
+
+## References
+
+- [Bidirectional Pagination](./references/bidirectional-pagination.md) — Forward/backward navigation
+- [Complete API Examples](./references/api-implementation-examples.md) — Full endpoint implementations with filtering
+- [Performance Benchmarks](./references/performance-comparison.md) — Detailed performance data, optimization guidance
+- [Common Mistakes](./references/common-mistakes.md) — Anti-patterns and fixes
+- [Data Change Handling](./references/data-change-handling.md) — Managing duplicates and gaps
--- a/skills/implementing-query-pagination/references/api-implementation-examples.md
+++ b/skills/implementing-query-pagination/references/api-implementation-examples.md
@@ -0,0 +1,164 @@
+# Complete API Implementation Examples
+
+## Example 1: API Endpoint with Cursor Pagination
+
+```typescript
+import { prisma } from './prisma-client';
+
+type GetPostsParams = {
+  cursor?: string;
+  limit?: number;
+};
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const cursor = searchParams.get('cursor') || undefined;
+  const limit = Number(searchParams.get('limit')) || 20;
+
+  if (limit > 100) {
+    return Response.json(
+      { error: 'Limit cannot exceed 100' },
+      { status: 400 }
+    );
+  }
+
+  const posts = await prisma.post.findMany({
+    take: limit,
+    skip: cursor ? 1 : 0,
+    cursor: cursor ? { id: cursor } : undefined,
+    orderBy: { createdAt: 'desc' },
+    include: {
+      author: {
+        select: { id: true, name: true, email: true },
+      },
+    },
+  });
+
+  const nextCursor = posts.length === limit
+    ? posts[posts.length - 1].id
+    : null;
+
+  return Response.json({
+    data: posts,
+    nextCursor,
+    hasMore: nextCursor !== null,
+  });
+}
+```
+
+**Client usage:**
+
+```typescript
+async function loadMorePosts() {
+  const response = await fetch(`/api/posts?cursor=${nextCursor}&limit=20`);
+  const { data, nextCursor: newCursor, hasMore } = await response.json();
+
+  setPosts(prev => [...prev, ...data]);
+  setNextCursor(newCursor);
+  setHasMore(hasMore);
+}
+```
+
+## Example 2: Filtered Cursor Pagination
+
+```typescript
+type GetFilteredPostsParams = {
+  cursor?: string;
+  authorId?: string;
+  tag?: string;
+  limit?: number;
+};
+
+async function getFilteredPosts({
+  cursor,
+  authorId,
+  tag,
+  limit = 20,
+}: GetFilteredPostsParams) {
+  const where = {
+    ...(authorId && { authorId }),
+    ...(tag && { tags: { some: { name: tag } } }),
+  };
+
+  const posts = await prisma.post.findMany({
+    where,
+    take: limit,
+    skip: cursor ? 1 : 0,
+    cursor: cursor ? { id: cursor } : undefined,
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return {
+    data: posts,
+    nextCursor: posts.length === limit ? posts[posts.length - 1].id : null,
+  };
+}
+```
+
+**Index requirement:**
+
+```prisma
+model Post {
+  id        String   @id @default(cuid())
+  authorId  String
+  createdAt DateTime @default(now())
+
+  @@index([authorId, createdAt, id])
+}
+```
+
+## Example 3: Small Admin Table with Offset
+
+```typescript
+type GetAdminUsersParams = {
+  page?: number;
+  pageSize?: number;
+  search?: string;
+};
+
+async function getAdminUsers({
+  page = 1,
+  pageSize = 50,
+  search,
+}: GetAdminUsersParams) {
+  const skip = (page - 1) * pageSize;
+
+  const where = search
+    ? {
+        OR: [
+          { email: { contains: search, mode: 'insensitive' as const } },
+          { name: { contains: search, mode: 'insensitive' as const } },
+        ],
+      }
+    : {};
+
+  const [users, total] = await Promise.all([
+    prisma.user.findMany({
+      where,
+      skip,
+      take: pageSize,
+      orderBy: { createdAt: 'desc' },
+      select: {
+        id: true,
+        email: true,
+        name: true,
+        role: true,
+        createdAt: true,
+      },
+    }),
+    prisma.user.count({ where }),
+  ]);
+
+  return {
+    data: users,
+    pagination: {
+      page,
+      pageSize,
+      totalPages: Math.ceil(total / pageSize),
+      totalRecords: total,
+      hasNext: page < Math.ceil(total / pageSize),
+      hasPrev: page > 1,
+    },
+  };
+}
+```
--- a/skills/implementing-query-pagination/references/bidirectional-pagination.md
+++ b/skills/implementing-query-pagination/references/bidirectional-pagination.md
@@ -0,0 +1,35 @@
+# Bidirectional Pagination
+
+Support both forward and backward navigation in cursor-based pagination.
+
+## Pattern
+
+```typescript
+async function getBidirectionalPosts(
+  cursor?: string,
+  direction: 'forward' | 'backward' = 'forward',
+  pageSize: number = 20
+) {
+  const posts = await prisma.post.findMany({
+    take: direction === 'forward' ? pageSize : -pageSize,
+    skip: cursor ? 1 : 0,
+    cursor: cursor ? { id: cursor } : undefined,
+    orderBy: { id: 'asc' },
+  });
+
+  const data = direction === 'backward' ? posts.reverse() : posts;
+
+  return {
+    data,
+    nextCursor: data.length === pageSize ? data[data.length - 1].id : null,
+    prevCursor: data.length > 0 ? data[0].id : null,
+  };
+}
+```
+
+## Key Points
+
+- Use negative `take` value for backward pagination
+- Reverse results when paginating backward
+- Return both `nextCursor` and `prevCursor` for navigation
+- Maintain consistent ordering across directions
--- a/skills/implementing-query-pagination/references/common-mistakes.md
+++ b/skills/implementing-query-pagination/references/common-mistakes.md
@@ -0,0 +1,84 @@
+# Common Pagination Mistakes
+
+## Mistake 1: Using non-unique cursor
+
+**Problem:**
+```typescript
+cursor: cursor ? { createdAt: cursor } : undefined,
+```
+
+Multiple records can have the same `createdAt` value, causing skipped or duplicate records.
+
+**Fix:** Use composite cursor with unique field:
+
+```typescript
+cursor: cursor ? { createdAt_id: cursor } : undefined,
+orderBy: [{ createdAt: 'desc' }, { id: 'asc' }],
+```
+
+## Mistake 2: Missing skip: 1 with cursor
+
+**Problem:**
+```typescript
+findMany({
+  cursor: { id: cursor },
+  take: 20,
+})
+```
+
+The cursor record itself is included in results, causing duplicate on next page.
+
+**Fix:** Skip cursor record itself:
+
+```typescript
+findMany({
+  cursor: { id: cursor },
+  skip: 1,
+  take: 20,
+})
+```
+
+## Mistake 3: Offset pagination on large datasets
+
+**Problem:**
+```typescript
+findMany({
+  skip: page * 1000,
+  take: 1000,
+})
+```
+
+Performance degrades linearly with page number on large datasets.
+
+**Fix:** Use cursor pagination:
+
+```typescript
+findMany({
+  cursor: cursor ? { id: cursor } : undefined,
+  skip: cursor ? 1 : 0,
+  take: 1000,
+})
+```
+
+## Mistake 4: Missing index on cursor field
+
+**Problem:**
+Schema without index causes full table scans:
+
+```prisma
+model Post {
+  id        String   @id
+  createdAt DateTime @default(now())
+}
+```
+
+**Fix:** Add appropriate index:
+
+```prisma
+model Post {
+  id        String   @id
+  createdAt DateTime @default(now())
+
+  @@index([createdAt, id])
+}
+```
--- a/skills/implementing-query-pagination/references/data-change-handling.md
+++ b/skills/implementing-query-pagination/references/data-change-handling.md
@@ -0,0 +1,75 @@
+# Handling Data Changes During Pagination
+
+## The Problem
+
+**Offset Pagination Issue:** Duplicates or missing records when data changes between page loads.
+
+### Example Scenario
+
+1. User loads page 1 (posts 1-20)
+2. New post is inserted at position 1
+3. User loads page 2 (posts 21-40)
+4. **Post 21 appears on both pages** (was post 20, now post 21)
+
+### Why It Happens
+
+Offset pagination uses absolute positions:
+- Page 1: Records at positions 0-19
+- Page 2: Records at positions 20-39
+
+When a record is inserted:
+- Page 1 positions: 0-19 (includes new record at position 0)
+- Page 2 positions: 20-39 (old position 20 is now position 21)
+- **Position 20 was seen on page 1, appears again on page 2**
+
+## Cursor Pagination Solution
+
+Cursor pagination is immune to this problem:
+
+```typescript
+const posts = await prisma.post.findMany({
+  take: 20,
+  skip: cursor ? 1 : 0,
+  cursor: cursor ? { id: cursor } : undefined,
+  orderBy: { createdAt: 'desc' },
+});
+```
+
+**Why it works:**
+- Uses record identity (cursor), not position
+- Always starts from the last seen record
+- New records appear in correct position
+- No duplicates or gaps
+
+## Mitigation for Offset Pagination
+
+If you must use offset pagination:
+
+### Strategy 1: Accept the Limitation
+Document behavior for admin tools where occasional duplicates are acceptable.
+
+### Strategy 2: Timestamp Filtering
+Create stable snapshots using timestamp filtering:
+
+```typescript
+const snapshotTime = new Date();
+
+async function getPage(page: number) {
+  return await prisma.post.findMany({
+    where: {
+      createdAt: { lte: snapshotTime },
+    },
+    skip: page * pageSize,
+    take: pageSize,
+    orderBy: { createdAt: 'desc' },
+  });
+}
+```
+
+**Limitations:**
+- Doesn't show new records during pagination session
+- User must refresh to see new data
+
+### Strategy 3: Switch to Cursor
+
+The best solution is to redesign using cursor pagination.
--- a/skills/implementing-query-pagination/references/performance-comparison.md
+++ b/skills/implementing-query-pagination/references/performance-comparison.md
@@ -0,0 +1,43 @@
+# Performance Comparison
+
+## Benchmark: 500k Posts
+
+**Cursor Pagination (id index):**
+- Page 1: 8ms
+- Page 100: 9ms
+- Page 1000: 10ms
+- Page 10000: 11ms
+- **Stable performance**
+
+**Offset Pagination (createdAt index):**
+- Page 1: 7ms
+- Page 100: 95ms
+- Page 1000: 890ms
+- Page 10000: 8,900ms
+- **Linear degradation**
+
+## Memory Usage
+
+Both approaches:
+- Load only pageSize records into memory
+- Similar memory footprint for same page size
+- Database performs filtering/sorting
+
+## Database Load
+
+**Cursor:**
+- Index scan from cursor position
+- Reads pageSize + 1 rows (for hasMore check)
+
+**Offset:**
+- Index scan from beginning
+- Skips offset rows (database work, not returned)
+- Reads pageSize rows
+
+## Optimization Guidelines
+
+1. **Always add indexes** on ordering fields
+2. **Test with realistic data volumes** before production
+3. **Monitor query performance** in production
+4. **Cache total counts** for offset pagination when possible
+5. **Use cursor by default** unless specific requirements demand offset