balda-js 0.0.1 → 0.0.2

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

@@ -1,388 +0,0 @@
----
-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

@@ -1,332 +0,0 @@
----
-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.