odac 1.4.8 → 1.4.10

package/docs/backend/08-database/06-read-through-cache.md

@@ -0,0 +1,206 @@
+# Read-Through Cache
+
+At high traffic, repeatedly querying the same data — blog posts, product listings, settings, categories — generates redundant database round-trips. A page with 10,000 daily visitors reading the same 50 posts means 10,000 identical `SELECT` queries.
+
+ODAC's **Read-Through Cache** solves this by caching `SELECT` results in `Odac.Ipc` and serving subsequent requests from memory. The only change to your code is adding `.cache()` to the chain.
+
+```javascript
+// Without cache — 1 DB query per request
+const posts = await Odac.DB.posts.where('active', true).select('id', 'title')
+
+// With cache — 1 DB query per TTL window, for all requests combined
+const posts = await Odac.DB.posts.cache(60).where('active', true).select('id', 'title')
+```
+
+---
+
+## How It Works
+
+**Architecture: Ipc-Backed, Driver-Agnostic**
+
+All cached data is stored in `Odac.Ipc`. The active IPC driver determines the scaling model:
+
+| Driver | Scope | When to use |
+|---|---|---|
+| `memory` (default) | Single machine — all workers share cache via Primary process | Single-server deployments |
+| `redis` | Multi-machine — all servers share cache in Redis | Horizontal scaling behind a load balancer |
+
+```
+// Memory driver (default)
+Worker 1 ─┐
+Worker 2 ─┼──→ Primary (Ipc memory store) ← cache HIT: O(1) return
+Worker N ─┘                                ← cache MISS: DB query → store → return
+
+// Redis driver
+Server A ─┐
+Server B ─┼──→ Redis (Ipc state) ← shared cache across all servers
+Server C ─┘
+```
+
+**Cache Key Generation**
+
+Each query is identified by a SHA-256 hash of its compiled SQL and bindings. Two identical queries — regardless of which worker or server generates them — always resolve to the same cache key.
+
+```
+rc:{connection}:{table}:{sha256(sql + bindings)}
+```
+
+**Automatic Invalidation**
+
+Any `insert()`, `update()`, `delete()`, or `truncate()` on a table automatically purges all cached queries for that table. You never need to manually invalidate after a write — ODAC handles it.
+
+```javascript
+// This update automatically clears all cached queries on the 'posts' table
+await Odac.DB.posts.where({id: 5}).update({title: 'New Title'})
+```
+
+**Cross-Table Invalidation (JOIN queries)**
+
+When a cached query includes `JOIN` clauses, ODAC automatically registers the cache key in all joined tables' indexes. This means a write to any table involved in the query triggers invalidation.
+
+```javascript
+// This query is registered in BOTH 'posts' and 'users' cache indexes
+const data = await Odac.DB.posts
+  .cache(60)
+  .join('users', 'posts.user_id', '=', 'users.id')
+  .select('posts.title', 'users.name')
+
+// Writing to 'users' invalidates the cached join query above — no stale data
+await Odac.DB.users.where({id: 1}).update({name: 'New Name'})
+```
+
+This works with `join()`, `leftJoin()`, `rightJoin()`, and aliased tables (`users as u`).
+
+---
+
+## Basic Usage
+
+### Cache with TTL
+
+Pass a TTL (in seconds) to `.cache()`. The result is served from cache for that duration, then re-fetched from the database on the next request.
+
+```javascript
+// Cache for 60 seconds
+const posts = await Odac.DB.posts.cache(60).where('active', true).select('id', 'title')
+
+// Cache for 5 minutes (default TTL from config)
+const post = await Odac.DB.posts.cache().where({id: 5}).first()
+
+// Cache a count
+const total = await Odac.DB.posts.cache(300).where('active', true).count()
+```
+
+### Named Connections
+
+```javascript
+// Default connection
+const posts = await Odac.DB.posts.cache(60).select('id', 'title')
+
+// Named connection: 'analytics'
+const stats = await Odac.DB.analytics.events.cache(120).where('date', today).select()
+```
+
+---
+
+## Manual Invalidation
+
+### Table-Level Clear
+
+Purge all cached queries for a table:
+
+```javascript
+// Via table proxy
+await Odac.DB.posts.cache.clear()
+
+// Via global accessor (useful in background jobs or service classes)
+await Odac.DB.cache.clear('default', 'posts')
+
+// Named connection
+await Odac.DB.cache.clear('analytics', 'events')
+```
+
+---
+
+## Automatic Invalidation on Write
+
+You do not need to call `.cache.clear()` after writes. ODAC intercepts all write operations on the proxy and invalidates the table cache automatically.
+
+| Operation | Cache invalidated? |
+|---|---|
+| `insert()` | ✅ Yes |
+| `update()` | ✅ Yes |
+| `delete()` | ✅ Yes |
+| `del()` | ✅ Yes |
+| `truncate()` | ✅ Yes |
+| `buffer.insert()` | ❌ No — buffer writes are deferred; invalidate manually if needed |
+
+> **Note on `buffer` + `cache`:** If you use the Write-Behind Cache (`buffer`) alongside the Read-Through Cache, the buffer's deferred writes do not trigger automatic invalidation. Call `Odac.DB.posts.cache.clear()` after a `buffer.flush()` if you need the cache to reflect the latest state immediately.
+
+---
+
+## Configuration
+
+Add a `cache` section to your `odac.json`:
+
+```json
+{
+  "cache": {
+    "ttl": 300,
+    "maxKeys": 10000
+  }
+}
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `ttl` | `300` | Default cache duration in seconds when `.cache()` is called without an argument |
+| `maxKeys` | `10000` | Maximum number of cached query keys per table. New entries are skipped once the limit is reached — protects against unbounded memory growth |
+
+---
+
+## Horizontal Scaling
+
+To share cache state across multiple servers, switch the `ipc` driver to `redis`:
+
+```json
+{
+  "ipc": {
+    "driver": "redis",
+    "redis": "default"
+  }
+}
+```
+
+With the Redis driver active, all servers share the same cache. A cache invalidation triggered by a write on Server A is immediately visible to Server B. No code changes are required in your application.
+
+---
+
+## When to Use (and Not Use)
+
+**Use Read-Through Cache for:**
+- Blog posts, articles, product listings
+- Navigation menus, category trees, tag lists
+- Site settings, feature flags, configuration values
+- Any data that is read frequently and changes infrequently
+
+**Do not use for:**
+- Data that must always reflect the latest DB state (e.g., account balances, inventory counts)
+- Queries with user-specific filters where caching would leak data across users
+- Queries inside transactions where consistency is critical
+
+> [!TIP]
+> Combine with the Write-Behind Cache for maximum throughput: use `.buffer` for high-frequency writes (view counters, last-active timestamps) and `.cache()` for high-frequency reads (post listings, settings). They operate independently and complement each other.
+
+---
+
+## Guarantees
+
+| Scenario | Behaviour |
+|---|---|
+| Cache MISS | DB query executes, result is stored in Ipc with TTL |
+| Cache HIT | Result returned from Ipc — no DB query |
+| TTL expired | Next request triggers a fresh DB query and re-caches |
+| `insert/update/delete` | All cached queries for that table are purged automatically |
+| Worker crash | No data loss — cache state is in Primary process (memory) or Redis |
+| `maxKeys` reached | New cache entries are skipped; existing entries still served |
+| Ipc not initialized | Invalidation is a no-op — safe for environments without Ipc setup |

package/docs/backend/10-authentication/01-authentication-basics.md

@@ -0,0 +1,53 @@
+## 🔐 Authentication Basics
+
+The `Odac.Auth` service is your bouncer, managing who gets in and who stays out. It handles user login sessions for you.
+
+#### Letting a User In
+
+`Odac.Auth.login(userId, userData)`
+
+*   `userId`: A unique ID for the user (like their database ID).
+*   `userData`: An object with any user info you want to remember, like their username or role.
+
+When you call this, `Auth` creates a secure session for the user.
+
+> **💡 Enterprise Security:** ODAC automatically handles **Token Rotation** every 15 minutes (configurable) and includes built-in **CSRF protection** for all forms. Sessions are persistent across browser restarts by default.
+
+#### Checking the Guest List
+
+*   `await Odac.Auth.check()`: Is the current user logged in? Returns `true` or `false`.
+*   `Odac.Auth.user()`: Gets the full user object of the logged-in user.
+*   `Odac.Auth.user('id')`: Gets a specific field from the user object (e.g., their ID).
+*   `Odac.Auth.token()`: Gets the full auth session record from the token table.
+*   `Odac.Auth.token('id')`: Gets the auth session ID from the token table.
+
+#### Showing a User Out
+
+*   `Odac.Auth.logout()`: Ends the user's session and logs them out.
+
+#### Example: A Login Flow
+```javascript
+// Controller for your login form
+module.exports = async function (Odac) {
+    const { username, password } = Odac.Request.post
+
+    const loginSuccess = await Odac.Auth.login({ username, password })
+
+    if (loginSuccess) {
+        return Odac.direct('/dashboard')
+    } else {
+        return Odac.direct('/login?error=1')
+    }
+}
+
+// A protected dashboard page
+module.exports = async function (Odac) {
+    if (!await Odac.Auth.check()) {
+        return Odac.direct('/login')
+    }
+
+    const username = Odac.Auth.user('username')
+    const authId = Odac.Auth.token('id')  // Auth session ID from token table
+    return `Welcome back, ${username}! (Session: ${authId})`
+}
+```

package/docs/backend/10-authentication/05-session-management.md

@@ -148,11 +148,20 @@ const isLoggedIn = await Odac.Auth.check()
 
 **Get user info:**
 ```javascript
