bxo 0.0.10-dev.4 → 0.0.10-dev.6

package/example/array-query-documentation.md

@@ -0,0 +1,155 @@
+# Array Query Parameters in BXO Framework
+
+The BXO framework has built-in support for handling arrays from URL search parameters. This guide explains the different ways to pass and receive arrays.
+
+## How It Works
+
+The framework automatically parses URL search parameters and converts multiple values with the same key into arrays. This happens in the `parseQuery` function which:
+
+1. **Handles array notation**: Keys ending with `[]` are automatically converted to arrays
+2. **Multiple values**: When the same key appears multiple times, values are collected into an array
+3. **Type coercion**: Works with Zod schemas for validation and type conversion
+
+## URL Formats for Arrays
+
+### Method 1: Multiple Parameters with Same Key
+```
+/api/tags?tags=javascript&tags=typescript&tags=nodejs
+```
+**Result**: `{ tags: ["javascript", "typescript", "nodejs"] }`
+
+### Method 2: Bracket Notation
+```
+/api/items?items[]=item1&items[]=item2&items[]=item3
+```
+**Result**: `{ items: ["item1", "item2", "item3"] }`
+
+### Method 3: Mixed Approach
+```
+/api/search?categories=tech&categories=web&tags[]=javascript&tags[]=react
+```
+**Result**: `{ categories: ["tech", "web"], tags: ["javascript", "react"] }`
+
+## Code Examples
+
+### Basic Array Handling
+```typescript
+app.get("/api/tags", (ctx) => {
+    // Access array directly from ctx.query
+    const tags = ctx.query.tags; // string[] or string
+    return ctx.json({ tags });
+});
+```
+
+### With Zod Validation
+```typescript
+app.get("/api/filtered-tags", (ctx) => {
+    return ctx.json({ tags: ctx.query.tags });
+}, {
+    query: z.object({
+        tags: z.array(z.string()).optional(),
+        category: z.string().optional()
+    })
+});
+```
+
+### Type Coercion for Numbers
+```typescript
+app.get("/api/numbers", (ctx) => {
+    return ctx.json({ numbers: ctx.query.numbers });
+}, {
+    query: z.object({
+        numbers: z.array(z.coerce.number()).optional()
+    })
+});
+```
+
+### Complex Validation
+```typescript
+app.get("/api/advanced-search", (ctx) => {
+    return ctx.json({ filters: ctx.query.filters });
+}, {
+    query: z.object({
+        filters: z.array(z.string()).optional(),
+        sort: z.array(z.enum(["name", "date", "price"])).optional(),
+        limit: z.coerce.number().min(1).max(100).optional()
+    })
+});
+```
+
+## Framework Implementation Details
+
+The array parsing happens in the `parseQuery` function:
+
+```typescript
+function parseQuery(searchParams: URLSearchParams, schema?: z.ZodTypeAny): any {
+    const out: QueryObject = {};
+    for (const [k, v] of searchParams.entries()) {
+        // Handle array notation like fields[] -> fields
+        const key = k.endsWith('[]') ? k.slice(0, -2) : k;
+        
+        if (key in out) {
+            const existing = out[key];
+            if (Array.isArray(existing)) out[key] = [...existing, v];
+            else out[key] = [existing as string, v];
+        } else out[key] = v;
+    }
+    // ... schema validation
+    return out;
+}
+```
+
+## Key Features
+
+1. **Automatic Array Detection**: Multiple values with the same key become arrays
+2. **Bracket Notation Support**: `param[]` syntax is supported
+3. **Mixed Types**: Single values and arrays can coexist
+4. **Zod Integration**: Full validation and type coercion support
+5. **Type Safety**: TypeScript support with proper typing
+
+## Common Use Cases
+
+### Filtering and Search
+```
+/api/products?categories=electronics&categories=computers&tags=on-sale&tags=featured
+```
+
+### Bulk Operations
+```
+/api/users?ids=1&ids=2&ids=3&ids=4
+```
+
+### Sorting and Ordering
+```
+/api/posts?sort=date&sort=title&order=desc&order=asc
+```
+
+### Complex Queries
+```
+/api/search?filters=active&filters=featured&categories=tech&categories=web&tags[]=javascript&tags[]=react&limit=10
+```
+
+## Best Practices
+
+1. **Use consistent naming**: Choose either bracket notation or repeated parameters
+2. **Validate with Zod**: Always validate array parameters for type safety
+3. **Handle optional arrays**: Use `.optional()` for arrays that might not be present
+4. **Type coercion**: Use `z.coerce.number()` for numeric arrays
+5. **Enum validation**: Use `z.enum()` for restricted value arrays
+
+## Testing Your Arrays
+
+You can test array parameters using curl:
+
+```bash
+# Simple array
+curl "http://localhost:3000/api/tags?tags=javascript&tags=typescript"
+
+# Bracket notation
+curl "http://localhost:3000/api/items?items[]=item1&items[]=item2"
+
+# Mixed approach
+curl "http://localhost:3000/api/search?categories=tech&tags[]=javascript&tags[]=react"
+```
+
+The framework handles all these formats automatically, making it easy to work with arrays in your API endpoints.

