react-native-onyx 2.0.42 → 2.0.44

package/dist/Onyx.d.ts

@@ -1,5 +1,5 @@
 import * as Logger from './Logger';
-import type { Collection, CollectionKeyBase, ConnectOptions, InitOptions, KeyValueMapping, Mapping, NonUndefined, NullableKeyValueMapping, NullishDeep, OnyxEntry, OnyxKey, OnyxUpdate } from './types';
+import type { CollectionKeyBase, ConnectOptions, InitOptions, Mapping, OnyxKey, OnyxMergeCollectionInput, OnyxMergeInput, OnyxMultiSetInput, OnyxSetInput, OnyxUpdate } from './types';
 /** Initialize the store with actions and listening for storage events */
 declare function init({ keys, initialKeyStates, safeEvictionKeys, maxCachedKeysCount, shouldSyncMultipleInstances, debugSetState, }: InitOptions): void;
 /**
@@ -45,7 +45,7 @@ declare function disconnect(connectionID: number, keyToRemoveFromEvictionBlockli
  * @param key ONYXKEY to set
  * @param value value to store
  */
-declare function set<TKey extends OnyxKey>(key: TKey, value: NonUndefined<OnyxEntry<KeyValueMapping[TKey]>>): Promise<void>;
+declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxSetInput<TKey>): Promise<void>;
 /**
  * Sets multiple keys and values
  *
@@ -53,7 +53,7 @@ declare function set<TKey extends OnyxKey>(key: TKey, value: NonUndefined<OnyxEn
  *
  * @param data object keyed by ONYXKEYS and the values to set
  */
-declare function multiSet(data: Partial<NullableKeyValueMapping>): Promise<void>;
+declare function multiSet(data: OnyxMultiSetInput): Promise<void>;
 /**
  * Merge a new value into an existing value at a key.
  *
@@ -70,7 +70,7 @@ declare function multiSet(data: Partial<NullableKeyValueMapping>): Promise<void>
  * Onyx.merge(ONYXKEYS.POLICY, {id: 1}); // -> {id: 1}
  * Onyx.merge(ONYXKEYS.POLICY, {name: 'My Workspace'}); // -> {id: 1, name: 'My Workspace'}
  */
-declare function merge<TKey extends OnyxKey>(key: TKey, changes: NonUndefined<OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>>): Promise<void>;
+declare function merge<TKey extends OnyxKey>(key: TKey, changes: OnyxMergeInput<TKey>): Promise<void>;
 /**
  * Merges a collection based on their keys
  *
@@ -84,7 +84,7 @@ declare function merge<TKey extends OnyxKey>(key: TKey, changes: NonUndefined<On
  * @param collectionKey e.g. `ONYXKEYS.COLLECTION.REPORT`
  * @param collection Object collection keyed by individual collection member keys and values
  */
