odac 0.9.0 → 1.0.0

package/docs/frontend/04-api-requests/01-get-post.md

@@ -1,13 +1,13 @@
-# API Requests with candy.js
+# API Requests with odac.js
 
-Learn how to make GET and POST requests to your API endpoints using candy.js.
+Learn how to make GET and POST requests to your API endpoints using odac.js.
 
 ## GET Requests
 
 ### Basic GET Request
 
 ```javascript
-Candy.get('/api/data', function(response) {
+odac.get('/api/data', function(response) {
   console.log('Data:', response)
 })
 ```
@@ -16,7 +16,7 @@ Candy.get('/api/data', function(response) {
 
 ```javascript
 const userId = 123
-Candy.get(`/api/users/${userId}`, function(user) {
+odac.get(`/api/users/${userId}`, function(user) {
   console.log('User:', user.name)
   console.log('Email:', user.email)
 })
@@ -25,7 +25,7 @@ Candy.get(`/api/users/${userId}`, function(user) {
 ### Error Handling
 
 ```javascript
-Candy.get('/api/data', function(response) {
+odac.get('/api/data', function(response) {
   if (response.error) {
     console.error('Error:', response.error)
     return
@@ -40,10 +40,10 @@ Candy.get('/api/data', function(response) {
 
 ### Using Forms
 
-The recommended way to make POST requests is using `Candy.form()`:
+The recommended way to make POST requests is using `Odac.form()`:
 
 ```javascript
-Candy.form('#my-form', function(data) {
+odac.form('#my-form', function(data) {
   if (data.result.success) {
     console.log('Success!')
   }
@@ -58,12 +58,12 @@ For custom POST requests without forms, use the internal AJAX method:
 
 ```javascript
 // Note: This is an advanced pattern
-// For most cases, use Candy.form() instead
+// For most cases, use odac.form() instead
 
 const formData = new FormData()
 formData.append('name', 'John')
 formData.append('email', 'john@example.com')
-formData.append('_token', Candy.token())
+formData.append('_token', odac.token())
 
 fetch('/api/submit', {
   method: 'POST',
@@ -79,16 +79,16 @@ fetch('/api/submit', {
 
 ### Automatic Token Management
 
-candy.js automatically handles CSRF tokens:
+odac.js automatically handles CSRF tokens:
 
 ```javascript
 // Token is automatically included
-Candy.get('/api/data', function(response) {
+odac.get('/api/data', function(response) {
   // ...
 })
 
 // Token is automatically included in forms
-Candy.form('#my-form', function(data) {
+odac.form('#my-form', function(data) {
   // ...
 })
 ```
@@ -98,7 +98,7 @@ Candy.form('#my-form', function(data) {
 If you need the token manually:
 
 ```javascript
-const token = Candy.token()
+const token = odac.token()
 console.log('Current token:', token)
 ```
 
@@ -108,7 +108,7 @@ console.log('Current token:', token)
 
 ```javascript
 // Get user profile
-Candy.get('/api/profile', function(profile) {
+odac.get('/api/profile', function(profile) {
   document.querySelector('#username').textContent = profile.name
   document.querySelector('#email').textContent = profile.email
 })
@@ -118,7 +118,7 @@ Candy.get('/api/profile', function(profile) {
 
 ```javascript
 // Get products
-Candy.get('/api/products', function(products) {
+odac.get('/api/products', function(products) {
   const container = document.querySelector('#products')
   
   products.forEach(product => {
@@ -143,7 +143,7 @@ searchInput.addEventListener('input', function() {
   
   if (query.length < 3) return
   
-  Candy.get(`/api/search?q=${encodeURIComponent(query)}`, function(results) {
+  odac.get(`/api/search?q=${encodeURIComponent(query)}`, function(results) {
     displayResults(results)
   })
 })
@@ -172,7 +172,7 @@ document.querySelector('#autocomplete').addEventListener('input', function() {
   debounceTimer = setTimeout(() => {
     if (value.length < 2) return
     
-    Candy.get(`/api/autocomplete?q=${value}`, function(suggestions) {
+    odac.get(`/api/autocomplete?q=${value}`, function(suggestions) {
       showSuggestions(suggestions)
     })
   }, 300)
@@ -200,7 +200,7 @@ function loadMore() {
   loading = true
   page++
   
-  Candy.get(`/api/posts?page=${page}`, function(posts) {
+  odac.get(`/api/posts?page=${page}`, function(posts) {
     posts.forEach(post => {
       appendPost(post)
     })
@@ -214,7 +214,7 @@ function loadMore() {
 ```javascript
 // Poll for updates every 30 seconds
 setInterval(function() {
-  Candy.get('/api/notifications', function(notifications) {
+  odac.get('/api/notifications', function(notifications) {
     updateNotificationBadge(notifications.count)
   })
 }, 30000)
@@ -226,7 +226,7 @@ setInterval(function() {
 
 ```javascript
 // controller/get/users.js
-module.exports = function(Candy) {
+module.exports = function(Odac) {
   // Get all users
   const users = [
     {id: 1, name: 'John', email: 'john@example.com'},
@@ -239,21 +239,21 @@ module.exports = function(Candy) {
 
 ```javascript
 // route/www.js
-Candy.Route.get('/api/users', 'users')
+odac.Route.get('/api/users', 'users')
 ```
 
 ### GET with Parameters
 
 ```javascript
 // controller/get/user.js
-module.exports = async function(Candy) {
-  const userId = Candy.Request.data.url.id
+module.exports = async function(Odac) {
+  const userId = odac.Request.data.url.id
   
   // Fetch user from database
   const user = await getUserById(userId)
   
   if (!user) {
-    Candy.Request.status(404)
+    odac.Request.status(404)
     return {error: 'User not found'}
   }
   
@@ -263,16 +263,16 @@ module.exports = async function(Candy) {
 
 ```javascript
 // route/www.js
-Candy.Route.get('/api/users/{id}', 'user')
+odac.Route.get('/api/users/{id}', 'user')
 ```
 
 ### POST Endpoint
 
 ```javascript
 // controller/post/create.js
-module.exports = async function(Candy) {
-  const name = await Candy.Request.request('name')
-  const email = await Candy.Request.request('email')
+module.exports = async function(Odac) {
+  const name = await odac.Request.request('name')
+  const email = await odac.Request.request('email')
   
   // Validation
   if (!name || !email) {
@@ -300,7 +300,7 @@ module.exports = async function(Candy) {
 
 ```javascript
 // route/www.js
-Candy.Route.post('/api/users/create', 'create')
+odac.Route.post('/api/users/create', 'create')
 ```
 
 ## Response Format
@@ -357,7 +357,7 @@ function getCached(url, callback) {
     return
   }
   
-  Candy.get(url, function(data) {
+  odac.get(url, function(data) {
     cache[url] = data
     callback(data)
   })
@@ -386,7 +386,7 @@ function processQueue() {
   processing = true
   const {url, callback} = requestQueue.shift()
   
-  Candy.get(url, function(data) {
+  odac.get(url, function(data) {
     callback(data)
     processing = false
     processQueue()
@@ -403,7 +403,7 @@ function getWithRetry(url, callback, maxRetries = 3) {
   function attempt() {
     attempts++
     
-    Candy.get(url, function(data) {
+    odac.get(url, function(data) {
       if (data.error && attempts < maxRetries) {
         setTimeout(attempt, 1000 * attempts)
       } else {
@@ -440,4 +440,4 @@ function getWithRetry(url, callback, maxRetries = 3) {
 
 - Learn about [Form Handling](../03-forms/01-form-handling.md)
 - Explore [AJAX Navigation](../02-ajax-navigation/01-quick-start.md)
-- Check [candy.js Overview](../01-overview/01-introduction.md)
+- Check [odac.js Overview](../01-overview/01-introduction.md)

package/docs/frontend/05-streaming/01-client-streaming.md

@@ -1,12 +1,12 @@
 # Client-Side Streaming
 
-CandyPack provides a simple client-side API for consuming Server-Sent Events (SSE) streams.
+Odac provides a simple client-side API for consuming Server-Sent Events (SSE) streams.
 
 ### Basic Usage
 
 ```javascript
 // Simple callback
-Candy.listen('/events', (data) => {
+odac.listen('/events', (data) => {
   console.log('Received:', data)
 })
 ```
@@ -14,7 +14,7 @@ Candy.listen('/events', (data) => {
 ### With Options
 
 ```javascript
-const stream = Candy.listen('/events', 
+const stream = odac.listen('/events', 
   (data) => {
     console.log('Message:', data)
   },
@@ -34,7 +34,7 @@ stream.close()
 
 ```javascript
 // Server sends: data: {"message": "Hello"}\n\n
-Candy.listen('/events', (data) => {
+odac.listen('/events', (data) => {
   console.log(data.message) // "Hello"
 })
 ```
@@ -47,8 +47,8 @@ Candy.listen('/events', (data) => {
 
 ```javascript
 // Server
-Candy.Route.get('/dashboard/stats', async (Candy) => {
-  Candy.stream((send) => {
+odac.Route.get('/dashboard/stats', async (Odac) => {
+  odac.stream((send) => {
     const interval = setInterval(async () => {
       const stats = await getServerStats()
       send(stats)
@@ -62,7 +62,7 @@ Candy.Route.get('/dashboard/stats', async (Candy) => {
 })
 
 // Client
-Candy.listen('/dashboard/stats', (stats) => {
+odac.listen('/dashboard/stats', (stats) => {
   document.getElementById('cpu').textContent = stats.cpu + '%'
   document.getElementById('memory').textContent = stats.memory + 'MB'
 })
@@ -72,16 +72,16 @@ Candy.listen('/dashboard/stats', (stats) => {
 
 ```javascript
 // Server
-Candy.Route.get('/notifications', async (Candy) => {
-  const userId = await Candy.request('userId')
+odac.Route.get('/notifications', async (Odac) => {
+  const userId = await odac.request('userId')
   
-  Candy.stream((send) => {
+  odac.stream((send) => {
     global.notificationStreams[userId] = { send }
   })
 })
 
 // Client
-Candy.listen('/notifications', (notification) => {
+odac.listen('/notifications', (notification) => {
   showToast(notification.message)
 })
 ```
@@ -90,8 +90,8 @@ Candy.listen('/notifications', (notification) => {
 
 ```javascript
 // Server
-Candy.Route.get('/build/logs', async (Candy) => {
-  Candy.stream(async function* () {
+odac.Route.get('/build/logs', async (Odac) => {
+  odac.stream(async function* () {
     for await (const log of getBuildLogs()) {
       yield { timestamp: Date.now(), message: log }
     }
@@ -100,7 +100,7 @@ Candy.Route.get('/build/logs', async (Candy) => {
 
 // Client
 const logs = []
-Candy.listen('/build/logs', (log) => {
+odac.listen('/build/logs', (log) => {
   logs.push(log)
   updateLogsUI(logs)
 })
@@ -108,7 +108,7 @@ Candy.listen('/build/logs', (log) => {
 
 ## API Reference
 
-### Candy.listen(url, onMessage, options)
+### odac.listen(url, onMessage, options)
 
 **Parameters:**
 - `url` (string): Stream endpoint URL

package/docs/frontend/06-websocket/00-overview.md

@@ -0,0 +1,76 @@
+# WebSocket Overview
+
+Odac provides built-in WebSocket support with automatic reconnection and cross-tab sharing capabilities.
+
+## Quick Start
+
+**Backend (route/main.js):**
+```javascript
+odac.Route.ws('/chat', (ws, Odac) => {
+  ws.on('message', data => {
+    ws.broadcast(data)
+  })
+})
+```
+
+**Frontend:**
+```javascript
+const ws = Odac.ws('/chat')
+ws.on('message', data => console.log(data))
+ws.send({message: 'Hello!'})
+```
+
+## Key Features
+
+### 🔄 Automatic Reconnection
+Automatically reconnects on connection loss with configurable retry logic.
+
+### 🔗 Cross-Tab Sharing
+Share a single WebSocket connection across multiple browser tabs using SharedWorker.
+
+### 🏠 Room Support
+Group clients into rooms for targeted broadcasting.
+
+### 🔐 Authentication
+Full access to Odac context for authentication and authorization.
+
+### 📦 JSON Auto-Parsing
+Automatically parses JSON messages on both client and server.
+
+### 🎯 URL Parameters
+Support for dynamic route parameters like `/room/{id}`.
+
+## Architecture
+
+```
+Browser Tab 1 ─┐
+Browser Tab 2 ─┼─> SharedWorker ─> WebSocket ─> Odac Server ─> Your Handler
+Browser Tab 3 ─┘
+```
+
+With `shared: true`, all tabs share one connection through a SharedWorker.
+
+## Use Cases
+
+- **Real-time chat applications**
+- **Live notifications**
+- **Collaborative editing**
+- **Live dashboards**
+- **Multiplayer games**
+- **Stock/crypto price updates**
+- **IoT device monitoring**
+
+## Browser Support
+
+| Feature | Chrome | Firefox | Safari | Edge |
+|---------|--------|---------|--------|------|
+| WebSocket | ✅ | ✅ | ✅ | ✅ |
+| Shared WebSocket | ✅ | ✅ | ❌ | ✅ |
+
+*Shared WebSocket automatically falls back to regular WebSocket in unsupported browsers.*
+
+## Next Steps
+
+- [WebSocket Client](01-websocket-client.md) - Basic client usage
+- [Shared WebSocket](02-shared-websocket.md) - Cross-tab communication
+- [Backend WebSocket](../../backend/04-routing/09-websocket.md) - Server-side implementation

package/docs/frontend/06-websocket/01-websocket-client.md

@@ -0,0 +1,139 @@
+# WebSocket Client
+
+odac.js provides a simple WebSocket client with automatic reconnection and cross-tab sharing support.
+
+## Basic Usage
+
+```javascript
+const ws = Odac.ws('/chat')
+
+ws.on('open', () => {
+  console.log('Connected!')
+})
+
+ws.on('message', data => {
+  console.log('Received:', data)
+})
+
+ws.send({type: 'hello', message: 'Hi there!'})
+```
+
+## Configuration Options
+
+```javascript
+const ws = Odac.ws('/chat', {
+  autoReconnect: true,        // Auto-reconnect on disconnect (default: true)
+  reconnectDelay: 3000,       // Delay between reconnect attempts (default: 3000ms)
+  maxReconnectAttempts: 10,   // Max reconnect attempts (default: 10)
+  shared: false,              // Share connection across browser tabs (default: false)
+  token: true                 // Send CSRF token (default: true)
+})
+```
+
+## CSRF Token Protection
+
+By default, odac.js automatically sends a CSRF token during the WebSocket handshake (similar to AJAX requests). The token is sent via the `Sec-WebSocket-Protocol` header.
+
+**Disable token (for public WebSockets):**
+```javascript
+const ws = Odac.ws('/public', {token: false})
+```
+
+**How it works:**
+1. Client calls `Odac.token()` to get current CSRF token
+2. Token is sent as `odac-token-{token}` in WebSocket protocol header
+3. Server validates token before accepting connection
+4. If invalid, connection closes with code `4002`
+
+## Shared WebSocket (Cross-Tab)
+
+Enable `shared: true` to share a single WebSocket connection across all browser tabs:
+
+```javascript
+const ws = Odac.ws('/chat', {shared: true})
+```
+
+**Benefits:**
+- Single connection shared across all tabs
+- Reduced server load
+- Synchronized state across tabs
+- Automatic cleanup when all tabs close
+
+**Browser Support:**
+- Uses SharedWorker API (supported in Chrome, Edge, Firefox)
+- Falls back to regular WebSocket if SharedWorker is unavailable
+
+**Example:**
+```javascript
+// Tab 1
+const ws = Odac.ws('/notifications', {shared: true})
+ws.on('message', data => {
+  console.log('Notification:', data)
+})
+
+// Tab 2 (same connection)
+const ws2 = Odac.ws('/notifications', {shared: true})
+ws2.on('message', data => {
+  console.log('Same notification:', data)
+})
+```
+
+## Event Handlers
+
+```javascript
+ws.on('open', () => {})       // Connection established
+ws.on('message', data => {})  // Message received (auto-parsed JSON)
+ws.on('close', event => {})   // Connection closed
+ws.on('error', event => {})   // Error occurred
+```
+
+## Sending Messages
+
+```javascript
+// Objects are automatically JSON-stringified
+ws.send({type: 'chat', message: 'Hello!'})
+
+// Strings sent as-is
+ws.send('Plain text')
+```
+
+## Connection State
+
+```javascript
+ws.connected  // true if connected
+ws.state      // WebSocket.OPEN, CLOSED, etc.
+```
+
+## Closing Connection
+
+```javascript
+ws.close()
+```
+
+## Removing Event Handlers
+
+```javascript
+const handler = data => console.log(data)
+ws.on('message', handler)
+ws.off('message', handler)  // Remove specific handler
+ws.off('message')           // Remove all message handlers
+```
+
+## Example: Chat Application
+
+```javascript
+const ws = Odac.ws('/chat')
+const messages = document.getElementById('messages')
+const input = document.getElementById('input')
+
+ws.on('message', data => {
+  if (data.type === 'chat') {
+    messages.innerHTML += `<p>${data.user}: ${data.text}</p>`
+  }
+})
+
+document.getElementById('send').onclick = () => {
+  ws.send({type: 'chat', text: input.value})
+  input.value = ''
+}
+```

package/docs/frontend/06-websocket/02-shared-websocket.md

@@ -0,0 +1,149 @@
+# Shared WebSocket (Cross-Tab Communication)
+
+Shared WebSocket allows multiple browser tabs to share a single WebSocket connection using the SharedWorker API.
+
+## Why Use Shared WebSocket?
+
+**Without Shared WebSocket:**
+- Each tab creates its own connection
+- 5 tabs = 5 WebSocket connections
+- Higher server load
+- Inconsistent state across tabs
+
+**With Shared WebSocket:**
+- All tabs share one connection
+- 5 tabs = 1 WebSocket connection
+- Lower server load
+- Synchronized state across tabs
+
+## Basic Usage
+
+```javascript
+const ws = Odac.ws('/chat', {shared: true})
+
+ws.on('message', data => {
+  console.log('Message received in this tab:', data)
+})
+
+ws.send({message: 'Hello from this tab'})
+```
+
+## Real-World Example: Notification System
+
+```javascript
+// All tabs share the same notification connection
+const notifications = Odac.ws('/notifications', {
+  shared: true,
+  autoReconnect: true
+})
+
+notifications.on('open', () => {
+  console.log('Notification system connected')
+})
+
+notifications.on('message', data => {
+  if (data.type === 'notification') {
+    showNotification(data.title, data.message)
+  }
+})
+
+function showNotification(title, message) {
+  if (Notification.permission === 'granted') {
+    new Notification(title, {body: message})
+  }
+}
+```
+
+## Chat Application Example
+
+```javascript
+// Shared chat connection across all tabs
+const chat = Odac.ws('/chat/room/general', {shared: true})
+
+chat.on('message', data => {
+  if (data.type === 'message') {
+    addMessageToUI(data.user, data.text)
+  }
+})
+
+document.getElementById('send').onclick = () => {
+  const text = document.getElementById('input').value
+  chat.send({type: 'message', text})
+}
+
+// All tabs will receive the same messages
+// Only one connection to the server
+```
+
+## Browser Compatibility
+
+Shared WebSocket uses the SharedWorker API:
+
+- ✅ Chrome/Edge: Full support
+- ✅ Firefox: Full support
+- ❌ Safari: Not supported (falls back to regular WebSocket)
+
+**Automatic Fallback:**
+```javascript
+// If SharedWorker is not available, automatically falls back to regular WebSocket
+const ws = Odac.ws('/chat', {shared: true})
+// Works in all browsers, shared only where supported
+```
+
+## Lifecycle Management
+
+The shared connection automatically manages its lifecycle:
+
+```javascript
+// Tab 1 opens
+const ws1 = Odac.ws('/chat', {shared: true})
+// Connection established
+
+// Tab 2 opens
+const ws2 = Odac.ws('/chat', {shared: true})
+// Reuses existing connection
+
+// Tab 1 closes
+// Connection stays alive (Tab 2 still using it)
+
+// Tab 2 closes
+// Connection automatically closes (no tabs using it)
+```
+
+## When to Use Shared WebSocket
+
+**Good Use Cases:**
+- Notification systems
+- Real-time updates (stock prices, sports scores)
+- Chat applications
+- Collaborative editing
+- Live dashboards
+
+**Not Recommended For:**
+- User-specific authenticated connections
+- File uploads/downloads
+- Connections requiring per-tab state
+
+## Performance Comparison
+
+**Regular WebSocket (5 tabs):**
+- Server connections: 5
+- Memory usage: ~5MB
+- Network overhead: 5x
+
+**Shared WebSocket (5 tabs):**
+- Server connections: 1
+- Memory usage: ~1MB
+- Network overhead: 1x
+
+## Debugging
+
+Check if SharedWorker is being used:
+
+```javascript
+const ws = Odac.ws('/chat', {shared: true})
+
+// In Chrome DevTools:
+// chrome://inspect/#workers
+// You'll see "odac-ws-/chat" if shared
+```