odac 1.4.8 → 1.4.10

package/CHANGELOG.md

@@ -1,3 +1,46 @@
+### 🛠️ Fixes & Improvements
+
+- **cache:** preserve Knex chain for insert operations during invalidation
+- **database:** resolve duplicate error handler bug in insert cache invalidation
+- **migration:** add column type comparison to detect schema changes
+- **migration:** handle PostgreSQL primary key type changes safely
+- **migration:** preserve column nullable state when altering without explicit schema
+- **write-buffer:** auto-generate nanoid values for buffered inserts
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### ⚙️ Engine Tuning
+
+- migrate hashing from BCrypt to scrypt and update Odac.Var documentation and validation logic
+
+### ✨ What's New
+
+- **auth:** add token tracking and retrieval method
+- **database:** add read-through cache API for SELECT query results
+- **migration:** add cross-driver default value comparison
+- **migration:** add foreign key introspection and synchronization
+- **websocket:** add readyState tracking and message fragmentation support
+
+### 📚 Documentation
+
+- **forms:** add options to control message display for success and error handling
+- **migrations:** add foreign keys and referential actions documentation
+
+### 🛠️ Fixes & Improvements
+
+- **database:** add catch method to write operation thenable for Promise compatibility
+- **pr-review:** apply ReadCache null sentinel, fix invalidation test, correct auth docs login example
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### ✨ What's New
 
 - **database:** add Write-Behind Cache with counter, update, and batch insert buffering

package/docs/ai/README.md

@@ -34,7 +34,8 @@ Detailed instructions are organized into Backend and Frontend categories:
 - `backend/streaming.md`: Server-Sent Events (SSE) and Streaming API.
 - `backend/structure.md`: Project organization and Service Classes.
 - `backend/translations.md`: Multi-language support (i18n).
-- `backend/utilities.md`: Odac.Var (String Manipulation) and Flow Control.
+- `backend/odac-var.md`: Odac.Var (Fluent String Manipulation, Hashing, Encryption).
+- `backend/utilities.md`: Flow Control (abort, direct, session).
 - `backend/validation.md`: Input sanitization and security checks.
 - `backend/views.md`: Template syntax, skeletons, and server-side JS.
 

package/docs/ai/skills/SKILL.md

@@ -29,7 +29,8 @@ Read the specific rule files based on whether you are working on the Backend or
 - [backend/streaming.md](backend/streaming.md) - Server-Sent Events (SSE) and Streaming API
 - [backend/structure.md](backend/structure.md) - Project organization and Service Classes
 - [backend/translations.md](backend/translations.md) - Multi-language support (i18n)
-- [backend/utilities.md](backend/utilities.md) - Odac.Var (String Manipulation) and Flow Control
+- [backend/odac-var.md](backend/odac-var.md) - Odac.Var (Fluent String Manipulation, Hashing, Encryption)
+- [backend/utilities.md](backend/utilities.md) - Flow Control (abort, direct, session)
 - [backend/validation.md](backend/validation.md) - Input sanitization and security checks
 - [backend/views.md](backend/views.md) - Template syntax, skeletons, and server-side JS
 

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

@@ -19,21 +19,27 @@ ODAC provides built-in drivers for session handling (Memory/Redis) and multiple
 4.  **Magic Links**: Use `Odac.Auth.magic(email)` for passwordless flows.
 5.  **Token Rotation**: Enterprise-grade rotation is enabled by default. It uses a 60s grace period to prevent race conditions in SPAs.
 6.  **Persistence**: Cookies use the configured `maxAge` to persist beyond browser closure.
+7.  **Token Accessor**: Use `Odac.Auth.token()` to access the active auth session record (e.g., auth ID, IP, timestamps). Returns `false` if no active session.
+
 ## Reference Patterns
 
 ### 1. Standard Login & Check
 ```javascript
 // Check if user is logged in
-if (Odac.Auth.check()) {
-  const user = Odac.Auth.user();
-  const userId = Odac.Auth.id();
+if (await Odac.Auth.check()) {
+  const user = Odac.Auth.user()           // Full user object
+  const userId = Odac.Auth.user('id')     // Specific user field
+
+  const authRecord = Odac.Auth.token()    // Full auth token record
+  const authId = Odac.Auth.token('id')    // Auth session ID from token table
+  const authIp = Odac.Auth.token('ip')    // IP address of the session
 }
 
-// Log in a user manually
-await Odac.Auth.login(userId);
+// Log in a user
+await Odac.Auth.login({ email, password })
 
 // Log out
-await Odac.Auth.logout();
+await Odac.Auth.logout()
 ```
 
 ### 2. Magic Links (Passwordless)

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

