bxo 0.0.5-dev.65 → 0.0.5-dev.67

package/README.md

@@ -1,746 +1,154 @@
-# 🦊 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 bxo
+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:
+## Lifecycle Hooks
 
-```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>;
-  };
-  status: (code: number, data?: any) => any;  // Type-safe status method
-  user?: any;                    // Added by auth plugin
-  [key: string]: any;            // Extended by plugins
-}
-```
+BXO provides powerful lifecycle hooks that allow you to intercept and modify requests and responses at different stages:
 
-### Type-Safe Status Method
-
-BXO provides a type-safe `ctx.status()` method similar to Elysia, which allows you to set HTTP status codes and return data in one call:
+### beforeRequest
+Runs before any route processing. Can modify the request or return a response to short-circuit processing.
 
 ```typescript
-// Simple usage
-app.get('/hello', (ctx) => {
-  return ctx.status(200, { message: 'Hello World' });
-});
-
-// With response validation
-app.get('/user/:id', (ctx) => {
-  const userId = ctx.params.id;
-  
-  if (userId === 'not-found') {
-    // TypeScript suggests 404 as valid status
-    return ctx.status(404, { error: 'User not found' });
-  }
-  
-  // TypeScript suggests 200 as valid status
-  return ctx.status(200, { user: { id: userId, name: 'John Doe' } });
-}, {
-  response: {
-    200: z.object({
-      user: z.object({
-        id: z.string(),
-        name: z.string()
-      })
-    }),
-    404: z.object({
-      error: z.string()
-    })
-  }
-});
-
-// POST with validation and status responses
-app.post('/users', (ctx) => {
-  const { name, email } = ctx.body;
-  
-  if (!name || !email) {
-    return ctx.status(400, { error: 'Missing required fields' });
-  }
-  
-  return ctx.status(201, { 
-    success: true, 
-    user: { id: 1, name, email } 
-  });
-}, {
-  body: z.object({
-    name: z.string(),
-    email: z.string().email()
-  }),
-  response: {
-    201: z.object({
-      success: z.boolean(),
-      user: z.object({
-        id: z.number(),
-        name: z.string(),
-        email: z.string()
-      })
-    }),
-    400: z.object({
-      error: z.string()
-    })
-  }
+app.beforeRequest(async (req) => {
+  console.log(`${req.method} ${req.url}`);
+  return req; // Continue with request
 });
 ```
 
-**Key Features:**
-- **Type Safety**: Status codes are suggested based on your response configuration
-- **Data Validation**: Return data is validated against the corresponding schema
-- **Autocomplete**: TypeScript provides autocomplete for valid status codes
-- **Return Type Inference**: Return types are properly inferred from schemas
-
-### Validation Configuration
-
-Each route can specify validation schemas for different parts of the request:
+### afterRequest
+Runs after route processing but before the response is sent. Can modify the final response.
 
 ```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.afterRequest(async (req, res) => {
+  res.headers.set("X-Response-Time", Date.now().toString());
+  return res;
+});
 ```
 
-## 🔌 Plugin System
-
-BXO has a powerful plugin system with lifecycle hooks. Plugins can be either middleware-style plugins or full BXO instances. Middleware plugins are separate modules imported from `./plugins` and are executed in the order they are added.
-
-### Available Plugins
-
-#### CORS Plugin
+### beforeResponse
+Runs after the route handler but before response headers are merged. Useful for modifying response metadata.
 
 ```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.beforeResponse(async (res) => {
+  res.headers.set("X-Custom-Header", "value");
+  return res;
+});
 ```
 
-**Features:**
-- **Origin Header Support**: Standard CORS origin header handling
-- **Referer Header Fallback**: Automatically falls back to Referer header when Origin is not present
-- **Origin Precedence**: When both Origin and Referer are present, Origin takes precedence
-- **Invalid URL Handling**: Gracefully handles invalid Referer URLs
-- **Flexible Origin Configuration**: Supports string, array, boolean, or wildcard (`*`) origins
-
-#### Logger Plugin
+### onError
+Runs when an error occurs during request processing. Can return a custom error response.
 
 ```typescript
-import { logger } from './plugins';
-
-app.use(logger({
-  format: 'simple',        // 'simple' | 'detailed' | 'json'
-  includeBody: false,      // Log request/response bodies
-  includeHeaders: false    // Log headers
-}));
+app.onError(async (error, req) => {
+  console.error(`Error: ${error.message}`);
+  return new Response("Internal Server Error", { status: 500 });
+});
 ```
 
-#### Authentication Plugin
+## Plugins
 
-```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' };
-  }
-}));
+### CORS Plugin
 
-// Create JWT tokens
-const token = createJWT(
-  { userId: 123, role: 'admin' }, 
-  'secret', 
-  3600 // expires in 1 hour
-);
-```
-
-#### Rate Limiting Plugin
+The CORS plugin provides comprehensive Cross-Origin Resource Sharing support:
 
 ```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
+import { cors } from "./plugins";
+
+app.use(cors({
+  origin: ["http://localhost:3000", "https://myapp.com"],
+  methods: ["GET", "POST", "PUT", "DELETE"],
+  credentials: true
 }));
 ```
 
 ### Creating Custom Plugins
 
