odac 1.4.7 → 1.4.9

package/test/Database/WriteBuffer/flush.test.js

@@ -0,0 +1,192 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests WriteBuffer flush operations: counter flush (batch UPDATE) and queue flush (batch INSERT).
+ * Why: Validates that buffered data is correctly persisted to the database,
+ * with proper transaction handling and error recovery.
+ */
+
+let knexLib, db, WriteBuffer
+
+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.integer('likes').defaultTo(0)
+    table.string('title', 255)
+  })
+
+  await db('posts').insert([
+    {id: 1, views: 100, likes: 10, title: 'First Post'},
+    {id: 2, views: 200, likes: 20, 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()
+
+  WriteBuffer = require('../../../src/Database/WriteBuffer')
+  await WriteBuffer.init({default: db})
+})
+
+afterEach(async () => {
+  await WriteBuffer.close()
+  await Odac.Ipc.close()
+  await db.destroy()
+  delete global.Odac
+})
+
+describe('WriteBuffer - Counter Flush', () => {
+  it('should persist accumulated deltas to the database', async () => {
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 5)
+    await WriteBuffer.increment('default', 'posts', 2, 'views', 10)
+
+    await WriteBuffer.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.views).toBe(210)
+  })
+
+  it('should flush multiple columns for the same row', async () => {
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 3)
+    await WriteBuffer.increment('default', 'posts', 1, 'likes', 7)
+
+    await WriteBuffer.flush()
+
+    const row = await db('posts').where({id: 1}).first()
+    expect(row.views).toBe(103)
+    expect(row.likes).toBe(17)
+  })
+
+  it('should clear counter index after successful flush', async () => {
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 5)
+    await WriteBuffer.flush()
+
+    // Counter index should be empty after flush
+    const remaining = await Odac.Ipc.smembers('wb:idx:counters')
+    expect(remaining).toHaveLength(0)
+  })
+
+  it('should update base after flush so subsequent reads are correct', async () => {
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 5)
+    await WriteBuffer.flush()
+
+    // New increment after flush
+    const result = await WriteBuffer.increment('default', 'posts', 1, 'views', 2)
+    expect(result).toBe(107) // base updated to 105, + 2
+
+    await WriteBuffer.flush()
+    const row = await db('posts').where({id: 1}).first()
+    expect(row.views).toBe(107)
+  })
+
+  it('should accumulate new deltas during flush correctly', async () => {
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 10)
+    await WriteBuffer.flush()
+
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 3)
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 2)
+    await WriteBuffer.flush()
+
+    const row = await db('posts').where({id: 1}).first()
+    expect(row.views).toBe(115) // 100 + 10 + 5
+  })
+
+  it('should scope flush to specific table when provided', async () => {
+    await db.schema.createTable('comments', table => {
+      table.integer('id').primary()
+      table.integer('votes').defaultTo(0)
+    })
+    await db('comments').insert({id: 1, votes: 50})
+
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 5)
+    await WriteBuffer.increment('default', 'comments', 1, 'votes', 3)
+
+    // Flush only posts
+    await WriteBuffer.flush('default', 'posts')
+
+    const post = await db('posts').where({id: 1}).first()
+    const comment = await db('comments').where({id: 1}).first()
+    expect(post.views).toBe(105) // Flushed
+    expect(comment.votes).toBe(50) // Not flushed
+  })
+})
+
+describe('WriteBuffer - Queue Flush (Batch Insert)', () => {
+  it('should batch insert queued rows', async () => {
+    await db.schema.createTable('activity_log', table => {
+      table.increments('id')
+      table.integer('user_id')
+      table.string('action', 50)
+    })
+
+    await WriteBuffer.insert('default', 'activity_log', {user_id: 1, action: 'view'})
+    await WriteBuffer.insert('default', 'activity_log', {user_id: 2, action: 'click'})
+    await WriteBuffer.insert('default', 'activity_log', {user_id: 1, action: 'scroll'})
+
+    await WriteBuffer.flush()
+
+    const rows = await db('activity_log').select()
+    expect(rows).toHaveLength(3)
+    expect(rows[0].action).toBe('view')
+    expect(rows[1].action).toBe('click')
+    expect(rows[2].action).toBe('scroll')
+  })
+
+  it('should clear queue after successful flush', async () => {
+    await db.schema.createTable('events', table => {
+      table.increments('id')
+      table.string('type', 50)
+    })
+
+    await WriteBuffer.insert('default', 'events', {type: 'pageview'})
+    await WriteBuffer.flush()
+
+    const queue = await Odac.Ipc.lrange('wb:q:default:events', 0, -1)
+    expect(queue).toHaveLength(0)
+  })
+
+  it('should handle empty queues gracefully', async () => {
+    await expect(WriteBuffer.flush()).resolves.not.toThrow()
+  })
+
+  it('should auto-flush when maxQueueSize is reached', async () => {
+    await db.schema.createTable('logs', table => {
+      table.increments('id')
+      table.string('msg', 50)
+    })
+
+    // Set low threshold for testing
+    WriteBuffer._config.maxQueueSize = 3
+
+    await WriteBuffer.insert('default', 'logs', {msg: 'a'})
+    await WriteBuffer.insert('default', 'logs', {msg: 'b'})
+    await WriteBuffer.insert('default', 'logs', {msg: 'c'}) // Triggers auto-flush
+
+    // Wait a tick for async auto-flush
+    await new Promise(r => setTimeout(r, 50))
+
+    const rows = await db('logs').select()
+    expect(rows.length).toBeGreaterThanOrEqual(3)
+  })
+})