@@ -1,19 +1,20 @@
 ---
 name: backend-database-skill
-description: High-performance ODAC database querying patterns including the Write-Behind Cache for counters, last-write-wins updates, and buffered batch inserts.
+description: High-performance ODAC database querying patterns including the Read-Through Cache for SELECT results and the Write-Behind Cache for counters, last-write-wins updates, and buffered batch inserts.
 metadata:
-  tags: backend, database, query-builder, sql, write-behind-cache, performance, security
+  tags: backend, database, query-builder, sql, read-through-cache, write-behind-cache, performance, security
 ---
 
 # Backend Database Skill
 
-High-performance database operations using the ODAC Query Builder and Write-Behind Cache.
+High-performance database operations using the ODAC Query Builder, Read-Through Cache, 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.
+4.  **Read Caching**: Use `cache()` for frequently-read, rarely-changed data.
+5.  **Write Coalescing**: Use `buffer` for high-frequency writes to avoid DB saturation.
 
 ## Query Builder Patterns
 ```javascript
@@ -29,6 +30,85 @@ await Odac.DB.users.where('id', 1).update({last_login: new Date()})
 const count = await Odac.DB.users.where('active', true).count() // → Number
 ```
 
+## Read-Through Cache (`cache`)
+
+The `cache()` API stores SELECT results in `Odac.Ipc` and serves subsequent requests from memory. Cache keys are SHA-256 hashes of the compiled SQL + bindings — identical queries always hit the same key.
+
+### When to suggest `cache`
+
+Propose the Read-Through Cache when the data meets **all three** of these criteria:
+1. **High read frequency** — the same query runs on many requests.
+2. **Low write frequency** — the data changes infrequently (minutes to hours between updates).
+3. **Not user-specific** — the same result is safe to serve to all users (no per-user filtering that could leak data).
+
+**Typical candidates:**
+- Blog posts, articles, product listings
+- Navigation menus, category trees, tag lists
+- Site settings, feature flags, configuration values
+- Public API responses that don't vary by user
+
+**Do NOT suggest `cache` for:**
+- Queries with user-specific WHERE clauses (data leakage risk)
+- Account balances, inventory counts, or anything requiring real-time accuracy
+- Queries inside transactions where consistency is critical
+
+### API
+
+```javascript
+// Cache with explicit TTL (seconds)
+const posts = await Odac.DB.posts.cache(60).where('active', true).select('id', 'title')
+
+// Cache with default TTL (from config, default 300s)
+const post = await Odac.DB.posts.cache().where({id: 5}).first()
+
+// Named connection
+const stats = await Odac.DB.analytics.events.cache(120).where('date', today).select()
+
+// Manual invalidation — table-level
+await Odac.DB.posts.cache.clear()
+
+// Global invalidation
+await Odac.DB.cache.clear('default', 'posts')
+```
+
+### Automatic Invalidation
+
+`insert()`, `update()`, `delete()`, `del()`, and `truncate()` automatically purge all cached queries for that table. No manual `.cache.clear()` needed after writes.
+
+```javascript
+// This update automatically clears all cached queries on 'posts'
+await Odac.DB.posts.where({id: 5}).update({title: 'New Title'})
+```
+
+**Cross-table (JOIN) invalidation:** When a cached query includes `JOIN` clauses, the cache key is registered in all joined tables' indexes. A write to any table involved in the query triggers invalidation automatically.
+
+```javascript
+// Cached in both 'posts' and 'users' indexes
+await Odac.DB.posts.cache(60).join('users', 'posts.user_id', '=', 'users.id').select(...)
+
+// Writing to 'users' invalidates the cached join query above
+await Odac.DB.users.where({id: 1}).update({name: 'New Name'})
+```
+
+> **`buffer` + `cache` interaction:** `buffer` writes are deferred and do NOT trigger automatic invalidation. Call `Odac.DB.posts.cache.clear()` after a `buffer.flush()` if the cache must reflect the latest state immediately.
+
+### Read-Through Cache — Key Rules
+1.  **Ipc-Backed**: Cache state goes through `Odac.Ipc`. Memory driver = Primary holds state; Redis driver = Redis holds state.
+2.  **Horizontally Scalable**: With Redis driver, all servers share the same cache. Invalidation on one server is immediately visible to all others.
+3.  **TTL is the safety net**: Even without explicit invalidation, cached data expires after TTL seconds.
+4.  **maxKeys guard**: Once `maxKeys` is reached for a table, new entries are skipped — existing cache still served. Prevents unbounded memory growth.
+5.  **Ipc-safe**: If `Odac.Ipc` is not initialized (e.g., in isolated test environments), invalidation is a no-op — never throws.
+
+## Configuration (`odac.json`)
+```json
+{
+  "cache": {
+    "ttl": 300,
+    "maxKeys": 10000
+  }
+}
+```
+
 ## ID Strategy (NanoID)
 1.  **Schema-Driven**: Define string IDs with `type: 'nanoid'` in `schema/*.js`.
 2.  **Auto Generation**: On `insert()`, ODAC auto-generates missing nanoid fields.
