bxo 0.0.5-dev.8 → 0.0.5-dev.80

package/example/openapi-example.ts

@@ -0,0 +1,132 @@
+import BXO, { z } from "../src";
+import { openapi } from "../plugins/openapi";
+
+// Create a BXO app with OpenAPI plugin
+const app = new BXO()
+    .use(openapi({
+        path: "/docs",
+        jsonPath: "/openapi.json",
+        defaultTags: ["API"],
+        securitySchemes: {
+            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: [
+            { bearerAuth: [] },
+            { apiKeyAuth: [] }
+        ],
+        openapiConfig: {
+            info: {
+                title: "My API with Security",
+                version: "1.0.0",
+                description: "An example API with OpenAPI documentation, tags, and security"
+            }
+        }
+    }))
+
+// Example routes with tags and security
+app.get("/users", (ctx) => {
+    return { users: [] }
+}, {
+    detail: {
+        tags: ["Users"],
+        summary: "Get all users",
+        description: "Retrieve a list of all users",
+        security: [{ bearerAuth: [] }]
+    }
+})
+
+app.get("/users/:id", (ctx) => {
+    const id = ctx.params.id
+    return { user: { id, name: "John Doe" } }
+}, {
+    detail: {
+        tags: ["Users"],
+        summary: "Get user by ID",
+        description: "Retrieve a specific user by their ID",
+        params: {
+            id: z.string().describe("User ID")
+        },
+        security: [{ apiKeyAuth: [] }]
+    }
+})
+
+app.post("/users", (ctx) => {
+    const body = ctx.body
+    return { message: "User created", user: body }
+}, {
+    body: z.object({
+        name: z.string(),
+        email: z.string().email()
+    }),
+    detail: {
+        tags: ["Users"],
+        summary: "Create a new user",
+        description: "Create a new user with the provided information",
+        security: [{ bearerAuth: [] }]
+    }
+})
+
+app.get("/products", (ctx) => {
+    return { products: [] }
+}, {
+    detail: {
+        tags: ["Products"],
+        summary: "Get all products",
+        description: "Retrieve a list of all products"
+    }
+})
+
+app.get("/products/:id", (ctx) => {
+    const id = ctx.params.id
+    return { product: { id, name: "Sample Product" } }
+}, {
+    detail: {
+        tags: ["Products"],
+        summary: "Get product by ID",
+        description: "Retrieve a specific product by its ID",
+        params: {
+            id: z.string().describe("Product ID")
+        }
+    }
+})
+
+// Admin routes with different security
+app.get("/admin/users", (ctx) => {
+    return { adminUsers: [] }
+}, {
+    detail: {
+        tags: ["Admin"],
+        summary: "Get all users (Admin)",
+        description: "Admin-only endpoint to retrieve all users",
+        security: [{ bearerAuth: [] }, { apiKeyAuth: [] }]
+    }
+})
+
+// Health check route (no security required)
+app.get("/health", (ctx) => {
+    return { status: "ok", timestamp: new Date().toISOString() }
+}, {
+    detail: {
+        tags: ["System"],
+        summary: "Health check",
+        description: "Check if the API is running"
+    }
+})
+
+// Start the server
+app.listen(3000, () => {
+    console.log("Server running on http://localhost:3000")
+    console.log("OpenAPI docs available at http://localhost:3000/docs")
+    console.log("OpenAPI JSON available at http://localhost:3000/openapi.json")
+})

package/example/passthrough-validation-example.ts

@@ -0,0 +1,115 @@
+import BXO, { z } from "../src";
+
+async function main() {
+    const app = new BXO({ serve: { port: 3002 } });
+
+    // Example 1: Header validation with passthrough
+    app.get("/api/headers", (ctx) => {
+        return ctx.json({
+            message: "Headers received",
+            // All headers are available, including extra ones not in schema
+            allHeaders: ctx.headers,
+            // Schema-validated headers are typed
+            contentType: ctx.headers["content-type"],
+            authorization: ctx.headers["authorization"]
+        });
+    }, {
+        headers: z.object({
+            "content-type": z.string().optional(),
+            "authorization": z.string().optional()
+        }).passthrough() // This allows extra headers to pass through
+    });
+
+    // Example 2: Cookie validation with passthrough
+    app.get("/api/cookies", (ctx) => {
+        return ctx.json({
+            message: "Cookies received",
+            // All cookies are available, including extra ones not in schema
+            allCookies: ctx.cookies,
+            // Schema-validated cookies are typed
+            sessionId: ctx.cookies.sessionId,
+            theme: ctx.cookies.theme
+        });
+    }, {
+        cookies: z.object({
+            sessionId: z.string().optional(),
+            theme: z.enum(["light", "dark"]).optional()
+        }).passthrough() // This allows extra cookies to pass through
+    });
+
+    // Example 3: Both headers and cookies with passthrough
+    app.post("/api/auth", (ctx) => {
+        return ctx.json({
+            message: "Authentication successful",
+            headers: {
+                // Only the required headers are typed
+                contentType: ctx.headers["content-type"],
+                authorization: ctx.headers["authorization"],
+                // But all headers are available
+                allHeaders: ctx.headers
+            },
+            cookies: {
+                // Only the required cookies are typed
+                sessionId: ctx.cookies.sessionId,
+                theme: ctx.cookies.theme,
+                // But all cookies are available
+                allCookies: ctx.cookies
+            }
+        });
+    }, {
+        headers: z.object({
+            "content-type": z.string(),
+            "authorization": z.string()
+        }).passthrough(),
+        cookies: z.object({
+            sessionId: z.string(),
+            theme: z.enum(["light", "dark"])
+        }).passthrough(),
+        body: z.object({
+            username: z.string(),
+            password: z.string()
+        })
+    });
+
+    // Example 4: Without passthrough (strict validation)
+    app.get("/api/strict", (ctx) => {
+        return ctx.json({
+            message: "Strict validation - only schema fields available",
+            headers: ctx.headers,
+            cookies: ctx.cookies
+        });
+    }, {
+        headers: z.object({
+            "content-type": z.string().optional()
+        }), // No passthrough - will fail if extra headers are present
+        cookies: z.object({
+            sessionId: z.string().optional()
+        }) // No passthrough - will fail if extra cookies are present
+    });
+
+    // Example 5: Demonstrating the difference
+    app.get("/api/demo", (ctx) => {
+        // Set some cookies to demonstrate
+        ctx.set.cookie("sessionId", "abc123");
+        ctx.set.cookie("theme", "dark");
+        ctx.set.cookie("extraCookie", "this-will-be-available-with-passthrough");
+        
+        return ctx.json({
+            message: "Check the cookies in your browser dev tools",
+            note: "extraCookie will be available in /api/cookies but not in /api/strict"
+        });
+    });
+
+    app.start();
+    console.log(`Passthrough validation example server running on http://localhost:${app.server?.port}`);
+    console.log("\nTry these endpoints:");
+    console.log("GET  /api/headers (with extra headers)");
+    console.log("GET  /api/cookies (with extra cookies)");
+    console.log("POST /api/auth (with both headers and cookies)");
+    console.log("GET  /api/strict (strict validation - may fail with extra fields)");
+    console.log("GET  /api/demo (sets some cookies for testing)");
+    console.log("\nExample with curl:");
+    console.log('curl -H "Content-Type: application/json" -H "Authorization: Bearer token123" -H "X-Custom-Header: value" -b "sessionId=abc123; theme=dark; extraCookie=test" http://localhost:3002/api/headers');
+}
+
+main().catch(console.error);

package/example/url-encoding-example.ts

@@ -0,0 +1,93 @@
+import BXO from "../src";
+
+async function main() {
+    const app = new BXO({ serve: { port: 3000 } });
+
+    // Route with space in the path
+    app.get("/api/resources/Workspace Item", (ctx) => {
+        return ctx.json({ 
+            message: "Found Workspace Item resource!",
+            path: ctx.request.url,
+            pathname: new URL(ctx.request.url).pathname
+        });
+    });
+
+    // Route with URL-encoded space
+    app.get("/api/resources/Workspace%20Item", (ctx) => {
+        return ctx.json({ 
+            message: "Found URL-encoded Workspace Item resource!",
+            path: ctx.request.url,
+            pathname: new URL(ctx.request.url).pathname
+        });
+    });
+
+    // Route with path parameter (recommended approach)
+    app.get("/api/resources/:resourceType", (ctx) => {
+        return ctx.json({ 
+            message: `Found resource type: ${ctx.params.resourceType}`,
+            path: ctx.request.url,
+            pathname: new URL(ctx.request.url).pathname,
+            params: ctx.params
+        });
+    });
+
+    // Route with multiple path parameters including URL-encoded spaces
+    app.get("/api/resources/:resourceType/:id", (ctx) => {
+        return ctx.json({ 
+            message: `Found resource: ${ctx.params.resourceType} with ID: ${ctx.params.id}`,
+            path: ctx.request.url,
+            pathname: new URL(ctx.request.url).pathname,
+            params: ctx.params
+        });
+    });
+
+    // Test route to show the difference
+    app.get("/test", (ctx) => {
+        return ctx.text(`
+<!DOCTYPE html>
+<html>
+<head>
+    <title>URL Encoding Test</title>
+</head>
+<body>
+    <h1>URL Encoding Test</h1>
+    <p>Test the following URLs:</p>
+    <ul>
+        <li><a href="/api/resources/Workspace Item">/api/resources/Workspace Item</a> (with space)</li>
+        <li><a href="/api/resources/Workspace%20Item">/api/resources/Workspace%20Item</a> (URL encoded)</li>
+        <li><a href="/api/resources/My%20Resource">/api/resources/My%20Resource</a> (URL encoded with params)</li>
+        <li><a href="/api/resources/Doctype%20Permission/01992af8-1c69-7000-9219-9b83c2feb2d6">/api/resources/Doctype%20Permission/01992af8-1c69-7000-9219-9b83c2feb2d6</a> (URL encoded with ID)</li>
+    </ul>
+    
+    <h2>Test with JavaScript fetch:</h2>
+    <button onclick="testFetch('/api/resources/Workspace Item')">Test with space</button>
+    <button onclick="testFetch('/api/resources/Workspace%20Item')">Test URL encoded</button>
+    <button onclick="testFetch('/api/resources/My%20Resource')">Test with params</button>
+    <button onclick="testFetch('/api/resources/Doctype%20Permission/01992af8-1c69-7000-9219-9b83c2feb2d6')">Test with ID</button>
+    
+    <div id="result"></div>
+    
+    <script>
+        async function testFetch(url) {
+            try {
+                const response = await fetch(url);
+                const data = await response.json();
+                document.getElementById('result').innerHTML = 
+                    '<h3>Result:</h3><pre>' + JSON.stringify(data, null, 2) + '</pre>';
+            } catch (error) {
+                document.getElementById('result').innerHTML = 
+                    '<h3>Error:</h3><pre>' + error.message + '</pre>';
+            }
+        }
+    </script>
+        `, 200, {
+            "Content-Type": "text/html"
+        });
+    });
+
+    app.start();
+    console.log(`Server is running on http://localhost:${app.server?.port}`);
+    console.log(`Test URL encoding at http://localhost:${app.server?.port}/test`);
+}
+
+main().catch(console.error);

package/example/websocket-example.ts

@@ -0,0 +1,132 @@
+import BXO from "../src";
+
+async function main() {
+    const app = new BXO({ serve: { port: 3000 } });
+
+    // HTTP routes
+    app.get("/", (ctx) => {
+        return ctx.text(`
+<!DOCTYPE html>
+<html>
+<head>
+    <title>BXO WebSocket Example</title>
+</head>
+<body>
+    <h1>BXO WebSocket Example</h1>
+    <div id="messages"></div>
+    <input type="text" id="messageInput" placeholder="Type a message...">
+    <button onclick="sendMessage()">Send</button>
+    <button onclick="connect()">Connect</button>
+    <button onclick="disconnect()">Disconnect</button>
+    
+    <script>
+        let ws = null;
+        
+        function connect() {
+            ws = new WebSocket('ws://localhost:3000/ws');
+            
+            ws.onopen = function() {
+                addMessage('Connected to WebSocket');
+            };
+            
+            ws.onmessage = function(event) {
+                addMessage('Received: ' + event.data);
+            };
+            
+            ws.onclose = function() {
+                addMessage('Disconnected from WebSocket');
+            };
+            
+            ws.onerror = function(error) {
+                addMessage('Error: ' + error);
+            };
+        }
+        
+        function disconnect() {
+            if (ws) {
+                ws.close();
+                ws = null;
+            }
+        }
+        
+        function sendMessage() {
+            const input = document.getElementById('messageInput');
+            if (ws && input.value) {
+                ws.send(input.value);
+                addMessage('Sent: ' + input.value);
+                input.value = '';
+            }
+        }
+        
+        function addMessage(message) {
+            const messages = document.getElementById('messages');
+            const div = document.createElement('div');
+            div.textContent = new Date().toLocaleTimeString() + ': ' + message;
+            messages.appendChild(div);
+            messages.scrollTop = messages.scrollHeight;
+        }
+        
+        // Allow Enter key to send message
+        document.getElementById('messageInput').addEventListener('keypress', function(e) {
+            if (e.key === 'Enter') {
+                sendMessage();
+            }
+        });
+    </script>
+        `, 200, {
+            "Content-Type": "text/html"
+        });
+    });
+
+    // WebSocket route
+    app.ws("/ws", {
+        open(ws) {
+            console.log("WebSocket connection opened");
+            ws.send("Welcome to BXO WebSocket!");
+        },
+        
+        message(ws, message) {
+            console.log("Received message:", message);
+            // Echo the message back
+            ws.send(`Echo: ${message}`);
+        },
+        
+        close(ws, code, reason) {
+            console.log(`WebSocket connection closed: ${code} ${reason}`);
+        },
+        
+        ping(ws, data) {
+            console.log("Ping received:", data);
+        },
+        
+        pong(ws, data) {
+            console.log("Pong received:", data);
+        }
+    });
+
+    // Another WebSocket route with parameters
+    app.ws("/chat/:room", {
+        open(ws) {
+            console.log(`WebSocket connection opened for room: ${ws.data?.room || 'unknown'}`);
+            ws.send(`Welcome to chat room: ${ws.data?.room || 'unknown'}`);
+        },
+        
+        message(ws, message) {
+            const room = ws.data?.room || 'unknown';
+            console.log(`Message in room ${room}:`, message);
+            ws.send(`[${room}] Echo: ${message}`);
+        },
+        
+        close(ws, code, reason) {
+            const room = ws.data?.room || 'unknown';
+            console.log(`WebSocket connection closed for room ${room}: ${code} ${reason}`);
+        }
+    });
+
+    app.start();
+    console.log(`Server is running on http://localhost:${app.server?.port}`);
+    console.log(`WebSocket available at ws://localhost:${app.server?.port}/ws`);
+    console.log(`Chat WebSocket available at ws://localhost:${app.server?.port}/chat/:room`);
+}
+
+main().catch(console.error);

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "bxo",
-  "module": "index.ts",
-  "version": "0.0.5-dev.8",
-  "description": "A simple and lightweight web framework for Bun",
+  "module": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./plugins": "./plugins/index.ts"
+  },
+  "version": "0.0.5-dev.80",
   "type": "module",
   "devDependencies": {
     "@types/bun": "latest"
   },
-  "exports": {
-    ".": "./index.ts",
-    "./plugins": "./plugins/index.ts"
-  },
   "peerDependencies": {
     "typescript": "^5"
   },
   "dependencies": {
-    "zod": "^4.0.5"
+    "zod": "^4.1.5",
+    "zod-openapi": "^5.4.0"
   }
 }