odac 1.4.7 → 1.4.9

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 ### ⚙️ 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
+- **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

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.
@@ -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

@@ -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
@@ -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,30 +1,112 @@
 ---
 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 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, indexing, 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.
+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.  **Read Caching**: Use `cache()` for frequently-read, rarely-changed data.
+5.  **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
+```
+
+## 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)
@@ -43,7 +125,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 +224,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) | [read-through-cache user docs](../../../backend/08-database/06-read-through-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/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