yinzerflow 0.4.4 → 0.5.0

package/docs/core/context.md

@@ -1,230 +0,0 @@
-# Context Object
-
-The Context object is the central interface for all YinzerFlow route handlers and hooks. It provides access to the request data, response controls, and maintains the complete request lifecycle state.
-
-## Configuration
-
-Context objects are automatically created and provided to all handlers - no configuration required:
-
-```typescript
-import { YinzerFlow } from 'yinzerflow';
-
-const app = new YinzerFlow({ port: 3000 });
-
-// Context is automatically provided to all handlers
-app.get('/api/data', (ctx) => {
-  // Access request data
-  const { path, method, headers } = ctx.request;
-  
-  // Control response
-  ctx.response.setStatusCode(200);
-  
-  return { message: 'Success' };
-});
-```
-
-## Examples
-
-### Basic Example
-
-See [Basic Handler Pattern](./examples.md#basic-handler-pattern) for a complete example showing how to use the context object.
-
-For detailed information about request properties and methods, see [Request Object Documentation](./request.md).
-For detailed information about response methods and capabilities, see [Response Object Documentation](./response.md).
-
-## Common Use Cases
-
-- **Request Data Access**: Extract headers, body, query parameters, and route parameters for processing
-- **Response Control**: Set status codes, add headers, and control response formatting
-- **Authentication**: Access authorization headers and client IP for security validation
-- **Content Negotiation**: Handle Accept headers and Content-Type for proper response formatting
-- **Error Handling**: Provide context to error handlers for detailed error responses
-- **Logging and Monitoring**: Access request metadata for logging and analytics
-
-## Context Structure
-
-The Context object contains two main properties:
-
-### Request Object (`ctx.request`)
-Contains all incoming request data including headers, body, query parameters, route parameters, and metadata. See [Request Object Documentation](./request.md) for detailed information about request properties and methods.
-
-### Response Object (`ctx.response`)
-Provides methods to control the HTTP response including status codes, headers, and response formatting. See [Response Object Documentation](./response.md) for detailed information about response methods and capabilities.
-
-## Context State
-
-The Context object provides a powerful state system that allows you to store and share custom data throughout the request lifecycle. This is perfect for authentication, middleware data, request-scoped variables, and custom context information.
-
-### What is Context State?
-
-Context state is a request-scoped object (`ctx.state`) that persists data throughout the entire request lifecycle. Unlike global variables, state is isolated to each individual request and automatically garbage collected when the request completes.
-
-### Basic Usage
-
-```typescript
-app.get('/api/users', async (ctx) => {
-  // Store custom data in state
-  ctx.state.user = { id: 1, name: 'John' };
-  ctx.state.requestId = generateRequestId();
-  ctx.state.timestamp = Date.now();
-  
-  // Access the data later
-  console.log(ctx.state.user.name);        // "John"
-  console.log(ctx.state.requestId);        // "req-123"
-  console.log(ctx.state.timestamp);        // 1703123456789
-  
-  return { users: ['John', 'Jane'] };
-});
-```
-
-### Advanced Usage with Type Safety
-
-For full type safety, you can extend the context with custom state types:
-
-```typescript
-// Define your custom state interface
-interface AuthContext extends InternalHandlerCallbackGenerics {
-  state: {
-    user: User;
-    permissions: string[];
-    requestId: string;
-    session: Session;
-  };
-}
-
-// Use it in your route handler
-const authHandler: HandlerCallback<AuthContext> = async (ctx) => {
-  // Fully type-safe access to state
-  console.log(ctx.state.user.name);           // Type: string
-  console.log(ctx.state.permissions[0]);      // Type: string
-  console.log(ctx.state.session.expiresAt);   // Type: Date
-  
-  // No type assertions needed!
-  const user = ctx.state.user;                // Type: User
-  const permissions = ctx.state.permissions;  // Type: string[]
-  
-  return { message: 'Authenticated', user };
-};
-```
-
-### State Lifecycle
-
-State data follows the request lifecycle:
-
-1. **Request Start**: State object is created as empty object
-2. **Global Hooks**: `beforeAll` hooks can populate state
-3. **Route Hooks**: `beforeHooks` can access and modify state
-4. **Route Handler**: Your handler can access and modify state
-5. **Route Hooks**: `afterHooks` can access state and modify response
-6. **Global Hooks**: `afterAll` hooks can access state and modify response
-7. **Request End**: State is automatically garbage collected
-
-### State Inheritance in Route Groups
-
-State can be shared across route groups and inherited by nested routes:
-
-```typescript
-app.group('/api/v1', (api) => {
-  // Group-level middleware sets state
-  api.beforeAll([async (ctx) => {
-    ctx.state.apiVersion = 'v1';
-    ctx.state.environment = process.env.NODE_ENV;
-  }]);
-  
-  api.group('/admin', (admin) => {
-    // Admin-specific middleware
-    admin.beforeAll([async (ctx) => {
-      ctx.state.requiresAuth = true;
-      ctx.state.adminOnly = true;
-    }]);
-    
-    // Routes inherit all state from parent groups
-    admin.get('/users', async (ctx) => {
-      console.log(ctx.state.apiVersion);    // "v1"
-      console.log(ctx.state.environment);   // "production"
-      console.log(ctx.state.requiresAuth);  // true
-      console.log(ctx.state.adminOnly);     // true
-      
-      return { users: ['Admin1', 'Admin2'] };
-    });
-  });
-});
-```
-
-### Common Use Cases
-
-- **Authentication**: Store user information and permissions
-- **Request Tracking**: Generate and store request IDs for logging
-- **Middleware Data**: Pass data between middleware and route handlers
-- **Session Management**: Store session information and user preferences
-- **Rate Limiting**: Track request counts and limits per user/IP
-- **Custom Headers**: Store computed headers for later use
-- **Validation Results**: Cache validation results to avoid re-validation
-- **Database Connections**: Store database connection pools or transactions
-
-### Best Practices
-
-- **Keep state minimal**: Only store data that's actually needed
-- **Use descriptive keys**: `ctx.state.user` is better than `ctx.state.u`
-- **Validate state access**: Check if properties exist before using them
-- **Type your state**: Use TypeScript interfaces for complex state structures
-- **Don't store sensitive data**: State is not encrypted or secured
-- **Clean up resources**: Release any resources (like DB connections) when done
-
-### Security Considerations
-
-YinzerFlow implements several security measures for context state:
-
-#### 🛡️ Request Isolation
-- **Problem**: State data could leak between requests
-- **YinzerFlow Solution**: Each request gets its own isolated state object
-
-#### 🛡️ Type Safety
-- **Problem**: Unchecked state access can lead to runtime errors
-- **YinzerFlow Solution**: TypeScript generics provide compile-time type checking
-
-#### 🛡️ Memory Management
-- **Problem**: State data could accumulate and cause memory leaks
-- **YinzerFlow Solution**: State is automatically garbage collected after each request
-
-These security measures ensure YinzerFlow's context state implementation follows security best practices and prevents common attack vectors while maintaining spec compliance.
-
-## TypeScript Support
-
-YinzerFlow provides full TypeScript support for context objects with generic type parameters.
-
-See [TypeScript Pattern](./examples.md#typescript-pattern) for a complete example showing how to use TypeScript with the context object.
-
-## Error Handling Integration
-
-Context objects are automatically passed to error handlers.
-
-See [Error Handler Pattern](./examples.md#error-handler-pattern) for a complete example.
-
-## Hook Integration
-
-Context objects are passed to all hooks (before/after hooks).
-
-See [Hook Pattern](./examples.md#hook-pattern) for a complete example.
-
-## Security Considerations
-
-YinzerFlow implements several security measures for context handling:
-
-### 🛡️ Input Validation
-- **Problem**: Malicious request data can cause injection attacks or bypass security controls
-- **YinzerFlow Solution**: All request properties are automatically validated and sanitized
-
-### 🛡️ Type Safety
-- **Problem**: Untyped request data can lead to runtime errors and security vulnerabilities
-- **YinzerFlow Solution**: Full TypeScript support with generic type parameters ensures type safety
-
-### 🛡️ Context Isolation
-- **Problem**: Context objects could be modified maliciously to bypass security controls
-- **YinzerFlow Solution**: Context objects are isolated and modifications are controlled
-
-### 🛡️ Header Security
-- **Problem**: Malicious headers can cause parsing errors or security bypasses
-- **YinzerFlow Solution**: Header validation and sanitization prevent header-based attacks
-
-These security measures ensure YinzerFlow's context implementation follows security best practices and prevents common attack vectors while maintaining type safety and developer experience. 

package/docs/core/examples.md

@@ -1,444 +0,0 @@
-# Common Examples
-
-This file contains shared examples that are referenced throughout the YinzerFlow documentation to avoid duplication.
-
-## Basic Handler Pattern
-
-```typescript
-import { YinzerFlow } from 'yinzerflow';
-
-const app = new YinzerFlow({ port: 3000 });
-
-app.post('/api/users/:id', (ctx) => {
-  // Access request properties
-  const userId = ctx.request.params.id;
-  const userData = ctx.request.body;
-  const includeProfile = ctx.request.query.include_profile;
-  const authHeader = ctx.request.headers['authorization'];
-  const clientIp = ctx.request.ipAddress;
-  
-  // Control response
-  ctx.response.setStatusCode(201);
-  ctx.response.addHeaders({
-    'Location': `/api/users/${userId}`,
-    'X-User-ID': userId
-  });
-  
-  return {
-    id: userId,
-    data: userData,
-    includeProfile: !!includeProfile,
-    clientIp
-  };
-});
-```
-
-## Request Access Pattern
-
-```typescript
-app.get('/api/users/:id', (ctx) => {
-  const { request } = ctx;
-  
-  // Access route parameters
-  const userId = request.params.id;
-  
-  // Access query parameters
-  const includeProfile = request.query.include_profile;
-  
-  // Access headers
-  const contentType = request.headers['content-type'];
-  const authorization = request.headers['authorization'];
-  
-  // Access request body
-  const userData = request.body;
-  
-  // Access raw body for manual parsing when needed
-  const rawBody = request.rawBody;
-
-  const clientIp = request.ipAddress
-  
-  return {
-    message: 'Request processed successfully',
-    userId,
-    includeProfile,
-    contentType,
-    hasAuth: !!authorization,
-    receivedData: userData
-  };
-});
-```
-
-## Response Control Pattern
-
-```typescript
-app.get('/api/users/:id', (ctx) => {
-  const { request, response } = ctx;
-  const userId = request.params.id;
-  
-  // Set successful status code
-  response.setStatusCode(200);
-  
-  // Add custom headers
-  response.addHeaders({
-    'X-User-ID': userId,
-    'Cache-Control': 'max-age=3600',
-    'X-API-Version': '1.0'
-  });
-  
-  // Return JSON response body (Content-Type automatically set)
-  return {
-    id: userId,
-    name: 'John Doe',
-    email: 'john@example.com',
-    timestamp: new Date().toISOString()
-  };
-});
-```
-
-## Error Handler Pattern
-
-## Context State Examples
-
-### Basic State Usage
-
-```typescript
-app.get('/api/users', async (ctx) => {
-  // Store simple data in state
-  ctx.state.requestId = generateRequestId();
-  ctx.state.timestamp = Date.now();
-  ctx.state.clientIp = ctx.request.ipAddress;
-  
-  // Access the stored data
-  console.log(`Request ${ctx.state.requestId} from ${ctx.state.clientIp}`);
-  
-  return { users: ['John', 'Jane'] };
-});
-```
-
-### Authentication State Pattern
-
-```typescript
-// Authentication middleware
-const authMiddleware: HandlerCallback = async (ctx) => {
-  const token = ctx.request.headers.authorization?.replace('Bearer ', '');
-  
-  if (!token) {
-    throw new Error('Unauthorized');
-  }
-  
-  try {
-    const user = await validateJWT(token);
-    const permissions = await getUserPermissions(user.id);
-    
-    // Store authentication data in state
-    ctx.state.user = user;
-    ctx.state.permissions = permissions;
-    ctx.state.isAuthenticated = true;
-    ctx.state.authTimestamp = Date.now();
-  } catch (error) {
-    throw new Error('Invalid token');
-  }
-};
-
-// Protected route using the state
-app.get('/api/admin/users', authMiddleware, async (ctx) => {
-  // Access the authenticated user data
-  const { user, permissions, isAuthenticated } = ctx.state;
-  
-  if (!permissions.includes('admin')) {
-    throw new Error('Insufficient permissions');
-  }
-  
-  return {
-    message: 'Admin access granted',
-    user: { id: user.id, name: user.name },
-    permissions,
-    authenticatedAt: ctx.state.authTimestamp
-  };
-});
-```
-
-### Typed State Pattern
-
-```typescript
-// Define your state interface
-interface UserContext extends InternalHandlerCallbackGenerics {
-  state: {
-    user: User;
-    permissions: string[];
-    requestId: string;
-    session: {
-      id: string;
-      expiresAt: Date;
-      lastActivity: Date;
-    };
-  };
-}
-
-// Use typed state in your handler
-const userProfileHandler: HandlerCallback<UserContext> = async (ctx) => {
-  // Fully type-safe access to state
-  const { user, permissions, session } = ctx.state;
-  
-  // No type assertions needed!
-  if (session.expiresAt < new Date()) {
-    throw new Error('Session expired');
-  }
-  
-  // Update session activity
-  ctx.state.session.lastActivity = new Date();
-  
-  return {
-    profile: {
-      id: user.id,
-      name: user.name,
-      email: user.email,
-      permissions
-    },
-    session: {
-      id: session.id,
-      expiresAt: session.expiresAt,
-      lastActivity: ctx.state.session.lastActivity
-    }
-  };
-};
-```
-
-### Middleware Chain State Pattern
-
-```typescript
-// Rate limiting middleware
-const rateLimitMiddleware: HandlerCallback = async (ctx) => {
-  const clientIp = ctx.request.ipAddress;
-  const currentCount = await getRequestCount(clientIp);
-  
-  if (currentCount > 100) {
-    throw new Error('Rate limit exceeded');
-  }
-  
-  // Store rate limiting data in state
-  ctx.state.rateLimit = {
-    clientIp,
-    currentCount,
-    limit: 100,
-    resetTime: Date.now() + 60000 // 1 minute
-  };
-  
-  await incrementRequestCount(clientIp);
-};
-
-// Logging middleware
-const loggingMiddleware: HandlerCallback = async (ctx) => {
-  // Access state from previous middleware
-  const rateLimit = ctx.state.rateLimit;
-  
-  ctx.state.logData = {
-    requestId: generateRequestId(),
-    timestamp: Date.now(),
-    clientIp: ctx.request.ipAddress,
-    rateLimitInfo: rateLimit,
-    userAgent: ctx.request.headers['user-agent']
-  };
-  
-  console.log('Request started:', ctx.state.logData);
-};
-
-// Route using both middlewares
-app.get('/api/data', rateLimitMiddleware, loggingMiddleware, async (ctx) => {
-  // Access state from all previous middleware
-  const { rateLimit, logData } = ctx.state;
-  
-  // Add route-specific data to state
-  ctx.state.routeData = {
-    endpoint: '/api/data',
-    method: 'GET',
-    processingTime: Date.now() - logData.timestamp
-  };
-  
-  return {
-    message: 'Data retrieved successfully',
-    rateLimit: {
-      remaining: rateLimit.limit - rateLimit.currentCount,
-      resetTime: rateLimit.resetTime
-    },
-    requestInfo: logData,
-    routeInfo: ctx.state.routeData
-  };
-});
-```
-
-### Route Group State Pattern
-
-```typescript
-app.group('/api/v1', (api) => {
-  // Global API state
-  api.beforeAll([async (ctx) => {
-    ctx.state.apiVersion = 'v1';
-    ctx.state.environment = process.env.NODE_ENV;
-    ctx.state.baseUrl = 'https://api.example.com';
-  }]);
-  
-  api.group('/admin', (admin) => {
-    // Admin-specific state
-    admin.beforeAll([async (ctx) => {
-      ctx.state.requiresAuth = true;
-      ctx.state.adminOnly = true;
-      ctx.state.auditLog = true;
-    }]);
-    
-    admin.group('/users', (users) => {
-      // User management state
-      users.beforeAll([async (ctx) => {
-        ctx.state.resourceType = 'user';
-        ctx.state.allowedOperations = ['create', 'read', 'update', 'delete'];
-      }]);
-      
-      // Route inherits all state from parent groups
-      users.get('/', async (ctx) => {
-        const {
-          apiVersion,        // "v1"
-          environment,       // "production"
-          requiresAuth,      // true
-          adminOnly,         // true
-          auditLog,          // true
-          resourceType,      // "user"
-          allowedOperations  // ["create", "read", "update", "delete"]
-        } = ctx.state;
-        
-        return {
-          message: 'User list retrieved',
-          apiInfo: { version: apiVersion, environment },
-          security: { requiresAuth, adminOnly, auditLog },
-          resource: { type: resourceType, operations: allowedOperations }
-        };
-      });
-    });
-  });
-});
-```
-
-### State Validation Pattern
-
-```typescript
-// State validation helper
-const validateState = (ctx: Context, requiredKeys: string[]) => {
-  const missing = requiredKeys.filter(key => !(key in ctx.state));
-  
-  if (missing.length > 0) {
-    throw new Error(`Missing required state: ${missing.join(', ')}`);
-  }
-};
-
-// Middleware that sets required state
-const userContextMiddleware: HandlerCallback = async (ctx) => {
-  const userId = ctx.request.params.userId;
-  
-  if (!userId) {
-    throw new Error('User ID required');
-  }
-  
-  const user = await getUserById(userId);
-  if (!user) {
-    throw new Error('User not found');
-  }
-  
-  // Set required state
-  ctx.state.user = user;
-  ctx.state.userId = userId;
-  ctx.state.userPermissions = await getUserPermissions(userId);
-};
-
-// Route that validates state
-app.get('/api/users/:userId/profile', userContextMiddleware, async (ctx) => {
-  // Validate required state
-  validateState(ctx, ['user', 'userId', 'userPermissions']);
-  
-  // Now we can safely access state
-  const { user, userPermissions } = ctx.state;
-  
-  return {
-    profile: user,
-    permissions: userPermissions,
-    lastAccessed: new Date().toISOString()
-  };
-});
-```
-
-## Hook Pattern
-
-```typescript
-// Before hook
-app.beforeAll([(ctx) => {
-  // Access request context
-  const authHeader = ctx.request.headers['authorization'];
-  
-  // Validate authentication
-  if (!authHeader) {
-    throw new Error('Authentication required');
-  }
-}]);
-
-// After hook
-app.afterAll([(ctx) => {
-  // Access response context
-  ctx.response.addHeaders({
-    'X-Response-Time': Date.now().toString()
-  });
-}]);
-```
-
-## TypeScript Pattern
-
-```typescript
-import type { HandlerCallback } from 'yinzerflow';
-
-// Define custom types for your API
-interface UserBody {
-  name: string;
-  email: string;
-  age: number;
-}
-
-interface UserResponse {
-  id: string;
-  name: string;
-  email: string;
-  createdAt: string;
-}
-
-interface UserQuery {
-  include_profile?: string;
-  limit?: string;
-}
-
-interface UserParams {
-  id: string;
-}
-
-// Typed handler with custom body, response, query, and params
-const createUserHandler: HandlerCallback<{
-  body: UserBody;
-  response: UserResponse;
-  query: UserQuery;
-  params: UserParams;
-}> = (ctx) => {
-  // ctx.request.body is typed as UserBody
-  const userData = ctx.request.body;
-  
-  // ctx.request.query is typed as UserQuery
-  const includeProfile = ctx.request.query.include_profile;
-  
-  // ctx.request.params is typed as UserParams
-  const userId = ctx.request.params.id;
-  
-  // Return type is typed as UserResponse
-  return {
-    id: 'user-123',
-    name: userData.name,
-    email: userData.email,
-    createdAt: new Date().toISOString()
-  };
-};
-
-app.post('/api/users/:id', createUserHandler);
-```