balda-js 0.0.1 → 0.0.3

package/docs/docs/plugins/swagger.md

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

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