odac 1.4.7 → 1.4.9

package/src/Database.js

@@ -1,6 +1,8 @@
 'use strict'
 const {buildConnections} = require('./Database/ConnectionFactory')
 const nanoid = require('./Database/nanoid')
+const readCache = require('./Database/ReadCache')
+const writeBuffer = require('./Database/WriteBuffer')
 
 class DatabaseManager {
   constructor() {
@@ -31,6 +33,12 @@ class DatabaseManager {
     // Cache nanoid column metadata from schema files for insert-time auto-generation.
     // Runs on ALL processes (primary + workers) since every process may insert data.
     this._loadNanoidMeta()
+
+    // Initialize Read-Through Cache (all processes — every worker may read cached data)
+    readCache.init()
+
+    // Initialize Write-Behind Cache (Primary holds state, Workers communicate via IPC)
+    await writeBuffer.init(this.connections)
   }
 
   /**
@@ -63,9 +71,17 @@ class DatabaseManager {
 
   /**
    * Gracefully destroys all active database connections.
+   * Flushes WriteBuffer before closing to prevent data loss.
    * Called during shutdown to release connection pools and prevent resource leaks.
    */
   async close() {
+    // Flush buffered writes before destroying connections
+    try {
+      await writeBuffer.close()
+    } catch (err) {
+      console.error('\x1b[31m[Database]\x1b[0m WriteBuffer close error:', err.message)
+    }
+
     const entries = Object.entries(this.connections)
     if (entries.length === 0) return
 
@@ -174,6 +190,67 @@ const tableProxyHandler = {
 
     // Create the Query Builder
     const qb = knexInstance(prop)
+    const connectionKey = knexInstance._odacConnectionKey || 'default'
+
+    // Write-Behind Cache: Odac.DB.posts.buffer.where(id).update({...}) / .increment('col') / .get('col')
+    //                     Odac.DB.posts.buffer.insert(row) / .flush()
+    qb.buffer = {
+      where: where => ({
+        update: data => writeBuffer.update(connectionKey, prop, where, data),
+        increment: (column, delta = 1) => writeBuffer.increment(connectionKey, prop, where, column, delta),
+        get: column => writeBuffer.get(connectionKey, prop, where, column)
+      }),
+      insert: row => writeBuffer.insert(connectionKey, prop, row),
+      flush: () => writeBuffer.flush(connectionKey, prop)
+    }
+
+    // Read-Through Cache: Odac.DB.posts.cache(60).where({active: true}).select('id', 'title')
+    //                     Odac.DB.posts.cache().where({id: 5}).first()
+    //                     Odac.DB.posts.cache.clear()
+    // Why: Returns a Proxy that intercepts .then() to inject cache lookup before DB execution.
+    // The ttl parameter on cache() sets per-query TTL; omit for config default.
+    const cacheFactory = ttl => {
+      const cachedQb = knexInstance(prop)
+      cachedQb._odacCacheTtl = ttl || 0
+
+      // Capture the ORIGINAL .then() before overriding — prevents infinite recursion
+      // when ReadCache.get() needs to execute the actual DB query on cache MISS.
+      const originalCacheThen = cachedQb.then.bind(cachedQb)
+      cachedQb.then = function (resolve, reject) {
+        const executeFn = () => new Promise((res, rej) => originalCacheThen(res, rej))
+        return readCache.get(connectionKey, prop, this, executeFn, this._odacCacheTtl).then(resolve, reject)
+      }
+
+      return cachedQb
+    }
+
+    qb.cache = Object.assign(cacheFactory, {
+      clear: () => readCache.clear(connectionKey, prop)
+    })
+
+    // Automatic cache invalidation on write operations (insert/update/delete/truncate).
+    // Why: Prevents stale reads — any mutation on a table purges all cached SELECT results.
+    // Write methods are terminal (no further chaining after await), so wrapping the return
+    // as a simple thenable is safe and avoids .then() override conflicts with count/other wraps.
+    const wrapWithInvalidation = original =>
+      function (...args) {
+        const qbResult = original.apply(this, args)
+        const thenable = {
+          then: (resolve, reject) =>
+            qbResult.then(res => readCache.invalidate(connectionKey, prop).then(() => res), reject).then(resolve, reject),
+          catch: fn => thenable.then(undefined, fn)
+        }
+        return thenable
+      }
+
+    const originalUpdate = qb.update
+    const originalDelete = qb.delete
+    const originalDel = qb.del
+    const originalTruncate = qb.truncate
+    qb.update = wrapWithInvalidation(originalUpdate)
+    qb.delete = wrapWithInvalidation(originalDelete)
+    qb.del = wrapWithInvalidation(originalDel)
+    qb.truncate = wrapWithInvalidation(originalTruncate)
 
     // Odac DX Improvement: Wrap count() to return a clean number
     const originalCount = qb.count
@@ -184,7 +261,6 @@ const tableProxyHandler = {
 
     // Odac DX Improvement: Auto-generate NanoID for columns defined as type 'nanoid' in schema.
     // Why: Zero-config ID generation — no manual Odac.DB.nanoid() calls needed.
-    const connectionKey = knexInstance._odacConnectionKey || 'default'
     const nanoidCols = manager._nanoidColumns[connectionKey]?.[prop]
     if (nanoidCols) {
       const originalInsert = qb.insert
@@ -204,6 +280,10 @@ const tableProxyHandler = {
       }
     }
 
+    // Cache invalidation for insert — applied AFTER nanoid wrap so both paths are covered.
+    const currentInsert = qb.insert
+    qb.insert = wrapWithInvalidation(currentInsert)
+
     const originalThen = qb.then
     qb.then = function (resolve, reject) {
       if (this._odacIsCount) {
@@ -257,6 +337,20 @@ const rootProxy = new Proxy(manager, {
     if (prop === '_nanoidColumns') return target._nanoidColumns
     if (prop === '_loadNanoidMeta') return target._loadNanoidMeta.bind(target)
 
+    // Global WriteBuffer: Odac.DB.buffer.flush()
+    if (prop === 'buffer') {
+      return {
+        flush: (connection, table) => writeBuffer.flush(connection, table)
+      }
+    }
+
+    // Global ReadCache: Odac.DB.cache.clear(connection, table)
+    if (prop === 'cache') {
+      return {
+        clear: (connection, table) => readCache.clear(connection, table)
+      }
+    }
+
     // Access to specific database connection: Odac.DB.analytics
     if (target.connections[prop]) {
       return new Proxy(target.connections[prop], tableProxyHandler)

package/src/Ipc.js

@@ -64,6 +64,197 @@ class Ipc extends EventEmitter {
     }
   }
 
+  // --- Atomic Counter Operations ---
+
+  /**
+   * Why: Atomically increment a numeric value. Essential for Write-Behind Cache counters
+   * where concurrent workers must not cause lost updates (get→modify→set race).
+   * Redis: INCRBYFLOAT. Memory: single-threaded Primary guarantees atomicity.
+   *
+   * @param {string} key
+   * @param {number} delta - Amount to add (can be negative)
+   * @returns {Promise<number>} New value after increment
+   */
+  async incrBy(key, delta) {
+    if (this.config.driver === 'redis') {
+      return Number(await this.redis.incrByFloat(key, delta))
+    }
+    return this._sendMemory('incrBy', {key, delta})
+  }
+
+  /**
+   * Why: Convenience wrapper. Flush logic needs to subtract flushed deltas atomically.
+   */
+  async decrBy(key, delta) {
+    return this.incrBy(key, -delta)
+  }
+
+  // --- Hash Operations ---
+
+  /**
+   * Why: Write-Behind Cache update coalescing stores pending column updates as hash fields.
+   * Merge semantics: existing fields are overwritten, new fields are added (last-write-wins).
+   * Redis: HSET key f1 v1 f2 v2. Memory: Object.assign into stored object.
+   *
+   * @param {string} key
+   * @param {object} obj - Field-value pairs to merge
+   * @returns {Promise<boolean>}
+   */
+  async hset(key, obj) {
+    if (this.config.driver === 'redis') {
+      const args = {}
+      for (const [field, value] of Object.entries(obj)) {
+        args[field] = JSON.stringify(value)
+      }
+      await this.redis.hSet(key, args)
+      return true
+    }
+    return this._sendMemory('hset', {key, obj})
+  }
+
+  /**
+   * Why: Flush reads all pending update fields for a row in one call.
+   *
+   * @param {string} key
+   * @returns {Promise<object|null>} All field-value pairs, or null if key doesn't exist
+   */
+  async hgetall(key) {
+    if (this.config.driver === 'redis') {
+      const raw = await this.redis.hGetAll(key)
+      if (!raw || Object.keys(raw).length === 0) return null
+      const result = {}
+      for (const [field, value] of Object.entries(raw)) {
+        result[field] = JSON.parse(value)
+      }
+      return result
+    }
+    return this._sendMemory('hgetall', {key})
+  }
+
+  // --- List Operations ---
+
+  /**
+   * Why: Write-Behind Cache batch insert queue. Workers push rows to a shared list;
+   * flush drains it to the database in a single INSERT.
+   * Redis: RPUSH. Memory: Array.push on Primary.
+   *
+   * @param {string} key
+   * @param {...*} items - Items to append
+   * @returns {Promise<number>} New list length
+   */
+  async rpush(key, ...items) {
+    if (this.config.driver === 'redis') {
+      const serialized = items.map(i => JSON.stringify(i))
+      return this.redis.rPush(key, serialized)
+    }
+    return this._sendMemory('rpush', {key, items})
+  }
+
+  /**
+   * Why: Flush reads queued rows before writing them to the database.
+   *
+   * @param {string} key
+   * @param {number} start - Start index (0-based, inclusive)
+   * @param {number} stop - End index (inclusive, -1 for last element)
+   * @returns {Promise<Array>} Elements in range
+   */
+  async lrange(key, start, stop) {
+    if (this.config.driver === 'redis') {
+      const raw = await this.redis.lRange(key, start, stop)
+      return raw.map(i => JSON.parse(i))
+    }
+    return this._sendMemory('lrange', {key, start, stop})
+  }
+
+  /**
+   * Why: Atomic read-and-clear for queue flush. Prevents data loss caused by
+   * non-atomic lrange() + del() where new rpush() arrivals between the two
+   * calls would be silently deleted. Redis: MULTI/EXEC pipeline.
+   * Memory: single-threaded Primary guarantees atomicity.
+   *
+   * @param {string} key
+   * @returns {Promise<Array>} All elements that were in the list
+   */
+  async lrangeAndDel(key) {
+    if (this.config.driver === 'redis') {
+      const results = await this.redis.multi().lRange(key, 0, -1).del(key).exec()
+      const raw = results[0]
+      if (!raw || !Array.isArray(raw)) return []
+      return raw.map(i => JSON.parse(i))
+    }
+    return this._sendMemory('lrangeAndDel', {key})
+  }
+
+  // --- Set Operations ---
+
+  /**
+   * Why: WriteBuffer maintains index sets (e.g., 'wb:idx:counters') to track which keys
+   * have pending data. Avoids expensive SCAN/KEYS pattern matching on flush.
+   *
+   * @param {string} key
+   * @param {...string} members
+   * @returns {Promise<number>} Number of members added
+   */
+  async sadd(key, ...members) {
+    if (this.config.driver === 'redis') {
+      return this.redis.sAdd(key, members)
+    }
+    return this._sendMemory('sadd', {key, members})
+  }
+
+  /**
+   * Why: Flush iterates all tracked keys in an index set to drain pending data.
+   *
+   * @param {string} key
+   * @returns {Promise<Array<string>>} All members
+   */
+  async smembers(key) {
+    if (this.config.driver === 'redis') {
+      return this.redis.sMembers(key)
+    }
+    return this._sendMemory('smembers', {key})
+  }
+
+  /**
+   * Why: After flushing a counter/update/queue key, remove it from the tracking index.
+   *
+   * @param {string} key
+   * @param {...string} members
+   * @returns {Promise<number>} Number of members removed
+   */
+  async srem(key, ...members) {
+    if (this.config.driver === 'redis') {
+      return this.redis.sRem(key, members)
+    }
+    return this._sendMemory('srem', {key, members})
+  }
+
+  // --- Distributed Lock ---
+
+  /**
+   * Why: Horizontal scaling requires exactly ONE server to run flush at a time.
+   * Redis: SET NX EX (atomic test-and-set with TTL). Memory: Primary-local boolean.
+   * TTL prevents deadlocks if the lock holder crashes mid-flush.
+   *
+   * @param {string} key
+   * @param {number} [ttl=10] - Lock time-to-live in seconds
+   * @returns {Promise<boolean>} true if lock acquired
+   */
+  async lock(key, ttl = 10) {
+    if (this.config.driver === 'redis') {
+      const result = await this.redis.set(key, '1', {NX: true, EX: ttl})
+      return result === 'OK'
+    }
+    return this._sendMemory('lock', {key, ttl})
+  }
+
+  /**
+   * Why: Release flush lock after completion so the next cycle can proceed.
+   */
+  async unlock(key) {
+    return this.del(key)
+  }
+
   async publish(channel, message) {
     if (this.config.driver === 'redis') {
       return this.redis.publish(channel, JSON.stringify(message))
@@ -219,32 +410,152 @@ class Ipc extends EventEmitter {
   }
 
   _handleDirectPrimaryCall(action, payload) {
-    // Basic implementation for Primary process using itself
-    if (action === 'set') {
-      const expireAt = payload.ttl > 0 ? Date.now() + payload.ttl * 1000 : Infinity
-      this._memoryStore.set(payload.key, {value: payload.value, expireAt})
-      return true
-    }
-    if (action === 'get') {
-      const data = this._memoryStore.get(payload.key)
-      if (!data) return null
-      if (data.expireAt !== Infinity && Date.now() > data.expireAt) {
-        this._memoryStore.delete(payload.key)
-        return null
-      }
-      return data.value
-    }
-    if (action === 'del') return this._memoryStore.delete(payload.key)
-    if (action === 'publish') {
-      const workers = this._memorySubs.get(payload.channel)
-      if (workers) {
-        workers.forEach(wId => {
-          const w = cluster.workers[wId]
-          if (w) w.send({type: 'ipc:message', channel: payload.channel, message: payload.message})
-        })
+    return this._executePrimaryAction(action, payload)
+  }
+
+  /**
+   * Why: Single source of truth for all memory-driver operations.
+   * Both _handlePrimaryMessage (worker→primary) and _handleDirectPrimaryCall (primary self-call)
+   * funnel through this method, eliminating logic duplication.
+   */
+  _executePrimaryAction(action, msg) {
+    switch (action) {
+      case 'set': {
+        const expireAt = msg.ttl > 0 ? Date.now() + msg.ttl * 1000 : Infinity
+        this._memoryStore.set(msg.key, {value: msg.value, expireAt})
+        return true
+      }
+      case 'get': {
+        const data = this._memoryStore.get(msg.key)
+        if (!data) return null
+        if (data.expireAt !== Infinity && Date.now() > data.expireAt) {
+          this._memoryStore.delete(msg.key)
+          return null
+        }
+        return data.value
+      }
+      case 'del':
+        return this._memoryStore.delete(msg.key)
+
+      // --- Atomic Counter ---
+      case 'incrBy': {
+        const data = this._memoryStore.get(msg.key) || {value: 0, expireAt: Infinity}
+        data.value = (typeof data.value === 'number' ? data.value : 0) + msg.delta
+        this._memoryStore.set(msg.key, data)
+        return data.value
+      }
+
+      // --- Hash ---
+      case 'hset': {
+        const data = this._memoryStore.get(msg.key) || {value: {}, expireAt: Infinity}
+        if (typeof data.value !== 'object' || data.value === null || Array.isArray(data.value)) {
+          data.value = {}
+        }
+        Object.assign(data.value, msg.obj)
+        this._memoryStore.set(msg.key, data)
+        return true
+      }
+      case 'hgetall': {
+        const data = this._memoryStore.get(msg.key)
+        if (!data || typeof data.value !== 'object' || Array.isArray(data.value)) return null
+        return {...data.value}
+      }
+
+      // --- List ---
+      case 'rpush': {
+        const data = this._memoryStore.get(msg.key) || {value: [], expireAt: Infinity}
+        if (!Array.isArray(data.value)) data.value = []
+        data.value.push(...msg.items)
+        this._memoryStore.set(msg.key, data)
+        return data.value.length
+      }
+      case 'lrange': {
+        const data = this._memoryStore.get(msg.key)
+        if (!data || !Array.isArray(data.value)) return []
+        return msg.stop === -1 ? data.value.slice(msg.start) : data.value.slice(msg.start, msg.stop + 1)
+      }
+      case 'lrangeAndDel': {
+        const data = this._memoryStore.get(msg.key)
+        if (!data || !Array.isArray(data.value)) return []
+        const items = data.value
+        this._memoryStore.delete(msg.key)
+        return items
+      }
+
+      // --- Set ---
+      case 'sadd': {
+        let data = this._memoryStore.get(msg.key)
+        if (!data) {
+          data = {value: [], expireAt: Infinity}
+          this._memoryStore.set(msg.key, data)
+        }
+        if (!Array.isArray(data.value)) data.value = []
+        let added = 0
+        for (const m of msg.members) {
+          if (!data.value.includes(m)) {
+            data.value.push(m)
+            added++
+          }
+        }
+        return added
+      }
+      case 'smembers': {
+        const data = this._memoryStore.get(msg.key)
+        return data && Array.isArray(data.value) ? data.value.slice() : []
+      }
+      case 'srem': {
+        const data = this._memoryStore.get(msg.key)
+        if (!data || !Array.isArray(data.value)) return 0
+        let removed = 0
+        for (const m of msg.members) {
+          const idx = data.value.indexOf(m)
+          if (idx !== -1) {
+            data.value.splice(idx, 1)
+            removed++
+          }
+        }
+        return removed
+      }
+
+      // --- Lock ---
+      case 'lock': {
+        const existing = this._memoryStore.get(msg.key)
+        if (existing && existing.expireAt > Date.now()) return false
+        const expireAt = Date.now() + (msg.ttl || 10) * 1000
+        this._memoryStore.set(msg.key, {value: '1', expireAt})
+        return true
+      }
+
+      // --- Pub/Sub ---
+      case 'publish': {
+        const workers = this._memorySubs.get(msg.channel)
+        if (workers) {
+          workers.forEach(wId => {
+            const w = require('node:cluster').workers[wId]
+            if (w) w.send({type: 'ipc:message', channel: msg.channel, message: msg.message})
+          })
+        }
+        return undefined
+      }
+      case 'subscribe': {
+        if (!this._memorySubs.has(msg.channel)) {
+          this._memorySubs.set(msg.channel, new Set())
+        }
+        // msg.workerId is set by _handlePrimaryMessage for worker context
+        if (msg.workerId) this._memorySubs.get(msg.channel).add(msg.workerId)
+        return undefined
+      }
+      case 'unsubscribe': {
+        if (this._memorySubs.has(msg.channel)) {
+          this._memorySubs.get(msg.channel).delete(msg.workerId)
+          if (this._memorySubs.get(msg.channel).size === 0) {
+            this._memorySubs.delete(msg.channel)
+          }
+        }
+        return undefined
       }
     }
-    // subscribe on primary not deeply implemented to avoid complexity, usually workers listen.
+    return null
   }
 
   _startGarbageCollector() {
@@ -308,66 +619,17 @@ class Ipc extends EventEmitter {
   }
 
   _handlePrimaryMessage(worker, msg) {
-    const {type, id, key, value, ttl, channel, message} = msg
-    const action = type.replace('ipc:', '')
-
-    let response = null
+    const action = msg.type.replace('ipc:', '')
 
-    switch (action) {
-      case 'set': {
-        const expireAt = ttl > 0 ? Date.now() + ttl * 1000 : Infinity
-        this._memoryStore.set(key, {value, expireAt})
-        response = true
-        break
-      }
-      case 'get': {
-        const data = this._memoryStore.get(key)
-        if (data) {
-          if (data.expireAt !== Infinity && Date.now() > data.expireAt) {
-            this._memoryStore.delete(key)
-            response = null
-          } else {
-            response = data.value
-          }
-        } else {
-          response = null
-        }
-        break
-      }
-      case 'del':
-        response = this._memoryStore.delete(key)
-        break
-      case 'subscribe':
-        if (!this._memorySubs.has(channel)) {
-          this._memorySubs.set(channel, new Set())
-        }
-        this._memorySubs.get(channel).add(worker.id)
-        break
-      case 'unsubscribe':
-        if (this._memorySubs.has(channel)) {
-          this._memorySubs.get(channel).delete(worker.id)
-          if (this._memorySubs.get(channel).size === 0) {
-            this._memorySubs.delete(channel)
-          }
-        }
-        break
-      case 'publish': {
-        // Relay to all subscribed workers
-        const workers = this._memorySubs.get(channel)
-        if (workers) {
-          workers.forEach(wId => {
-            // Don't echo back to sender if desired? Usually pub/sub receives own too if subbed.
-            // Redis publishes to all subscribers.
-            const w = cluster.workers[wId]
-            if (w) w.send({type: 'ipc:message', channel, message})
-          })
-        }
-        break
-      }
+    // Inject worker context for subscribe/unsubscribe
+    if (action === 'subscribe' || action === 'unsubscribe') {
+      msg.workerId = worker.id
     }
 
-    if (id) {
-      worker.send({type: 'ipc:response', id, data: response})
+    const response = this._executePrimaryAction(action, msg)
+
+    if (msg.id) {
+      worker.send({type: 'ipc:response', id: msg.id, data: response})
     }
   }
 }

package/src/Odac.js

@@ -6,11 +6,12 @@ module.exports = {
 
     await global.Odac.Env.init()
     await global.Odac.Config.init()
-    await global.Odac.Database.init()
 
     global.Odac.Ipc = require('./Ipc.js')
     await global.Odac.Ipc.init()
 
+    await global.Odac.Database.init()
+
     await global.Odac.Route.init()
     await global.Odac.Server.init()
     global.Odac.instance = this.instance

package/src/Storage.js

@@ -45,12 +45,14 @@ class OdacStorage {
 
   put(key, value) {
     if (!this.ready) return false
-    return this.db.put(key, value)
+    this.db.putSync(key, value)
+    return true
   }
 
   remove(key) {
     if (!this.ready) return false
-    return this.db.remove(key)
+    this.db.removeSync(key)
+    return true
   }
 
   // --- Range Operations ---

package/src/Validator.js

@@ -224,7 +224,7 @@ class Validator {
                     error = value && value !== '' && !this.#odac.Var(value).is('url')
                     break
                   case 'username':
-                    error = value && value !== '' && !/^[a-zA-Z0-9]+$/.test(value)
+                    error = value && value !== '' && !this.#odac.Var(value).is('username')
                     break
                   case 'xss':
                     error = value && value !== '' && /<[^>]*>/g.test(value)

package/src/Var.js

@@ -139,6 +139,7 @@ class Var {
           /([0-9#][\u20E3])|[\u00ae\u00a9\u203C\u2047\u2048\u2049\u3030\u303D\u2139\u2122\u3297\u3299][\uFE00-\uFEFF]?|[\u2190-\u21FF][\uFE00-\uFEFF]?|[\u2300-\u23FF][\uFE00-\uFEFF]?|[\u2460-\u24FF][\uFE00-\uFEFF]?|[\u25A0-\u25FF][\uFE00-\uFEFF]?|[\u2600-\u27BF][\uFE00-\uFEFF]?|[\u2900-\u297F][\uFE00-\uFEFF]?|[\u2B00-\u2BF0][\uFE00-\uFEFF]?|[\u1F000-\u1F6FF][\uFE00-\uFEFF]?/u.test(
             this.#value
           ))
+    if (args.includes('username')) result = (result || any) && ((any && result) || /^[a-zA-Z0-9]+$/.test(this.#value))
     if (args.includes('xss')) result = (result || any) && ((any && result) || this.#value == this.#value.replace(/<[^>]*>/g, ''))
     return result
   }