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/SQLOpenFactory.ts

@@ -7,7 +7,7 @@ export interface SQLOpenOptions {
   dbFilename: string;
   /**
    * Directory where the database file is located.
-   * 
+   *
    * When set, the directory must exist when the database is opened, it will
    * not be created automatically.
    */

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/client/sync/stream/AbstractStreamingSyncImplementation.ts

@@ -497,10 +497,7 @@ The next upload iteration will be delayed.`);
     return [req, localDescriptions];
   }
 
-  protected async streamingSyncIteration(
-    signal: AbortSignal,
-    options?: PowerSyncConnectionOptions
-  ): Promise<void> {
+  protected async streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void> {
     await this.obtainLock({
       type: LockType.SYNC,
       signal,
@@ -673,7 +670,7 @@ The next upload iteration will be delayed.`);
                * (uses the same one), this should have some delay.
                */
               await this.delayRetry();
-              return ;
+              return;
             }
             this.triggerCrudUpload();
           } else {

packages/common/src/db/crud/SyncStatus.ts

@@ -34,7 +34,7 @@ export class SyncStatus {
 
   /**
    * Indicates if the client is currently connected to the PowerSync service.
-   * 
+   *
    * @returns {boolean} True if connected, false otherwise. Defaults to false if not specified.
    */
   get connected() {
@@ -43,7 +43,7 @@ export class SyncStatus {
 
   /**
    * Indicates if the client is in the process of establishing a connection to the PowerSync service.
-   * 
+   *
    * @returns {boolean} True if connecting, false otherwise. Defaults to false if not specified.
    */
   get connecting() {
@@ -53,7 +53,7 @@ export class SyncStatus {
   /**
    * Time that a last sync has fully completed, if any.
    * This timestamp is reset to null after a restart of the PowerSync service.
-   * 
+   *
    * @returns {Date | undefined} The timestamp of the last successful sync, or undefined if no sync has completed.
    */
   get lastSyncedAt() {
@@ -62,7 +62,7 @@ export class SyncStatus {
 
   /**
    * Indicates whether there has been at least one full sync completed since initialization.
-   * 
+   *
    * @returns {boolean | undefined} True if at least one sync has completed, false if no sync has completed,
    * or undefined when the state is still being loaded from the database.
    */
@@ -72,7 +72,7 @@ export class SyncStatus {
 
   /**
    * Provides the current data flow status regarding uploads and downloads.
-   * 
+   *
    * @returns {SyncDataFlowStatus} An object containing:
    * - downloading: True if actively downloading changes (only when connected is also true)
    * - uploading: True if actively uploading changes
@@ -96,7 +96,7 @@ export class SyncStatus {
 
   /**
    * Provides sync status information for all bucket priorities, sorted by priority (highest first).
-   * 
+   *
    * @returns {SyncPriorityStatus[]} An array of status entries for different sync priority levels,
    * sorted with highest priorities (lower numbers) first.
    */
@@ -105,18 +105,18 @@ export class SyncStatus {
   }
 
   /**
-   * Reports the sync status (a pair of {@link SyncStatus#hasSynced} and {@link SyncStatus#lastSyncedAt} fields) 
+   * Reports the sync status (a pair of {@link SyncStatus#hasSynced} and {@link SyncStatus#lastSyncedAt} fields)
    * for a specific bucket priority level.
-   * 
+   *
    * When buckets with different priorities are declared, PowerSync may choose to synchronize higher-priority
    * buckets first. When a consistent view over all buckets for all priorities up until the given priority is
    * reached, PowerSync makes data from those buckets available before lower-priority buckets have finished
    * syncing.
-   * 
-   * This method returns the status for the requested priority or the next higher priority level that has 
-   * status information available. This is because when PowerSync makes data for a given priority available, 
+   *
+   * This method returns the status for the requested priority or the next higher priority level that has
+   * status information available. This is because when PowerSync makes data for a given priority available,
    * all buckets in higher-priorities are guaranteed to be consistent with that checkpoint.
-   * 
+   *
    * For example, if PowerSync just finished synchronizing buckets in priority level 3, calling this method
    * with a priority of 1 may return information for priority level 3.
    *
@@ -143,7 +143,7 @@ export class SyncStatus {
   /**
    * Compares this SyncStatus instance with another to determine if they are equal.
    * Equality is determined by comparing the serialized JSON representation of both instances.
-   * 
+   *
    * @param {SyncStatus} status The SyncStatus instance to compare against
    * @returns {boolean} True if the instances are considered equal, false otherwise
    */
@@ -154,7 +154,7 @@ export class SyncStatus {
   /**
    * Creates a human-readable string representation of the current sync status.
    * Includes information about connection state, sync completion, and data flow.
-   * 
+   *
    * @returns {string} A string representation of the sync status
    */
   getMessage() {
@@ -164,7 +164,7 @@ export class SyncStatus {
 
   /**
    * Serializes the SyncStatus instance to a plain object.
-   * 
+   *
    * @returns {SyncStatusOptions} A plain object representation of the sync status
    */
   toJSON(): SyncStatusOptions {

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/src/db/BetterSQLite3DBAdapter.ts

@@ -64,7 +64,9 @@ export class BetterSQLite3DBAdapter extends BaseObserver<DBAdapterListener> impl
       }
 
       if (!directoryExists) {
-        throw new Error(`The dbLocation directory at "${this.options.dbLocation}" does not exist. Please create it before opening the PowerSync database!`);
+        throw new Error(
+          `The dbLocation directory at "${this.options.dbLocation}" does not exist. Please create it before opening the PowerSync database!`
+        );
       }
 
       dbFilePath = path.join(this.options.dbLocation, dbFilePath);

packages/node/tests/PowerSyncDatabase.test.ts

@@ -1,5 +1,4 @@
 import * as path from 'node:path';
-import * as fs from 'node:fs/promises';
 import { Worker } from 'node:worker_threads';
 
 import { vi, expect, test } from 'vitest';