odac 1.4.9 → 1.4.11

package/package.json

@@ -7,7 +7,7 @@
     "email": "mail@emre.red",
     "url": "https://emre.red"
   },
-  "version": "1.4.9",
+  "version": "1.4.11",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"
@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@tailwindcss/cli": "^4.1.18",
+    "esbuild": "^0.25.12",
     "knex": "^3.1.0",
     "lmdb": "^3.4.4",
     "tailwindcss": "^4.1.18"

package/src/Config.js

@@ -27,6 +27,13 @@ module.exports = {
     driver: 'memory',
     redis: 'default'
   },
+  js: {
+    target: 'es2020',
+    minify: true,
+    sourcemap: false,
+    bundle: true,
+    obfuscate: false
+  },
   debug: process.env.NODE_ENV !== 'production',
 
   init: function () {

package/src/Database/Migration.js

@@ -524,7 +524,7 @@ class Migration {
       if (!currentColumns[colName]) continue // New column, handled above
 
       if (this._columnNeedsAlter(colDef, currentColumns[colName])) {
-        ops.push({type: 'alter_column', column: colName, definition: colDef})
+        ops.push({type: 'alter_column', column: colName, definition: colDef, currentNullable: currentColumns[colName].nullable})
       }
     }
 
@@ -582,18 +582,35 @@ class Migration {
   /**
    * Checks if a column definition differs from the current DB metadata enough to warrant ALTER.
    * Conservative: only alters when there is a clear type or constraint mismatch.
+   * Why: Without type comparison, changing a column from e.g. 'string' to 'text' in the
+   * schema file would be silently ignored — the DB would never receive the ALTER.
    * @param {object} desired - Column definition from schema file
    * @param {object} current - Column metadata from introspection
    * @returns {boolean}
    */
   _columnNeedsAlter(desired, current) {
+    // Type mismatch — map the raw DB type back to an ODAC type and compare.
+    // nanoid is stored as 'string' (varchar) in the DB, so normalize before comparison.
+    // specificType uses the raw DB type directly (def.length holds the actual PG type),
+    // so compare against the raw introspected type instead of reverse-mapping.
+    if (desired.type === 'specificType') {
+      const rawDesired = (desired.length || '').toLowerCase().trim()
+      const rawCurrent = (current.type || '').toLowerCase().trim()
+      if (rawDesired !== rawCurrent) return true
+    } else {
+      const desiredType = desired.type === 'nanoid' ? 'string' : desired.type
+      const currentType = this._reverseMapType(current.type)
+      if (desiredType !== currentType) return true
+    }
+
     // Nullable mismatch
     if (desired.nullable === false && current.nullable === true) return true
     if (desired.nullable === true && current.nullable === false) return true
 
     // Length mismatch for string types — use Number() coercion since some
     // 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
+    if (desired.type !== 'specificType' && 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).
@@ -686,10 +703,17 @@ class Migration {
     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) {
+    // Separate primary key alter ops — PostgreSQL's ALTER COLUMN via Knex emits
+    // DROP NOT NULL before SET NOT NULL, which PG rejects on PK columns (42P16).
+    // These must be handled with raw ALTER COLUMN ... TYPE ... USING instead.
+    const isPG = knex.client?.config?.client === 'pg' || knex.client?.config?.client === 'postgresql'
+    const pkAlterOps = isPG ? columnOps.filter(op => op.type === 'alter_column' && op.definition.primary) : []
+    const batchOps = isPG ? columnOps.filter(op => !(op.type === 'alter_column' && op.definition.primary)) : columnOps
+
+    // Phase 1a: Batch column operations (non-PK alters + adds + drops)
+    if (batchOps.length > 0) {
       await knex.schema.alterTable(tableName, table => {
-        for (const op of columnOps) {
+        for (const op of batchOps) {
           switch (op.type) {
             case 'add_column':
               this._addColumn(table, op.column, op.definition)
@@ -698,13 +722,31 @@ class Migration {
               table.dropColumn(op.column)
               break
             case 'alter_column':
-              this._alterColumn(table, op.column, op.definition)
+              this._alterColumn(table, op.column, op.definition, op.currentNullable)
               break
           }
         }
       })
     }
 
+    // Phase 1b: Primary key column type changes on PostgreSQL — raw SQL.
+    // Why: Knex .alter() generates "DROP NOT NULL" + "SET NOT NULL" sequence,
+    // but PG forbids DROP NOT NULL on primary key columns. Raw ALTER COLUMN TYPE
+    // changes the type without touching the NOT NULL constraint.
+    for (const op of pkAlterOps) {
+      const sqlType = this._pgColumnType(op.definition)
+      await knex.raw(`ALTER TABLE ?? ALTER COLUMN ?? TYPE ${sqlType} USING ??::${sqlType}`, [tableName, op.column, op.column])
+
+      // Apply default value change if specified
+      if (op.definition.default !== undefined) {
+        if (op.definition.default === 'now()') {
+          await knex.raw(`ALTER TABLE ?? ALTER COLUMN ?? SET DEFAULT now()`, [tableName, op.column])
+        } else {
+          await knex.raw(`ALTER TABLE ?? ALTER COLUMN ?? SET DEFAULT ?`, [tableName, op.column, op.definition.default])
+        }
+      }
+    }
+
     // Phase 2: Foreign key operations — drop before add to handle replacements
     for (const op of fkOps) {
       if (op.type === 'drop_foreign_key') {
@@ -723,6 +765,51 @@ class Migration {
     }
   }
 
+  /**
+   * Maps an ODAC column definition to a PostgreSQL type string for raw ALTER COLUMN TYPE.
+   * @param {object} def - Column definition from schema
+   * @returns {string} PostgreSQL type name
+   */
+  _pgColumnType(def) {
+    switch (def.type) {
+      case 'nanoid':
+      case 'string':
+        return `varchar(${def.length || (def.type === 'nanoid' ? 21 : 255)})`
+      case 'text':
+        return 'text'
+      case 'integer':
+        return 'integer'
+      case 'bigInteger':
+        return 'bigint'
+      case 'boolean':
+        return 'boolean'
+      case 'float':
+        return 'double precision'
+      case 'decimal':
+        return `numeric(${def.precision || 10},${def.scale || 2})`
+      case 'uuid':
+        return 'uuid'
+      case 'json':
+        return 'json'
+      case 'jsonb':
+        return 'jsonb'
+      case 'timestamp':
+        return 'timestamp'
+      case 'datetime':
+        return 'timestamp'
+      case 'date':
+        return 'date'
+      case 'time':
+        return 'time'
+      case 'binary':
+        return 'bytea'
+      case 'specificType':
+        return def.length || def.specificType || def.type
+      default:
+        return def.type
+    }
+  }
+
   /**
    * Why: PostgreSQL introspection can miss existing constraints across PG versions
    * (int2vector cast edge cases, search_path mismatches, expression indexes).
@@ -902,6 +989,8 @@ class Migration {
         return table.uuid(colName)
       case 'enum':
         return table.enum(colName, def.values || [])
+      case 'specificType':
+        return table.specificType(colName, def.length || def.specificType || def.type)
       default:
         return table.specificType(colName, def.type)
     }
@@ -950,12 +1039,18 @@ class Migration {
    * @param {string} colName - Column name
    * @param {object} def - Column definition
    */
-  _alterColumn(table, colName, def) {
+  _alterColumn(table, colName, def, currentNullable) {
     const col = this._createColumnBuilder(table, colName, def)
     if (!col) return
 
+    // Knex .alter() defaults to nullable when no explicit nullable/notNullable is set,
+    // which generates "ALTER COLUMN ... DROP NOT NULL" — PostgreSQL rejects this on
+    // primary key columns (error 42P16). When the schema doesn't specify nullable,
+    // preserve the column's current DB state to avoid destructive no-op alterations.
     if (def.nullable === false) col.notNullable()
     else if (def.nullable === true) col.nullable()
+    else if (currentNullable === false) col.notNullable()
+    else if (currentNullable === true) col.nullable()
 
     if (def.default !== undefined) col.defaultTo(def.default)
 

package/src/Database/WriteBuffer.js

@@ -1,5 +1,6 @@
 'use strict'
 const cluster = require('node:cluster')
+const nanoid = require('./nanoid')
 
 /**
  * Write-Behind Cache with Write Coalescing for ODAC Database layer.
@@ -56,12 +57,15 @@ class WriteBuffer {
    * Why: Initializes the WriteBuffer. Called from Database.init() after Ipc is ready.
    * Primary: recovers LMDB checkpoint, starts flush/checkpoint timers.
    * All processes: stores connection references for flush DB writes.
+   * @param {object} connections - Knex connection map {connectionKey: knexInstance}
+   * @param {object} nanoidColumns - NanoID column metadata from DatabaseManager {connectionKey: {tableName: [{column, size}]}}
    */
-  async init(connections) {
+  async init(connections, nanoidColumns = {}) {
     if (this._initialized) return
     this._initialized = true
 
     this._connections = connections
+    this._nanoidColumns = nanoidColumns
     this._config = {...DEFAULT_CONFIG, ...Odac.Config.buffer}
 
     if (cluster.isPrimary) {
@@ -127,6 +131,16 @@ class WriteBuffer {
    * that are drained to the database in a single INSERT batch.
    */
   async insert(connection, table, row) {
+    // Auto-generate nanoid values for columns defined as type 'nanoid' in schema.
+    // Why: The Database.js proxy nanoid injection only covers direct QB calls.
+    // WriteBuffer bypasses that proxy — rows must be populated here before queuing.
+    const nanoidCols = this._nanoidColumns?.[connection]?.[table]
+    if (nanoidCols) {
+      for (const {column, size} of nanoidCols) {
+        if (!row[column]) row[column] = nanoid(size)
+      }
+    }
+
     const queueKey = `${connection}:${table}`
     const length = await Odac.Ipc.rpush(`wb:q:${queueKey}`, row)
     await Odac.Ipc.sadd('wb:idx:queues', queueKey)

package/src/Database.js

@@ -38,7 +38,7 @@ class DatabaseManager {
     readCache.init()
 
     // Initialize Write-Behind Cache (Primary holds state, Workers communicate via IPC)
-    await writeBuffer.init(this.connections)
+    await writeBuffer.init(this.connections, this._nanoidColumns)
   }
 
   /**
@@ -281,8 +281,22 @@ const tableProxyHandler = {
     }
 
     // Cache invalidation for insert — applied AFTER nanoid wrap so both paths are covered.
-    const currentInsert = qb.insert
-    qb.insert = wrapWithInvalidation(currentInsert)
+    // IMPORTANT: Unlike update/delete/truncate, insert is NOT terminal — it supports
+    // chaining (e.g. .insert().onConflict().merge()). So we cannot use wrapWithInvalidation
+    // which returns a plain thenable. Instead, override .then() on the query builder to
+    // inject invalidation at execution time, preserving the full Knex chain.
+    const insertBeforeInvalidation = qb.insert
+    qb.insert = function (...args) {
+      const result = insertBeforeInvalidation.apply(this, args)
+      const origThen = result.then
+      result.then = function (resolve, reject) {
+        return origThen
+          .call(this)
+          .then(res => readCache.invalidate(connectionKey, prop).then(() => res))
+          .then(resolve, reject)
+      }
+      return result
+    }
 
     const originalThen = qb.then
     qb.then = function (resolve, reject) {

package/src/Odac.js

@@ -156,6 +156,9 @@ module.exports = {
         _odac.write = function (value) {
           return _odac.Request.write(value)
         }
+        _odac.cache = function (seconds) {
+          return _odac.Request.cache(seconds)
+        }
         _odac.stream = function (input) {
           _odac.Request.clearTimeout()
           return new (require('./Stream'))(_odac.Request.req, _odac.Request.res, input, _odac)

package/src/Request.js

@@ -310,6 +310,27 @@ class OdacRequest {
     }
   }
 
+  // - SET PROXY CACHE
+  /**
+   * Enables ODAC Proxy caching for the current response.
+   * Sets the X-ODAC-Cache header with the specified TTL (in seconds)
+   * and updates Cache-Control to allow proxy caching.
+   *
+   * Why: Allows controllers to declaratively opt-in to proxy-level
+   * caching for static or semi-static HTML responses, offloading
+   * repeated rendering from the application server.
+   *
+   * @param {number} seconds - Cache TTL in seconds (must be a positive integer)
+   * @throws {TypeError} If seconds is not a positive integer
+   */
+  cache(seconds) {
+    if (!Number.isInteger(seconds) || seconds < 1) {
+      throw new TypeError('Odac.cache() requires a positive integer (seconds)')
+    }
+    this.header('X-ODAC-Cache', seconds)
+    this.header('Cache-Control', `public, max-age=${seconds}`)
+  }
+
   // - HTTP CODE
   status(code) {
     this.#status = code

package/template/{public/assets → view}/js/app.js

@@ -1,8 +1,14 @@
-/* global Odac */
 /**
  * ODAC Template - Client-Side Application
  *
- * This file demonstrates odac.js features including:
+ * This file is automatically compiled by ODAC's JS/TS pipeline.
+ * Write your frontend logic here — TypeScript (.ts) and plain JavaScript (.js) both work.
+ *
+ * - Place files in view/js/ to create entry points
+ * - Files starting with _ are ignored (use them as shared imports)
+ * - Output goes to public/assets/js/{name}.js
+ *
+ * Features demonstrated:
  * - AJAX page loading with Odac.loader() for smooth navigation
  * - History API integration
  * - Event delegation

package/test/Database/Migration/migrate_column.test.js

@@ -218,3 +218,146 @@ describe('Migration.migrate() - Foreign Key Diff', () => {
     warnSpy.mockRestore()
   })
 })
+
+describe('Migration.migrate() - Column Type Change', () => {
+  it('should alter a column when its type changes (string → text)', async () => {
+    writeSchema('articles', {columns: {id: {type: 'increments'}, body: {type: 'string'}}})
+    await Migration.migrate()
+
+    writeSchema('articles', {columns: {id: {type: 'increments'}, body: {type: 'text'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toEqual(expect.arrayContaining([expect.objectContaining({type: 'alter_column', column: 'body', table: 'articles'})]))
+  })
+
+  it('should alter a column when its type changes (integer → bigInteger)', async () => {
+    writeSchema('counters', {columns: {id: {type: 'increments'}, value: {type: 'integer'}}})
+    await Migration.migrate()
+
+    writeSchema('counters', {columns: {id: {type: 'increments'}, value: {type: 'bigInteger'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toEqual(expect.arrayContaining([expect.objectContaining({type: 'alter_column', column: 'value', table: 'counters'})]))
+  })
+
+  it('should not alter a column when its type is unchanged', async () => {
+    writeSchema('logs', {columns: {id: {type: 'increments'}, message: {type: 'text'}}})
+    await Migration.migrate()
+
+    writeSchema('logs', {columns: {id: {type: 'increments'}, message: {type: 'text'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toHaveLength(0)
+  })
+
+  it('should not produce alter for nanoid columns stored as string', async () => {
+    writeSchema('tokens', {columns: {id: {type: 'nanoid', length: 21}, name: {type: 'string'}}})
+    await Migration.migrate()
+
+    // Re-run with same schema — nanoid maps to varchar in DB, should not trigger false alter
+    writeSchema('tokens', {columns: {id: {type: 'nanoid', length: 21}, name: {type: 'string'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toHaveLength(0)
+  })
+})
+
+describe('Migration.migrate() - Nullable Preservation on Alter', () => {
+  it('should preserve NOT NULL when altering a column that has no explicit nullable in schema', async () => {
+    // Create table with a NOT NULL column
+    writeSchema('domains', {columns: {id: {type: 'increments'}, code: {type: 'string', nullable: false, default: 'A'}}})
+    await Migration.migrate()
+
+    // Change default value but omit nullable — should preserve NOT NULL from DB
+    writeSchema('domains', {columns: {id: {type: 'increments'}, code: {type: 'string', default: 'B'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toHaveLength(1)
+    expect(alterOps[0]).toMatchObject({column: 'code', currentNullable: false})
+  })
+
+  it('should preserve NULLABLE when altering a column that has no explicit nullable in schema', async () => {
+    // Create table with a NULLABLE column
+    writeSchema('logs', {columns: {id: {type: 'increments'}, note: {type: 'string', nullable: true, default: 'x'}}})
+    await Migration.migrate()
+
+    // Change default but omit nullable — should preserve nullable from DB
+    writeSchema('logs', {columns: {id: {type: 'increments'}, note: {type: 'string', default: 'y'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toHaveLength(1)
+    expect(alterOps[0]).toMatchObject({column: 'note', currentNullable: true})
+  })
+})
+
+describe('Migration - PG Primary Key Alter Safety', () => {
+  it('should carry primary flag in alter_column diff for PK columns', async () => {
+    // Create table with a primary nanoid column
+    writeSchema('domains', {columns: {id: {type: 'nanoid', primary: true}, name: {type: 'string'}}})
+    await Migration.migrate()
+
+    // Simulate a type mismatch by changing to a different length — triggers alter
+    writeSchema('domains', {columns: {id: {type: 'nanoid', primary: true, length: 30}, name: {type: 'string'}}})
+    const result = await Migration.migrate({dryRun: true})
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column' && op.column === 'id')
+
+    expect(alterOps).toHaveLength(1)
+    expect(alterOps[0].definition.primary).toBe(true)
+  })
+
+  it('should map ODAC types to PG types correctly via _pgColumnType', () => {
+    const m = Migration
+    expect(m._pgColumnType({type: 'nanoid'})).toBe('varchar(21)')
+    expect(m._pgColumnType({type: 'nanoid', length: 30})).toBe('varchar(30)')
+    expect(m._pgColumnType({type: 'string'})).toBe('varchar(255)')
+    expect(m._pgColumnType({type: 'string', length: 100})).toBe('varchar(100)')
+    expect(m._pgColumnType({type: 'text'})).toBe('text')
+    expect(m._pgColumnType({type: 'integer'})).toBe('integer')
+    expect(m._pgColumnType({type: 'bigInteger'})).toBe('bigint')
+    expect(m._pgColumnType({type: 'boolean'})).toBe('boolean')
+    expect(m._pgColumnType({type: 'uuid'})).toBe('uuid')
+    expect(m._pgColumnType({type: 'jsonb'})).toBe('jsonb')
+    expect(m._pgColumnType({type: 'timestamp'})).toBe('timestamp')
+    expect(m._pgColumnType({type: 'binary'})).toBe('bytea')
+    expect(m._pgColumnType({type: 'decimal'})).toBe('numeric(10,2)')
+    expect(m._pgColumnType({type: 'decimal', precision: 8, scale: 4})).toBe('numeric(8,4)')
+    expect(m._pgColumnType({type: 'specificType', length: 'text[]'})).toBe('text[]')
+  })
+})
+
+describe('Migration - specificType handling', () => {
+  it('should create a specificType column using the length field as the raw DB type', async () => {
+    writeSchema('events', {
+      columns: {
+        id: {type: 'increments'},
+        tags: {type: 'specificType', length: 'text'}
+      }
+    })
+    await Migration.migrate()
+
+    const info = await db('events').columnInfo()
+    expect(info).toHaveProperty('tags')
+  })
+
+  it('should not produce false alter for specificType when DB type matches', async () => {
+    writeSchema('events', {
+      columns: {
+        id: {type: 'increments'},
+        tags: {type: 'specificType', length: 'text'}
+      }
+    })
+    await Migration.migrate()
+
+    // Re-run with same schema — should not trigger alter
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toHaveLength(0)
+  })
+})

package/test/Database/WriteBuffer/insert.test.js

@@ -0,0 +1,118 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests WriteBuffer.insert() nanoid auto-generation.
+ * Why: WriteBuffer bypasses the Database.js proxy QB nanoid injection.
+ * Rows must be populated with nanoid values before being queued to IPC,
+ * otherwise flush writes to DB with a null primary key and violates NOT NULL.
+ */
+
+let knexLib, db
+
+beforeEach(async () => {
+  jest.resetModules()
+
+  knexLib = require('knex')
+  db = knexLib({client: 'sqlite3', connection: {filename: ':memory:'}, useNullAsDefault: true})
+
+  await db.schema.createTable('activity', table => {
+    table.string('id', 21).primary().notNullable()
+    table.string('user', 255).notNullable()
+    table.string('action', 50).notNullable()
+  })
+
+  await db.schema.createTable('events', table => {
+    table.string('eid', 12).primary().notNullable()
+    table.string('name', 100)
+  })
+
+  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()
+
+  const writeBuffer = require('../../../src/Database/WriteBuffer')
+  await writeBuffer.init(
+    {default: db},
+    {
+      default: {
+        activity: [{column: 'id', size: 21}],
+        events: [{column: 'eid', size: 12}]
+      }
+    }
+  )
+
+  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('WriteBuffer.insert() - NanoID auto-generation', () => {
+  it('should auto-generate nanoid for a column when not provided', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.activity.buffer.insert({user: 'alice', action: 'login'})
+    await DB.activity.buffer.flush()
+
+    const rows = await db('activity').select()
+    expect(rows).toHaveLength(1)
+    expect(rows[0].id).toBeTruthy()
+    expect(rows[0].id).toHaveLength(21)
+  })
+
+  it('should not overwrite an explicitly provided id', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.activity.buffer.insert({id: 'my-custom-id-00000', user: 'bob', action: 'logout'})
+    await DB.activity.buffer.flush()
+
+    const row = await db('activity').first()
+    expect(row.id).toBe('my-custom-id-00000')
+  })
+
+  it('should respect custom nanoid length from schema metadata', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.events.buffer.insert({name: 'page_view'})
+    await DB.events.buffer.flush()
+
+    const row = await db('events').first()
+    expect(row.eid).toBeTruthy()
+    expect(row.eid).toHaveLength(12)
+  })
+
+  it('should generate unique ids for multiple buffered inserts', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.activity.buffer.insert({user: 'alice', action: 'login'})
+    await DB.activity.buffer.insert({user: 'bob', action: 'view'})
+    await DB.activity.buffer.insert({user: 'carol', action: 'logout'})
+    await DB.activity.buffer.flush()
+
+    const rows = await db('activity').select()
+    expect(rows).toHaveLength(3)
+
+    const ids = rows.map(r => r.id)
+    expect(new Set(ids).size).toBe(3) // all unique
+    ids.forEach(id => expect(id).toHaveLength(21))
+  })
+})

package/test/Odac/cache.test.js

@@ -0,0 +1,54 @@
+const Odac = require('../../src/Odac')
+
+describe('Odac.cache()', () => {
+  let mockOdac
+
+  beforeEach(() => {
+    mockOdac = {
+      Config: {request: {timeout: 1000}},
+      Route: {routes: {www: {}}},
+      Storage: {get: jest.fn(), put: jest.fn()}
+    }
+    global.Odac = mockOdac
+    global.__dir = '/mock'
+  })
+
+  afterEach(() => {
+    delete global.Odac
+    delete global.__dir
+  })
+
+  it('should expose cache() as a shorthand on the instance', () => {
+    const mockReq = {
+      method: 'GET',
+      url: '/',
+      headers: {host: 'www.example.com'},
+      connection: {remoteAddress: '127.0.0.1'},
+      on: jest.fn()
+    }
+    const mockRes = {on: jest.fn(), writeHead: jest.fn(), end: jest.fn()}
+
+    const ctx = Odac.instance('id', mockReq, mockRes)
+
+    expect(typeof ctx.cache).toBe('function')
+  })
+
+  it('should delegate to Request.cache()', () => {
+    const mockReq = {
+      method: 'GET',
+      url: '/',
+      headers: {host: 'www.example.com'},
+      connection: {remoteAddress: '127.0.0.1'},
+      on: jest.fn()
+    }
+    const mockRes = {on: jest.fn(), writeHead: jest.fn(), end: jest.fn(), finished: false}
+
+    const ctx = Odac.instance('id', mockReq, mockRes)
+    ctx.cache(3600)
+
+    ctx.Request.print()
+    const headers = mockRes.writeHead.mock.calls[0][1]
+    expect(headers['X-ODAC-Cache']).toBe(3600)
+    expect(headers['Cache-Control']).toBe('public, max-age=3600')
+  })
+})