balda-js 0.0.1

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

@@ -0,0 +1,388 @@
+---
+sidebar_position: 3
+---
+
+# Routing
+
+Balda.js provides a flexible and intuitive routing system that supports both direct route registration and controller-based routing with decorators.
+
+## Route Registration
+
+### Direct Route Registration
+
+You can register routes directly on the server instance:
+
+```typescript
+import { Server } from 'balda-js';
+
+const server = new Server({ port: 3000 });
+
+// GET route
+server.get('/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+// POST route
+server.post('/users', (req, res) => {
+  res.created(req.body);
+});
+
+// PUT route
+server.put('/users/:id', (req, res) => {
+  res.json({ id: req.params.id, ...req.body });
+});
+
+// PATCH route
+server.patch('/users/:id', (req, res) => {
+  res.json({ id: req.params.id, ...req.body });
+});
+
+// DELETE route
+server.delete('/users/:id', (req, res) => {
+  res.noContent();
+});
+```
+
+### Controller-Based Routing
+
+Controllers provide a more organized way to define routes:
+
+```typescript
+import { controller, get, post, put, del } from 'balda-js';
+
+@controller('/users')
+export class UsersController {
+  @get('/')
+  async getAllUsers(req, res) {
+    res.json({ users: [] });
+  }
+
+  @get('/:id')
+  async getUserById(req, res) {
+    res.json({ id: req.params.id });
+  }
+
+  @post('/')
+  async createUser(req, res) {
+    res.created(req.body);
+  }
+
+  @put('/:id')
+  async updateUser(req, res) {
+    res.json({ id: req.params.id, ...req.body });
+  }
+
+  @del('/:id')
+  async deleteUser(req, res) {
+    res.noContent();
+  }
+}
+```
+
+## Route Parameters
+
+### Path Parameters
+
+Define dynamic segments in your routes:
+
+```typescript
+@controller('/users')
+export class UsersController {
+  @get('/:id')
+  async getUserById(req, res) {
+    const id = req.params.id;
+    res.json({ id });
+  }
+
+  @get('/:userId/posts/:postId')
+  async getUserPost(req, res) {
+    const { userId, postId } = req.params;
+    res.json({ userId, postId });
+  }
+}
+```
+
+### Query Parameters
+
+Access query string parameters:
+
+```typescript
+@get('/users')
+async getUsers(req, res) {
+  const { page = 1, limit = 10, search } = req.query;
+
+  // Handle pagination and search
+  res.json({
+    page: parseInt(page),
+    limit: parseInt(limit),
+    search
+  });
+}
+```
+
+## Route Options
+
+### Middleware
+
+Apply middleware to specific routes:
+
+```typescript
+@get('/admin/users', { middleware: [authMiddleware, adminMiddleware] })
+async getAdminUsers(req, res) {
+  res.json({ users: [] });
+}
+```
+
+### Swagger Documentation
+
+Add OpenAPI documentation to routes:
+
+```typescript
+@get('/', {
+  swagger: {
+    summary: 'Get all users',
+    description: 'Retrieve a list of all users with pagination',
+    tags: ['Users'],
+    responses: {
+      200: {
+        description: 'List of users',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'array',
+              items: { $ref: '#/components/schemas/User' }
+            }
+          }
+        }
+      }
+    }
+  }
+})
+async getAllUsers(req, res) {
+  res.json({ users: [] });
+}
+```
+
+## Route Patterns
+
+### Static Routes
+
+```typescript
+@get('/about')
+async getAbout(req, res) {
+  res.json({ message: 'About page' });
+}
+```
+
+### Dynamic Routes
+
+```typescript
+@get('/users/:id')
+async getUser(req, res) {
+  const id = req.params.id;
+  res.json({ id });
+}
+```
+
+### Optional Parameters
+
+```typescript
+@get('/posts/:id?')
+async getPost(req, res) {
+  const id = req.params.id;
+  if (id) {
+    res.json({ id });
+  } else {
+    res.json({ posts: [] });
+  }
+}
+```
+
+### Wildcard Routes
+
+```typescript
+@get('/files/*')
+async getFile(req, res) {
+  const filePath = req.params['*'];
+  res.json({ filePath });
+}
+```
+
+## Route Precedence
+
+Routes are matched in the order they are registered. More specific routes should be defined before more general ones:
+
+```typescript
+@controller('/users')
+export class UsersController {
+  // Specific route first
+  @get('/admin')
+  async getAdminUsers(req, res) {
+    res.json({ users: [] });
+  }
+
+  // General route after
+  @get('/:id')
+  async getUserById(req, res) {
+    res.json({ id: req.params.id });
+  }
+}
+```
+
+## Route Groups
+
+Organize related routes using controllers:
+
+```typescript
+@controller('/api/v1/users')
+export class UsersController {
+  @get('/')
+  async getAllUsers(req, res) {
+    res.json({ users: [] });
+  }
+}
+
+@controller('/api/v1/posts')
+export class PostsController {
+  @get('/')
+  async getAllPosts(req, res) {
+    res.json({ posts: [] });
+  }
+}
+```
+
+## Error Handling
+
+### 404 Not Found
+
+Routes that don't match any pattern return a 404 response:
+
+```typescript
+// This will be handled by the 404 handler
+server.get('/nonexistent', (req, res) => {
+  // This won't be reached
+});
+```
+
+### Custom 404 Handler
+
+```typescript
+server.setErrorHandler((req, res, next, error) => {
+  if (error.name === 'RouteNotFoundError') {
+    return res.notFound({
+      error: 'Route not found',
+      path: req.url
+    });
+  }
+  next(error);
+});
+```
+
+## Route Testing
+
+### Mock Server
+
+Use the mock server for testing routes:
+
+```typescript
+import { Server } from 'balda-js';
+
+const server = new Server({ port: 3000 });
+
+server.get('/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+// Get mock server for testing
+const mockServer = await server.getMockServer();
+
+// Test the route
+const response = await mockServer.get('/users');
+console.log(response.statusCode()); // 200
+console.log(response.body()); // { users: [] }
+```
+
+## Best Practices
+
+### 1. Use Controllers for Organization
+
+```typescript
+// Good: Organized by resource
+@controller('/users')
+export class UsersController {}
+
+@controller('/posts')
+export class PostsController {}
+
+// Avoid: Mixed resources in one controller
+@controller('/api')
+export class ApiController {} // Too broad
+```
+
+### 2. Consistent Naming
+
+```typescript
+// Good: RESTful naming
+@get('/users')           // GET /users
+@get('/users/:id')       // GET /users/123
+@post('/users')          // POST /users
+@put('/users/:id')       // PUT /users/123
+@del('/users/:id')       // DELETE /users/123
+
+// Avoid: Inconsistent naming
+@get('/getUsers')
+@post('/createUser')
+@put('/updateUser')
+```
+
+### 3. Parameter Validation
+
+```typescript
+@get('/users/:id')
+async getUserById(req, res) {
+  const id = parseInt(req.params.id);
+
+  if (isNaN(id)) {
+    return res.badRequest({ error: 'Invalid user ID' });
+  }
+
+  res.json({ id });
+}
+```
+
+### 4. Query Parameter Handling
+
+```typescript
+@get('/users')
+async getUsers(req, res) {
+  const page = Math.max(1, parseInt(req.query.page) || 1);
+  const limit = Math.min(100, Math.max(1, parseInt(req.query.limit) || 10));
+
+  res.json({ page, limit });
+}
+```
+
+### 5. Route Documentation
+
+```typescript
+@get('/', {
+  swagger: {
+    summary: 'Get all users',
+    description: 'Retrieve a paginated list of users',
+    tags: ['Users'],
+    parameters: [
+      {
+        name: 'page',
+        in: 'query',
+        description: 'Page number',
+        schema: { type: 'integer', default: 1 }
+      }
+    ]
+  }
+})
+async getAllUsers(req, res) {
+  res.json({ users: [] });
+}
+```
+
+Balda.js routing provides a powerful and flexible system for defining your application's endpoints with support for both simple and complex routing patterns.

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

