balda-js 0.0.1

package/docs/docs/plugins/swagger.md

@@ -0,0 +1,411 @@
+---
+sidebar_position: 9
+---
+
+# Swagger Plugin
+
+The Swagger plugin automatically generates OpenAPI 3.0 documentation for your Balda.js API. It provides interactive documentation with three UI options: Swagger UI, ReDoc, and RapiDoc.
+
+## Features
+
+- **Automatic Route Discovery**: Automatically discovers and documents all your routes
+- **Multiple UI Options**: Choose between Swagger UI, ReDoc, or RapiDoc
+- **Type Integration**: Uses your validation schemas to generate accurate request/response documentation
+- **Security Support**: Document authentication schemes and security requirements
+- **Custom Models**: Define reusable data models for your API
+
+## Global Configuration
+
+### Basic Setup
+
+```typescript
+import { Server } from 'balda-js';
+
+const server = new Server({
+  port: 3000,
+  swagger: {
+    type: "standard", // "standard" | "redoc" | "rapidoc"
+    path: "/docs",
+    title: "My API Documentation",
+    description: "API documentation for my application",
+    version: "1.0.0",
+    servers: ["http://localhost:3000"]
+  }
+});
+```
+
+### Advanced Configuration
+
+```typescript
+const server = new Server({
+  port: 3000,
+  swagger: {
+    type: "standard",
+    path: "/api-docs",
+    title: "E-Commerce API",
+    description: "Complete API for our e-commerce platform",
+    version: "2.1.0",
+    servers: [
+      "http://localhost:3000",
+      "https://api.staging.example.com",
+      "https://api.example.com"
+    ],
+    security: [
+      { bearer: [] }
+    ],
+    securitySchemes: {
+      bearer: {
+        type: "http",
+        scheme: "bearer",
+        bearerFormat: "JWT"
+      },
+      apiKey: {
+        type: "apiKey",
+        name: "X-API-Key",
+        in: "header"
+      }
+    },
+    tags: {
+      users: {
+        description: "User management operations"
+      },
+      products: {
+        description: "Product catalog operations"
+      },
+      orders: {
+        description: "Order processing operations"
+      }
+    },
+    models: {
+      User: {
+        type: "object",
+        properties: {
+          id: { type: "string", format: "uuid" },
+          email: { type: "string", format: "email" },
+          name: { type: "string" },
+          createdAt: { type: "string", format: "date-time" }
+        },
+        required: ["email", "name"]
+      },
+      Product: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          name: { type: "string" },
+          price: { type: "number" },
+          category: { type: "string" }
+        },
+        required: ["name", "price"]
+      }
+    }
+  }
+});
+```
+
+## Route-Level Documentation
+
+### Basic Route Documentation
+
+```typescript
+import { controller, get, post } from 'balda-js';
+import { Request, Response } from 'balda-js';
+
+@controller('/users')
+export class UsersController {
+  @get('/', {
+    swagger: {
+      name: "Get All Users",
+      description: "Retrieve a list of all users",
+      service: "users",
+      responses: {
+        "200": {
+          type: "array",
+          items: { $ref: "#/components/schemas/User" }
+        }
+      }
+    }
+  })
+  async getAllUsers(req: Request, res: Response) {
+    const users = await getUsers();
+    res.json(users);
+  }
+
+  @post('/', {
+    swagger: {
+      name: "Create User",
+      description: "Create a new user account",
+      service: "users",
+      requestBody: {
+        type: "object",
+        properties: {
+          email: { type: "string", format: "email" },
+          name: { type: "string" },
+          password: { type: "string", minLength: 8 }
+        },
+        required: ["email", "name", "password"]
+      },
+      responses: {
+        "201": {
+          type: "object",
+          properties: {
+            user: { $ref: "#/components/schemas/User" },
+            message: { type: "string" }
+          }
+        },
+        "400": {
+          type: "object",
+          properties: {
+            error: { type: "string" },
+            details: { type: "array", items: { type: "string" } }
+          }
+        }
+      }
+    }
+  })
+  async createUser(req: Request, res: Response) {
+    const user = await createUser(req.body);
+    res.created({ user, message: "User created successfully" });
+  }
+}
+```
+
+### Path Parameters
+
+```typescript
+@get('/:id', {
+  swagger: {
+    name: "Get User by ID",
+    description: "Retrieve a specific user by their ID",
+    service: "users",
+    params: {
+      type: "object",
+      properties: {
+        id: { type: "string", format: "uuid" }
+      }
+    },
+    responses: {
+      "200": { $ref: "#/components/schemas/User" },
+      "404": {
+        type: "object",
+        properties: {
+          error: { type: "string" }
+        }
+      }
+    }
+  }
+})
+async getUserById(req: Request, res: Response) {
+  const { id } = req.params;
+  const user = await getUserById(id);
+  if (!user) {
+    return res.notFound({ error: "User not found" });
+  }
+  res.json(user);
+}
+```
+
+### Query Parameters
+
+```typescript
+@get('/search', {
+  swagger: {
+    name: "Search Users",
+    description: "Search users with filters",
+    service: "users",
+    query: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "Search query" },
+        limit: { type: "number", minimum: 1, maximum: 100, default: 10 },
+        offset: { type: "number", minimum: 0, default: 0 },
+        sort: { type: "string", enum: ["name", "email", "createdAt"] }
+      },
+      required: ["q"]
+    },
+    responses: {
+      "200": {
+        type: "object",
+        properties: {
+          users: {
+            type: "array",
+            items: { $ref: "#/components/schemas/User" }
+          },
+          total: { type: "number" },
+          limit: { type: "number" },
+          offset: { type: "number" }
+        }
+      }
+    }
+  }
+})
+async searchUsers(req: Request, res: Response) {
+  const { q, limit = 10, offset = 0, sort } = req.query;
+  const result = await searchUsers({ q, limit, offset, sort });
+  res.json(result);
+}
+```
+
+### Security Requirements
+
+```typescript
+@post('/profile', {
+  swagger: {
+    name: "Update Profile",
+    description: "Update user profile (requires authentication)",
+    service: "users",
+    security: [
+      { type: "bearer", bearerFormat: "JWT" }
+    ],
+    requestBody: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        bio: { type: "string" }
+      }
+    },
+    responses: {
+      "200": { $ref: "#/components/schemas/User" },
+      "401": {
+        type: "object",
+        properties: {
+          error: { type: "string" }
+        }
+      }
+    }
+  }
+})
+async updateProfile(req: Request, res: Response) {
+  // Implementation with authentication
+  const user = await updateUserProfile(req.user.id, req.body);
+  res.json(user);
+}
+```
+
+### File Upload Documentation
+
+```typescript
+@post('/avatar', {
+  swagger: {
+    name: "Upload Avatar",
+    description: "Upload user avatar image",
+    service: "users",
+    bodyType: "form-data",
+    requestBody: {
+      type: "object",
+      properties: {
+        avatar: {
+          type: "string",
+          format: "binary",
+          description: "Avatar image file"
+        }
+      },
+      required: ["avatar"]
+    },
+    responses: {
+      "200": {
+        type: "object",
+        properties: {
+          url: { type: "string", format: "uri" },
+          message: { type: "string" }
+        }
+      }
+    }
+  }
+})
+async uploadAvatar(req: Request, res: Response) {
+  const file = req.files.avatar;
+  const url = await uploadFile(file);
+  res.json({ url, message: "Avatar uploaded successfully" });
+}
+```
+
+### Excluding Routes
+
+```typescript
+@get('/internal/health', {
+  swagger: {
+    excludeFromSwagger: true
+  }
+})
+async healthCheck(req: Request, res: Response) {
+  res.json({ status: "ok" });
+}
+```
+
+## UI Options
+
+### Swagger UI (Standard)
+
+```typescript
+swagger: {
+  type: "standard",
+  path: "/docs"
+}
+```
+
+### ReDoc
+
+```typescript
+swagger: {
+  type: "redoc",
+  path: "/docs"
+}
+```
+
+### RapiDoc
+
+```typescript
+swagger: {
+  type: "rapidoc",
+  path: "/docs"
+}
+```
+
+## Integration with Validation
+
+Balda.js automatically integrates your validation schemas with Swagger documentation:
+
+```typescript
+import { Type } from '@sinclair/typebox';
+
+const CreateUserSchema = Type.Object({
+  email: Type.String({ format: 'email' }),
+  name: Type.String({ minLength: 1 }),
+  password: Type.String({ minLength: 8 })
+});
+
+@post('/', {
+  validate: { body: CreateUserSchema },
+  swagger: {
+    name: "Create User",
+    requestBody: CreateUserSchema,
+    responses: {
+      "201": { $ref: "#/components/schemas/User" },
+      "400": { $ref: "#/components/schemas/ValidationError" }
+    }
+  }
+})
+async createUser(req: Request, res: Response) {
+  // The validation schema automatically becomes the OpenAPI schema
+  const user = await createUser(req.body);
+  res.created(user);
+}
+```
+
+## Accessing Documentation
+
+Once configured, your API documentation will be available at:
+
+- **Swagger UI**: `http://localhost:3000/docs`
+- **OpenAPI JSON**: `http://localhost:3000/docs/json`
+
+The JSON specification can be used with other OpenAPI tools or imported into external documentation systems.
+
+## Best Practices
+
+1. **Use Descriptive Names**: Give your routes meaningful names and descriptions
+2. **Group Related Routes**: Use the `service` property to group related endpoints
+3. **Document All Responses**: Include success and error responses
+4. **Use Reusable Models**: Define models in the global configuration for reuse
+5. **Keep Security Simple**: Use standard security schemes when possible
+6. **Test Your Documentation**: Use the generated documentation to test your API

