yinzerflow 0.2.7 → 0.2.9

package/docs/{routes.md → core/routes.md}

@@ -30,54 +30,9 @@ YinzerFlow's routing system includes built-in security and performance optimizat
 | **Hook System** | Optional | Before/after hooks for middleware |
 | **Route Groups** | Optional | Organized route prefixes and shared hooks |
 
-## Basic Example
+## Basic Examples
 
-```typescript
-import { YinzerFlow } from 'yinzerflow';
-
-const app = new YinzerFlow({ port: 3000 });
-
-// Simple GET route
-app.get('/api/health', ({ response }) => {
-  return { status: 'healthy', timestamp: new Date().toISOString() };
-});
-
-// POST route with body parsing
-app.post('/api/users', ({ request }) => {
-  const userData = request.body;
-  const clientIp = request.ipAddress;
-  
-  return {
-    message: 'User created',
-    data: userData,
-    clientIp
-  };
-});
-
-// Route with parameters
-app.get('/api/users/:id', ({ request }) => {
-  const userId = request.params.id;
-  const includeProfile = request.query.include_profile;
-  
-  return {
-    userId,
-    includeProfile,
-    message: 'User details retrieved'
-  };
-});
-```
-
-For detailed information about the request and response objects, see [Request Documentation](./request.md) and [Response Documentation](./response.md).
-
-## Common Use Cases
-
-- **API Endpoints**: Create RESTful APIs with proper HTTP methods and status codes
-- **File Uploads**: Handle multipart form data with automatic parsing and validation
-- **Authentication**: Implement middleware hooks for token validation and user sessions
-- **Rate Limiting**: Add before hooks to limit request frequency and prevent abuse
-- **Logging**: Use after hooks to log request/response data for monitoring
-- **CORS Handling**: Configure cross-origin requests with proper headers and preflight handling
-- **Route Organization**: Group related routes with shared prefixes and middleware
+For common routing patterns and examples, see [Shared Examples](./examples.md).
 
 ## HTTP Methods
 
@@ -524,46 +479,9 @@ await app.listen();
 
 ## Error Handling
 
-YinzerFlow provides comprehensive error handling for routes:
-
-### Custom Error Handlers
-```typescript
-// Global error handler
-app.onError(({ request, response }) => {
-  console.error('Unhandled error:', request.path);
-  response.setStatusCode(500);
-  return { error: 'Internal server error' };
-});
+YinzerFlow provides comprehensive error handling with automatic error catching and custom error handlers. The framework automatically catches all errors thrown in route handlers, hooks, and middleware.
 
-// Custom not found handler
-app.onNotFound(({ request, response }) => {
-  response.setStatusCode(404);
-  return { 
-    error: 'Route not found',
-    path: request.path,
-    method: request.method
-  };
-});
-```
-
-### Route-Specific Error Handling
-```typescript
-app.get('/api/users/:id', ({ request, response }) => {
-  try {
-    const userId = request.params.id;
-    
-    // Simulate database lookup
-    if (userId === '999') {
-      throw new Error('User not found');
-    }
-    
-    return { userId, name: 'John Doe' };
-  } catch (error) {
-    response.setStatusCode(404);
-    return { error: 'User not found' };
-  }
-});
-```
+For detailed error handling documentation including advanced patterns, security considerations, and best practices, see [Error Handling Documentation](./error-handling.md).
 
 ## HandlerCallback Interface
 
@@ -619,38 +537,21 @@ Using the interface is optional but encouraged for better type safety and develo
 
 ## Security Considerations
 
