balda-js 0.0.1 → 0.0.3

package/docs/docs/core-concepts/request-response.md

@@ -1,486 +0,0 @@
----
-sidebar_position: 5
----
-
-# Request & Response
-
-Balda.js provides a clean and intuitive API for handling HTTP requests and responses. The framework extends the standard Node.js request and response objects with additional convenience methods and properties.
-
-## Request Object
-
-The request object contains information about the incoming HTTP request.
-
-### Basic Properties
-
-```typescript
-interface Request {
-  method: string;           // HTTP method (GET, POST, etc.)
-  url: string;              // Request URL
-  path: string;             // Request path
-  headers: Record<string, string>; // Request headers
-  query: Record<string, string>;   // Query parameters
-  params: Record<string, string>;  // Route parameters
-  body: any;                // Request body (parsed)
-  ip: string;               // Client IP address
-  cookies: Record<string, string>; // Request cookies
-}
-```
-
-### Accessing Request Data
-
-```typescript
-@get('/users/:id')
-async getUser(req: Request, res: Response) {
-  // Route parameters
-  const userId = req.params.id;
-
-  // Query parameters
-  const { page = 1, limit = 10 } = req.query;
-
-  // Headers
-  const userAgent = req.headers['user-agent'];
-  const authToken = req.headers.authorization;
-
-  // Request body (for POST/PUT/PATCH)
-  const userData = req.body;
-
-  // Client IP
-  const clientIP = req.ip;
-
-  res.json({ userId, page, limit, userAgent, clientIP });
-}
-```
-
-### File Uploads
-
-```typescript
-import { Request, Response, fileParser } from 'balda-js';
-
-@post('/upload')
-@middleware(fileParser())
-async uploadFile(req: Request, res: Response) {
-  const file = req.file('file');
-
-  if (!file) {
-    return res.badRequest({ error: 'No file uploaded' });
-  }
-
-  res.json({
-    filename: file.originalName,
-    size: file.size,
-    mimetype: file.mimeType
-  });
-}
-```
-
-## Response Object
-
-The response object provides methods for sending HTTP responses.
-
-### Status Methods
-
-```typescript
-import { Request, Response } from 'balda-js';
-
-@get('/users')
-async getUsers(req: Request, res: Response) {
-  // Success responses
-  res.ok({ users: [] });                    // 200 OK
-  res.created({ id: 1 });                   // 201 Created
-  res.noContent();                          // 204 No Content
-
-  // Client error responses
-  res.badRequest({ error: 'Invalid data' }); // 400 Bad Request
-  res.unauthorized({ error: 'Auth required' }); // 401 Unauthorized
-  res.forbidden({ error: 'Access denied' });    // 403 Forbidden
-  res.notFound({ error: 'User not found' });    // 404 Not Found
-  res.conflict({ error: 'User exists' });       // 409 Conflict
-  res.tooManyRequests({ error: 'Rate limited' }); // 429 Too Many Requests
-
-  // Server error responses
-  res.internalServerError({ error: 'Server error' }); // 500 Internal Server Error
-  res.notImplemented({ error: 'Not implemented' });   // 501 Not Implemented
-  res.badGateway({ error: 'Bad gateway' });           // 502 Bad Gateway
-  res.serviceUnavailable({ error: 'Unavailable' });   // 503 Service Unavailable
-}
-```
-
-### Content Methods
-
-```typescript
-import { Request, Response } from 'balda-js';
-
-@get('/api/data')
-async getData(req: Request, res: Response) {
-  // Manually set headers
-  res.setHeader('X-Custom-Header', 'value');
-
-  // JSON response
-  res.json({ message: 'Hello World' });
-
-  // Text response
-  res.text('Hello World');
-
-  // HTML response
-  res.html('<h1>Hello World</h1>');
-
-  // Redirect
-  res.redirect('/new-location');
-
-  // Download file
-  res.download('/path/to/file.pdf', 'filename.pdf');
-
-  // Send tries to understand the best content type to send based on the body (better to use specific methods)
-  res.send({ message: 'Hello World' });
-}
-```
-
-### Header Management
-
-```typescript
-import { Request, Response } from 'balda-js';
-
-@get('/api/data')
-async getData(req: Request, res: Response) {
-  // Set headers
-  res.setHeader('Content-Type', 'application/json');
-  res.setHeader('Cache-Control', 'no-cache');
-
-  // Set multiple headers
-  res.setHeaders({
-    'Content-Type': 'application/json',
-    'X-Custom-Header': 'value'
-  });
-
-  // Get headers
-  const contentType = res.getHeader('Content-Type');
-
-  res.json({ data: 'value' });
-}
-```
-
-### Cookie Management
-
-```typescript
-import { Request, Response } from 'balda-js';
-
-@post('/login')
-async login(req: Request, res: Response) {
-  // Set cookies
-  res.setCookie('sessionId', 'abc123', {
-    httpOnly: true,
-    secure: true,
-    maxAge: 24 * 60 * 60 * 1000 // 24 hours
-  });
-
-  // Clear cookies
-  res.clearCookie('oldSession');
-
-  res.json({ message: 'Logged in' });
-}
-```
-
-## Request Validation
-
-### Built-in Validation
-
-The built in validation is based on the `@sinclair/typebox` library, you can use it to validate the request body or query parameters.
-The validated body is passed as the next argument to the route handler (can be stacked with other validation decorators).
-
-```typescript
-import { Request, Response, validate } from 'balda-js';
-import { Type, Static } from '@sinclair/typebox';
-
-const CreateUserSchema = Type.Object({
-  name: Type.String({ minLength: 1 }),
-  email: Type.String({ format: 'email' }),
-  age: Type.Number({ minimum: 18 })
-});
-
-@post('/users')
-@validate.body(CreateUserSchema)
-async createUser(req: Request, res: Response, body: Static<typeof CreateUserSchema>) {
-  // body is validated and typed
-  const { name, email, age } = body;
-
-  res.created({ name, email, age });
-}
-```
-
-### Query Parameter Validation
-
-```typescript
-import { Request, Response, validate } from 'balda-js';
-import { Type, Static } from '@sinclair/typebox';
-
-const QuerySchema = Type.Object({
-  page: Type.Optional(Type.Number({ minimum: 1 })),
-  limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100 }))
-});
-
-@get('/users')
-@validate.query(QuerySchema)
-async getUsers(req: Request, res: Response, query: any) {
-  const { page = 1, limit = 10 } = query;
-  res.json({ page, limit });
-}
-```
-
-## Response Serialization
-
-### Schema-based Serialization
-
-```typescript
-import { Request, Response, serialize } from 'balda-js';
-import { Type } from '@sinclair/typebox';
-
-const UserSchema = Type.Object({
-  id: Type.Number(),
-  name: Type.String(),
-  email: Type.String()
-});
-
-@get('/users')
-@serialize(Type.Array(UserSchema))
-async getUsers(req: Request, res: Response) {
-  const users = await userService.findAll();
-  res.json(users);
-}
-
-@get('/users/:id')
-@serialize(UserSchema)
-async getUser(req: Request, res: Response) {
-  const user = await userService.findById(req.params.id);
-  res.json(user);
-}
-```
-
-### Multiple Response Schemas
-
-```typescript
-import { Request, Response, serialize } from 'balda-js';
-import { Type } from '@sinclair/typebox';
-
-@get('/users/:id')
-@serialize(UserSchema)
-@serialize(Type.Object({ error: Type.String() }), { status: 404 })
-async getUser(req: Request, res: Response) {
-  const user = await userService.findById(req.params.id);
-
-  if (!user) {
-    return res.notFound({ error: 'User not found' });
-  }
-
-  res.json(user);
-}
-```
-
-## Error Handling
-
-### Custom Error Responses
-
-```typescript
-import { Request, Response } from 'balda-js';
-
-@get('/users/:id')
-async getUser(req: Request, res: Response) {
-  try {
-    const user = await userService.findById(req.params.id);
-
-    if (!user) {
-      return res.notFound({
-        error: 'User not found',
-        code: 'USER_NOT_FOUND'
-      });
-    }
-
-    res.json(user);
-  } catch (error) {
-    console.error('Error fetching user:', error);
-    res.internalServerError({
-      error: 'Failed to fetch user',
-      code: 'FETCH_ERROR'
-    });
-  }
-}
-```
-
-### Global Error Handler
-
-```typescript
-import { Server } from 'balda-js';
-
-server.setErrorHandler((req, res, next, error) => {
-  console.error('Error:', error);
-
-  if (error.name === 'ValidationError') {
-    return res.badRequest({
-      error: 'Validation failed',
-      details: error.message
-    });
-  }
-
-  if (error.name === 'UnauthorizedError') {
-    return res.unauthorized({ error: 'Authentication required' });
-  }
-
-  res.internalServerError({ error: 'Internal server error' });
-});
-```
-
-## Request Lifecycle
-
-### Middleware Chain
-
-```typescript
-import { Server, controller, get, post, middleware, validate } from 'balda-js';
-import { Request, Response } from 'balda-js';
-import { Type } from '@sinclair/typebox';
-
-// 1. Global middleware
-server.use(logger);
-server.use(cors);
-
-// 2. Controller middleware
-@controller('/users')
-@middleware(authMiddleware)
-export class UsersController {
-
-  // 3. Route middleware
-  @get('/:id', { middleware: [rateLimit] })
-  // 4. Validation
-  @validate.params(Type.Object({ id: Type.String() }))
-  // 5. Route handler
-  async getUser(req: Request, res: Response) {
-    // 6. Response serialization
-    res.json({ user: req.params.id });
-  }
-}
-```
-
-## TypeScript Support
-
-### Request Extensions
-
-```typescript
-import { Request, Response } from 'balda-js';
-
-interface AuthenticatedRequest extends Request {
-  user: {
-    id: number;
-    email: string;
-    role: string;
-  };
-}
-
-@get('/profile')
-@middleware(authMiddleware)
-async getProfile(req: AuthenticatedRequest, res: Response) {
-  // req.user is now typed
-  res.json({
-    id: req.user.id,
-    email: req.user.email,
-    role: req.user.role
-  });
-}
-```
-
-### Response Types
-
-```typescript
-import { Request, Response } from 'balda-js';
-
-interface ApiResponse<T> {
-  data: T;
-  message?: string;
-  timestamp: string;
-}
-
-@get('/users')
-async getUsers(req: Request, res: Response) {
-  const users = await userService.findAll();
-
-  const response: ApiResponse<typeof users> = {
-    data: users,
-    message: 'Users retrieved successfully',
-    timestamp: new Date().toISOString()
-  };
-
-  res.json(response);
-}
-```
-
-## Best Practices
-
-### 1. Consistent Response Format
-
-```typescript
-// Good: Consistent structure
-res.json({
-  success: true,
-  data: { id: 1, name: 'John' },
-  message: 'User created successfully'
-});
-
-// Error response
-res.badRequest({
-  success: false,
-  error: 'Validation failed',
-  details: ['Name is required']
-});
-```
-
-### 2. Proper Status Codes
-
-```typescript
-// Use appropriate status codes
-res.created({ id: 1 });        // 201 for new resources
-res.noContent();               // 204 for successful deletion
-res.badRequest({ error: '' }); // 400 for client errors
-res.notFound({ error: '' });   // 404 for missing resources
-```
-
-### 3. Input Validation
-
-```typescript
-@post('/users')
-@validate.body(CreateUserSchema)
-async createUser(req: Request, res: Response, body: CreateUser) {
-  // body is validated and typed
-  const user = await userService.create(body);
-  res.created(user);
-}
-```
-
-### 4. Error Handling
-
-```typescript
-@get('/users/:id')
-async getUser(req: Request, res: Response) {
-  try {
-    const user = await userService.findById(req.params.id);
-
-    if (!user) {
-      return res.notFound({ error: 'User not found' });
-    }
-
-    res.json(user);
-  } catch (error) {
-    console.error('Database error:', error);
-    res.internalServerError({ error: 'Failed to fetch user' });
-  }
-}
-```
-
-### 5. Security Headers
-
-```typescript
-// Set security headers
-res.setHeaders({
-  'X-Content-Type-Options': 'nosniff',
-  'X-Frame-Options': 'DENY',
-  'X-XSS-Protection': '1; mode=block'
-});
-```
-
-The request and response objects in Balda.js provide a powerful and intuitive API for building robust web applications with proper error handling, validation, and type safety.