-declare function mergeCollection<TKey extends CollectionKeyBase, TMap>(collectionKey: TKey, collection: Collection<TKey, TMap, NullishDeep<KeyValueMapping[TKey]>>): Promise<void>;
+declare function mergeCollection<TKey extends CollectionKeyBase, TMap>(collectionKey: TKey, collection: OnyxMergeCollectionInput<TKey, TMap>): Promise<void>;
 /**
  * Clear out all the data in the store
  *

package/dist/Onyx.js

@@ -47,7 +47,7 @@ function init({ keys = {}, initialKeyStates = {}, safeEvictionKeys = [], maxCach
     storage_1.default.init();
     if (shouldSyncMultipleInstances) {
         (_a = storage_1.default.keepInstancesSync) === null || _a === void 0 ? void 0 : _a.call(storage_1.default, (key, value) => {
-            const prevValue = OnyxCache_1.default.getValue(key, false);
+            const prevValue = OnyxCache_1.default.get(key, false);
             OnyxCache_1.default.set(key, value);
             OnyxUtils_1.default.keyChanged(key, value, prevValue);
         });
@@ -106,7 +106,7 @@ function connect(connectOptions) {
         // Performance improvement
         // If the mapping is connected to an onyx key that is not a collection
         // we can skip the call to getAllKeys() and return an array with a single item
-        if (Boolean(mapping.key) && typeof mapping.key === 'string' && !mapping.key.endsWith('_') && OnyxCache_1.default.storageKeys.has(mapping.key)) {
+        if (Boolean(mapping.key) && typeof mapping.key === 'string' && !mapping.key.endsWith('_') && OnyxCache_1.default.getAllKeys().has(mapping.key)) {
             return new Set([mapping.key]);
         }
         return OnyxUtils_1.default.getAllKeys();
@@ -122,9 +122,9 @@ function connect(connectOptions) {
         // component. This null value will be filtered out so that the connected component can utilize defaultProps.
         if (matchingKeys.length === 0) {
             if (mapping.key && !OnyxUtils_1.default.isCollectionKey(mapping.key)) {
-                OnyxCache_1.default.set(mapping.key, null);
+                OnyxCache_1.default.addNullishStorageKey(mapping.key);
             }
-            // Here we cannot use batching because the null value is expected to be set immediately for default props
+            // Here we cannot use batching because the nullish value is expected to be set immediately for default props
             // or they will be undefined.
             OnyxUtils_1.default.sendDataToConnection(mapping, null, undefined, false);
             return;
@@ -192,8 +192,17 @@ function disconnect(connectionID, keyToRemoveFromEvictionBlocklist) {
  * @param value value to store
  */
 function set(key, value) {
-    // check if the value is compatible with the existing value in the storage
-    const existingValue = OnyxCache_1.default.getValue(key, false);
+    // 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)) {
+        delete OnyxUtils_1.default.getMergeQueue()[key];
+    }
+    const existingValue = OnyxCache_1.default.get(key, false);
+    // If the existing value as well as the new value are null, we can return early.
+    if (value === null && existingValue === null) {
+        return Promise.resolve();
+    }
+    // Check if the value is compatible with the existing value in the storage
     const { isCompatible, existingValueType, newValueType } = utils_1.default.checkCompatibilityWithExistingValue(value, existingValue);
     if (!isCompatible) {
         Logger.logAlert(logMessages_1.default.incompatibleUpdateAlert(key, 'set', existingValueType, newValueType));
@@ -201,17 +210,23 @@ function set(key, value) {
     }
     // If the value is null, we remove the key from storage
     const { value: valueAfterRemoving, wasRemoved } = OnyxUtils_1.default.removeNullValues(key, value);
-    const valueWithoutNullValues = valueAfterRemoving;
-    if (OnyxUtils_1.default.hasPendingMergeForKey(key)) {
-        delete OnyxUtils_1.default.getMergeQueue()[key];
+    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.
+    // Therefore, we don't need to further broadcast and update the value so we can return early.
+    if (wasRemoved) {
+        logSetCall();
+        return Promise.resolve();
     }
+    const valueWithoutNullValues = valueAfterRemoving;
     const hasChanged = OnyxCache_1.default.hasValueChanged(key, valueWithoutNullValues);
-    // 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}`);
+    logSetCall(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, wasRemoved);
+    const updatePromise = OnyxUtils_1.default.broadcastUpdate(key, valueWithoutNullValues, 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 || wasRemoved) {
+    if (!hasChanged) {
         return updatePromise;
     }
     return storage_1.default.setItem(key, valueWithoutNullValues)
@@ -229,18 +244,28 @@ function set(key, value) {
  * @param data object keyed by ONYXKEYS and the values to set
  */
 function multiSet(data) {
-    const keyValuePairs = OnyxUtils_1.default.prepareKeyValuePairsForStorage(data, true);
-    const updatePromises = keyValuePairs.map(([key, value]) => {
-        const prevValue = OnyxCache_1.default.getValue(key, false);
+    const allKeyValuePairs = OnyxUtils_1.default.prepareKeyValuePairsForStorage(data, true);
+    // When a key is set to null, we need to remove the remove the key from storage using "OnyxUtils.remove".
+    // Therefore, we filter the key value pairs to exclude null values and remove those keys explicitly.
+    const removePromises = [];
+    const keyValuePairsToUpdate = allKeyValuePairs.filter(([key, value]) => {
+        if (value === null) {
+            removePromises.push(OnyxUtils_1.default.remove(key));
+            return false;
+        }
+        return true;
+    });
+    const updatePromises = keyValuePairsToUpdate.map(([key, value]) => {
+        const prevValue = OnyxCache_1.default.get(key, false);
         // Update cache and optimistically inform subscribers on the next tick
         OnyxCache_1.default.set(key, value);
         return OnyxUtils_1.default.scheduleSubscriberUpdate(key, value, prevValue);
     });
-    return storage_1.default.multiSet(keyValuePairs)
+    return storage_1.default.multiSet(allKeyValuePairs)
         .catch((error) => OnyxUtils_1.default.evictStorageAndRetry(error, multiSet, data))
         .then(() => {
         OnyxUtils_1.default.sendActionToDevTools(OnyxUtils_1.default.METHOD.MULTI_SET, undefined, data);
-        return Promise.all(updatePromises);
+        return Promise.all([removePromises, updatePromises]);
     })
         .then(() => undefined);
 }
@@ -278,7 +303,7 @@ function merge(key, changes) {
     mergeQueuePromise[key] = OnyxUtils_1.default.get(key).then((existingValue) => {
         // Calls to Onyx.set after a merge will terminate the current merge process and clear the merge queue
         if (mergeQueue[key] == null) {
-            return undefined;
+            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)
@@ -291,7 +316,7 @@ function merge(key, changes) {
                 return isCompatible;
             });
             if (!validChanges.length) {
-                return undefined;
+                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.
@@ -301,8 +326,18 @@ function merge(key, changes) {
             // 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.
+            // Therefore, we don't need to further broadcast and update the value so we can return early.
+            if (wasRemoved) {
+                logMergeCall();
+                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.
@@ -310,12 +345,11 @@ function merge(key, changes) {
             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);
-            // 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}`);
+            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, wasRemoved);
+            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 || wasRemoved) {
+            if (!hasChanged) {
                 return updatePromise;
             }
             return storage_1.default.mergeItem(key, batchedDeltaChanges, preMergedValue, shouldSetValue).then(() => {
@@ -453,6 +487,7 @@ function mergeCollection(collectionKey, collection) {
 function clear(keysToPreserve = []) {
     return OnyxUtils_1.default.getAllKeys()
         .then((keys) => {
+        OnyxCache_1.default.clearNullishStorageKeys();
         const keysToBeClearedFromStorage = [];
         const keyValuesToResetAsCollection = {};
         const keyValuesToResetIndividually = {};
@@ -471,7 +506,7 @@ function clear(keysToPreserve = []) {
             // 2. Figure out whether it is a collection key or not,
             //      since collection key subscribers need to be updated differently
             if (!isKeyToPreserve) {
-                const oldValue = OnyxCache_1.default.getValue(key);
+                const oldValue = OnyxCache_1.default.get(key);
                 const newValue = (_a = defaultKeyStates[key]) !== null && _a !== void 0 ? _a : null;
                 if (newValue !== oldValue) {
                     OnyxCache_1.default.set(key, newValue);
@@ -496,7 +531,7 @@ function clear(keysToPreserve = []) {
         const updatePromises = [];
         // Notify the subscribers for each key/value group so they can receive the new values
         Object.entries(keyValuesToResetIndividually).forEach(([key, value]) => {
-            updatePromises.push(OnyxUtils_1.default.scheduleSubscriberUpdate(key, value, OnyxCache_1.default.getValue(key, false)));
+            updatePromises.push(OnyxUtils_1.default.scheduleSubscriberUpdate(key, value, OnyxCache_1.default.get(key, false)));
         });
         Object.entries(keyValuesToResetAsCollection).forEach(([key, value]) => {
             updatePromises.push(OnyxUtils_1.default.scheduleNotifyCollectionSubscribers(key, value));

package/dist/OnyxCache.d.ts

@@ -5,7 +5,9 @@ import type { OnyxKey, OnyxValue } from './types';
  */
 declare class OnyxCache {
     /** Cache of all the storage keys available in persistent storage */
-    storageKeys: Set<OnyxKey>;
+    private storageKeys;
+    /** A list of keys where a nullish value has been fetched from storage before, but the key still exists in cache */
+    private nullishStorageKeys;
     /** Unique list of keys maintained in access order (most recent at the end) */
     private recentKeys;
     /** A map of cached values */
@@ -21,16 +23,32 @@ declare class OnyxCache {
     /** Get all the storage keys */
     getAllKeys(): Set<OnyxKey>;
     /**
-     * Get a cached value from storage
-     * @param [shouldReindexCache] – This is an LRU cache, and by default accessing a value will make it become last in line to be evicted. This flag can be used to skip that and just access the value directly without side-effects.
+     * Allows to set all the keys at once.
+     * This is useful when we are getting
+     * all the keys from the storage provider
+     * and we want to keep the cache in sync.
+     *
+     * Previously, we had to call `addKey` in a loop
+     * to achieve the same result.
+     *
+     * @param keys - an array of keys
      */
-    getValue(key: OnyxKey, shouldReindexCache?: boolean): OnyxValue<OnyxKey>;
-    /** Check whether cache has data for the given key */
-    hasCacheForKey(key: OnyxKey): boolean;
+    setAllKeys(keys: OnyxKey[]): void;
     /** Saves a key in the storage keys list
      * Serves to keep the result of `getAllKeys` up to date
      */
     addKey(key: OnyxKey): void;
+    /** Used to set keys that are null/undefined in storage without adding null to the storage map */
+    addNullishStorageKey(key: OnyxKey): void;
+    /** Used to clear keys that are null/undefined in cache */
+    clearNullishStorageKeys(): void;
+    /** Check whether cache has data for the given key */
+    hasCacheForKey(key: OnyxKey): boolean;
+    /**
+     * Get a cached value from storage
+     * @param [shouldReindexCache] – This is an LRU cache, and by default accessing a value will make it become last in line to be evicted. This flag can be used to skip that and just access the value directly without side-effects.
+     */
+    get(key: OnyxKey, shouldReindexCache?: boolean): OnyxValue<OnyxKey>;
     /**
      * Set's a key value in cache
      * Adds the key to the storage keys list as well
@@ -43,18 +61,6 @@ declare class OnyxCache {
      * @param data - a map of (cache) key - values
      */
     merge(data: Record<OnyxKey, OnyxValue<OnyxKey>>): void;
-    /**
-     * Allows to set all the keys at once.
-     * This is useful when we are getting
-     * all the keys from the storage provider
-     * and we want to keep the cache in sync.
-     *
-     * Previously, we had to call `addKey` in a loop
-     * to achieve the same result.
-     *
-     * @param keys - an array of keys
-     */
-    setAllKeys(keys: OnyxKey[]): void;
     /**
      * Check whether the given task is already running
      * @param taskName - unique name given for the task

package/dist/OnyxCache.js

@@ -15,29 +15,30 @@ class OnyxCache {
         /** Maximum size of the keys store din cache */
         this.maxRecentKeysSize = 0;
         this.storageKeys = new Set();
+        this.nullishStorageKeys = new Set();
         this.recentKeys = new Set();
         this.storageMap = {};
         this.pendingPromises = new Map();
         // bind all public methods to prevent problems with `this`
-        (0, bindAll_1.default)(this, 'getAllKeys', 'getValue', 'hasCacheForKey', 'addKey', 'set', 'drop', 'merge', 'hasPendingTask', 'getTaskPromise', 'captureTask', 'removeLeastRecentlyUsedKeys', 'setRecentKeysLimit', 'setAllKeys');
+        (0, bindAll_1.default)(this, 'getAllKeys', 'get', 'hasCacheForKey', 'addKey', 'addNullishStorageKey', 'clearNullishStorageKeys', 'set', 'drop', 'merge', 'hasPendingTask', 'getTaskPromise', 'captureTask', 'removeLeastRecentlyUsedKeys', 'setRecentKeysLimit', 'setAllKeys');
     }
     /** Get all the storage keys */
     getAllKeys() {
         return this.storageKeys;
     }
     /**
-     * Get a cached value from storage
-     * @param [shouldReindexCache] – This is an LRU cache, and by default accessing a value will make it become last in line to be evicted. This flag can be used to skip that and just access the value directly without side-effects.
+     * Allows to set all the keys at once.
+     * This is useful when we are getting
+     * all the keys from the storage provider
+     * and we want to keep the cache in sync.
+     *
+     * Previously, we had to call `addKey` in a loop
+     * to achieve the same result.
+     *
+     * @param keys - an array of keys
      */
-    getValue(key, shouldReindexCache = true) {
-        if (shouldReindexCache) {
-            this.addToAccessedKeys(key);
-        }
-        return this.storageMap[key];
-    }
-    /** Check whether cache has data for the given key */
-    hasCacheForKey(key) {
-        return this.storageMap[key] !== undefined;
+    setAllKeys(keys) {
+        this.storageKeys = new Set(keys);
     }
     /** Saves a key in the storage keys list
      * Serves to keep the result of `getAllKeys` up to date
@@ -45,6 +46,28 @@ class OnyxCache {
     addKey(key) {
         this.storageKeys.add(key);
     }
+    /** Used to set keys that are null/undefined in storage without adding null to the storage map */
+    addNullishStorageKey(key) {
+        this.nullishStorageKeys.add(key);
+    }
+    /** Used to clear keys that are null/undefined in cache */
+    clearNullishStorageKeys() {
+        this.nullishStorageKeys = new Set();
+    }
+    /** Check whether cache has data for the given key */
+    hasCacheForKey(key) {
+        return this.storageMap[key] !== undefined || this.nullishStorageKeys.has(key);
+    }
+    /**
+     * Get a cached value from storage
+     * @param [shouldReindexCache] – This is an LRU cache, and by default accessing a value will make it become last in line to be evicted. This flag can be used to skip that and just access the value directly without side-effects.
+     */
+    get(key, shouldReindexCache = true) {
+        if (shouldReindexCache) {
+            this.addToAccessedKeys(key);
+        }
+        return this.storageMap[key];
+    }
     /**
      * Set's a key value in cache
      * Adds the key to the storage keys list as well
@@ -52,6 +75,13 @@ class OnyxCache {
     set(key, value) {
         this.addKey(key);
         this.addToAccessedKeys(key);
+        // When a key is explicitly set in cache, we can remove it from the list of nullish keys,
+        // since it will either be set to a non nullish value or removed from the cache completely.
+        this.nullishStorageKeys.delete(key);
+        if (value === null || value === undefined) {
+            delete this.storageMap[key];
+            return undefined;
+        }
         this.storageMap[key] = value;
         return value;
     }
@@ -69,25 +99,17 @@ 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, false));
-        const storageKeys = this.getAllKeys();
-        const mergedKeys = Object.keys(data);
-        this.storageKeys = new Set([...storageKeys, ...mergedKeys]);
-        mergedKeys.forEach((key) => this.addToAccessedKeys(key));
-    }
-    /**
-     * Allows to set all the keys at once.
-     * This is useful when we are getting
-     * all the keys from the storage provider
-     * and we want to keep the cache in sync.
-     *
-     * Previously, we had to call `addKey` in a loop
-     * to achieve the same result.
-     *
-     * @param keys - an array of keys
-     */
-    setAllKeys(keys) {
-        this.storageKeys = new Set(keys);
+        this.storageMap = Object.assign({}, utils_1.default.fastMerge(this.storageMap, data));
+        Object.entries(data).forEach(([key, value]) => {
+            this.addKey(key);
+            this.addToAccessedKeys(key);
+            if (value === null || value === undefined) {
+                this.addNullishStorageKey(key);
+            }
+            else {
+                this.nullishStorageKeys.delete(key);
+            }
+        });
     }
     /**
      * Check whether the given task is already running

package/dist/OnyxUtils.d.ts

@@ -1,6 +1,6 @@
 import type { ValueOf } from 'type-fest';
 import type Onyx from './Onyx';
-import type { CollectionKey, CollectionKeyBase, DeepRecord, KeyValueMapping, Mapping, NullableKeyValueMapping, OnyxCollection, OnyxEntry, OnyxKey, OnyxValue, WithOnyxConnectOptions } from './types';
+import type { CollectionKey, CollectionKeyBase, DeepRecord, KeyValueMapping, Mapping, OnyxCollection, OnyxEntry, OnyxKey, OnyxValue, WithOnyxConnectOptions } from './types';
 declare const METHOD: {
     readonly SET: "set";
     readonly MERGE: "merge";
@@ -32,7 +32,7 @@ declare function getDefaultKeyStates(): Record<OnyxKey, OnyxValue<OnyxKey>>;
  * @param initialKeyStates - initial data to set when `init()` and `clear()` are called
  * @param safeEvictionKeys - This is an array of keys (individual or collection patterns) that when provided to Onyx are flagged as "safe" for removal.
  */
-declare function initStoreValues(keys: DeepRecord<string, OnyxKey>, initialKeyStates: Partial<NullableKeyValueMapping>, safeEvictionKeys: OnyxKey[]): void;
+declare function initStoreValues(keys: DeepRecord<string, OnyxKey>, initialKeyStates: Partial<KeyValueMapping>, safeEvictionKeys: OnyxKey[]): void;
 /**
  * Sends an action to DevTools extension
  *
@@ -107,7 +107,7 @@ declare function getCachedCollection<TKey extends CollectionKeyBase>(collectionK
 /**
  * When a collection of keys change, search for any callbacks matching the collection key and trigger those callbacks
  */
-declare function keysChanged<TKey extends CollectionKeyBase>(collectionKey: TKey, partialCollection: OnyxCollection<KeyValueMapping[TKey]>, previousPartialCollection: OnyxCollection<KeyValueMapping[TKey]> | undefined, notifyRegularSubscibers?: boolean, notifyWithOnyxSubscibers?: boolean): void;
+declare function keysChanged<TKey extends CollectionKeyBase>(collectionKey: TKey, partialCollection: OnyxCollection<KeyValueMapping[TKey]>, partialPreviousCollection: OnyxCollection<KeyValueMapping[TKey]> | undefined, notifyRegularSubscibers?: boolean, notifyWithOnyxSubscibers?: boolean): void;
 /**
  * When a key change happens, search for any callbacks matching the key or collection key and trigger those callbacks
  *
@@ -120,7 +120,7 @@ declare function keyChanged<TKey extends OnyxKey>(key: TKey, value: OnyxValue<TK
  *     - sets state on the withOnyxInstances
  *     - triggers the callback function
  */
-declare function sendDataToConnection<TKey extends OnyxKey>(mapping: Mapping<TKey>, val: OnyxValue<TKey>, matchedKey: TKey | undefined, isBatched: boolean): void;
+declare function sendDataToConnection<TKey extends OnyxKey>(mapping: Mapping<TKey>, value: OnyxValue<TKey> | null, matchedKey: TKey | undefined, isBatched: boolean): void;
 /**
  * We check to see if this key is flagged as safe for eviction and add it to the recentlyAccessedKeys list so that when we
  * run out of storage the least recently accessed key can be removed.
@@ -157,10 +157,10 @@ declare function evictStorageAndRetry<TMethod extends typeof Onyx.set | typeof O
 /**
  * Notifies subscribers and writes current value to cache
  */
-declare function broadcastUpdate<TKey extends OnyxKey>(key: TKey, value: OnyxValue<TKey>, hasChanged?: boolean, wasRemoved?: boolean): Promise<void>;
+declare function broadcastUpdate<TKey extends OnyxKey>(key: TKey, value: OnyxValue<TKey>, hasChanged?: boolean): Promise<void>;
 declare function hasPendingMergeForKey(key: OnyxKey): boolean;
-type RemoveNullValuesOutput = {
-    value: Record<string, unknown> | unknown[] | null;
+type RemoveNullValuesOutput<Value extends OnyxValue<OnyxKey> | null> = {
+    value: Value | null;
     wasRemoved: boolean;
 };
 /**
@@ -170,7 +170,7 @@ type RemoveNullValuesOutput = {
  *
  * @returns The value without null values and a boolean "wasRemoved", which indicates if the key got removed completely
  */
-declare function removeNullValues(key: OnyxKey, value: OnyxValue<OnyxKey>, shouldRemoveNestedNulls?: boolean): RemoveNullValuesOutput;
+declare function removeNullValues<Value extends OnyxValue<OnyxKey>>(key: OnyxKey, value: Value | null, 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}

package/dist/OnyxUtils.js

@@ -163,7 +163,7 @@ function reduceCollectionWithSelector(collection, selector, withOnyxInstanceStat
 function get(key) {
     // When we already have the value in cache - resolve right away
     if (OnyxCache_1.default.hasCacheForKey(key)) {
-        return Promise.resolve(OnyxCache_1.default.getValue(key));
+        return Promise.resolve(OnyxCache_1.default.get(key));
     }
     const taskName = `get:${key}`;
     // When a value retrieving task for this key is still running hook to it
@@ -173,6 +173,10 @@ function get(key) {
     // Otherwise retrieve the value from storage and capture a promise to aid concurrent usages
     const promise = storage_1.default.getItem(key)
         .then((val) => {
+        if (val === undefined) {
+            OnyxCache_1.default.addNullishStorageKey(key);
+            return undefined;
+        }
         OnyxCache_1.default.set(key, val);
         return val;
     })
@@ -182,9 +186,9 @@ function get(key) {
 /** Returns current key names stored in persisted storage */
 function getAllKeys() {
     // When we've already read stored keys, resolve right away
-    const storedKeys = OnyxCache_1.default.getAllKeys();
-    if (storedKeys.size > 0) {
-        return Promise.resolve(storedKeys);
+    const cachedKeys = OnyxCache_1.default.getAllKeys();
+    if (cachedKeys.size > 0) {
+        return Promise.resolve(cachedKeys);
     }
     const taskName = 'getAllKeys';
     // When a value retrieving task for all keys is still running hook to it
@@ -237,7 +241,7 @@ function isSafeEvictionKey(testKey) {
  * If the requested key is a collection, it will return an object with all the collection members.
  */
 function tryGetCachedValue(key, mapping) {
-    let val = OnyxCache_1.default.getValue(key);
+    let val = OnyxCache_1.default.get(key);
     if (isCollectionKey(key)) {
         const allCacheKeys = OnyxCache_1.default.getAllKeys();
         // It is possible we haven't loaded all keys yet so we do not know if the
@@ -247,7 +251,7 @@ function tryGetCachedValue(key, mapping) {
         }
         const matchingKeys = Array.from(allCacheKeys).filter((k) => k.startsWith(key));
         const values = matchingKeys.reduce((finalObject, matchedKey) => {
-            const cachedValue = OnyxCache_1.default.getValue(matchedKey);
+            const cachedValue = OnyxCache_1.default.get(matchedKey);
             if (cachedValue) {
                 // This is permissible because we're in the process of constructing the final object in a reduce function.
                 // eslint-disable-next-line no-param-reassign
@@ -334,23 +338,22 @@ function getCachedCollection(collectionKey, collectionMemberKeys) {
         if (!collectionMemberKeys && !isCollectionMemberKey(collectionKey, key)) {
             return;
         }
-        collection[key] = OnyxCache_1.default.getValue(key);
+        collection[key] = OnyxCache_1.default.get(key);
     });
     return collection;
 }
 /**
  * When a collection of keys change, search for any callbacks matching the collection key and trigger those callbacks
  */
-function keysChanged(collectionKey, partialCollection, previousPartialCollection, notifyRegularSubscibers = true, notifyWithOnyxSubscibers = true) {
-    const previousCollectionWithoutNestedNulls = previousPartialCollection === undefined ? {} : utils_1.default.removeNestedNullValues(previousPartialCollection);
+function keysChanged(collectionKey, partialCollection, partialPreviousCollection, notifyRegularSubscibers = true, notifyWithOnyxSubscibers = true) {
     // We prepare the "cached collection" which is the entire collection + the new partial data that
     // was merged in via mergeCollection().
     const cachedCollection = getCachedCollection(collectionKey);
-    const cachedCollectionWithoutNestedNulls = utils_1.default.removeNestedNullValues(cachedCollection);
     // If the previous collection equals the new collection then we do not need to notify any subscribers.
-    if (previousPartialCollection !== undefined && (0, fast_equals_1.deepEqual)(cachedCollectionWithoutNestedNulls, previousCollectionWithoutNestedNulls)) {
+    if (partialPreviousCollection !== undefined && (0, fast_equals_1.deepEqual)(cachedCollection, partialPreviousCollection)) {
         return;
     }
+    const previousCollection = partialPreviousCollection !== null && partialPreviousCollection !== void 0 ? partialPreviousCollection : {};
     // We are iterating over all subscribers similar to keyChanged(). However, we are looking for subscribers who are subscribing to either a collection key or
     // individual collection key member for the collection that is being updated. It is important to note that the collection parameter cane be a PARTIAL collection
     // and does not represent all of the combined keys and values for a collection key. It is just the "new" data that was merged in via mergeCollection().
@@ -381,7 +384,7 @@ function keysChanged(collectionKey, partialCollection, previousPartialCollection
             // send the whole cached collection.
             if (isSubscribedToCollectionKey) {
                 if (subscriber.waitForCollectionCallback) {
-                    subscriber.callback(cachedCollectionWithoutNestedNulls);
+                    subscriber.callback(cachedCollection);
                     continue;
                 }
                 // If they are not using waitForCollectionCallback then we notify the subscriber with
@@ -389,21 +392,21 @@ function keysChanged(collectionKey, partialCollection, previousPartialCollection
                 const dataKeys = Object.keys(partialCollection !== null && partialCollection !== void 0 ? partialCollection : {});
                 for (let j = 0; j < dataKeys.length; j++) {
                     const dataKey = dataKeys[j];
-                    if ((0, fast_equals_1.deepEqual)(cachedCollectionWithoutNestedNulls[dataKey], previousCollectionWithoutNestedNulls[dataKey])) {
+                    if ((0, fast_equals_1.deepEqual)(cachedCollection[dataKey], previousCollection[dataKey])) {
                         continue;
                     }
-                    subscriber.callback(cachedCollectionWithoutNestedNulls[dataKey], dataKey);
+                    subscriber.callback(cachedCollection[dataKey], dataKey);
                 }
                 continue;
             }
             // And if the subscriber is specifically only tracking a particular collection member key then we will
             // notify them with the cached data for that key only.
             if (isSubscribedToCollectionMemberKey) {
-                if ((0, fast_equals_1.deepEqual)(cachedCollectionWithoutNestedNulls[subscriber.key], previousCollectionWithoutNestedNulls[subscriber.key])) {
+                if ((0, fast_equals_1.deepEqual)(cachedCollection[subscriber.key], previousCollection[subscriber.key])) {
                     continue;
                 }
                 const subscriberCallback = subscriber.callback;
-                subscriberCallback(cachedCollectionWithoutNestedNulls[subscriber.key], subscriber.key);
+                subscriberCallback(cachedCollection[subscriber.key], subscriber.key);
                 continue;
             }
             continue;
@@ -449,7 +452,7 @@ function keysChanged(collectionKey, partialCollection, previousPartialCollection
             }
             // If a React component is only interested in a single key then we can set the cached value directly to the state name.
             if (isSubscribedToCollectionMemberKey) {
-                if ((0, fast_equals_1.deepEqual)(cachedCollectionWithoutNestedNulls[subscriber.key], previousCollectionWithoutNestedNulls[subscriber.key])) {
+                if ((0, fast_equals_1.deepEqual)(cachedCollection[subscriber.key], previousCollection[subscriber.key])) {
                     continue;
                 }
                 // However, we only want to update this subscriber if the partial data contains a change.
@@ -525,14 +528,12 @@ function keyChanged(key, value, previousValue, canUpdateSubscriber = () => true,
             }
             if (isCollectionKey(subscriber.key) && subscriber.waitForCollectionCallback) {
                 const cachedCollection = getCachedCollection(subscriber.key);
-                const cachedCollectionWithoutNestedNulls = utils_1.default.removeNestedNullValues(cachedCollection);
-                cachedCollectionWithoutNestedNulls[key] = value;
-                subscriber.callback(cachedCollectionWithoutNestedNulls);
+                cachedCollection[key] = value;
+                subscriber.callback(cachedCollection);
                 continue;
             }
-            const valueWithoutNestedNulls = utils_1.default.removeNestedNullValues(value);
             const subscriberCallback = subscriber.callback;
-            subscriberCallback(valueWithoutNestedNulls, key);
+            subscriberCallback(value, key);
             continue;
         }
         // Subscriber connected via withOnyx() HOC
@@ -612,7 +613,7 @@ function keyChanged(key, value, previousValue, canUpdateSubscriber = () => true,
  *     - sets state on the withOnyxInstances
  *     - triggers the callback function
  */
-function sendDataToConnection(mapping, val, matchedKey, isBatched) {
+function sendDataToConnection(mapping, value, matchedKey, isBatched) {
     var _a, _b;
     // If the mapping no longer exists then we should not send any data.
     // This means our subscriber disconnected or withOnyx wrapped component unmounted.
@@ -620,15 +621,15 @@ function sendDataToConnection(mapping, val, matchedKey, isBatched) {
         return;
     }
     if ('withOnyxInstance' in mapping && mapping.withOnyxInstance) {
-        let newData = val;
+        let newData = value;
         // If the mapping has a selector, then the component's state must only be updated with the data
         // returned by the selector.
         if (mapping.selector) {
             if (isCollectionKey(mapping.key)) {
-                newData = reduceCollectionWithSelector(val, mapping.selector, mapping.withOnyxInstance.state);
+                newData = reduceCollectionWithSelector(value, mapping.selector, mapping.withOnyxInstance.state);
             }
             else {
-                newData = mapping.selector(val, mapping.withOnyxInstance.state);
+                newData = mapping.selector(value, mapping.withOnyxInstance.state);
             }
         }
         PerformanceUtils.logSetStateCall(mapping, null, newData, 'sendDataToConnection');
@@ -640,8 +641,13 @@ function sendDataToConnection(mapping, val, matchedKey, isBatched) {
         }
         return;
     }
-    const valuesWithoutNestedNulls = utils_1.default.removeNestedNullValues(val);
-    (_b = (_a = mapping).callback) === null || _b === void 0 ? void 0 : _b.call(_a, valuesWithoutNestedNulls, matchedKey);
+    // When there are no matching keys in "Onyx.connect", we pass null to "sendDataToConnection" explicitly,
+    // to allow the withOnyx instance to set the value in the state initially and therefore stop the loading state once all
+    // required keys have been set.
+    // If we would pass undefined to setWithOnyxInstance instead, withOnyx would not set the value in the state.
+    // withOnyx will internally replace null values with undefined and never pass null values to wrapped components.
+    // For regular callbacks, we never want to pass null values, but always just undefined if a value is not set in cache or storage.
+    (_b = (_a = mapping).callback) === null || _b === void 0 ? void 0 : _b.call(_a, value === null ? undefined : value, matchedKey);
 }
 /**
  * We check to see if this key is flagged as safe for eviction and add it to the recentlyAccessedKeys list so that when we
@@ -682,7 +688,7 @@ function getCollectionDataAndSendAsObject(matchingKeys, mapping) {
      * These missingKeys will be later to use to multiGet the data from the storage.
      */
     matchingKeys.forEach((key) => {
-        const cacheValue = OnyxCache_1.default.getValue(key);
+        const cacheValue = OnyxCache_1.default.get(key);
         if (cacheValue) {
             data[key] = cacheValue;
             return;
@@ -755,7 +761,7 @@ function scheduleNotifyCollectionSubscribers(key, value, previousValue) {
  * Remove a key from Onyx and update the subscribers
  */
 function remove(key) {
-    const prevValue = OnyxCache_1.default.getValue(key, false);
+    const prevValue = OnyxCache_1.default.get(key, false);
     OnyxCache_1.default.drop(key);
     scheduleSubscriberUpdate(key, null, prevValue);
     return storage_1.default.removeItem(key).then(() => undefined);
@@ -798,11 +804,11 @@ function evictStorageAndRetry(error, onyxMethod, ...args) {
 /**
  * Notifies subscribers and writes current value to cache
  */
-function broadcastUpdate(key, value, hasChanged, wasRemoved = false) {
-    const prevValue = OnyxCache_1.default.getValue(key, false);
+function broadcastUpdate(key, value, hasChanged) {
+    const prevValue = OnyxCache_1.default.get(key, false);
     // Update subscribers if the cached value has changed, or when the subscriber specifically requires
     // all updates regardless of value changes (indicated by initWithStoredValues set to false).
-    if (hasChanged && !wasRemoved) {
+    if (hasChanged) {
         OnyxCache_1.default.set(key, value);
     }
     else {
@@ -823,7 +829,7 @@ function hasPendingMergeForKey(key) {
 function removeNullValues(key, value, shouldRemoveNestedNulls = true) {
     if (value === null) {
         remove(key);
-        return { value, wasRemoved: true };
+        return { value: null, wasRemoved: true };
     }
     // We can remove all null values in an object by merging it with itself
     // utils.fastMerge recursively goes through the object and removes all null values

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import type { ConnectOptions, OnyxUpdate } from './Onyx';
 import Onyx from './Onyx';
-import type { CustomTypeOptions, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxValue, Selector } from './types';
+import type { CustomTypeOptions, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxInput, OnyxKey, OnyxValue, Selector, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput } from './types';
 import type { FetchStatus, ResultMetadata, UseOnyxResult } from './useOnyx';
 import useOnyx from './useOnyx';
 import withOnyx from './withOnyx';
 import type { WithOnyxState } from './withOnyx/types';
 export default Onyx;
 export { useOnyx, withOnyx };
-export type { ConnectOptions, CustomTypeOptions, FetchStatus, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxUpdate, OnyxValue, ResultMetadata, Selector, UseOnyxResult, WithOnyxState, };
+export type { ConnectOptions, CustomTypeOptions, FetchStatus, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxInput, OnyxKey, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxUpdate, OnyxValue, ResultMetadata, Selector, UseOnyxResult, WithOnyxState, };

package/dist/storage/providers/IDBKeyValProvider.js

@@ -22,14 +22,26 @@ const provider = {
             throw Error('IDBKeyVal store could not be created');
         idbKeyValStore = newIdbKeyValStore;
     },
-    setItem: (key, value) => (0, idb_keyval_1.set)(key, value, idbKeyValStore),
+    setItem: (key, value) => {
+        if (value === null) {
+            provider.removeItem(key);
+        }
+        return (0, idb_keyval_1.set)(key, value, idbKeyValStore);
+    },
     multiGet: (keysParam) => (0, idb_keyval_1.getMany)(keysParam, idbKeyValStore).then((values) => values.map((value, index) => [keysParam[index], value])),
     multiMerge: (pairs) => idbKeyValStore('readwrite', (store) => {
         // Note: we are using the manual store transaction here, to fit the read and update
         // of the items in one transaction to achieve best performance.
         const getValues = Promise.all(pairs.map(([key]) => (0, idb_keyval_1.promisifyRequest)(store.get(key))));
         return getValues.then((values) => {
-            const upsertMany = pairs.map(([key, value], index) => {
+            const pairsWithoutNull = pairs.filter(([key, value]) => {
+                if (value === null) {
+                    provider.removeItem(key);
+                    return false;
+                }
+                return true;
+            });
+            const upsertMany = pairsWithoutNull.map(([key, value], index) => {
                 const prev = values[index];
                 const newValue = utils_1.default.fastMerge(prev, value);
                 return (0, idb_keyval_1.promisifyRequest)(store.put(newValue, key));
@@ -41,7 +53,16 @@ const provider = {
         // Since Onyx also merged the existing value with the changes, we can just set the value directly
         return provider.setItem(key, preMergedValue);
     },
-    multiSet: (pairs) => (0, idb_keyval_1.setMany)(pairs, idbKeyValStore),
+    multiSet: (pairs) => {
+        const pairsWithoutNull = pairs.filter(([key, value]) => {
+            if (value === null) {
+                provider.removeItem(key);
+                return false;
+            }
+            return true;
+        });
+        return (0, idb_keyval_1.setMany)(pairsWithoutNull, idbKeyValStore);
+    },
     clear: () => (0, idb_keyval_1.clear)(idbKeyValStore),
     getAllKeys: () => (0, idb_keyval_1.keys)(idbKeyValStore),
     getItem: (key) => (0, idb_keyval_1.get)(key, idbKeyValStore)

package/dist/types.d.ts

@@ -121,7 +121,7 @@ type KeyValueMapping = {
  * It's very similar to `KeyValueMapping` but this type accepts using `null` as well.
  */
 type NullableKeyValueMapping = {
-    [TKey in OnyxKey]: OnyxValue<TKey>;
+    [TKey in OnyxKey]: NonUndefined<OnyxValue<TKey>> | null;
 };
 /**
  * Represents a selector function type which operates based on the provided `TKey` and `ReturnType`.
@@ -161,7 +161,13 @@ type Selector<TKey extends OnyxKey, TOnyxProps, TReturnType> = (value: OnyxEntry
  * })(Component);
  * ```
  */
-type OnyxEntry<TOnyxValue> = TOnyxValue | null | undefined;
+type OnyxEntry<TOnyxValue> = TOnyxValue | undefined;
+/**
+ * Represents an input value that can be passed to Onyx methods, that can be either `TOnyxValue` or `null`.
+ * Setting a key to `null` will remove the key from the store.
+ * `undefined` is not allowed for setting values, because it will have no effect on the data.
+ */
+type OnyxInput<TOnyxValue> = TOnyxValue | null;
 /**
  * Represents an Onyx collection of entries, that can be either a record of `TOnyxValue`s or `null` / `undefined` if it is empty or doesn't exist.
  *
@@ -190,7 +196,7 @@ type OnyxEntry<TOnyxValue> = TOnyxValue | null | undefined;
  * })(Component);
  * ```
  */
-type OnyxCollection<TOnyxValue> = OnyxEntry<Record<string, TOnyxValue | null | undefined>>;
+type OnyxCollection<TOnyxValue> = OnyxEntry<Record<string, TOnyxValue | undefined>>;
 /** Utility type to extract `TOnyxValue` from `OnyxCollection<TOnyxValue>` */
 type ExtractOnyxCollectionValue<TOnyxCollection> = TOnyxCollection extends NonNullable<OnyxCollection<infer U>> ? U : never;
 type NonTransformableTypes = BuiltIns | ((...args: any[]) => unknown) | Map<unknown, unknown> | Set<unknown> | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | unknown[] | readonly unknown[];
@@ -229,7 +235,7 @@ type NullishObjectDeep<ObjectType extends object> = {
  * Also, the `TMap` type is inferred automatically in `mergeCollection()` method and represents
  * the object of collection keys/values specified in the second parameter of the method.
  */
-type Collection<TKey extends CollectionKeyBase, TMap, TValue> = {
+type Collection<TKey extends CollectionKeyBase, TValue, TMap = never> = {
     [MapK in keyof TMap]: MapK extends `${TKey}${string}` ? MapK extends `${TKey}` ? never : TValue : never;
 };
 /** Represents the base options used in `Onyx.connect()` method. */
@@ -276,6 +282,22 @@ type ConnectOptions<TKey extends OnyxKey> = (CollectionConnectOptions<TKey> | De
 type Mapping<TKey extends OnyxKey> = ConnectOptions<TKey> & {
     connectionID: number;
 };
+/**
+ * This represents the value that can be passed to `Onyx.set` and to `Onyx.update` with the method "SET"
+ */
+type OnyxSetInput<TKey extends OnyxKey> = OnyxInput<KeyValueMapping[TKey]>;
+/**
+ * This represents the value that can be passed to `Onyx.multiSet` and to `Onyx.update` with the method "MULTI_SET"
+ */
+type OnyxMultiSetInput = Partial<NullableKeyValueMapping>;
+/**
+ * This represents the value that can be passed to `Onyx.merge` and to `Onyx.update` with the method "MERGE"
+ */
+type OnyxMergeInput<TKey extends OnyxKey> = OnyxInput<NullishDeep<KeyValueMapping[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, NullishDeep<KeyValueMapping[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.
@@ -284,15 +306,15 @@ type OnyxUpdate = {
     [TKey in OnyxKey]: {
         onyxMethod: typeof OnyxUtils.METHOD.SET;
         key: TKey;
-        value: NonUndefined<OnyxEntry<KeyValueMapping[TKey]>>;
+        value: OnyxSetInput<TKey>;
     } | {
-        onyxMethod: typeof OnyxUtils.METHOD.MERGE;
+        onyxMethod: typeof OnyxUtils.METHOD.MULTI_SET;
         key: TKey;
-        value: NonUndefined<OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>>;
+        value: OnyxMultiSetInput;
     } | {
-        onyxMethod: typeof OnyxUtils.METHOD.MULTI_SET;
+        onyxMethod: typeof OnyxUtils.METHOD.MERGE;
         key: TKey;
-        value: Partial<NullableKeyValueMapping>;
+        value: OnyxMergeInput<TKey>;
     } | {
         onyxMethod: typeof OnyxUtils.METHOD.CLEAR;
         key: TKey;
@@ -302,7 +324,7 @@ type OnyxUpdate = {
     [TKey in CollectionKeyBase]: {
         onyxMethod: typeof OnyxUtils.METHOD.MERGE_COLLECTION;
         key: TKey;
-        value: Record<`${TKey}${string}`, NullishDeep<KeyValueMapping[TKey]>>;
+        value: OnyxMergeCollectionInput<TKey>;
     };
 }[CollectionKeyBase];
 /**
@@ -333,4 +355,4 @@ type InitOptions = {
     debugSetState?: boolean;
 };
 type GenericFunction = (...args: any[]) => any;
-export type { BaseConnectOptions, Collection, CollectionConnectCallback, CollectionConnectOptions, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, DefaultConnectOptions, ExtractOnyxCollectionValue, GenericFunction, InitOptions, Key, KeyValueMapping, Mapping, NonNull, NonUndefined, NullableKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxUpdate, OnyxValue, Selector, WithOnyxConnectOptions, };
+export type { BaseConnectOptions, Collection, CollectionConnectCallback, CollectionConnectOptions, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, DefaultConnectOptions, ExtractOnyxCollectionValue, GenericFunction, InitOptions, Key, KeyValueMapping, Mapping, NonNull, NonUndefined, NullableKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxInput, OnyxKey, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxUpdate, OnyxValue, Selector, WithOnyxConnectOptions, };

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import type { OnyxKey } from './types';
+import type { OnyxKey, OnyxValue } from './types';
 type EmptyObject = Record<string, never>;
 type EmptyValue = EmptyObject | null | undefined;
 /** Checks whether the given object is an object and not null/undefined. */
@@ -12,7 +12,7 @@ declare function isEmptyObject<T>(obj: T | EmptyValue): obj is EmptyValue;
  */
 declare function fastMerge<TObject extends Record<string, unknown>>(target: TObject | null, source: TObject | null, shouldRemoveNestedNulls?: boolean): TObject | null;
 /** Deep removes the nested null values from the given value. */
-declare function removeNestedNullValues<TObject extends Record<string, unknown>>(value: unknown | unknown[] | TObject): Record<string, unknown> | unknown[] | null;
+declare function removeNestedNullValues<TValue extends OnyxValue<OnyxKey> | unknown | unknown[]>(value: TValue | null): TValue | null;
 /** Formats the action name by uppercasing and adding the key if provided. */
 declare function formatActionName(method: string, key?: OnyxKey): string;
 /** validate that the update and the existing value are compatible */

package/dist/utils.js

@@ -90,7 +90,8 @@ function fastMerge(target, source, shouldRemoveNestedNulls = true) {
 /** Deep removes the nested null values from the given value. */
 function removeNestedNullValues(value) {
     if (typeof value === 'object' && !Array.isArray(value)) {
-        return fastMerge(value, value);
+        const objectValue = value;
+        return fastMerge(objectValue, objectValue);
     }
     return value;
 }

package/dist/withOnyx/index.js

@@ -36,6 +36,7 @@ const Onyx_1 = __importDefault(require("../Onyx"));
 const OnyxUtils_1 = __importDefault(require("../OnyxUtils"));
 const Str = __importStar(require("../Str"));
 const utils_1 = __importDefault(require("../utils"));
+const OnyxCache_1 = __importDefault(require("../OnyxCache"));
 // This is a list of keys that can exist on a `mapping`, but are not directly related to loading data from Onyx. When the keys of a mapping are looped over to check
 // if a key has changed, it's a good idea to skip looking at these properties since they would have unexpected results.
 const mappingPropertiesToIgnoreChangesTo = ['initialValue', 'allowStaleData'];
@@ -85,7 +86,8 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
                 const cachedState = mapOnyxToStateEntries(mapOnyxToState).reduce((resultObj, [propName, mapping]) => {
                     const key = Str.result(mapping.key, props);
                     let value = OnyxUtils_1.default.tryGetCachedValue(key, mapping);
-                    if (!value && mapping.initialValue) {
+                    const hasCacheForKey = OnyxCache_1.default.hasCacheForKey(key);
+                    if (!hasCacheForKey && !value && mapping.initialValue) {
                         value = mapping.initialValue;
                     }
                     /**
@@ -99,7 +101,10 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
                      * In reality, Onyx.merge() will only update the subscriber after all merges have been batched and the previous value is retrieved via a get() (returns a promise).
                      * So, we won't use the cache optimization here as it will lead us to arbitrarily defer various actions in the application code.
                      */
-                    if (mapping.initWithStoredValues !== false && ((value !== undefined && !OnyxUtils_1.default.hasPendingMergeForKey(key)) || mapping.allowStaleData)) {
+                    const hasPendingMergeForKey = OnyxUtils_1.default.hasPendingMergeForKey(key);
+                    const hasValueInCache = hasCacheForKey || value !== undefined;
+                    const shouldSetState = mapping.initWithStoredValues !== false && ((hasValueInCache && !hasPendingMergeForKey) || !!mapping.allowStaleData);
+                    if (shouldSetState) {
                         // eslint-disable-next-line no-param-reassign
                         resultObj[propName] = value;
                     }
@@ -183,7 +188,7 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
              * initialValue is there, we just check if the update is different than that and then try to handle it as best as we can.
              */
             setWithOnyxState(statePropertyName, val) {
-                const prevValue = this.state[statePropertyName];
+                const prevVal = this.state[statePropertyName];
                 // If the component is not loading (read "mounting"), then we can just update the state
                 // There is a small race condition.
                 // When calling setWithOnyxState we delete the tempState object that is used to hold temporary state updates while the HOC is gathering data.
@@ -193,10 +198,11 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
                 // This simply bypasses the loading check if the tempState is gone and the update can be safely queued with a normal setStateProxy.
                 if (!this.state.loading || !this.tempState) {
                     // Performance optimization, do not trigger update with same values
-                    if (prevValue === val || (utils_1.default.isEmptyObject(prevValue) && utils_1.default.isEmptyObject(val))) {
+                    if (prevVal === val || (utils_1.default.isEmptyObject(prevVal) && utils_1.default.isEmptyObject(val))) {
                         return;
                     }
-                    this.setStateProxy({ [statePropertyName]: val });
+                    const valueWithoutNull = val === null ? undefined : val;
+                    this.setStateProxy({ [statePropertyName]: valueWithoutNull });
                     return;
                 }
                 this.tempState[statePropertyName] = val;
@@ -217,16 +223,16 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
                         const initialValue = mapOnyxToState[key].initialValue;
                         // If initialValue is there and the state contains something different it means
                         // an update has already been received and we can discard the value we are trying to hydrate
-                        if (initialValue !== undefined && prevState[key] !== undefined && prevState[key] !== initialValue) {
+                        if (initialValue !== undefined && prevState[key] !== undefined && prevState[key] !== initialValue && prevState[key] !== null) {
                             // eslint-disable-next-line no-param-reassign
                             result[key] = prevState[key];
-                            // if value is already there (without initial value) then we can discard the value we are trying to hydrate
                         }
-                        else if (prevState[key] !== undefined) {
+                        else if (prevState[key] !== undefined && prevState[key] !== null) {
+                            // if value is already there (without initial value) then we can discard the value we are trying to hydrate
                             // eslint-disable-next-line no-param-reassign
                             result[key] = prevState[key];
                         }
-                        else {
+                        else if (stateUpdate[key] !== null) {
                             // eslint-disable-next-line no-param-reassign
                             result[key] = stateUpdate[key];
                         }
@@ -300,9 +306,8 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
                 // Remove any internal state properties used by withOnyx
                 // that should not be passed to a wrapped component
                 const stateToPass = utils_1.default.omit(this.state, ([stateKey, stateValue]) => stateKey === 'loading' || stateValue === null);
-                const stateToPassWithoutNestedNulls = utils_1.default.removeNestedNullValues(stateToPass);
                 // Spreading props and state is necessary in an HOC where the data cannot be predicted
-                return (react_1.default.createElement(WrappedComponent, Object.assign({ markReadyForHydration: this.flushPendingSetStates }, propsToPass, stateToPassWithoutNestedNulls, { ref: this.props.forwardedRef })));
+                return (react_1.default.createElement(WrappedComponent, Object.assign({ markReadyForHydration: this.flushPendingSetStates }, propsToPass, stateToPass, { ref: this.props.forwardedRef })));
             }
         }
         withOnyx.displayName = `withOnyx(${displayName})`;

package/dist/withOnyx/types.d.ts

@@ -1,6 +1,6 @@
 import type { ForwardedRef } from 'react';
 import type { IsEqual } from 'type-fest';
-import type { CollectionKeyBase, ExtractOnyxCollectionValue, KeyValueMapping, NullableKeyValueMapping, OnyxCollection, OnyxEntry, OnyxKey, OnyxValue, Selector } from '../types';
+import type { CollectionKeyBase, ExtractOnyxCollectionValue, KeyValueMapping, OnyxCollection, OnyxEntry, OnyxKey, OnyxValue, Selector } from '../types';
 /**
  * Represents the base mapping options between an Onyx key and the component's prop.
  */
@@ -134,7 +134,7 @@ type WithOnyxState<TOnyxProps> = TOnyxProps & {
 /**
  * Represents the `withOnyx` internal component instance.
  */
-type WithOnyxInstance = React.Component<unknown, WithOnyxState<NullableKeyValueMapping>> & {
+type WithOnyxInstance = React.Component<unknown, WithOnyxState<KeyValueMapping>> & {
     setStateProxy: (modifier: Record<string, OnyxCollection<KeyValueMapping[OnyxKey]>> | ((state: Record<string, OnyxCollection<KeyValueMapping[OnyxKey]>>) => OnyxValue<OnyxKey>)) => void;
     setWithOnyxState: (statePropertyName: OnyxKey, value: OnyxValue<OnyxKey>) => void;
 };

package/package.json

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