-YinzerFlow implements several security measures to prevent common routing vulnerabilities:
-
-### 🛡️ Route Parameter Validation
-- **Problem**: Malicious route parameters can cause injection attacks or bypass security controls
-- **YinzerFlow Solution**: Automatic parameter validation and sanitization prevents injection attacks
-
-### 🛡️ Path Traversal Protection
-- **Problem**: Directory traversal attacks through URL paths can access unauthorized files
-- **YinzerFlow Solution**: Comprehensive path normalization and validation prevents traversal attempts
-
-### 🛡️ Query Parameter Sanitization
-- **Problem**: Malicious query parameters can cause injection attacks or bypass validation
-- **YinzerFlow Solution**: Automatic query parameter parsing with built-in sanitization
-
-### 🛡️ Request Body Validation
-- **Problem**: Malformed request bodies can cause parsing errors or security vulnerabilities
-- **YinzerFlow Solution**: Comprehensive body parsing with size limits and validation - see [Body Parsing Documentation](./body-parsing.md)
-
-### 🛡️ Hook Execution Security
-- **Problem**: Malicious hooks can modify responses or bypass security controls
-- **YinzerFlow Solution**: Hook execution is isolated and errors are handled gracefully
+YinzerFlow implements several security measures to prevent common routing vulnerabilities. For detailed security documentation, see:
 
-### 🛡️ Route Collision Prevention
-- **Problem**: Duplicate routes can cause unexpected behavior or security bypasses
-- **YinzerFlow Solution**: Automatic detection and prevention of route conflicts during registration
+- **[Body Parsing Security](../security/body-parsing.md)** - Protection against DoS attacks and malicious payloads
+- **[CORS Security](../security/cors.md)** - Cross-origin request validation and protection
+- **[IP Security](../security/ip-security.md)** - Client IP validation and spoofing protection
 
-### 🛡️ Method Validation
-- **Problem**: Invalid HTTP methods can cause parsing errors or security issues
-- **YinzerFlow Solution**: Strict validation of HTTP methods against RFC specifications
+### Key Security Features
 
-### 🛡️ Response Header Security
-- **Problem**: Malicious response headers can cause client-side vulnerabilities
-- **YinzerFlow Solution**: Automatic security headers and header validation - see [Response Documentation](./response.md)
+- **Route Parameter Validation**: Automatic validation and sanitization prevents injection attacks
+- **Path Traversal Protection**: Comprehensive path normalization prevents directory traversal
+- **Query Parameter Sanitization**: Built-in sanitization with configurable limits
+- **Request Body Validation**: Size limits and content validation prevent DoS attacks
+- **Hook Execution Security**: Isolated hook execution with graceful error handling
+- **Route Collision Prevention**: Automatic detection and prevention of route conflicts
+- **Method Validation**: Strict HTTP method validation against RFC specifications
+- **Response Header Security**: Automatic security headers and validation
 
 These security measures ensure YinzerFlow's routing implementation follows security best practices and prevents common attack vectors while maintaining HTTP compliance and performance.

package/docs/quick-reference.md

