odac 1.4.8 → 1.4.10

package/test/Database/ReadCache/crossTable.test.js

@@ -0,0 +1,179 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests cross-table cache invalidation for JOIN queries.
+ * Why: A cached query like posts.join('users').cache().select() must be invalidated
+ * when EITHER posts OR users is written to. Validates that cache keys are registered
+ * in all joined tables' indexes.
+ */
+
+let knexLib, db
+
+beforeEach(async () => {
+  jest.resetModules()
+
+  knexLib = require('knex')
+  db = knexLib({client: 'sqlite3', connection: {filename: ':memory:'}, useNullAsDefault: true})
+
+  await db.schema.createTable('posts', table => {
+    table.integer('id').primary()
+    table.string('title', 255)
+    table.integer('user_id')
+  })
+
+  await db.schema.createTable('users', table => {
+    table.integer('id').primary()
+    table.string('name', 255)
+  })
+
+  await db.schema.createTable('categories', table => {
+    table.integer('id').primary()
+    table.string('label', 255)
+  })
+
+  await db('users').insert([
+    {id: 1, name: 'Alice'},
+    {id: 2, name: 'Bob'}
+  ])
+
+  await db('categories').insert([{id: 1, label: 'Tech'}])
+
+  await db('posts').insert([
+    {id: 1, title: 'Post A', user_id: 1},
+    {id: 2, title: 'Post B', user_id: 2}
+  ])
+
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  const Ipc = require('../../../src/Ipc')
+  global.Odac = {
+    Config: {
+      cache: {ttl: 60, maxKeys: 10000},
+      buffer: {flushInterval: 999999, checkpointInterval: 999999}
+    },
+    Storage: {
+      isReady: () => false,
+      put: jest.fn(),
+      remove: jest.fn(),
+      getRange: () => []
+    },
+    Ipc
+  }
+  await Ipc.init()
+
+  const writeBuffer = require('../../../src/Database/WriteBuffer')
+  await writeBuffer.init({default: db})
+
+  const readCache = require('../../../src/Database/ReadCache')
+  readCache.init()
+
+  const DB = require('../../../src/Database')
+  DB.connections = {default: db}
+})
+
+afterEach(async () => {
+  const writeBuffer = require('../../../src/Database/WriteBuffer')
+  await writeBuffer.close()
+  await Odac.Ipc.close()
+  await db.destroy()
+  delete global.Odac
+})
+
+describe('Cross-table cache invalidation (JOIN queries)', () => {
+  it('should register cache key in joined table index', async () => {
+    const readCache = require('../../../src/Database/ReadCache')
+
+    const qb = db('posts').join('users', 'posts.user_id', '=', 'users.id').select('posts.title', 'users.name')
+    const executeFn = () => qb.then(r => r)
+    await readCache.get('default', 'posts', qb, executeFn, 60)
+
+    // Cache key should be in BOTH posts and users indexes
+    const postKeys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    const userKeys = await Odac.Ipc.smembers('rc:idx:default:users')
+
+    expect(postKeys).toHaveLength(1)
+    expect(userKeys).toHaveLength(1)
+    expect(postKeys[0]).toBe(userKeys[0])
+  })
+
+  it('should invalidate joined query when joined table is written to', async () => {
+    const DB = require('../../../src/Database')
+
+    // Cache a JOIN query via proxy
+    const result1 = await DB.posts.cache(60).join('users', 'posts.user_id', '=', 'users.id').select('posts.title', 'users.name')
+
+    expect(result1).toHaveLength(2)
+
+    // Verify cache exists in both indexes
+    let postKeys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    let userKeys = await Odac.Ipc.smembers('rc:idx:default:users')
+    expect(postKeys).toHaveLength(1)
+    expect(userKeys).toHaveLength(1)
+
+    // Write to the JOINED table (users) — should invalidate the cached join query
+    await DB.users.where({id: 1}).update({name: 'Alice Updated'})
+
+    userKeys = await Odac.Ipc.smembers('rc:idx:default:users')
+    expect(userKeys).toHaveLength(0)
+
+    // The cache entry itself should be deleted — next read should hit DB
+    const result2 = await DB.posts.cache(60).join('users', 'posts.user_id', '=', 'users.id').select('posts.title', 'users.name')
+
+    expect(result2[0].name).toBe('Alice Updated')
+  })
+
+  it('should invalidate joined query when primary table is written to', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.cache(60).join('users', 'posts.user_id', '=', 'users.id').select('posts.title', 'users.name')
+
+    // Write to the PRIMARY table (posts)
+    await DB.posts.where({id: 1}).update({title: 'Updated Post'})
+
+    const postKeys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(postKeys).toHaveLength(0)
+
+    // Fresh read should reflect the update
+    const result = await DB.posts.cache(60).join('users', 'posts.user_id', '=', 'users.id').select('posts.title', 'users.name')
+
+    expect(result[0].title).toBe('Updated Post')
+  })
+
+  it('should handle multiple joins', async () => {
+    const readCache = require('../../../src/Database/ReadCache')
+
+    const qb = db('posts')
+      .join('users', 'posts.user_id', '=', 'users.id')
+      .leftJoin('categories', 'posts.id', '=', 'categories.id')
+      .select('posts.title', 'users.name', 'categories.label')
+
+    const executeFn = () => qb.then(r => r)
+    await readCache.get('default', 'posts', qb, executeFn, 60)
+
+    // Cache key should be in ALL three table indexes
+    const postKeys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    const userKeys = await Odac.Ipc.smembers('rc:idx:default:users')
+    const catKeys = await Odac.Ipc.smembers('rc:idx:default:categories')
+
+    expect(postKeys).toHaveLength(1)
+    expect(userKeys).toHaveLength(1)
+    expect(catKeys).toHaveLength(1)
+    expect(postKeys[0]).toBe(userKeys[0])
+    expect(postKeys[0]).toBe(catKeys[0])
+  })
+
+  it('should handle aliased table names in joins', async () => {
+    const readCache = require('../../../src/Database/ReadCache')
+
+    const qb = db('posts').join('users as u', 'posts.user_id', '=', 'u.id').select('posts.title', 'u.name')
+
+    const executeFn = () => qb.then(r => r)
+    await readCache.get('default', 'posts', qb, executeFn, 60)
+
+    // Should register under 'users', not 'users as u'
+    const userKeys = await Odac.Ipc.smembers('rc:idx:default:users')
+    expect(userKeys).toHaveLength(1)
+  })
+})

