odac 1.4.7 → 1.4.9

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)
+  })
+})

package/test/Database/WriteBuffer/_recoverFromCheckpoint.test.js

@@ -0,0 +1,207 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests WriteBuffer LMDB checkpoint and crash recovery.
+ * Why: Validates zero data loss guarantee — buffered data survives process crashes
+ * via periodic LMDB checkpoints and is recovered on next startup.
+ */
+
+let knexLib, db, storageData
+
+function createMockStorage() {
+  storageData = new Map()
+  return {
+    isReady: () => true,
+    put: (key, value) => storageData.set(key, value),
+    remove: key => storageData.delete(key),
+    get: key => storageData.get(key) ?? null,
+    getRange: ({start, end}) => {
+      const results = []
+      for (const [key, value] of storageData) {
+        if (key >= start && key < end) {
+          results.push({key, value})
+        }
+      }
+      return results
+    }
+  }
+}
+
+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.integer('views').defaultTo(0)
+  })
+  await db('posts').insert({id: 1, views: 100})
+
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+})
+
+afterEach(async () => {
+  await db.destroy()
+  delete global.Odac
+})
+
+describe('WriteBuffer - Checkpoint', () => {
+  it('should write counter deltas to LMDB on checkpoint', async () => {
+    const Ipc = require('../../../src/Ipc')
+    global.Odac = {
+      Config: {buffer: {flushInterval: 999999, checkpointInterval: 999999}},
+      Storage: createMockStorage(),
+      Ipc
+    }
+    await Ipc.init()
+
+    const WriteBuffer = require('../../../src/Database/WriteBuffer')
+    await WriteBuffer.init({default: db})
+
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 5)
+    await WriteBuffer._writeCheckpoint()
+
+    const checkpoint = storageData.get('wb:c:default:posts:1:views')
+    expect(checkpoint).toBeDefined()
+    expect(checkpoint.delta).toBe(5)
+    expect(checkpoint.base).toBe(100)
+
+    await WriteBuffer.close()
+    await Ipc.close()
+  })
+
+  it('should write queue rows to LMDB on checkpoint', async () => {
+    const Ipc = require('../../../src/Ipc')
+    global.Odac = {
+      Config: {buffer: {flushInterval: 999999, checkpointInterval: 999999}},
+      Storage: createMockStorage(),
+      Ipc
+    }
+    await Ipc.init()
+
+    const WriteBuffer = require('../../../src/Database/WriteBuffer')
+    await WriteBuffer.init({default: db})
+
+    await WriteBuffer.insert('default', 'activity_log', {user_id: 1, action: 'view'})
+    await WriteBuffer.insert('default', 'activity_log', {user_id: 2, action: 'click'})
+    await WriteBuffer._writeCheckpoint()
+
+    const checkpoint = storageData.get('wb:q:default:activity_log')
+    expect(checkpoint).toBeDefined()
+    expect(checkpoint).toHaveLength(2)
+    expect(checkpoint[0].action).toBe('view')
+
+    await WriteBuffer.close()
+    await Ipc.close()
+  })
+})
+
+describe('WriteBuffer - Recovery', () => {
+  it('should recover counter deltas from LMDB on startup', async () => {
+    // Simulate crash: write checkpoint data before init
+    const mockStorage = createMockStorage()
+    storageData.set('wb:c:default:posts:1:views', {delta: 7, base: 100})
+
+    const Ipc = require('../../../src/Ipc')
+    global.Odac = {
+      Config: {buffer: {flushInterval: 999999, checkpointInterval: 999999}},
+      Storage: mockStorage,
+      Ipc
+    }
+    await Ipc.init()
+
+    const WriteBuffer = require('../../../src/Database/WriteBuffer')
+    await WriteBuffer.init({default: db})
+
+    // Should recover the delta from checkpoint
+    const result = await WriteBuffer.get('default', 'posts', 1, 'views')
+    expect(result).toBe(107) // base 100 + recovered delta 7
+
+    await WriteBuffer.close()
+    await Ipc.close()
+  })
+
+  it('should recover queue rows from LMDB on startup', async () => {
+    await db.schema.createTable('activity_log', table => {
+      table.increments('id')
+      table.integer('user_id')
+      table.string('action', 50)
+    })
+
+    const mockStorage = createMockStorage()
+    storageData.set('wb:q:default:activity_log', [{user_id: 1, action: 'recovered_view'}])
+
+    const Ipc = require('../../../src/Ipc')
+    global.Odac = {
+      Config: {buffer: {flushInterval: 999999, checkpointInterval: 999999}},
+      Storage: mockStorage,
+      Ipc
+    }
+    await Ipc.init()
+
+    const WriteBuffer = require('../../../src/Database/WriteBuffer')
+    await WriteBuffer.init({default: db})
+
+    // Flush recovered data
+    await WriteBuffer.flush()
+
+    const rows = await db('activity_log').select()
+    expect(rows).toHaveLength(1)
+    expect(rows[0].action).toBe('recovered_view')
+
+    await WriteBuffer.close()
+    await Ipc.close()
+  })
+
+  it('should merge recovered data with new increments', async () => {
+    const mockStorage = createMockStorage()
+    storageData.set('wb:c:default:posts:1:views', {delta: 5, base: 100})
+
+    const Ipc = require('../../../src/Ipc')
+    global.Odac = {
+      Config: {buffer: {flushInterval: 999999, checkpointInterval: 999999}},
+      Storage: mockStorage,
+      Ipc
+    }
+    await Ipc.init()
+
+    const WriteBuffer = require('../../../src/Database/WriteBuffer')
+    await WriteBuffer.init({default: db})
+
+    // Add more increments on top of recovered data
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 3)
+
+    const result = await WriteBuffer.get('default', 'posts', 1, 'views')
+    expect(result).toBe(108) // base 100 + recovered 5 + new 3
+
+    await WriteBuffer.close()
+    await Ipc.close()
+  })
+
+  it('should clear LMDB checkpoint after successful flush', async () => {
+    const mockStorage = createMockStorage()
+    storageData.set('wb:c:default:posts:1:views', {delta: 5, base: 100})
+
+    const Ipc = require('../../../src/Ipc')
+    global.Odac = {
+      Config: {buffer: {flushInterval: 999999, checkpointInterval: 999999}},
+      Storage: mockStorage,
+      Ipc
+    }
+    await Ipc.init()
+
+    const WriteBuffer = require('../../../src/Database/WriteBuffer')
+    await WriteBuffer.init({default: db})
+    await WriteBuffer.flush()
+
+    // Checkpoint data should be cleared
+    expect(storageData.has('wb:c:default:posts:1:views')).toBe(false)
+
+    await WriteBuffer.close()
+    await Ipc.close()
+  })
+})