-#### Middleware-Style Plugins (Recommended)
-
-```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' };
-  }
-};
-
-app.use(customPlugin);
-```
-
-#### Full BXO Instance Plugins
-
-You can also use full BXO instances as plugins, which will merge their routes and hooks:
-
-```typescript
-const pluginApp = new BXO();
-pluginApp.get('/plugin-route', async (ctx) => {
-  return { message: 'From plugin' };
-});
-
-app.use(pluginApp);
-```
-
-## 🎣 Lifecycle Hooks
-
-BXO provides comprehensive lifecycle hooks with a consistent before/after pattern for both server and request lifecycle:
-
-### Server Lifecycle Hooks
+Plugins are just BXO instances with lifecycle hooks:
 
 ```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
-
-```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
+function loggingPlugin() {
+  const plugin = new BXO();
+  
+  plugin.beforeRequest(async (req) => {
+    console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
+    return req;
   });
-```
-
-## 🔄 Hot Reload & Server Management
-
-BXO includes built-in hot reload and comprehensive server management capabilities:
-
-### Hot Reload
-
-```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
-```
-
-### Server Management
-
-```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!');
+  
+  return plugin;
 }
 
-// Get server information
-const info = app.getServerInfo();
-console.log(info); // { running: true, hotReload: true, watchedFiles: ['./'] }
-
-// Restart server programmatically
-await app.restart(3000, 'localhost');
-
-// Stop server gracefully
-await app.stop();
-
-// Backward compatibility - listen() still works
-await app.listen(3000); // Same as app.start(3000)
+app.use(loggingPlugin());
 ```
 
-### Custom Serve Options
+## Route Validation
 
-BXO allows you to extend the native Bun serve options, giving you full control over the server configuration while maintaining the framework's functionality:
+Define Zod schemas for request validation:
 
 ```typescript
-// Basic serve options
-const app = new BXO({
-  serve: {
-    port: 3000,
-    hostname: "0.0.0.0", // Listen on all interfaces
-  }
-});
-
-// With TLS/HTTPS options
-const app = new BXO({
-  serve: {
-    port: 443,
-    hostname: "localhost",
-    // tls: {
-    //   cert: Bun.file("cert.pem"),
-    //   key: Bun.file("key.pem"),
-    // }
-  }
-});
+import { z } from "bxo";
 
-// With development options
-const app = new BXO({
-  serve: {
-    port: 5000,
-    development: true, // Enable development mode
-  }
+const UserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email()
 });
 
-// With custom error handling
-const app = new BXO({
-  serve: {
-    port: 6000,
-    error: (error) => {
-      console.error("Custom error handler:", error);
-      return new Response("Something went wrong", { status: 500 });
-    }
-  }
-});
-
-// With custom fetch handler (extends framework functionality)
-const app = new BXO({
-  serve: {
-    port: 4000,
-    // You can override the fetch handler if needed
-    // fetch: (request, server) => {
-    //   // Your custom logic here
-    //   // You can still call the framework's handler
-    //   return app.requestHandler.handleRequest(request, server);
-    // }
-  }
+app.post("/users", async (ctx) => {
+  const user = ctx.body; // Already validated by UserSchema
+  return ctx.json({ id: 1, ...user });
+}, {
+  body: UserSchema
 });
 ```
 
-**Available Serve Options:**
-- `port` - Server port (default: 3000)
-- `hostname` - Server hostname (default: 'localhost')
-- `development` - Enable development mode
-- `tls` - TLS/HTTPS configuration
-- `error` - Custom error handler
-- `fetch` - Custom fetch handler (overrides framework's handler)
-- `websocket` - WebSocket configuration
-- And all other [Bun.serve options](https://bun.sh/docs/api/http#bun-serve)
-
-The framework will merge your serve options with its own defaults, ensuring that BXO's routing, middleware, and WebSocket functionality continue to work while allowing you to customize the server behavior.
-
-### Development vs Production
-
-```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' };
-  });
-  
-  app.get('/dev/status', async (ctx) => {
-    return {
-      ...app.getServerInfo(),
-      uptime: process.uptime(),
-      memory: process.memoryUsage()
-    };
-  });
-}
-```
-
-## 🌟 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()
-    };
-  });
-
-// Start server with hot reload
-app.start(3000);
-```
-
-## 🧪 Testing Endpoints
-
-With the example server running, test these endpoints:
+## Running
 
 ```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
+bun run ./src/index.ts
 ```
 
-## 📖 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
-
-```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
-}
-```
-
-### Plugin Interface
-
-```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;
-}
-```
-
-## 🛠️ Development
-
-### Running the Example
+Or run the CORS example:
 
 ```bash
-# Run with hot reload enabled
-bun run example.ts
-
-# The server will automatically restart when you edit any .ts/.js files!
-```
-
-### Project Structure
-
-```
-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
+bun run ./example/cors-example.ts
 ```
 
-## 🤝 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
+- `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.