-const user = Odac.Auth.user(null)  // Full user object
-const user = Odac.Auth.user(null)  // Full user object
-const email = Odac.Auth.user('email')  // Specific field
+const user = Odac.Auth.user()          // Full user object
+const email = Odac.Auth.user('email')  // Specific user field
 ```
 
+**Get auth session record:**
+```javascript
+const authRecord = Odac.Auth.token()       // Full token record from auth table
+const authId = Odac.Auth.token('id')       // Auth session ID
+const sessionIp = Odac.Auth.token('ip')    // IP address of the session
+const sessionDate = Odac.Auth.token('date') // When the session was created
+```
+
+> **Note:** `token()` returns `false` if no active session exists. It is populated after a successful `check()` call.
+
 ### Custom Session Data
 
 If you need to store your own data in the session (e.g. shopping cart ID, preferences), use the `Odac.session()` helper:

package/docs/backend/13-utilities/01-odac-var.md

@@ -8,9 +8,6 @@
 // Create a Var instance
 const result = Odac.Var('hello world').slug()
 // Returns: 'hello-world'
-
-// Chain multiple operations
-const email = Odac.Var('  USER@EXAMPLE.COM  ').trim().toLowerCase()
 ```
 
 ### String Validation
@@ -47,19 +44,20 @@ Odac.Var('example.com').isAny('email', 'domain')       // true
 'alphaspace'         // Letters and spaces
 'alphanumeric'       // Letters and numbers
 'alphanumericspace'  // Letters, numbers, and spaces