package/test/Database/WriteBuffer/buffer.test.js

@@ -0,0 +1,143 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests the chainable buffer API exposed via Database.js proxy.
+ * Why: Validates that the Odac.DB.table.buffer.where(id).update(data) pattern
+ * correctly delegates to WriteBuffer's internal methods.
+ */
+
+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.integer('views').defaultTo(0)
+    table.string('title', 255)
+  })
+
+  await db.schema.createTable('activity_log', table => {
+    table.increments('id')
+    table.integer('user_id')
+    table.string('action', 50)
+  })
+
+  await db('posts').insert([
+    {id: 1, views: 100, title: 'First Post'},
+    {id: 2, views: 200, title: 'Second Post'}
+  ])
+
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  const Ipc = require('../../../src/Ipc')
+  global.Odac = {
+    Config: {buffer: {flushInterval: 999999, checkpointInterval: 999999}},
+    Storage: {
+      isReady: () => false,
+      put: jest.fn(),
+      remove: jest.fn(),
+      getRange: () => []
+    },
+    Ipc
+  }
+  await Ipc.init()
+
+  // Initialize WriteBuffer with our test DB
+  const writeBuffer = require('../../../src/Database/WriteBuffer')
+  await writeBuffer.init({default: db})
+
+  // Wire up Database.js proxy
+  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 - buffer.where().update()', () => {
+  it('should buffer and flush via Odac.DB.posts.buffer.where(id).update()', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.buffer.where(1).update({title: 'Updated Title'})
+    await DB.posts.buffer.flush()
+
+    const row = await db('posts').where({id: 1}).first()
+    expect(row.title).toBe('Updated Title')
+  })
+
+  it('should merge multiple updates via chainable API', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.buffer.where(1).update({title: 'New Title'})
+    await DB.posts.buffer.where(1).update({title: 'Final Title'})
+    await DB.posts.buffer.flush()
+
+    const row = await db('posts').where({id: 1}).first()
+    expect(row.title).toBe('Final Title')
+  })
+})
+
+describe('Database.js Proxy - buffer.where().increment()', () => {
+  it('should increment via Odac.DB.posts.buffer.where(id).increment(col)', async () => {
+    const DB = require('../../../src/Database')
+
+    const result = await DB.posts.buffer.where(1).increment('views')
+    expect(result).toBe(101)
+  })
+
+  it('should support custom delta', async () => {
+    const DB = require('../../../src/Database')
+
+    const result = await DB.posts.buffer.where(1).increment('views', 5)
+    expect(result).toBe(105)
+  })
+})
+
+describe('Database.js Proxy - buffer.where().get()', () => {
+  it('should get buffered value via Odac.DB.posts.buffer.where(id).get(col)', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.buffer.where(1).increment('views', 10)
+    const result = await DB.posts.buffer.where(1).get('views')
+    expect(result).toBe(110)
+  })
+})
+
+describe('Database.js Proxy - buffer.insert()', () => {
+  it('should buffer insert via Odac.DB.activity_log.buffer.insert(row)', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.activity_log.buffer.insert({user_id: 1, action: 'view'})
+    await DB.activity_log.buffer.insert({user_id: 2, action: 'click'})
+    await DB.activity_log.buffer.flush()
+
+    const rows = await db('activity_log').select()
+    expect(rows).toHaveLength(2)
+  })
+})
+
+describe('Database.js Proxy - buffer.flush()', () => {
+  it('should flush all buffered data for the table', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.buffer.where(1).increment('views', 5)
+    await DB.posts.buffer.where(2).update({title: 'Changed'})
+    await DB.posts.buffer.flush()
+
+    const row1 = await db('posts').where({id: 1}).first()
+    const row2 = await db('posts').where({id: 2}).first()
+    expect(row1.views).toBe(105)
+    expect(row2.title).toBe('Changed')
+  })
+})