bxo 0.0.5-dev.42 → 0.0.5-dev.44

package/index.ts

@@ -1352,7 +1352,7 @@ const redirect = (location: string, status: number = 302) => {
 export { z, error, file, redirect };
 
 // Export types for external use
-export type { RouteConfig, RouteDetail, Handler, WebSocketHandler, WSRoute, Cookie, BXOOptions };
+export type { RouteConfig, RouteDetail, Handler, WebSocketHandler, WSRoute, Cookie, BXOOptions, Plugin };
 
 // Helper function to create a cookie
 export const createCookie = (

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bxo",
   "module": "index.ts",
-  "version": "0.0.5-dev.42",
+  "version": "0.0.5-dev.44",
   "description": "A simple and lightweight web framework for Bun",
   "type": "module",
   "exports": {

package/plugins/README.md

@@ -0,0 +1,160 @@
+# BXO Plugins
+
+BXO supports a plugin system that allows you to extend functionality through middleware-style plugins. Plugins can intercept requests, modify responses, and handle errors.
+
+## Plugin Type
+
+The `Plugin` type defines the interface for all plugins:
+
+```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;
+}
+```
+
+## Built-in Plugins
+
+### CORS Plugin
+
+The CORS plugin adds Cross-Origin Resource Sharing headers to your responses:
+
+```typescript
+import BXO from 'bxo';
+import { cors } from 'bxo/plugins';
+
+const app = new BXO();
+
+// Use with default options
+app.use(cors());
+
+// Or with custom options
+app.use(cors({
+  origin: ['http://localhost:3000', 'https://myapp.com'],
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  allowedHeaders: ['Content-Type', 'Authorization'],
+  credentials: true,
+  maxAge: 86400
+}));
+```
+
+### Rate Limit Plugin
+
+The rate limit plugin helps protect your API from abuse:
+
+```typescript
+import BXO from 'bxo';
+import { rateLimit } from 'bxo/plugins';
+
+const app = new BXO();
+
+app.use(rateLimit({
+  max: 100, // Maximum requests per window
+  window: 60, // Time window in seconds
+  message: 'Too many requests',
+  statusCode: 429,
+  exclude: ['/health', '/metrics'] // Exclude certain paths
+}));
+```
+
+## Creating Custom Plugins
+
+You can create your own plugins by implementing the `Plugin` interface:
+
+```typescript
+import type { Plugin } from 'bxo';
+
+// Simple logging plugin
+export function logger(): Plugin {
+  return {
+    name: 'logger',
+    onRequest: async (ctx) => {
+      console.log(`${new Date().toISOString()} - ${ctx.request.method} ${ctx.path}`);
+    },
+    onResponse: async (ctx, response) => {
+      if (response instanceof Response) {
+        console.log(`${new Date().toISOString()} - ${ctx.request.method} ${ctx.path} - ${response.status}`);
+      }
+      return response;
+    },
+    onError: async (ctx, error) => {
+      console.error(`${new Date().toISOString()} - Error in ${ctx.request.method} ${ctx.path}:`, error);
+    }
+  };
+}
+
+// Authentication plugin
+export function auth(secret: string): Plugin {
+  return {
+    name: 'auth',
+    onRequest: async (ctx) => {
+      const token = ctx.headers.authorization?.replace('Bearer ', '');
+      
+      if (!token) {
+        throw new Response(JSON.stringify({ error: 'No token provided' }), {
+          status: 401,
+          headers: { 'Content-Type': 'application/json' }
+        });
+      }
+      
+      // Verify token logic here...
+      // If invalid, throw a Response with 401 status
+    }
+  };
+}
+```
+
+## Using Plugins
+
+Plugins are applied using the `use()` method:
+
+```typescript
+import BXO from 'bxo';
+import { cors, rateLimit } from 'bxo/plugins';
+import { logger, auth } from './my-plugins';
+
+const app = new BXO();
+
+// Apply plugins in order (they will execute in this order)
+app.use(logger());
+app.use(cors());
+app.use(rateLimit({ max: 100, window: 60 }));
+app.use(auth('my-secret'));
+
+// Your routes
+app.get('/', (ctx) => {
+  return { message: 'Hello World!' };
+});
+```
+
+## Plugin Execution Order
+
+Plugins execute in the order they are added:
+
+1. **onRequest**: All plugins' `onRequest` hooks execute before the route handler
+2. **Route Handler**: The actual route handler executes
+3. **onResponse**: All plugins' `onResponse` hooks execute after the route handler
+4. **onError**: If an error occurs, all plugins' `onError` hooks execute
+
+## Plugin Context
+
+Each plugin receives a `Context` object that contains:
+
+- `params`: Route parameters
+- `query`: Query string parameters
+- `body`: Request body
+- `headers`: Request headers
+- `cookies`: Request cookies
+- `path`: Request path
+- `request`: The original Request object
+- `set`: Object to set response properties (status, headers, cookies, redirect)
+
+## Best Practices
+
+1. **Keep plugins focused**: Each plugin should handle one specific concern
+2. **Handle errors gracefully**: Use try-catch blocks in your plugin hooks
+3. **Return responses properly**: Always return the response from `onResponse` hooks
+4. **Use meaningful names**: Give your plugins descriptive names for debugging
+5. **Document your plugins**: Include JSDoc comments explaining what your plugin does

package/plugins/cors.ts

@@ -1,4 +1,4 @@
-import BXO from '../index';
+import type { Plugin } from '../index';
 
 interface CORSOptions {
   origin?: string | string[] | boolean;
@@ -48,7 +48,7 @@ function validateOrigin(requestOrigin: string | null, allowedOrigins: string | s
   return null;
 }
 
-export function cors(options: CORSOptions = {}): any {
+export function cors(options: CORSOptions = {}): Plugin {
   const {
     origin = '*',
     methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
@@ -59,12 +59,53 @@ export function cors(options: CORSOptions = {}): any {
 
   return {
     name: 'cors',
-    onRequest: async (ctx: any) => {
+    onRequest: async (ctx) => {
+      // Handle preflight OPTIONS requests
+      if (ctx.request.method === 'OPTIONS') {
+        const requestOrigin = getRequestOrigin(ctx.request);
+        const allowedOrigin = validateOrigin(requestOrigin, origin);
+        
+        // Set CORS headers for preflight
+        ctx.set.headers = {
+          ...ctx.set.headers,
+          'Access-Control-Allow-Origin': allowedOrigin || '*',
+          'Access-Control-Allow-Methods': methods.join(', '),
+          'Access-Control-Allow-Headers': allowedHeaders.join(', '),
+          'Access-Control-Max-Age': maxAge.toString()
+        };
+        
+        if (credentials) {
+          ctx.set.headers['Access-Control-Allow-Credentials'] = 'true';
+        }
+      }
     },
-    onResponse: async (ctx: any, response: any) => {
-      response.headers.set('Access-Control-Allow-Origin', '*');
-      response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    onResponse: async (ctx, response) => {
+      // Handle CORS headers for actual requests
+      if (response instanceof Response) {
+        const requestOrigin = getRequestOrigin(ctx.request);
+        const allowedOrigin = validateOrigin(requestOrigin, origin);
+        
+        // Clone the response to modify headers
+        const newResponse = new Response(response.body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers: new Headers(response.headers)
+        });
+        
+        // Set CORS headers
+        newResponse.headers.set('Access-Control-Allow-Origin', allowedOrigin || '*');
+        newResponse.headers.set('Access-Control-Allow-Methods', methods.join(', '));
+        newResponse.headers.set('Access-Control-Allow-Headers', allowedHeaders.join(', '));
+        newResponse.headers.set('Access-Control-Max-Age', maxAge.toString());
+        
+        if (credentials) {
+          newResponse.headers.set('Access-Control-Allow-Credentials', 'true');
+        }
+        
+        return newResponse;
+      }
+      
       return response;
     }
   };
-} 
+}

package/plugins/example.ts

@@ -0,0 +1,173 @@
+import type { Plugin } from '../index';
+
+// Example 1: Simple logging plugin
+export function logger(): Plugin {
+  return {
+    name: 'logger',
+    onRequest: async (ctx) => {
+      console.log(`[${new Date().toISOString()}] ${ctx.request.method} ${ctx.path}`);
+    },
+    onResponse: async (ctx, response) => {
+      if (response instanceof Response) {
+        console.log(`[${new Date().toISOString()}] ${ctx.request.method} ${ctx.path} - ${response.status}`);
+      }
+      return response;
+    },
+    onError: async (ctx, error) => {
+      console.error(`[${new Date().toISOString()}] Error in ${ctx.request.method} ${ctx.path}:`, error);
+    }
+  };
+}
+
+// Example 2: Authentication plugin
+export function auth(secret: string): Plugin {
+  return {
+    name: 'auth',
+    onRequest: async (ctx) => {
+      const token = ctx.headers.authorization?.replace('Bearer ', '');
+      
+      if (!token) {
+        throw new Response(JSON.stringify({ error: 'No token provided' }), {
+          status: 401,
+          headers: { 'Content-Type': 'application/json' }
+        });
+      }
+      
+      // Simple token validation (replace with your actual logic)
+      if (token !== secret) {
+        throw new Response(JSON.stringify({ error: 'Invalid token' }), {
+          status: 401,
+          headers: { 'Content-Type': 'application/json' }
+        });
+      }
+      
+      // Add user info to context
+      (ctx as any).user = { id: 'user-123', token };
+    }
+  };
+}
+
+// Example 3: Request timing plugin
+export function timing(): Plugin {
+  return {
+    name: 'timing',
+    onRequest: async (ctx) => {
+      (ctx as any).startTime = Date.now();
+    },
+    onResponse: async (ctx, response) => {
+      const startTime = (ctx as any).startTime;
+      if (startTime) {
+        const duration = Date.now() - startTime;
+        console.log(`Request to ${ctx.path} took ${duration}ms`);
+        
+        // Add timing header to response
+        if (response instanceof Response) {
+          const newResponse = new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: new Headers(response.headers)
+          });
+          newResponse.headers.set('X-Response-Time', `${duration}ms`);
+          return newResponse;
+        }
+      }
+      return response;
+    }
+  };
+}
+
+// Example 4: Request ID plugin
+export function requestId(): Plugin {
+  return {
+    name: 'requestId',
+    onRequest: async (ctx) => {
+      const requestId = crypto.randomUUID();
+      (ctx as any).requestId = requestId;
+      
+      // Add request ID to response headers
+      ctx.set.headers = {
+        ...ctx.set.headers,
+        'X-Request-ID': requestId
+      };
+    }
+  };
+}
+
+// Example 5: Conditional plugin (only applies to certain paths)
+export function conditionalAuth(secret: string, paths: string[]): Plugin {
+  return {
+    name: 'conditionalAuth',
+    onRequest: async (ctx) => {
+      // Only apply auth to specified paths
+      if (!paths.some(path => ctx.path.startsWith(path))) {
+        return; // Skip authentication for this path
+      }
+      
+      const token = ctx.headers.authorization?.replace('Bearer ', '');
+      
+      if (!token || token !== secret) {
+        throw new Response(JSON.stringify({ error: 'Authentication required' }), {
+          status: 401,
+          headers: { 'Content-Type': 'application/json' }
+        });
+      }
+    }
+  };
+}
+
+// Example 6: Response transformation plugin
+export function responseTransformer(): Plugin {
+  return {
+    name: 'responseTransformer',
+    onResponse: async (ctx, response) => {
+      // Only transform JSON responses
+      if (response instanceof Response) {
+        const contentType = response.headers.get('content-type');
+        if (contentType?.includes('application/json')) {
+          try {
+            const data = await response.json();
+            
+            // Transform the response data
+            const transformed = {
+              success: true,
+              data,
+              timestamp: new Date().toISOString(),
+              path: ctx.path
+            };
+            
+            return new Response(JSON.stringify(transformed), {
+              status: response.status,
+              headers: response.headers
+            });
+          } catch (error) {
+            // If response is not JSON, return as-is
+            return response;
+          }
+        }
+      }
+      
+      return response;
+    }
+  };
+}
+
+// Example 7: Error handling plugin
+export function errorHandler(): Plugin {
+  return {
+    name: 'errorHandler',
+    onError: async (ctx, error) => {
+      console.error(`Error in ${ctx.request.method} ${ctx.path}:`, error);
+      
+      // Return a standardized error response
+      return new Response(JSON.stringify({
+        error: 'Internal Server Error',
+        message: error.message,
+        timestamp: new Date().toISOString(),
+        path: ctx.path
+      }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
+  };
+}

package/plugins/index.ts

@@ -2,8 +2,8 @@
 export { cors } from './cors';
 export { rateLimit } from './ratelimit';
 
-// Import BXO for plugin typing
-import BXO from '../index';
+// Import types for plugin typing
+import type { Plugin } from '../index';
 
-// Plugin functions now return BXO instances
-export type PluginFactory<T = any> = (options?: T) => BXO;
+// Plugin functions return Plugin instances
+export type PluginFactory<T = any> = (options?: T) => Plugin;

package/plugins/ratelimit.ts

@@ -1,4 +1,4 @@
-import BXO from '../index';
+import type { Plugin } from '../index';
 
 interface RateLimitOptions {
   max: number;
@@ -52,7 +52,7 @@ class RateLimitStore {
   }
 }
 
-export function rateLimit(options: RateLimitOptions): any {
+export function rateLimit(options: RateLimitOptions): Plugin {
   const {
     max,
     window,