balda-js 0.0.1 → 0.0.2

package/docs/docs/plugins/overview.md

@@ -1,390 +0,0 @@
----
-sidebar_position: 1
----
-
-# Plugins Overview
-
-Balda.js provides a comprehensive plugin system that allows you to extend the framework's functionality with additional features and middleware.
-Those are included by default in the framework as a standard library, you can use them directly or as a reference to create your own plugins.
-
-## What are Plugins?
-
-Plugins in Balda.js are modular components that add specific functionality to your application. They can provide:
-
-- **Middleware**: Request/response processing
-- **Body Parsing**: JSON, form data, file uploads
-- **Security**: CORS, Helmet, rate limiting
-- **Documentation**: Swagger/OpenAPI
-- **Utilities**: Logging, cookies, static file serving
-
-## Built-in Plugins
-
-Balda.js comes with several built-in plugins:
-
-### Core Plugins
-
-- **[CORS](./cors.md)** - Cross-Origin Resource Sharing
-- **[JSON](./json.md)** - JSON body parsing
-- **[Static](./static.md)** - Static file serving
-- **[Cookie](./cookie.md)** - Cookie parsing and management
-
-### Security Plugins
-
-- **[Helmet](./helmet.md)** - Security headers
-- **[Rate Limiter](./rate-limiter.md)** - Request rate limiting
-
-### Utility Plugins
-
-- **[Log](./log.md)** - Request logging
-- **[File](./file.md)** - File upload handling
-- **[URL Encoded](./urlencoded.md)** - Form data parsing
-
-### Documentation Plugins
-
-- **[Swagger](./swagger.md)** - API documentation
-
-## Plugin Configuration
-
-### Basic Configuration
-
-Plugins are configured through the server options:
-
-```typescript
-import { Server } from 'balda-js';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cors: {
-      origin: ['http://localhost:3000'],
-      credentials: true
-    },
-    json: {
-      limit: '10mb'
-    },
-    static: {
-      root: './public'
-    }
-  }
-});
-```
-
-### Environment-based Configuration
-
-```typescript
-const isProduction = process.env.NODE_ENV === 'production';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cors: {
-      origin: isProduction
-        ? ['https://myapp.com']
-        : ['http://localhost:3000']
-    },
-    helmet: isProduction ? {} : false,
-    rateLimiter: isProduction ? {
-      windowMs: 15 * 60 * 1000, // 15 minutes
-      max: 100 // limit each IP to 100 requests per windowMs
-    } : false
-  }
-});
-```
-
-## Plugin Order
-
-Plugins are applied in a specific order to ensure proper functionality:
-
-1. **CORS** - Handle cross-origin requests first
-2. **Helmet** - Apply security headers
-3. **Rate Limiter** - Check request limits
-4. **Body Parsers** - Parse request bodies
-   - JSON
-   - URL Encoded
-   - File uploads
-5. **Cookie** - Parse cookies
-6. **Log** - Log requests
-7. **Static** - Serve static files
-8. **Swagger** - API documentation
-
-## Plugin Options
-
-### Enabling/Disabling Plugins
-
-```typescript
-const server = new Server({
-  plugins: {
-    cors: true,        // Use default configuration
-    json: false,       // Disable plugin
-    static: {          // Custom configuration
-      root: './public'
-    }
-  }
-});
-```
-
-### Plugin-specific Options
-
-Each plugin has its own configuration options:
-
-```typescript
-const server = new Server({
-  plugins: {
-    cors: {
-      origin: ['http://localhost:3000'],
-      methods: ['GET', 'POST', 'PUT', 'DELETE'],
-      credentials: true
-    },
-    json: {
-      limit: '10mb',
-      strict: true
-    },
-    static: {
-      root: './public',
-      prefix: '/static'
-    },
-    rateLimiter: {
-      windowMs: 15 * 60 * 1000,
-      max: 100
-    }
-  }
-});
-```
-
-## Custom Plugins
-
-### Creating a Custom Plugin
-
-```typescript
-import { ServerPlugin } from 'balda-js';
-
-export class CustomPlugin implements ServerPlugin {
-  name = 'custom';
-
-  apply(server: Server) {
-    // Add middleware
-    server.use((req, res, next) => {
-      console.log('Custom plugin middleware');
-      next();
-    });
-
-    // Add routes
-    server.get('/custom', (req, res) => {
-      res.json({ message: 'Custom plugin route' });
-    });
-  }
-}
-
-// Usage
-const server = new Server({
-  plugins: {
-    custom: new CustomPlugin()
-  }
-});
-```
-
-### Plugin with Configuration
-
-```typescript
-interface CustomPluginOptions {
-  message?: string;
-  enabled?: boolean;
-}
-
-export class CustomPlugin implements ServerPlugin {
-  name = 'custom';
-  private options: CustomPluginOptions;
-
-  constructor(options: CustomPluginOptions = {}) {
-    this.options = {
-      message: 'Hello from custom plugin',
-      enabled: true,
-      ...options
-    };
-  }
-
-  apply(server: Server) {
-    if (!this.options.enabled) {
-      return;
-    }
-
-    server.use((req, res, next) => {
-      console.log(this.options.message);
-      next();
-    });
-  }
-}
-
-// Usage
-const server = new Server({
-  plugins: {
-    custom: {
-      message: 'Custom message',
-      enabled: true
-    }
-  }
-});
-```
-
-## Plugin Lifecycle
-
-### Initialization
-
-1. Server creates plugin instances
-2. Plugins are validated
-3. Plugins are applied in order
-4. Middleware is registered
-
-### Request Processing
-
-1. Request enters plugin middleware chain
-2. Each plugin processes the request
-3. Request reaches route handlers
-4. Response flows back through plugins
-
-## Best Practices
-
-### 1. Configure Based on Environment
-
-```typescript
-const isProduction = process.env.NODE_ENV === 'production';
-
-const server = new Server({
-  plugins: {
-    cors: {
-      origin: isProduction
-        ? process.env.ALLOWED_ORIGINS?.split(',')
-        : ['http://localhost:3000'],
-      credentials: true
-    },
-    helmet: isProduction ? {} : false,
-    rateLimiter: isProduction ? {
-      windowMs: 15 * 60 * 1000,
-      max: 100
-    } : false
-  }
-});
-```
-
-### 2. Use Appropriate Limits
-
-```typescript
-const server = new Server({
-  plugins: {
-    json: {
-      limit: '10mb'  // Reasonable limit for JSON payloads
-    },
-    file: {
-      maxFileSize: '5mb',  // Limit file uploads
-      maxFiles: 10
-    }
-  }
-});
-```
-
-### 3. Secure Your Application
-
-```typescript
-const server = new Server({
-  plugins: {
-    helmet: {
-      contentSecurityPolicy: {
-        directives: {
-          defaultSrc: ["'self'"],
-          styleSrc: ["'self'", "'unsafe-inline'"],
-          scriptSrc: ["'self'"]
-        }
-      }
-    },
-    cors: {
-      origin: ['https://myapp.com'],
-      credentials: true
-    }
-  }
-});
-```
-
-### 4. Monitor and Log
-
-```typescript
-const server = new Server({
-  plugins: {
-    log: {
-      level: 'info',
-      format: 'combined'
-    },
-    rateLimiter: {
-      windowMs: 15 * 60 * 1000,
-      max: 100,
-      message: 'Too many requests from this IP'
-    }
-  }
-});
-```
-
-### 5. Optimize for Performance
-
-```typescript
-const server = new Server({
-  plugins: {
-    static: {
-      root: './public',
-      maxAge: '1d',  // Cache static files
-      etag: true
-    },
-    json: {
-      limit: '1mb'  // Reasonable limit
-    }
-  }
-});
-```
-
-## Plugin Compatibility
-
-### Runtime Support
-
-All built-in plugins work across all supported runtimes:
-
-- **Node.js**: Full support
-- **Bun**: Full support
-- **Deno**: Full support
-
-### Plugin Dependencies
-
-Some plugins may have runtime-specific dependencies:
-
-```typescript
-// Plugin automatically detects runtime and uses appropriate implementation
-const server = new Server({
-  plugins: {
-    file: {
-      // Works on Node.js, Bun, and Deno
-      storage: 'memory'  // or 'disk'
-    }
-  }
-});
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Plugin not working**: Check plugin order and configuration
-2. **CORS errors**: Verify origin configuration
-3. **File upload failures**: Check file size limits and storage configuration
-4. **Rate limiting too strict**: Adjust window and max request settings
-
-### Debugging
-
-Enable debug logging to troubleshoot plugin issues:
-
-```typescript
-const server = new Server({
-  debug: true,  // Enable debug logging
-  plugins: {
-    // Your plugin configuration
-  }
-});
-```
-
-Plugins in Balda.js provide a powerful and flexible way to extend your application with additional functionality while maintaining clean, modular code.

package/docs/docs/plugins/rate-limiter.md

@@ -1,347 +0,0 @@
----
-sidebar_position: 7
----
-
-# Rate Limiter Plugin
-
-The Rate Limiter plugin helps protect your Balda.js application from abuse by limiting the number of requests a client can make within a specified time window. It supports both IP-based and custom key-based rate limiting with flexible storage options.
-
-## Features
-
-- **IP-Based Limiting**: Limit requests per IP address
-- **Custom Key Limiting**: Limit requests based on custom criteria (user ID, API key, etc.)
-- **Flexible Storage**: In-memory storage with custom storage support
-- **Configurable Limits**: Set custom request limits and time windows
-- **Customizable Responses**: Configure error messages and status codes
-
-## Basic Configuration
-
-### Simple IP-Based Limiting
-
-```typescript
-import { Server } from 'balda-js';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    rateLimiter: {
-      type: "ip",
-      limit: 100,
-      windowMs: 60000 // 1 minute
-    }
-  }
-});
-```
-
-### Custom Key-Based Limiting
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    rateLimiter: {
-      type: "custom",
-      key: (req) => req.headers.get('X-API-Key') || req.ip,
-      limit: 50,
-      windowMs: 60000
-    }
-  }
-});
-```
-
-## Configuration Options
-
-### IP-Based Rate Limiting
-
-```typescript
-rateLimiter: {
-  type: "ip",
-  limit: 100,                    // Requests per window
-  windowMs: 60000,              // Time window in milliseconds
-  message: "Too many requests",  // Custom error message
-  statusCode: 429               // Custom status code
-}
-```
-
-### Custom Key-Based Rate Limiting
-
-```typescript
-rateLimiter: {
-  type: "custom",
-  key: (req) => {
-    // Custom key generation logic
-    return req.headers.get('X-API-Key') || req.ip;
-  },
-  limit: 50,
-  windowMs: 60000,
-  message: "Rate limit exceeded",
-  statusCode: 429
-}
-```
-
-### Storage Configuration
-
-```typescript
-rateLimiter: {
-  type: "ip",
-  limit: 100,
-  windowMs: 60000,
-  storageStrategy: "memory", // Default: "memory"
-  // For custom storage:
-  storageStrategy: "custom",
-  get: async (key) => { /* custom get logic */ },
-  set: async (key, value) => { /* custom set logic */ }
-}
-```
-
-## Usage Examples
-
-### Basic Rate Limiting
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    rateLimiter: {
-      type: "ip",
-      limit: 100,
-      windowMs: 60000 // 1 minute
-    }
-  }
-});
-
-@controller('/api')
-export class ApiController {
-  @get('/users')
-  async getUsers(req: Request, res: Response) {
-    // This endpoint is rate limited to 100 requests per minute per IP
-    const users = await getUsers();
-    res.json(users);
-  }
-}
-```
-
-### Different Limits for Different Endpoints
-
-```typescript
-@controller('/api')
-export class ApiController {
-  @get('/public', {
-    middleware: [rateLimiter({
-      type: "ip",
-      limit: 1000,
-      windowMs: 60000
-    })]
-  })
-  async publicEndpoint(req: Request, res: Response) {
-    // 1000 requests per minute
-    res.json({ message: 'Public endpoint' });
-  }
-
-  @get('/sensitive', {
-    middleware: [rateLimiter({
-      type: "ip",
-      limit: 10,
-      windowMs: 60000
-    })]
-  })
-  async sensitiveEndpoint(req: Request, res: Response) {
-    // 10 requests per minute
-    res.json({ message: 'Sensitive endpoint' });
-  }
-}
-```
-
-### User-Based Rate Limiting
-
-```typescript
-@controller('/api')
-export class UserController {
-  @get('/profile', {
-    middleware: [rateLimiter({
-      type: "custom",
-      key: (req) => {
-        // Rate limit by user ID from JWT token
-        const token = req.headers.get('Authorization')?.replace('Bearer ', '');
-        const decoded = jwt.verify(token, process.env.JWT_SECRET);
-        return decoded.userId;
-      },
-      limit: 50,
-      windowMs: 60000
-    })]
-  })
-  async getProfile(req: Request, res: Response) {
-    // 50 requests per minute per user
-    const profile = await getUserProfile(req.user.id);
-    res.json(profile);
-  }
-}
-```
-
-### API Key-Based Rate Limiting
-
-```typescript
-@controller('/api')
-export class ApiKeyController {
-  @get('/data', {
-    middleware: [rateLimiter({
-      type: "custom",
-      key: (req) => req.headers.get('X-API-Key'),
-      limit: 1000,
-      windowMs: 60000
-    })]
-  })
-  async getData(req: Request, res: Response) {
-    // 1000 requests per minute per API key
-    const data = await getData();
-    res.json(data);
-  }
-}
-```
-
-## Advanced Configuration
-
-### Multiple Rate Limiters
-
-```typescript
-@controller('/api')
-export class AdvancedController {
-  @get('/complex', {
-    middleware: [
-      // IP-based rate limiting
-      rateLimiter({
-        type: "ip",
-        limit: 100,
-        windowMs: 60000
-      }),
-      // User-based rate limiting
-      rateLimiter({
-        type: "custom",
-        key: (req) => req.user?.id || req.ip,
-        limit: 20,
-        windowMs: 60000
-      })
-    ]
-  })
-  async complexEndpoint(req: Request, res: Response) {
-    // Must pass both rate limiters
-    res.json({ message: 'Complex endpoint' });
-  }
-}
-```
-
-### Custom Storage Implementation
-
-```typescript
-// Redis storage example
-const redisStorage = {
-  get: async (key: string) => {
-    const value = await redis.get(`rate_limit:${key}`);
-    return value ? parseInt(value) : 0;
-  },
-  set: async (key: string, value: number) => {
-    await redis.setex(`rate_limit:${key}`, 60, value.toString());
-  }
-};
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    rateLimiter: {
-      type: "ip",
-      limit: 100,
-      windowMs: 60000,
-      storageStrategy: "custom",
-      get: redisStorage.get,
-      set: redisStorage.set
-    }
-  }
-});
-```
-
-### Environment-Based Configuration
-
-```typescript
-const isProduction = process.env.NODE_ENV === 'production';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    rateLimiter: {
-      type: "ip",
-      limit: isProduction ? 100 : 1000, // Stricter in production
-      windowMs: 60000,
-      message: isProduction ? "Rate limit exceeded" : "Too many requests",
-      statusCode: 429
-    }
-  }
-});
-```
-
-## Error Handling
-
-### Rate Limit Exceeded Response
-
-```typescript
-// Default response when rate limit is exceeded
-{
-  "message": "ERR_RATE_LIMIT_EXCEEDED"
-}
-
-// Custom response
-{
-  "message": "Too many requests, please try again later"
-}
-```
-
-### Custom Error Handling
-
-```typescript
-@controller('/api')
-export class ErrorController {
-  @get('/limited', {
-    middleware: [rateLimiter({
-      type: "ip",
-      limit: 5,
-      windowMs: 60000,
-      message: "You've exceeded the rate limit",
-      statusCode: 429
-    })]
-  })
-  async limitedEndpoint(req: Request, res: Response) {
-    res.json({ message: 'Success' });
-  }
-}
-```
-
-## Storage Strategies
-
-### In-Memory Storage (Default)
-
-```typescript
-rateLimiter: {
-  type: "ip",
-  limit: 100,
-  windowMs: 60000,
-  storageStrategy: "memory" // Default
-}
-```
-
-### Custom Storage
-
-```typescript
-rateLimiter: {
-  type: "ip",
-  limit: 100,
-  windowMs: 60000,
-  storageStrategy: "custom",
-  get: async (key: string) => {
-    // Custom get implementation
-    return await yourStorage.get(key);
-  },
-  set: async (key: string, value: number) => {
-    // Custom set implementation
-    await yourStorage.set(key, value, 60); // 60 seconds TTL
-  }
-}
-```