package/test/Database/WriteBuffer/get.test.js

@@ -0,0 +1,72 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests WriteBuffer.get().
+ * Why: Validates that get() returns the accurate current value (DB base + buffered delta)
+ * without flushing to the database.
+ */
+
+let knexLib, db, WriteBuffer
+
+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('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()
+
+  WriteBuffer = require('../../../src/Database/WriteBuffer')
+  await WriteBuffer.init({default: db})
+})
+
+afterEach(async () => {
+  await WriteBuffer.close()
+  await Odac.Ipc.close()
+  await db.destroy()
+  delete global.Odac
+})
+
+describe('WriteBuffer - get()', () => {
+  it('should return base value from DB when no buffer exists', async () => {
+    const result = await WriteBuffer.get('default', 'posts', 1, 'views')
+    expect(result).toBe(100)
+  })
+
+  it('should return base + delta when buffer exists', async () => {
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 7)
+    const result = await WriteBuffer.get('default', 'posts', 1, 'views')
+    expect(result).toBe(107)
+  })
+
+  it('should return 0 for non-existent rows', async () => {
+    const result = await WriteBuffer.get('default', 'posts', 999, 'views')
+    expect(result).toBe(0)
+  })
+})

package/test/Database/WriteBuffer/increment.test.js

@@ -0,0 +1,118 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests WriteBuffer.increment().
+ * Why: Validates that the Write-Behind Cache correctly accumulates deltas
+ * and returns accurate current totals (base + buffered delta) without a DB write.
+ */
+
+let knexLib, db, WriteBuffer
+
+beforeEach(async () => {
+  jest.resetModules()
+
+  knexLib = require('knex')
+  db = knexLib({client: 'sqlite3', connection: {filename: ':memory:'}, useNullAsDefault: true})
+
+  // Create test table
+  await db.schema.createTable('posts', table => {
+    table.integer('id').primary()
+    table.integer('views').defaultTo(0)
+    table.integer('likes').defaultTo(0)
+    table.string('title', 255)
+  })
+
+  // Seed data
+  await db('posts').insert([
+    {id: 1, views: 100, likes: 10, title: 'First Post'},
+    {id: 2, views: 200, likes: 20, title: 'Second Post'}
+  ])
+
+  // Mock cluster as primary
+  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()
+
+  WriteBuffer = require('../../../src/Database/WriteBuffer')
+  await WriteBuffer.init({default: db})
+})
+
+afterEach(async () => {
+  await WriteBuffer.close()
+  await Odac.Ipc.close()
+  await db.destroy()
+  delete global.Odac
+})
+
+describe('WriteBuffer - increment()', () => {
+  it('should increment and return base + delta on first call', async () => {
+    const result = await WriteBuffer.increment('default', 'posts', 1, 'views')
+    expect(result).toBe(101) // DB base 100 + delta 1
+  })
+
+  it('should accumulate multiple increments correctly', async () => {
+    await WriteBuffer.increment('default', 'posts', 1, 'views')
+    await WriteBuffer.increment('default', 'posts', 1, 'views')
+    const result = await WriteBuffer.increment('default', 'posts', 1, 'views')
+    expect(result).toBe(103) // 100 + 3
+  })
+
+  it('should support custom delta values', async () => {
+    const result = await WriteBuffer.increment('default', 'posts', 1, 'views', 5)
+    expect(result).toBe(105) // 100 + 5
+  })
+
+  it('should handle different columns independently', async () => {
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 3)
+    await WriteBuffer.increment('default', 'posts', 1, 'likes', 2)
+
+    const views = await WriteBuffer.get('default', 'posts', 1, 'views')
+    const likes = await WriteBuffer.get('default', 'posts', 1, 'likes')
+
+    expect(views).toBe(103) // 100 + 3
+    expect(likes).toBe(12) // 10 + 2
+  })
+
+  it('should handle different rows independently', async () => {
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 5)
+    await WriteBuffer.increment('default', 'posts', 2, 'views', 10)
+
+    const row1 = await WriteBuffer.get('default', 'posts', 1, 'views')
+    const row2 = await WriteBuffer.get('default', 'posts', 2, 'views')
+
+    expect(row1).toBe(105) // 100 + 5
+    expect(row2).toBe(210) // 200 + 10
+  })
+
+  it('should handle composite where keys', async () => {
+    // Create a table with composite key
+    await db.schema.createTable('post_stats', table => {
+      table.integer('post_id')
+      table.string('date', 10)
+      table.integer('views').defaultTo(0)
+      table.primary(['post_id', 'date'])
+    })
+    await db('post_stats').insert({post_id: 1, date: '2026-04-01', views: 50})
+
+    const result = await WriteBuffer.increment('default', 'post_stats', {post_id: 1, date: '2026-04-01'}, 'views', 3)
+    expect(result).toBe(53) // 50 + 3
+  })
+
+  it('should return 0 + delta for non-existent rows', async () => {
+    const result = await WriteBuffer.increment('default', 'posts', 999, 'views')
+    expect(result).toBe(1) // 0 base + 1
+  })
+})

