baraqex 1.0.74 → 2.0.0

package/README.md

@@ -1,595 +1,395 @@
-# Baraqex 🚀
+<div align="center">
 
-A powerful, modern JavaScript/TypeScript framework for building universal web applications with seamless WebAssembly integration, server-side rendering, and full-stack capabilities.
+<img src="https://raw.githubusercontent.com/mohamedx2/baraqex/main/assets/logo.svg" alt="Baraqex Logo" width="180" height="180">
 
-## ✨ Features
-
-### 🎯 Core Features
-- **Universal JSX Support** - Modern React-like components without dependencies
-- **WebAssembly Integration** - Seamless Go WASM support for both browser and Node.js
-- **Server-Side Rendering** - Built-in SSR with hydration support
-- **Full-Stack Framework** - Complete backend server with API routes
-- **TypeScript First** - Full TypeScript support with excellent IntelliSense
-- **Zero Dependencies** - Lightweight core with optional features
-
-### 🌐 WebAssembly Features
-- **Browser WASM** - Load and execute Go WASM modules in the browser
-- **Server WASM** - Run Go WASM functions in Node.js environment
-- **Unified API** - Identical interface for browser and server environments
-- **Hot Reloading** - Development support with fast refresh
-
-### 🔧 Backend Features
-- **Express Integration** - Built on Express.js for reliability
-- **API Routes** - File-based API routing system
-- **Authentication** - JWT-based auth with middleware support
-- **Database Support** - MongoDB, MySQL, PostgreSQL adapters
-- **Static Serving** - Efficient static file serving
-
-## 📦 Installation
+# Baraqex
 
-```bash
-npm install baraqex
-```
+### ⚡ The Full-Stack Framework with WASM Superpowers
 
-## 🚀 Quick Start
+Build universal web applications with React-like syntax and Go-powered performance.
 
