bxo 0.0.5-dev.50 → 0.0.5-dev.52

package/REFACTOR_README.md

@@ -0,0 +1,209 @@
+# BXO Framework - Refactored Structure
+
+The BXO framework has been completely refactored to be more modular, maintainable, and easier to understand. The functionality remains exactly the same, but the code is now organized into logical modules.
+
+## 🏗️ New Directory Structure
+
+```
+src/
+├── core/           # Core BXO class and main logic
+├── types/          # TypeScript type definitions
+├── utils/          # Utility functions and helpers
+├── handlers/       # Request handling logic
+├── plugins/        # Plugin system (existing)
+├── middleware/     # Middleware system (existing)
+└── index.ts        # Main export file
+```
+
+## 📁 Module Breakdown
+
+### `src/types/index.ts`
+- All TypeScript interfaces and types
+- Zod schema type utilities
+- Context, Route, and Plugin interfaces
+- File upload type definitions
+
+### `src/utils/index.ts`
+- Core utility functions for parsing requests
+- Validation helpers
+- Cookie handling utilities
+- File upload utilities
+
+### `src/utils/route-matcher.ts`
+- Route matching logic for HTTP routes
+- WebSocket route matching
+- Wildcard and parameter handling
+
+### `src/utils/context-factory.ts`
+- Context object creation
+- Validation integration
+- Cookie management
+
+### `src/utils/response-handler.ts`
+- Response processing and formatting
+- Error response creation
+- File and Bun.file handling
+
+### `src/utils/helpers.ts`
+- Helper functions (error, file, redirect)
+- Cookie options utilities
+
+### `src/handlers/request-handler.ts`
+- Main request processing logic
+- Middleware and hook execution
+- WebSocket upgrade handling
+- Error handling
+
+### `src/core/bxo.ts`
+- Main BXO class
+- Route registration methods
+- Server lifecycle management
+- Plugin system integration
+
+## 🔄 Migration Guide
+
+### Before (Old Structure)
+```typescript
+import BXO from './index';
+
+const app = new BXO();
+app.get('/', () => 'Hello World');
+```
+
+### After (New Structure)
+```typescript
+import BXO from './index'; // Still works exactly the same!
+
+const app = new BXO();
+app.get('/', () => 'Hello World');
+```
+
+**No changes needed in your existing code!** The API is completely backward compatible.
+
+## ✨ Benefits of Refactoring
+
+### 1. **Better Separation of Concerns**
+- Each module has a single responsibility
+- Easier to understand what each part does
+- Clear boundaries between different functionalities
+
+### 2. **Improved Maintainability**
+- Smaller, focused files are easier to modify
+- Changes to one feature don't affect others
+- Better testability with isolated modules
+
+### 3. **Enhanced Readability**
+- Code is organized logically
+- Related functionality is grouped together
+- Easier to find specific features
+
+### 4. **Better Type Safety**
+- Types are centralized and well-defined
+- Easier to maintain type consistency
+- Better IntelliSense support
+
+### 5. **Easier Testing**
+- Individual modules can be tested in isolation
+- Mocking is simpler with clear interfaces
+- Unit tests are more focused
+
+## 🧪 Testing the Refactored Structure
+
+Run the test file to verify everything works:
+
+```bash
+bun run test-refactored.ts
+```
+
+## 📚 Usage Examples
+
+### Basic Usage (Unchanged)
+```typescript
+import BXO, { z } from './index';
+
+const app = new BXO();
+
+app.get('/', () => 'Hello World');
+
+app.post('/users', async (ctx) => {
+  return { message: 'User created' };
+}, {
+  body: z.object({
+    name: z.string(),
+    email: z.string().email()
+  })
+});
+
+app.start(3000);
+```
+
+### File Uploads (Unchanged)
+```typescript
+import { isFileUpload, saveUploadedFile } from './index';
+
+app.post('/upload', async (ctx) => {
+  if (ctx.body.avatar && isFileUpload(ctx.body.avatar)) {
+    await saveUploadedFile(ctx.body.avatar, './uploads/avatar.jpg');
+  }
+  return { message: 'Upload successful' };
+});
+```
+
+### WebSockets (Unchanged)
+```typescript
+app.ws('/chat', {
+  onOpen: (ws) => console.log('Connected'),
+  onMessage: (ws, message) => ws.send(`Echo: ${message}`)
+});
+```
+
+## 🔧 Development
+
+### Adding New Features
+1. **New utility functions**: Add to `src/utils/`
+2. **New types**: Add to `src/types/`
+3. **New handlers**: Add to `src/handlers/`
+4. **New core features**: Add to `src/core/`
+
+### Modifying Existing Features
+- **Route matching**: Edit `src/utils/route-matcher.ts`
+- **Request parsing**: Edit `src/utils/index.ts`
+- **Response handling**: Edit `src/utils/response-handler.ts`
+- **Context creation**: Edit `src/utils/context-factory.ts`
+
+## 📦 Build and Distribution
+
+The main `index.ts` file now simply re-exports everything from the new structure:
+
+```typescript
+// Re-export everything from the refactored source
+export * from './src/index';
+```
+
+This means:
+- ✅ **Zero breaking changes** for existing users
+- ✅ **Same import syntax** as before
+- ✅ **All functionality preserved**
+- ✅ **Better internal organization**
+
+## 🎯 Future Improvements
+
+With this new structure, we can now easily:
+
+1. **Add new modules** without cluttering the main file
+2. **Implement better testing** with isolated components
+3. **Add new features** in dedicated modules
+4. **Improve performance** by optimizing specific modules
+5. **Better documentation** with focused module descriptions
+
+## 🤝 Contributing
+
+When contributing to the framework:
+
+1. **Identify the right module** for your changes
+2. **Keep modules focused** on their specific responsibility
+3. **Update types** if adding new interfaces
+4. **Add tests** for new functionality
+5. **Update documentation** for new features
+
+The refactored structure makes it much easier to contribute and maintain the codebase!