package/test/Database/WriteBuffer/update.test.js

@@ -0,0 +1,178 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests WriteBuffer.update() — last-write-wins coalescing.
+ * Why: Validates that repeated updates to the same row collapse into one UPDATE query,
+ * and that different rows/tables are isolated correctly.
+ */
+
+let knexLib, db, WriteBuffer
+
+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)
+    table.string('slug', 255)
+  })
+
+  await db('posts').insert([
+    {id: 1, views: 100, title: 'First Post', slug: 'first-post'},
+    {id: 2, views: 200, title: 'Second Post', slug: '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()
+
+  WriteBuffer = require('../../../src/Database/WriteBuffer')
+  await WriteBuffer.init({default: db})
+})
+
+afterEach(async () => {
+  await WriteBuffer.close()
+  await Odac.Ipc.close()
+  await db.destroy()
+  delete global.Odac
+})
+
+describe('WriteBuffer - update()', () => {
+  it('should buffer and flush a single update', async () => {
+    await WriteBuffer.update('default', 'posts', 1, {title: 'Updated Title'})
+    await WriteBuffer.flush()
+
+    const row = await db('posts').where({id: 1}).first()
+    expect(row.title).toBe('Updated Title')
+    expect(row.slug).toBe('first-post') // Untouched
+  })
+
+  it('should merge multiple updates (last-write-wins)', async () => {
+    await WriteBuffer.update('default', 'posts', 1, {title: 'First Update'})
+    await WriteBuffer.update('default', 'posts', 1, {title: 'Second Update'})
+    await WriteBuffer.flush()
+
+    const row = await db('posts').where({id: 1}).first()
+    expect(row.title).toBe('Second Update')
+  })
+
+  it('should merge different columns from multiple updates', async () => {
+    await WriteBuffer.update('default', 'posts', 1, {title: 'New Title'})
+    await WriteBuffer.update('default', 'posts', 1, {slug: 'new-slug'})
+    await WriteBuffer.flush()
+
+    const row = await db('posts').where({id: 1}).first()
+    expect(row.title).toBe('New Title')
+    expect(row.slug).toBe('new-slug')
+  })
+
+  it('should handle different rows independently', async () => {
+    await WriteBuffer.update('default', 'posts', 1, {title: 'Row 1'})
+    await WriteBuffer.update('default', 'posts', 2, {title: 'Row 2'})
+    await WriteBuffer.flush()
+
+    const row1 = await db('posts').where({id: 1}).first()
+    const row2 = await db('posts').where({id: 2}).first()
+    expect(row1.title).toBe('Row 1')
+    expect(row2.title).toBe('Row 2')
+  })
+
+  it('should handle composite where key', async () => {
+    await db.schema.createTable('user_prefs', table => {
+      table.string('pref_key', 50)
+      table.integer('user_id')
+      table.string('value', 255)
+      table.primary(['pref_key', 'user_id'])
+    })
+    await db('user_prefs').insert({pref_key: 'theme', user_id: 1, value: 'light'})
+
+    await WriteBuffer.update('default', 'user_prefs', {pref_key: 'theme', user_id: 1}, {value: 'dark'})
+    await WriteBuffer.flush()
+
+    const row = await db('user_prefs').where({pref_key: 'theme', user_id: 1}).first()
+    expect(row.value).toBe('dark')
+  })
+
+  it('should return true when buffered', async () => {
+    const result = await WriteBuffer.update('default', 'posts', 1, {title: 'Test'})
+    expect(result).toBe(true)
+  })
+
+  it('should clear update index after successful flush', async () => {
+    await WriteBuffer.update('default', 'posts', 1, {title: 'Test'})
+    await WriteBuffer.flush()
+
+    const remaining = await Odac.Ipc.smembers('wb:idx:updates')
+    expect(remaining).toHaveLength(0)
+  })
+
+  it('should combine increment and update on same row during flush', async () => {
+    await WriteBuffer.increment('default', 'posts', 1, 'views', 5)
+    await WriteBuffer.update('default', 'posts', 1, {title: 'Combo Test'})
+    await WriteBuffer.flush()
+
+    const row = await db('posts').where({id: 1}).first()
+    expect(row.views).toBe(105)
+    expect(row.title).toBe('Combo Test')
+  })
+
+  it('should handle different tables independently', async () => {
+    await db.schema.createTable('comments', table => {
+      table.integer('id').primary()
+      table.string('body', 255)
+    })
+    await db('comments').insert({id: 1, body: 'Original'})
+
+    await WriteBuffer.update('default', 'posts', 1, {title: 'Post Updated'})
+    await WriteBuffer.update('default', 'comments', 1, {body: 'Comment Updated'})
+    await WriteBuffer.flush()
+
+    const post = await db('posts').where({id: 1}).first()
+    const comment = await db('comments').where({id: 1}).first()
+    expect(post.title).toBe('Post Updated')
+    expect(comment.body).toBe('Comment Updated')
+  })
+
+  it('should scope flush to specific table when provided', async () => {
+    await db.schema.createTable('comments', table => {
+      table.integer('id').primary()
+      table.string('body', 255)
+    })
+    await db('comments').insert({id: 1, body: 'Original'})
+
+    await WriteBuffer.update('default', 'posts', 1, {title: 'Post Updated'})
+    await WriteBuffer.update('default', 'comments', 1, {body: 'Comment Updated'})
+
+    // Flush only posts
+    await WriteBuffer.flush('default', 'posts')
+
+    const post = await db('posts').where({id: 1}).first()
+    const comment = await db('comments').where({id: 1}).first()
+    expect(post.title).toBe('Post Updated')
+    expect(comment.body).toBe('Original') // Not flushed
+  })
+
+  it('should not modify DB before flush is called', async () => {
+    await WriteBuffer.update('default', 'posts', 1, {title: 'Buffered Only'})
+
+    const row = await db('posts').where({id: 1}).first()
+    expect(row.title).toBe('First Post') // Still original
+  })
+})

package/test/Database/insert.test.js

@@ -0,0 +1,98 @@
+'use strict'
+
+const knexLib = require('knex')
+
+/**
+ * Tests the wrapWithInvalidation thenable returned by write operations (insert/update/delete/truncate).
+ * Why: Ensures the thenable is fully Promise-compatible — supporting both await and .catch() chaining.
+ * This prevents TypeError when consumers call .insert(...).catch() or .update(...).catch().
+ */
+
+let db
+
+beforeEach(async () => {
+  db = knexLib({client: 'sqlite3', connection: {filename: ':memory:'}, useNullAsDefault: true})
+  await db.schema.createTable('tokens', table => {
+    table.string('id', 21).primary()
+    table.string('user', 100)
+    table.string('token_x', 64)
+  })
+})
+
+afterEach(async () => {
+  await db.destroy()
+  jest.resetModules()
+})
+
+describe('Database.js - wrapWithInvalidation thenable', () => {
+  it('insert().catch() should be a function', () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    const result = DB.tokens.insert({id: 'test1', user: 'u1', token_x: 'tx1'})
+    expect(typeof result.catch).toBe('function')
+  })
+
+  it('insert().catch() should resolve on success', async () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    const result = await DB.tokens.insert({id: 'test2', user: 'u2', token_x: 'tx2'}).catch(() => false)
+    expect(result).not.toBe(false)
+
+    const rows = await db('tokens').where('id', 'test2')
+    expect(rows).toHaveLength(1)
+    expect(rows[0].user).toBe('u2')
+  })
+
+  it('insert().catch() should catch errors gracefully', async () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    // Insert first row
+    await DB.tokens.insert({id: 'dup1', user: 'u1', token_x: 'tx1'})
+
+    // Duplicate primary key — should trigger catch
+    const result = await DB.tokens.insert({id: 'dup1', user: 'u2', token_x: 'tx2'}).catch(() => 'caught')
+    expect(result).toBe('caught')
+  })
+
+  it('update().catch() should be a function', () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    const result = DB.tokens.where('id', 'x').update({user: 'new'})
+    expect(typeof result.catch).toBe('function')
+  })
+
+  it('delete().catch() should be a function', () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    const result = DB.tokens.where('id', 'x').delete()
+    expect(typeof result.catch).toBe('function')
+  })
+
+  it('insert() should work with await (no .catch)', async () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    await DB.tokens.insert({id: 'await1', user: 'u_await', token_x: 'tx_await'})
+
+    const rows = await db('tokens').where('id', 'await1')
+    expect(rows).toHaveLength(1)
+    expect(rows[0].user).toBe('u_await')
+  })
+})