-'bcrypt'             // BCrypt hash format
+'username'           // Alphanumeric only (no spaces)
+'hash'               // scrypt hash format ($scrypt$)
 'date'               // Valid date string
 'domain'             // Valid domain name (example.com)
 'email'              // Valid email address
 'float'              // Floating point number
-'host'               // IP address
+'host'               // IP address / Host
 'ip'                 // IP address
 'json'               // Valid JSON string
 'mac'                // MAC address
-'md5'                // MD5 hash
+'md5'                // 32-char MD5 hash
 'numeric'            // Numbers only
-'url'                // Valid URL
-'emoji'              // Contains emoji
+'url'                // Valid URL (protocol + domain)
+'emoji'              // Contains emoji characters
 'xss'                // XSS-safe (no HTML tags)
 ```
 
@@ -193,21 +191,18 @@ Odac.Var('<script>alert("xss")</script>').html()
 
 ### Encryption & Hashing
 
-#### hash() - BCrypt password hashing
+#### hash() - Secure scrypt password hashing
 
 ```javascript
-// Hash a password
+// Hash a password using enterprise-grade scrypt
 const hashedPassword = Odac.Var('mypassword').hash()
-// Returns: '$2b$10$...' (BCrypt hash)
-
-// Custom salt rounds
-const hashedPassword = Odac.Var('mypassword').hash(12)
+// Returns: '$scrypt$[salt]$[hash]'
 ```
 
-#### hashCheck() - Verify BCrypt hash
+#### hashCheck() - Verify scrypt hash
 
 ```javascript
