Add new Cube.modifyRecordsAsync (#4058)

* Add new `Cube.modifyRecordsAsync`

* Rename interfaces + fix bug where `Store.modifyRecords` was not properly handling changes to `SummaryRecords`.

* Limit use of rebuildFiltered in Store.modifyRecords

Author: ghsolomon

CHANGELOG.md

@@ -23,6 +23,11 @@
   which `dimensions` are provided to the model.
 * Added new `ClipboardButton.errorMessage` prop to customize or suppress a toast alert if the copy
   operation fails. Set to `false` to fail silently (the behavior prior to this change).
+* Added new `Cube.modifyRecordsAsync` for modifying individual field values in a local uncommitted
+  state. Additionally enhanced `Store.modifyRecords` to return a `StoreChangeLog` of updates.
+
+### 🐞 Bug Fixes
+* Fixed bug where `Store.modifyRecords` was not properly handling changes to `SummaryRecords`.
 
 ### 🐞 Bug Fixes
 

data/Store.ts

@@ -153,6 +153,17 @@ export interface StoreTransaction {
     rawSummaryData?: Some<PlainObject>;
 }
 
+/**
+ * Collection of changes made to a Store's RecordSet. Unlike `StoreTransaction` which is used to
+ * specify changes, this object is used to report the actual changes made in a single transaction.
+ */
+export interface StoreChangeLog {
+    update?: StoreRecord[];
+    add?: StoreRecord[];
+    remove?: StoreRecordId[];
+    summaryRecords?: StoreRecord[];
+}
+
 export interface ChildRawData {
     /** ID of the pre-existing parent record. */
     parentId: string;
@@ -348,13 +359,13 @@ export class Store extends HoistBase {
      */
     @action
     @logWithDebug
-    updateData(rawData: PlainObject[] | StoreTransaction): PlainObject {
+    updateData(rawData: PlainObject[] | StoreTransaction): StoreChangeLog {
         if (isEmpty(rawData)) return null;
 
-        const changeLog: PlainObject = {};
+        const changeLog: StoreChangeLog = {};
 
         // Build a transaction object out of a flat list of adds and updates
-        let rawTransaction;
+        let rawTransaction: StoreTransaction;
         if (isArray(rawData)) {
             const update = [],
                 add = [];
@@ -381,7 +392,7 @@ export class Store extends HoistBase {
         throwIf(!isEmpty(other), 'Unknown argument(s) passed to updateData().');
 
         // 1) Pre-process updates and adds into Records
-        let updateRecs, addRecs;
+        let updateRecs: StoreRecord[], addRecs: Map<StoreRecordId, StoreRecord>;
         if (update) {
             updateRecs = update.map(it => {
                 const recId = this.idSpec(it),
@@ -426,7 +437,11 @@ export class Store extends HoistBase {
         }
 
         // 3) Apply changes
-        let rsTransaction: any = {};
+        let rsTransaction: {
+            update?: StoreRecord[];
+            add?: StoreRecord[];
+            remove?: StoreRecordId[];
+        } = {};
         if (!isEmpty(updateRecs)) rsTransaction.update = updateRecs;
         if (!isEmpty(addRecs)) rsTransaction.add = Array.from(addRecs.values());
         if (!isEmpty(remove)) rsTransaction.remove = remove;
@@ -545,21 +560,23 @@ export class Store extends HoistBase {
      *      Records in this Store. Each object in the list must have an `id` property identifying
      *      the StoreRecord to modify, plus any other properties with updated field values to apply,
      *      e.g. `{id: 4, quantity: 100}, {id: 5, quantity: 99, customer: 'bob'}`.
+     * @returns changes applied, or null if no record changes were made.
      */
     @action
-    modifyRecords(modifications: Some<PlainObject>) {
+    modifyRecords(modifications: Some<PlainObject>): StoreChangeLog {
         modifications = castArray(modifications);
         if (isEmpty(modifications)) return;
 
-        const updateRecs = new Map();
+        // 1) Pre-process modifications into Records
+        const updateMap = new Map<StoreRecordId, StoreRecord>();
         let hadDupes = false;
         modifications.forEach(mod => {
             let {id} = mod;
 
             // Ignore multiple updates for the same record - we are updating this Store in a
             // transaction after processing all modifications, so this method is not currently setup
             // to process more than one update for a given rec at a time.
-            if (updateRecs.has(id)) {
+            if (updateMap.has(id)) {
                 hadDupes = true;
                 return;
             }
@@ -577,20 +594,40 @@ export class Store extends HoistBase {
             });
 
             if (!equal(currentRec.data, updatedRec.data)) {
-                updateRecs.set(id, updatedRec);
+                updateMap.set(id, updatedRec);
             }
         });
 
-        if (isEmpty(updateRecs)) return;
+        if (isEmpty(updateMap)) return null;
 
         warnIf(
             hadDupes,
             'Store.modifyRecords() called with multiple updates for the same Records. Only the first modification for each StoreRecord was processed.'
         );
 
-        this._current = this._current.withTransaction({update: Array.from(updateRecs.values())});
+        const updateRecs = Array.from(updateMap.values()),
+            changeLog: StoreChangeLog = {};
 
-        this.rebuildFiltered();
+        // 2) Pre-process summary records, peeling them out of updates if needed
+        const {summaryRecords} = this;
+        let summaryUpdateRecs: StoreRecord[];
+        if (!isEmpty(summaryRecords)) {
+            summaryUpdateRecs = lodashRemove(updateRecs, ({id}) => some(summaryRecords, {id}));
+        }
+
+        if (!isEmpty(summaryUpdateRecs)) {
+            this.summaryRecords = summaryUpdateRecs;
+            changeLog.summaryRecords = this.summaryRecords;
+        }
+
+        // 3) Apply changes
+        if (!isEmpty(updateRecs)) {
+            this._current = this._current.withTransaction({update: updateRecs});
+            changeLog.update = updateRecs;
+            this.rebuildFiltered();
+        }
+
+        return changeLog;
     }
 
     /**
@@ -705,7 +742,7 @@ export class Store extends HoistBase {
     /** True if the store has changes which need to be committed. */
     @computed
     get isDirty(): boolean {
-        return this._current !== this._committed;
+        return this._current !== this._committed || this.summaryRecords?.some(it => it.isModified);
     }
 
     /** Alias for {@link Store.isDirty} */

data/cube/Cube.ts

@@ -5,7 +5,7 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 
-import {HoistBase, managed, PlainObject} from '@xh/hoist/core';
+import {HoistBase, managed, PlainObject, Some} from '@xh/hoist/core';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {forEachAsync} from '@xh/hoist/utils/async';
 import {CubeField, CubeFieldSpec} from './CubeField';
@@ -244,6 +244,26 @@ export class Cube extends HoistBase {
         }
     }
 
+    /**
+     * Similar to `updateDataAsync`, but intended for modifying individual field values in a local
+     * uncommitted state - i.e. when updating via an inline grid editor or similar control. Like
+     * `updateDataAsync`, this method will update its views asynchronously.
+     *
+     * This method largely delegates to {@link Store.modifyRecords} - see that method for more info.
+     *
+     * @param modifications - field-level modifications to apply to existing
+     *      Records in this Cube. Each object in the list must have an `id` property identifying
+     *      the StoreRecord to modify, plus any other properties with updated field values to apply,
+     *      e.g. `{id: 4, quantity: 100}, {id: 5, quantity: 99, customer: 'bob'}`.
+     */
+    async modifyRecordsAsync(modifications: Some<PlainObject>): Promise<void> {
+        const changeLog = this.store.modifyRecords(modifications);
+
+        if (changeLog) {
+            await forEachAsync(this._connectedViews, v => v.noteCubeUpdated(changeLog));
+        }
+    }
+
     /** Clear any/all data and info from this Cube. */
     async clearAsync() {
         await this.loadDataAsync([]);