react-native-onyx 2.0.117 → 2.0.119

package/API.md

@@ -29,7 +29,7 @@ applied in the order they were called. Note: <code>Onyx.set()</code> calls do no
 <code>Onyx.merge()</code> and <code>Onyx.set()</code>.</p>
 </dd>
 <dt><a href="#mergeCollection">mergeCollection(collectionKey, collection)</a></dt>
-<dd><p>Merges a collection based on their keys</p>
+<dd><p>Merges a collection based on their keys.</p>
 </dd>
 <dt><a href="#clear">clear(keysToPreserve)</a></dt>
 <dd><p>Clear out all the data in the store</p>
@@ -158,7 +158,7 @@ Onyx.merge(ONYXKEYS.POLICY, {name: 'My Workspace'}); // -> {id: 1, name: 'My Wor
 <a name="mergeCollection"></a>
 
 ## mergeCollection(collectionKey, collection)
-Merges a collection based on their keys
+Merges a collection based on their keys.
 
 **Kind**: global function  
 

package/README.md

@@ -59,6 +59,33 @@ API.Authenticate(params)
 
 The data will then be cached and stored via [`AsyncStorage`](https://github.com/react-native-async-storage/async-storage).
 
+### Performance Options for Large Objects
+
+For performance-critical scenarios with large objects, `Onyx.set()` accepts optional flags to skip expensive operations:
+
+```javascript
+Onyx.set(ONYXKEYS.LARGE_DATA, computedValue, {
+    skipCacheCheck: true,     // Skip deep equality check
+    skipNullRemoval: true,    // Skip null value pruning
+});
+```
+
+**Options:**
+- `skipCacheCheck`: Skips the deep equality comparison with the cached value. By default, Onyx compares new values against cached ones to avoid unnecessary updates. For large objects, this comparison can be expensive.
+- `skipNullRemoval`: Skips the removal of `null` values from nested objects. By default, Onyx removes `null` values before storage. Use this when `null` values are meaningful in your data structure.
+
+#### When to Use SetOptions
+- **Use `skipCacheCheck: true`** for:
+  - Large objects where deep equality checking is expensive
+  - Values that you know have changed
+
+- **Use `skipNullRemoval: true`** for:
+  - Computed values where `null` represents a legitimate result
+  - Data structures where `null` has semantic meaning
+  - Values that should preserve their exact structure
+
+**Note**: These options are recommended only for large objects where performance is critical. Most use cases should use the standard `Onyx.set(key, value)` syntax.
+
 ## Merging data
 
 We can also use `Onyx.merge()` to merge new `Object` or `Array` data in with existing data.

package/dist/Onyx.d.ts

@@ -1,5 +1,5 @@
 import * as Logger from './Logger';
-import type { CollectionKeyBase, ConnectOptions, InitOptions, Mapping, OnyxKey, OnyxMergeCollectionInput, OnyxMergeInput, OnyxMultiSetInput, OnyxSetInput, OnyxUpdate } from './types';
+import type { CollectionKeyBase, ConnectOptions, InitOptions, Mapping, OnyxKey, OnyxMergeCollectionInput, OnyxMergeInput, OnyxMultiSetInput, OnyxSetInput, OnyxUpdate, SetOptions } from './types';
 import type { Connection } from './OnyxConnectionManager';
 /** Initialize the store with actions and listening for storage events */
 declare function init({ keys, initialKeyStates, evictableKeys, maxCachedKeysCount, shouldSyncMultipleInstances, debugSetState, enablePerformanceMetrics, skippableCollectionMemberIDs, fullyMergedSnapshotKeys, }: InitOptions): void;
@@ -49,8 +49,9 @@ declare function disconnect(connection: Connection): void;
  *
  * @param key ONYXKEY to set
  * @param value value to store
+ * @param options optional configuration object
  */
-declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxSetInput<TKey>): Promise<void>;
+declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxSetInput<TKey>, options?: SetOptions): Promise<void>;
 /**
  * Sets multiple keys and values
  *
@@ -77,7 +78,7 @@ declare function multiSet(data: OnyxMultiSetInput): Promise<void>;
  */
 declare function merge<TKey extends OnyxKey>(key: TKey, changes: OnyxMergeInput<TKey>): Promise<void>;
 /**
- * Merges a collection based on their keys
+ * Merges a collection based on their keys.
  *
  * @example
  *
@@ -155,4 +156,4 @@ declare const Onyx: {
     registerLogger: typeof Logger.registerLogger;
 };
 export default Onyx;
-export type { OnyxUpdate, Mapping, ConnectOptions };
+export type { OnyxUpdate, Mapping, ConnectOptions, SetOptions };

package/dist/Onyx.js

@@ -26,8 +26,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-/* eslint-disable no-continue */
-const underscore_1 = __importDefault(require("underscore"));
 const Logger = __importStar(require("./Logger"));
 const OnyxCache_1 = __importStar(require("./OnyxCache"));
 const PerformanceUtils = __importStar(require("./PerformanceUtils"));
