react-native-onyx 2.0.80 → 2.0.82

package/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,
+});
+```

package/dist/Onyx.d.ts

@@ -119,11 +119,26 @@ declare function clear(keysToPreserve?: OnyxKey[]): Promise<void>;
  * @returns resolves when all operations are complete
  */
 declare function update(data: OnyxUpdate[]): Promise<void>;
+/**
+ * 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
+ */
+declare function setCollection<TKey extends CollectionKeyBase, TMap extends string>(collectionKey: TKey, collection: OnyxMergeCollectionInput<TMap>): Promise<void>;
 declare const Onyx: {
     readonly METHOD: {
         readonly SET: "set";
         readonly MERGE: "merge";
         readonly MERGE_COLLECTION: "mergecollection";
+        readonly SET_COLLECTION: "setcollection";
         readonly MULTI_SET: "multiset";
         readonly CLEAR: "clear";
     };
@@ -133,6 +148,7 @@ declare const Onyx: {
     readonly multiSet: typeof multiSet;
     readonly merge: typeof merge;
     readonly mergeCollection: typeof mergeCollection;
+    readonly setCollection: typeof setCollection;
     readonly update: typeof update;
     readonly clear: typeof clear;
     readonly init: typeof init;

package/dist/Onyx.js

@@ -515,7 +515,7 @@ function updateSnapshots(data) {
 function update(data) {
     // First, validate the Onyx object is in the format we expect
     data.forEach(({ onyxMethod, key, value }) => {
-        if (![OnyxUtils_1.default.METHOD.CLEAR, OnyxUtils_1.default.METHOD.SET, OnyxUtils_1.default.METHOD.MERGE, OnyxUtils_1.default.METHOD.MERGE_COLLECTION, OnyxUtils_1.default.METHOD.MULTI_SET].includes(onyxMethod)) {
+        if (!Object.values(OnyxUtils_1.default.METHOD).includes(onyxMethod)) {
             throw new Error(`Invalid onyxMethod ${onyxMethod} in Onyx update.`);
         }
         if (onyxMethod === OnyxUtils_1.default.METHOD.MULTI_SET) {
@@ -552,18 +552,14 @@ function update(data) {
     const promises = [];
     let clearPromise = Promise.resolve();
     data.forEach(({ onyxMethod, key, value }) => {
-        switch (onyxMethod) {
-            case OnyxUtils_1.default.METHOD.SET:
-                enqueueSetOperation(key, value);
-                break;
-            case OnyxUtils_1.default.METHOD.MERGE:
-                enqueueMergeOperation(key, value);
-                break;
-            case OnyxUtils_1.default.METHOD.MERGE_COLLECTION: {
+        const handlers = {
+            [OnyxUtils_1.default.METHOD.SET]: enqueueSetOperation,
+            [OnyxUtils_1.default.METHOD.MERGE]: enqueueMergeOperation,
+            [OnyxUtils_1.default.METHOD.MERGE_COLLECTION]: () => {
                 const collection = value;
                 if (!OnyxUtils_1.default.isValidNonEmptyCollectionForMerge(collection)) {
                     Logger.logInfo('mergeCollection enqueued within update() with invalid or empty value. Skipping this operation.');
-                    break;
+                    return;
                 }
                 // Confirm all the collection keys belong to the same parent
                 const collectionKeys = Object.keys(collection);
@@ -571,17 +567,14 @@ function update(data) {
                     const mergedCollection = collection;
                     collectionKeys.forEach((collectionKey) => enqueueMergeOperation(collectionKey, mergedCollection[collectionKey]));
                 }
-                break;
-            }
-            case OnyxUtils_1.default.METHOD.MULTI_SET:
-                Object.entries(value).forEach(([entryKey, entryValue]) => enqueueSetOperation(entryKey, entryValue));
-                break;
-            case OnyxUtils_1.default.METHOD.CLEAR:
+            },
+            [OnyxUtils_1.default.METHOD.SET_COLLECTION]: (k, v) => promises.push(() => setCollection(k, v)),
+            [OnyxUtils_1.default.METHOD.MULTI_SET]: (k, v) => Object.entries(v).forEach(([entryKey, entryValue]) => enqueueSetOperation(entryKey, entryValue)),
+            [OnyxUtils_1.default.METHOD.CLEAR]: () => {
                 clearPromise = clear();
-                break;
-            default:
-                break;
-        }
+            },
+        };
+        handlers[onyxMethod](key, value);
     });
     // Group all the collection-related keys and update each collection in a single `mergeCollection` call.
     // This is needed to prevent multiple `mergeCollection` calls for the same collection and `merge` calls for the individual items of the said collection.
@@ -632,6 +625,39 @@ function update(data) {
         .then(() => updateSnapshots(data))
         .then(() => undefined);
 }
+/**
+ * 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(collectionKey, collection) {
+    const newCollectionKeys = Object.keys(collection);
+    if (!OnyxUtils_1.default.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_1.default.getAllKeys().then((persistedKeys) => {
+        const mutableCollection = Object.assign({}, collection);
+        persistedKeys.forEach((key) => {
+            if (!key.startsWith(collectionKey)) {
+                return;
+            }
+            if (newCollectionKeys.includes(key)) {
+                return;
+            }
+            mutableCollection[key] = null;
+        });
+        return multiSet(mutableCollection);
+    });
+}
 const Onyx = {
     METHOD: OnyxUtils_1.default.METHOD,
     connect,
@@ -640,6 +666,7 @@ const Onyx = {
     multiSet,
     merge,
     mergeCollection,
+    setCollection,
     update,
     clear,
     init,

package/dist/OnyxUtils.d.ts

@@ -6,6 +6,7 @@ declare const METHOD: {
     readonly SET: "set";
     readonly MERGE: "merge";
     readonly MERGE_COLLECTION: "mergecollection";
+    readonly SET_COLLECTION: "setcollection";
     readonly MULTI_SET: "multiset";
     readonly CLEAR: "clear";
 };
@@ -228,6 +229,7 @@ declare const OnyxUtils: {
         readonly SET: "set";
         readonly MERGE: "merge";
         readonly MERGE_COLLECTION: "mergecollection";
+        readonly SET_COLLECTION: "setcollection";
         readonly MULTI_SET: "multiset";
         readonly CLEAR: "clear";
     };
@@ -276,4 +278,5 @@ declare const OnyxUtils: {
     unsubscribeFromKey: typeof unsubscribeFromKey;
     getEvictionBlocklist: typeof getEvictionBlocklist;
 };
+export type { OnyxMethod };
 export default OnyxUtils;

package/dist/OnyxUtils.js

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

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import type { Merge } from 'type-fest';
 import type { BuiltIns } from 'type-fest/source/internal';
 import type OnyxUtils from './OnyxUtils';
 import type { WithOnyxInstance, WithOnyxState } from './withOnyx/types';
+import type { OnyxMethod } from './OnyxUtils';
 /**
  * Utility type that excludes `null` from the type `TValue`.
  */
@@ -329,35 +330,43 @@ type OnyxMergeInput<TKey extends OnyxKey> = OnyxInput<TKey>;
  * This represents the value that can be passed to `Onyx.merge` and to `Onyx.update` with the method "MERGE"
  */
 type OnyxMergeCollectionInput<TKey extends OnyxKey, TMap = object> = Collection<TKey, NonNullable<OnyxInput<TKey>>, TMap>;
-/**
- * Represents different kinds of updates that can be passed to `Onyx.update()` method. It is a discriminated union of
- * different update methods (`SET`, `MERGE`, `MERGE_COLLECTION`), each with their own key and value structure.
- */
-type OnyxUpdate = {
-    [TKey in OnyxKey]: {
-        onyxMethod: typeof OnyxUtils.METHOD.SET;
-        key: TKey;
-        value: OnyxSetInput<TKey>;
-    } | {
-        onyxMethod: typeof OnyxUtils.METHOD.MULTI_SET;
-        key: TKey;
+type OnyxMethodMap = typeof OnyxUtils.METHOD;
+type OnyxMethodValueMap = {
+    [OnyxUtils.METHOD.SET]: {
+        key: OnyxKey;
+        value: OnyxSetInput<OnyxKey>;
+    };
+    [OnyxUtils.METHOD.MULTI_SET]: {
+        key: OnyxKey;
         value: OnyxMultiSetInput;
-    } | {
-        onyxMethod: typeof OnyxUtils.METHOD.MERGE;
-        key: TKey;
-        value: OnyxMergeInput<TKey>;
-    } | {
-        onyxMethod: typeof OnyxUtils.METHOD.CLEAR;
-        key: TKey;
+    };
+    [OnyxUtils.METHOD.MERGE]: {
+        key: OnyxKey;
+        value: OnyxMergeInput<OnyxKey>;
+    };
+    [OnyxUtils.METHOD.CLEAR]: {
+        key: OnyxKey;
         value?: undefined;
     };
-}[OnyxKey] | {
-    [TKey in CollectionKeyBase]: {
-        onyxMethod: typeof OnyxUtils.METHOD.MERGE_COLLECTION;
-        key: TKey;
-        value: OnyxMergeCollectionInput<TKey>;
+    [OnyxUtils.METHOD.MERGE_COLLECTION]: {
+        key: CollectionKeyBase;
+        value: OnyxMergeCollectionInput<CollectionKeyBase>;
     };
-}[CollectionKeyBase];
+    [OnyxUtils.METHOD.SET_COLLECTION]: {
+        key: CollectionKeyBase;
+        value: OnyxMergeCollectionInput<CollectionKeyBase>;
+    };
+};
+/**
+ * OnyxUpdate type includes all onyx methods used in OnyxMethodValueMap.
+ * If a new method is added to OnyxUtils.METHOD constant, it must be added to OnyxMethodValueMap type.
+ * Otherwise it will show static type errors.
+ */
+type OnyxUpdate = {
+    [Method in OnyxMethod]: {
+        onyxMethod: Method;
+    } & OnyxMethodValueMap[Method];
+}[OnyxMethod];
 /**
  * Represents the options used in `Onyx.init()` method.
  */
@@ -393,4 +402,4 @@ type MixedOperationsQueue = {
     merge: OnyxInputKeyValueMapping;
     set: OnyxInputKeyValueMapping;
 };
-export type { BaseConnectOptions, Collection, CollectionConnectCallback, CollectionConnectOptions, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, DefaultConnectOptions, ExtractOnyxCollectionValue, GenericFunction, InitOptions, Key, KeyValueMapping, Mapping, NonNull, NonUndefined, OnyxInputKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxUpdate, OnyxValue, Selector, WithOnyxConnectOptions, MixedOperationsQueue, };
+export type { BaseConnectOptions, Collection, CollectionConnectCallback, CollectionConnectOptions, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, DefaultConnectOptions, ExtractOnyxCollectionValue, GenericFunction, InitOptions, Key, KeyValueMapping, Mapping, NonNull, NonUndefined, OnyxInputKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxMethod, OnyxMethodMap, OnyxUpdate, OnyxValue, Selector, WithOnyxConnectOptions, MixedOperationsQueue, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-onyx",
-  "version": "2.0.80",
+  "version": "2.0.82",
   "author": "Expensify, Inc.",
   "homepage": "https://expensify.com",
   "description": "State management for React Native",