@@ -144,4 +224,4 @@ await Odac.DB.buffer.flush()         // flush everything
 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) | [write-behind-cache user docs](../../../backend/08-database/05-write-behind-cache.md)
+See: [migrations.md](./migrations.md) | [write-behind-cache user docs](../../../backend/08-database/05-write-behind-cache.md) | [read-through-cache user docs](../../../backend/08-database/06-read-through-cache.md)

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

@@ -45,6 +45,29 @@ module.exports = {
 }
 ```
 
+### 2. Foreign Keys & Referential Actions
+```javascript
+// schema/posts.js
+module.exports = {
+  columns: {
+    id:      {type: 'nanoid', primary: true},
+    user_id: {
+      type:       'integer',
+      unsigned:   true,
+      nullable:   false,
+      references: {table: 'users', column: 'id'},
+      onDelete:   'CASCADE',  // 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION' | 'SET DEFAULT'
+      onUpdate:   'CASCADE'
+    }
+  }
+}
+```
+
+**Rules:**
+- `references` + `onDelete`/`onUpdate` are supported in table creation, column addition, and schema-diff updates to existing columns.
+- Schema diff supports adding, dropping, and replacing an existing column's foreign key constraint. Use an imperative `migration/` file only for cases that require custom data movement or engine-specific manual SQL.
+- Always index foreign key columns for query performance.
+
 ### NanoID Notes
 - `length` can be customized: `{type: 'nanoid', length: 12, primary: true}`.
 - If seed rows omit the nanoid field, ODAC fills it automatically.

package/docs/ai/skills/backend/odac-var.md

@@ -0,0 +1,155 @@
+---
+name: backend-odac-var-skill
+description: Comprehensive API reference and practical patterns for the Odac.Var utility class. Includes every single method available in src/Var.js.
+metadata:
+  tags: backend, utilities, strings, hashing, encryption, validation, mapping
+---
+
+# Backend Odac.Var API Reference
+
+`Odac.Var` is a high-performance utility class for string manipulation, security, and validation.
+
+## Core Principles
+- **Direct Output**: Manipulation methods return raw values (string/object). Chaining is NOT supported.
+- **Type Safety**: Methods handle various input types (strings, arrays, objects) gracefully.
+- **Enterprise Security**: Uses scrypt for hashing and AES-256-CBC for encryption.
+
+---
+
+## 🛠 Full Method List & API Reference
+
+### 1. `.clear(...args)`
+Removes specified strings from the value using global regex.
+```javascript
+Odac.Var('a-b-c').clear('-'); // 'abc'
+Odac.Var('hello123world').clear('1', '2', '3'); // 'helloworld'
+```
+
+### 2. `.contains(...args)`
+Checks if the string contains **all** of the specified values (AND logic).
+```javascript
+Odac.Var('hello world').contains('hello', 'world'); // true
+```
+
+### 3. `.containsAny(...args)`
+Checks if the string contains **any** of the specified values (OR logic).
+```javascript
+Odac.Var('hello world').containsAny('foo', 'world'); // true
+```
+
+### 4. `.date(format)`
+Formats a date string/timestamp. Default: `Y-m-d H:i:s`.
+- Tokens: `Y` (2024), `y` (24), `m` (01-12), `d` (01-31), `H` (00-23), `i` (00-59), `s` (00-59).
+```javascript
+Odac.Var('2024-04-10').date('d/m/Y'); // '10/04/2024'
+```
+
+### 5. `.encrypt(key?)`
+Encrypts the value using AES-256-CBC. Uses `Odac.Config.encrypt.key` by default. Returns Base64.
+```javascript
+const secret = Odac.Var('data').encrypt();
+```
+
+### 6. `.decrypt(key?)`
+Decrypts an AES-256-CBC Base64 string.
+```javascript
+const data = Odac.Var(secret).decrypt();
+```
+
+### 7. `.hash()`
+Generates a secure **scrypt** hash. Returns string prefixed with `$scrypt$`.
+```javascript
+const hash = Odac.Var('password').hash();
+```
+
+### 8. `.hashCheck(check)`
+Verifies a plain text string against an existing scrypt hash. Uses `timingSafeEqual`.
+```javascript
+Odac.Var(hash).hashCheck('password'); // true
+```
+
+### 9. `.html()`
+Escapes HTML special characters (`&`, `<`, `>`, `"`, `'`).
+```javascript
+Odac.Var('<div>').html(); // '&lt;div&gt;'
+```
+
+### 10. `.is(...args)`
+Validates string against **all** specified rules (AND logic).
+```javascript
+Odac.Var('test@test.com').is('email'); // true
+```
+
+### 11. `.isAny(...args)`
+Validates string against **any** specified rule (OR logic).
+```javascript
+Odac.Var('user123').isAny('email', 'username'); // true
+```
+
+### 12. `.isBegin(...args)`
+Checks if string starts with any of the specified values.
+```javascript
+Odac.Var('https://odac.run').isBegin('http', 'https'); // true
+```
+
+### 13. `.isEnd(...args)`
+Checks if string ends with any of the specified values.
+```javascript
+Odac.Var('image.png').isEnd('.png', '.jpg'); // true
+```
+
+### 14. `.md5()`
+Generates an MD5 hash of the value.
+```javascript
+Odac.Var('hello').md5(); // '5d41402...'
+```
+
+### 15. `.replace(...args)`
+Replaces values in the string. If the Var value is an object/array, it applies replacement recursively.
+```javascript
+// String replacement
+Odac.Var('Hello {{n}}').replace('{{n}}', 'Emre'); 
+
+// Bulk replacement
+Odac.Var('{{a}} {{b}}').replace({ '{{a}}': '1', '{{b}}': '2' });
+
+// Recursive object replacement
+Odac.Var({ key: '{{v}}' }).replace('{{v}}', 'data'); // { key: 'data' }
+```
+
+### 16. `.save(path)`
+Saves the value to a file. **Auto-creates directories** recursively if they don't exist.
+```javascript
+Odac.Var('content').save('./storage/logs/app.log');
+```
+
+### 17. `.slug(separator = '-')`
+Generates a URL-friendly slug. Replaces non-alphanumeric chars with separator.
+```javascript
+Odac.Var('Hello World!').slug(); // 'hello-world'
+```
+
+### 18. `.format(format)`
+Formats a string based on a pattern.
+- `?`: Placeholder for a single character from the input.
+- `*`: Placeholder for the remaining part of the input.
+```javascript
+Odac.Var('12345').format('??-???'); // '12-345'
+Odac.Var('TR12345').format('?? *'); // 'TR 12345'
+```
+
+---
+
+## 🔍 Validation Rule Catalog (for `.is()` and `.isAny()`)
+- `alpha`, `alphaspace`: `A-Z, a-z` (+ spaces).
+- `alphanumeric`, `alphanumericspace`: `A-Z, a-z, 0-9` (+ spaces).
+- `username`: `A-Z, a-z, 0-9` (Strictly alphanumeric).
+- `numeric`, `float`: Numbers and decimals.
+- `email`, `domain`, `url`: Standard web identifiers.
+- `ip`, `host`, `mac`: Networking addresses.
+- `json`: Check if value is valid JSON.
+- `date`: Check if value is a valid date string.
+- `hash`: Check if value follows `$scrypt$` hash format.
+- `xss`: Check if value is free of HTML tags.
+- `emoji`: Detect presence of emojis.
+- `md5`: Check for 32-char hex string.

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