-### Frontend Usage
+[![npm version](https://img.shields.io/npm/v/baraqex?color=blue&label=npm)](https://www.npmjs.com/package/baraqex)
+[![npm downloads](https://img.shields.io/npm/dm/baraqex?color=blue)](https://www.npmjs.com/package/baraqex)
+[![GitHub stars](https://img.shields.io/github/stars/mohamedx2/baraqex?style=social)](https://github.com/mohamedx2/baraqex)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![Docs](https://img.shields.io/badge/Docs-baraqex.tech-blue)](https://www.baraqex.tech)
 
-```javascript
-import { jsx, useState } from 'baraqex';
-import { loadGoWasm, callWasmFunction } from 'baraqex';
+[Get Started](#-quick-start) · [Documentation](https://www.baraqex.tech/docs) · [Examples](#-examples) · [Contributing](#-contributing)
 
-function App() {
-  const [count, setCount] = useState(0);
-  const [wasmReady, setWasmReady] = useState(false);
+</div>
 
-  // Load WebAssembly module
-  useEffect(() => {
-    async function initWasm() {
-      await loadGoWasm('/app.wasm');
-      setWasmReady(true);
-    }
-    initWasm();
-  }, []);
-
-  const handleCalculate = () => {
-    if (wasmReady) {
-      // Call Go WASM function
-      const result = callWasmFunction('calculate', count);
-      console.log('WASM result:', result);
-    }
-  };
-
-  return (
-    <div>
-      <h1>Baraqex App</h1>
-      <p>Count: {count}</p>
-      <button onClick={() => setCount(count + 1)}>
-        Increment
-      </button>
-      <button onClick={handleCalculate} disabled={!wasmReady}>
-        Calculate with WASM
-      </button>
-    </div>
-  );
-}
-
-export default App;
-```
-
-### Server Usage
-
-```javascript
-import { createServer } from 'baraqex/server';
-import { loadGoWasmFromFile, callWasmFunction } from 'baraqex/server';
-
-// Create server
-const server = createServer({
-  port: 3000,
-  apiDir: './api',
-  pagesDir: './pages',
-  staticDir: './public'
-});
-
-// Load WASM for server-side processing
-async function initServerWasm() {
-  await loadGoWasmFromFile('./compute.wasm');
-  console.log('Server WASM ready!');
-}
-
-// Start server
-server.start().then(() => {
-  console.log('Server running on http://localhost:3000');
-  initServerWasm();
-});
-```
+---
 
-## 📖 Documentation
+## Why Baraqex?
 
-### WebAssembly Integration
+| Feature | Baraqex | Others |
+|---------|---------|--------|
+| 🚀 **WASM Integration** | Native Go/WASM support | Manual setup required |
+| 🔄 **Universal Rendering** | SSR + CSR + Static | Framework-specific |
+| ⚡ **Zero Config** | Works out of the box | Complex configuration |
+| 🎯 **Full-Stack** | Frontend + Backend + API | Separate tools needed |
+| 📦 **Tiny Bundle** | < 15KB gzipped | Often 50KB+ |
 
-#### Browser WASM
+---
 
-```javascript
-import { loadGoWasm, callWasmFunction, isWasmReady, getWasmFunctions } from 'baraqex';
+## ✨ Features
 
-// Load WASM module
-await loadGoWasm('/example.wasm', {
-  debug: true,
-  onLoad: (instance) => {
-    console.log('WASM loaded!', instance);
-  }
-});
+- **🔥 WebAssembly First** - Run Go code in the browser at near-native speed
+- **⚛️ React-like Syntax** - Familiar JSX with hooks (`useState`, `useEffect`, etc.)
+- **🌐 Universal Rendering** - SSR, CSR, and Static Generation
+- **🛣️ File-based Routing** - Automatic API routes from your file structure
+- **🔐 Built-in Auth** - JWT authentication with password hashing
+- **🗄️ Database Adapters** - MongoDB, PostgreSQL, MySQL out of the box
+- **📡 Real-time** - WebSocket support for live updates
+- **🎨 TypeScript** - Full type safety and IntelliSense
+- **🧪 Tested** - 140+ tests with 56% coverage
 
-// Check if ready
-if (isWasmReady()) {
-  // Get available functions
-  const functions = getWasmFunctions();
-  console.log('Available functions:', functions);
-  
-  // Call functions
-  const greeting = callWasmFunction('goHello', 'World');
-  const sum = callWasmFunction('goAdd', 10, 20);
-  const fibonacci = callWasmFunction('goFibonacci', 10);
-}
-```
+> **Built on [frontend-hamroun](https://www.npmjs.com/package/frontend-hamroun)** - The lightweight React-like core (~8KB gzipped)
 
-#### Server WASM
+---
 
-```javascript
-import { loadGoWasmFromFile, callWasmFunction } from 'baraqex/server';
+## 🚀 Quick Start
 
-// Load WASM from file
-await loadGoWasmFromFile('./example.wasm', {
-  debug: true,
-  goWasmPath: './wasm_exec.cjs'
-});
+### Create a New Project
 
-// Use identical API as browser
-const result = callWasmFunction('goCalculate', 42);
+```bash
+npx create-baraqex-app my-app
+cd my-app
+npm run dev
 ```
 
-#### Go WASM Example
-
-```go
-// main.go
-package main
-
-import (
-    "fmt"
-    "syscall/js"
-)
+### Or Install Manually
 
-func goHello(this js.Value, args []js.Value) interface{} {
-    name := args[0].String()
-    return fmt.Sprintf("Hello, %s from Go WASM!", name)
-}
-
-func goAdd(this js.Value, args []js.Value) interface{} {
-    a := args[0].Float()
-    b := args[1].Float()
-    return a + b
-}
-
-func main() {
-    // Register functions
-    js.Global().Set("goHello", js.FuncOf(goHello))
-    js.Global().Set("goAdd", js.FuncOf(goAdd))
-    
-    fmt.Println("Go WASM ready!")
-    
-    // Keep running
-    select {}
-}
-```
-
-Build with:
 ```bash
-GOOS=js GOARCH=wasm go build -o example.wasm main.go
+npm install baraqex
 ```
 
-### Server-Side Rendering
+---
 
-#### Page Components
+## 📖 Basic Usage
 
-```javascript
-// pages/index.js
-import { jsx } from 'baraqex';
+### Create a Component
+
+```jsx
+import { jsx, useState } from 'baraqex';
 
-export default function HomePage(props) {
+function Counter() {
+  const [count, setCount] = useState(0);
+  
   return (
-    <html>
-      <head>
-        <title>My App</title>
-      </head>
-      <body>
-        <h1>Welcome to Baraqex!</h1>
-        <p>Server time: {props.api.serverTime}</p>
-      </body>
-    </html>
+    <div>
+      <h1>Count: {count}</h1>
+      <button onClick={() => setCount(count + 1)}>
+        Increment
+      </button>
+    </div>
   );
 }
-
-// Optional: Add metadata
-HomePage.getTitle = (props) => 'Home - My App';
-HomePage.getDescription = (props) => 'Welcome to my application';
 ```
 
-#### API Routes
+### Create an API Route
 
 ```javascript
-// api/users.js
+// api/users.js - automatically becomes /api/users
 export async function get(req, res) {
-  // GET /api/users
-  const users = await getUsersFromDatabase();
-  res.json({ users });
+  const users = await db.query('SELECT * FROM users');
+  res.json(users);
 }
 
 export async function post(req, res) {
-  // POST /api/users
-  const newUser = await createUser(req.body);
-  res.json({ user: newUser });
-}
-
-// api/users/[id].js
-export async function get(req, res) {
-  // GET /api/users/:id
-  const user = await getUserById(req.params.id);
-  res.json({ user });
+  const user = await db.insert('users', req.body);
+  res.status(201).json(user);
 }
 ```
 
-### Database Integration
-
-```javascript
-import { Database } from 'baraqex/server';
-
-// MongoDB
-const db = new Database({
-  type: 'mongodb',
-  url: 'mongodb://localhost:27017/myapp'
-});
-
-await db.connect();
-const collection = db.getMongoDb().collection('users');
+### Use WebAssembly
 
-// MySQL
-const db = new Database({
-  type: 'mysql',
-  url: 'mysql://user:pass@localhost:3306/myapp'
-});
+```jsx
+import { loadGoWasm, callWasmFunction } from 'baraqex';
 
-await db.connect();
-const users = await db.query('SELECT * FROM users WHERE active = ?', [true]);
+// Load your Go WASM module
+await loadGoWasm('/math.wasm');
 
-// PostgreSQL
-const db = new Database({
-  type: 'postgres',
-  url: 'postgresql://user:pass@localhost:5432/myapp'
-});
-
-await db.connect();
-const result = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
+// Call Go functions from JavaScript
+const result = callWasmFunction('fibonacci', 1000000);
+console.log(result); // Computed in milliseconds!
 ```
 
-### Authentication
+### Start a Server
 
 ```javascript
-import { AuthService } from 'baraqex/server';
+import { Server } from 'baraqex/server';
 
-const auth = new AuthService({
-  secret: 'your-secret-key',
-  expiresIn: '24h'
+const server = new Server({
+  port: 3000,
+  apiDir: './api',
+  pagesDir: './pages',
+  db: {
+    type: 'postgres',
+    url: process.env.DATABASE_URL
+  },
+  auth: {
+    secret: process.env.JWT_SECRET
+  }
 });
 
-// In your API routes
-export async function post(req, res) {
-  const { username, password } = req.body;
-  
-  // Validate user
-  const user = await validateUser(username, password);
-  if (!user) {
-    return res.status(401).json({ error: 'Invalid credentials' });
-  }
-  
-  // Generate token
-  const token = auth.generateToken(user);
-  res.json({ token, user });
-}
+await server.start();
+// 🚀 Server running at http://localhost:3000
+```
 
-// Protected route
-export const middleware = [auth.requireAuth()];
+---
 
-export async function get(req, res) {
-  // req.user is available
-  res.json({ user: req.user });
-}
+## 📚 Documentation
+
+### Core Concepts
+
+| Topic | Description |
+|-------|-------------|
+| [Components](docs/components.md) | Creating and composing components |
+| [Hooks](docs/hooks.md) | useState, useEffect, useContext, and more |
+| [Routing](docs/routing.md) | File-based and programmatic routing |
+| [Server](docs/server.md) | Express-based server with middleware |
+| [Database](docs/database.md) | MongoDB, PostgreSQL, MySQL adapters |
+| [Authentication](docs/auth.md) | JWT tokens and password hashing |
+| [WebAssembly](docs/wasm.md) | Go WASM integration guide |
+| [SSR](docs/ssr.md) | Server-side rendering |
+
+### API Reference
+
+```typescript
+// Browser APIs
+import {
+  jsx,
+  Fragment,
+  render,
+  useState,
+  useEffect,
+  useContext,
+  useRef,
+  useMemo,
+  useCallback,
+  loadGoWasm,
+  callWasmFunction,
+  getWasmExports
+} from 'baraqex';
+
+// Server APIs
+import {
+  Server,
+  Database,
+  AuthService,
+  ApiRouter,
+  rateLimit,
+  requestLogger,
+  errorHandler
+} from 'baraqex/server';
 ```
 
-## 🛠️ Development
+---
 
-### Project Structure
+## 🎯 Examples
 
-```
-my-app/
-├── src/
-│   ├── pages/          # SSR pages
-│   │   ├── index.js    # Home page
-│   │   └── about.js    # About page
-│   ├── api/            # API routes
-│   │   ├── users.js    # /api/users
-│   │   └── auth/       # /api/auth/*
-│   └── components/     # Reusable components
-├── public/             # Static files
-│   ├── app.wasm       # WebAssembly modules
-│   └── styles.css     # Stylesheets
-├── wasm/              # Go WASM source
-│   └── main.go        # Go functions
-└── package.json
-```
+### Todo App with WASM
 
-### Build Scripts
+```jsx
+import { jsx, useState, loadGoWasm, callWasmFunction } from 'baraqex';
 
-```json
-{
-  "scripts": {
-    "dev": "baraqex dev",
-    "build": "baraqex build",
-    "start": "baraqex start",
-    "build:wasm": "GOOS=js GOARCH=wasm go build -o public/app.wasm wasm/main.go"
-  }
+function TodoApp() {
+  const [todos, setTodos] = useState([]);
+  const [input, setInput] = useState('');
+
+  const addTodo = () => {
+    // Use WASM for validation/processing
+    const validated = callWasmFunction('validateTodo', input);
+    if (validated) {
+      setTodos([...todos, { id: Date.now(), text: input }]);
+      setInput('');
+    }
+  };
+
+  return (
+    <div className="todo-app">
+      <h1>📝 WASM Todo</h1>
+      <input 
+        value={input} 
+        onChange={(e) => setInput(e.target.value)}
+        placeholder="Add a todo..."
+      />
+      <button onClick={addTodo}>Add</button>
+      <ul>
+        {todos.map(todo => (
+          <li key={todo.id}>{todo.text}</li>
+        ))}
+      </ul>
+    </div>
+  );
 }
 ```
 
-### Development Server
+### Full-Stack API
 
 ```javascript
-import { createDevServer } from 'baraqex/server';
+// server.js
+import { Server } from 'baraqex/server';
 
-const server = createDevServer({
+const server = new Server({
   port: 3000,
-  enableCors: true
+  db: { type: 'mongodb', url: 'mongodb://localhost:27017/myapp' },
+  auth: { secret: 'your-secret-key' }
 });
 
-// Enable SSR with hot reloading
-server.enableSSR({ hydratable: true });
+// Custom middleware
+server.use((req, res, next) => {
+  console.log(`${req.method} ${req.url}`);
+  next();
+});
 
 await server.start();
 ```
 
-## 🔧 Configuration
-
-### Server Configuration
-
 ```javascript
-import { createServer } from 'baraqex/server';
-
-const server = createServer({
-  port: process.env.PORT || 3000,
-  apiDir: './src/api',
-  pagesDir: './src/pages',
-  staticDir: './public',
-  enableCors: true,
-  corsOptions: {
-    origin: ['http://localhost:3000'],
-    credentials: true
-  },
-  db: {
-    type: 'mongodb',
-    url: process.env.DATABASE_URL
-  },
-  auth: {
-    secret: process.env.JWT_SECRET,
-    expiresIn: '7d'
-  }
-});
+// api/posts/[id].js - Dynamic routes
+export async function get(req, res, { db }) {
+  const post = await db.query(`SELECT * FROM posts WHERE id = $1`, [req.params.id]);
+  res.json(post);
+}
 ```
 
-### WASM Configuration
+---
 
-```javascript
-// Browser
-await loadGoWasm('/app.wasm', {
-  debug: process.env.NODE_ENV === 'development',
-  importObject: {
-    // Custom WASM imports
-  },
-  onLoad: (instance) => {
-    console.log('WASM loaded with exports:', instance.exports);
-  }
-});
+## 🏗️ Project Structure
 
-// Server
-await loadGoWasmFromFile('./app.wasm', {
-  debug: true,
-  goWasmPath: './wasm_exec.cjs'
-});
+```
+my-app/
+├── api/                 # API routes (file-based)
+│   ├── users.js        # → /api/users
+│   └── posts/
+│       ├── index.js    # → /api/posts
+│       └── [id].js     # → /api/posts/:id
+├── pages/               # Page components
+│   ├── index.jsx       # → /
+│   └── about.jsx       # → /about
+├── public/              # Static assets
+├── src/
+│   ├── components/     # Reusable components
+│   └── wasm/           # Go WASM source files
+├── package.json
+└── baraqex.config.js   # Optional configuration
 ```
 
-## 📊 Performance
+---
 
-### WebAssembly Benefits
-- **Near-native performance** for compute-intensive tasks
-- **Memory efficiency** with direct memory access
-- **Parallel processing** capabilities
-- **Type safety** with compiled languages
+## ⚡ Performance
 
-### Server Optimizations
-- **Built-in caching** for static assets
-- **Compression** support (gzip, brotli)
-- **HTTP/2** ready
-- **Cluster mode** for production
+Baraqex is designed for speed:
 
-## 🧪 Testing
+| Metric | Value |
+|--------|-------|
+| Bundle Size | 14.2 KB (gzipped) |
+| First Paint | < 50ms |
+| Server Start | < 200ms |
+| WASM Load | < 100ms |
+| Rate Limit Check | < 0.01ms |
 
-### Complete Test Suite
+Run benchmarks yourself:
 
 ```bash
-# Run all tests (builds project first)
-npm test
-
-# Run server function tests only
-npm run test:server
-
-# Run WASM integration tests only
-npm run test:wasm
+npm run benchmark
 ```
 
-### WASM Testing
+---
 
-```javascript
-// test-wasm.js
-import { loadGoWasmFromFile, callWasmFunction } from 'baraqex/server';
+## 🧪 Testing
 
-async function testWasm() {
-  await loadGoWasmFromFile('./example.wasm');
-  
-  // Test functions
-  const greeting = callWasmFunction('goHello', 'Test');
-  console.assert(greeting.includes('Test'), 'Hello function works');
-  
-  const sum = callWasmFunction('goAdd', 5, 3);
-  console.assert(sum === 8, 'Add function works');
-  
-  console.log('All WASM tests passed!');
-}
+```bash
+# Run all tests
+npm test
 
-testWasm();
-```
+# Run with coverage
+npm run test:coverage
 
-### Server Testing
+# Run specific tests
+npm run test:unit
+npm run test:integration
 
-```javascript
-import request from 'supertest';
-import { createServer } from 'baraqex/server';
-
-const server = createServer();
-const app = server.getExpressApp();
-
-describe('API Routes', () => {
-  test('GET /api/users', async () => {
-    const response = await request(app)
-      .get('/api/users')
-      .expect(200);
-    
-    expect(response.body).toHaveProperty('users');
-  });
-});
+# Run benchmarks
+npm run test:benchmarks
 ```
 
-### Test Results
-
-The test suite covers:
-- ✅ **Server Creation** - Basic server setup and configuration
-- ✅ **Database Connections** - MongoDB, MySQL, PostgreSQL adapters
-- ✅ **Authentication** - JWT token generation and validation
-- ✅ **WebAssembly Integration** - Go WASM loading and function calls
-- ✅ **API Routes** - Dynamic route registration and handling
-- ✅ **Server Utilities** - Helper functions and middleware
-- ✅ **Template Generation** - HTML document and error page creation
+---
 
-## 🚀 Deployment
+## 🤝 Contributing
 
-### Production Build
+We love contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ```bash
-# Build WASM modules
-npm run build:wasm
+# Clone the repo
+git clone https://github.com/mohamedx2/baraqex.git
+cd baraqex
 
-# Build application
-npm run build
+# Install dependencies
+npm install
 
-# Start production server
-npm start
-```
-
-### Docker Deployment
-
-```dockerfile
-FROM node:18-alpine
-
-WORKDIR /app
-
-# Install Go for WASM building
-RUN apk add --no-cache go
-
-# Copy package files
-COPY package*.json ./
-RUN npm ci --only=production
-
-# Copy source
-COPY . .
-
-# Build WASM
-RUN npm run build:wasm
+# Run tests
+npm test
 
-# Build app
-RUN npm run build
+# Start development
+npm run dev
+```
 
-EXPOSE 3000
+---
 
-CMD ["npm", "start"]
-```
+## 📦 Templates
 
-### Environment Variables
+Create projects with pre-configured templates:
 
 ```bash
-# Server
-PORT=3000
-NODE_ENV=production
+# Basic app
+npx create-baraqex-app my-app --template basic
 
-# Database
-DATABASE_URL=mongodb://localhost:27017/myapp
+# Full-stack with database
+npx create-baraqex-app my-app --template fullstack
 
-# Authentication
-JWT_SECRET=your-super-secret-key
+# SSR application
+npx create-baraqex-app my-app --template ssr
 
-# WASM
-WASM_DEBUG=false
+# WASM-powered app
+npx create-baraqex-app my-app --template wasm
 ```
 
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing-feature`
-3. Make changes and add tests
-4. Commit: `git commit -m 'Add amazing feature'`
-5. Push: `git push origin feature/amazing-feature`
-6. Submit a Pull Request
-
-## 📄 License
+---
 
-MIT License - see the [LICENSE](LICENSE) file for details.
+## 🗺️ Roadmap
 
-## 🆘 Support
+- [x] Core framework with JSX support
+- [x] WebAssembly integration
+- [x] Server-side rendering
+- [x] Database adapters (MongoDB, PostgreSQL, MySQL)
+- [x] Authentication system
+- [x] CLI with project scaffolding
+- [ ] Edge runtime support
+- [ ] GraphQL integration
+- [ ] React Server Components
+- [ ] Incremental Static Regeneration
+- [ ] Built-in caching layer
 
-- **Documentation**: [www.baraqex.tech](https://www.baraqex.tech)
-- **Website**: [www.baraqex.tech](https://www.baraqex.tech)
-- **Issues**: [GitHub Issues](https://github.com/hamroun/baraqex/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/hamroun/baraqex/discussions)
-- **Discord**: [Join our community](https://discord.gg/baraqex)
+---
 
-## 🎯 Examples
+## 📄 License
 
-Check out the [examples directory](./examples) for complete sample applications:
+MIT © [Mohamed X](https://github.com/mohamedx2)
 
-- **Basic WASM App** - Simple calculator with Go WASM
-- **Full-Stack Todo** - Complete CRUD app with auth
-- **Real-time Chat** - WebSocket integration
-- **E-commerce Site** - Complex SSR application
-- **Data Visualization** - WASM-powered charts
+---
 
-## 🔗 Related Projects
+<div align="center">
 
-- **Go WASM Runtime**: Standard Go WebAssembly support
-- **Express.js**: The underlying server framework
-- **TypeScript**: Type safety and developer experience
-- **Official Website**: [www.baraqex.tech](https://www.baraqex.tech)
+**[⬆ Back to Top](#baraqex)**
 
----
+Made with ❤️ by the Baraqex team
 
-**Made with ❤️ by the Baraqex team**
+**One Culture, One Framework** | **ثقافة واحدة، إطار عمل واحد**
 
-*Build universal, high-performance web applications with the power of WebAssembly and modern JavaScript.*
+[Website](https://www.baraqex.tech) · [Docs](https://www.baraqex.tech/docs) · [GitHub](https://github.com/mohamedx2/baraqex) · [npm](https://www.npmjs.com/package/baraqex) · [Arabic Community](https://www.baraqex.tech/arabic)
 
-**Learn more at [www.baraqex.tech](https://www.baraqex.tech)**
+</div>