@@ -39,6 +37,7 @@ const logMessages_1 = __importDefault(require("./logMessages"));
 const OnyxConnectionManager_1 = __importDefault(require("./OnyxConnectionManager"));
 const GlobalSettings = __importStar(require("./GlobalSettings"));
 const metrics_1 = __importDefault(require("./metrics"));
+const OnyxMerge_1 = __importDefault(require("./OnyxMerge"));
 /** Initialize the store with actions and listening for storage events */
 function init({ keys = {}, initialKeyStates = {}, evictableKeys = [], maxCachedKeysCount = 1000, shouldSyncMultipleInstances = !!global.localStorage, debugSetState = false, enablePerformanceMetrics = false, skippableCollectionMemberIDs = [], fullyMergedSnapshotKeys = [], }) {
     var _a;
@@ -115,8 +114,9 @@ function disconnect(connection) {
  *
  * @param key ONYXKEY to set
  * @param value value to store
+ * @param options optional configuration object
  */
-function set(key, value) {
+function set(key, value, options) {
     // When we use Onyx.set to set a key we want to clear the current delta changes from Onyx.merge that were queued
     // before the value was set. If Onyx.merge is currently reading the old value from storage, it will then not apply the changes.
     if (OnyxUtils_1.default.hasPendingMergeForKey(key)) {
@@ -151,31 +151,26 @@ function set(key, value) {
         Logger.logAlert(logMessages_1.default.incompatibleUpdateAlert(key, 'set', existingValueType, newValueType));
         return Promise.resolve();
     }
-    // If the value is null, we remove the key from storage
-    const { value: valueAfterRemoving, wasRemoved } = OnyxUtils_1.default.removeNullValues(key, value);
-    const logSetCall = (hasChanged = true) => {
-        // Logging properties only since values could be sensitive things we don't want to log
-        Logger.logInfo(`set called for key: ${key}${underscore_1.default.isObject(value) ? ` properties: ${underscore_1.default.keys(value).join(',')}` : ''} hasChanged: ${hasChanged}`);
-    };
-    // Calling "OnyxUtils.removeNullValues" removes the key from storage and cache and updates the subscriber.
+    // If the change is null, we can just delete the key.
     // Therefore, we don't need to further broadcast and update the value so we can return early.
-    if (wasRemoved) {
-        logSetCall();
+    if (value === null) {
+        OnyxUtils_1.default.remove(key);
+        OnyxUtils_1.default.logKeyRemoved(OnyxUtils_1.default.METHOD.SET, key);
         return Promise.resolve();
     }
-    const valueWithoutNullValues = valueAfterRemoving;
-    const hasChanged = OnyxCache_1.default.hasValueChanged(key, valueWithoutNullValues);
-    logSetCall(hasChanged);
+    const valueWithoutNestedNullValues = ((options === null || options === void 0 ? void 0 : options.skipNullRemoval) ? value : utils_1.default.removeNestedNullValues(value));
+    const hasChanged = (options === null || options === void 0 ? void 0 : options.skipCacheCheck) ? true : OnyxCache_1.default.hasValueChanged(key, valueWithoutNestedNullValues);
+    OnyxUtils_1.default.logKeyChanged(OnyxUtils_1.default.METHOD.SET, key, value, hasChanged);
     // This approach prioritizes fast UI changes without waiting for data to be stored in device storage.
-    const updatePromise = OnyxUtils_1.default.broadcastUpdate(key, valueWithoutNullValues, hasChanged);
+    const updatePromise = OnyxUtils_1.default.broadcastUpdate(key, valueWithoutNestedNullValues, hasChanged);
     // If the value has not changed or the key got removed, calling Storage.setItem() would be redundant and a waste of performance, so return early instead.
     if (!hasChanged) {
         return updatePromise;
     }
-    return storage_1.default.setItem(key, valueWithoutNullValues)
-        .catch((error) => OnyxUtils_1.default.evictStorageAndRetry(error, set, key, valueWithoutNullValues))
+    return storage_1.default.setItem(key, valueWithoutNestedNullValues)
+        .catch((error) => OnyxUtils_1.default.evictStorageAndRetry(error, set, key, valueWithoutNestedNullValues))
         .then(() => {
-        OnyxUtils_1.default.sendActionToDevTools(OnyxUtils_1.default.METHOD.SET, key, valueWithoutNullValues);
+        OnyxUtils_1.default.sendActionToDevTools(OnyxUtils_1.default.METHOD.SET, key, valueWithoutNestedNullValues);
         return updatePromise;
     });
 }
@@ -276,8 +271,6 @@ function merge(key, changes) {
             return Promise.resolve();
         }
         try {
-            // We first only merge the changes, so we can provide these to the native implementation (SQLite uses only delta changes in "JSON_PATCH" to merge)
-            // We don't want to remove null values from the "batchedDeltaChanges", because SQLite uses them to remove keys from storage natively.
             const validChanges = mergeQueue[key].filter((change) => {
                 const { isCompatible, existingValueType, newValueType } = utils_1.default.checkCompatibilityWithExistingValue(change, existingValue);
                 if (!isCompatible) {
@@ -288,42 +281,18 @@ function merge(key, changes) {
             if (!validChanges.length) {
                 return Promise.resolve();
             }
-            const batchedDeltaChanges = OnyxUtils_1.default.applyMerge(undefined, validChanges, false);
-            // Case (1): When there is no existing value in storage, we want to set the value instead of merge it.
-            // Case (2): The presence of a top-level `null` in the merge queue instructs us to drop the whole existing value.
-            // In this case, we can't simply merge the batched changes with the existing value, because then the null in the merge queue would have no effect
-            const shouldSetValue = !existingValue || mergeQueue[key].includes(null);
-            // Clean up the write queue, so we don't apply these changes again
+            // Clean up the write queue, so we don't apply these changes again.
             delete mergeQueue[key];
             delete mergeQueuePromise[key];
-            const logMergeCall = (hasChanged = true) => {
-                // Logging properties only since values could be sensitive things we don't want to log
-                Logger.logInfo(`merge called for key: ${key}${underscore_1.default.isObject(batchedDeltaChanges) ? ` properties: ${underscore_1.default.keys(batchedDeltaChanges).join(',')}` : ''} hasChanged: ${hasChanged}`);
-            };
-            // If the batched changes equal null, we want to remove the key from storage, to reduce storage size
-            const { wasRemoved } = OnyxUtils_1.default.removeNullValues(key, batchedDeltaChanges);
-            // Calling "OnyxUtils.removeNullValues" removes the key from storage and cache and updates the subscriber.
+            // If the last change is null, we can just delete the key.
             // Therefore, we don't need to further broadcast and update the value so we can return early.
-            if (wasRemoved) {
-                logMergeCall();
+            if (validChanges.at(-1) === null) {
+                OnyxUtils_1.default.remove(key);
+                OnyxUtils_1.default.logKeyRemoved(OnyxUtils_1.default.METHOD.MERGE, key);
                 return Promise.resolve();
             }
-            // For providers that can't handle delta changes, we need to merge the batched changes with the existing value beforehand.
-            // The "preMergedValue" will be directly "set" in storage instead of being merged
-            // Therefore we merge the batched changes with the existing value to get the final merged value that will be stored.
-            // We can remove null values from the "preMergedValue", because "null" implicates that the user wants to remove a value from storage.
-            const preMergedValue = OnyxUtils_1.default.applyMerge(shouldSetValue ? undefined : existingValue, [batchedDeltaChanges], true);
-            // In cache, we don't want to remove the key if it's null to improve performance and speed up the next merge.
-            const hasChanged = OnyxCache_1.default.hasValueChanged(key, preMergedValue);
-            logMergeCall(hasChanged);
-            // This approach prioritizes fast UI changes without waiting for data to be stored in device storage.
-            const updatePromise = OnyxUtils_1.default.broadcastUpdate(key, preMergedValue, hasChanged);
-            // If the value has not changed, calling Storage.setItem() would be redundant and a waste of performance, so return early instead.
-            if (!hasChanged) {
-                return updatePromise;
-            }
-            return storage_1.default.mergeItem(key, batchedDeltaChanges, preMergedValue, shouldSetValue).then(() => {
-                OnyxUtils_1.default.sendActionToDevTools(OnyxUtils_1.default.METHOD.MERGE, key, changes, preMergedValue);
+            return OnyxMerge_1.default.applyMerge(key, existingValue, validChanges).then(({ mergedValue, updatePromise }) => {
+                OnyxUtils_1.default.sendActionToDevTools(OnyxUtils_1.default.METHOD.MERGE, key, changes, mergedValue);
                 return updatePromise;
             });
         }
@@ -335,7 +304,7 @@ function merge(key, changes) {
     return mergeQueuePromise[key];
 }
 /**
- * Merges a collection based on their keys
+ * Merges a collection based on their keys.
  *
  * @example
  *
@@ -348,98 +317,7 @@ function merge(key, changes) {
  * @param collection Object collection keyed by individual collection member keys and values
  */
 function mergeCollection(collectionKey, collection) {
-    if (!OnyxUtils_1.default.isValidNonEmptyCollectionForMerge(collection)) {
-        Logger.logInfo('mergeCollection() called with invalid or empty value. Skipping this update.');
-        return Promise.resolve();
-    }
-    let resultCollection = collection;
-    let resultCollectionKeys = Object.keys(resultCollection);
-    // Confirm all the collection keys belong to the same parent
-    if (!OnyxUtils_1.default.doAllCollectionItemsBelongToSameParent(collectionKey, resultCollectionKeys)) {
-        return Promise.resolve();
-    }
-    const skippableCollectionMemberIDs = OnyxUtils_1.default.getSkippableCollectionMemberIDs();
-    if (skippableCollectionMemberIDs.size) {
-        resultCollection = resultCollectionKeys.reduce((result, key) => {
-            try {
-                const [, collectionMemberID] = OnyxUtils_1.default.splitCollectionMemberKey(key, collectionKey);
-                // If the collection member key is a skippable one we set its value to null.
-                // eslint-disable-next-line no-param-reassign
-                result[key] = !skippableCollectionMemberIDs.has(collectionMemberID) ? resultCollection[key] : null;
-            }
-            catch (_a) {
-                // Something went wrong during split, so we assign the data to result anyway.
-                // eslint-disable-next-line no-param-reassign
-                result[key] = resultCollection[key];
-            }
-            return result;
-        }, {});
-    }
-    resultCollectionKeys = Object.keys(resultCollection);
-    return OnyxUtils_1.default.getAllKeys()
-        .then((persistedKeys) => {
-        // Split to keys that exist in storage and keys that don't
-        const keys = resultCollectionKeys.filter((key) => {
-            if (resultCollection[key] === null) {
-                OnyxUtils_1.default.remove(key);
-                return false;
-            }
-            return true;
-        });
-        const existingKeys = keys.filter((key) => persistedKeys.has(key));
-        const cachedCollectionForExistingKeys = OnyxUtils_1.default.getCachedCollection(collectionKey, existingKeys);
-        const existingKeyCollection = existingKeys.reduce((obj, key) => {
-            const { isCompatible, existingValueType, newValueType } = utils_1.default.checkCompatibilityWithExistingValue(resultCollection[key], cachedCollectionForExistingKeys[key]);
-            if (!isCompatible) {
-                Logger.logAlert(logMessages_1.default.incompatibleUpdateAlert(key, 'mergeCollection', existingValueType, newValueType));
-                return obj;
-            }
-            // eslint-disable-next-line no-param-reassign
-            obj[key] = resultCollection[key];
-            return obj;
-        }, {});
-        const newCollection = {};
-        keys.forEach((key) => {
-            if (persistedKeys.has(key)) {
-                return;
-            }
-            newCollection[key] = resultCollection[key];
-        });
-        // When (multi-)merging the values with the existing values in storage,
-        // we don't want to remove nested null values from the data that we pass to the storage layer,
-        // because the storage layer uses them to remove nested keys from storage natively.
-        const keyValuePairsForExistingCollection = OnyxUtils_1.default.prepareKeyValuePairsForStorage(existingKeyCollection, false);
-        // We can safely remove nested null values when using (multi-)set,
-        // because we will simply overwrite the existing values in storage.
-        const keyValuePairsForNewCollection = OnyxUtils_1.default.prepareKeyValuePairsForStorage(newCollection, true);
-        const promises = [];
-        // We need to get the previously existing values so we can compare the new ones
-        // against them, to avoid unnecessary subscriber updates.
-        const previousCollectionPromise = Promise.all(existingKeys.map((key) => OnyxUtils_1.default.get(key).then((value) => [key, value]))).then(Object.fromEntries);
-        // New keys will be added via multiSet while existing keys will be updated using multiMerge
-        // This is because setting a key that doesn't exist yet with multiMerge will throw errors
-        if (keyValuePairsForExistingCollection.length > 0) {
-            promises.push(storage_1.default.multiMerge(keyValuePairsForExistingCollection));
-        }
-        if (keyValuePairsForNewCollection.length > 0) {
-            promises.push(storage_1.default.multiSet(keyValuePairsForNewCollection));
-        }
-        // finalMergedCollection contains all the keys that were merged, without the keys of incompatible updates
-        const finalMergedCollection = Object.assign(Object.assign({}, existingKeyCollection), newCollection);
-        // Prefill cache if necessary by calling get() on any existing keys and then merge original data to cache
-        // and update all subscribers
-        const promiseUpdate = previousCollectionPromise.then((previousCollection) => {
-            OnyxCache_1.default.merge(finalMergedCollection);
-            return OnyxUtils_1.default.scheduleNotifyCollectionSubscribers(collectionKey, finalMergedCollection, previousCollection);
-        });
-        return Promise.all(promises)
-            .catch((error) => OnyxUtils_1.default.evictStorageAndRetry(error, mergeCollection, collectionKey, resultCollection))
-            .then(() => {
-            OnyxUtils_1.default.sendActionToDevTools(OnyxUtils_1.default.METHOD.MERGE_COLLECTION, undefined, resultCollection);
-            return promiseUpdate;
-        });
-    })
-        .then(() => undefined);
+    return OnyxUtils_1.default.mergeCollectionWithPatches(collectionKey, collection);
 }
 /**
  * Clear out all the data in the store
@@ -628,35 +506,42 @@ function update(data) {
             const operations = updateQueue[key];
             // Remove the collection-related key from the updateQueue so that it won't be processed individually.
             delete updateQueue[key];
-            const updatedValue = OnyxUtils_1.default.applyMerge(undefined, operations, false);
+            const batchedChanges = OnyxUtils_1.default.mergeAndMarkChanges(operations);
             if (operations[0] === null) {
                 // eslint-disable-next-line no-param-reassign
-                queue.set[key] = updatedValue;
+                queue.set[key] = batchedChanges.result;
             }
             else {
                 // eslint-disable-next-line no-param-reassign
-                queue.merge[key] = updatedValue;
+                queue.merge[key] = batchedChanges.result;
+                if (batchedChanges.replaceNullPatches.length > 0) {
+                    // eslint-disable-next-line no-param-reassign
+                    queue.mergeReplaceNullPatches[key] = batchedChanges.replaceNullPatches;
+                }
             }
             return queue;
         }, {
             merge: {},
+            mergeReplaceNullPatches: {},
             set: {},
         });
         if (!utils_1.default.isEmptyObject(batchedCollectionUpdates.merge)) {
-            promises.push(() => mergeCollection(collectionKey, batchedCollectionUpdates.merge));
+            promises.push(() => OnyxUtils_1.default.mergeCollectionWithPatches(collectionKey, batchedCollectionUpdates.merge, batchedCollectionUpdates.mergeReplaceNullPatches));
         }
         if (!utils_1.default.isEmptyObject(batchedCollectionUpdates.set)) {
             promises.push(() => multiSet(batchedCollectionUpdates.set));
         }
     });
     Object.entries(updateQueue).forEach(([key, operations]) => {
-        const batchedChanges = OnyxUtils_1.default.applyMerge(undefined, operations, false);
         if (operations[0] === null) {
+            const batchedChanges = OnyxUtils_1.default.mergeChanges(operations).result;
             promises.push(() => set(key, batchedChanges));
+            return;
         }
-        else {
-            promises.push(() => merge(key, batchedChanges));
-        }
+        const mergePromises = operations.map((operation) => {
+            return merge(key, operation);
+        });
+        promises.push(() => { var _a; return (_a = mergePromises.at(0)) !== null && _a !== void 0 ? _a : Promise.resolve(); });
     });
     const snapshotPromises = OnyxUtils_1.default.updateSnapshots(data, merge);
     // We need to run the snapshot updates before the other updates so the snapshot data can be updated before the loading state in the snapshot

package/dist/OnyxCache.js

@@ -165,7 +165,10 @@ class OnyxCache {
         if (typeof data !== 'object' || Array.isArray(data)) {
             throw new Error('data passed to cache.merge() must be an Object of onyx key/value pairs');
         }
-        this.storageMap = Object.assign({}, utils_1.default.fastMerge(this.storageMap, data));
+        this.storageMap = Object.assign({}, utils_1.default.fastMerge(this.storageMap, data, {
+            shouldRemoveNestedNulls: true,
+            objectRemovalMode: 'replace',
+        }).result);
         Object.entries(data).forEach(([key, value]) => {
             this.addKey(key);
             this.addToAccessedKeys(key);

package/dist/OnyxMerge/index.d.ts

@@ -0,0 +1,5 @@
+import type { ApplyMerge } from './types';
+declare const OnyxMerge: {
+    applyMerge: ApplyMerge;
+};
+export default OnyxMerge;

package/dist/OnyxMerge/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const OnyxCache_1 = __importDefault(require("../OnyxCache"));
+const OnyxUtils_1 = __importDefault(require("../OnyxUtils"));
+const storage_1 = __importDefault(require("../storage"));
+const applyMerge = (key, existingValue, validChanges) => {
+    const { result: mergedValue } = OnyxUtils_1.default.mergeChanges(validChanges, existingValue);
+    // In cache, we don't want to remove the key if it's null to improve performance and speed up the next merge.
+    const hasChanged = OnyxCache_1.default.hasValueChanged(key, mergedValue);
+    // Logging properties only since values could be sensitive things we don't want to log.
+    OnyxUtils_1.default.logKeyChanged(OnyxUtils_1.default.METHOD.MERGE, key, mergedValue, hasChanged);
+    // This approach prioritizes fast UI changes without waiting for data to be stored in device storage.
+    const updatePromise = OnyxUtils_1.default.broadcastUpdate(key, mergedValue, hasChanged);
+    // If the value has not changed, calling Storage.setItem() would be redundant and a waste of performance, so return early instead.
+    if (!hasChanged) {
+        return Promise.resolve({ mergedValue, updatePromise });
+    }
+    // For web platforms we use `setItem` since the object was already merged with its changes before.
+    return storage_1.default.setItem(key, mergedValue).then(() => ({
+        mergedValue,
+        updatePromise,
+    }));
+};
+const OnyxMerge = {
+    applyMerge,
+};
+exports.default = OnyxMerge;

package/dist/OnyxMerge/index.native.d.ts

@@ -0,0 +1,5 @@
+import type { ApplyMerge } from './types';
+declare const OnyxMerge: {
+    applyMerge: ApplyMerge;
+};
+export default OnyxMerge;

package/dist/OnyxMerge/index.native.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const OnyxUtils_1 = __importDefault(require("../OnyxUtils"));
+const OnyxCache_1 = __importDefault(require("../OnyxCache"));
+const storage_1 = __importDefault(require("../storage"));
+const applyMerge = (key, existingValue, validChanges) => {
+    // If any of the changes is null, we need to discard the existing value.
+    const baseValue = validChanges.includes(null) ? undefined : existingValue;
+    // We first batch the changes into a single change with object removal marks,
+    // so that SQLite can merge the changes more efficiently.
+    const { result: batchedChanges, replaceNullPatches } = OnyxUtils_1.default.mergeAndMarkChanges(validChanges);
+    // We then merge the batched changes with the existing value, because we need to final merged value to broadcast to subscribers.
+    const { result: mergedValue } = OnyxUtils_1.default.mergeChanges([batchedChanges], baseValue);
+    // In cache, we don't want to remove the key if it's null to improve performance and speed up the next merge.
+    const hasChanged = OnyxCache_1.default.hasValueChanged(key, mergedValue);
+    // Logging properties only since values could be sensitive things we don't want to log.
+    OnyxUtils_1.default.logKeyChanged(OnyxUtils_1.default.METHOD.MERGE, key, mergedValue, hasChanged);
+    // This approach prioritizes fast UI changes without waiting for data to be stored in device storage.
+    const updatePromise = OnyxUtils_1.default.broadcastUpdate(key, mergedValue, hasChanged);
+    // If the value has not changed, calling Storage.setItem() would be redundant and a waste of performance, so return early instead.
+    if (!hasChanged) {
+        return Promise.resolve({ mergedValue, updatePromise });
+    }
+    // For native platforms we use `mergeItem` that will take advantage of JSON_PATCH and JSON_REPLACE SQL operations to
+    // merge the object in a performant way.
+    return storage_1.default.mergeItem(key, batchedChanges, replaceNullPatches).then(() => ({
+        mergedValue,
+        updatePromise,
+    }));
+};
+const OnyxMerge = {
+    applyMerge,
+};
+exports.default = OnyxMerge;

package/dist/OnyxMerge/types.d.ts

@@ -0,0 +1,7 @@
+import type { OnyxInput, OnyxKey } from '../types';
+type ApplyMergeResult<TValue> = {
+    mergedValue: TValue;
+    updatePromise: Promise<void>;
+};
+type ApplyMerge = <TKey extends OnyxKey, TValue extends OnyxInput<OnyxKey> | undefined, TChange extends OnyxInput<OnyxKey> | null>(key: TKey, existingValue: TValue, validChanges: TChange[]) => Promise<ApplyMergeResult<TChange>>;
+export type { ApplyMerge, ApplyMergeResult };

package/dist/OnyxMerge/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/OnyxUtils.d.ts

@@ -1,8 +1,10 @@
 import type { ValueOf } from 'type-fest';
 import type Onyx from './Onyx';
-import type { CollectionKey, CollectionKeyBase, ConnectOptions, DeepRecord, KeyValueMapping, Mapping, OnyxCollection, OnyxEntry, OnyxInput, OnyxKey, OnyxMergeCollectionInput, OnyxUpdate, OnyxValue, Selector } from './types';
+import type { CollectionKey, CollectionKeyBase, ConnectOptions, DeepRecord, KeyValueMapping, Mapping, MultiMergeReplaceNullPatches, OnyxCollection, OnyxEntry, OnyxInput, OnyxKey, OnyxMergeCollectionInput, OnyxUpdate, OnyxValue, Selector } from './types';
+import type { FastMergeResult } from './utils';
 import type { WithOnyxState } from './withOnyx/types';
 import type { DeferredTask } from './createDeferredTask';
+import type { StorageKeyValuePair } from './storage/providers/types';
 declare const METHOD: {
     readonly SET: "set";
     readonly MERGE: "merge";
@@ -194,32 +196,29 @@ declare function evictStorageAndRetry<TMethod extends typeof Onyx.set | typeof O
  */
 declare function broadcastUpdate<TKey extends OnyxKey>(key: TKey, value: OnyxValue<TKey>, hasChanged?: boolean): Promise<void>;
 declare function hasPendingMergeForKey(key: OnyxKey): boolean;
-type RemoveNullValuesOutput<Value extends OnyxInput<OnyxKey> | undefined> = {
-    value: Value;
-    wasRemoved: boolean;
-};
-/**
- * Removes a key from storage if the value is null.
- * Otherwise removes all nested null values in objects,
- * if shouldRemoveNestedNulls is true and returns the object.
- *
- * @returns The value without null values and a boolean "wasRemoved", which indicates if the key got removed completely
- */
-declare function removeNullValues<Value extends OnyxInput<OnyxKey> | undefined>(key: OnyxKey, value: Value, shouldRemoveNestedNulls?: boolean): RemoveNullValuesOutput<Value>;
 /**
  * Storage expects array like: [["@MyApp_user", value_1], ["@MyApp_key", value_2]]
  * This method transforms an object like {'@MyApp_user': myUserValue, '@MyApp_key': myKeyValue}
  * to an array of key-value pairs in the above format and removes key-value pairs that are being set to null
-
-* @return an array of key - value pairs <[key, value]>
+ *
+ * @return an array of key - value pairs <[key, value]>
  */
-declare function prepareKeyValuePairsForStorage(data: Record<OnyxKey, OnyxInput<OnyxKey>>, shouldRemoveNestedNulls: boolean): Array<[OnyxKey, OnyxInput<OnyxKey>]>;
+declare function prepareKeyValuePairsForStorage(data: Record<OnyxKey, OnyxInput<OnyxKey>>, shouldRemoveNestedNulls?: boolean, replaceNullPatches?: MultiMergeReplaceNullPatches): StorageKeyValuePair[];
 /**
- * Merges an array of changes with an existing value
+ * Merges an array of changes with an existing value or creates a single change.
  *
- * @param changes Array of changes that should be applied to the existing value
+ * @param changes Array of changes that should be merged
+ * @param existingValue The existing value that should be merged with the changes
  */
-declare function applyMerge<TValue extends OnyxInput<OnyxKey> | undefined, TChange extends OnyxInput<OnyxKey> | undefined>(existingValue: TValue, changes: TChange[], shouldRemoveNestedNulls: boolean): TChange;
+declare function mergeChanges<TValue extends OnyxInput<OnyxKey> | undefined, TChange extends OnyxInput<OnyxKey> | undefined>(changes: TChange[], existingValue?: TValue): FastMergeResult<TChange>;
+/**
+ * Merges an array of changes with an existing value or creates a single change.
+ * It will also mark deep nested objects that need to be entirely replaced during the merge.
+ *
+ * @param changes Array of changes that should be merged
+ * @param existingValue The existing value that should be merged with the changes
+ */
+declare function mergeAndMarkChanges<TValue extends OnyxInput<OnyxKey> | undefined, TChange extends OnyxInput<OnyxKey> | undefined>(changes: TChange[], existingValue?: TValue): FastMergeResult<TChange>;
 /**
  * Merge user provided default key value pairs.
  */
@@ -246,6 +245,19 @@ declare function subscribeToKey<TKey extends OnyxKey>(connectOptions: ConnectOpt
  */
 declare function unsubscribeFromKey(subscriptionID: number): void;
 declare function updateSnapshots(data: OnyxUpdate[], mergeFn: typeof Onyx.merge): Array<() => Promise<void>>;
+/**
+ * Merges a collection based on their keys.
+ * Serves as core implementation for `Onyx.mergeCollection()` public function, the difference being
+ * that this internal function allows passing an additional `mergeReplaceNullPatches` parameter.
+ *
+ * @param collectionKey e.g. `ONYXKEYS.COLLECTION.REPORT`
+ * @param collection Object collection keyed by individual collection member keys and values
+ * @param mergeReplaceNullPatches Record where the key is a collection member key and the value is a list of
+ * tuples that we'll use to replace the nested objects of that collection member record with something else.
+ */
+declare function mergeCollectionWithPatches<TKey extends CollectionKeyBase, TMap>(collectionKey: TKey, collection: OnyxMergeCollectionInput<TKey, TMap>, mergeReplaceNullPatches?: MultiMergeReplaceNullPatches): Promise<void>;
+declare function logKeyChanged(onyxMethod: Extract<OnyxMethod, 'set' | 'merge'>, key: OnyxKey, value: unknown, hasChanged: boolean): void;
+declare function logKeyRemoved(onyxMethod: Extract<OnyxMethod, 'set' | 'merge'>, key: OnyxKey): void;
 /**
  * Clear internal variables used in this file, useful in test environments.
  */
@@ -288,9 +300,9 @@ declare const OnyxUtils: {
     evictStorageAndRetry: typeof evictStorageAndRetry;
     broadcastUpdate: typeof broadcastUpdate;
     hasPendingMergeForKey: typeof hasPendingMergeForKey;
-    removeNullValues: typeof removeNullValues;
     prepareKeyValuePairsForStorage: typeof prepareKeyValuePairsForStorage;
-    applyMerge: typeof applyMerge;
+    mergeChanges: typeof mergeChanges;
+    mergeAndMarkChanges: typeof mergeAndMarkChanges;
     initializeWithDefaultKeyStates: typeof initializeWithDefaultKeyStates;
     getSnapshotKey: typeof getSnapshotKey;
     multiGet: typeof multiGet;
@@ -306,6 +318,9 @@ declare const OnyxUtils: {
     addKeyToRecentlyAccessedIfNeeded: typeof addKeyToRecentlyAccessedIfNeeded;
     reduceCollectionWithSelector: typeof reduceCollectionWithSelector;
     updateSnapshots: typeof updateSnapshots;
+    mergeCollectionWithPatches: typeof mergeCollectionWithPatches;
+    logKeyChanged: typeof logKeyChanged;
+    logKeyRemoved: typeof logKeyRemoved;
 };
 export type { OnyxMethod };
 export default OnyxUtils;