@@ -0,0 +1,332 @@
+---
+sidebar_position: 1
+---
+
+# Server
+
+The `Server` class is the main entry point for creating Balda.js applications. It handles HTTP requests, manages middleware, and orchestrates the entire application lifecycle.
+
+## Creating a Server
+
+```typescript
+import { Server } from 'balda-js';
+
+const server = new Server({
+  port: 3000,
+  host: 'localhost'
+});
+```
+
+## Server Lifecycle
+
+### 1. Initialization
+
+When you create a server instance, it:
+
+- Sets up the runtime connector (Node.js, Bun, or Deno)
+- Initializes the router
+- Applies global middleware
+- Sets up the body parser
+
+```typescript
+const server = new Server({
+  port: 3000,
+  plugins: {
+    cors: { origin: '*' },
+    json: { sizeLimit: '1mb' }
+  }
+});
+```
+
+### 2. Route Registration
+
+Routes can be registered in two ways:
+
+**Direct registration:**
+```typescript
+server.get('/users', (req, res) => {
+  res.json({ users: [] });
+});
+```
+
+**Controller-based registration:**
+```typescript
+@controller('/users')
+export class UsersController {
+  @get('/')
+  async getUsers(req, res) {
+    res.json({ users: [] });
+  }
+}
+```
+
+### 3. Server Startup
+
+When you call `server.listen()`, the server:
+
+- Imports controllers based on patterns
+- Registers all routes
+- Applies plugins
+- Starts listening for requests
+
+```typescript
+server.listen(({ port, host }) => {
+  console.log(`Server running on http://${host}:${port}`);
+});
+```
+
+## Server Configuration
+
+### Basic Options
+
+```typescript
+const server = new Server({
+  port: 3000,                    // Server port
+  host: 'localhost',             // Server host
+  controllerPatterns: [          // Controller file patterns
+    './controllers/**/*.ts'
+  ],
+  plugins: {},                   // Plugin configuration
+  swagger: true,                 // Enable Swagger docs
+  tapOptions: {}                 // Runtime-specific options
+});
+```
+
+### Advanced Configuration
+
+```typescript
+const server = new Server({
+  port: process.env.PORT || 3000,
+  host: process.env.HOST || '0.0.0.0',
+  controllerPatterns: [
+    './src/controllers/**/*.ts',
+    './src/api/**/*.ts'
+  ],
+  plugins: {
+    cors: { origin: '*' },
+    json: { sizeLimit: '10mb' },
+    static: { root: './public' }
+  },
+  swagger: {
+    type: 'standard',
+    models: {
+      User: {
+        type: 'object',
+        properties: {
+          id: { type: 'number' },
+          name: { type: 'string' }
+        }
+      }
+    }
+  }
+});
+```
+
+## Server Methods
+
+### HTTP Methods
+
+```typescript
+// GET requests
+server.get('/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+// POST requests
+server.post('/users', (req, res) => {
+  res.created({ id: 1, name: 'John' });
+});
+
+// PUT requests
+server.put('/users/:id', (req, res) => {
+  res.json({ id: req.params.id, name: 'Updated' });
+});
+
+// PATCH requests
+server.patch('/users/:id', (req, res) => {
+  res.json({ id: req.params.id, ...req.body });
+});
+
+// DELETE requests
+server.delete('/users/:id', (req, res) => {
+  res.noContent();
+});
+```
+
+### Middleware Management
+
+```typescript
+// Add global middleware
+server.use((req, res, next) => {
+  console.log(`${req.method} ${req.url}`);
+  next();
+});
+
+// Add 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();
+  }
+);
+```
+
+### Error Handling
+
+```typescript
+server.setErrorHandler((req, res, next, error) => {
+  console.error('Error:', error);
+
+  if (error.name === 'ValidationError') {
+    return res.badRequest({ error: error.message });
+  }
+
+  res.internalServerError({ error: 'Internal server error' });
+});
+```
+
+## Server Properties
+
+### Read-only Properties
+
+```typescript
+// Get server URL
+console.log(server.url); // http://localhost:3000
+
+// Get server port
+console.log(server.port); // 3000
+
+// Get server host
+console.log(server.host); // localhost
+
+// Check if server is listening
+console.log(server.isListening); // true/false
+```
+
+### Utility Methods
+
+```typescript
+// Get temporary directory
+const tmpDir = server.tmpDir('uploads', 'images');
+
+// Embed data for later use
+server.embed('config', { apiKey: 'secret' });
+
+// Get embedded data
+const config = server.embed('config');
+
+// Exit the server
+server.exit(0);
+```
+
+## Event Handling
+
+```typescript
+// Handle graceful shutdown
+server.on('SIGTERM', () => {
+  console.log('Received SIGTERM, shutting down gracefully');
+  server.close();
+});
+
+server.on('SIGINT', () => {
+  console.log('Received SIGINT, shutting down gracefully');
+  server.close();
+});
+```
+
+## Server Shutdown
+
+```typescript
+// Graceful shutdown
+async function shutdown() {
+  console.log('Shutting down server...');
+  await server.close();
+  console.log('Server shut down successfully');
+  process.exit(0);
+}
+
+// Handle shutdown signals
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+```
+
+## Runtime Support
+
+Balda.js automatically detects and adapts to your runtime:
+
+### Node.js
+```typescript
+// Uses Node.js http module
+const server = new Server({
+  port: 3000
+});
+```
+
+### Bun
+```typescript
+// Uses Bun's HTTP server
+const server = new Server({
+  port: 3000
+});
+```
+
+### Deno
+```typescript
+// Uses Deno's HTTP server
+const server = new Server({
+  port: 3000
+});
+```
+
+## Complete Example
+
+```typescript
+import { Server } from 'balda-js';
+
+const server = new Server({
+  port: 3000,
+  host: 'localhost',
+  controllerPatterns: ['./src/controllers/**/*.ts'],
+  plugins: {
+    cors: { origin: '*' },
+    json: { sizeLimit: '10mb' },
+    log: { logRequest: true }
+  }
+});
+
+// Global middleware
+server.use((req, res, next) => {
+  req.startTime = Date.now();
+  next();
+});
+
+// Error handler
+server.setErrorHandler((req, res, next, error) => {
+  console.error('Error:', error);
+  res.internalServerError({ error: 'Something went wrong' });
+});
+
+// Direct route registration
+server.get('/health', (req, res) => {
+  res.json({ status: 'ok', uptime: process.uptime() });
+});
+
+// Start server
+server.listen(({ port, host }) => {
+  console.log(`🚀 Server running on http://${host}:${port}`);
+  console.log(`📚 API Documentation: http://${host}:${port}/docs`);
+});
+
+// Graceful shutdown
+process.on('SIGTERM', () => server.close());
+process.on('SIGINT', () => server.close());
+```
+
+The Server class provides a solid foundation for building scalable web applications with Balda.js.