balda-js 0.0.1

package/docs/docs/getting-started/configuration.md

@@ -0,0 +1,168 @@
+---
+sidebar_position: 3
+---
+
+# Configuration
+
+Learn how to configure your Balda.js server with various options and plugins.
+
+## Server Configuration
+
+The `Server` constructor accepts a configuration object with the following options:
+
+```typescript
+import { Server } from 'balda-js';
+
+const server = new Server({
+  port: 3000,                    // Server port (default: 80)
+  host: '0.0.0.0',             // Server host (default: '0.0.0.0')
+  controllerPatterns: [          // Controller file patterns
+    './controllers/**/*.ts'
+  ],
+  plugins: {                     // Global Plugin configuration
+    cors: { origin: '*' },
+    json: { sizeLimit: '1mb' }
+  },
+  swagger: true,                 // Enable Swagger docs (default: true)
+  tapOptions: {}                 // Runtime-specific options applied before start
+});
+```
+
+## Plugin Configuration
+
+### CORS Plugin
+
+Configure Cross-Origin Resource Sharing:
+
+```typescript
+plugins: {
+  cors: {
+    origin: ['http://localhost:3000', 'https://myapp.com'],
+    methods: ['GET', 'POST', 'PUT', 'DELETE'],
+    allowedHeaders: ['Content-Type', 'Authorization'],
+    credentials: true
+  }
+}
+```
+
+### JSON Plugin
+
+Configure JSON body parsing:
+
+```typescript
+plugins: {
+  json: {
+    sizeLimit: '10mb',           // Maximum request body size
+    strict: true,                // Strict JSON parsing
+    type: 'application/json'     // Content type to parse
+  }
+}
+```
+
+### Static Files Plugin
+
+Serve static files:
+
+```typescript
+plugins: {
+  static: {
+    root: './public',            // Static files directory
+    prefix: '/static',           // URL prefix (optional)
+    index: 'index.html'          // Default index file
+  }
+}
+```
+
+### Cookie Plugin
+
+Configure cookie parsing:
+
+```typescript
+plugins: {
+  cookie: {
+    secret: 'your-secret-key',   // Secret for signed cookies
+    secure: false,               // HTTPS only (production: true)
+    httpOnly: true,              // Prevent XSS attacks
+    sameSite: 'Strict'           // CSRF protection
+  }
+}
+```
+
+### Helmet Plugin
+
+Configure security headers:
+
+```typescript
+plugins: {
+  helmet: {
+    contentSecurityPolicy: {
+      directives: {
+        defaultSrc: ["'self'"],
+        styleSrc: ["'self'", "'unsafe-inline'"],
+        scriptSrc: ["'self'"]
+      }
+    },
+    hsts: {
+      maxAge: 31536000,
+      includeSubDomains: true
+    }
+  }
+}
+```
+
+### Rate Limiter Plugin
+
+Configure request rate limiting:
+
+```typescript
+plugins: {
+  rateLimiter: {
+    windowMs: 15 * 60 * 1000,    // 15 minutes
+    max: 100,                    // Limit each IP to 100 requests per window
+    message: 'Too many requests',
+    standardHeaders: true,
+    legacyHeaders: false
+  }
+}
+```
+
+### Log Plugin
+
+Configure request/response logging:
+
+```typescript
+plugins: {
+  log: {
+    logRequest: true,            // Log incoming requests
+    logResponse: true,           // Log responses
+    logError: true,              // Log errors
+    format: 'combined'           // Log format
+  }
+}
+```
+
+### File Upload Plugin
+
+Configure file upload handling:
+
+```typescript
+plugins: {
+  file: {
+    maxFileSize: '10mb',         // Maximum file size
+  }
+}
+```
+
+### URL Encoded Plugin
+
+Configure www-urlencoded data parsing:
+
+```typescript
+plugins: {
+  urlencoded: {
+    extended: true,              // Use qs library for parsing
+    limit: '10mb',               // Maximum body size
+    parameterLimit: 1000         // Maximum parameters
+  }
+}
+```

package/docs/docs/getting-started/installation.md

