bxo 0.0.5-dev.7 → 0.0.5-dev.71

package/README.md

@@ -1,579 +1,225 @@
-# 🦊 BXO - A Type-Safe Web Framework for Bun
+# bxo
 
-BXO is a fast, lightweight, and fully type-safe web framework built specifically for Bun runtime. Inspired by Elysia, it provides excellent developer experience with automatic type inference, Zod validation, and a powerful plugin system.
+A fast, lightweight web framework for Bun with built-in Zod validation and lifecycle hooks.
 
-## ✨ Features
+## Features
 
-- 🚀 **Built for Bun** - Leverages Bun's native HTTP server for maximum performance
-- 🔒 **Type-Safe** - Full TypeScript support with automatic type inference
-- 📋 **Zod Validation** - Built-in request/response validation using Zod schemas
-- 🔌 **Plugin System** - Extensible architecture with lifecycle hooks
-- 🎣 **Lifecycle Hooks** - Complete control over server and request/response lifecycle
-- 🔄 **Hot Reload** - Automatic server restart on file changes during development
-- 🎮 **Server Management** - Programmatic start, stop, and restart capabilities
-- 📊 **Status Monitoring** - Built-in server status and runtime statistics
-- 📦 **Zero Dependencies** - Only depends on Zod for validation
-- ⚡ **Fast** - Minimal overhead with efficient routing
+- **Type-safe routing** with Zod schema validation
+- **Lifecycle hooks** for middleware and plugins
+- **Plugin system** for extending functionality
+- **Built-in CORS support** via plugin
+- **Fast performance** leveraging Bun's native HTTP server
 
-## 🚀 Quick Start
-
-### Installation
+## Installation
 
 ```bash
-bun add zod
+bun install
 ```
 
-### Basic Usage
+## Quick Start
 
 ```typescript
-import BXO, { z } from './index';
-
-const app = new BXO()
-  .get('/', async (ctx) => {
-    return { message: 'Hello, BXO!' };
-  })
-  .start(3000);
-```
+import BXO from "./src/index";
+import { cors } from "./plugins";
 
-## 📚 Documentation
+const app = new BXO();
 
-### HTTP Handlers
+// Use CORS plugin
+app.use(cors());
 
-BXO supports all standard HTTP methods with fluent chaining:
+// Define routes
+app.get("/", (ctx) => ctx.json({ message: "Hello World!" }));
 
-```typescript
-const app = new BXO()
-  // Simple handler
-  .get('/simple', async (ctx) => {
-    return { message: 'Hello World' };
-  })
-  
-  // With validation
-  .post('/users', async (ctx) => {
-    // ctx.body is fully typed
-    return { created: ctx.body };
-  }, {
-    body: z.object({
-      name: z.string(),
-      email: z.string().email()
-    })
-  })
-  
-  // Path parameters
-  .get('/users/:id', async (ctx) => {
-    // ctx.params.id is typed as UUID string
-    return { user: { id: ctx.params.id } };
-  }, {
-    params: z.object({ 
-      id: z.string().uuid() 
-    }),
-    query: z.object({ 
-      include: z.string().optional() 
-    })
-  })
-  
-  // All HTTP methods supported
-  .put('/users/:id', handler)
-  .delete('/users/:id', handler)
-  .patch('/users/:id', handler);
+app.start();
 ```
 
-### Context Object
-
-The context object (`ctx`) provides access to request data and response configuration:
-
-```typescript
-interface Context<TConfig> {
-  params: InferredParamsType;    // Path parameters
-  query: InferredQueryType;      // Query string parameters  
-  body: InferredBodyType;        // Request body
-  headers: InferredHeadersType;  // Request headers
-  request: Request;              // Original Request object
-  set: {                         // Response configuration
-    status?: number;
-    headers?: Record<string, string>;
-  };
-  user?: any;                    // Added by auth plugin
-  [key: string]: any;            // Extended by plugins
-}
-```
+## Lifecycle Hooks
 
-### Validation Configuration
+BXO provides powerful lifecycle hooks that allow you to intercept and modify requests and responses at different stages:
 