package/test/Database/ReadCache/get.test.js

@@ -0,0 +1,128 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests ReadCache.get() — the core read-through logic.
+ * Why: Validates cache HIT/MISS behavior, TTL propagation, and maxKeys guard.
+ */
+
+let knexLib, db
+
+beforeEach(async () => {
+  jest.resetModules()
+
+  knexLib = require('knex')
+  db = knexLib({client: 'sqlite3', connection: {filename: ':memory:'}, useNullAsDefault: true})
+
+  await db.schema.createTable('posts', table => {
+    table.integer('id').primary()
+    table.string('title', 255)
+    table.boolean('active').defaultTo(true)
+  })
+
+  await db('posts').insert([
+    {id: 1, title: 'First Post', active: true},
+    {id: 2, title: 'Second Post', active: true},
+    {id: 3, title: 'Draft', active: false}
+  ])
+
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  const Ipc = require('../../../src/Ipc')
+  global.Odac = {
+    Config: {cache: {ttl: 60, maxKeys: 10000}},
+    Ipc
+  }
+  await Ipc.init()
+})
+
+afterEach(async () => {
+  await Odac.Ipc.close()
+  await db.destroy()
+  delete global.Odac
+})
+
+describe('ReadCache.get()', () => {
+  let readCache
+
+  beforeEach(() => {
+    readCache = require('../../../src/Database/ReadCache')
+    readCache.init()
+  })
+
+  it('should return DB result on cache MISS and cache it', async () => {
+    const qb = db('posts').where({active: true}).select('id', 'title')
+    const executeFn = () => qb.then(r => r)
+    const result = await readCache.get('default', 'posts', qb, executeFn, 60)
+
+    expect(result).toHaveLength(2)
+    expect(result[0].title).toBe('First Post')
+
+    // Verify it was cached — check index
+    const keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+  })
+
+  it('should return cached result on cache HIT without querying DB', async () => {
+    const qb1 = db('posts').where({active: true}).select('id', 'title')
+    const executeFn1 = () => qb1.then(r => r)
+    const result1 = await readCache.get('default', 'posts', qb1, executeFn1, 60)
+
+    // Modify DB directly — cache should NOT reflect this
+    await db('posts').where({id: 1}).update({title: 'Modified'})
+
+    const qb2 = db('posts').where({active: true}).select('id', 'title')
+    const executeFn2 = () => qb2.then(r => r)
+    const result2 = await readCache.get('default', 'posts', qb2, executeFn2, 60)
+
+    // Should still return the old cached value
+    expect(result2[0].title).toBe('First Post')
+    expect(result1).toEqual(result2)
+  })
+
+  it('should use config default TTL when ttl parameter is 0', async () => {
+    const qb = db('posts').where({id: 1}).first()
+    const executeFn = () => qb.then(r => r)
+    const result = await readCache.get('default', 'posts', qb, executeFn, 0)
+
+    expect(result.title).toBe('First Post')
+
+    // Should still be cached
+    const keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+  })
+
+  it('should respect maxKeys limit', async () => {
+    // Re-init with maxKeys = 1
+    global.Odac.Config.cache = {ttl: 60, maxKeys: 1}
+
+    readCache = require('../../../src/Database/ReadCache')
+    readCache.init()
+
+    const qb1 = db('posts').where({id: 1}).first()
+    const executeFn1 = () => qb1.then(r => r)
+    await readCache.get('default', 'posts', qb1, executeFn1, 60)
+
+    const qb2 = db('posts').where({id: 2}).first()
+    const executeFn2 = () => qb2.then(r => r)
+    await readCache.get('default', 'posts', qb2, executeFn2, 60)
+
+    // Only 1 key should be in the index (first one cached, second skipped)
+    const keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+  })
+
+  it('should generate different keys for different queries', async () => {
+    const qb1 = db('posts').where({id: 1}).first()
+    const qb2 = db('posts').where({id: 2}).first()
+    const executeFn1 = () => qb1.then(r => r)
+    const executeFn2 = () => qb2.then(r => r)
+
+    await readCache.get('default', 'posts', qb1, executeFn1, 60)
+    await readCache.get('default', 'posts', qb2, executeFn2, 60)
+
+    const keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(2)
+  })
+})

