balda-js 0.0.1 → 0.0.2

package/docs/docs/core-concepts/middleware.md

@@ -1,302 +0,0 @@
----
-sidebar_position: 4
----
-
-# Middleware
-
-Middleware in Balda.js are functions that have access to the request object, response object, and the next middleware function in the application's request-response cycle. They can execute code, modify the request and response objects, end the request-response cycle, and call the next middleware function.
-
-## Basic Middleware
-
-### Function Signature
-
-```typescript
-type Middleware = (
-  req: Request,
-  res: Response,
-  next: NextFunction
-) => void | Promise<void>;
-```
-
-### Simple Middleware Example
-
-```typescript
-const logger = (req, res, next) => {
-  console.log(`${req.method} ${req.url} - ${new Date().toISOString()}`);
-  next();
-};
-
-const auth = (req, res, next) => {
-  const token = req.headers.authorization;
-
-  if (!token) {
-    return res.unauthorized({ error: 'Authentication required' });
-  }
-
-  // Verify token logic here
-  req.user = { id: 1, name: 'John' };
-  next();
-};
-```
-
-## Middleware Application
-
-### Global Middleware
-
-Apply middleware to all routes:
-
-```typescript
-import { Server } from 'balda-js';
-
-const server = new Server({ port: 3000 });
-
-// Apply to all routes
-server.use(logger);
-server.use(cors);
-
-// Multiple middleware
-server.use(
-  (req, res, next) => {
-    req.startTime = Date.now();
-    next();
-  },
-  (req, res, next) => {
-    res.on('finish', () => {
-      const duration = Date.now() - req.startTime;
-      console.log(`${req.method} ${req.url} - ${duration}ms`);
-    });
-    next();
-  }
-);
-```
-
-### Controller-Level Middleware
-
-Apply middleware to all routes in a controller:
-
-```typescript
-import { controller, get, middleware } from 'balda-js';
-
-@controller('/users')
-@middleware(authMiddleware)
-export class UsersController {
-  @get('/')
-  async getAllUsers(req, res) {
-    // This route will use authMiddleware
-    res.json({ users: [] });
-  }
-
-  @get('/public')
-  @middleware(publicMiddleware) // Override controller middleware
-  async getPublicUsers(req, res) {
-    // This route will use publicMiddleware instead
-    res.json({ users: [] });
-  }
-}
-```
-
-### Route-Level Middleware
-
-Apply middleware to specific routes:
-
-```typescript
-@get('/admin/users', { middleware: [authMiddleware, adminMiddleware] })
-async getAdminUsers(req, res) {
-  res.json({ users: [] });
-}
-```
-
-## Common Middleware Patterns
-
-### Authentication Middleware
-
-```typescript
-const authMiddleware = async (req, res, next) => {
-  const token = req.headers.authorization?.replace('Bearer ', '');
-
-  if (!token) {
-    return res.unauthorized({ error: 'Authentication token required' });
-  }
-
-  try {
-    // Verify JWT token
-    const decoded = jwt.verify(token, process.env.JWT_SECRET);
-    req.user = decoded;
-    next();
-  } catch (error) {
-    return res.unauthorized({ error: 'Invalid authentication token' });
-  }
-};
-```
-
-### Role-Based Authorization
-
-```typescript
-const requireRole = (role) => {
-  return (req, res, next) => {
-    if (!req.user) {
-      return res.unauthorized({ error: 'Authentication required' });
-    }
-
-    if (req.user.role !== role) {
-      return res.forbidden({ error: 'Insufficient permissions' });
-    }
-
-    next();
-  };
-};
-
-// Usage
-@get('/admin', { middleware: [authMiddleware, requireRole('admin')] })
-async getAdminPanel(req, res) {
-  res.json({ admin: true });
-}
-```
-
-### Request Logging
-
-```typescript
-const requestLogger = (req, res, next) => {
-  const start = Date.now();
-
-  res.on('finish', () => {
-    const duration = Date.now() - start;
-    console.log(`${req.method} ${req.url} ${res.statusCode} - ${duration}ms`);
-  });
-
-  next();
-};
-```
-
-### Error Handling Middleware
-
-```typescript
-const errorHandler = (req, res, next, error) => {
-  console.error('Error:', error);
-
-  if (error.name === 'ValidationError') {
-    return res.badRequest({ error: error.message });
-  }
-
-  if (error.name === 'UnauthorizedError') {
-    return res.unauthorized({ error: 'Authentication required' });
-  }
-
-  res.internalServerError({ error: 'Internal server error' });
-};
-
-server.setErrorHandler(errorHandler);
-```
-
-### CORS Middleware
-
-```typescript
-const corsMiddleware = (req, res, next) => {
-  res.setHeader('Access-Control-Allow-Origin', '*');
-  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
-  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
-
-  if (req.method === 'OPTIONS') {
-    res.status(200).end();
-    return;
-  }
-
-  next();
-};
-```
-
-### Rate Limiting
-
-```typescript
-const rateLimit = (windowMs = 15 * 60 * 1000, max = 100) => {
-  const requests = new Map();
-
-  return (req, res, next) => {
-    const ip = req.ip;
-    const now = Date.now();
-
-    if (!requests.has(ip)) {
-      requests.set(ip, { count: 0, resetTime: now + windowMs });
-    }
-
-    const record = requests.get(ip);
-
-    if (now > record.resetTime) {
-      record.count = 0;
-      record.resetTime = now + windowMs;
-    }
-
-    if (record.count >= max) {
-      return res.tooManyRequests({ error: 'Too many requests' });
-    }
-
-    record.count++;
-    next();
-  };
-};
-```
-
-## Middleware Order
-
-The order of middleware matters. Middleware are executed in the order they are applied:
-
-```typescript
-// 1. Global middleware (applied first)
-server.use(logger);
-server.use(cors);
-
-// 2. Controller middleware
-@controller('/users')
-@middleware(authMiddleware) // Applied to all routes in controller
-
-// 3. Route middleware (applied last)
-@get('/admin', { middleware: [adminMiddleware] })
-async getAdmin(req, res) {
-  // Execution order: logger -> cors -> authMiddleware -> adminMiddleware -> handler
-}
-```
-
-## Async Middleware
-
-Middleware can be async functions:
-
-```typescript
-const asyncAuthMiddleware = async (req, res, next) => {
-  try {
-    const token = req.headers.authorization?.replace('Bearer ', '');
-
-    if (!token) {
-      return res.unauthorized({ error: 'Authentication required' });
-    }
-
-    // Async operation
-    const user = await verifyToken(token);
-    req.user = user;
-    next();
-  } catch (error) {
-    return res.unauthorized({ error: 'Invalid token' });
-  }
-};
-```
-
-## Conditional Middleware
-
-Apply middleware conditionally:
-
-```typescript
-const conditionalAuth = (req, res, next) => {
-  // Skip auth for public routes
-  if (req.path.startsWith('/public')) {
-    return next();
-  }
-
-  // Apply auth for protected routes
-  const token = req.headers.authorization;
-  if (!token) {
-    return res.unauthorized({ error: 'Authentication required' });
-  }
-
-  req.user = { id: 1 };
-  next();
-};
-```