package/example/array-query-example.ts

@@ -0,0 +1,90 @@
+import BXO, { z } from "../src";
+
+async function main() {
+    const app = new BXO({ serve: { port: 3000 } });
+
+    // Example 1: Simple array with multiple values
+    app.get("/api/tags", (ctx) => {
+        return ctx.json({
+            message: "Tags received",
+            tags: ctx.query.tags,
+            query: ctx.query
+        });
+    });
+
+    // Example 2: Array with validation using Zod schema
+    app.get("/api/filtered-tags", (ctx) => {
+        return ctx.json({
+            message: "Filtered tags received",
+            tags: ctx.query.tags,
+            query: ctx.query
+        });
+    }, {
+        query: z.object({
+            tags: z.array(z.string()).optional(),
+            category: z.string().optional()
+        })
+    });
+
+    // Example 3: Multiple arrays in the same query
+    app.get("/api/search", (ctx) => {
+        return ctx.json({
+            message: "Search parameters received",
+            categories: ctx.query.categories,
+            tags: ctx.query.tags,
+            ids: ctx.query.ids,
+            query: ctx.query
+        });
+    });
+
+    // Example 4: Array with mixed data types
+    app.get("/api/numbers", (ctx) => {
+        return ctx.json({
+            message: "Numbers received",
+            numbers: ctx.query.numbers,
+            query: ctx.query
+        });
+    }, {
+        query: z.object({
+            numbers: z.array(z.coerce.number()).optional()
+        })
+    });
+
+    // Example 5: Nested array-like structure (using bracket notation)
+    app.get("/api/items", (ctx) => {
+        return ctx.json({
+            message: "Items received",
+            items: ctx.query.items,
+            query: ctx.query
+        });
+    });
+
+    // Example 6: Complex query with arrays and validation
+    app.get("/api/advanced-search", (ctx) => {
+        return ctx.json({
+            message: "Advanced search parameters received",
+            filters: ctx.query.filters,
+            sort: ctx.query.sort,
+            limit: ctx.query.limit,
+            query: ctx.query
+        });
+    }, {
+        query: z.object({
+            filters: z.array(z.string()).optional(),
+            sort: z.array(z.enum(["name", "date", "price"])).optional(),
+            limit: z.coerce.number().min(1).max(100).optional()
+        })
+    });
+
+    app.start();
+    console.log("🚀 Server running on http://localhost:3000");
+    console.log("\n📝 Array Query Examples:");
+    console.log("1. Simple array: http://localhost:3000/api/tags?tags=javascript&tags=typescript&tags=nodejs");
+    console.log("2. With validation: http://localhost:3000/api/filtered-tags?tags=web&tags=api&category=development");
+    console.log("3. Multiple arrays: http://localhost:3000/api/search?categories=tech&categories=web&tags=javascript&tags=react&ids=1&ids=2&ids=3");
+    console.log("4. Numbers array: http://localhost:3000/api/numbers?numbers=1&numbers=2&numbers=3&numbers=42");
+    console.log("5. Bracket notation: http://localhost:3000/api/items?items[]=item1&items[]=item2&items[]=item3");
+    console.log("6. Advanced search: http://localhost:3000/api/advanced-search?filters=active&filters=featured&sort=name&sort=date&limit=10");
+}
+
+main();

package/example/auto-array-parse-example.ts

