baraqex 1.0.76 → 2.0.0

package/README.md

@@ -1,442 +1,395 @@
 <div align="center">
 
-# 🚀 Baraqex
+<img src="https://raw.githubusercontent.com/mohamedx2/baraqex/main/assets/logo.svg" alt="Baraqex Logo" width="180" height="180">
 
-**A powerful, modern JavaScript/TypeScript framework for building universal web applications**
+# Baraqex
 
-[![npm version](https://img.shields.io/npm/v/baraqex.svg)](https://www.npmjs.com/package/baraqex)
-[![Build Status](https://img.shields.io/github/workflow/status/hamroun/baraqex/CI)](https://github.com/hamroun/baraqex/actions)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Discord](https://img.shields.io/discord/123456789?color=7289da&label=Discord&logo=discord)](https://discord.gg/baraqex)
+### ⚡ The Full-Stack Framework with WASM Superpowers
 
-[🎮 Try Interactive Demo](https://demo.baraqex.tech) • [📚 Documentation](https://docs.baraqex.tech) • [💬 Discord](https://discord.gg/baraqex) • [🐛 Report Bug](https://github.com/hamroun/baraqex/issues)
+Build universal web applications with React-like syntax and Go-powered performance.
+
+[![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)
+
+[Get Started](#-quick-start) · [Documentation](https://www.baraqex.tech/docs) · [Examples](#-examples) · [Contributing](#-contributing)
 
 </div>
 
 ---
 
-## 🎯 **What makes Baraqex special?**
+## Why Baraqex?
 
-<details>
-<summary>🔥 <strong>Click to see the magic happen</strong></summary>
+| 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+ |
 
-```javascript
-// Write this once, run everywhere! 🌍
-import { jsx, callWasmFunction } from 'baraqex';
+---
 
-function SuperFastApp() {
-  // This Go function runs at near-native speed! ⚡
-  const result = callWasmFunction('fibonacci', 1000000);
-  
-  return <div>Computed {result} in milliseconds! 🚀</div>;
-}
-```
+## ✨ Features
 
-**Result:** Your heavy computations run 10-100x faster than pure JavaScript! 📈
+- **🔥 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
 
-</details>
+> **Built on [frontend-hamroun](https://www.npmjs.com/package/frontend-hamroun)** - The lightweight React-like core (~8KB gzipped)
 
 ---
 
-## 🎮 **Try It Now - Interactive Playground**
-
-<details>
-<summary>🎪 <strong>Live Code Playground - Click to expand!</strong></summary>
+## 🚀 Quick Start
 
-### 1️⃣ **Quick Start (30 seconds)**
+### Create a New Project
 
 ```bash
-# 🚀 One command to rule them all
-npx create-baraqex-app my-super-app
-cd my-super-app
+npx create-baraqex-app my-app
+cd my-app
 npm run dev
 ```
 
-### 2️⃣ **Add Some WebAssembly Magic**
+### Or Install Manually
 
-```javascript
-// ✨ Your first WASM-powered component
-import { jsx, useState, loadGoWasm, callWasmFunction } from 'baraqex';
+```bash
+npm install baraqex
+```
 
-function Calculator() {
-  const [result, setResult] = useState(0);
-  
-  const handleCalculate = async () => {
-    // 🔥 This runs Go code in the browser!
-    await loadGoWasm('/calculator.wasm');
-    const answer = callWasmFunction('complexMath', 42);
-    setResult(answer);
-  };
+---
+
+## 📖 Basic Usage
+
+### Create a Component
+
+```jsx
+import { jsx, useState } from 'baraqex';
+
+function Counter() {
+  const [count, setCount] = useState(0);
   
   return (
-    <div className="calculator">
-      <h2>🧮 WASM Calculator</h2>
-      <button onClick={handleCalculate}>
-        Calculate π to 1M digits! 🥧
+    <div>
+      <h1>Count: {count}</h1>
+      <button onClick={() => setCount(count + 1)}>
+        Increment
       </button>
-      <div>Result: {result}</div>
     </div>
   );
 }
 ```
 
-### 3️⃣ **See It In Action**
+### Create an API Route
 
-[🎮 **Open Interactive Demo**](https://stackblitz.com/edit/baraqex-playground?file=src%2FApp.jsx) ← **Click here to play!**
+```javascript
+// api/users.js - automatically becomes /api/users
+export async function get(req, res) {
+  const users = await db.query('SELECT * FROM users');
+  res.json(users);
+}
 
-</details>
+export async function post(req, res) {
+  const user = await db.insert('users', req.body);
+  res.status(201).json(user);
+}
+```
 
----
+### Use WebAssembly
 
-## ✨ **Feature Showcase**
+```jsx
+import { loadGoWasm, callWasmFunction } from 'baraqex';
 
-<table>
-<tr>
-<td width="33%">
+// Load your Go WASM module
+await loadGoWasm('/math.wasm');
 
-### 🎭 **Universal JSX**
-```jsx
-// Same code, everywhere!
-<MyComponent server={true} client={true} />
+// Call Go functions from JavaScript
+const result = callWasmFunction('fibonacci', 1000000);
+console.log(result); // Computed in milliseconds!
 ```
-**No React dependency needed!**
 
-</td>
-<td width="33%">
+### Start a Server
 
-### ⚡ **WebAssembly Power**
 ```javascript
-// Go functions in JavaScript!
-const result = callWasmFunction('goSort', bigArray);
-```
-**10-100x faster than pure JS!**
+import { Server } from 'baraqex/server';
 
-</td>
-<td width="33%">
+const server = new Server({
+  port: 3000,
+  apiDir: './api',
+  pagesDir: './pages',
+  db: {
+    type: 'postgres',
+    url: process.env.DATABASE_URL
+  },
+  auth: {
+    secret: process.env.JWT_SECRET
+  }
+});
 
-### 🏗️ **Full-Stack Ready**
-```javascript
-// API routes made simple
-export async function get(req, res) {
-  res.json({ hello: 'world' });
-}
+await server.start();
+// 🚀 Server running at http://localhost:3000
 ```
-**Zero configuration needed!**
 
-</td>
-</tr>
-</table>
+---
+
+## 📚 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';
+```
 
 ---
 
-## 🎯 **Choose Your Adventure**
+## 🎯 Examples
 
-<details>
-<summary>🎨 <strong>Frontend Developer</strong> - Build amazing UIs</summary>
+### Todo App with WASM
 
-### **Quick Setup**
-```bash
-npm install baraqex
-```
+```jsx
+import { jsx, useState, loadGoWasm, callWasmFunction } from 'baraqex';
 
-### **Your First Component**
-```javascript
-import { jsx, useState, useEffect } from 'baraqex';
+function TodoApp() {
+  const [todos, setTodos] = useState([]);
+  const [input, setInput] = useState('');
 
-function CoolCounter() {
-  const [count, setCount] = useState(0);
-  const [wasmPowered, setWasmPowered] = useState(false);
-  
-  useEffect(() => {
-    // Load your Go WASM module
-    loadGoWasm('/math.wasm').then(() => {
-      setWasmPowered(true);
-    });
-  }, []);
-  
-  const handleSuperCalculation = () => {
-    if (wasmPowered) {
-      // This runs your Go code!
-      const result = callWasmFunction('fibonacci', count);
-      console.log(`Fibonacci(${count}) = ${result}`);
+  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="counter">
-      <h1>🚀 Super Counter</h1>
-      <p>Count: {count}</p>
-      <button onClick={() => setCount(count + 1)}>
-        ➕ Increment
-      </button>
-      <button 
-        onClick={handleSuperCalculation}
-        disabled={!wasmPowered}
-        className={wasmPowered ? 'ready' : 'loading'}
-      >
-        {wasmPowered ? '⚡ Calculate with WASM' : '⏳ Loading WASM...'}
-      </button>
+    <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>
   );
 }
 ```
 
-**[📺 Watch Video Tutorial](https://youtube.com/watch?v=baraqex-frontend)** | **[🎮 Try Live Demo](https://demo.baraqex.tech/frontend)**
+### Full-Stack API
 
-</details>
-
-<details>
-<summary>🔧 <strong>Backend Developer</strong> - Build robust APIs</summary>
-
-### **Server Setup**
 ```javascript
-import { createServer, Database, AuthService } from 'baraqex/server';
+// server.js
+import { Server } from 'baraqex/server';
 
-// 🚀 Everything configured for you!
-const server = createServer({
+const server = new Server({
   port: 3000,
-  apiDir: './api',        // File-based routing
-  staticDir: './public',  // Static file serving
-  database: {
-    type: 'mongodb',
-    url: process.env.DATABASE_URL
-  }
+  db: { type: 'mongodb', url: 'mongodb://localhost:27017/myapp' },
+  auth: { secret: 'your-secret-key' }
 });
 
-// 🔐 Built-in auth
-const auth = new AuthService({
-  secret: process.env.JWT_SECRET
+// Custom middleware
+server.use((req, res, next) => {
+  console.log(`${req.method} ${req.url}`);
+  next();
 });
 
-server.start().then(() => {
-  console.log('🎉 Server running on http://localhost:3000');
-});
+await server.start();
 ```
 
-### **API Routes (File-based)**
 ```javascript
-// api/users.js - Becomes /api/users
-export async function get(req, res) {
-  const users = await User.find({});
-  res.json({ users });
-}
-
-export async function post(req, res) {
-  const user = await User.create(req.body);
-  res.json({ user });
-}
-
-// api/users/[id].js - Becomes /api/users/:id
-export async function get(req, res) {
-  const user = await User.findById(req.params.id);
-  res.json({ user });
+// 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);
 }
 ```
 
-**[📺 Watch Video Tutorial](https://youtube.com/watch?v=baraqex-backend)** | **[🎮 Try Live Demo](https://demo.baraqex.tech/backend)**
-
-</details>
-
-<details>
-<summary>⚡ <strong>Performance Engineer</strong> - Supercharge with WebAssembly</summary>
-
-### **Go WASM Module**
-```go
-// wasm/math.go
-package main
-
-import (
-    "fmt"
-    "syscall/js"
-)
-
-func fibonacci(this js.Value, args []js.Value) interface{} {
-    n := args[0].Int()
-    
-    if n <= 1 {
-        return n
-    }
-    
-    a, b := 0, 1
-    for i := 2; i <= n; i++ {
-        a, b = b, a+b
-    }
-    
-    return b
-}
+---
 
-func isPrime(this js.Value, args []js.Value) interface{} {
-    n := args[0].Int()
-    
-    if n < 2 {
-        return false
-    }
-    
-    for i := 2; i*i <= n; i++ {
-        if n%i == 0 {
-            return false
-        }
-    }
-    
-    return true
-}
+## 🏗️ Project Structure
 
-func main() {
-    // Register functions for JavaScript
-    js.Global().Set("fibonacci", js.FuncOf(fibonacci))
-    js.Global().Set("isPrime", js.FuncOf(isPrime))
-    
-    fmt.Println("🔥 Go WASM module loaded!")
-    
-    // Keep the program running
-    select {}
-}
 ```
-
-### **Build & Use**
-```bash
-# Build WASM module
-GOOS=js GOARCH=wasm go build -o public/math.wasm wasm/math.go
-
-# Use in your app
-npm run dev
+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 Comparison**
-| Operation | JavaScript | Baraqex + WASM | Speedup |
-|-----------|------------|----------------|---------|
-| Fibonacci(40) | 1.2s | 0.08s | **15x faster** |
-| Prime check(1M) | 450ms | 45ms | **10x faster** |
-| Image processing | 2.1s | 0.3s | **7x faster** |
-
-**[📺 Watch Performance Demo](https://youtube.com/watch?v=baraqex-performance)** | **[🎮 Try Benchmark](https://demo.baraqex.tech/benchmark)**
-
-</details>
-
 ---
 
-## 🏆 **Success Stories**
-
-<details>
-<summary>📈 <strong>Real Companies Using Baraqex</strong></summary>
+## ⚡ Performance
 
-### 🚀 **TechCorp Inc.**
-> *"Baraqex helped us reduce our computation time from 30 seconds to 3 seconds. Our users love the speed!"*
-> 
-> **— Sarah Johnson, CTO**
+Baraqex is designed for speed:
 
-### 💰 **FinanceApp Ltd.**
-> *"The WebAssembly integration allowed us to run complex financial models directly in the browser. Game changer!"*
-> 
-> **— Mike Chen, Lead Developer**
+| Metric | Value |
+|--------|-------|
+| Bundle Size | 14.2 KB (gzipped) |
+| First Paint | < 50ms |
+| Server Start | < 200ms |
+| WASM Load | < 100ms |
+| Rate Limit Check | < 0.01ms |
 
-### 🎮 **GameStudio XYZ**
-> *"Our browser-based game now runs at 60fps thanks to Baraqex's WASM support."*
-> 
-> **— Alex Rodriguez, Technical Director**
+Run benchmarks yourself:
 
-**[📖 Read More Success Stories](https://baraqex.tech/success-stories)**
-
-</details>
+```bash
+npm run benchmark
+```
 
 ---
 
-## 🎓 **Learning Path**
-
-### 🥇 **Beginner Track** (30 minutes)
-1. [🎮 **Interactive Tutorial**](https://learn.baraqex.tech/beginner) - Learn by building
-2. [📺 **Video Series**](https://youtube.com/playlist?list=baraqex-basics) - Step-by-step guides
-3. [💬 **Ask Questions**](https://discord.gg/baraqex) - Get help from the community
+## 🧪 Testing
 
-### 🥈 **Intermediate Track** (2 hours)
-1. [🔧 **Full-Stack Workshop**](https://learn.baraqex.tech/fullstack) - Build a complete app
-2. [⚡ **WASM Deep Dive**](https://learn.baraqex.tech/wasm) - Master WebAssembly
-3. [🚀 **Deployment Guide**](https://learn.baraqex.tech/deploy) - Go live!
+```bash
+# Run all tests
+npm test
 
-### 🥉 **Advanced Track** (1 day)
-1. [🏗️ **Architecture Patterns**](https://learn.baraqex.tech/patterns) - Best practices
-2. [📊 **Performance Optimization**](https://learn.baraqex.tech/performance) - Make it fast
-3. [🔬 **Contributing Guide**](https://learn.baraqex.tech/contributing) - Join the team
+# Run with coverage
+npm run test:coverage
 
----
+# Run specific tests
+npm run test:unit
+npm run test:integration
 
-## 🎪 **Community Challenges**
+# Run benchmarks
+npm run test:benchmarks
+```
 
-<details>
-<summary>🏆 <strong>Monthly Coding Challenges</strong> - Win prizes!</summary>
+---
 
-### 🎯 **December 2024: Speed Challenge**
-Build the fastest image processing app using Baraqex + WASM!
+## 🤝 Contributing
 
-**Prizes:**
-- 🥇 **1st Place:** $500 + Baraqex Pro License
-- 🥈 **2nd Place:** $300 + Swag Pack
-- 🥉 **3rd Place:** $100 + Stickers
+We love contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
-**[🎮 Join Challenge](https://challenges.baraqex.tech/speed-2024)**
+```bash
+# Clone the repo
+git clone https://github.com/mohamedx2/baraqex.git
+cd baraqex
 
-### 📅 **Upcoming Challenges**
-- **January 2025:** Best UI/UX Design
-- **February 2025:** Most Creative Use Case
-- **March 2025:** Best Tutorial Creation
+# Install dependencies
+npm install
 
-**[📧 Get Notified](https://baraqex.tech/challenges/subscribe)**
+# Run tests
+npm test
 
-</details>
+# Start development
+npm run dev
+```
 
 ---
 
-## 🚀 **Get Started Now!**
+## 📦 Templates
 
-<div align="center">
-
-### Choose your starting point:
-
-**[🎮 Interactive Tutorial](https://learn.baraqex.tech)** | **[📺 Video Course](https://youtube.com/baraqex)** | **[💬 Join Discord](https://discord.gg/baraqex)**
-
-### Quick Commands:
+Create projects with pre-configured templates:
 
 ```bash
-# 🚀 Create new project
-npx create-baraqex-app my-app
+# Basic app
+npx create-baraqex-app my-app --template basic
 
-# 📦 Add to existing project  
-npm install baraqex
+# Full-stack with database
+npx create-baraqex-app my-app --template fullstack
+
+# SSR application
+npx create-baraqex-app my-app --template ssr
 
-# 🎮 Try online playground
-open https://stackblitz.com/edit/baraqex-playground
+# WASM-powered app
+npx create-baraqex-app my-app --template wasm
 ```
 
-### 🌟 **Star us on GitHub if you like what you see!**
+---
 
-[![GitHub stars](https://img.shields.io/github/stars/hamroun/baraqex.svg?style=social&label=Star)](https://github.com/hamroun/baraqex)
+## 🗺️ Roadmap
 
-</div>
+- [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
 
 ---
 
-## 📱 **Stay Connected**
-
-<div align="center">
+## 📄 License
 
-| Platform | Link | Purpose |
-|----------|------|---------|
-| 🌐 **Website** | [baraqex.tech](https://baraqex.tech) | Official docs & news |
-| 💬 **Discord** | [Join Chat](https://discord.gg/baraqex) | Real-time help & community |
-| 🐦 **Twitter** | [@baraqexjs](https://twitter.com/baraqexjs) | Updates & tips |
-| 📺 **YouTube** | [Baraqex Channel](https://youtube.com/baraqex) | Tutorials & demos |
-| 📧 **Newsletter** | [Subscribe](https://baraqex.tech/newsletter) | Monthly updates |
-
-</div>
+MIT © [Mohamed X](https://github.com/mohamedx2)
 
 ---
 
 <div align="center">
 
-**Made with ❤️ by the Baraqex community**
+**[⬆ Back to Top](#baraqex)**
+
+Made with ❤️ by the Baraqex team
 
-*Build the future of web applications with WebAssembly and modern JavaScript.*
+**One Culture, One Framework** | **ثقافة واحدة، إطار عمل واحد**
 
-**[🚀 Start Building Now](https://learn.baraqex.tech)** • **[💖 Sponsor Project](https://github.com/sponsors/hamroun)**
+[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)
 
 </div>