qhttpx 2.1.0 → 2.3.1

package/docs/API_REFERENCE.md

@@ -1,749 +0,0 @@
-# QHttpX 2.0.1 API Reference
-
-**Complete Guide to QHttpX Methods and Options**
-
----
-
-## Table of Contents
-
-1. [App Initialization](#app-initialization)
-2. [Route Definitions](#route-definitions)
-3. [Context Methods](#context-methods)
-4. [Configuration](#configuration)
-5. [Error Handling](#error-handling)
-6. [Middleware](#middleware)
-7. [Advanced Features](#advanced-features)
-
----
-
-## App Initialization
-
-### `new QHTTPX(options)`
-
-Creates a new QHttpX application instance.
-
-**Signature:**
-```typescript
-const app = new QHTTPX(options?: QHTTPXOptions);
-```
-
-**Options:**
-```typescript
-interface QHTTPXOptions {
-  // Port configuration (default: 3000)
-  port?: number;
-  
-  // Worker count for clustering (default: CPU cores)
-  workers?: number;
-  
-  // Buffer pool for request/response optimization
-  bufferPool?: BufferPoolConfig;
-  
-  // Request fusion settings (coalesce identical concurrent requests)
-  fusion?: RequestFusionOptions | boolean;
-  
-  // Database manager
-  db?: DatabaseManager;
-  
-  // View engine (for template rendering)
-  views?: ViewEngine;
-  
-  // Validation library (default: simple schema validation)
-  validator?: Validator;
-  
-  // Rate limiting configuration
-  rateLimit?: RateLimitOptions | boolean;
-  
-  // CORS configuration
-  cors?: CorsOptions | boolean;
-  
-  // Compression settings
-  compression?: CompressionOptions | boolean;
-  
-  // Security headers
-  security?: SecurityHeadersOptions | boolean;
-  
-  // Production mode optimizations
-  production?: boolean;
-  
-  // Logging configuration
-  logging?: LoggerOptions;
-  
-  // Enable metrics collection
-  metrics?: boolean;
-  
-  // Custom tracer for observability
-  tracer?: QHTTPXTracer;
-}
-```
-
-**Example:**
-```typescript
-const app = new QHTTPX({
-  port: 3000,
-  workers: 4,
-  production: true,
-  fusion: { maxWait: 10 },
-  metrics: true,
-});
-```
-
----
-
-### `app.start(port?, callback?)`
-
-Starts the HTTP server.
-
-**Signature:**
-```typescript
-start(port?: number, callback?: () => void): Promise<void>;
-```
-
-**Returns:** Promise that resolves when server is listening
-
-**Example:**
-```typescript
-// Using Promise
-app.start(3000).then(() => {
-  console.log('Server running');
-}).catch(console.error);
-
-// Using async/await
-async function start() {
-  await app.start(3000);
-  console.log('Server running');
-}
-start();
-
-// With callback (backward compat)
-app.start(3000, () => {
-  console.log('Server running');
-});
-```
-
----
-
-### Configuration Methods (Fluent API)
-
-All return `this` for chaining.
-
-#### `app.production()`
-Enables production optimizations (compression, caching, etc).
-
-```typescript
-app.production();
-```
-
-#### `app.fusion(enabled?: boolean | options)`
-Enables request fusion (coalesce identical concurrent requests).
-
-```typescript
-app.fusion(true);
-app.fusion({ maxWait: 10, maxSize: 100 });
-```
-
-#### `app.metrics(enabled?: boolean)`
-Enables metrics collection for performance monitoring.
-
-```typescript
-app.metrics(true);
-```
-
-#### `app.security(options)`
-Configures security settings (CORS, rate limiting, headers).
-
-```typescript
-app.security({
-  cors: { origin: '*' },
-  rateLimit: { max: 100, windowMs: 60000 },
-  headers: true,
-});
-```
-
-#### `app.cors(options)`
-Configures CORS.
-
-```typescript
-app.cors({
-  origin: ['http://localhost:3000', 'https://example.com'],
-  methods: ['GET', 'POST'],
-  credentials: true,
-});
-```
-
-#### `app.rateLimit(options)`
-Configures rate limiting.
-
-```typescript
-app.rateLimit({
-  windowMs: 15 * 60 * 1000,  // 15 minutes
-  max: 100,                   // 100 requests
-  keyGenerator: (ctx) => ctx.ip,
-});
-```
-
----
-
-## Route Definitions
-
-### HTTP Method Signatures
-
-```typescript
-// GET request
-app.get(path, handler);
-app.get(path, options, handler);
-
-// POST request
-app.post(path, handler);
-app.post(path, options, handler);
-
-// PUT request
-app.put(path, handler);
-app.put(path, options, handler);
-
-// DELETE request
-app.delete(path, handler);
-app.delete(path, options, handler);
-
-// PATCH request
-app.patch(path, handler);
-app.patch(path, options, handler);
-
-// HEAD request
-app.head(path, handler);
-app.head(path, options, handler);
-
-// OPTIONS request
-app.options(path, handler);
-app.options(path, options, handler);
-```
-
-### Route Handler
-
-```typescript
-type QHTTPXHandler = (ctx: QHTTPXContext) => void | Promise<void>;
-```
-
-The handler receives a `QHTTPXContext` object with all request/response utilities.
-
-### Route Options
-
-```typescript
-interface QHTTPXRouteOptions {
-  // JSON Schema for validation
-  schema?: {
-    body?: any;      // Validate request body
-    params?: any;    // Validate URL parameters
-    query?: any;     // Validate query string
-    headers?: any;   // Validate headers
-    response?: any;  // Document response shape
-  };
-  
-  // Route priority for execution order
-  priority?: 'critical' | 'standard' | 'best-effort';
-  
-  // Pre-built static response (optimization)
-  staticResponse?: any;
-}
-```
-
-### Examples
-
-```typescript
-// Simple GET
-app.get('/', ({ json }) => {
-  json({ status: 'ok' }, 200);
-});
-
-// With URL parameters
-app.get('/users/:id', ({ params, json }) => {
-  const userId = params.id;
-  json({ userId }, 200);
-});
-
-// With query parameters
-app.get('/search', ({ query, json }) => {
-  const q = query.q;  // ?q=hello
-  json({ results: [] }, 200);
-});
-
-// With validation schema
-app.post('/users', 
-  {
-    schema: {
-      body: {
-        type: 'object',
-        required: ['email', 'name'],
-        properties: {
-          email: { type: 'string', format: 'email' },
-          name: { type: 'string', minLength: 2 },
-        }
-      }
-    }
-  },
-  ({ body, json }) => {
-    const { email, name } = body as any;
-    json({ created: true, email, name }, 201);
-  }
-);
-
-// With priority routing
-app.post('/admin/users', 
-  { priority: 'critical' },
-  ({ body, json }) => {
-    json({ admin: true }, 201);
-  }
-);
-```
-
----
-
-## Context Methods
-
-The context object (first parameter to handlers) contains request/response utilities.
-
-### Request Properties
-
-```typescript
-ctx.req: IncomingMessage           // Node HTTP request
-ctx.res: ServerResponse            // Node HTTP response
-ctx.method: HTTPMethod             // GET, POST, PUT, DELETE, etc
-ctx.url: URL                       // Parsed URL object
-ctx.path: string                   // URL path (/users/123)
-ctx.headers: IncomingHttpHeaders   // Request headers
-ctx.ip: string                     // Client IP address
-ctx.params: Record<string, string> // URL parameters ({id: '123'})
-ctx.query: Record<string, any>     // Query parameters ({sort: 'asc'})
-ctx.body: unknown                  // Parsed request body
-ctx.cookies: Record<string, string>// Cookies
-ctx.files?: QHTTPXFile[]           // Uploaded files
-```
-
-### Response Methods
-
-#### `json(body, status?)`
-Sends JSON response.
-
-```typescript
-ctx.json({ message: 'ok' }, 200);
-ctx.json({ error: 'not found' }, 404);
-ctx.json({ users: [] });  // default status 200
-```
-
-#### `send(body, status?)`
-Sends text/buffer response.
-
-```typescript
-ctx.send('Hello world', 200);
-ctx.send(Buffer.from('data'), 200);
-```
-
-#### `html(html, status?)`
-Sends HTML response.
-
-```typescript
-ctx.html('<h1>Hello</h1>', 200);
-```
-
-#### `redirect(url, status?)`
-Redirects to URL.
-
-```typescript
-ctx.redirect('/login', 302);
-```
-
-#### `setCookie(name, value, options?)`
-Sets a cookie.
-
-```typescript
-ctx.setCookie('sessionId', 'abc123', {
-  httpOnly: true,
-  secure: true,
-  maxAge: 7 * 24 * 60 * 60 * 1000,  // 7 days
-  sameSite: 'lax',
-});
-```
-
-### Validation and Data
-
-#### `validate(schema, data?)`
-Validates data against schema.
-
-```typescript
-const validated = await ctx.validate({
-  type: 'object',
-  required: ['email'],
-  properties: { email: { type: 'string' } }
-}, data);
-```
-
-#### `render(view, locals?)`
-Renders template view.
-
-```typescript
-await ctx.render('users/list', { users: [] });
-```
-
-#### `db`
-Database manager (if configured).
-
-```typescript
-const users = await ctx.db?.query('SELECT * FROM users');
-```
-
-### Error Handling
-
-#### `httpError(status, message?, options?)`
-Creates an HTTP error.
-
-```typescript
-throw ctx.httpError(404, 'User not found');
-throw ctx.httpError(400, 'Invalid input', { 
-  code: 'VALIDATION_ERROR',
-  details: { field: 'email' }
-});
-```
-
----
-
-## Configuration
-
-### Security Options
-
-```typescript
-interface SecurityOptions {
-  cors?: CorsOptions | boolean;
-  rateLimit?: RateLimitOptions;
-  headers?: SecurityHeadersOptions | boolean;
-}
-
-interface CorsOptions {
-  origin?: string | string[] | ((origin: string) => boolean);
-  methods?: string[];
-  allowedHeaders?: string[];
-  credentials?: boolean;
-  maxAge?: number;
-}
-
-interface RateLimitOptions {
-  windowMs: number;           // Time window in ms
-  max: number;                // Max requests per window
-  trustProxy?: boolean;       // Trust X-Forwarded-For
-  standardHeaders?: boolean;  // Return RateLimit-* headers
-  keyGenerator?: (ctx: QHTTPXContext) => string;  // Custom key
-  handler?: QHTTPXHandler;    // Custom handler for limited requests
-  skip?: (ctx: QHTTPXContext) => boolean;  // Skip rate limiting
-}
-```
-
-### Compression Options
-
-```typescript
-interface CompressionOptions {
-  threshold?: number;  // Min size to compress (bytes)
-  level?: number;      // Compression level (0-9)
-  brotli?: boolean;    // Enable Brotli compression
-}
-```
-
-### Request Fusion Options
-
-```typescript
-interface RequestFusionOptions {
-  maxWait?: number;    // Max ms to wait for coalescing
-  maxSize?: number;    // Max concurrent requests to coalesce
-}
-```
-
----
-
-## Error Handling
-
-### Global Error Handler
-
-```typescript
-app.onError(({ req, res, error, json }) => {
-  console.error('Error:', error);
-  
-  if (error instanceof HttpError) {
-    json({ error: error.message, code: error.code }, error.status);
-  } else {
-    json({ error: 'Internal server error' }, 500);
-  }
-});
-```
-
-### Not Found Handler
-
-```typescript
-app.notFound(({ url, json }) => {
-  json({ error: 'Not found', path: url.pathname }, 404);
-});
-```
-
-### Method Not Allowed Handler
-
-```typescript
-app.methodNotAllowed(({ method, path, json }) => {
-  json({ error: 'Method not allowed', method, path }, 405);
-});
-```
-
----
-
-## Middleware
-
-### Global Middleware
-
-```typescript
-app.use(async (ctx) => {
-  // Log request
-  console.log(`${ctx.method} ${ctx.path}`);
-  
-  // Perform operation
-  
-  // Continue to next handler
-  if (ctx.next) await ctx.next();
-});
-```
-
-### Route-Specific Middleware (via schema options)
-
-```typescript
-app.post('/admin/users',
-  {
-    priority: 'critical',  // Run before standard routes
-  },
-  ({ json }) => {
-    // Only critical routes run here
-    json({ admin: true }, 201);
-  }
-);
-```
-
----
-
-## Advanced Features
-
-### Request Fusion
-
-Automatically coalesces identical concurrent requests into a single backend operation.
-
-```typescript
-app.fusion(true);
-
-// GET /expensive route
-app.get('/expensive', async ({ json }) => {
-  await sleep(2000);  // Expensive operation
-  json({ data: 'result' }, 200);
-});
-
-// 100 users request simultaneously
-// → Only 1 backend operation executes
-// → All 100 users get same response
-// → Saves 99 database queries!
-```
-
-### Metrics Collection
-
-```typescript
-app.metrics(true);
-
-// Access via GET /metrics endpoint
-// Shows: request count, response times, memory usage, etc
-```
-
-### WebSocket Support
-
-```typescript
-app.upgrade('/chat', (ws) => {
-  ws.join('general');
-  
-  ws.on('message', (msg) => {
-    ws.broadcast('general', msg);
-  });
-});
-
-app.get('/rooms', ({ json }) => {
-  const rooms = ws.getRooms();
-  json({ rooms }, 200);
-});
-```
-
-### Batch Operations
-
-```typescript
-// Batch GET
-app.post('/batch/get', ({ body, json }) => {
-  const { ids } = body;
-  const results = ids.map(id => db.query(`SELECT * FROM users WHERE id = ?`, [id]));
-  json({ results }, 200);
-});
-
-// Batch CREATE
-app.post('/batch/create', ({ body, json }) => {
-  const { items } = body;
-  const results = items.map(item => db.query('INSERT ...', [item]));
-  json({ created: results.length }, 201);
-});
-```
-
-### OpenAPI/Swagger Documentation
-
-```typescript
-app.openapi({
-  title: 'My API',
-  version: '1.0.0',
-  basePath: '/api',
-});
-
-// Auto-generates /openapi.json and /swagger documentation
-```
-
----
-
-## Common Patterns
-
-### Error Handling Pattern
-
-```typescript
-app.post('/users', async ({ body, json, httpError }) => {
-  try {
-    // Validate
-    if (!body.email) {
-      throw httpError(400, 'Email required');
-    }
-    
-    // Process
-    const user = await createUser(body);
-    
-    // Respond
-    json({ user }, 201);
-  } catch (error) {
-    if (error instanceof HttpError) {
-      json({ error: error.message }, error.status);
-    } else {
-      console.error(error);
-      json({ error: 'Internal server error' }, 500);
-    }
-  }
-});
-```
-
-### Authentication Pattern
-
-```typescript
-app.use(async ({ headers, json, next }) => {
-  const token = headers.authorization?.replace('Bearer ', '');
-  
-  if (!token) {
-    // Skip auth for public routes
-    if (ctx.path.startsWith('/public/')) {
-      if (next) await next();
-      return;
-    }
-    json({ error: 'Unauthorized' }, 401);
-    return;
-  }
-  
-  // Verify token
-  const user = await verifyToken(token);
-  if (!user) {
-    json({ error: 'Invalid token' }, 401);
-    return;
-  }
-  
-  // Store in context
-  ctx.state.user = user;
-  if (next) await next();
-});
-```
-
-### Caching Pattern
-
-```typescript
-const cache = new Map();
-
-app.get('/users', ({ json, query }) => {
-  const cacheKey = `users:${JSON.stringify(query)}`;
-  
-  // Check cache
-  if (cache.has(cacheKey)) {
-    json({ ...cache.get(cacheKey), fromCache: true }, 200);
-    return;
-  }
-  
-  // Fetch
-  const users = db.query('SELECT * FROM users');
-  
-  // Cache
-  cache.set(cacheKey, { users });
-  
-  json({ users }, 200);
-});
-```
-
----
-
-## Type Definitions
-
-Complete TypeScript support available:
-
-```typescript
-import {
-  QHTTPX,
-  QHTTPXContext,
-  HttpError,
-  RequestFusionOptions,
-  QHTTPXOptions,
-} from 'qhttpx';
-
-const app: QHTTPX = new QHTTPX();
-
-app.get('/path', (ctx: QHTTPXContext) => {
-  ctx.json({ data: 'value' }, 200);
-});
-```
-
----
-
-## Performance Tuning
-
-### Enable All Optimizations
-
-```typescript
-const app = new QHTTPX({
-  production: true,
-  fusion: { maxWait: 10, maxSize: 100 },
-  compression: { level: 6, brotli: true },
-  metrics: true,
-  bufferPool: { size: 1024 * 1024 },  // 1MB buffer pool
-});
-
-app
-  .production()
-  .fusion(true)
-  .metrics(true);
-```
-
-### Monitor Performance
-
-```typescript
-app.onError(({ error, requestStart, json }) => {
-  const duration = Date.now() - (requestStart || 0);
-  if (duration > 1000) {
-    console.warn(`Slow request: ${duration}ms`);
-  }
-  json({ error: error.message }, 500);
-});
-```
-
----
-
-## More Information
-
-- **Examples:** See `examples/` directory
-- **Benchmarks:** See `benchmarks/` directory
-- **Migration:** See [MIGRATION_1.9_TO_2.0.md](./MIGRATION_1.9_TO_2.0.md)
-- **Production:** See [PRODUCTION_DEPLOYMENT.md](./PRODUCTION_DEPLOYMENT.md)
-- **Security:** See [SECURITY.md](./SECURITY.md)