improve readonly mutability in types. Persist previous object references better in differential queries.

Author: stevensJourney

packages/common/src/client/watched/WatchedQuery.ts

@@ -28,7 +28,7 @@ export interface WatchedQueryState<Data> {
   /**
    * The last data returned by the query.
    */
-  data: Data;
+  readonly data: Data;
 }
 
 /**

packages/common/src/client/watched/processors/DifferentialQueryProcessor.ts

@@ -6,20 +6,34 @@ import { AbstractQueryProcessor, AbstractQueryProcessorOptions, LinkQueryOptions
  * It contains both the current and previous state of the row.
  */
 export interface WatchedQueryRowDifferential<RowType> {
-  current: RowType;
-  previous: RowType;
+  readonly current: RowType;
+  readonly previous: RowType;
 }
 
 /**
  * Represents the result of a watched query that has been differentiated.
  * {@link WatchedQueryState.data} is of the {@link WatchedQueryDifferential} form when using the {@link IncrementalWatchMode.DIFFERENTIAL} mode.
  */
 export interface WatchedQueryDifferential<RowType> {
-  added: RowType[];
-  all: RowType[];
-  removed: RowType[];
-  updated: WatchedQueryRowDifferential<RowType>[];
-  unchanged: RowType[];
+  added: ReadonlyArray<RowType>;
+  /**
+   * The entire current result set.
+   * Array item object references are preserved between updates if the item is unchanged.
+   *
+   * e.g. In the query
+   * ```sql
+   *  SELECT name, make FROM assets ORDER BY make ASC;
+   * ```
+   *
+   * If a previous result set contains an item (A) `{name: 'pc', make: 'Cool PC'}` and
+   * an update has been made which adds another item (B) to the result set (the item A is unchanged) - then
+   * the updated result set will be contain the same object reference,to item A, as the previous resultset.
+   * This is regardless of the item A's position in the updated result set.
+   */
+  all: ReadonlyArray<RowType>;
+  removed: ReadonlyArray<RowType>;
+  updated: ReadonlyArray<WatchedQueryRowDifferential<RowType>>;
+  unchanged: ReadonlyArray<RowType>;
 }
 
 /**
@@ -98,36 +112,44 @@ export class DifferentialQueryProcessor<RowType>
 
     let hasChanged = false;
     const currentMap = new Map<string, { hash: string; item: RowType }>();
-    current.forEach((item) => {
-      currentMap.set(identify(item), {
-        hash: compareBy(item),
-        item
-      });
-    });
-
     const removedTracker = new Set(previousMap.keys());
 
-    const diff: WatchedQueryDifferential<RowType> = {
-      all: current,
-      added: [],
-      removed: [],
-      updated: [],
-      unchanged: []
+    // Allow mutating to populate the data temporarily.
+    const diff = {
+      all: [] as RowType[],
+      added: [] as RowType[],
+      removed: [] as RowType[],
+      updated: [] as WatchedQueryRowDifferential<RowType>[],
+      unchanged: [] as RowType[]
     };
 
-    for (const [key, { hash, item }] of currentMap) {
+    /**
+     * Looping over the current result set array is important to preserve
+     * the ordering of the result set.
+     * We can replace items in the current array with previous object references if they are equal.
+     */
+    for (const item of current) {
+      const key = identify(item);
+      const hash = compareBy(item);
+      currentMap.set(key, { hash, item });
+
       const previousItem = previousMap.get(key);
       if (!previousItem) {
         // New item
         hasChanged = true;
         diff.added.push(item);
+        diff.all.push(item);
       } else {
         // Existing item
         if (hash == previousItem.hash) {
           diff.unchanged.push(item);
+          // Use the previous object reference
+          diff.all.push(previousItem.item);
         } else {
           hasChanged = true;
           diff.updated.push({ current: item, previous: previousItem.item });
+          // Use the new reference
+          diff.all.push(item);
         }
       }
       // The item is present, we don't consider it removed
@@ -175,7 +197,9 @@ export class DifferentialQueryProcessor<RowType>
               await this.updateState({ isFetching: true });
             }
 
-            const partialStateUpdate: Partial<WatchedQueryState<WatchedQueryDifferential<RowType>>> = {};
+            const partialStateUpdate: Partial<WatchedQueryState<WatchedQueryDifferential<RowType>>> & {
+              data?: WatchedQueryDifferential<RowType>;
+            } = {};
 
             // Always run the query if an underlying table has changed
             const result = await watchOptions.query.execute({

packages/common/src/client/watched/processors/OnChangeQueryProcessor.ts

@@ -56,7 +56,7 @@ export class OnChangeQueryProcessor<Data> extends AbstractQueryProcessor<Data, C
               await this.updateState({ isFetching: true });
             }
 
-            const partialStateUpdate: Partial<WatchedQueryState<Data>> = {};
+            const partialStateUpdate: Partial<WatchedQueryState<Data>> & { data?: Data } = {};
 
             // Always run the query if an underlying table has changed
             const result = await watchOptions.query.execute({

packages/web/tests/watch.test.ts

@@ -668,6 +668,83 @@ describe('Watch Tests', { sequential: true }, () => {
     );
   });
 
+  it('should preserve object references in result set', async () => {
+    // Sort the results by the `make` column in ascending order
+    const watch = powersync
+      .incrementalWatch({
+        mode: IncrementalWatchMode.DIFFERENTIAL
+      })
+      .build({
+        differentiator: {
+          identify: (item) => item.id,
+          compareBy: (item) => JSON.stringify(item)
+        },
+        watch: {
+          query: new GetAllQuery({
+            sql: /* sql */ `
+              SELECT
+                *
+              FROM
+                assets
+              ORDER BY
+                make ASC;
+            `,
+            mapper: (raw) => {
+              return {
+                id: raw.id as string,
+                make: raw.make as string
+              };
+            }
+          })
+        }
+      });
+
+    // Create sample data
+    await powersync.execute(
+      /* sql */ `
+        INSERT INTO
+          assets (id, make, customer_id)
+        VALUES
+          (uuid (), ?, uuid ()),
+          (uuid (), ?, uuid ()),
+          (uuid (), ?, uuid ())
+      `,
+      ['a', 'b', 'd']
+    );
+
+    await vi.waitFor(
+      () => {
+        expect(watch.state.data.all.map((i) => i.make)).deep.equals(['a', 'b', 'd']);
+      },
+      { timeout: 1000 }
+    );
+
+    const initialData = watch.state.data.all;
+
+    await powersync.execute(
+      /* sql */ `
+        INSERT INTO
+          assets (id, make, customer_id)
+        VALUES
+          (uuid (), ?, uuid ())
+      `,
+      ['c']
+    );
+
+    await vi.waitFor(
+      () => {
+        expect(watch.state.data.all).toHaveLength(4);
+      },
+      { timeout: 1000 }
+    );
+
+    console.log(JSON.stringify(watch.state.data.all));
+    expect(initialData[0] == watch.state.data.all[0]).true;
+    expect(initialData[1] == watch.state.data.all[1]).true;
+    // The index after the insert should also still be the same ref as the previous item
+    expect(initialData[2] == watch.state.data.all[3]).true;
+  });
+
   it('should report differential query results from initial state', async () => {
     /**
      * Differential queries start with a placeholder data. We run a watched query under the hood