-Each route can specify validation schemas for different parts of the request:
+### beforeRequest
+Runs before any route processing. Can modify the request or return a response to short-circuit processing.
 
 ```typescript
-const config = {
-  params: z.object({ id: z.string().uuid() }),
-  query: z.object({ 
-    page: z.coerce.number().default(1),
-    limit: z.coerce.number().max(100).default(10)
-  }),
-  body: z.object({
-    name: z.string().min(1),
-    email: z.string().email()
-  }),
-  headers: z.object({
-    'content-type': z.literal('application/json')
-  })
-};
-
-app.post('/api/users/:id', async (ctx) => {
-  // All properties are fully typed based on schemas
-  const { id } = ctx.params;           // string (UUID)
-  const { page, limit } = ctx.query;   // number, number
-  const { name, email } = ctx.body;    // string, string
-}, config);
+app.beforeRequest(async (req) => {
+  console.log(`${req.method} ${req.url}`);
+  return req; // Continue with request
+});
 ```
 
-## 🔌 Plugin System
-
-BXO has a powerful plugin system with lifecycle hooks. Plugins are separate modules imported from `./plugins`.
-
-### Available Plugins
-
-#### CORS Plugin
+### afterRequest
+Runs after route processing but before the response is sent. Can modify the final response.
 
 ```typescript
-import { cors } from './plugins';
-
-app.use(cors({
-  origin: ['http://localhost:3000', 'https://example.com'],
-  methods: ['GET', 'POST', 'PUT', 'DELETE'],
-  allowedHeaders: ['Content-Type', 'Authorization'],
-  credentials: true,
-  maxAge: 86400
-}));
+app.afterRequest(async (req, res) => {
+  res.headers.set("X-Response-Time", Date.now().toString());
+  return res;
+});
 ```
 
-#### Logger Plugin
+### beforeResponse
+Runs after the route handler but before response headers are merged. Useful for modifying response metadata.
 
 ```typescript
-import { logger } from './plugins';
-
-app.use(logger({
-  format: 'simple',        // 'simple' | 'detailed' | 'json'
-  includeBody: false,      // Log request/response bodies
-  includeHeaders: false    // Log headers
-}));
+app.beforeResponse(async (res) => {
+  res.headers.set("X-Custom-Header", "value");
+  return res;
+});
 ```
 
-#### Authentication Plugin
+### onError
+Runs when an error occurs during request processing. Can return a custom error response.
 
 ```typescript
-import { auth, createJWT } from './plugins';
-
-app.use(auth({
-  type: 'jwt',                    // 'jwt' | 'bearer' | 'apikey'
-  secret: 'your-secret-key',
-  exclude: ['/login', '/health'], // Skip auth for these paths
-  verify: async (token, ctx) => {
-    // Custom token verification
-    return { user: 'data' };
-  }
-}));
-
-// Create JWT tokens
-const token = createJWT(
-  { userId: 123, role: 'admin' }, 
-  'secret', 
-  3600 // expires in 1 hour
-);
+app.onError(async (error, req) => {
+  console.error(`Error: ${error.message}`);
+  return new Response("Internal Server Error", { status: 500 });
+});
 ```
 
-#### Rate Limiting Plugin
+## Plugins
 
-```typescript
-import { rateLimit } from './plugins';
-
-app.use(rateLimit({
-  max: 100,                    // Max requests
-  window: 60,                  // Time window in seconds
-  exclude: ['/health'],        // Skip rate limiting for these paths
-  keyGenerator: (ctx) => {     // Custom key generation
-    return ctx.request.headers.get('x-api-key') || 'default';
-  },
-  message: 'Too many requests',
-  statusCode: 429
-}));
-```
+### CORS Plugin
 
-### Creating Custom Plugins
+The CORS plugin provides comprehensive Cross-Origin Resource Sharing support:
 
 ```typescript
-const customPlugin = {
-  name: 'custom',
-  onRequest: async (ctx) => {
-    console.log('Before request processing');
-    ctx.startTime = Date.now();
-  },
-  onResponse: async (ctx, response) => {
-    console.log(`Request took ${Date.now() - ctx.startTime}ms`);
-    return response;
-  },
-  onError: async (ctx, error) => {
-    console.error('Request failed:', error.message);
-    return { error: 'Custom error response' };
-  }
-};
+import { cors } from "./plugins";
 
-app.use(customPlugin);
+app.use(cors({
+  origin: ["http://localhost:3000", "https://myapp.com"],
+  methods: ["GET", "POST", "PUT", "DELETE"],
+  credentials: true
+}));
 ```
 
-## 🎣 Lifecycle Hooks
-
-BXO provides comprehensive lifecycle hooks with a consistent before/after pattern for both server and request lifecycle:
+### OpenAPI Plugin
 
