bxo 0.0.5-dev.41 → 0.0.5-dev.43

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.41",
+  "version": "0.0.5-dev.43",
   "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,69 +59,53 @@ export function cors(options: CORSOptions = {}): any {
 
   return {
     name: 'cors',
-    onRequest: async (ctx: any) => {
-      // Handle preflight OPTIONS request
+    onRequest: async (ctx) => {
+      // Handle preflight OPTIONS requests
       if (ctx.request.method === 'OPTIONS') {
-        const headers: Record<string, string> = {};
-
-        // Get and validate origin
         const requestOrigin = getRequestOrigin(ctx.request);
-        const validatedOrigin = validateOrigin(requestOrigin, origin);
-
-        if (validatedOrigin) {
-          headers['Access-Control-Allow-Origin'] = validatedOrigin;
-        } else if (typeof origin === 'string' && origin === '*') {
-          headers['Access-Control-Allow-Origin'] = '*';
-        }
-
-        headers['Access-Control-Allow-Methods'] = methods.join(', ');
-        headers['Access-Control-Allow-Headers'] = allowedHeaders.join(', ');
+        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) {
-          headers['Access-Control-Allow-Credentials'] = 'true';
+          ctx.set.headers['Access-Control-Allow-Credentials'] = 'true';
         }
-        
-        headers['Access-Control-Max-Age'] = maxAge.toString();
-
-        ctx.set.status = 204;
-        ctx.set.headers = { ...ctx.set.headers, ...headers };
-        
-        throw new Response(null, { status: 204, headers });
       }
     },
-    onResponse: async (ctx: any, response: any) => {
-      const headers: Record<string, string> = {};
-
-      // Get and validate origin for actual requests
-      const requestOrigin = getRequestOrigin(ctx.request);
-      const validatedOrigin = validateOrigin(requestOrigin, origin);
-
-      if (validatedOrigin) {
-        headers['Access-Control-Allow-Origin'] = validatedOrigin;
-      } else if (typeof origin === 'string' && origin === '*') {
-        headers['Access-Control-Allow-Origin'] = '*';
-      }
-
-      if (credentials) {
-        headers['Access-Control-Allow-Credentials'] = 'true';
-      }
-
-      // If response is a Response object, add headers to it
+    onResponse: async (ctx, response) => {
+      // Handle CORS headers for actual requests
       if (response instanceof Response) {
-        const newHeaders = new Headers(response.headers);
-        Object.entries(headers).forEach(([key, value]) => {
-          newHeaders.set(key, value);
-        });
-        return new Response(response.body, {
+        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: newHeaders
+          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;
       }
-
-      // Otherwise, set headers in context for the framework to handle
-      ctx.set.headers = { ...ctx.set.headers, ...headers };
+      
       return response;
     }
   };
-} 
+}

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,