@@ -0,0 +1,125 @@
+---
+sidebar_position: 1
+---
+
+# Installation
+
+Balda.js supports multiple JavaScript runtimes. Choose the installation method that best fits your project.
+
+## Prerequisites
+
+- **Node.js**: Version 18 or higher
+- **Bun**: Version 1.0 or higher
+- **Deno**: Version 1.40 or higher
+- **TypeScript**: Version 5.0 or higher (recommended)
+
+## Installation Options
+
+### Node.js
+
+```bash
+# Using npm
+npm install balda-js
+
+# Using yarn
+yarn add balda-js
+
+# Using pnpm
+pnpm add balda-js
+```
+
+### Bun
+
+```bash
+# Using bun
+bun add balda-js
+```
+
+### Deno
+
+```typescript
+// deno.json
+{
+  "imports": {
+    "balda-js": "npm:balda-js"
+  }
+}
+```
+
+## TypeScript Setup
+
+Balda.js is built with TypeScript and provides excellent type support. Make sure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}
+```
+
+## Development Dependencies
+
+For development, you might want to install additional packages:
+
+```bash
+# TypeScript support
+npm install -D typescript @types/node
+
+# Testing
+npm install -D vitest
+
+# Development server
+npm install -D tsx
+
+# Code formatting
+npm install -D prettier
+```
+
+## Verify Installation
+
+Create a simple test file to verify your installation:
+
+```typescript
+// test-installation.ts
+import { Server } from 'balda-js';
+
+const server = new Server({
+  port: 3000
+});
+
+server.get('/', (req, res) => {
+  res.json({ message: 'Balda.js is working!' });
+});
+
+server.listen(() => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+Run the test:
+
+```bash
+# Node.js
+npx tsx test-installation.ts
+
+# Bun
+bun run test-installation.ts
+
+# Deno
+deno run --allow-net test-installation.ts
+```
+
+Visit `http://localhost:3000` to see the welcome message.
+
+## Next Steps
+
+Now that you have Balda.js installed, check out our [Quick Start Guide](./quick-start) to build your first application.

package/docs/docs/getting-started/quick-start.md

@@ -0,0 +1,273 @@
+---
+sidebar_position: 2
+---
+
+# Quick Start
+
+Get up and running with Balda.js in minutes. This guide will walk you through creating a simple REST API.
+
+## Create Your First Server
+
+Create a new file called `server.ts`:
+
+```typescript
+import { Server, controller, get, post } from 'balda-js';
+
+// Create a new server instance
+const server = new Server({
+  port: 3000,
+  host: 'localhost',
+  plugins: {
+    cors: { origin: '*' },
+    json: { sizeLimit: '1mb' }
+  }
+});
+
+// Define a controller
+@controller('/users')
+export class UsersController {
+  private users = [
+    { id: 1, name: 'John Doe', email: 'john@example.com' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+  ];
+
+  @get('/')
+  async getAllUsers(req, res) {
+    res.json(this.users);
+  }
+
+  @get('/:id')
+  async getUserById(req, res) {
+    const id = parseInt(req.params.id);
+    const user = this.users.find(u => u.id === id);
+
+    if (!user) {
+      return res.notFound({ error: 'User not found' });
+    }
+
+    res.json(user);
+  }
+
+  @post('/')
+  async createUser(req, res) {
+    const newUser = {
+      id: this.users.length + 1,
+      ...req.body
+    };
+
+    this.users.push(newUser);
+    res.created(newUser);
+  }
+}
+
+// Start the server
+server.listen(({ port, host }) => {
+  console.log(`Server running on http://${host}:${port}`);
+});
+```
+
+## Run Your Server
+
+```bash
+# Node.js
+npx tsx server.ts
+
+# Bun
+bun run server.ts
+
+# Deno
+deno run --allow-net server.ts
+```
+
+## Test Your API
+
+Use curl or any HTTP client to test your endpoints:
+
+```bash
+# Get all users
+curl http://localhost:3000/users
+
+# Get user by ID
+curl http://localhost:3000/users/1
+
+# Create a new user
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Bob Wilson", "email": "bob@example.com"}'
+```
+
+## Add Validation
+
+Enhance your API with request validation:
+
+```typescript
+import { Server, controller, get, post, validate } from 'balda-js';
+import { Type, Static } from '@sinclair/typebox';
+
+const CreateUserSchema = Type.Object({
+  name: Type.String({ minLength: 1 }),
+  email: Type.String({ format: 'email' })
+});
+
+@controller('/users')
+export class UsersController {
+  // ... existing code ...
+
+  @post('/')
+  @validate.body(CreateUserSchema)
+  async createUser(req: Request, res: Response, body: Static<CreateUserSchema>) {
+    const newUser = {
+      id: this.users.length + 1,
+      ...body
+    };
+
+    this.users.push(newUser);
+    res.created(newUser);
+  }
+}
+```
+
+## Add Response Serialization
+
+Define response schemas for better API documentation:
+
+```typescript
+import { serialize } from 'balda-js';
+
+const UserSchema = Type.Object({
+  id: Type.Number(),
+  name: Type.String(),
+  email: Type.String()
+});
+
+@controller('/users')
+export class UsersController {
+  @get('/')
+  @serialize(Type.Array(UserSchema))
+  async getAllUsers(req, res) {
+    res.json(this.users);
+  }
+
+  @get('/:id')
+  @serialize(UserSchema)
+  async getUserById(req, res) {
+    // ... existing code ...
+  }
+}
+```
+
+## Add Middleware
+
+Use middleware for cross-cutting concerns:
+
+```typescript
+import { middleware, Request, Response } from 'balda-js';
+
+// Custom middleware
+const logger = (req: Request, res: Response, next: () => void) => {
+  console.log(`${req.method} ${req.url} - ${new Date().toISOString()}`);
+  await next();
+  console.log(`${res} ${req.url} - ${new Date().toISOString()}`);
+};
+
+@controller('/users')
+@middleware(logger)
+export class UsersController {
+  // All routes in this controller will use the logger middleware
+}
+```
+
+## Complete Example
+
+Here's a complete example with all the features:
+
+```typescript
+import {
+  Server,
+  controller,
+  get,
+  post,
+  validate,
+  serialize,
+  middleware
+} from 'balda-js';
+import { Type } from '@sinclair/typebox';
+
+const server = new Server({
+  port: 3000,
+  plugins: {
+    cors: { origin: '*' },
+    json: { sizeLimit: '1mb' },
+    log: { logResponse: true }
+  }
+});
+
+const UserSchema = Type.Object({
+  id: Type.Number(),
+  name: Type.String(),
+  email: Type.String()
+});
+
+const CreateUserSchema = Type.Object({
+  name: Type.String({ minLength: 1 }),
+  email: Type.String({ format: 'email' })
+});
+
+const logger = (req, res, next) => {
+  console.log(`${req.method} ${req.url}`);
+  next();
+};
+
+@controller('/users')
+@middleware(logger)
+export class UsersController {
+  private users = [
+    { id: 1, name: 'John Doe', email: 'john@example.com' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+  ];
+
+  @get('/')
+  @serialize(Type.Array(UserSchema))
+  async getAllUsers(req, res) {
+    res.json(this.users);
+  }
+
+  @get('/:id')
+  @serialize(UserSchema)
+  async getUserById(req, res) {
+    const id = parseInt(req.params.id);
+    const user = this.users.find(u => u.id === id);
+
+    if (!user) {
+      return res.notFound({ error: 'User not found' });
+    }
+
+    res.json(user);
+  }
+
+  @post('/')
+  @validate.body(CreateUserSchema)
+  @serialize(UserSchema)
+  async createUser(req, res, body) {
+    const newUser = {
+      id: this.users.length + 1,
+      ...body
+    };
+
+    this.users.push(newUser);
+    res.created(newUser);
+  }
+}
+
+server.listen(({ port, host }) => {
+  console.log(`🚀 Server running on http://${host}:${port}`);
+  console.log(`📚 API Documentation: http://${host}:${port}/docs`);
+});
+```
+
+## What's Next?
+
+- Learn about [Core Concepts](../core-concepts/server) to understand how Balda.js works
+- Explore [Plugins](../plugins/overview) to add more functionality
+- Check out [Examples](../examples/rest-api) for more complex use cases
+- Read the [Server API reference](../core-concepts/server) for detailed documentation

package/docs/docs/intro.md

@@ -0,0 +1,46 @@
+---
+id: intro
+title: Balda.js at a Glance
+sidebar_position: 0
+slug: /
+---
+
+# Balda.js
+
+Balda.js is a runtime-agnostic backend framework that lets you write once and run anywhere—**Node.js**, **Bun**, and **Deno**—without changing a single line of code. Its minimal core and decorator-based API make building fast, type-safe HTTP services straightforward and clean.
+
+## Key Ideas
+
+- **Cross-Runtime**: One codebase, three runtimes. Choose the engine that best suits your deployment without vendor lock-in. It uses web apis that are available in all the runtimes and underling uses the specific `Deno` (Deno.serve), `Bun`(Bun.serve) or `Node.js`(http.createServer) APIs.
+- **Performance First**: Tight, low-overhead abstractions keep the request/response path lean.
+- **TypeScript-Native**: Written in TypeScript from the ground up for rich typings and editor autocompletion.
+- **Batteries Included**: Controllers, middleware, validation, serialization, cron jobs, CLI, and a plugin ecosystem supplied out of the box.
+- **Elegant API**: Decorators for routes and middleware promote self-documenting code and clean project structure.
+- **Swagger/OpenAPI**: Built-in support for Swagger/OpenAPI documentation that merges with your codebase since validators and serializers directly generate the OpenAPI schema without any additional effort.
+- **Validation**: Balda uses `ajv` for body and query strings validations under the hood, schemas can be built with `@sinclair/typebox` that provides a zod-like apis.
+
+## Tiny Example
+
+```typescript
+import { Server, get, controller, Request, Response } from 'balda-js';
+
+const server = new Server({ port: 3000 });
+
+@controller()
+class WelcomeController {
+  @get('/')
+  async hello(_: Request, res: response) {
+    res.text('Hello, World!');
+  }
+}
+
+server.listen();
+```
+
+## Learn More
+
+- Start with the two-minute [Quick Start](./getting-started/quick-start)
+- Understand the [Server lifecycle](./core-concepts/server)
+- Explore [Plugins](./plugins/overview) to add CORS, logging, rate-limiting, and more
+
+Balda.js—**simple**, **fast**, and **everywhere**.