@@ -0,0 +1,90 @@
+import BXO, { z } from "../src";
+
+async function main() {
+    console.log("🚀 Testing BXO autoArrayParse feature\n");
+
+    // Example 1: Default behavior (autoArrayParse: true)
+    console.log("📝 Example 1: Default autoArrayParse (enabled)");
+    const app1 = new BXO({ serve: { port: 3001 } }); // Default: autoArrayParse: true
+
+    app1.get("/api/tags", (ctx) => {
+        return ctx.json({
+            message: "Default autoArrayParse - always arrays",
+            tags: ctx.query.tags,
+            isArray: Array.isArray(ctx.query.tags),
+            query: ctx.query
+        });
+    });
+
+    // Example 2: Explicitly enabled
+    console.log("📝 Example 2: Explicitly enabled autoArrayParse");
+    const app2 = new BXO({ 
+        serve: { port: 3002 },
+        autoArrayParse: true 
+    });
+
+    app2.get("/api/tags", (ctx) => {
+        return ctx.json({
+            message: "Explicitly enabled autoArrayParse",
+            tags: ctx.query.tags,
+            isArray: Array.isArray(ctx.query.tags),
+            query: ctx.query
+        });
+    });
+
+    // Example 3: Disabled
+    console.log("📝 Example 3: Disabled autoArrayParse");
+    const app3 = new BXO({ 
+        serve: { port: 3003 },
+        autoArrayParse: false 
+    });
+
+    app3.get("/api/tags", (ctx) => {
+        return ctx.json({
+            message: "Disabled autoArrayParse - original behavior",
+            tags: ctx.query.tags,
+            isArray: Array.isArray(ctx.query.tags),
+            query: ctx.query
+        });
+    });
+
+    // Example 4: With Zod validation
+    console.log("📝 Example 4: With Zod validation");
+    const app4 = new BXO({ 
+        serve: { port: 3004 },
+        autoArrayParse: true 
+    });
+
+    app4.get("/api/validated-tags", (ctx) => {
+        return ctx.json({
+            message: "Validated with autoArrayParse",
+            tags: ctx.query.tags,
+            isArray: Array.isArray(ctx.query.tags),
+            query: ctx.query
+        });
+    }, {
+        query: z.object({
+            tags: z.array(z.string()).optional()
+        })
+    });
+
+    // Start all servers
+    app1.start();
+    app2.start();
+    app3.start();
+    app4.start();
+
+    console.log("✅ All servers started!");
+    console.log("\n🧪 Test URLs:");
+    console.log("1. Default (enabled): http://localhost:3001/api/tags?tags=javascript");
+    console.log("2. Explicit (enabled): http://localhost:3002/api/tags?tags=javascript");
+    console.log("3. Disabled: http://localhost:3003/api/tags?tags=javascript");
+    console.log("4. With validation: http://localhost:3004/api/validated-tags?tags=javascript");
+    console.log("\n🔍 Multiple values:");
+    console.log("1. Default: http://localhost:3001/api/tags?tags=javascript&tags=typescript");
+    console.log("2. Explicit: http://localhost:3002/api/tags?tags=javascript&tags=typescript");
+    console.log("3. Disabled: http://localhost:3003/api/tags?tags=javascript&tags=typescript");
+    console.log("4. With validation: http://localhost:3004/api/validated-tags?tags=javascript&tags=typescript");
+}
+
+main();

package/example/recommended-array-example.ts

