odac 1.4.6 → 1.4.8

package/CHANGELOG.md

@@ -1,3 +1,40 @@
+### ✨ What's New
+
+- **database:** add Write-Behind Cache with counter, update, and batch insert buffering
+- **ipc,database:** extend Ipc with atomic ops and delegate WriteBuffer state to Ipc layer
+
+### 🛠️ Fixes & Improvements
+
+- atomic queue drain, transaction-safe flush, hgetall clone & unhandled rejection
+- **odac:** ensure proper token query parameter handling in get method
+- **storage:** ensure synchronous operations for put and remove methods
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### ⚙️ Engine Tuning
+
+- **test:** remove unused fsPromises and standardize async I/O in View tests
+
+### 📚 Documentation
+
+- add quick start guide and register in documentation index
+
+### 🛠️ Fixes & Improvements
+
+- add raw attribute support to `<odac get>` tag for unescaped HTML output
+- improve title extraction logic and optimize data-odac-navigate attribute injection in View rendering
+- prevent data-odac-navigate injection into closing HTML tags
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### ⚙️ Engine Tuning
 
 - replace global Odac reference with private instance and update dependency overrides for security hardening

package/client/odac.js

@@ -679,7 +679,7 @@ if (typeof window !== 'undefined') {
     }
 
     get(url, callback) {
-      url = url + '?_token=' + this.token()
+      url = url + (url.includes('?') ? '&' : '?') + '_token=' + this.token()
       this.#ajax({url: url, success: callback})
     }
 

package/docs/ai/README.md

@@ -24,7 +24,7 @@ Detailed instructions are organized into Backend and Frontend categories:
 - `backend/config.md`: Configuration management and environment variables.
 - `backend/controllers.md`: Request handling and Class-Based Controllers.
 - `backend/cron.md`: Scheduled background tasks and automation.
-- `backend/database.md`: High-performance query builder usage.
+- `backend/database.md`: High-performance query builder usage, Write-Behind Cache (buffered counters, last-write-wins updates, batch inserts).
 - `backend/forms.md`: Form processing and validation logic.
 - `backend/ipc.md`: Inter-Process Communication and state sharing.
 - `backend/mail.md`: Transactional email sending.

package/docs/ai/skills/SKILL.md

@@ -18,7 +18,7 @@ Read the specific rule files based on whether you are working on the Backend or
 - [backend/config.md](backend/config.md) - Configuration management and environment variables
 - [backend/controllers.md](backend/controllers.md) - Request handling and Class-Based Controllers
 - [backend/cron.md](backend/cron.md) - Scheduled background tasks and automation
-- [backend/database.md](backend/database.md) - Query Builder and DB best practices
+- [backend/database.md](backend/database.md) - Query Builder, Write-Behind Cache, and DB best practices
 - [backend/forms.md](backend/forms.md) - Form processing and Validation logic
 - [backend/ipc.md](backend/ipc.md) - Inter-Process Communication and state sharing
 - [backend/mail.md](backend/mail.md) - Transactional email sending

package/docs/ai/skills/backend/database.md

@@ -1,30 +1,32 @@
 ---
 name: backend-database-skill
-description: High-performance ODAC database querying patterns using the built-in query builder with secure and efficient data access.
+description: High-performance ODAC database querying patterns including the Write-Behind Cache for counters, last-write-wins updates, and buffered batch inserts.
 metadata:
-  tags: backend, database, query-builder, sql, indexing, performance, security
+  tags: backend, database, query-builder, sql, write-behind-cache, performance, security
 ---
 
 # Backend Database Skill
 
-High-performance database operations using the ODAC Query Builder.
+High-performance database operations using the ODAC Query Builder and Write-Behind Cache.
 
 ## Principles
 1.  **Directness**: Avoid ORM overhead. Use fluent Query Builder.
 2.  **Safety**: Always use parameterized queries (built-in).
 3.  **Efficiency**: Index foreign keys. No `SELECT *`.
+4.  **Write Coalescing**: Use `buffer` for high-frequency writes to avoid DB saturation.
 
