codecruise 0.1.0

package/config/skills/performance/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: performance-patterns
+description: Caching, optimization, scaling - cache strategies, lazy loading, profiling
+keywords: [performance, caching, optimization, lazy load, profiling, bundle size, redis, cdn]
+---
+
+# Performance Patterns
+
+Caching, optimization, and scaling strategies.
+
+## Priority Order
+
+```
+Measure → Profile → Optimize → Measure Again
+```
+
+Never optimize without data. Premature optimization is the root of evil.
+
+## Caching Strategy
+
+### Cache Hierarchy
+
+| Layer | Use Case | TTL | Invalidation |
+|-------|----------|-----|--------------|
+| Browser | Static assets | Long (1 year) | Versioned URLs |
+| CDN | Public pages, images | Medium (1 hour) | Purge API |
+| Redis | Session, hot data | Short (5-15 min) | On write |
+| Memory | Computed values | Very short (1 min) | Process restart |
+
+### Cache-Aside Pattern
+
+```typescript
+async function getUser(id: string): Promise<User> {
+  const cacheKey = `user:${id}`;
+
+  // Try cache first
+  const cached = await redis.get(cacheKey);
+  if (cached) {
+    return JSON.parse(cached);
+  }
+
+  // Cache miss - fetch from DB
+  const user = await db.user.findUnique({ where: { id } });
+
+  if (user) {
+    // Write to cache (non-blocking)
+    redis.setex(cacheKey, 300, JSON.stringify(user)).catch(() => {});
+  }
+
+  return user;
+}
+
+// Invalidate on update
+async function updateUser(id: string, data: UpdateUserInput): Promise<User> {
+  const user = await db.user.update({
+    where: { id },
+    data,
+  });
+
+  // Invalidate cache
+  await redis.del(`user:${id}`);
+
+  return user;
+}
+```
+
+### Stale-While-Revalidate
+
+```typescript
+interface CacheOptions {
+  ttl: number;           // Fresh duration
+  staleTTL: number;      // Stale-but-usable duration
+}
+
+async function getWithSWR<T>(
+  key: string,
+  fetcher: () => Promise<T>,
+  options: CacheOptions
+): Promise<T> {
+  const cached = await redis.get(key);
+
+  if (cached) {
+    const { data, timestamp } = JSON.parse(cached);
+    const age = Date.now() - timestamp;
+
+    // Fresh - return immediately
+    if (age < options.ttl) {
+      return data;
+    }
+
+    // Stale but usable - return and revalidate
+    if (age < options.staleTTL) {
+      // Revalidate in background (non-blocking)
+      fetcher().then((fresh) => {
+        redis.setex(key, options.staleTTL / 1000, JSON.stringify({
+          data: fresh,
+          timestamp: Date.now(),
+        }));
+      }).catch(() => {});
+
+      return data;
+    }
+  }
+
+  // No cache or expired - fetch fresh
+  const fresh = await fetcher();
+
+  await redis.setex(key, options.staleTTL / 1000, JSON.stringify({
+    data: fresh,
+    timestamp: Date.now(),
+  }));
+
+  return fresh;
+}
+```
+
+## Database Optimization
+
+### Query Performance
+
+```typescript
+// ❌ N+1 Query (blocker)
+const users = await db.user.findMany();
+for (const user of users) {
+  const posts = await db.post.findMany({ where: { userId: user.id } });
+}
+
+// ✅ Eager loading
+const users = await db.user.findMany({
+  include: { posts: true },
+});
+
+// ✅ Selective fields
+const users = await db.user.findMany({
+  select: {
+    id: true,
+    email: true,
+    posts: {
+      select: { id: true, title: true },
+      take: 5,
+    },
+  },
+});
+```
+
+### Pagination
+
+```typescript
+// ❌ OFFSET (slow on large datasets)
+const page10 = await db.post.findMany({
+  skip: 900,
+  take: 100,
+});
+
+// ✅ Cursor-based (constant time)
+const page10 = await db.post.findMany({
+  take: 100,
+  cursor: { id: lastSeenId },
+  skip: 1,
+  orderBy: { createdAt: 'desc' },
+});
+```
+
+### Indexing Rules
+
+| Query Pattern | Index |
+|---------------|-------|
+| WHERE column = value | Single column index |
+| WHERE a = x AND b = y | Composite index (a, b) |
+| ORDER BY column | Index on column |
+| Foreign key | Always index |
+| Full-text search | GIN/GIST index |
+
+## API Response Optimization
+
+### Field Selection
+
+```typescript
+// Allow clients to select fields
+// GET /users?fields=id,name,email
+export async function GET(request: NextRequest) {
+  const fields = request.nextUrl.searchParams.get('fields')?.split(',');
+
+  const select = fields?.reduce((acc, field) => {
+    acc[field] = true;
+    return acc;
+  }, {} as Record<string, boolean>);
+
+  const users = await db.user.findMany({
+    select: select || undefined,
+  });
+
+  return NextResponse.json({ data: users });
+}
+```
+
+### Compression
+
+```typescript
+// Next.js config
+module.exports = {
+  compress: true,
+};
+
+// Manual for API routes
+import { gzip } from 'zlib';
+import { promisify } from 'util';
+
+const gzipAsync = promisify(gzip);
+
+export async function GET() {
+  const data = await getLargeDataset();
+  const compressed = await gzipAsync(JSON.stringify(data));
+
+  return new Response(compressed, {
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Encoding': 'gzip',
+    },
+  });
+}
+```
+
+## Frontend Performance
+
+### Code Splitting
+
+```typescript
+// Dynamic imports for heavy components
+import dynamic from 'next/dynamic';
+
+const HeavyChart = dynamic(() => import('@/components/Chart'), {
+  loading: () => <ChartSkeleton />,
+  ssr: false,
+});
+```
+
+### Image Optimization
+
+```typescript
+import Image from 'next/image';
+
+// Always use next/image
+<Image
+  src="/hero.jpg"
+  alt="Hero"
+  width={1200}
+  height={600}
+  priority           // Above the fold
+  placeholder="blur" // Smooth loading
+/>
+```
+
+### Bundle Analysis
+
+```bash
+# Analyze bundle size
+ANALYZE=true pnpm build
+
+# Size limits in package.json
+{
+  "size-limit": [
+    { "path": ".next/static/chunks/*.js", "limit": "200 KB" }
+  ]
+}
+```
+
+## Async Patterns
+
+### Background Jobs
+
+```typescript
+// Don't block response for non-critical work
+export async function POST(request: NextRequest) {
+  const order = await createOrder(request);
+
+  // Non-blocking: queue for later
+  await queue.add('send-confirmation', { orderId: order.id });
+  await queue.add('update-inventory', { items: order.items });
+  await queue.add('notify-warehouse', { orderId: order.id });
+
+  // Return immediately
+  return NextResponse.json({ data: order }, { status: 201 });
+}
+```
+
+### Parallel Fetching
+
+```typescript
+// ❌ Sequential (slow)
+const user = await getUser(id);
+const orders = await getOrders(id);
+const recommendations = await getRecommendations(id);
+
+// ✅ Parallel (fast)
+const [user, orders, recommendations] = await Promise.all([
+  getUser(id),
+  getOrders(id),
+  getRecommendations(id),
+]);
+
+// ✅ With error isolation
+const [user, orders, recommendations] = await Promise.allSettled([
+  getUser(id),
+  getOrders(id),
+  getRecommendations(id),
+]);
+```
+
+## Rate Limiting
+
+```typescript
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '10 s'),
+  analytics: true,
+});
+
+export async function middleware(request: NextRequest) {
+  const ip = request.ip ?? '127.0.0.1';
+  const { success, limit, reset, remaining } = await ratelimit.limit(ip);
+
+  if (!success) {
+    return NextResponse.json(
+      { error: 'Too many requests' },
+      {
+        status: 429,
+        headers: {
+          'X-RateLimit-Limit': limit.toString(),
+          'X-RateLimit-Remaining': remaining.toString(),
+          'X-RateLimit-Reset': reset.toString(),
+        },
+      }
+    );
+  }
+
+  return NextResponse.next();
+}
+```
+
+## Profiling Commands
+
+```bash
+# Node.js profiling
+node --inspect dist/server.js
+# Then open chrome://inspect
+
+# Database query logging
+DATABASE_URL="...?log=query"
+
+# Bundle analysis
+ANALYZE=true next build
+```
+
+## Performance Budgets
+
+| Metric | Target | Maximum |
+|--------|--------|---------|
+| First Contentful Paint | < 1.5s | < 2.5s |
+| Time to Interactive | < 3s | < 5s |
+| API Response (p95) | < 200ms | < 500ms |
+| DB Query (p95) | < 50ms | < 200ms |
+| Bundle Size (JS) | < 150KB | < 300KB |
+
+## Quality Checklist
+
+- [ ] No N+1 queries
+- [ ] Cache strategy for hot data
+- [ ] Cursor pagination for lists
+- [ ] Images optimized (next/image)
+- [ ] Code splitting for heavy components
+- [ ] API responses compressed
+- [ ] Rate limiting in place
+- [ ] Performance budgets defined
+- [ ] Profiling done before optimization