@@ -0,0 +1,100 @@
+import BXO, { z } from "../src";
+
+async function main() {
+    const app = new BXO({ serve: { port: 3000 } });
+
+    // RECOMMENDED APPROACH: Always parse to array if we expect array
+    app.get("/api/tags", (ctx) => {
+        return ctx.json({
+            message: "Tags endpoint - always returns array",
+            tags: ctx.query.tags,
+            count: ctx.query.tags?.length || 0,
+            isArray: Array.isArray(ctx.query.tags)
+        });
+    }, {
+        query: z.object({
+            tags: z.union([
+                z.string(),
+                z.array(z.string())
+            ]).transform(val => Array.isArray(val) ? val : [val]).optional()
+        })
+    });
+
+    // Alternative: Handle in code (also good approach)
+    app.get("/api/categories", (ctx) => {
+        // Normalize to array in code
+        let categories = ctx.query.categories;
+        if (categories && !Array.isArray(categories)) {
+            categories = [categories];
+        }
+        
+        return ctx.json({
+            message: "Categories endpoint - normalized to array",
+            categories: categories || [],
+            count: categories?.length || 0,
+            isArray: Array.isArray(categories)
+        });
+    });
+
+    // For required arrays with default
+    app.get("/api/filters", (ctx) => {
+        return ctx.json({
+            message: "Filters endpoint - required array",
+            filters: ctx.query.filters,
+            count: ctx.query.filters.length,
+            isArray: Array.isArray(ctx.query.filters)
+        });
+    }, {
+        query: z.object({
+            filters: z.union([
+                z.string(),
+                z.array(z.string())
+            ]).transform(val => Array.isArray(val) ? val : [val]).default([])
+        })
+    });
+
+    // Complex example with multiple array parameters
+    app.get("/api/search", (ctx) => {
+        return ctx.json({
+            message: "Search endpoint with multiple arrays",
+            categories: ctx.query.categories,
+            tags: ctx.query.tags,
+            ids: ctx.query.ids,
+            categoryCount: ctx.query.categories?.length || 0,
+            tagCount: ctx.query.tags?.length || 0,
+            idCount: ctx.query.ids?.length || 0
+        });
+    }, {
+        query: z.object({
+            categories: z.union([
+                z.string(),
+                z.array(z.string())
+            ]).transform(val => Array.isArray(val) ? val : [val]).optional(),
+            tags: z.union([
+                z.string(),
+                z.array(z.string())
+            ]).transform(val => Array.isArray(val) ? val : [val]).optional(),
+            ids: z.union([
+                z.string(),
+                z.array(z.string())
+            ]).transform(val => Array.isArray(val) ? val : [val]).optional()
+        })
+    });
+
+    app.start();
+    console.log("🚀 Server running on http://localhost:3000");
+    console.log("\n📝 RECOMMENDED Array Examples:");
+    console.log("✅ BEST: Single value -> array: http://localhost:3000/api/tags?tags=javascript");
+    console.log("✅ BEST: Multiple values -> array: http://localhost:3000/api/tags?tags=javascript&tags=typescript");
+    console.log("✅ BEST: No params: http://localhost:3000/api/tags");
+    console.log("");
+    console.log("✅ Alternative: Code normalization: http://localhost:3000/api/categories?categories=web");
+    console.log("✅ Alternative: Multiple: http://localhost:3000/api/categories?categories=web&categories=mobile");
+    console.log("");
+    console.log("✅ Required with default: http://localhost:3000/api/filters");
+    console.log("✅ Required with value: http://localhost:3000/api/filters?filters=active");
+    console.log("");
+    console.log("✅ Complex search: http://localhost:3000/api/search?categories=tech&tags=javascript&ids=1&ids=2");
+}
+
+main();

package/example/single-item-array-documentation.md