@@ -21,7 +21,7 @@ String manipulation, hashing, and flow control.
 ```javascript
 const slug = Odac.Var('My Post Title').slug();
 const isValid = Odac.Var('test@test.com').is('email');
-const password = Odac.Var('secret').hash(); // BCrypt
+const password = Odac.Var('secret').hash(); // scrypt
 ```
 
 ### 2. Redirect and Abort

package/docs/ai/skills/frontend/forms.md

@@ -42,7 +42,29 @@ Odac.form(
   }
 )
 
-// 5) Manual GET request helper
+// 5) Disable all automatic messages and handle everything in the callback
+Odac.form(
+  {form: 'form[data-odac-form]', messages: false},
+  response => {
+    if (response?.result?.success) {
+      // Custom success: e.g. show a toast, update UI
+    } else if (response?.errors) {
+      // Custom error: manually map errors to DOM
+    }
+  }
+)
+
+// 6) Only show success messages, handle errors manually
+Odac.form(
+  {form: 'form[data-odac-form]', messages: ['success']},
+  response => {
+    if (!response?.result?.success && response?.errors) {
+      // Custom error handling
+    }
+  }
+)
+
+// 7) Manual GET request helper
 Odac.get('/api/status', data => {
   const status = document.querySelector('[data-api-status]')
   if (status) status.textContent = String(data?.status ?? '')

package/docs/backend/04-routing/09-websocket-quick-reference.md

@@ -31,6 +31,7 @@ Odac.Route.ws('/path', Odac => {
 | Property | Description |
 |----------|-------------|
 | `Odac.ws.id` | Unique client ID |
+| `Odac.ws.readyState` | RFC 6455 state: `0` CONNECTING, `1` OPEN, `2` CLOSING, `3` CLOSED |
 | `Odac.ws.rooms` | Array of joined rooms |
 | `Odac.ws.data` | Custom data storage |
 
@@ -169,14 +170,33 @@ const ws = Odac.ws('/chat', {shared: true})
 |------|-------------|
 | `1000` | Normal closure |
 | `1001` | Going away |
-| `1002` | Protocol error |
+| `1002` | Protocol error (e.g. unexpected continuation frame) |
 | `1003` | Unsupported data |
 | `1006` | Abnormal closure |
+| `1008` | Rate limit exceeded |
+| `1009` | Payload too large |
 | `4000` | Middleware rejected |
 | `4001` | Unauthorized |
 | `4002` | Invalid/missing token |
 | `4003` | Forbidden (middleware) |
 
+## readyState Constants
+
+| Value | Constant | Description |
+|-------|----------|-------------|
+| `0` | `CONNECTING` | Handshake done, handler not yet invoked |
+| `1` | `OPEN` | Active — messages can be sent/received |
+| `2` | `CLOSING` | Close frame sent, draining |
+| `3` | `CLOSED` | Fully terminated |
+
+```javascript
+const {READY_STATE} = require('odac')
+
+if (Odac.ws.readyState === READY_STATE.OPEN) {
+  Odac.ws.send({status: 'alive'})
+}
+```
+
 ## Best Practices
 
 1. **Always handle authentication**

package/docs/backend/04-routing/09-websocket.md

@@ -97,9 +97,30 @@ Odac.ws.on('error', err => {})     // Error occurred
 ### Connection Management
 
 ```javascript
-Odac.ws.close()           // Close connection
+Odac.ws.close()           // Close connection (sends close frame, transitions to CLOSED)
 Odac.ws.ping()            // Send ping frame
 Odac.ws.id                // Unique client ID
+Odac.ws.readyState        // Current connection state (0–3)
+```
+
+### Connection State
+
+`Odac.ws.readyState` reflects the RFC 6455 lifecycle. Use the static constants on `WebSocketClient` or the exported `READY_STATE` enum for readable comparisons:
+
+| Value | Constant | Description |
+|-------|----------|-------------|
+| `0` | `CONNECTING` | Handshake complete, handler not yet called |
+| `1` | `OPEN` | Connection active, messages can be sent |
+| `2` | `CLOSING` | Close frame sent, waiting for socket drain |
+| `3` | `CLOSED` | Connection fully terminated |
+
+```javascript
+const {READY_STATE} = require('odac')
+
+Odac.ws.on('message', data => {
+  if (Odac.ws.readyState !== READY_STATE.OPEN) return
+  Odac.ws.send({echo: data})
+})
 ```
 
 ## Rooms