-const hashedPassword = '$2b$10$...'
+const hashedPassword = '$scrypt$...'
 const isValid = Odac.Var(hashedPassword).hashCheck('mypassword')
 // Returns: true or false
 ```
@@ -498,7 +493,6 @@ module.exports = async function(Odac) {
 
 ### Notes
 
-- `Odac.Var()` returns the processed string value, not a Var instance (except for chaining)
-- Encryption uses AES-256-CBC with a fixed IV
-- BCrypt hashing is one-way and cannot be decrypted
+- Encryption uses AES-256-CBC with a fixed IV (defined in framework core).
+- scrypt hashing is one-way and computationally expensive to prevent brute-force.
 - Date formatting works with any valid JavaScript date string

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

@@ -200,11 +200,24 @@ odac.form({
 ### Disable Specific Messages
 
 ```javascript
+// Only show error messages, suppress success messages
 odac.form({
   form: '#my-form',
-  messages: ['error']  // Only show errors, not success
+  messages: ['error']
 }, function(data) {
-  // Custom success handling
+  if (data.result.success) {
+    // Custom success handling
+  }
+})
+
+// Only show success messages, suppress error messages
+odac.form({
+  form: '#my-form',
+  messages: ['success']
+}, function(data) {
+  if (!data.result.success) {
+    // Custom error handling
+  }
 })
 ```
 

package/docs/index.json

@@ -255,7 +255,7 @@
       "title": "Authentication & Security",
       "children": [
         {
-          "file": "01-user-logins-with-authjs.md",
+          "file": "01-authentication-basics.md",
           "title": "User Authentication"
         },
         {

package/package.json

@@ -7,7 +7,7 @@
     "email": "mail@emre.red",
     "url": "https://emre.red"
   },
-  "version": "1.4.8",
+  "version": "1.4.10",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/src/Auth.js

@@ -4,6 +4,7 @@ const TOKEN_ROTATION_GRACE_PERIOD_MS = 60 * 1000
 class Auth {
   #request = null
   #table = null
+  #token = null
   #user = null
   static #migrationCache = new Set()
 
@@ -140,6 +141,8 @@ class Auth {
       this.#user = await Odac.DB[this.#table].where(primaryKey, sql_token[0].user).first()
       if (!this.#user) return false
 
+      this.#token = sql_token[0]
+
       let triggerRotation = false
       let isRecoveryRotation = false
 
@@ -434,6 +437,7 @@ class Auth {
     this.#request.cookie('odac_x', '', {'max-age': -1})
     this.#request.cookie('odac_y', '', {'max-age': -1})
 
+    this.#token = null
     this.#user = null
     return true
   }
@@ -713,6 +717,19 @@ class Auth {
     })
   }
 
+  /**
+   * Retrieves the active auth token record or a specific column from it.
+   * Why: To provide access to the current session's token metadata (e.g., auth ID, IP, date).
+   *
+   * @param {string|null} [col=null] - The column to retrieve, or null for the full token object.
+   * @returns {object|string|number|boolean|false} The token object, column value, or false if no active session.
+   */
+  token(col = null) {
+    if (!this.#token) return false
+    if (col === null) return this.#token
+    return this.#token[col]
+  }
+
   /**
    * Retrieves the authenticated user or a specific column.
    * Why: To provide access to the current user's session data securely.