package/docs/docs/plugins/urlencoded.md

@@ -0,0 +1,76 @@
+---
+sidebar_position: 3
+---
+
+# URL Encoded Plugin
+
+The **URL Encoded** plugin parses `application/x-www-form-urlencoded` request bodies and exposes the parsed data on `req.body` for easy access.
+
+## Features
+
+- Parses standard HTML form submissions
+- Supports nested objects and arrays
+- Configurable size limit
+- Works across Node.js, Bun, and Deno
+
+## Basic Usage
+
+```typescript
+import { Server } from 'balda-js';
+
+const server = new Server({
+  plugins: {
+    urlencoded: true  // Enable with default options
+  }
+});
+```
+
+## Custom Configuration
+
+```typescript
+const server = new Server({
+  plugins: {
+    urlencoded: {
+      limit: '2mb',     // Maximum body size
+      extended: true    // Use qs library for rich objects (default: true)
+    }
+  }
+});
+```
+
+## Disabling the Plugin
+
+```typescript
+const server = new Server({
+  plugins: {
+    urlencoded: false  // Disable entirely
+  }
+});
+```
+
+## Options Reference
+
+| Option   | Type    | Default | Description                                   |
+|----------|---------|---------|-----------------------------------------------|
+| `limit`  | string  | `1mb`   | Maximum allowed body size before rejection    |
+| `extended` | boolean | `true` | Use rich object parsing (qs) if `true`, or the built-in querystring parser if `false` |
+
+## Example Route
+
+```typescript
+import { post, Server } from 'balda-js';
+
+@post('/submit')
+async handleSubmit(req, res) {
+  const data = req.body;  // Parsed form data
+  res.json({ received: data });
+}
+
+const server = new Server({
+  plugins: { urlencoded: true }
+});
+
+server.listen();
+```
+
+The URL Encoded plugin makes handling traditional HTML form submissions in Balda.js straightforward and type-safe.