-### Server Lifecycle Hooks
+The OpenAPI plugin automatically generates OpenAPI 3.0 documentation with support for tags, security schemes, and comprehensive route metadata:
 
 ```typescript
-app
-  .onBeforeStart(() => {
-    console.log('🔧 Preparing to start server...');
-  })
-  .onAfterStart(() => {
-    console.log('✅ Server fully started and ready!');
-  })
-  .onBeforeStop(() => {
-    console.log('🔧 Preparing to stop server...');
-  })
-  .onAfterStop(() => {
-    console.log('✅ Server fully stopped!');
-  })
-  .onBeforeRestart(() => {
-    console.log('🔧 Preparing to restart server...');
-  })
-  .onAfterRestart(() => {
-    console.log('✅ Server restart completed!');
-  });
-```
-
-### Request Lifecycle Hooks
+import { openapi } from "./plugins";
 
-```typescript
-app
-  .onRequest((ctx) => {
-    console.log(`📨 ${ctx.request.method} ${ctx.request.url}`);
-  })
-  .onResponse((ctx, response) => {
-    console.log(`📤 Response sent`);
-    return response; // Can modify response
-  })
-  .onError((ctx, error) => {
-    console.error(`💥 Error:`, error.message);
-    return { error: 'Something went wrong' }; // Can provide custom error response
-  });
+app.use(openapi({
+  path: "/docs",                    // Swagger UI endpoint
+  jsonPath: "/openapi.json",        // OpenAPI JSON endpoint
+  defaultTags: ["API"],             // Default tags for routes
+  securitySchemes: {                // Define security schemes
+    bearerAuth: {
+      type: "http",
+      scheme: "bearer",
+      bearerFormat: "JWT",
+      description: "JWT token for authentication"
+    },
+    apiKeyAuth: {
+      type: "apiKey",
+      in: "header",
+      name: "X-API-Key",
+      description: "API key for authentication"
+    }
+  },
+  globalSecurity: [                 // Global security requirements
+    { bearerAuth: [] },
+    { apiKeyAuth: [] }
+  ],
+  openapiConfig: {                  // Additional OpenAPI config
+    info: {
+      title: "My API",
+      version: "1.0.0",
+      description: "API description"
+    }
+  }
+}));
 ```
 
-## 🔄 Hot Reload & Server Management
+#### Route Metadata
 
-BXO includes built-in hot reload and comprehensive server management capabilities:
-
-### Hot Reload
+Routes can include detailed metadata for better OpenAPI documentation:
 
 ```typescript
-const app = new BXO();
-
-// Enable hot reload - server will restart when files change
-app.enableHotReload(['./']); // Watch current directory
-
-// Hot reload will automatically restart the server when:
-// - Any .ts or .js file changes in watched directories
-// - Server lifecycle hooks are properly executed during restart
+app.get("/users/:id", (ctx) => {
+  const id = ctx.params.id
+  return { user: { id, name: "John Doe" } }
+}, {
+  detail: {
+    tags: ["Users"],                    // Route tags for grouping
+    summary: "Get user by ID",          // Operation summary
+    description: "Retrieve user details", // Detailed description
+    security: [{ bearerAuth: [] }],     // Route-specific security
+    params: {                           // Parameter documentation
+      id: z.string().describe("User ID")
+    }
+  }
+})
 ```
 
-### Server Management
+#### Supported Metadata Fields
 
-```typescript
-const app = new BXO();
-
-// Start server
-await app.start(3000, 'localhost');
-
-// Check if server is running
-if (app.isServerRunning()) {
-  console.log('Server is running!');
-}
-
-// Get server information
-const info = app.getServerInfo();
-console.log(info); // { running: true, hotReload: true, watchedFiles: ['./'] }
-
-// Restart server programmatically
-await app.restart(3000, 'localhost');
+- `tags`: Array of tags for grouping operations
+- `summary`: Short description of the operation
+- `description`: Detailed description of the operation
+- `security`: Security requirements for the route
+- `params`: Path parameter schemas and descriptions
+- `query`: Query parameter schemas
+- `hidden`: Set to `true` to exclude from OpenAPI docs
 
-// Stop server gracefully
-await app.stop();
-
-// Backward compatibility - listen() still works
-await app.listen(3000); // Same as app.start(3000)
-```
+### Creating Custom Plugins
 