package/test/Database/ReadCache/invalidate.test.js

@@ -0,0 +1,103 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests ReadCache.invalidate() — table-level cache purge.
+ * Why: Validates that all cached queries for a table are removed on invalidation,
+ * and that unrelated tables remain unaffected.
+ */
+
+let knexLib, db
+
+beforeEach(async () => {
+  jest.resetModules()
+
+  knexLib = require('knex')
+  db = knexLib({client: 'sqlite3', connection: {filename: ':memory:'}, useNullAsDefault: true})
+
+  await db.schema.createTable('posts', table => {
+    table.integer('id').primary()
+    table.string('title', 255)
+  })
+
+  await db.schema.createTable('users', table => {
+    table.integer('id').primary()
+    table.string('name', 255)
+  })
+
+  await db('posts').insert([
+    {id: 1, title: 'Post A'},
+    {id: 2, title: 'Post B'}
+  ])
+
+  await db('users').insert([{id: 1, name: 'Alice'}])
+
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  const Ipc = require('../../../src/Ipc')
+  global.Odac = {
+    Config: {cache: {ttl: 60, maxKeys: 10000}},
+    Ipc
+  }
+  await Ipc.init()
+})
+
+afterEach(async () => {
+  await Odac.Ipc.close()
+  await db.destroy()
+  delete global.Odac
+})
+
+describe('ReadCache.invalidate()', () => {
+  let readCache
+
+  beforeEach(() => {
+    readCache = require('../../../src/Database/ReadCache')
+    readCache.init()
+  })
+
+  it('should purge all cached queries for the specified table', async () => {
+    // Cache two different queries on posts
+    const qb1 = db('posts').where({id: 1}).first()
+    const qb2 = db('posts').where({id: 2}).first()
+    await readCache.get('default', 'posts', qb1, () => qb1.then(r => r), 60)
+    await readCache.get('default', 'posts', qb2, () => qb2.then(r => r), 60)
+
+    const cachedKeys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(cachedKeys).toHaveLength(2)
+
+    // Invalidate
+    await readCache.invalidate('default', 'posts')
+
+    const keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+
+    // Verify cache entries are actually deleted
+    for (const key of cachedKeys) {
+      const val = await Odac.Ipc.get(key)
+      expect(val).toBeNull()
+    }
+  })
+
+  it('should not affect cache of other tables', async () => {
+    const qbPosts = db('posts').where({id: 1}).first()
+    const qbUsers = db('users').where({id: 1}).first()
+    await readCache.get('default', 'posts', qbPosts, () => qbPosts.then(r => r), 60)
+    await readCache.get('default', 'users', qbUsers, () => qbUsers.then(r => r), 60)
+
+    // Invalidate only posts
+    await readCache.invalidate('default', 'posts')
+
+    const postKeys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    const userKeys = await Odac.Ipc.smembers('rc:idx:default:users')
+
+    expect(postKeys).toHaveLength(0)
+    expect(userKeys).toHaveLength(1)
+  })
+
+  it('should be a no-op when no cache exists for the table', async () => {
+    // Should not throw
+    await expect(readCache.invalidate('default', 'nonexistent')).resolves.toBeUndefined()
+  })
+})