@@ -0,0 +1,217 @@
+# Single Item Arrays in BXO Framework
+
+When you have only one item in what would normally be an array, the BXO framework's behavior depends on how you structure your URL parameters.
+
+## Key Behavior
+
+### **Single Value (No Bracket Notation)**
+```
+/api/tags?tag=javascript
+```
+**Result**: `{ tag: "javascript" }` (string, not array)
+
+### **Single Value with Bracket Notation**
+```
+/api/tags?tag[]=javascript
+```
+**Result**: `{ tag: ["javascript"] }` (array with one item)
+
+### **Multiple Values**
+```
+/api/tags?tag=javascript&tag=typescript
+```
+**Result**: `{ tag: ["javascript", "typescript"] }` (array)
+
+## Framework Logic
+
+The framework's `parseQuery` function works like this:
+
+```typescript
+if (key in out) {
+    const existing = out[key];
+    if (Array.isArray(existing)) out[key] = [...existing, v];
+    else out[key] = [existing as string, v];  // Convert to array on second occurrence
+} else out[key] = v;  // First occurrence stays as string
+```
+
+**This means:**
+- **First occurrence**: Single value remains a string
+- **Second occurrence**: Converts to array
+- **Bracket notation**: Always creates array
+
+## Handling Single Item Arrays
+
+### **Method 1: Always Use Bracket Notation**
+```typescript
+// URL: /api/tags?tag[]=javascript
+app.get("/api/tags", (ctx) => {
+    const tags = ctx.query.tag; // Always array: ["javascript"]
+    return ctx.json({ tags });
+});
+```
+
+### **Method 2: Handle Both Cases in Code**
+```typescript
+app.get("/api/tags", (ctx) => {
+    let tags = ctx.query.tag;
+    
+    // Normalize to array
+    if (!Array.isArray(tags)) {
+        tags = [tags];
+    }
+    
+    return ctx.json({ tags });
+});
+```
+
+### **Method 3: Use Zod Union Type**
+```typescript
+app.get("/api/tags", (ctx) => {
+    return ctx.json({ tags: ctx.query.tags });
+}, {
+    query: z.object({
+        tags: z.union([
+            z.string(),
+            z.array(z.string())
+        ]).optional()
+    })
+});
+```
+
+### **Method 4: Force Array with Zod Transform**
+```typescript
+app.get("/api/tags", (ctx) => {
+    return ctx.json({ tags: ctx.query.tags });
+}, {
+    query: z.object({
+        tags: z.union([
+            z.string(),
+            z.array(z.string())
+        ]).transform(val => Array.isArray(val) ? val : [val]).optional()
+    })
+});
+```
+
+### **Method 5: Default Empty Array**
+```typescript
+app.get("/api/tags", (ctx) => {
+    return ctx.json({ tags: ctx.query.tags });
+}, {
+    query: z.object({
+        tags: z.array(z.string()).default([])
+    })
+});
+```
+
+## Real-World Examples
+
+### **Search with Optional Filters**
+```typescript
+// URL: /api/search?filters=active
+// URL: /api/search?filters=active&filters=featured
+app.get("/api/search", (ctx) => {
+    let filters = ctx.query.filters;
+    
+    // Normalize to array
+    if (filters && !Array.isArray(filters)) {
+        filters = [filters];
+    }
+    
+    return ctx.json({ 
+        filters: filters || [],
+        count: filters?.length || 0 
+    });
+});
+```
+
+### **Bulk Operations**
+```typescript
+// URL: /api/users?ids=1
+// URL: /api/users?ids=1&ids=2&ids=3
+app.get("/api/users", (ctx) => {
+    const ids = Array.isArray(ctx.query.ids) 
+        ? ctx.query.ids 
+        : ctx.query.ids ? [ctx.query.ids] : [];
+    
+    return ctx.json({ 
+        userIds: ids,
+        count: ids.length 
+    });
+});
+```
+
+### **Tag System**
+```typescript
+// URL: /api/posts?tags=javascript
+// URL: /api/posts?tags=javascript&tags=react
+app.get("/api/posts", (ctx) => {
+    const tags = ctx.query.tags;
+    const tagArray = Array.isArray(tags) ? tags : (tags ? [tags] : []);
+    
+    return ctx.json({ 
+        posts: [],
+        filters: { tags: tagArray }
+    });
+});
+```
+
+## Best Practices
+
+### **1. Be Explicit About Array Expectations**
+```typescript
+// Good: Always expect array
+app.get("/api/tags", (ctx) => {
+    const tags = Array.isArray(ctx.query.tags) 
+        ? ctx.query.tags 
+        : ctx.query.tags ? [ctx.query.tags] : [];
+    // Process tags...
+});
+```
+
+### **2. Use Zod for Type Safety**
+```typescript
+// Good: Zod handles the union type
+app.get("/api/tags", (ctx) => {
+    return ctx.json({ tags: ctx.query.tags });
+}, {
+    query: z.object({
+        tags: z.union([z.string(), z.array(z.string())])
+            .transform(val => Array.isArray(val) ? val : [val])
+    })
+});
+```
+
+### **3. Document Expected Format**
+```typescript
+// Good: Clear documentation
+app.get("/api/tags", (ctx) => {
+    // Expects: ?tags=value OR ?tags=value1&tags=value2 OR ?tags[]=value
+    const tags = ctx.query.tags;
+    // Handle both cases...
+});
+```
+
+## Testing Single Item Arrays
+
+```bash
+# Single value (string)
+curl "http://localhost:3000/api/tags?tag=javascript"
+
+# Single value with bracket (array)
+curl "http://localhost:3000/api/tags?tag[]=javascript"
+
+# Multiple values (array)
+curl "http://localhost:3000/api/tags?tag=javascript&tag=typescript"
+
+# Mixed approach
+curl "http://localhost:3000/api/tags?tag[]=javascript&tag=typescript"
+```
+
+## Summary
+
+- **Single value without brackets**: Returns string
+- **Single value with brackets**: Returns array with one item
+- **Multiple values**: Returns array
+- **Best practice**: Use bracket notation if you always want arrays
+- **Alternative**: Handle both cases in your code with type checking
+- **Recommended**: Use Zod transforms for consistent array handling

