@proteinjs/db 1.7.0 → 1.8.0

package/src/Table.ts

@@ -42,6 +42,27 @@ export const getColumnByName = (table: Table<any>, columnName: string) => {
   return null;
 };
 
+export const addDefaultFieldValues = async (table: Table<any>, record: any) => {
+  for (const columnPropertyName in table.columns) {
+    const column = (table.columns as any)[columnPropertyName] as Column<any, any>;
+    if (
+      column.options?.defaultValue &&
+      (typeof record[columnPropertyName] === 'undefined' || column.options?.forceDefaultValue)
+    ) {
+      record[columnPropertyName] = await column.options.defaultValue(record);
+    }
+  }
+};
+
+export const addUpdateFieldValues = async (table: Table<any>, record: any) => {
+  for (const columnPropertyName in table.columns) {
+    const column = (table.columns as any)[columnPropertyName] as Column<any, any>;
+    if (column.options?.updateValue) {
+      record[columnPropertyName] = await column.options.updateValue(record);
+    }
+  }
+};
+
 /**
  * primary key is `id`
  */
@@ -112,6 +133,8 @@ export type ColumnOptions = {
   nullable?: boolean;
   /** Value stored on insert */
   defaultValue?: (insertObj: any) => Promise<any>;
+  /** If true, the `defaultValue` function will always provide the value and override any existing value */
+  forceDefaultValue?: boolean;
   /** Value stored on update */
   updateValue?: (updateObj: any) => Promise<any>;
   /** Add conditions to query; called on every query of this table */

package/src/services/TransactionRunnerService.ts

@@ -0,0 +1,10 @@
+import { Service, serviceFactory } from '@proteinjs/service';
+import { Operation } from '../transaction/Transaction';
+
+export const getTransactionRunnerService = serviceFactory<TransactionRunnerService>(
+  '@proteinjs/db/TransactionRunnerService'
+);
+
+export interface TransactionRunnerService extends Service {
+  run(ops: Operation<any>[]): Promise<void>;
+}

package/src/transaction/Transaction.ts

@@ -0,0 +1,186 @@
+import { Record } from '../Record';
+import { DbService, ObjectQuery } from '../services/DbService';
+import { getTransactionRunner } from './TransactionRunner';
+import { addDefaultFieldValues, Table } from '../Table';
+import { isInstanceOf } from '@proteinjs/util';
+import { QueryBuilder } from '@proteinjs/db-query';
+
+export type OperationQueue<R extends Record = Record> = {
+  insert: (...args: Parameters<DbService<R>['insert']>) => Promise<R>;
+  update: (...args: Parameters<DbService<R>['update']>) => void;
+  delete: (...args: Parameters<DbService<R>['delete']>) => void;
+};
+
+export type Operation<R extends Record = Record> = {
+  name: 'insert' | 'update' | 'delete';
+  args: Parameters<DbService<R>['insert']> | Parameters<DbService<R>['update']> | Parameters<DbService<R>['delete']>;
+};
+
+const hasAllProperties = (a: any, b: any) => Object.entries(b).every(([key, val]) => a[key] === val);
+
+/**
+ * A queue of db write operations that are executed sequentially (not batched) as a single transaction when `run` is called.
+ *
+ * Intended to be used on the client to decrease network calls when performing an atomic unit of db write operations.
+ *
+ * A more robust server-side transaction api is available via `Db.runTransaction`.
+ */
+export class Transaction implements OperationQueue {
+  /** Operations to be run in sequence in a transaction when `run` is called. */
+  ops: Operation<any>[] = [];
+
+  /**
+   * Local cache of tables.
+   *
+   * Data will be updated as operations are queued.
+   */
+  db: { [table: string]: { [id: string]: any } } = {};
+
+  constructor(
+    private onInsert?: (table: Table<any>, record: any) => void,
+    private onUpdate?: (table: Table<any>, prevRecord: any, currentRecord: any) => void,
+    private onDelete?: (table: Table<any>, record: any) => void
+  ) {}
+
+  /**
+   * @returns locally cached records for table
+   */
+  recordMap(table: string) {
+    if (!this.db[table]) {
+      this.db[table] = {};
+    }
+
+    return this.db[table];
+  }
+
+  /**
+   * Queue an insert.
+   */
+  async insert<R extends Record = Record>(...args: Parameters<DbService<R>['insert']>): Promise<R> {
+    const [table, record] = args;
+    const recordCopy = Object.assign({}, record) as R;
+    await addDefaultFieldValues(table, recordCopy);
+    const recordMap = this.recordMap(table.name);
+    if (recordMap[recordCopy.id]) {
+      throw new Error(`Attempting to insert with duplicate id: ${recordCopy.id}, record already exists`);
+    }
+
+    recordMap[recordCopy.id] = recordCopy;
+    if (this.onInsert) {
+      this.onInsert(table, recordCopy);
+    }
+
+    this.ops.push({ name: 'insert', args: [table, recordCopy] });
+
+    return recordCopy;
+  }
+
+  /**
+   * Queue an update.
+   *
+   * Updates are performed in-place on the existing object to ensure all references
+   * receive the changes.
+   *
+   * If a `QueryBuilder` is passed in for `query`, changes will not be made to the cached `db`.
+   * Passing in an `ObjectQuery` will update the cached `db`.
+   */
+  update<R extends Record = Record>(...args: Parameters<DbService<R>['update']>): void {
+    const [table, record, query] = args;
+    if (!query && !record.id) {
+      throw new Error(`Update must be called with either a Query or a record with an id property`);
+    }
+
+    if (record.id) {
+      const recordMap = this.recordMap(table.name);
+      const existingRecord = recordMap[record.id];
+      const prevRecord = { ...existingRecord };
+      if (existingRecord) {
+        Object.keys(record).forEach((key) => {
+          if (key !== 'id') {
+            existingRecord[key] = record[key as keyof R];
+          }
+        });
+        if (this.onUpdate) {
+          this.onUpdate(table, prevRecord, existingRecord);
+        }
+      } else {
+        throw new Error(`Attempting to update record not in the cached db`);
+      }
+    } else if (query && !isInstanceOf(query, QueryBuilder)) {
+      const objectQuery = query as ObjectQuery<any>;
+      const recordMap = this.recordMap(table.name);
+      if (objectQuery.id && recordMap[objectQuery.id]) {
+        const existingRecord = recordMap[objectQuery.id];
+        const prevRecord = { ...existingRecord };
+        Object.keys(record).forEach((key) => {
+          if (key !== 'id') {
+            existingRecord[key] = record[key as keyof R];
+          }
+        });
+        if (this.onUpdate) {
+          this.onUpdate(table, prevRecord, existingRecord);
+        }
+      } else {
+        for (const existingRecord of Object.values(recordMap)) {
+          if (hasAllProperties(existingRecord, objectQuery)) {
+            const prevRecord = { ...existingRecord };
+            Object.keys(record).forEach((key) => {
+              if (key !== 'id') {
+                existingRecord[key] = record[key as keyof R];
+              }
+            });
+            if (this.onUpdate) {
+              this.onUpdate(table, prevRecord, existingRecord);
+            }
+          }
+        }
+      }
+    }
+
+    this.ops.push({ name: 'update', args });
+  }
+
+  /**
+   * Queue a delete.
+   *
+   * If a `QueryBuilder` is passed in for `query`, changes will not be made to the cached `db`.
+   * Passing in an `ObjectQuery` will update the cached `db`.
+   */
+  delete<R extends Record = Record>(...args: Parameters<DbService<R>['delete']>): void {
+    const [table, query] = args;
+    if (!isInstanceOf(query, QueryBuilder)) {
+      const objectQuery = query as ObjectQuery<any>;
+      const recordMap = this.recordMap(table.name);
+      if (objectQuery.id) {
+        if (this.onDelete && recordMap[objectQuery.id]) {
+          this.onDelete(table, recordMap[objectQuery.id]);
+        }
+        delete recordMap[objectQuery.id];
+      } else {
+        for (const record of Object.values(recordMap)) {
+          if (hasAllProperties(record, objectQuery)) {
+            if (this.onDelete && recordMap[record.id]) {
+              this.onDelete(table, recordMap[record.id]);
+            }
+            delete recordMap[record.id];
+          }
+        }
+      }
+    }
+
+    this.ops.push({ name: 'delete', args });
+  }
+
+  /**
+   * Run the operations in order (not a batch), as a single transaction.
+   */
+  async run(): Promise<void> {
+    if (this.ops.length === 0) {
+      return;
+    }
+
+    const runner = getTransactionRunner();
+    await runner.run(this.ops);
+    this.ops = [];
+  }
+}

package/src/transaction/TransactionRunner.ts

@@ -0,0 +1,18 @@
+import { getDb } from '../Db';
+import { TransactionRunnerService, getTransactionRunnerService } from '../services/TransactionRunnerService';
+import { Operation } from './Transaction';
+
+export const getTransactionRunner = () =>
+  typeof self === 'undefined' ? new TransactionRunner() : (getTransactionRunnerService() as TransactionRunner);
+
+export class TransactionRunner implements TransactionRunnerService {
+  async run(ops: Operation<any>[]): Promise<void> {
+    const db = getDb();
+
+    await db.runTransaction(async () => {
+      for (const op of ops) {
+        await (db[op.name] as Function)(...op.args);
+      }
+    });
+  }
+}

package/test/TransactionDb.test.ts

@@ -0,0 +1,335 @@
+import moment from 'moment';
+import { Transaction } from '../src/transaction/Transaction';
+import { Table } from '../src/Table';
+import { Record, withRecordColumns } from '../src/Record';
+import { StringColumn, BooleanColumn, DateColumn } from '../src/Columns';
+
+interface Employee extends Record {
+  name: string;
+  department?: string;
+  jobTitle?: string | null;
+  isRemote?: boolean;
+  startDate?: Date;
+  object?: string;
+}
+
+class EmployeeTestTable extends Table<Employee> {
+  name = 'db_test_employee';
+  columns = withRecordColumns<Employee>({
+    name: new StringColumn('name'),
+    department: new StringColumn('department'),
+    isRemote: new BooleanColumn('is_remote'),
+    jobTitle: new StringColumn('job_title'),
+    startDate: new DateColumn('start_date'),
+    object: new StringColumn('object'),
+  });
+}
+
+describe('Transaction db', () => {
+  const employeeTable = new EmployeeTestTable() as Table<Employee>;
+  let transaction: Transaction;
+  let insertCallback: jest.Mock;
+  let updateCallback: jest.Mock;
+  let deleteCallback: jest.Mock;
+
+  beforeEach(() => {
+    insertCallback = jest.fn();
+    updateCallback = jest.fn();
+    deleteCallback = jest.fn();
+    transaction = new Transaction(insertCallback, updateCallback, deleteCallback);
+  });
+
+  describe('insert', () => {
+    it('should add record to cached db and queue insert operation', async () => {
+      const record: Partial<Employee> = {
+        name: 'John Doe',
+        department: 'Engineering',
+        jobTitle: 'Software Engineer',
+        isRemote: true,
+        startDate: new Date('2024-01-01'),
+      };
+
+      const result = await transaction.insert(employeeTable, record);
+
+      // Verify record was added to cache
+      expect(transaction.recordMap(employeeTable.name)[result.id]).toEqual({
+        id: expect.any(String),
+        name: 'John Doe',
+        department: 'Engineering',
+        jobTitle: 'Software Engineer',
+        isRemote: true,
+        startDate: expect.any(Date),
+        created: expect.any(moment),
+        updated: expect.any(moment),
+      });
+
+      // Verify operation was queued
+      expect(transaction.ops).toHaveLength(1);
+      expect(transaction.ops[0]).toEqual({
+        name: 'insert',
+        args: [employeeTable, result],
+      });
+
+      // Verify callback was called
+      expect(insertCallback).toHaveBeenCalledTimes(1);
+      expect(insertCallback).toHaveBeenCalledWith(employeeTable, result);
+    });
+
+    it('should throw error when inserting record with duplicate id', async () => {
+      const record: Partial<Employee> = {
+        id: 'test-id',
+        name: 'John Doe',
+        department: 'Engineering',
+      };
+      await transaction.insert(employeeTable, record);
+
+      await expect(transaction.insert(employeeTable, record)).rejects.toThrow(
+        'Attempting to insert with duplicate id: test-id, record already exists'
+      );
+    });
+  });
+
+  describe('update', () => {
+    it('should update record in cached db by id and queue update operation', async () => {
+      // First insert a record
+      const original = await transaction.insert(employeeTable, {
+        name: 'John Doe',
+        department: 'Engineering',
+        isRemote: true,
+      });
+
+      // Update the record
+      const updates = {
+        id: original.id,
+        department: 'Product',
+        jobTitle: 'Product Manager',
+      };
+      transaction.update(employeeTable, updates);
+
+      // Verify cache was updated
+      const cached = transaction.recordMap(employeeTable.name)[original.id];
+      expect(cached).toEqual({
+        id: original.id,
+        name: 'John Doe',
+        department: 'Product',
+        jobTitle: 'Product Manager',
+        isRemote: true,
+        created: expect.any(moment),
+        updated: expect.any(moment),
+      });
+
+      // Verify operation was queued
+      expect(transaction.ops[1]).toEqual({
+        name: 'update',
+        args: [employeeTable, updates],
+      });
+
+      // Verify callback was called
+      expect(updateCallback).toHaveBeenCalledTimes(1);
+      expect(updateCallback).toHaveBeenCalledWith(
+        employeeTable,
+        {
+          id: original.id,
+          name: 'John Doe',
+          department: 'Engineering',
+          isRemote: true,
+          created: expect.any(moment),
+          updated: expect.any(moment),
+        },
+        cached
+      );
+    });
+
+    it('should update records in cached db by object query and queue update operation', async () => {
+      // Insert two records
+      await transaction.insert(employeeTable, {
+        name: 'John Doe',
+        department: 'Engineering',
+        isRemote: true,
+      });
+      await transaction.insert(employeeTable, {
+        name: 'Jane Doe',
+        department: 'Engineering',
+        isRemote: false,
+      });
+
+      // Update all records in Engineering department
+      const updates = { jobTitle: 'Software Engineer' };
+      transaction.update(employeeTable, updates, { department: 'Engineering' });
+
+      // Verify all matching records were updated in cache
+      const cachedRecords = Object.values(transaction.recordMap(employeeTable.name));
+      cachedRecords.forEach((record) => {
+        expect(record.jobTitle).toBe('Software Engineer');
+      });
+
+      // Verify operation was queued
+      expect(transaction.ops[2]).toEqual({
+        name: 'update',
+        args: [employeeTable, updates, { department: 'Engineering' }],
+      });
+    });
+
+    it('should throw error when updating non-existent record by id', () => {
+      const update = { id: 'non-existent', name: 'John' };
+
+      expect(() => transaction.update(employeeTable, update)).toThrow(
+        'Attempting to update record not in the cached db'
+      );
+    });
+  });
+
+  describe('delete', () => {
+    it('should remove record from cached db by id and queue delete operation', async () => {
+      const record = await transaction.insert(employeeTable, {
+        name: 'John Doe',
+        department: 'Engineering',
+      });
+
+      transaction.delete(employeeTable, { id: record.id });
+
+      expect(transaction.recordMap(employeeTable.name)[record.id]).toBeUndefined();
+      expect(transaction.ops[1]).toEqual({
+        name: 'delete',
+        args: [employeeTable, { id: record.id }],
+      });
+      expect(deleteCallback).toHaveBeenCalledTimes(1);
+      expect(deleteCallback).toHaveBeenCalledWith(employeeTable, record);
+    });
+
+    it('should remove records from cached db by object query and queue delete operation', async () => {
+      await transaction.insert(employeeTable, {
+        name: 'John Doe',
+        department: 'Engineering',
+        isRemote: true,
+      });
+      await transaction.insert(employeeTable, {
+        name: 'Jane Doe',
+        department: 'Engineering',
+        isRemote: true,
+      });
+
+      transaction.delete(employeeTable, { department: 'Engineering' });
+
+      const cachedRecords = Object.values(transaction.recordMap(employeeTable.name));
+      expect(cachedRecords).toHaveLength(0);
+      expect(transaction.ops[2]).toEqual({
+        name: 'delete',
+        args: [employeeTable, { department: 'Engineering' }],
+      });
+    });
+  });
+
+  describe('cache integrity', () => {
+    it('should preserve unspecified fields during partial updates', async () => {
+      // Insert a record with multiple fields
+      const record = await transaction.insert(employeeTable, {
+        name: 'John Doe',
+        department: 'Engineering',
+        jobTitle: 'Software Engineer',
+        isRemote: true,
+        startDate: new Date('2024-01-01'),
+      });
+
+      // Perform a partial update
+      transaction.update(employeeTable, {
+        id: record.id,
+        department: 'Product',
+      });
+
+      // Verify that only the specified field was updated and others remain unchanged
+      const cached = transaction.recordMap(employeeTable.name)[record.id];
+      expect(cached).toEqual({
+        id: record.id,
+        name: 'John Doe',
+        department: 'Product', // Only this field should change
+        jobTitle: 'Software Engineer',
+        isRemote: true,
+        startDate: expect.any(Date),
+        created: expect.any(moment),
+        updated: expect.any(moment),
+      });
+    });
+
+    it('should maintain referential integrity in the cache across operations', async () => {
+      // Insert initial record
+      const record = await transaction.insert(employeeTable, {
+        name: 'John Doe',
+        department: 'Engineering',
+      });
+
+      // Get a reference to the cached record
+      const initialCacheRef = transaction.recordMap(employeeTable.name)[record.id];
+
+      // Store references to verify they stay up to date
+      const references = [initialCacheRef, transaction.recordMap(employeeTable.name)[record.id]];
+
+      // Perform multiple updates
+      transaction.update(employeeTable, {
+        id: record.id,
+        jobTitle: 'Software Engineer',
+      });
+
+      transaction.update(employeeTable, {
+        id: record.id,
+        isRemote: true,
+      });
+
+      // Get another reference after updates
+      references.push(transaction.recordMap(employeeTable.name)[record.id]);
+
+      // All references should point to the same, updated object
+      const expectedState = {
+        id: record.id,
+        name: 'John Doe',
+        department: 'Engineering',
+        jobTitle: 'Software Engineer',
+        isRemote: true,
+        created: expect.any(moment),
+        updated: expect.any(moment),
+      };
+
+      // Verify all references have the same, updated state
+      references.forEach((ref) => {
+        expect(ref).toEqual(expectedState);
+      });
+
+      // Verify all references point to the exact same object
+      references.forEach((ref) => {
+        expect(ref).toBe(initialCacheRef);
+      });
+    });
+
+    it('should maintain referential integrity when updating via query', async () => {
+      // Insert records
+      const record = await transaction.insert(employeeTable, {
+        name: 'John Doe',
+        department: 'Engineering',
+        isRemote: true,
+      });
+
+      // Get initial reference
+      const initialRef = transaction.recordMap(employeeTable.name)[record.id];
+
+      // Update via query
+      transaction.update(employeeTable, { jobTitle: 'Remote Engineer' }, { department: 'Engineering', isRemote: true });
+
+      // Get new reference
+      const currentRef = transaction.recordMap(employeeTable.name)[record.id];
+
+      // Verify both references point to the same object
+      expect(currentRef).toBe(initialRef);
+
+      // Verify the object was updated correctly
+      expect(currentRef).toEqual({
+        id: record.id,
+        name: 'John Doe',
+        department: 'Engineering',
+        isRemote: true,
+        jobTitle: 'Remote Engineer',
+        created: expect.any(moment),
+        updated: expect.any(moment),
+      });
+    });
+  });
+});