Add tests and changeset entry

Author: simolus3

.changeset/giant-ladybugs-dress.md

@@ -0,0 +1,8 @@
+---
+'@powersync/common': minor
+---
+
+- Add `includeOld` option on `Table` which sets `CrudEntry.oldData` to previous values on updates.
+- Add `includeMetadata` option on `Table` which adds a `_metadata` column that can be used for updates.
+  The configured metadata is available through `CrudEntry.metadata`.
+- Add `ignoreEmptyUpdate` option which skips creating CRUD entries for updates that don't change any values.

packages/common/src/client/sync/bucket/CrudEntry.ts

@@ -25,9 +25,11 @@ export type CrudEntryJSON = {
 
 type CrudEntryDataJSON = {
   data: Record<string, any>;
+  old?: Record<string, any>;
   op: UpdateType;
   type: string;
   id: string;
+  metadata?: string;
 };
 
 /**
@@ -62,6 +64,13 @@ export class CrudEntry {
    * Data associated with the change.
    */
   opData?: Record<string, any>;
+
+  /**
+   * For tables where the `includeOld` option has been enabled, this tracks previous values for
+   * `UPDATE` and `DELETE` statements.
+   */
+  oldData?: Record<string, any>;
+
   /**
    * Table that contained the change.
    */
@@ -71,9 +80,26 @@ export class CrudEntry {
    */
   transactionId?: number;
 
+  /**
+   * Client-side metadata attached with this write.
+   *
+   * This field is only available when the `includeMetadata` option was set to `true` when creating a table
+   * and the insert or update statement set the `_metadata` column.
+   */
+  metadata?: string;
+
   static fromRow(dbRow: CrudEntryJSON) {
     const data: CrudEntryDataJSON = JSON.parse(dbRow.data);
-    return new CrudEntry(parseInt(dbRow.id), data.op, data.type, data.id, dbRow.tx_id, data.data);
+    return new CrudEntry(
+      parseInt(dbRow.id),
+      data.op,
+      data.type,
+      data.id,
+      dbRow.tx_id,
+      data.data,
+      data.old,
+      data.metadata
+    );
   }
 
   constructor(
@@ -82,14 +108,18 @@ export class CrudEntry {
     table: string,
     id: string,
     transactionId?: number,
-    opData?: Record<string, any>
+    opData?: Record<string, any>,
+    oldData?: Record<string, any>,
+    metadata?: string
   ) {
     this.clientId = clientId;
     this.id = id;
     this.op = op;
     this.opData = opData;
     this.table = table;
     this.transactionId = transactionId;
+    this.oldData = oldData;
+    this.metadata = metadata;
   }
 
   /**

packages/common/src/db/schema/Schema.ts

@@ -53,15 +53,7 @@ export class Schema<S extends SchemaType = SchemaType> {
 
   private convertToClassicTables(props: S) {
     return Object.entries(props).map(([name, table]) => {
-      const convertedTable = new Table({
-        name,
-        columns: table.columns,
-        indexes: table.indexes,
-        localOnly: table.localOnly,
-        insertOnly: table.insertOnly,
-        viewName: table.viewNameOverride || name
-      });
-      return convertedTable;
+      return table.copyWithName(name);
     });
   }
 }

packages/common/src/db/schema/Table.ts

@@ -46,7 +46,7 @@ export const DEFAULT_TABLE_OPTIONS = {
   localOnly: false,
   includeOld: false,
   includeMetadata: false,
-  ignoreEmptyUpdate: false,
+  ignoreEmptyUpdate: false
 };
 
 export const InvalidSQLCharacters = /["'%,.#\s[\]]/;
@@ -143,6 +143,13 @@ export class Table<Columns extends ColumnsType = ColumnsType> {
     }
   }
 
+  copyWithName(name: string): Table {
+    return new Table({
+      ...this.options,
+      name
+    });
+  }
+
   private isTableV1(arg: TableOptions | Columns): arg is TableOptions {
     return 'columns' in arg && Array.isArray(arg.columns);
   }

packages/common/tests/db/schema/Table.test.ts

@@ -132,18 +132,18 @@ describe('Table', () => {
 
   it('should handle options', () => {
     function createTable(options: TableV2Options) {
-      return new Table({name: column.text}, options);
+      return new Table({ name: column.text }, options);
     }
 
     expect(createTable({}).toJSON().include_metadata).toBe(false);
-    expect(createTable({includeMetadata: true}).toJSON().include_metadata).toBe(true);
+    expect(createTable({ includeMetadata: true }).toJSON().include_metadata).toBe(true);
 
-    expect(createTable({includeOld: true}).toJSON().include_old).toBe(true);
-    expect(createTable({includeOld: true}).toJSON().include_old_only_when_changed).toBe(false);
-    expect(createTable({includeOld: 'when-changed'}).toJSON().include_old).toBe(true);
-    expect(createTable({includeOld: 'when-changed'}).toJSON().include_old_only_when_changed).toBe(true);
+    expect(createTable({ includeOld: true }).toJSON().include_old).toBe(true);
+    expect(createTable({ includeOld: true }).toJSON().include_old_only_when_changed).toBe(false);
+    expect(createTable({ includeOld: 'when-changed' }).toJSON().include_old).toBe(true);
+    expect(createTable({ includeOld: 'when-changed' }).toJSON().include_old_only_when_changed).toBe(true);
 
-    expect(createTable({ignoreEmptyUpdate: true}).toJSON().ignore_empty_update).toBe(true);
+    expect(createTable({ ignoreEmptyUpdate: true }).toJSON().ignore_empty_update).toBe(true);
   });
 
   describe('validate', () => {
@@ -196,23 +196,32 @@ describe('Table', () => {
 
     it('should throw an error for local-only tables with metadata', () => {
       expect(() =>
-        new Table({
-          name: column.text,
-        }, { localOnly: true, includeMetadata: true }).validate()
+        new Table(
+          {
+            name: column.text
+          },
+          { localOnly: true, includeMetadata: true }
+        ).validate()
       ).toThrowError("Can't include metadata for local-only tables.");
     });
 
     it('should throw an error for local-only tables tracking old values', () => {
       expect(() =>
-        new Table({
-          name: column.text,
-        }, { localOnly: true, includeOld: true }).validate()
+        new Table(
+          {
+            name: column.text
+          },
+          { localOnly: true, includeOld: true }
+        ).validate()
       ).toThrowError("Can't include old values for local-only tables.");
 
       expect(() =>
-        new Table({
-          name: column.text,
-        }, { localOnly: true, includeOld: 'when-changed' }).validate()
+        new Table(
+          {
+            name: column.text
+          },
+          { localOnly: true, includeOld: 'when-changed' }
+        ).validate()
       ).toThrowError("Can't include old values for local-only tables.");
     });
   });

packages/node/tests/crud.test.ts

@@ -0,0 +1,78 @@
+import { expect } from 'vitest';
+import { column, Schema, Table } from '@powersync/common';
+import { databaseTest } from './utils';
+
+databaseTest('include metadata', async ({ database }) => {
+  await database.init();
+  const schema = new Schema({
+    lists: new Table(
+      {
+        name: column.text
+      },
+      { includeMetadata: true }
+    )
+  });
+  await database.updateSchema(schema);
+  await database.execute('INSERT INTO lists (id, name, _metadata) VALUES (uuid(), ?, ?);', ['entry', 'so meta']);
+ 
+  const batch = await database.getNextCrudTransaction();
+  expect(batch?.crud[0].metadata).toBe('so meta');
+});
+
+databaseTest('include old values', async ({ database }) => {
+  await database.init();
+  const schema = new Schema({
+    lists: new Table(
+      {
+        name: column.text
+      },
+      { includeOld: true }
+    )
+  });
+  await database.updateSchema(schema);
+  await database.execute('INSERT INTO lists (id, name) VALUES (uuid(), ?);', ['entry']);
+  await database.execute('DELETE FROM ps_crud;');
+  await database.execute('UPDATE lists SET name = ?', ['new name']);
+ 
+  const batch = await database.getNextCrudTransaction();
+  expect(batch?.crud[0].oldData).toStrictEqual({name: 'entry'});
+});
+
+databaseTest('include old values when changed', async ({ database }) => {
+  await database.init();
+  const schema = new Schema({
+    lists: new Table(
+      {
+        name: column.text,
+        content: column.text
+      },
+      { includeOld: 'when-changed' }
+    )
+  });
+  await database.updateSchema(schema);
+  await database.execute('INSERT INTO lists (id, name, content) VALUES (uuid(), ?, ?);', ['name', 'content']);
+  await database.execute('DELETE FROM ps_crud;');
+  await database.execute('UPDATE lists SET name = ?', ['new name']);
+ 
+  const batch = await database.getNextCrudTransaction();
+  expect(batch?.crud[0].oldData).toStrictEqual({name: 'name'});
+});
+
+databaseTest('ignore empty update', async ({ database }) => {
+  await database.init();
+  const schema = new Schema({
+    lists: new Table(
+      {
+        name: column.text
+      },
+      { ignoreEmptyUpdate: true }
+    )
+  });
+  await database.updateSchema(schema);
+  await database.execute('INSERT INTO lists (id, name) VALUES (uuid(), ?);', ['name']);
+  await database.execute('DELETE FROM ps_crud;');
+  await database.execute('UPDATE lists SET name = ?', ['name']);
+ 
+  const batch = await database.getNextCrudTransaction();
+  expect(batch).toBeNull();
+});