package/example/single-item-array-example.ts

@@ -0,0 +1,121 @@
+import BXO, { z } from "../src";
+
+async function main() {
+    const app = new BXO({ serve: { port: 3000 } });
+
+    // Example 1: Single item array - shows the behavior difference
+    app.get("/api/single-tag", (ctx) => {
+        return ctx.json({
+            message: "Single tag analysis",
+            tag: ctx.query.tag,
+            isArray: Array.isArray(ctx.query.tag),
+            type: typeof ctx.query.tag,
+            query: ctx.query
+        });
+    });
+
+    // Example 2: Single item with bracket notation
+    app.get("/api/single-item-bracket", (ctx) => {
+        return ctx.json({
+            message: "Single item with bracket notation",
+            item: ctx.query.item,
+            isArray: Array.isArray(ctx.query.item),
+            type: typeof ctx.query.item,
+            query: ctx.query
+        });
+    });
+
+    // Example 3: Mixed single and multiple values
+    app.get("/api/mixed", (ctx) => {
+        return ctx.json({
+            message: "Mixed single and multiple values",
+            single: ctx.query.single,
+            multiple: ctx.query.multiple,
+            singleIsArray: Array.isArray(ctx.query.single),
+            multipleIsArray: Array.isArray(ctx.query.multiple),
+            query: ctx.query
+        });
+    });
+
+    // Example 4: With Zod validation - handles both cases
+    app.get("/api/validated-tags", (ctx) => {
+        return ctx.json({
+            message: "Validated tags",
+            tags: ctx.query.tags,
+            isArray: Array.isArray(ctx.query.tags),
+            query: ctx.query
+        });
+    }, {
+        query: z.object({
+            tags: z.union([
+                z.string(),
+                z.array(z.string())
+            ]).optional()
+        })
+    });
+
+    // Example 4b: Better approach - always parse to array if we expect array
+    app.get("/api/smart-tags", (ctx) => {
+        return ctx.json({
+            message: "Smart tags - always array",
+            tags: ctx.query.tags,
+            isArray: Array.isArray(ctx.query.tags),
+            query: ctx.query
+        });
+    }, {
+        query: z.object({
+            tags: z.union([
+                z.string(),
+                z.array(z.string())
+            ]).transform(val => Array.isArray(val) ? val : [val]).optional()
+        })
+    });
+
+    // Example 5: Force array with Zod transform
+    app.get("/api/force-array", (ctx) => {
+        return ctx.json({
+            message: "Force array transformation",
+            tags: ctx.query.tags,
+            isArray: Array.isArray(ctx.query.tags),
+            query: ctx.query
+        });
+    }, {
+        query: z.object({
+            tags: z.union([
+                z.string(),
+                z.array(z.string())
+            ]).transform(val => Array.isArray(val) ? val : [val]).optional()
+        })
+    });
+
+    // Example 6: Always array with default
+    app.get("/api/always-array", (ctx) => {
+        return ctx.json({
+            message: "Always array with default",
+            tags: ctx.query.tags,
+            isArray: Array.isArray(ctx.query.tags),
+            query: ctx.query
+        });
+    }, {
+        query: z.object({
+            tags: z.array(z.string()).default([])
+        })
+    });
+
+    app.start();
+    console.log("🚀 Server running on http://localhost:3000");
+    console.log("\n📝 Single Item Array Examples:");
+    console.log("1. Single value: http://localhost:3000/api/single-tag?tag=javascript");
+    console.log("2. Single bracket: http://localhost:3000/api/single-item-bracket?item[]=single");
+    console.log("3. Mixed values: http://localhost:3000/api/mixed?single=one&multiple=first&multiple=second");
+    console.log("4. Validated single: http://localhost:3000/api/validated-tags?tags=javascript");
+    console.log("5. Validated multiple: http://localhost:3000/api/validated-tags?tags=javascript&tags=typescript");
+    console.log("6. Smart tags (BEST): http://localhost:3000/api/smart-tags?tags=javascript");
+    console.log("7. Smart tags multiple: http://localhost:3000/api/smart-tags?tags=javascript&tags=typescript");
+    console.log("8. Force array single: http://localhost:3000/api/force-array?tags=javascript");
+    console.log("9. Force array multiple: http://localhost:3000/api/force-array?tags=javascript&tags=typescript");
+    console.log("10. Always array: http://localhost:3000/api/always-array");
+    console.log("11. Always array with value: http://localhost:3000/api/always-array?tags=javascript");
+}
+
+main();

