qhttpx 2.0.0 → 2.1.0

package/docs/MIGRATION_1.9_TO_2.0.md

@@ -0,0 +1,495 @@
+# QHttpX Migration Guide: 1.9.4 → 2.0.1
+
+**Updated:** January 21, 2026  
+**Status:** Complete Breaking Changes Guide
+
+---
+
+## Overview
+
+QHttpX 2.0 introduces significant improvements in performance, security, and API consistency. While there are breaking changes, migration is straightforward (30 minutes for most projects).
+
+## Quick Summary of Changes
+
+| Aspect | 1.9.4 | 2.0+ | Migration |
+|--------|-------|------|-----------|
+| Response handling | `return {}` (implicit) | `json({}, 200)` (explicit) | Update all route handlers |
+| Server startup | `app.listen(port, cb)` | `app.start(port)` (Promise) | Change callback style |
+| Rate limiting | `app.rateLimit('strict')` | `app.security({rateLimit: {...}})` | Update config |
+| Error handling | `throw app.error(401)` | Throw `HttpError` class | Update error creation |
+| Middleware | Basic approach | Lifecycle hooks available | Optional improvements |
+
+---
+
+## Step-by-Step Migration
+
+### Step 1: Update Response Handling
+
+**1.9.4 (Implicit JSON):**
+```typescript
+app.get('/users', async ({ json }) => {
+  const users = await getUsers();
+  return { users };  // ❌ Implicit - status always 200
+});
+
+app.post('/users', async ({ body }) => {
+  const user = await createUser(body);
+  return { user, created: true };  // ❌ Always returns 200
+});
+```
+
+**2.0.1 (Explicit JSON):**
+```typescript
+app.get('/users', async ({ json }) => {
+  const users = await getUsers();
+  json({ users }, 200);  // ✅ Explicit status
+});
+
+app.post('/users', async ({ body, json }) => {
+  const user = await createUser(body);
+  json({ user, created: true }, 201);  // ✅ 201 Created
+});
+```
+
+**Migration Command:** Search & Replace (with caution):
+```
+Find:    return \({ (.*) }\);
+Replace: json({ $1 }, 200);
+```
+
+**Then manually verify status codes** - change 201, 400, 404, 401 as needed.
+
+---
+
+### Step 2: Update Server Startup
+
+**1.9.4 (Callback-based):**
+```typescript
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+**2.0.1 (Promise-based):**
+```typescript
+// Option A: Using async/await
+async function start() {
+  await app.start(3000);
+  console.log('Server running on http://localhost:3000');
+}
+start().catch(console.error);
+
+// Option B: Using .then()
+app.start(3000).then(() => {
+  console.log('Server running on http://localhost:3000');
+}).catch(console.error);
+```
+
+**Migration Checklist:**
+- [ ] Remove callback from `app.listen()`
+- [ ] Change to `app.start()`
+- [ ] Wrap in async function or use `.then()`
+- [ ] Add error handling with `.catch()`
+
+---
+
+### Step 3: Update Rate Limiting Configuration
+
+**1.9.4:**
+```typescript
+// String-based configuration
+app.rateLimit('strict');      // Pre-defined
+app.rateLimit('moderate');    // Limited customization
+app.rateLimit('permissive');
+```
+
+**2.0.1:**
+```typescript
+// Granular configuration
+app.security({
+  rateLimit: {
+    windowMs: 15 * 60 * 1000,  // 15 minutes
+    max: 100,                   // 100 requests
+    standardHeaders: true,      // Return RateLimit-* headers
+    legacyHeaders: false,       // Disable X-RateLimit-* headers
+    trustProxy: true,           // Trust X-Forwarded-For
+    keyGenerator: (ctx) => ctx.ip,  // Custom key (IP by default)
+    handler: ({ json }) => json({ error: 'Rate limited' }, 429),
+    skip: (ctx) => ctx.ip === '127.0.0.1',  // Skip localhost
+  }
+});
+```
+
+**Common Presets:**
+```typescript
+// Strict (like 1.9.4)
+app.security({
+  rateLimit: {
+    windowMs: 1 * 60 * 1000,   // 1 minute
+    max: 10,                    // 10 requests
+  }
+});
+
+// Moderate
+app.security({
+  rateLimit: {
+    windowMs: 15 * 60 * 1000,  // 15 minutes
+    max: 100,                   // 100 requests
+  }
+});
+
+// Permissive
+app.security({
+  rateLimit: {
+    windowMs: 60 * 60 * 1000,  // 1 hour
+    max: 1000,                  // 1000 requests
+  }
+});
+```
+
+---
+
+### Step 4: Update Error Handling
+
+**1.9.4:**
+```typescript
+// ❌ This no longer exists
+throw app.error(401, 'Unauthorized');
+throw app.error(404, 'Not found');
+```
+
+**2.0.1 - Option A (Using HttpError):**
+```typescript
+import { HttpError } from 'qhttpx';
+
+app.post('/protected', ({ json, httpError }) => {
+  if (!isAuthorized) {
+    throw httpError(401, 'Unauthorized', { code: 'AUTH_REQUIRED' });
+  }
+  json({ success: true }, 200);
+});
+```
+
+**2.0.1 - Option B (Direct JSON response):**
+```typescript
+app.post('/protected', ({ json }) => {
+  if (!isAuthorized) {
+    json({ error: 'Unauthorized', code: 'AUTH_REQUIRED' }, 401);
+    return;  // Important: return to prevent further execution
+  }
+  json({ success: true }, 200);
+});
+```
+
+**2.0.1 - Option C (Using json() with error):**
+```typescript
+app.post('/protected', async ({ json }) => {
+  try {
+    const result = await protectedOperation();
+    json({ data: result }, 200);
+  } catch (error) {
+    if (error.code === 'AUTH_REQUIRED') {
+      json({ error: error.message, code: error.code }, 401);
+    } else {
+      json({ error: 'Internal server error' }, 500);
+    }
+  }
+});
+```
+
+**Migration Path:**
+1. Replace `app.error()` calls with `httpError()`
+2. Or use `json({ error: msg }, status); return;`
+3. Preferred: Use try-catch with explicit json responses
+
+---
+
+### Step 5: Update Configuration
+
+**1.9.4:**
+```typescript
+app
+  .rateLimit('strict')
+  .production()
+  .compression()
+  .cors();
+```
+
+**2.0.1:**
+```typescript
+app
+  .fusion(true)              // Enable Request Fusion
+  .metrics(true)             // Enable metrics collection
+  .production()              // Enable production optimizations
+  .security({
+    cors: {
+      origin: '*',
+      methods: ['GET', 'POST', 'PUT', 'DELETE'],
+      credentials: false,
+    },
+    rateLimit: {
+      windowMs: 15 * 60 * 1000,
+      max: 100,
+    },
+    headers: true,  // Enable security headers
+  });
+```
+
+---
+
+### Step 6: Update Middleware (Optional)
+
+**1.9.4:**
+```typescript
+app.use(async ({ req, next }) => {
+  console.log(`${req.method} ${req.url}`);
+  if (next) await next();
+});
+```
+
+**2.0.1 - Same approach still works:**
+```typescript
+app.use(async ({ req, next }) => {
+  console.log(`${req.method} ${req.url}`);
+  if (next) await next();
+});
+```
+
+**2.0.1 - New lifecycle hooks (optional):**
+```typescript
+// Before handler
+app.onRequest(({ req }) => {
+  console.log(`→ ${req.method} ${req.url}`);
+});
+
+// After handler  
+app.onResponse(({ req, status }) => {
+  console.log(`← ${req.method} ${req.url} ${status}`);
+});
+
+// On error
+app.onError(({ req, error }) => {
+  console.error(`❌ ${req.method} ${req.url}:`, error.message);
+});
+```
+
+---
+
+## Full Migration Example
+
+### Before (1.9.4):
+
+```typescript
+import { app } from 'qhttpx';
+
+app.rateLimit('strict').production();
+
+app.get('/', ({ json }) => {
+  return { status: 'ok' };
+});
+
+app.post('/users', async ({ body, json }) => {
+  const { email, name } = body as any;
+  
+  if (!email) {
+    throw app.error(400, 'Email required');
+  }
+  
+  const user = await createUser(email, name);
+  return { user };
+});
+
+app.onError(({ error, json }) => {
+  json({ error: error.message }, 500);
+});
+
+app.listen(3000, () => {
+  console.log('Server running');
+});
+```
+
+### After (2.0.1):
+
+```typescript
+import { app, HttpError } from 'qhttpx';
+
+app
+  .production()
+  .security({
+    rateLimit: {
+      windowMs: 1 * 60 * 1000,
+      max: 10,
+    }
+  });
+
+app.get('/', ({ json }) => {
+  json({ status: 'ok' }, 200);
+});
+
+app.post('/users', async ({ body, json, httpError }) => {
+  const { email, name } = body as any;
+  
+  if (!email) {
+    throw httpError(400, 'Email required');
+  }
+  
+  const user = await createUser(email, name);
+  json({ user }, 201);  // 201 Created
+});
+
+app.onError(({ error, json }) => {
+  const status = error instanceof HttpError ? error.status : 500;
+  json({ error: error.message }, status);
+});
+
+app.start(3000).then(() => {
+  console.log('Server running');
+}).catch(console.error);
+```
+
+---
+
+## Automated Migration Script
+
+**Create a script to help with common replacements:**
+
+```bash
+# Find all 'return {' statements in routes
+grep -r "return {" src/routes/ | wc -l
+
+# Find all 'app.error' calls
+grep -r "app\.error" src/ | wc -l
+
+# Find all 'app.listen' calls
+grep -r "app\.listen" src/ | wc -l
+```
+
+---
+
+## Common Pitfalls
+
+### ❌ Pitfall 1: Forgetting to call json()
+
+```typescript
+// WRONG - Returns nothing
+app.get('/users', ({ json }) => {
+  const users = getUsers();
+  // Missing: json(...)
+});
+
+// RIGHT
+app.get('/users', ({ json }) => {
+  const users = getUsers();
+  json({ users }, 200);
+});
+```
+
+### ❌ Pitfall 2: Not returning after json() on error paths
+
+```typescript
+// WRONG - Continues execution
+app.post('/users', ({ json }) => {
+  if (!isValid) {
+    json({ error: 'Invalid' }, 400);
+    // Missing: return
+  }
+  json({ success: true }, 200);  // This still executes!
+});
+
+// RIGHT
+app.post('/users', ({ json }) => {
+  if (!isValid) {
+    json({ error: 'Invalid' }, 400);
+    return;  // Stop execution
+  }
+  json({ success: true }, 200);
+});
+```
+
+### ❌ Pitfall 3: Using old error creation
+
+```typescript
+// WRONG - app.error() doesn't exist
+throw app.error(404, 'Not found');
+
+// RIGHT
+throw httpError(404, 'Not found');
+```
+
+### ❌ Pitfall 4: Async/await with app.start()
+
+```typescript
+// WRONG - Not waiting for start
+app.start(3000);
+console.log('Running');  // May print before server is ready!
+
+// RIGHT
+async function start() {
+  await app.start(3000);
+  console.log('Running');
+}
+start();
+```
+
+---
+
+## Testing After Migration
+
+### Checklist:
+
+- [ ] All routes return via `json()` or `send()`
+- [ ] All error cases return proper status codes
+- [ ] No more `app.error()` calls
+- [ ] `app.listen()` changed to `app.start()`
+- [ ] Error handler updated for new error types
+- [ ] Rate limiting configured explicitly
+- [ ] TypeScript compiles without errors
+- [ ] All endpoints tested in Postman/curl
+
+### Test Command:
+
+```bash
+# Compile TypeScript
+npm run build
+
+# Start server
+npm run start
+
+# Test endpoints
+curl http://localhost:3000/
+curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -d '{"email":"test@example.com","name":"Test"}'
+```
+
+---
+
+## Getting Help
+
+1. **Check examples:** `QHttpX/examples/` directory
+2. **Read API docs:** Check docs/ folder (v2.0.1+)
+3. **GitHub Issues:** Report problems
+4. **Community:** Ask on GitHub Discussions
+
+---
+
+## Version Support
+
+- **v1.9.4:** No longer supported (use 2.0+)
+- **v2.0.0+:** Current stable version
+- **v2.1.0+:** Recommended (better docs, more features)
+
+**Timeline:**
+- v2.0.1: January 2026
+- v2.1.0: February 2026 (docs + features)
+- v3.0.0: Q2 2026 (stable API)
+
+---
+
+## Feedback
+
+Found issues with this guide? Please:
+1. Create a GitHub issue with "[DOCS]" prefix
+2. Include your version number
+3. Describe the unclear part
+4. Suggest improvement
+
+Thank you for helping make QHttpX better! 🙏