-### Development vs Production
+Plugins are just BXO instances with lifecycle hooks:
 
 ```typescript
-const app = new BXO();
-
-if (process.env.NODE_ENV === 'development') {
-  // Enable hot reload in development
-  app.enableHotReload(['./src', './routes']);
-}
-
-// Add server management endpoints for development
-if (process.env.NODE_ENV === 'development') {
-  app.post('/dev/restart', async (ctx) => {
-    setTimeout(() => app.restart(3000), 100);
-    return { message: 'Server restart initiated' };
-  });
+function loggingPlugin() {
+  const plugin = new BXO();
   
-  app.get('/dev/status', async (ctx) => {
-    return {
-      ...app.getServerInfo(),
-      uptime: process.uptime(),
-      memory: process.memoryUsage()
-    };
+  plugin.beforeRequest(async (req) => {
+    console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
+    return req;
   });
-}
-```
-
-## 🌟 Complete Example
-
-```typescript
-import BXO, { z } from './index';
-import { cors, logger, auth, rateLimit, createJWT } from './plugins';
-
-const app = new BXO();
-
-// Enable hot reload for development
-app.enableHotReload(['./']);
-
-// Add plugins
-app
-  .use(logger({ format: 'simple' }))
-  .use(cors({ 
-    origin: ['http://localhost:3000'],
-    credentials: true 
-  }))
-  .use(rateLimit({ 
-    max: 100, 
-    window: 60,
-    exclude: ['/health'] 
-  }))
-  .use(auth({ 
-    type: 'jwt', 
-    secret: 'your-secret-key',
-    exclude: ['/', '/login', '/health']
-  }));
-
-// Comprehensive lifecycle hooks
-app
-  .onBeforeStart(() => console.log('🔧 Preparing server startup...'))
-  .onAfterStart(() => console.log('✅ Server ready!'))
-  .onBeforeRestart(() => console.log('🔄 Restarting server...'))
-  .onAfterRestart(() => console.log('✅ Server restarted!'))
-  .onError((ctx, error) => ({ 
-    error: 'Internal server error',
-    timestamp: new Date().toISOString()
-  }));
-
-// Routes
-app
-  .get('/health', async () => ({ 
-    status: 'ok', 
-    timestamp: new Date().toISOString(),
-    server: app.getServerInfo()
-  }))
-  
-  .post('/login', async (ctx) => {
-    const { username, password } = ctx.body;
-    
-    if (username === 'admin' && password === 'password') {
-      const token = createJWT(
-        { username, role: 'admin' }, 
-        'your-secret-key'
-      );
-      return { token, user: { username, role: 'admin' } };
-    }
-    
-    ctx.set.status = 401;
-    return { error: 'Invalid credentials' };
-  }, {
-    body: z.object({
-      username: z.string(),
-      password: z.string()
-    })
-  })
-  
-  .get('/users/:id', async (ctx) => {
-    return { 
-      user: { 
-        id: ctx.params.id,
-        include: ctx.query.include 
-      } 
-    };
-  }, {
-    params: z.object({ id: z.string().uuid() }),
-    query: z.object({ include: z.string().optional() })
-  })
   
-  .post('/users', async (ctx) => {
-    return { created: ctx.body };
-  }, {
-    body: z.object({
-      name: z.string(),
-      email: z.string().email()
-    })
-  })
-  
-  .get('/protected', async (ctx) => {
-    // ctx.user available from auth plugin
-    return { 
-      message: 'Protected resource', 
-      user: ctx.user 
-    };
-  })
-  
-  // Server management endpoints
-  .post('/restart', async (ctx) => {
-    setTimeout(() => app.restart(3000), 100);
-    return { message: 'Server restart initiated' };
-  })
-  
-  .get('/status', async (ctx) => {
-    return {
-      ...app.getServerInfo(),
-      uptime: process.uptime(),
-      memory: process.memoryUsage()
-    };
-  });
+  return plugin;
+}
 
-// Start server with hot reload
-app.start(3000);
+app.use(loggingPlugin());
 ```
 
-## 🧪 Testing Endpoints
-
-With the example server running, test these endpoints:
+## Route Validation
 
