odac 1.4.14 → 1.4.16

package/docs/frontend/02-ajax-navigation/03-advanced-usage.md

@@ -6,31 +6,31 @@ Advanced techniques and patterns for AJAX navigation in Odac.
 
 ## Programmatic Navigation
 
-### Using odac.load()
+### Using Odac.load()
 
 Navigate programmatically from your code:
 
 ```javascript
 // Basic usage
-odac.load('/about')
+Odac.load('/about')
 
 // With callback
-odac.load('/about', function(page, variables) {
+Odac.load('/about', function(page, variables) {
   console.log('Loaded:', page)
   console.log('Data:', variables)
 })
 
 // Without updating history
-odac.load('/about', callback, false)
+Odac.load('/about', callback, false)
 ```
 
 ### Use Cases
 
 **Redirect after form submission:**
 ```javascript
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   if (data.result.success) {
-    odac.load('/success')
+    Odac.load('/success')
   }
 })
 ```
@@ -38,16 +38,16 @@ odac.form('#my-form', function(data) {
 **Conditional navigation:**
 ```javascript
 if (user.isLoggedIn) {
-  odac.load('/dashboard')
+  Odac.load('/dashboard')
 } else {
-  odac.load('/login')
+  Odac.load('/login')
 }
 ```
 
 **Timed navigation:**
 ```javascript
 setTimeout(() => {
-  odac.load('/next-page')
+  Odac.load('/next-page')
 }, 3000)
 ```
 
@@ -76,8 +76,8 @@ Define all parts in your controller:
 
 ```javascript
 module.exports = function(Odac) {
-  odac.View.skeleton('main')
-  odac.View.set({
+  Odac.View.skeleton('main')
+  Odac.View.set({
     header: 'main',
     content: 'dashboard',
     sidebar: 'dashboard',
@@ -333,10 +333,10 @@ Odac.action({
 Gracefully handle navigation errors:
 
 ```javascript
-// Override odac.load to add error handling
-const originalLoad = odac.load.bind(Odac)
+// Override Odac.load to add error handling
+const originalLoad = Odac.load.bind(Odac)
 
-odac.load = function(url, callback, push) {
+Odac.load = function(url, callback, push) {
   try {
     originalLoad(url, function(page, variables) {
       if (callback) callback(page, variables)
@@ -359,7 +359,7 @@ function loadWithRetry(url, maxRetries = 3) {
   
   function attempt() {
     attempts++
-    odac.load(url, 
+    Odac.load(url, 
       (page, vars) => {
         console.log('Success after', attempts, 'attempts')
       },
@@ -491,7 +491,7 @@ describe('Navigation', () => {
     })
     
     // Simulate navigation
-    odac.load('/about')
+    Odac.load('/about')
     
     // Assert
     expect(document.querySelector('.nav-link.active').href)

package/docs/frontend/03-forms/01-form-handling.md

@@ -14,7 +14,7 @@ Learn how to handle forms with automatic AJAX submission, CSRF protection, and v
 ```
 
 ```javascript
-odac.form('#contact-form', function(data) {
+Odac.form('#contact-form', function(data) {
   if (data.result.success) {
     alert('Form submitted successfully!')
   }
@@ -35,7 +35,7 @@ That's it! odac.js handles:
 ### Basic Usage
 
 ```javascript
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   console.log('Response:', data)
 })
 ```
@@ -43,7 +43,7 @@ odac.form('#my-form', function(data) {
 ### With Options
 
 ```javascript
-odac.form({
+Odac.form({
   form: '#my-form',
   messages: true,  // Show error/success messages
   loading: function(percent) {
@@ -59,10 +59,37 @@ odac.form({
 ### Redirect After Submit
 
 ```javascript
-odac.form('#my-form', '/success-page')
+Odac.form('#my-form', '/success-page')
 // Redirects to /success-page on success
 ```
 
+## Using with `<odac:form>` Components
+
+`Odac.form()` works with both plain `<form>` elements and server-rendered
+[`<odac:form>` components](../../backend/05-forms/01-custom-forms.md).
+
+An `<odac:form>` already registers itself automatically, so you only call
+`Odac.form()` when you want to add your own callback. Give the component an `id`
+and bind to it:
+
+```html
+<odac:form action="Contact.submit" id="contact-form">
+  <!-- fields -->
+  <odac:submit text="Send"/>
+</odac:form>
+```
+
+```javascript
+Odac.form('#contact-form', function(data) {
+  if (data.result.success) {
+    closeModal()
+  }
+})
+```
+
+Calling `Odac.form()` on an already-registered `<odac:form>` **re-binds** the
+same form instead of adding a second handler, so it still submits only once.
+
 ## Error Handling
 
 ### Automatic Error Display
@@ -85,7 +112,7 @@ If you want to control where errors appear, add error elements manually:
 ### Custom Error Display
 
 ```javascript
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   if (!data.result.success) {
     // Custom error handling
     Object.entries(data.errors).forEach(([field, message]) => {
@@ -137,7 +164,7 @@ If you want to control where success messages appear, add a success element manu
 ### Custom Success Message
 
 ```javascript
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   if (data.result.success) {
     document.querySelector('#custom-message').innerHTML = 
       'Thank you! Your form has been submitted.'
@@ -147,49 +174,66 @@ odac.form('#my-form', function(data) {
 
 ## File Uploads
 
-### Basic File Upload
+### Basic File Upload with `<odac:form>`
+
+File upload in Odac forms is seamless — just add a `type="file"` input and validation rules:
 
 ```html
-<form id="upload-form" action="/api/upload" method="POST">
-  <input name="file" type="file" required>
-  <button type="submit">Upload</button>
-</form>
+<odac:form action="Profile.saveAvatar" id="avatar-form">
+  <odac:input type="file" name="avatar" label="Profile Picture">
+    <odac:validate rule="required|maxsize:2MB|mimetype:image/png,image/jpeg" message="PNG/JPEG, max 2MB"/>
+  </odac:input>
+  <odac:submit text="Upload"/>
+</odac:form>
 ```
 
 ```javascript
-odac.form('#upload-form', function(data) {
+Odac.form('#avatar-form', function(data) {
   if (data.result.success) {
-    console.log('File uploaded:', data.result.filename)
+    alert('Avatar uploaded!')
   }
 })
 ```
 
-### Upload Progress
+**Features:**
+- ✅ Client-side validation (size, MIME type, extension)
+- ✅ Server-side validation with magic-byte sniffing for images
+- ✅ Automatic multipart/form-data handling
+- ✅ File size progress tracking
+
+### Upload Progress Tracking
 
 ```javascript
-odac.form({
-  form: '#upload-form',
+Odac.form({
+  form: '#avatar-form',
   loading: function(percent) {
     document.querySelector('#progress').style.width = percent + '%'
-    document.querySelector('#progress-text').textContent = percent + '%'
   }
 }, function(data) {
-  console.log('Upload complete!')
+  if (data.result.success) {
+    console.log('Upload complete!')
+  }
 })
 ```
 
-### Multiple Files
+### Multiple File Upload
+
+For multiple file selection, add the `multiple` attribute and use `maxfiles` validation:
 
 ```html
-<input name="files[]" type="file" multiple>
+<odac:input type="file" name="documents" label="Documents" multiple>
+  <odac:validate rule="maxfiles:5|ext:pdf,docx" message="Max 5 PDFs/Word docs"/>
+</odac:input>
 ```
 
+**Note:** File inputs are never repopulated on validation error (for security). Users must re-select files after an error.
+
 ## Advanced Features
 
 ### Disable Messages
 
 ```javascript
-odac.form({
+Odac.form({
   form: '#my-form',
   messages: false  // Don't show automatic messages
 }, function(data) {
@@ -201,7 +245,7 @@ odac.form({
 
 ```javascript
 // Only show error messages, suppress success messages
-odac.form({
+Odac.form({
   form: '#my-form',
   messages: ['error']
 }, function(data) {
@@ -211,7 +255,7 @@ odac.form({
 })
 
 // Only show success messages, suppress error messages
-odac.form({
+Odac.form({
   form: '#my-form',
   messages: ['success']
 }, function(data) {
@@ -224,7 +268,7 @@ odac.form({
 ### Form Reset
 
 ```javascript
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   if (data.result.success) {
     // Reset the form
     document.querySelector('#my-form').reset()
@@ -242,7 +286,7 @@ document.querySelector('#my-form').addEventListener('submit', function(e) {
   }
 })
 
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   console.log('Submitted!')
 })
 ```
@@ -254,8 +298,8 @@ odac.form('#my-form', function(data) {
 ```javascript
 // controller/post/contact.js
 module.exports = async function(Odac) {
-  const email = await odac.Request.request('email')
-  const message = await odac.Request.request('message')
+  const email = await Odac.Request.request('email')
+  const message = await Odac.Request.request('message')
   
   // Validation
   const errors = {}
@@ -285,7 +329,7 @@ module.exports = async function(Odac) {
 
 ```javascript
 // route/www.js
-odac.Route.post('/api/contact', 'contact')
+Odac.Route.post('/api/contact', 'contact')
 ```
 
 ## Validation
@@ -306,7 +350,7 @@ Always validate on the server:
 
 ```javascript
 module.exports = async function(Odac) {
-  const email = await odac.Request.request('email')
+  const email = await Odac.Request.request('email')
   
   const errors = {}
   
@@ -349,7 +393,7 @@ module.exports = async function(Odac) {
 **Note:** Error and success elements are auto-generated. Add them manually only if you need custom positioning or styling.
 
 ```javascript
-odac.form('#contact-form', function(data) {
+Odac.form('#contact-form', function(data) {
   if (data.result.success) {
     document.querySelector('#contact-form').reset()
   }
@@ -367,7 +411,7 @@ odac.form('#contact-form', function(data) {
 ```
 
 ```javascript
-odac.form('#login-form', function(data) {
+Odac.form('#login-form', function(data) {
   if (data.result.success) {
     // Redirect to dashboard
     window.location.href = '/dashboard'
@@ -420,6 +464,15 @@ odac.form('#login-form', function(data) {
 - Verify `messages` option is not set to `false`
 - If using custom error elements, ensure `odac-form-error` attributes match field names exactly
 
+### Form Submits Twice
+
+- Make sure you don't register the **same form under two different selectors**
+  (e.g. `Odac.form('#my-form')` and `Odac.form('form#my-form')`) — use one
+  consistent selector.
+- Binding `Odac.form()` to an `<odac:form>` is safe and will **not** double up;
+  it re-binds the existing handler. If you still see two submits, check that you
+  bind **after** the form is in the DOM, not before it renders.
+
 ### CSRF Token Errors
 
 - CSRF tokens are handled automatically

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

@@ -7,7 +7,7 @@ Learn how to make GET and POST requests to your API endpoints using odac.js.
 ### Basic GET Request
 
 ```javascript
-odac.get('/api/data', function(response) {
+Odac.get('/api/data', function(response) {
   console.log('Data:', response)
 })
 ```
@@ -16,7 +16,7 @@ odac.get('/api/data', function(response) {
 
 ```javascript
 const userId = 123
-odac.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 @@ odac.get(`/api/users/${userId}`, function(user) {
 ### Error Handling
 
 ```javascript
-odac.get('/api/data', function(response) {
+Odac.get('/api/data', function(response) {
   if (response.error) {
     console.error('Error:', response.error)
     return
@@ -43,7 +43,7 @@ odac.get('/api/data', function(response) {
 The recommended way to make POST requests is using `Odac.form()`:
 
 ```javascript
-odac.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 odac.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', odac.token())
+formData.append('_token', Odac.token())
 
 fetch('/api/submit', {
   method: 'POST',
@@ -83,12 +83,12 @@ odac.js automatically handles CSRF tokens:
 
 ```javascript
 // Token is automatically included
-odac.get('/api/data', function(response) {
+Odac.get('/api/data', function(response) {
   // ...
 })
 
 // Token is automatically included in forms
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   // ...
 })
 ```
@@ -98,7 +98,7 @@ odac.form('#my-form', function(data) {
 If you need the token manually:
 
 ```javascript
-const token = odac.token()
+const token = Odac.token()
 console.log('Current token:', token)
 ```
 
@@ -108,7 +108,7 @@ console.log('Current token:', token)
 
 ```javascript
 // Get user profile
-odac.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 @@ odac.get('/api/profile', function(profile) {
 
 ```javascript
 // Get products
-odac.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
   
-  odac.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
     
-    odac.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++
   
-  odac.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() {
-  odac.get('/api/notifications', function(notifications) {
+  Odac.get('/api/notifications', function(notifications) {
     updateNotificationBadge(notifications.count)
   })
 }, 30000)
@@ -239,7 +239,7 @@ module.exports = function(Odac) {
 
 ```javascript
 // route/www.js
-odac.Route.get('/api/users', 'users')
+Odac.Route.get('/api/users', 'users')
 ```
 
 ### GET with Parameters
@@ -247,13 +247,13 @@ odac.Route.get('/api/users', 'users')
 ```javascript
 // controller/get/user.js
 module.exports = async function(Odac) {
-  const userId = odac.Request.data.url.id
+  const userId = Odac.Request.data.url.id
   
   // Fetch user from database
   const user = await getUserById(userId)
   
   if (!user) {
-    odac.Request.status(404)
+    Odac.Request.status(404)
     return {error: 'User not found'}
   }
   
@@ -263,7 +263,7 @@ module.exports = async function(Odac) {
 
 ```javascript
 // route/www.js
-odac.Route.get('/api/users/{id}', 'user')
+Odac.Route.get('/api/users/{id}', 'user')
 ```
 
 ### POST Endpoint
@@ -271,8 +271,8 @@ odac.Route.get('/api/users/{id}', 'user')
 ```javascript
 // controller/post/create.js
 module.exports = async function(Odac) {
-  const name = await odac.Request.request('name')
-  const email = await odac.Request.request('email')
+  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(Odac) {
 
 ```javascript
 // route/www.js
-odac.Route.post('/api/users/create', 'create')
+Odac.Route.post('/api/users/create', 'create')
 ```
 
 ## Response Format
@@ -357,7 +357,7 @@ function getCached(url, callback) {
     return
   }
   
-  odac.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()
   
-  odac.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++
     
-    odac.get(url, function(data) {
+    Odac.get(url, function(data) {
       if (data.error && attempts < maxRetries) {
         setTimeout(attempt, 1000 * attempts)
       } else {

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

@@ -6,7 +6,7 @@ Odac provides a simple client-side API for consuming Server-Sent Events (SSE) st
 
 ```javascript
 // Simple callback
-odac.listen('/events', (data) => {
+Odac.listen('/events', (data) => {
   console.log('Received:', data)
 })
 ```
@@ -14,7 +14,7 @@ odac.listen('/events', (data) => {
 ### With Options
 
 ```javascript
-const stream = odac.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
-odac.listen('/events', (data) => {
+Odac.listen('/events', (data) => {
   console.log(data.message) // "Hello"
 })
 ```
@@ -47,8 +47,8 @@ odac.listen('/events', (data) => {
 
 ```javascript
 // Server
-odac.Route.get('/dashboard/stats', async (Odac) => {
-  odac.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 @@ odac.Route.get('/dashboard/stats', async (Odac) => {
 })
 
 // Client
-odac.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 @@ odac.listen('/dashboard/stats', (stats) => {
 
 ```javascript
 // Server
-odac.Route.get('/notifications', async (Odac) => {
-  const userId = await odac.request('userId')
+Odac.Route.get('/notifications', async (Odac) => {
+  const userId = await Odac.request('userId')
   
-  odac.stream((send) => {
+  Odac.stream((send) => {
     global.notificationStreams[userId] = { send }
   })
 })
 
 // Client
-odac.listen('/notifications', (notification) => {
+Odac.listen('/notifications', (notification) => {
   showToast(notification.message)
 })
 ```
@@ -90,8 +90,8 @@ odac.listen('/notifications', (notification) => {
 
 ```javascript
 // Server
-odac.Route.get('/build/logs', async (Odac) => {
-  odac.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 @@ odac.Route.get('/build/logs', async (Odac) => {
 
 // Client
 const logs = []
-odac.listen('/build/logs', (log) => {
+Odac.listen('/build/logs', (log) => {
   logs.push(log)
   updateLogsUI(logs)
 })
@@ -108,7 +108,7 @@ odac.listen('/build/logs', (log) => {
 
 ## API Reference
 
-### odac.listen(url, onMessage, options)
+### Odac.listen(url, onMessage, options)
 
 **Parameters:**
 - `url` (string): Stream endpoint URL

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

@@ -6,7 +6,7 @@ Odac provides built-in WebSocket support with automatic reconnection and cross-t
 
 **Backend (route/main.js):**
 ```javascript
-odac.Route.ws('/chat', (ws, Odac) => {
+Odac.Route.ws('/chat', (ws, Odac) => {
   ws.on('message', data => {
     ws.broadcast(data)
   })

package/index.js

@@ -1,4 +1,14 @@
 'use strict'
 
 global.__dir = process.cwd()
-require('./src/Odac.js').init()
+
+// Surface startup failures loudly. init() is async; without a .catch() any
+// rejection (migration, DB connection, config parse) becomes an UnhandledPromiseRejection
+// that the structured logger never sees — making a broken boot look like a clean start.
+require('./src/Odac.js')
+  .init()
+  .catch(err => {
+    console.error('\x1b[31m[ODAC Fatal]\x1b[0m Startup failed:', err.message)
+    if (err.cause) console.error('\x1b[31m[ODAC Fatal]\x1b[0m Cause:', err.cause.message || err.cause)
+    process.exit(1)
+  })