add setCollection method

API.md

@@ -50,6 +50,10 @@ value will be saved to storage after the default value.</p>
 <dt><a href="#update">update(data)</a> ⇒</dt>
 <dd><p>Insert API responses and lifecycle data into Onyx</p>
 </dd>
+<dt><a href="#setCollection">setCollection(collectionKey, collection)</a></dt>
+<dd><p>Sets a collection by replacing all existing collection members with new values.
+Any existing collection members not included in the new data will be removed.</p>
+</dd>
 </dl>
 
 <a name="init"></a>
@@ -209,3 +213,23 @@ Insert API responses and lifecycle data into Onyx
 | --- | --- |
 | data | An array of objects with update expressions |
 
+<a name="setCollection"></a>
+
+## setCollection(collectionKey, collection)
+Sets a collection by replacing all existing collection members with new values.
+Any existing collection members not included in the new data will be removed.
+
+**Kind**: global function  
+
+| Param | Description |
+| --- | --- |
+| collectionKey | e.g. `ONYXKEYS.COLLECTION.REPORT` |
+| collection | Object collection keyed by individual collection member keys and values |
+
+**Example**  
+```js
+Onyx.setCollection(ONYXKEYS.COLLECTION.REPORT, {
+    [`${ONYXKEYS.COLLECTION.REPORT}1`]: report1,
+    [`${ONYXKEYS.COLLECTION.REPORT}2`]: report2,
+});
+```

lib/Onyx.ts

@@ -725,6 +725,47 @@ function update(data: OnyxUpdate[]): Promise<void> {
         .then(() => undefined);
 }
 
+type BaseCollection<TMap> = Record<string, TMap | null>;
+
+/**
+ * Sets a collection by replacing all existing collection members with new values.
+ * Any existing collection members not included in the new data will be removed.
+ *
+ * @example
+ * Onyx.setCollection(ONYXKEYS.COLLECTION.REPORT, {
+ *     [`${ONYXKEYS.COLLECTION.REPORT}1`]: report1,
+ *     [`${ONYXKEYS.COLLECTION.REPORT}2`]: report2,
+ * });
+ *
+ * @param collectionKey e.g. `ONYXKEYS.COLLECTION.REPORT`
+ * @param collection Object collection keyed by individual collection member keys and values
+ */
+function setCollection<TKey extends CollectionKeyBase, TMap extends string>(collectionKey: TKey, collection: OnyxMergeCollectionInput<TMap>): Promise<void> {
+    const newCollectionKeys = Object.keys(collection);
+
+    if (!OnyxUtils.doAllCollectionItemsBelongToSameParent(collectionKey, newCollectionKeys)) {
+        Logger.logAlert(`setCollection called with keys that do not belong to the same parent ${collectionKey}. Skipping this update.`);
+        return Promise.resolve();
+    }
+
+    return OnyxUtils.getAllKeys().then((persistedKeys) => {
+        const mutableCollection: BaseCollection<TMap> = {...collection};
+
+        persistedKeys.forEach((key) => {
+            if (!key.startsWith(collectionKey)) {
+                return;
+            }
+            if (newCollectionKeys.includes(key)) {
+                return;
+            }
+
+            mutableCollection[key] = null;
+        });
+
+        return multiSet(mutableCollection);
+    });
+}
+
 const Onyx = {
     METHOD: OnyxUtils.METHOD,
     connect,
@@ -733,6 +774,7 @@ const Onyx = {
     multiSet,
     merge,
     mergeCollection,
+    setCollection,
     update,
     clear,
     init,

lib/OnyxUtils.ts

@@ -38,6 +38,7 @@ const METHOD = {
     SET: 'set',
     MERGE: 'merge',
     MERGE_COLLECTION: 'mergecollection',
+    SET_COLLECTION: 'setcollection',
     MULTI_SET: 'multiset',
     CLEAR: 'clear',
 } as const;

tests/unit/onyxTest.ts

@@ -1725,5 +1725,87 @@ describe('Onyx', () => {
                     });
             });
         });
+
+        describe('setCollection', () => {
+            it('should replace all existing collection members with new values and remove old ones', async () => {
+                let result: OnyxCollection<unknown>;
+                const routeA = `${ONYX_KEYS.COLLECTION.ROUTES}A`;
+                const routeB = `${ONYX_KEYS.COLLECTION.ROUTES}B`;
+                const routeB1 = `${ONYX_KEYS.COLLECTION.ROUTES}B1`;
+                const routeC = `${ONYX_KEYS.COLLECTION.ROUTES}C`;
+
+                connection = Onyx.connect({
+                    key: ONYX_KEYS.COLLECTION.ROUTES,
+                    initWithStoredValues: false,
+                    callback: (value) => (result = value),
+                    waitForCollectionCallback: true,
+                });
+
+                // Set initial collection state
+                await Onyx.mergeCollection(ONYX_KEYS.COLLECTION.ROUTES, {
+                    [routeA]: {name: 'Route A'},
+                    [routeB1]: {name: 'Route B1'},
+                    [routeC]: {name: 'Route C'},
+                } as GenericCollection);
+
+                // Replace with new collection data
+                await Onyx.setCollection(ONYX_KEYS.COLLECTION.ROUTES, {
+                    [routeA]: {name: 'New Route A'},
+                    [routeB]: {name: 'New Route B'},
+                    [routeC]: {name: 'New Route C'},
+                } as GenericCollection);
+
+                expect(result).toEqual({
+                    [routeA]: {name: 'New Route A'},
+                    [routeB]: {name: 'New Route B'},
+                    [routeC]: {name: 'New Route C'},
+                });
+            });
+
+            it('should replace the collection with empty values', async () => {
+                let result: OnyxCollection<unknown>;
+                const routeA = `${ONYX_KEYS.COLLECTION.ROUTES}A`;
+
+                connection = Onyx.connect({
+                    key: ONYX_KEYS.COLLECTION.ROUTES,
+                    initWithStoredValues: false,
+                    callback: (value) => (result = value),
+                    waitForCollectionCallback: true,
+                });
+
+                await Onyx.mergeCollection(ONYX_KEYS.COLLECTION.ROUTES, {
+                    [routeA]: {name: 'Route A'},
+                } as GenericCollection);
+
+                await Onyx.setCollection(ONYX_KEYS.COLLECTION.ROUTES, {} as GenericCollection);
+
+                expect(result).toEqual({});
+            });
+
+            it('should reject collection items with invalid keys', async () => {
+                let result: OnyxCollection<unknown>;
+                const routeA = `${ONYX_KEYS.COLLECTION.ROUTES}A`;
+                const invalidRoute = 'invalid_route';
+
+                connection = Onyx.connect({
+                    key: ONYX_KEYS.COLLECTION.ROUTES,
+                    initWithStoredValues: false,
+                    callback: (value) => (result = value),
+                    waitForCollectionCallback: true,
+                });
+
+                await Onyx.mergeCollection(ONYX_KEYS.COLLECTION.ROUTES, {
+                    [routeA]: {name: 'Route A'},
+                } as GenericCollection);
+
+                await Onyx.setCollection(ONYX_KEYS.COLLECTION.ROUTES, {
+                    [invalidRoute]: {name: 'Invalid Route'},
+                } as GenericCollection);
+
+                expect(result).toEqual({
+                    [routeA]: {name: 'Route A'},
+                });
+            });
+        });
     });
 });