-```bash
-# Health check
-curl http://localhost:3000/health
-
-# Login to get token
-curl -X POST http://localhost:3000/login \
-  -H "Content-Type: application/json" \
-  -d '{"username": "admin", "password": "password"}'
-
-# Create user
-curl -X POST http://localhost:3000/users \
-  -H "Content-Type: application/json" \
-  -d '{"name": "John Doe", "email": "john@example.com"}'
-
-# Get user with validation
-curl "http://localhost:3000/users/123e4567-e89b-12d3-a456-426614174000?include=profile"
-
-# Access protected route (use token from login)
-curl http://localhost:3000/protected \
-  -H "Authorization: Bearer YOUR_JWT_TOKEN"
-
-# Check server status
-curl http://localhost:3000/status
-
-# Restart server programmatically
-curl -X POST http://localhost:3000/restart
-```
-
-## 📖 API Reference
-
-### BXO Class Methods
-
-#### HTTP Methods
-- `get(path, handler, config?)` - Handle GET requests
-- `post(path, handler, config?)` - Handle POST requests  
-- `put(path, handler, config?)` - Handle PUT requests
-- `delete(path, handler, config?)` - Handle DELETE requests
-- `patch(path, handler, config?)` - Handle PATCH requests
-
-#### Plugins & Hooks
-- `use(plugin)` - Add a plugin
-- `onBeforeStart(handler)` - Before server start hook
-- `onAfterStart(handler)` - After server start hook
-- `onBeforeStop(handler)` - Before server stop hook
-- `onAfterStop(handler)` - After server stop hook
-- `onBeforeRestart(handler)` - Before server restart hook
-- `onAfterRestart(handler)` - After server restart hook
-- `onRequest(handler)` - Global request hook
-- `onResponse(handler)` - Global response hook
-- `onError(handler)` - Global error hook
-
-#### Server Management
-- `start(port?, hostname?)` - Start the server
-- `stop()` - Stop the server gracefully
-- `restart(port?, hostname?)` - Restart the server
-- `listen(port?, hostname?)` - Start the server (backward compatibility)
-- `isServerRunning()` - Check if server is running
-- `getServerInfo()` - Get server status information
-
-#### Hot Reload
-- `enableHotReload(watchPaths?)` - Enable hot reload with file watching
-
-### Route Configuration
+Define Zod schemas for request validation:
 
 ```typescript
-interface RouteConfig {
-  params?: z.ZodSchema<any>;   // Path parameter validation
-  query?: z.ZodSchema<any>;    // Query string validation  
-  body?: z.ZodSchema<any>;     // Request body validation
-  headers?: z.ZodSchema<any>;  // Header validation
-}
-```
+import { z } from "bxo";
 
-### Plugin Interface
+const UserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email()
+});
 
-```typescript
-interface Plugin {
-  name?: string;
-  onRequest?: (ctx: Context) => Promise<void> | void;
-  onResponse?: (ctx: Context, response: any) => Promise<any> | any;
-  onError?: (ctx: Context, error: Error) => Promise<any> | any;
-}
+app.post("/users", async (ctx) => {
+  const user = ctx.body; // Already validated by UserSchema
+  return ctx.json({ id: 1, ...user });
+}, {
+  body: UserSchema
+});
 ```
 
-## 🛠️ Development
-
-### Running the Example
+## Running
 
 ```bash
-# Run with hot reload enabled
-bun run example.ts
-
-# The server will automatically restart when you edit any .ts/.js files!
+bun run ./src/index.ts
 ```
 
-### Project Structure
+Or run the CORS example:
 
+```bash
+bun run ./example/cors-example.ts
 ```
-bxo/
-├── index.ts              # Main BXO framework
-├── plugins/
-│   ├── index.ts          # Plugin exports
-│   ├── cors.ts           # CORS plugin
-│   ├── logger.ts         # Logger plugin
-│   ├── auth.ts           # Authentication plugin
-│   └── ratelimit.ts      # Rate limiting plugin
-├── example.ts            # Usage example
-├── package.json
-└── README.md
-```
-
-## 🤝 Contributing
-
-BXO is designed to be simple and extensible. Contributions are welcome!
 
-## 📄 License
+## Examples
 
-MIT License - feel free to use BXO in your projects!
+Check out the `example/` directory for more usage examples:
 
----
+- `cors-example.ts` - Demonstrates CORS plugin and lifecycle hooks
+- `openapi-example.ts` - Demonstrates OpenAPI plugin with tags and security
+- `index.ts` - Basic routing example
 
-Built with ❤️ for the Bun ecosystem
+This project was created using `bun init` in bun v1.2.3. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.