package/package.json

@@ -5,7 +5,7 @@
     ".": "./src/index.ts",
     "./plugins": "./plugins/index.ts"
   },
-  "version": "0.0.10-dev.4",
+  "version": "0.0.10-dev.6",
   "type": "module",
   "devDependencies": {
     "@types/bun": "latest"

package/src/index.ts

@@ -191,9 +191,21 @@ function serializeCookie(name: string, value: string, options: CookieOptions = {
     return cookie;
 }
 
-function parseQuery(searchParams: URLSearchParams): QueryObject;
-function parseQuery<T extends z.ZodTypeAny>(searchParams: URLSearchParams, schema: T): z.infer<T>;
-function parseQuery(searchParams: URLSearchParams, schema?: z.ZodTypeAny): any {
+function parseQuery(searchParams: URLSearchParams, autoArrayParse?: boolean): QueryObject;
+function parseQuery<T extends z.ZodTypeAny>(searchParams: URLSearchParams, schema: T, autoArrayParse?: boolean): z.infer<T>;
+function parseQuery(searchParams: URLSearchParams, schemaOrAutoArrayParse?: z.ZodTypeAny | boolean, autoArrayParse?: boolean): any {
+    // Handle overloaded parameters
+    let schema: z.ZodTypeAny | undefined;
+    let shouldAutoArrayParse: boolean;
+    
+    if (typeof schemaOrAutoArrayParse === 'boolean') {
+        shouldAutoArrayParse = schemaOrAutoArrayParse;
+        schema = undefined;
+    } else {
+        shouldAutoArrayParse = autoArrayParse ?? false;
+        schema = schemaOrAutoArrayParse;
+    }
+    
     const out: QueryObject = {};
     for (const [k, v] of searchParams.entries()) {
         // Handle array notation like fields[] -> fields
@@ -203,8 +215,20 @@ function parseQuery(searchParams: URLSearchParams, schema?: z.ZodTypeAny): any {
             const existing = out[key];
             if (Array.isArray(existing)) out[key] = [...existing, v];
             else out[key] = [existing as string, v];
-        } else out[key] = v;
+        } else {
+            out[key] = v;
+        }
+    }
+    
+    // Apply autoArrayParse transformation if enabled
+    if (shouldAutoArrayParse) {
+        for (const [key, value] of Object.entries(out)) {
+            if (typeof value === 'string') {
+                out[key] = [value];
+            }
+        }
     }
+    
     if (schema) {
         return (schema as any).parse ? (schema as any).parse(out) : out;
     }
@@ -359,6 +383,7 @@ function toResponse(body: unknown, init?: ResponseInit): Response {
 export default class BXO {
     private routes: InternalRoute[] = [];
     private serveOptions: ServeOptions;
+    private autoArrayParse: boolean;
     public server?: ReturnType<typeof Bun.serve>;
 
     // Lifecycle hooks
@@ -367,8 +392,9 @@ export default class BXO {
     protected beforeResponseHooks: BeforeResponseHook[] = [];
     protected onErrorHooks: OnErrorHook[] = [];
 
-    constructor(options?: { serve?: ServeOptions }) {
+    constructor(options?: { serve?: ServeOptions; autoArrayParse?: boolean }) {
         this.serveOptions = options?.serve ?? {};
+        this.autoArrayParse = options?.autoArrayParse ?? true; // Default to true
     }
 
     getRoutes(): InternalRoute[] {
@@ -714,7 +740,7 @@ export default class BXO {
 
         // Parse query using schema if provided
         try {
-            queryObj = route.schema?.query ? parseQuery(url.searchParams, route.schema.query as any) : parseQuery(url.searchParams);
+            queryObj = route.schema?.query ? parseQuery(url.searchParams, route.schema.query as any, this.autoArrayParse) : parseQuery(url.searchParams, this.autoArrayParse);
         } catch (err: any) {
             const payload = err?.issues ? { error: "Validation Error", issues: err.issues } : { error: "Validation Error", issues: [], message: err.message };
             return new Response(JSON.stringify(payload), { status: 400, headers: { "Content-Type": "application/json" } });