Add alternative helper for bypassing file amendments.

Author: jameswilddev

react-native/services/SyncableStateHelper/index.tsx

@@ -108,4 +108,37 @@ export class SyncableStateHelper<
       })
     }
   }
+
+  /**
+   * Inserts or updates a collection item.  Does NOT manage changes to files.  You likely want "upsertCollection", not this.
+   * This has one known use case: that you are soft-deleting a child record of the item, and that the sync system should NOT attempt to delete its associated media.
+   * @param state         The current state.
+   * @param collectionKey The key of the collection in which to make changes.
+   * @param uuid          The UUID of the collection item to insert or update.
+   * @param data          The data of the collection item to insert or update.
+   * @param setState      Called when the next state has been computed.
+   */
+  upsertCollectionWithoutAmendingFiles<T extends keyof TSchema['collections']>(
+    state: SyncableState<TSchema>,
+    collectionKey: T,
+    uuid: string,
+    data: TSchema['collections'][T],
+    setState: (to: SyncableState<TSchema>) => void
+  ): void {
+    const collection = state.collections[collectionKey]
+
+    setState({
+      ...state,
+      collections: {
+        ...state.collections,
+        [collectionKey]: {
+          ...collection,
+          [uuid]: {
+            status: 'awaitingPush',
+            data
+          }
+        }
+      }
+    })
+  }
 }

react-native/services/SyncableStateHelper/readme.md

@@ -17,3 +17,23 @@ syncableStateHelper.upsertCollection(
   setState,
 );
 ```
+
+### Without amending files
+
+A call to `upsertCollection` will enqueue file uploads and deletions based upon the differences between the new data and the previous data.
+
+There are some rare cases in which this should be skipped; for example, if a record had embedded child records with files, removal of one such child record should not lead the sync system to start trying to delete its associated files from the server.  Use `upsertCollectionWithoutAmendingFiles` to handle this:
+
+```tsx
+import { SyncableStateHelper } from "react-native-app-helpers";
+
+const syncableStateHelper = new SyncableStateHelper(syncConfiguration);
+
+syncableStateHelper.upsertCollectionWithoutAmendingFiles(
+  state,
+  `exampleCollectionKey`,
+  `76a7d202-7971-45d4-8fb6-586403a312b0`,
+  `Example Data`,
+  setState,
+);
+```