-## Patterns
+## Query Builder Patterns
 ```javascript
-const user = await Odac.DB.table('users')
+const user = await Odac.DB.users
   .select('id', 'name', 'email')
   .where('status', 'active')
-  .first();
+  .first()
 
-await Odac.DB.table('posts').insert({
-  title: 'Hello',
-  user_id: 1
-});
+await Odac.DB.posts.insert({title: 'Hello', user_id: 1})
+
+await Odac.DB.users.where('id', 1).update({last_login: new Date()})
+
+const count = await Odac.DB.users.where('active', true).count() // → Number
 ```
 
 ## ID Strategy (NanoID)
@@ -43,7 +45,96 @@ module.exports = {
 }
 
 // ID is generated automatically
-await Odac.DB.table('posts').insert({title: 'Hello'});
+await Odac.DB.posts.insert({title: 'Hello'})
+```
+
+## Write-Behind Cache (`buffer`)
+
+The `buffer` API routes all writes through `Odac.Ipc`. The active IPC driver determines the scaling model — no code changes required when switching drivers.
+
+- **`memory` driver** (default): Primary process holds all state; workers communicate via cluster IPC.
+- **`redis` driver**: State lives in Redis — works transparently across multiple servers.
+
+### When to suggest `buffer`
+
+Propose the Write-Behind Cache when the user's write operation meets **all three** of these criteria:
+1. **High frequency** — the same column or row is written on many requests (counters, timestamps, last-seen values).
+2. **Eventual consistency is acceptable** — a few seconds' delay before the value reaches the DB is fine.
+3. **Not safety-critical** — losing the buffered value in a crash has no financial, legal, or user-facing consequence.
+
+**Typical candidates:**
+- Page / post / download view counters (`increment`)
+- Like, upvote, share counts (`increment`)
+- User last-active timestamp, last IP (`update`)
+- Analytics events, audit logs, activity streams (`insert`)
+- Score accumulators, play counts, rating tallies (`increment`)
+
+**Do NOT suggest `buffer` for:**
+- Payments, charges, refunds, or any monetary operation
+- Order creation, inventory decrements
+- Anything the same request needs to read back immediately
+- Inserts that return a generated ID the caller uses
+
+When in doubt, use a direct DB call.
+
+**Three operation types:**
+
+### 1. Counter Increment (Write Coalescing)
+Accumulates deltas — multiple increments merge into one `UPDATE col = col + delta`.
+`get()` returns `base + pending delta` (always current, no DB read needed).
+```javascript
+// Increment — returns current total (DB base + buffered delta)
+const views = await Odac.DB.posts.buffer.where(postId).increment('views')
+const likes = await Odac.DB.posts.buffer.where(postId).increment('likes', 5)
+
+// Read buffered counter (no extra DB round-trip)
+const current = await Odac.DB.posts.buffer.where(postId).get('views')
+
+// Composite key
+await Odac.DB.post_stats.buffer.where({post_id: 1, date: '2026-04-01'}).increment('views')
+```
+
+### 2. Last-Write-Wins Update (Field Coalescing)
+Multiple updates to the same row merge column maps — 50 requests = 1 `UPDATE` at flush.
+```javascript
+// Columns are merged per row: first update + second update = single UPDATE at flush
+await Odac.DB.users.buffer.where(userId).update({active_date: new Date()})
+await Odac.DB.users.buffer.where(userId).update({last_ip: req.ip})
+// → UPDATE users SET active_date = ?, last_ip = ? WHERE id = ?  (one query)
+```
+
+### 3. Batch Insert (Queue)
+Rows accumulate in memory; flushed in chunks of 1000. Auto-flushes when `maxQueueSize` is reached.
+```javascript
+await Odac.DB.activity_log.buffer.insert({user_id: userId, action: 'page_view', meta: url})
+```
+
+### Manual Flush
+```javascript
+await Odac.DB.posts.buffer.flush()   // flush this table only
+await Odac.DB.buffer.flush()         // flush everything
+```
+
+## Write-Behind Cache — Key Rules
+1.  **Ipc-Backed**: All buffer state goes through `Odac.Ipc`. Memory driver = Primary holds state; Redis driver = Redis holds state.
+2.  **Horizontally Scalable**: With Redis driver, multiple servers share the same buffer state. Distributed lock (`Ipc.lock`) prevents duplicate flushes.
+3.  **Crash-Safe (memory)**: LMDB checkpoint written every 30s. On restart, pending data is recovered and flushed before serving traffic.
+4.  **Crash-Safe (redis)**: Redis persistence provides durability. LMDB checkpoints are skipped.
+5.  **get() is authoritative**: Always returns `DB base + buffered delta`. Never stale.
+6.  **Flush on shutdown**: `Database.close()` triggers a final flush automatically — no data loss on graceful shutdown.
+7.  **Error resilience**: If a flush fails, data is retained in Ipc for the next cycle. Never lost silently.
+8.  **NEVER use buffer for safety-critical writes**: Payment records, order confirmations, balance changes, inventory decrements — anything where data loss has real-world consequences MUST use direct DB transactions. The buffer does not guarantee delivery before a crash.
+
+## Configuration (`odac.json`)
+```json
+{
+  "buffer": {
+    "flushInterval": 5000,
+    "checkpointInterval": 30000,
+    "maxQueueSize": 10000,
+    "primaryKey": "id"
+  }
+}
 ```
 
 ## Migration Awareness
@@ -53,4 +144,4 @@ await Odac.DB.table('posts').insert({title: 'Hello'});
 4.  **Indexes**: Keep index definitions in schema so add/drop is managed automatically.
 5.  **Data Changes**: Use `migration/*.js` only for one-time data transformation.
 
-See: [migrations.md](./migrations.md)
+See: [migrations.md](./migrations.md) | [write-behind-cache user docs](../../../backend/08-database/05-write-behind-cache.md)

package/docs/ai/skills/backend/ipc.md

@@ -24,25 +24,81 @@ IPC abstracts the underlying driver, allowing seamless transition between `memor
 ### 1. Key-Value Storage
 ```javascript
 // Set value with optional TTL (seconds)
-await Odac.Ipc.set('maintenance_mode', true);
-await Odac.Ipc.set('cache_key', { data: 123 }, 60);
+await Odac.Ipc.set('maintenance_mode', true)
+await Odac.Ipc.set('cache_key', {data: 123}, 60)
 
 // Get value
-const status = await Odac.Ipc.get('maintenance_mode');
+const status = await Odac.Ipc.get('maintenance_mode')
 
 // Delete value
-await Odac.Ipc.del('maintenance_mode');
+await Odac.Ipc.del('maintenance_mode')
 ```
 
-### 2. Pub/Sub Messaging
+### 2. Atomic Counters
 ```javascript
-// Subscribe to a channel (usually in a service or app start)
+// Increment / decrement a numeric key (returns new value)
+await Odac.Ipc.incrBy('page:views', 1)    // → 1
+await Odac.Ipc.incrBy('page:views', 5)    // → 6
+await Odac.Ipc.decrBy('page:views', 2)    // → 4
+
+// Read current value
+const views = await Odac.Ipc.get('page:views')  // → 4
+```
+
+### 3. Hash Maps
+```javascript
+// Set / merge fields (last-write-wins per field)
+await Odac.Ipc.hset('user:1', {active_date: new Date(), last_ip: '1.2.3.4'})
+await Odac.Ipc.hset('user:1', {score: 42})
+
+// Get all fields
+const fields = await Odac.Ipc.hgetall('user:1')
+// → {active_date: ..., last_ip: '1.2.3.4', score: 42}
+```
+
+### 4. Lists
+```javascript
+// Append items to the right (returns new length)
+await Odac.Ipc.rpush('events', {type: 'click'}, {type: 'view'})  // → 2
+
+// Read range (inclusive, -1 = last item)
+const items = await Odac.Ipc.lrange('events', 0, -1)
+```
+
+### 5. Sets
+```javascript
+// Add members
+await Odac.Ipc.sadd('online_users', 'user:1', 'user:2')
+
+// Get all members
+const users = await Odac.Ipc.smembers('online_users')  // → ['user:1', 'user:2']
+
+// Remove members (returns removed count)
+await Odac.Ipc.srem('online_users', 'user:1')
+```
+
+### 6. Distributed Locks
+```javascript
+// Acquire lock with TTL in seconds (returns true if acquired, false if already held)
+const acquired = await Odac.Ipc.lock('flush:lock', 10)
+if (!acquired) return  // another process is holding the lock
+
+try {
+  // ... critical section ...
+} finally {
+  await Odac.Ipc.unlock('flush:lock')
+}
+```
+
+### 7. Pub/Sub Messaging
+```javascript
+// Subscribe to a channel
 await Odac.Ipc.subscribe('notifications', (msg) => {
-  console.log('Received:', msg);
-});
+  console.log('Received:', msg)
+})
 
 // Publish a message from any worker
-await Odac.Ipc.publish('notifications', { type: 'alert', text: 'System update' });
+await Odac.Ipc.publish('notifications', {type: 'alert', text: 'System update'})
 ```
 
 ## Configuration
@@ -57,6 +113,9 @@ In `odac.json` or a config provider:
 ```
 
 ## Best Practices
--   **Async First**: All IPC operations are asynchronous.
--   **TTL Usage**: Always set a TTL for temporary cache data to prevent memory bloat.
--   **Scaling**: Switch to `redis` driver when deploying across multiple containers or servers.
+- **Async First**: All IPC operations are asynchronous.
+- **TTL Usage**: Always set a TTL for temporary cache data to prevent memory bloat.
+- **Scaling**: Switch to `redis` driver when deploying across multiple containers or servers. No application code changes required.
+- **Locks**: Always release locks in a `finally` block to prevent deadlocks.
+- **Sets for indexes**: Use `sadd/smembers/srem` to track active keys — avoids expensive SCAN operations.
+- **Atomic counters over get+set**: Use `incrBy`/`decrBy` instead of `get` → compute → `set` to prevent race conditions.

package/docs/ai/skills/backend/views.md

@@ -18,7 +18,8 @@ Views in ODAC are logic-light but powerful. They support automatic XSS protectio
 3.  **Data Binding — Two Equivalent Syntaxes**:
     -   `<odac var="key" />`: Tag-based output (HTML-escaped, XSS-safe).
     -   `{{ key }}`: Inline/interpolation output (HTML-escaped, XSS-safe). Identical behavior to `<odac var>`.
-    -   `<odac var="key" raw />` or `{!! key !!}`: Raw output (use with extreme caution).
+    -   `<odac get="key" />`: Query Parameter output (HTML-escaped, XSS-safe).
+    -   `<odac var="key" raw />`, `<odac get="key" raw />` or `{!! key !!}`: Raw output (use with extreme caution).
 4.  **Choosing the Right Syntax**:
     -   **Inside HTML attributes** (`src`, `alt`, `href`, `class`, `value`, etc.) → Always prefer `{{ }}`.
     -   **Inline within text or mixed HTML** → Prefer `{{ }}` for short interpolations.
@@ -112,6 +113,10 @@ module.exports = function (Odac) {
 <!-- Inline text interpolation -->
 <p>Welcome, {{ user.name }}. You have {{ notifications }} new messages.</p>
 
+<!-- Query parameter from URL (/page?q=search) -->
+<p>Search Results for: <odac get="q" /></p>
+<div class="raw-content"><odac get="htmlContent" raw /></div>
+
 <!-- Conditional -->
 <odac:if condition="stats.users > 100">
   <span class="badge">Popular!</span>

package/docs/backend/00-getting-started/01-quick-start.md

@@ -0,0 +1,77 @@
+## 🚀 Quick Start
+
+ODAC is built for speed and zero-configuration. You can bootstrap a production-ready, high-performance web application in seconds.
+
+### 1. Requirements
+
+- **Node.js:** 18.0.0 or higher.
+- **npm:** 8.0.0 or higher.
+
+---
+
+### 2. Initialize Your Project
+
+The standard way to start an ODAC project is using the interactive **init** command via `npx`. Run this in your terminal:
+
+```bash
+npx odac init my-app
+```
+
+**What this does:**
+- Creates a new folder named `my-app`.
+- Copies the ODAC enterprise skeleton (controllers, routes, views, etc.).
+- Initializes `package.json` with the latest ODAC framework dependency.
+- Runs `npm install` automatically.
+
+---
+
+### 3. Launch Development Mode
+
+Navigate into your project directory and start the smart development server:
+
+```bash
+cd my-app
+npm run dev
+```
+
+Your app is now live at `http://localhost:1071` (default port).
+
+**Features enabled in Dev Mode:**
+- **Hot-reloading:** The server and cluster workers restart instantly on backend changes.
+- **Zero-Config Tailwind CSS v4:** Automatically watches and compiles your styles.
+- **Detailed Stack Traces:** Helps you debug errors quickly in the browser and console.
+
+---
+
+### 4. Setup AI Agent Skills
+
+ODAC is designed to be **AI-First**. It provides pre-built "skills" (knowledge files) that teach your AI coding assistant (like Antigravity, Claude, Cursor, or Windsurf) exactly how to write ODAC-compatible code.
+
+Run this command inside your project root:
+
+```bash
+npx odac skills
+```
+
+Follow the interactive prompt to sync the documentation and patterns directly into your IDE's agent configuration folder.
+
+---
+
+### 5. Essential Commands
+
+| Command | Description |
+| :--- | :--- |
+| `npm run dev` | Start development server with hot-reload & styles. |
+| `npm run build` | Compile and minify styles for production. |
+| `npm start` | Run the application in high-performance production mode. |
+| `npx odac migrate` | Run pending database migrations. |
+| `npx odac skills` | Sync/Update AI Agent knowledge files. |
+
+---
+
+### 6. Next Steps
+
+- **Define Routes:** Open `route/web.js` to see how URLs are mapped to views.
+- **Project Structure:** Learn how to organize your [file/folder layout](../02-structure/01-typical-project-layout.md).
+- **Build Views:** Check the `view/` directory for your HTML templates.
+- **Manage Database:** Update `odac.json` to connect to PostgreSQL, MySQL, or SQLite.

package/docs/backend/07-views/03-template-syntax.md

@@ -50,6 +50,10 @@ Access URL query parameters directly:
 <!-- URL: /search?q=laptop -->
 <odac get="q" />
 <!-- Output: laptop -->
+
+<!-- Get raw query parameter (unescaped) -->
+<odac get="htmlContent" raw />
+<!-- Output: <b>Trusted HTML</b> -->
 ```
 
 **Note:** `<odac get>` is for URL parameters. For controller data, use `<odac var>`.
@@ -185,6 +189,7 @@ Full access to the Odac object in templates:
 | Raw HTML (inline) | `{!! x !!}` | [Variables](./03-variables.md) |
 | String | `<odac>text</odac>` | [Variables](./03-variables.md) |
 | Query Parameter | `<odac get="key" />` | [Request Data](./04-request-data.md) |
+| Query Parameter Raw | `<odac get="key" raw />` | [Request Data](./04-request-data.md) |
 | Translation | `<odac translate>key</odac>` | [Translations](./07-translations.md) |
 | Translation Raw | `<odac translate raw>key</odac>` | [Translations](./07-translations.md) |
 | If | `<odac:if condition="x">` | [Conditionals](./05-conditionals.md) |

package/docs/backend/07-views/04-request-data.md

@@ -33,6 +33,19 @@ If a parameter doesn't exist, it safely returns an empty string:
 
 This prevents errors when parameters are optional.
 
+### Raw HTML Output
+
+By default, `<odac get>` automatically escapes HTML special characters to prevent XSS attacks. If you need to output raw HTML from a query parameter (only from trusted sources), use the `raw` attribute:
+
+```html
+<!-- URL: /page?content=%3Cb%3EHello%3C/b%3E -->
+
+<odac get="content" raw />
+<!-- Output: <b>Hello</b> -->
+```
+
+**Security Warning:** Never use `raw` with query parameters if they can contain user-generated content. Query parameters are easily manipulated by users. Only use `raw` if you are certain the value is safe (e.g., predefined tokens).
+
 ### Difference: get vs var
 
 **`<odac get>` - Query Parameters (from URL):**