package/test/Database/ReadCache/proxy.test.js

@@ -0,0 +1,184 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests the cache chain API exposed via Database.js proxy.
+ * Why: Validates that Odac.DB.posts.cache(60).where(...).select(...) pattern
+ * correctly delegates to ReadCache, and that write operations auto-invalidate.
+ */
+
+let knexLib, db
+
+beforeEach(async () => {
+  jest.resetModules()
+
+  knexLib = require('knex')
+  db = knexLib({client: 'sqlite3', connection: {filename: ':memory:'}, useNullAsDefault: true})
+
+  await db.schema.createTable('posts', table => {
+    table.integer('id').primary()
+    table.string('title', 255)
+    table.integer('views').defaultTo(0)
+    table.boolean('active').defaultTo(true)
+  })
+
+  await db('posts').insert([
+    {id: 1, title: 'First Post', views: 100, active: true},
+    {id: 2, title: 'Second Post', views: 200, active: true},
+    {id: 3, title: 'Draft', views: 0, active: false}
+  ])
+
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  const Ipc = require('../../../src/Ipc')
+  global.Odac = {
+    Config: {
+      cache: {ttl: 60, maxKeys: 10000},
+      buffer: {flushInterval: 999999, checkpointInterval: 999999}
+    },
+    Storage: {
+      isReady: () => false,
+      put: jest.fn(),
+      remove: jest.fn(),
+      getRange: () => []
+    },
+    Ipc
+  }
+  await Ipc.init()
+
+  const writeBuffer = require('../../../src/Database/WriteBuffer')
+  await writeBuffer.init({default: db})
+
+  const readCache = require('../../../src/Database/ReadCache')
+  readCache.init()
+
+  const DB = require('../../../src/Database')
+  DB.connections = {default: db}
+})
+
+afterEach(async () => {
+  const writeBuffer = require('../../../src/Database/WriteBuffer')
+  await writeBuffer.close()
+  await Odac.Ipc.close()
+  await db.destroy()
+  delete global.Odac
+})
+
+describe('Database.js Proxy - cache(ttl).where().select()', () => {
+  it('should cache SELECT results with specified TTL', async () => {
+    const DB = require('../../../src/Database')
+
+    const result1 = await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    expect(result1).toHaveLength(2)
+
+    // Modify DB directly
+    await db('posts').where({id: 1}).update({title: 'Modified'})
+
+    // Should return cached (stale) data
+    const result2 = await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    expect(result2[0].title).toBe('First Post')
+  })
+
+  it('should cache with default TTL when called without argument', async () => {
+    const DB = require('../../../src/Database')
+
+    const result = await DB.posts.cache().where({id: 1}).first()
+    expect(result.title).toBe('First Post')
+
+    // Verify cached
+    const keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+  })
+})
+
+describe('Database.js Proxy - cache.clear()', () => {
+  it('should manually clear table cache via Odac.DB.posts.cache.clear()', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    await DB.posts.cache.clear()
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+  })
+})
+
+describe('Database.js Proxy - automatic invalidation on write', () => {
+  it('should invalidate cache after update()', async () => {
+    const DB = require('../../../src/Database')
+
+    // Cache a query
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    // Update via proxy — should auto-invalidate
+    await DB.posts.where({id: 1}).update({title: 'Updated'})
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+
+    // Next cache() call should fetch fresh data
+    const result = await DB.posts.cache(60).where({id: 1}).first()
+    expect(result.title).toBe('Updated')
+  })
+
+  it('should invalidate cache after insert()', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    await DB.posts.insert({id: 4, title: 'New Post', views: 0, active: true})
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+  })
+
+  it('should invalidate cache after delete()', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    await DB.posts.where({id: 3}).delete()
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+  })
+
+  it('should invalidate cache after del() (alias)', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    await DB.posts.where({id: 3}).del()
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+  })
+})
+
+describe('Database.js Proxy - global cache.clear()', () => {
+  it('should clear cache via Odac.DB.cache.clear(connection, table)', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    await DB.cache.clear('default', 'posts')
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+  })
+})