@@ -0,0 +1,346 @@
+# Quick Reference
+
+This quick reference contains the most common patterns and examples for YinzerFlow. For detailed documentation, see the full documentation sections.
+
+## Installation & Setup
+
+```bash
+# Install
+npm install yinzerflow
+
+# Basic setup
+import { YinzerFlow } from 'yinzerflow';
+const app = new YinzerFlow({ port: 3000 });
+await app.listen();
+```
+
+## Basic Routes
+
+```typescript
+// GET route
+app.get('/api/users', (ctx) => {
+  return { users: ['John', 'Jane'] };
+});
+
+// POST route with body
+app.post('/api/users', (ctx) => {
+  const userData = ctx.request.body;
+  return { message: 'User created', data: userData };
+});
+
+// Route with parameters
+app.get('/api/users/:id', (ctx) => {
+  const userId = ctx.request.params.id;
+  return { userId, name: 'John Doe' };
+});
+
+// Route with query parameters
+app.get('/api/search', (ctx) => {
+  const { q, limit } = ctx.request.query;
+  return { search: q, limit: parseInt(limit || '10') };
+});
+```
+
+## HTTP Methods
+
+```typescript
+app.get('/api/users', handler);      // GET
+app.post('/api/users', handler);     // POST  
+app.put('/api/users/:id', handler);  // PUT
+app.patch('/api/users/:id', handler); // PATCH
+app.delete('/api/users/:id', handler); // DELETE
+app.options('/api/users', handler);  // OPTIONS
+app.head('/api/users', handler);     // HEAD (or auto-registered with GET)
+```
+
+## Route Groups
+
+```typescript
+app.group('/api/v1', (group) => {
+  group.get('/users', handler);
+  group.post('/users', handler);
+  group.get('/users/:id', handler);
+}, {
+  beforeHooks: [authHook]
+});
+```
+
+## Hooks
+
+```typescript
+// Route-specific hooks
+app.post('/api/users', handler, {
+  beforeHooks: [authHook, logHook],
+  afterHooks: [responseHook]
+});
+
+// Global hooks
+app.beforeAll([globalAuthHook]);
+app.afterAll([globalLogHook]);
+app.onError(errorHandler);
+app.onNotFound(notFoundHandler);
+```
+
+## Request Data
+
+```typescript
+app.post('/api/users', ({ request }) => {
+  // Body data
+  const userData = request.body;
+  
+  // URL parameters
+  const userId = request.params.id;
+  
+  // Query parameters
+  const { page, limit } = request.query;
+  
+  // Headers
+  const token = request.headers['authorization'];
+  
+  // Client IP
+  const clientIp = request.ipAddress;
+  
+  // Request info
+  const { method, path, url } = request;
+});
+```
+
+## Response Control
+
+```typescript
+app.post('/api/users', ({ response }) => {
+  // Set status code
+  response.setStatusCode(201);
+  
+  // Add headers
+  response.addHeaders({
+    'X-User-ID': '123',
+    'Content-Type': 'application/json'
+  });
+  
+  // Return data
+  return { message: 'User created' };
+});
+```
+
+## Error Handling
+
+```typescript
+// Global error handler
+app.onError(({ response }, error) => {
+  response.setStatusCode(500);
+  return { error: 'Internal server error' };
+});
+
+// Route error handling
+app.get('/api/users/:id', ({ request }) => {
+  const userId = request.params.id;
+  if (!userId) {
+    throw new Error('User ID required');
+  }
+  return { userId };
+});
+```
+
+## Common Configurations
+
+### Basic API
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  cors: {
+    enabled: true,
+    origin: ['https://yourdomain.com']
+  }
+});
+```
+
+### Production API
+```typescript
+const app = new YinzerFlow({
+  port: 443,
+  cors: {
+    enabled: true,
+    origin: ['https://yourdomain.com'],
+    credentials: true
+  },
+  bodyParser: {
+    json: {
+      maxSize: 262144, // 256KB
+      allowPrototypeProperties: false
+    }
+  },
+  ipSecurity: {
+    trustedProxies: ['127.0.0.1'],
+    detectSpoofing: true
+  }
+});
+```
+
+### File Upload Service
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  bodyParser: {
+    fileUploads: {
+      maxFileSize: 10485760, // 10MB
+      maxFiles: 10,
+      allowedExtensions: ['.jpg', '.png', '.pdf']
+    }
+  }
+});
+```
+
+## TypeScript Support
+
+```typescript
+interface UserBody {
+  name: string;
+  email: string;
+}
+
+interface UserResponse {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const createUser: HandlerCallback<{
+  body: UserBody;
+  response: UserResponse;
+}> = ({ request }) => {
+  const userData = request.body; // Typed as UserBody
+  return {
+    id: 'user-123',
+    name: userData.name,
+    email: userData.email
+  }; // Typed as UserResponse
+};
+
+app.post('/api/users', createUser);
+```
+
+## Common Patterns
+
+### Authentication Hook
+```typescript
+const authHook = ({ request, response }) => {
+  const token = request.headers['authorization'];
+  if (!token) {
+    response.setStatusCode(401);
+    return { error: 'Unauthorized' };
+  }
+};
+```
+
+### Logging Hook
+```typescript
+const logHook = ({ request }) => {
+  console.log(`${request.method} ${request.path} - ${request.ipAddress}`);
+};
+```
+
+### Rate Limiting Hook
+```typescript
+const rateLimitHook = ({ request, response }) => {
+  const clientIp = request.ipAddress;
+  const requests = getRequestCount(clientIp);
+  
+  if (requests > 100) {
+    response.setStatusCode(429);
+    return { error: 'Too many requests' };
+  }
+};
+```
+
+### Validation Hook
+```typescript
+const validateUserData = ({ request, response }) => {
+  const userData = request.body;
+  
+  if (!userData.name || !userData.email) {
+    response.setStatusCode(400);
+    return { error: 'Name and email required' };
+  }
+};
+```
+
+## File Organization
+
+### routes/users.ts
+```typescript
+import type { YinzerFlow } from 'yinzerflow';
+
+export const registerUserRoutes = (app: YinzerFlow) => {
+  app.get('/api/users', getAllUsers);
+  app.post('/api/users', createUser);
+  app.get('/api/users/:id', getUserById);
+  app.put('/api/users/:id', updateUser);
+  app.delete('/api/users/:id', deleteUser);
+};
+```
+
+### Main app
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+import { registerUserRoutes } from './routes/users';
+
+const app = new YinzerFlow({ port: 3000 });
+registerUserRoutes(app);
+await app.listen();
+```
+
+## Security Checklist
+
+- [ ] CORS configured with specific origins
+- [ ] Body parsing limits set appropriately
+- [ ] File upload restrictions in place
+- [ ] IP security configured for infrastructure
+- [ ] Error handling prevents information leakage
+- [ ] Authentication hooks implemented
+- [ ] Rate limiting configured
+- [ ] HTTPS enabled (production)
+- [ ] Security headers configured
+- [ ] Logging configured to avoid sensitive data
+
+## Common Issues
+
+### CORS Errors
+```typescript
+cors: {
+  enabled: true,
+  origin: ['https://yourdomain.com'], // Specific origin
+  credentials: true // If using cookies
+}
+```
+
+### File Upload Issues
+```typescript
+bodyParser: {
+  fileUploads: {
+    maxFileSize: 10485760, // 10MB
+    allowedExtensions: ['.jpg', '.png', '.pdf']
+  }
+}
+```
+
+### IP Address Issues
+```typescript
+ipSecurity: {
+  trustedProxies: ['127.0.0.1', '192.168.1.10'],
+  headerPreference: ['x-forwarded-for', 'x-real-ip']
+}
+```
+
+## Documentation Sections
+
+- **[Getting Started](./start-here.md)** - Installation and basic setup
+- **[Routes](./core/routes.md)** - Complete routing system
+- **[Context Object](./core/context.md)** - Request/response interface
+- **[Request Object](./core/request.md)** - Request data access
+- **[Response Object](./core/response.md)** - Response control
+- **[Error Handling](./core/error-handling.md)** - Error management
+- **[Examples](./core/examples.md)** - Common patterns and examples
+- **[Security Overview](./security/security-overview.md)** - Security features
+- **[Configuration Patterns](./configuration/configuration-patterns.md)** - Configuration examples
+- **[Advanced Configuration](./configuration/advanced-configuration-options.md)** - Complete configuration reference 

package/docs/{body-parsing.md → security/body-parsing.md}

@@ -1,7 +1,9 @@
-# Body Parsing
+# Body Parsing Security
 
 YinzerFlow provides comprehensive body parsing with built-in security protections against DoS attacks, prototype pollution, and memory exhaustion vulnerabilities. The body parser automatically handles JSON, file uploads, and URL-encoded form data with configurable security limits.
 
+For an overview of all security features, see [Security Overview](./security-overview.md).
+
 ## Configuration
 
 Body parsing is automatically enabled with secure defaults that protect against common attack vectors:

package/docs/{cors.md → security/cors.md}

@@ -1,7 +1,9 @@
-# CORS (Cross-Origin Resource Sharing)
+# CORS Security
 
 YinzerFlow provides built-in CORS support to handle cross-origin requests securely and efficiently.
 
+For an overview of all security features, see [Security Overview](./security-overview.md).
+
 ## Configuration
 
 Configure CORS in your YinzerFlow setup:

package/docs/{ip-security.md → security/ip-security.md}

@@ -1,7 +1,9 @@
-# IP Address Security
+# IP Security
 
 YinzerFlow provides comprehensive IP address validation and security protection against IP spoofing attacks, supporting multiple header formats with trusted proxy validation.
 
+For an overview of all security features, see [Security Overview](./security-overview.md).
+
 ## Configuration
 
 Configure IP security settings in your YinzerFlow application: