odac 1.4.7 → 1.4.9

package/docs/backend/13-utilities/02-ipc.md

@@ -71,3 +71,120 @@ await Odac.Ipc.publish('chat:global', { user: 'Emre', text: 'Hello World' });
 
 > [!TIP]
 > When using `memory` driver, the subscription listener is registered in the current worker. When a message is published, it goes to the Main process and is then broadcasted to all subscribed workers.
+
+### Atomic Counters
+
+Use `incrBy` / `decrBy` to atomically increment or decrement a numeric key. These are safe to call from multiple workers simultaneously — no read-then-write race conditions.
+
+```javascript
+// Increment by 1 — returns new value
+await Odac.Ipc.incrBy('page:views', 1)   // → 1
+await Odac.Ipc.incrBy('page:views', 5)   // → 6
+
+// Decrement
+await Odac.Ipc.decrBy('page:views', 2)   // → 4
+
+// Read the result
+const views = await Odac.Ipc.get('page:views')  // → 4
+```
+
+> [!NOTE]
+> Keys that don't exist yet are initialised to `0` before the operation.
+
+---
+
+### Hash Maps
+
+Store and retrieve structured per-key data. Fields are merged on every `hset` call — existing fields not mentioned in the call are preserved.
+
+```javascript
+// Set fields (merged, not overwritten)
+await Odac.Ipc.hset('user:42', {active_date: new Date(), last_ip: '1.2.3.4'})
+await Odac.Ipc.hset('user:42', {score: 100})
+
+// Retrieve all fields
+const data = await Odac.Ipc.hgetall('user:42')
+// → {active_date: ..., last_ip: '1.2.3.4', score: 100}
+```
+
+---
+
+### Lists
+
+Append items to a shared list and read them back in order. Useful for queues and event streams.
+
+```javascript
+// Append items to the right — returns new list length
+await Odac.Ipc.rpush('jobs', {type: 'email', to: 'a@b.com'})
+await Odac.Ipc.rpush('jobs', {type: 'sms'}, {type: 'push'})  // → 3
+
+// Read a range (0-indexed, -1 = last item)
+const pending = await Odac.Ipc.lrange('jobs', 0, -1)
+```
+
+---
+
+### Sets
+
+Maintain a collection of unique string members.
+
+```javascript
+// Add members
+await Odac.Ipc.sadd('online', 'user:1', 'user:2', 'user:3')
+
+// List all members
+const online = await Odac.Ipc.smembers('online')  // → ['user:1', 'user:2', 'user:3']
+
+// Remove members — returns number of members actually removed
+await Odac.Ipc.srem('online', 'user:2')
+```
+
+---
+
+### Distributed Locks
+
+Acquire a mutex across all workers and servers before entering a critical section. The TTL prevents deadlocks if a process crashes while holding the lock.
+
+```javascript
+// Attempt to acquire the lock (TTL in seconds)
+const acquired = await Odac.Ipc.lock('report:generate', 30)
+
+if (!acquired) {
+  // Another process is already running this — skip
+  return
+}
+
+try {
+  // Critical section — only one process runs this at a time
+  await generateReport()
+} finally {
+  // Always release, even on error
+  await Odac.Ipc.unlock('report:generate')
+}
+```
+
+> [!TIP]
+> With the `redis` driver, locks work across multiple servers — making them true distributed locks.
+
+---
+
+## Method Reference
+
+| Method | Description |
+|---|---|
+| `set(key, value, ttl?)` | Store a value, with optional TTL in seconds |
+| `get(key)` | Retrieve a value |
+| `del(key)` | Delete a key |
+| `incrBy(key, delta)` | Atomically increment a numeric key |
+| `decrBy(key, delta)` | Atomically decrement a numeric key |
+| `hset(key, fields)` | Merge fields into a hash map |
+| `hgetall(key)` | Retrieve all fields of a hash map |
+| `rpush(key, ...items)` | Append items to a list |
+| `lrange(key, start, stop)` | Read a range of list items |
+| `sadd(key, ...members)` | Add members to a set |
+| `smembers(key)` | Get all members of a set |
+| `srem(key, ...members)` | Remove members from a set |
+| `lock(key, ttl)` | Acquire a mutex lock |
+| `unlock(key)` | Release a mutex lock |
+| `subscribe(channel, handler)` | Subscribe to a Pub/Sub channel |
+| `publish(channel, message)` | Publish a message to a channel |

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.7",
+  "version": "1.4.9",
   "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.

package/src/Database/Migration.js

@@ -148,7 +148,8 @@ class Migration {
       } else {
         const currentColumns = await this._introspectColumns(knex, tableName)
         const currentIndexes = await this._introspectIndexes(knex, tableName)
-        const diff = this._computeDiff(desired, currentColumns, currentIndexes)
+        const currentForeignKeys = await this._introspectForeignKeys(knex, tableName)
+        const diff = this._computeDiff(desired, currentColumns, currentIndexes, currentForeignKeys)
 
         if (diff.length > 0) {
           operations.push(...diff.map(d => ({...d, table: tableName})))
@@ -379,6 +380,91 @@ class Migration {
     return result
   }
 
+  // ---------------------------------------------------------------------------
+  // FOREIGN KEY INTROSPECTION
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Introspects existing foreign key constraints for a given table.
+   * Why: The diff engine needs current FK state to detect when a schema adds, changes,
+   * or removes a `references` / `onDelete` / `onUpdate` definition on an existing column.
+   * @param {object} knex - Knex instance
+   * @param {string} tableName - Table to introspect
+   * @returns {Promise<Object>} Map of columnName -> {table, column, onDelete, onUpdate}
+   */
+  async _introspectForeignKeys(knex, tableName) {
+    const client = knex.client.config.client
+    const fks = {}
+
+    if (client === 'pg') {
+      const result = await knex.raw(
+        `SELECT
+           kcu.column_name,
+           ccu.table_name  AS foreign_table,
+           ccu.column_name AS foreign_column,
+           rc.delete_rule,
+           rc.update_rule,
+           tc.constraint_name
+         FROM information_schema.table_constraints tc
+         JOIN information_schema.key_column_usage kcu
+           ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+         JOIN information_schema.constraint_column_usage ccu
+           ON tc.constraint_name = ccu.constraint_name AND tc.table_schema = ccu.table_schema
+         JOIN information_schema.referential_constraints rc
+           ON tc.constraint_name = rc.constraint_name AND tc.table_schema = rc.constraint_schema
+         WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = ?`,
+        [tableName]
+      )
+      for (const row of result.rows) {
+        fks[row.column_name] = {
+          table: row.foreign_table,
+          column: row.foreign_column,
+          onDelete: (row.delete_rule || 'NO ACTION').toUpperCase(),
+          onUpdate: (row.update_rule || 'NO ACTION').toUpperCase(),
+          constraintName: row.constraint_name
+        }
+      }
+    } else if (client === 'mysql2' || client === 'mysql') {
+      const [rows] = await knex.raw(
+        `SELECT
+           kcu.COLUMN_NAME          AS column_name,
+           kcu.REFERENCED_TABLE_NAME AS foreign_table,
+           kcu.REFERENCED_COLUMN_NAME AS foreign_column,
+           rc.DELETE_RULE            AS delete_rule,
+           rc.UPDATE_RULE            AS update_rule,
+           kcu.CONSTRAINT_NAME       AS constraint_name
+         FROM information_schema.KEY_COLUMN_USAGE kcu
+         JOIN information_schema.REFERENTIAL_CONSTRAINTS rc
+           ON kcu.CONSTRAINT_NAME = rc.CONSTRAINT_NAME AND kcu.TABLE_SCHEMA = rc.CONSTRAINT_SCHEMA
+         WHERE kcu.TABLE_SCHEMA = DATABASE() AND kcu.TABLE_NAME = ? AND kcu.REFERENCED_TABLE_NAME IS NOT NULL`,
+        [tableName]
+      )
+      for (const row of rows) {
+        fks[row.column_name] = {
+          table: row.foreign_table,
+          column: row.foreign_column,
+          onDelete: (row.delete_rule || 'NO ACTION').toUpperCase(),
+          onUpdate: (row.update_rule || 'NO ACTION').toUpperCase(),
+          constraintName: row.constraint_name
+        }
+      }
+    } else if (client === 'sqlite3') {
+      const result = await knex.raw(`PRAGMA foreign_key_list('${tableName}')`)
+      const rows = Array.isArray(result) ? result : []
+      for (const row of rows) {
+        fks[row.from] = {
+          table: row.table,
+          column: row.to,
+          onDelete: (row.on_delete || 'NO ACTION').toUpperCase(),
+          onUpdate: (row.on_update || 'NO ACTION').toUpperCase(),
+          constraintName: null
+        }
+      }
+    }
+
+    return fks
+  }
+
   // ---------------------------------------------------------------------------
   // DIFF ENGINE — Compute desired vs current delta
   // ---------------------------------------------------------------------------
@@ -391,7 +477,7 @@ class Migration {
    * @param {Array} currentIndexes - Introspected index list
    * @returns {Array} Ordered list of diff operations
    */
-  _computeDiff(desired, currentColumns, currentIndexes) {
+  _computeDiff(desired, currentColumns, currentIndexes, currentForeignKeys = {}) {
     const ops = []
     const desiredColumns = desired.columns || {}
     const desiredIndexes = desired.indexes || []
@@ -442,6 +528,34 @@ class Migration {
       }
     }
 
+    // --- Foreign key synchronization ---
+    for (const [colName, colDef] of Object.entries(desiredColumns)) {
+      if (colDef.type === 'timestamps') continue
+      if (!currentColumns[colName]) continue // New column — _addColumn handles FK
+
+      const desiredRef = colDef.references || null
+      const currentFK = currentForeignKeys[colName] || null
+      const desiredOnDelete = (colDef.onDelete || 'NO ACTION').toUpperCase()
+      const desiredOnUpdate = (colDef.onUpdate || 'NO ACTION').toUpperCase()
+
+      if (desiredRef && !currentFK) {
+        // FK added to existing column
+        ops.push({type: 'add_foreign_key', column: colName, definition: colDef})
+      } else if (!desiredRef && currentFK) {
+        // FK removed from schema
+        ops.push({type: 'drop_foreign_key', column: colName, constraintName: currentFK.constraintName})
+      } else if (desiredRef && currentFK) {
+        // FK exists — check if target table/column or actions changed
+        const targetChanged = desiredRef.table !== currentFK.table || desiredRef.column !== currentFK.column
+        const actionChanged = desiredOnDelete !== currentFK.onDelete || desiredOnUpdate !== currentFK.onUpdate
+
+        if (targetChanged || actionChanged) {
+          ops.push({type: 'drop_foreign_key', column: colName, constraintName: currentFK.constraintName})
+          ops.push({type: 'add_foreign_key', column: colName, definition: colDef})
+        }
+      }
+    }
+
     // --- Index synchronization ---
     const desiredIndexSignatures = new Set(desiredIndexes.map(idx => this._indexSignature(idx)))
     const currentIndexSignatures = new Set(currentIndexes.map(idx => this._indexSignature(idx)))
@@ -481,9 +595,41 @@ class Migration {
     // drivers (SQLite) return maxLength as a string, e.g. '100' vs 100.
     if (desired.length && current.maxLength && Number(desired.length) !== Number(current.maxLength)) return true
 
+    // Default value mismatch — normalize both sides before comparing because
+    // drivers return defaults as strings (e.g. "'active'" in PG, "active" in SQLite).
+    const desiredDefault = desired.default !== undefined ? this._normalizeDefaultValue(desired.default) : null
+    const currentDefault =
+      current.defaultValue !== undefined && current.defaultValue !== null ? this._normalizeDefaultValue(current.defaultValue) : null
+
+    if (desiredDefault !== currentDefault) return true
+
     return false
   }
 
+  /**
+   * Normalizes a column default value to a canonical string for cross-driver comparison.
+   * Why: Each DB driver serializes defaults differently — PG wraps strings in single quotes
+   * and appends type casts (e.g. `'active'::character varying`), SQLite returns raw values,
+   * MySQL returns unquoted strings. Stripping quotes and casts gives a stable comparison key.
+   * @param {*} value - Raw default value from schema definition or DB introspection
+   * @returns {string} Normalized string representation
+   */
+  _normalizeDefaultValue(value) {
+    if (value === null || value === undefined) return 'null'
+
+    let str = String(value)
+
+    // Strip PG type cast suffix: 'foo'::character varying → 'foo'
+    str = str.replace(/::[\w\s]+$/, '')
+
+    // Strip surrounding single quotes added by PG/MySQL: 'foo' → foo
+    if (str.startsWith("'") && str.endsWith("'")) {
+      str = str.slice(1, -1)
+    }
+
+    return str.trim().toLowerCase()
+  }
+
   /**
    * Generates a deterministic signature for an index to enable set comparison.
    * @param {object} idx - Index definition {columns, unique}
@@ -538,6 +684,7 @@ class Migration {
   async _applyDiff(knex, tableName, diff) {
     const columnOps = diff.filter(op => op.type === 'add_column' || op.type === 'drop_column' || op.type === 'alter_column')
     const indexOps = diff.filter(op => op.type === 'add_index' || op.type === 'drop_index')
+    const fkOps = diff.filter(op => op.type === 'add_foreign_key' || op.type === 'drop_foreign_key')
 
     // Phase 1: Column operations — atomic batch
     if (columnOps.length > 0) {
@@ -558,7 +705,19 @@ class Migration {
       })
     }
 
-    // Phase 2: Index operations — each applied individually for idempotent safety
+    // Phase 2: Foreign key operations — drop before add to handle replacements
+    for (const op of fkOps) {
+      if (op.type === 'drop_foreign_key') {
+        await this._applyForeignKeyOp(knex, tableName, op)
+      }
+    }
+    for (const op of fkOps) {
+      if (op.type === 'add_foreign_key') {
+        await this._applyForeignKeyOp(knex, tableName, op)
+      }
+    }
+
+    // Phase 3: Index operations — each applied individually for idempotent safety
     for (const op of indexOps) {
       await this._applyIndexOp(knex, tableName, op)
     }
@@ -606,6 +765,63 @@ class Migration {
     }
   }
 
+  /**
+   * Applies a single foreign key add/drop operation with idempotent error handling.
+   * Why: Knex's col.alter() cannot manage FK constraints — they require table-level
+   * alterTable calls (add .foreign() / drop .dropForeign()) which are separate from column ops.
+   * @param {object} knex - Knex instance
+   * @param {string} tableName - Target table
+   * @param {object} op - FK operation {type, column, definition?, constraintName?}
+   */
+  async _applyForeignKeyOp(knex, tableName, op) {
+    try {
+      if (op.type === 'add_foreign_key') {
+        const ref = op.definition.references
+
+        // Clean orphan rows before adding constraint — existing data may reference
+        // rows that no longer exist in the parent table, which would cause PG error 23503.
+        // Nullable columns get SET NULL safely. Non-nullable columns are NOT deleted —
+        // instead the constraint is skipped with a warning to prevent silent data loss.
+        const orphanCondition = knex(tableName).whereNotIn(op.column, knex(ref.table).select(ref.column)).whereNotNull(op.column)
+
+        if (op.definition.nullable !== false) {
+          await orphanCondition.update({[op.column]: null})
+        } else {
+          const [{count: orphanCount}] = await orphanCondition.clone().count('* as count')
+
+          if (Number(orphanCount) > 0) {
+            console.error(
+              `\x1b[31m[ODAC Migration]\x1b[0m Skipping foreign key on "${tableName}.${op.column}" → ` +
+                `"${ref.table}.${ref.column}": ${orphanCount} orphan row(s) found. ` +
+                `Column is NOT NULL so rows cannot be nullified. ` +
+                `Clean the data manually and restart, or make the column nullable.`
+            )
+            return
+          }
+        }
+
+        await knex.schema.alterTable(tableName, table => {
+          const fk = table.foreign(op.column).references(ref.column).inTable(ref.table)
+          if (op.definition.onDelete) fk.onDelete(op.definition.onDelete)
+          if (op.definition.onUpdate) fk.onUpdate(op.definition.onUpdate)
+        })
+      } else if (op.type === 'drop_foreign_key') {
+        await knex.schema.alterTable(tableName, table => {
+          table.dropForeign(op.column)
+        })
+      }
+    } catch (e) {
+      const isDuplicate = e.message && (e.message.includes('already exists') || e.code === '42710')
+      const isNotFound = e.message && (e.message.includes('does not exist') || e.code === '42704')
+
+      if ((op.type === 'add_foreign_key' && isDuplicate) || (op.type === 'drop_foreign_key' && isNotFound)) {
+        return
+      }
+
+      throw e
+    }
+  }
+
   /**
    * Translates schema column definitions into Knex schema builder calls.
    * Supports all common column types with their modifiers.

package/src/Database/ReadCache.js

@@ -0,0 +1,174 @@
+'use strict'
+const nodeCrypto = require('node:crypto')
+
+/**
+ * Read-Through Cache for ODAC Database layer.
+ *
+ * Why: Frequently-read, rarely-changed data (blog posts, settings, categories)
+ * generates redundant DB queries across workers. This module caches SELECT results
+ * via the Ipc layer, providing O(1) reads after the first query.
+ *
+ * Architecture: Fully delegated to Odac.Ipc for state management (same as WriteBuffer).
+ * - Memory driver: Primary process holds cached data in Maps via cluster IPC.
+ * - Redis driver: All state lives in Redis — works across horizontal load balancers.
+ * - Both drivers: TTL-based expiration + automatic invalidation on write operations.
+ *
+ * Key namespaces in Ipc:
+ *   rc:{connection}:{table}:{queryHash}   — cached query result (Ipc.set/get with TTL)
+ *   rc:idx:{connection}:{table}           — set of active cache keys for bulk invalidation
+ *
+ * API (exposed via Database.js proxy):
+ *   Odac.DB.posts.cache(60).where({active: true}).select('id', 'title')  — TTL cache
+ *   Odac.DB.posts.cache().where({id: 5}).first()                         — default TTL
+ *   Odac.DB.posts.cache.clear()                                          — table invalidation
+ *   Odac.DB.posts.cache.clear({id: 5})                                   — targeted invalidation
+ *
+ * Automatic invalidation:
+ *   insert/update/delete on a table → all cached queries for that table are purged.
+ */
+
+const DEFAULT_CONFIG = {
+  ttl: 300,
+  maxKeys: 10000
+}
+
+class ReadCache {
+  constructor() {
+    this._config = {}
+  }
+
+  /**
+   * Why: Merges user config with sensible defaults. Called from Database.init().
+   * No timers or background processes — cache is purely reactive (read-through + TTL).
+   */
+  init() {
+    this._config = {...DEFAULT_CONFIG, ...Odac.Config.cache}
+  }
+
+  /**
+   * Why: Generates a deterministic cache key from the Knex query builder's compiled SQL + bindings.
+   * SHA-256 ensures fixed-length keys regardless of query complexity.
+   * Sorting bindings is unnecessary — Knex preserves parameter order deterministically.
+   *
+   * @param {string} connection - Connection key (e.g., 'default', 'analytics')
+   * @param {string} table - Table name
+   * @param {object} queryBuilder - Knex query builder instance
+   * @returns {string} Cache key in format rc:{connection}:{table}:{hash}
+   */
+  buildKey(connection, table, queryBuilder) {
+    const {sql, bindings} = queryBuilder.toSQL()
+    const hash = nodeCrypto
+      .createHash('sha256')
+      .update(`${sql}:${JSON.stringify(bindings)}`)
+      .digest('hex')
+    return `rc:${connection}:${table}:${hash}`
+  }
+
+  /**
+   * Why: Core read-through logic. Returns cached result on HIT, executes query on MISS.
+   * TTL ensures eventual consistency even without explicit invalidation.
+   *
+   * @param {string} connection - Connection key
+   * @param {string} table - Table name
+   * @param {object} queryBuilder - Knex query builder (used for key generation via .toSQL())
+   * @param {function} executeFn - Callback that executes the original DB query (avoids .then() recursion)
+   * @param {number} ttl - Time-to-live in seconds
+   * @returns {Promise<*>} Query result (from cache or DB)
+   */
+  async get(connection, table, queryBuilder, executeFn, ttl) {
+    const effectiveTtl = ttl || this._config.ttl
+    const cacheKey = this.buildKey(connection, table, queryBuilder)
+
+    // O(1) cache lookup via Ipc — sentinel envelope {__v} distinguishes "cached null" from MISS
+    const cached = await Odac.Ipc.get(cacheKey)
+    if (cached !== null && typeof cached === 'object' && '__v' in cached) return cached.__v
+
+    // MISS — execute the actual DB query via the original (unwrapped) .then()
+    const result = await executeFn()
+
+    // Guard against exceeding maxKeys to prevent unbounded memory growth
+    const indexKey = `rc:idx:${connection}:${table}`
+    const currentKeys = await Odac.Ipc.smembers(indexKey)
+
+    if (currentKeys.length < this._config.maxKeys) {
+      await Odac.Ipc.set(cacheKey, {__v: result}, effectiveTtl)
+      await Odac.Ipc.sadd(indexKey, cacheKey)
+
+      // Cross-table invalidation: register cache key in joined tables' indexes too.
+      // Why: A query like posts.join('users').cache().select() must be invalidated
+      // when EITHER posts OR users is written to. Without this, a users.insert()
+      // would leave stale joined data in the posts cache.
+      const joinedTables = this._extractJoinedTables(queryBuilder)
+      for (const joinedTable of joinedTables) {
+        await Odac.Ipc.sadd(`rc:idx:${connection}:${joinedTable}`, cacheKey)
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Why: Purges all cached queries for a specific table. Called automatically on
+   * insert/update/delete via Database.js proxy intercept.
+   * Table-level granularity is intentional — row-level invalidation would require
+   * parsing WHERE clauses of cached queries, which is O(n) and error-prone.
+   *
+   * @param {string} connection - Connection key
+   * @param {string} table - Table name
+   * @returns {Promise<void>}
+   */
+  async invalidate(connection, table) {
+    if (!global.Odac?.Ipc) return
+
+    const indexKey = `rc:idx:${connection}:${table}`
+    const keys = await Odac.Ipc.smembers(indexKey)
+
+    if (keys.length === 0) return
+
+    // Delete all cached entries in parallel
+    await Promise.all(keys.map(key => Odac.Ipc.del(key)))
+    await Odac.Ipc.del(indexKey)
+  }
+
+  /**
+   * Why: Extracts table names from JOIN clauses in a Knex query builder.
+   * Used to register cache keys in joined tables' indexes for cross-table invalidation.
+   * Parses Knex's internal _statements array — entries with a joinType property
+   * contain the joined table name. Handles aliased tables (e.g., 'users as u' → 'users').
+   *
+   * @param {object} queryBuilder - Knex query builder instance
+   * @returns {string[]} Array of joined table names (deduplicated)
+   */
+  _extractJoinedTables(queryBuilder) {
+    const statements = queryBuilder._statements
+    if (!statements || !Array.isArray(statements)) return []
+
+    const tables = new Set()
+    for (const stmt of statements) {
+      if (!stmt.joinType || !stmt.table) continue
+      // Handle aliased tables: 'users as u' → 'users'
+      const tableName = String(stmt.table)
+        .split(/\s+as\s+/i)[0]
+        .trim()
+      if (tableName) tables.add(tableName)
+    }
+    return [...tables]
+  }
+
+  /**
+   * Why: Targeted invalidation — clears cache entries whose query hash matches
+   * a specific WHERE condition. Falls back to full table invalidation since
+   * precise row-level matching against arbitrary cached SQL is not feasible.
+   * Exposed as Odac.DB.posts.cache.clear({id: 5}) for semantic clarity,
+   * but internally equivalent to table-level purge.
+   *
+   * @param {string} connection - Connection key
+   * @param {string} table - Table name
+   * @returns {Promise<void>}
+   */
+  async clear(connection, table) {
+    return this.invalidate(connection, table)
+  }
+}
+
+module.exports = new ReadCache()