yinzerflow 0.2.9 → 0.3.0

package/docs/core/context.md

@@ -51,6 +51,144 @@ Contains all incoming request data including headers, body, query parameters, ro
 ### 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.

package/docs/core/examples.md

@@ -97,20 +97,269 @@ app.get('/api/users/:id', (ctx) => {
 
 ## Error Handler Pattern
 
+## Context State Examples
+
+### Basic State Usage
+
 ```typescript
-app.onError((ctx, error) => {
-  // Access request context in error handler
-  const { path, method, headers } = ctx.request;
+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;
   
-  // Control error response
-  ctx.response.setStatusCode(500);
+  // 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 {
-    success: false,
-    error: 'Internal server error',
-    path,
-    method,
-    timestamp: new Date().toISOString()
+    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()
   };
 });
 ```

package/docs/core/routes.md

@@ -144,6 +144,83 @@ app.get('/users/:userId/posts/:postId', ({ request }) => {
 - Use consistent naming conventions
 - Avoid generic names that could cause confusion
 
+## Context State
+
+YinzerFlow provides a powerful context 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.
+
+### Quick Reference
+
+The context state is accessible via `ctx.state` and can store any data you need:
+
+```typescript
+app.get('/api/users', async (ctx) => {
+  // Store custom data in state
+  ctx.state.user = { id: 1, name: 'John' };
+  ctx.state.requestId = generateRequestId();
+  
+  // Access the data later
+  console.log(ctx.state.user.name);        // "John"
+  console.log(ctx.state.requestId);        // "req-123"
+  
+  return { users: ['John', 'Jane'] };
+});
+```
+
+### Middleware Integration
+
+State is perfect for middleware that needs to pass data to route handlers:
+
+```typescript
+// Authentication middleware
+const authMiddleware: HandlerCallback = async (ctx) => {
+  const token = ctx.request.headers.authorization;
+  const user = await validateToken(token);
+  
+  // Store user data in state for route handlers
+  ctx.state.user = user;
+  ctx.state.permissions = await getUserPermissions(user.id);
+};
+
+// Route that uses the authenticated state
+app.get('/api/admin/users', authMiddleware, async (ctx) => {
+  const { user, permissions } = ctx.state;
+  
+  if (!permissions.includes('admin')) {
+    throw new Error('Insufficient permissions');
+  }
+  
+  return { message: 'Admin access granted', user };
+});
+```
+
+### Route Group State
+
+State can be shared across route groups and inherited by nested routes:
+
+```typescript
+app.group('/api/v1', (api) => {
+  api.beforeAll([async (ctx) => {
+    ctx.state.apiVersion = 'v1';
+    ctx.state.environment = process.env.NODE_ENV;
+  }]);
+  
+  api.group('/admin', (admin) => {
+    admin.beforeAll([async (ctx) => {
+      ctx.state.requiresAuth = true;
+      ctx.state.adminOnly = true;
+    }]);
+    
+    // Routes inherit all state from parent groups
+    admin.get('/users', async (ctx) => {
+      const { apiVersion, environment, requiresAuth, adminOnly } = ctx.state;
+      return { users: ['Admin1', 'Admin2'] };
+    });
+  });
+});
+```
+
+**📚 For comprehensive Context State documentation including TypeScript patterns, security considerations, and best practices, see [Context State Documentation](./context.md#context-state).**
+
 ## Query Parameters
 
 URL query strings are automatically parsed and available in `ctx.request.query`:
@@ -305,10 +382,11 @@ Global hooks are executed in the following order:
 
 ## Route Groups
 
-Organize related routes with shared prefixes and hooks. Groups automatically merge hooks from the group level with individual route hooks:
+Route groups allow you to organize related routes under a common prefix and apply shared middleware or hooks to all routes within the group. Groups can be nested to create hierarchical route structures.
+
+### Basic Group Usage
 
 ```typescript
-// API v1 routes with authentication
 app.group('/api/v1', (group) => {
   group.get('/users', ({ response }) => {
     return { users: ['John', 'Jane'] };
@@ -331,49 +409,134 @@ app.group('/api/v1', (group) => {
     }
   ]
 });
+```
+
+### Nested Groups
 
-// Admin routes with admin authentication
-app.group('/admin', (group) => {
-  group.get('/dashboard', ({ response }) => {
-    return { message: 'Admin dashboard' };
+Groups can be nested to create hierarchical route structures like `/api/v1/admin/users`:
+
+```typescript
+app.group('/api/v1', (api) => {
+  // /api/v1/users
+  api.group('/users', (users) => {
+    users.get('/', ({ response }) => {
+      return { users: ['John', 'Jane'] };
+    });
+    
+    users.get('/:id', ({ request }) => {
+      const userId = request.params.id;
+      return { userId, name: 'John Doe' };
+    });
   });
   
-  group.post('/settings', ({ request }) => {
-    const settings = request.body;
-    return { message: 'Settings updated', settings };
+  // /api/v1/admin
+  api.group('/admin', (admin) => {
+    // /api/v1/admin/users
+    admin.group('/users', (adminUsers) => {
+      adminUsers.get('/', ({ response }) => {
+        return { adminUsers: ['Admin1', 'Admin2'] };
+      });
+      
+      adminUsers.post('/', ({ request }) => {
+        const userData = request.body;
+        return { message: 'Admin user created', data: userData };
+      });
+    }, {
+      beforeHooks: [
+        ({ request }) => {
+          // Admin authentication check
+          if (!request.headers.authorization) {
+            throw new Error('Unauthorized');
+          }
+        }
+      ]
+    });
+  }, {
+    beforeHooks: [
+      ({ request }) => {
+        // Admin role verification
+        console.log('Admin route accessed');
+      }
+    ]
   });
 }, {
   beforeHooks: [
-    ({ request, response }) => {
-      // Admin authentication
-      const adminToken = request.headers['x-admin-token'];
-      if (!adminToken) {
-        response.setStatusCode(403);
-        return { error: 'Admin access required' };
-      }
+    ({ request }) => {
+      // Global API logging
+      console.log(`API request to: ${request.url}`);
     }
   ]
 });
+```
+
+### Hook Inheritance
+
+Hooks are inherited and merged from parent groups to child groups:
 
-// Nested groups with complex hook merging
-app.group('/api/v1', (v1Group) => {
-  v1Group.group('/admin', (adminGroup) => {
-    adminGroup.get('/users', ({ response }) => {
-      return { message: 'Admin users endpoint' };
+```typescript
+app.group('/api', (api) => {
+  // This group inherits the 'api' beforeHooks
+  
+  api.group('/v1', (v1) => {
+    // This group inherits both 'api' and 'v1' beforeHooks
+    
+    v1.group('/admin', (admin) => {
+      // This group inherits 'api', 'v1', and 'admin' beforeHooks
+      
+      admin.get('/dashboard', ({ response }) => {
+        // All three beforeHooks will execute in order
+        return { message: 'Admin dashboard' };
+      });
+    }, {
+      beforeHooks: [
+        ({ request }) => {
+          // Admin-specific hook
+          console.log('Admin route accessed');
+        }
+      ]
     });
   }, {
     beforeHooks: [
-      () => {
-        // Admin-specific hook
-        console.log('Admin group hook');
+      ({ request }) => {
+        // Version-specific hook
+        console.log('API v1 accessed');
       }
     ]
   });
 }, {
   beforeHooks: [
-    () => {
-      // API v1 hook
-      console.log('API v1 group hook');
+    ({ request }) => {
+      // Global API hook
+      console.log('API request');
+    }
+  ]
+});
+```
+
+### Group Options
+
+Groups support the same options as individual routes:
+
+```typescript
+app.group('/api/v1', (group) => {
+  group.get('/public', ({ response }) => {
+    return { message: 'Public endpoint' };
+  });
+  
+  group.get('/private', ({ response }) => {
+    return { message: 'Private endpoint' };
+  });
+}, {
+  beforeHooks: [
+    ({ request }) => {
+      // Global group hooks
+      console.log('API v1 request');
+    }
+  ],
+  afterHooks: [
+    ({ response }) => {
+      // Global group after hooks
+      response.headers.set('X-API-Version', 'v1');
     }
   ]
 });