react-native-onyx 2.0.46 → 2.0.48

package/dist/Onyx.js

@@ -197,9 +197,13 @@ function set(key, value) {
     if (OnyxUtils_1.default.hasPendingMergeForKey(key)) {
         delete OnyxUtils_1.default.getMergeQueue()[key];
     }
+    // Onyx.set will ignore `undefined` values as inputs, therefore we can return early.
+    if (value === undefined) {
+        return Promise.resolve();
+    }
     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) {
+    if (existingValue === undefined && value === null) {
         return Promise.resolve();
     }
     // Check if the value is compatible with the existing value in the storage
@@ -244,28 +248,18 @@ function set(key, value) {
  * @param data object keyed by ONYXKEYS and the values to set
  */
 function multiSet(data) {
-    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 keyValuePairsToSet = OnyxUtils_1.default.prepareKeyValuePairsForStorage(data, true);
+    const updatePromises = keyValuePairsToSet.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(allKeyValuePairs)
+    return storage_1.default.multiSet(keyValuePairsToSet)
         .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([removePromises, updatePromises]);
+        return Promise.all(updatePromises);
     })
         .then(() => undefined);
 }
@@ -515,10 +509,10 @@ function clear(keysToPreserve = []) {
                         if (!keyValuesToResetAsCollection[collectionKey]) {
                             keyValuesToResetAsCollection[collectionKey] = {};
                         }
-                        keyValuesToResetAsCollection[collectionKey][key] = newValue;
+                        keyValuesToResetAsCollection[collectionKey][key] = newValue !== null && newValue !== void 0 ? newValue : undefined;
                     }
                     else {
-                        keyValuesToResetIndividually[key] = newValue;
+                        keyValuesToResetIndividually[key] = newValue !== null && newValue !== void 0 ? newValue : undefined;
                     }
                 }
             }

package/dist/OnyxCache.d.ts

@@ -40,6 +40,8 @@ declare class OnyxCache {
     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 set keys that are null/undefined in storage without adding null to the storage map */
+    hasNullishStorageKey(key: OnyxKey): boolean;
     /** Used to clear keys that are null/undefined in cache */
     clearNullishStorageKeys(): void;
     /** Check whether cache has data for the given key */

package/dist/OnyxCache.js

@@ -20,7 +20,7 @@ class OnyxCache {
         this.storageMap = {};
         this.pendingPromises = new Map();
         // bind all public methods to prevent problems with `this`
-        (0, bindAll_1.default)(this, 'getAllKeys', 'get', 'hasCacheForKey', 'addKey', 'addNullishStorageKey', 'clearNullishStorageKeys', 'set', 'drop', 'merge', 'hasPendingTask', 'getTaskPromise', 'captureTask', 'removeLeastRecentlyUsedKeys', 'setRecentKeysLimit', 'setAllKeys');
+        (0, bindAll_1.default)(this, 'getAllKeys', 'get', 'hasCacheForKey', 'addKey', 'addNullishStorageKey', 'hasNullishStorageKey', 'clearNullishStorageKeys', 'set', 'drop', 'merge', 'hasPendingTask', 'getTaskPromise', 'captureTask', 'removeLeastRecentlyUsedKeys', 'setRecentKeysLimit', 'setAllKeys');
     }
     /** Get all the storage keys */
     getAllKeys() {
@@ -50,13 +50,17 @@ class OnyxCache {
     addNullishStorageKey(key) {
         this.nullishStorageKeys.add(key);
     }
+    /** Used to set keys that are null/undefined in storage without adding null to the storage map */
+    hasNullishStorageKey(key) {
+        return this.nullishStorageKeys.has(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);
+        return this.storageMap[key] !== undefined || this.hasNullishStorageKey(key);
     }
     /**
      * Get a cached value from storage

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, OnyxCollection, OnyxEntry, OnyxKey, OnyxValue, WithOnyxConnectOptions } from './types';
+import type { CollectionKey, CollectionKeyBase, DeepRecord, KeyValueMapping, Mapping, OnyxCollection, OnyxEntry, OnyxInput, OnyxKey, OnyxValue, WithOnyxConnectOptions } from './types';
 declare const METHOD: {
     readonly SET: "set";
     readonly MERGE: "merge";
@@ -52,7 +52,7 @@ declare function sendActionToDevTools(method: Exclude<OnyxMethod, typeof METHOD.
 declare function maybeFlushBatchUpdates(): Promise<void>;
 declare function batchUpdates(updates: () => void): Promise<void>;
 /** Get some data from the store */
-declare function get(key: OnyxKey): Promise<OnyxValue<OnyxKey>>;
+declare function get<TKey extends OnyxKey, TValue extends OnyxValue<TKey>>(key: TKey): Promise<TValue>;
 /** Returns current key names stored in persisted storage */
 declare function getAllKeys(): Promise<Set<OnyxKey>>;
 /**
@@ -159,8 +159,8 @@ 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 OnyxValue<OnyxKey> | null> = {
-    value: Value | null;
+type RemoveNullValuesOutput<Value extends OnyxInput<OnyxKey> | undefined> = {
+    value: Value;
     wasRemoved: boolean;
 };
 /**
@@ -170,7 +170,7 @@ type RemoveNullValuesOutput<Value extends OnyxValue<OnyxKey> | null> = {
  *
  * @returns The value without null values and a boolean "wasRemoved", which indicates if the key got removed completely
  */
-declare function removeNullValues<Value extends OnyxValue<OnyxKey>>(key: OnyxKey, value: Value | null, shouldRemoveNestedNulls?: boolean): RemoveNullValuesOutput<Value>;
+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}
@@ -178,13 +178,13 @@ declare function removeNullValues<Value extends OnyxValue<OnyxKey>>(key: OnyxKey
 
 * @return an array of key - value pairs <[key, value]>
  */
-declare function prepareKeyValuePairsForStorage(data: Record<OnyxKey, OnyxValue<OnyxKey>>, shouldRemoveNestedNulls: boolean): Array<[OnyxKey, OnyxValue<OnyxKey>]>;
+declare function prepareKeyValuePairsForStorage(data: Record<OnyxKey, OnyxInput<OnyxKey>>, shouldRemoveNestedNulls: boolean): Array<[OnyxKey, OnyxInput<OnyxKey>]>;
 /**
  * Merges an array of changes with an existing value
  *
  * @param changes Array of changes that should be applied to the existing value
  */
-declare function applyMerge(existingValue: OnyxValue<OnyxKey>, changes: Array<OnyxValue<OnyxKey>>, shouldRemoveNestedNulls: boolean): OnyxValue<OnyxKey>;
+declare function applyMerge<TValue extends OnyxInput<OnyxKey> | undefined, TChange extends OnyxInput<OnyxKey> | undefined>(existingValue: TValue, changes: TChange[], shouldRemoveNestedNulls: boolean): TChange;
 /**
  * Merge user provided default key value pairs.
  */

package/dist/OnyxUtils.js

@@ -338,6 +338,10 @@ function getCachedCollection(collectionKey, collectionMemberKeys) {
         if (!collectionMemberKeys && !isCollectionMemberKey(collectionKey, key)) {
             return;
         }
+        const cachedValue = OnyxCache_1.default.get(key);
+        if (cachedValue === undefined && !OnyxCache_1.default.hasNullishStorageKey(key)) {
+            return;
+        }
         collection[key] = OnyxCache_1.default.get(key);
     });
     return collection;
@@ -349,10 +353,6 @@ function keysChanged(collectionKey, partialCollection, partialPreviousCollection
     // We prepare the "cached collection" which is the entire collection + the new partial data that
     // was merged in via mergeCollection().
     const cachedCollection = getCachedCollection(collectionKey);
-    // If the previous collection equals the new collection then we do not need to notify any subscribers.
-    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
@@ -426,23 +426,27 @@ function keysChanged(collectionKey, partialCollection, partialPreviousCollection
                     subscriber.withOnyxInstance.setStateProxy((prevState) => {
                         const previousData = prevState[subscriber.statePropertyName];
                         const newData = reduceCollectionWithSelector(cachedCollection, collectionSelector, subscriber.withOnyxInstance.state);
-                        if (!(0, fast_equals_1.deepEqual)(previousData, newData)) {
-                            return {
-                                [subscriber.statePropertyName]: newData,
-                            };
+                        if ((0, fast_equals_1.deepEqual)(previousData, newData)) {
+                            return null;
                         }
-                        return null;
+                        return {
+                            [subscriber.statePropertyName]: newData,
+                        };
                     });
                     continue;
                 }
                 subscriber.withOnyxInstance.setStateProxy((prevState) => {
                     var _a;
-                    const finalCollection = (0, clone_1.default)((_a = prevState === null || prevState === void 0 ? void 0 : prevState[subscriber.statePropertyName]) !== null && _a !== void 0 ? _a : {});
+                    const prevCollection = (_a = prevState === null || prevState === void 0 ? void 0 : prevState[subscriber.statePropertyName]) !== null && _a !== void 0 ? _a : {};
+                    const finalCollection = (0, clone_1.default)(prevCollection);
                     const dataKeys = Object.keys(partialCollection !== null && partialCollection !== void 0 ? partialCollection : {});
                     for (let j = 0; j < dataKeys.length; j++) {
                         const dataKey = dataKeys[j];
                         finalCollection[dataKey] = cachedCollection[dataKey];
                     }
+                    if ((0, fast_equals_1.deepEqual)(prevCollection, finalCollection)) {
+                        return null;
+                    }
                     PerformanceUtils.logSetStateCall(subscriber, prevState === null || prevState === void 0 ? void 0 : prevState[subscriber.statePropertyName], finalCollection, 'keysChanged', collectionKey);
                     return {
                         [subscriber.statePropertyName]: finalCollection,
@@ -469,29 +473,29 @@ function keysChanged(collectionKey, partialCollection, partialPreviousCollection
                     subscriber.withOnyxInstance.setStateProxy((prevState) => {
                         const prevData = prevState[subscriber.statePropertyName];
                         const newData = selector(cachedCollection[subscriber.key], subscriber.withOnyxInstance.state);
-                        if (!(0, fast_equals_1.deepEqual)(prevData, newData)) {
-                            PerformanceUtils.logSetStateCall(subscriber, prevData, newData, 'keysChanged', collectionKey);
-                            return {
-                                [subscriber.statePropertyName]: newData,
-                            };
+                        if ((0, fast_equals_1.deepEqual)(prevData, newData)) {
+                            return null;
                         }
-                        return null;
+                        PerformanceUtils.logSetStateCall(subscriber, prevData, newData, 'keysChanged', collectionKey);
+                        return {
+                            [subscriber.statePropertyName]: newData,
+                        };
                     });
                     continue;
                 }
                 subscriber.withOnyxInstance.setStateProxy((prevState) => {
-                    const data = cachedCollection[subscriber.key];
-                    const previousData = prevState[subscriber.statePropertyName];
+                    const prevData = prevState[subscriber.statePropertyName];
+                    const newData = cachedCollection[subscriber.key];
                     // Avoids triggering unnecessary re-renders when feeding empty objects
-                    if (utils_1.default.isEmptyObject(data) && utils_1.default.isEmptyObject(previousData)) {
+                    if (utils_1.default.isEmptyObject(newData) && utils_1.default.isEmptyObject(prevData)) {
                         return null;
                     }
-                    if (data === previousData) {
+                    if ((0, fast_equals_1.deepEqual)(prevData, newData)) {
                         return null;
                     }
-                    PerformanceUtils.logSetStateCall(subscriber, previousData, data, 'keysChanged', collectionKey);
+                    PerformanceUtils.logSetStateCall(subscriber, prevData, newData, 'keysChanged', collectionKey);
                     return {
-                        [subscriber.statePropertyName]: data,
+                        [subscriber.statePropertyName]: newData,
                     };
                 });
             }
@@ -553,20 +557,23 @@ function keyChanged(key, value, previousValue, canUpdateSubscriber = () => true,
                             [key]: selector(value, subscriber.withOnyxInstance.state),
                         };
                         const prevDataWithNewData = Object.assign(Object.assign({}, prevWithOnyxData), newWithOnyxData);
-                        if (!(0, fast_equals_1.deepEqual)(prevWithOnyxData, prevDataWithNewData)) {
-                            PerformanceUtils.logSetStateCall(subscriber, prevWithOnyxData, newWithOnyxData, 'keyChanged', key);
-                            return {
-                                [subscriber.statePropertyName]: prevDataWithNewData,
-                            };
+                        if ((0, fast_equals_1.deepEqual)(prevWithOnyxData, prevDataWithNewData)) {
+                            return null;
                         }
-                        return null;
+                        PerformanceUtils.logSetStateCall(subscriber, prevWithOnyxData, newWithOnyxData, 'keyChanged', key);
+                        return {
+                            [subscriber.statePropertyName]: prevDataWithNewData,
+                        };
                     });
                     continue;
                 }
                 subscriber.withOnyxInstance.setStateProxy((prevState) => {
-                    const collection = prevState[subscriber.statePropertyName] || {};
-                    const newCollection = Object.assign(Object.assign({}, collection), { [key]: value });
-                    PerformanceUtils.logSetStateCall(subscriber, collection, newCollection, 'keyChanged', key);
+                    const prevCollection = prevState[subscriber.statePropertyName] || {};
+                    const newCollection = Object.assign(Object.assign({}, prevCollection), { [key]: value });
+                    if ((0, fast_equals_1.deepEqual)(prevCollection, newCollection)) {
+                        return null;
+                    }
+                    PerformanceUtils.logSetStateCall(subscriber, prevCollection, newCollection, 'keyChanged', key);
                     return {
                         [subscriber.statePropertyName]: newCollection,
                     };
@@ -579,12 +586,12 @@ function keyChanged(key, value, previousValue, canUpdateSubscriber = () => true,
                 subscriber.withOnyxInstance.setStateProxy(() => {
                     const prevValue = selector(previousValue, subscriber.withOnyxInstance.state);
                     const newValue = selector(value, subscriber.withOnyxInstance.state);
-                    if (!(0, fast_equals_1.deepEqual)(prevValue, newValue)) {
-                        return {
-                            [subscriber.statePropertyName]: newValue,
-                        };
+                    if ((0, fast_equals_1.deepEqual)(prevValue, newValue)) {
+                        return null;
                     }
-                    return null;
+                    return {
+                        [subscriber.statePropertyName]: newValue,
+                    };
                 });
                 continue;
             }
@@ -763,7 +770,7 @@ function scheduleNotifyCollectionSubscribers(key, value, previousValue) {
 function remove(key) {
     const prevValue = OnyxCache_1.default.get(key, false);
     OnyxCache_1.default.drop(key);
-    scheduleSubscriberUpdate(key, null, prevValue);
+    scheduleSubscriberUpdate(key, undefined, prevValue);
     return storage_1.default.removeItem(key).then(() => undefined);
 }
 function reportStorageQuota() {
@@ -829,7 +836,10 @@ function hasPendingMergeForKey(key) {
 function removeNullValues(key, value, shouldRemoveNestedNulls = true) {
     if (value === null) {
         remove(key);
-        return { value: null, wasRemoved: true };
+        return { value, wasRemoved: true };
+    }
+    if (value === undefined) {
+        return { value, wasRemoved: false };
     }
     // 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
@@ -846,7 +856,7 @@ function removeNullValues(key, value, shouldRemoveNestedNulls = true) {
 function prepareKeyValuePairsForStorage(data, shouldRemoveNestedNulls) {
     return Object.entries(data).reduce((pairs, [key, value]) => {
         const { value: valueAfterRemoving, wasRemoved } = removeNullValues(key, value, shouldRemoveNestedNulls);
-        if (!wasRemoved) {
+        if (!wasRemoved && valueAfterRemoving !== undefined) {
             pairs.push([key, valueAfterRemoving]);
         }
         return pairs;
@@ -864,7 +874,7 @@ function applyMerge(existingValue, changes, shouldRemoveNestedNulls) {
     }
     if (changes.some((change) => change && typeof change === 'object')) {
         // Object values are then merged one after the other
-        return changes.reduce((modifiedData, change) => utils_1.default.fastMerge(modifiedData, change, shouldRemoveNestedNulls), existingValue || {});
+        return changes.reduce((modifiedData, change) => utils_1.default.fastMerge(modifiedData, change, shouldRemoveNestedNulls), (existingValue || {}));
     }
     // If we have anything else we can't merge it so we'll
     // simply return the last value that was queued

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, OnyxInput, OnyxKey, OnyxValue, Selector, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput } from './types';
+import type { CustomTypeOptions, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxValue, Selector, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, 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, OnyxInput, OnyxKey, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxUpdate, OnyxValue, ResultMetadata, Selector, UseOnyxResult, WithOnyxState, };
+export type { ConnectOptions, CustomTypeOptions, FetchStatus, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxUpdate, OnyxValue, ResultMetadata, Selector, UseOnyxResult, WithOnyxState, };

package/dist/types.d.ts

@@ -99,30 +99,6 @@ type CollectionKey = `${CollectionKeyBase}${string}`;
  * Represents a string union of all Onyx normal and collection keys.
  */
 type OnyxKey = Key | CollectionKey;
-/**
- * Represents a Onyx value that can be either a single entry or a collection of entries, depending on the `TKey` provided.
- */
-type OnyxValue<TKey extends OnyxKey> = string extends TKey ? unknown : TKey extends CollectionKeyBase ? OnyxCollection<KeyValueMapping[TKey]> : OnyxEntry<KeyValueMapping[TKey]>;
-/**
- * Represents a mapping of Onyx keys to values, where keys are either normal or collection Onyx keys
- * and values are the corresponding values in Onyx's state.
- *
- * For collection keys, `KeyValueMapping` allows any string to be appended
- * to the key (e.g., 'report_some-id', 'download_some-id').
- *
- * The mapping is derived from the `values` property of the `TypeOptions` type.
- */
-type KeyValueMapping = {
-    [TKey in keyof TypeOptions['values'] as TKey extends CollectionKeyBase ? `${TKey}${string}` : TKey]: TypeOptions['values'][TKey];
-};
-/**
- * Represents a mapping object where each `OnyxKey` maps to either a value of its corresponding type in `KeyValueMapping` or `null`.
- *
- * It's very similar to `KeyValueMapping` but this type accepts using `null` as well.
- */
-type NullableKeyValueMapping = {
-    [TKey in OnyxKey]: NonUndefined<OnyxValue<TKey>> | null;
-};
 /**
  * Represents a selector function type which operates based on the provided `TKey` and `ReturnType`.
  *
@@ -134,7 +110,7 @@ type NullableKeyValueMapping = {
  */
 type Selector<TKey extends OnyxKey, TOnyxProps, TReturnType> = (value: OnyxEntry<KeyValueMapping[TKey]>, state?: WithOnyxState<TOnyxProps>) => TReturnType;
 /**
- * Represents a single Onyx entry, that can be either `TOnyxValue` or `null` / `undefined` if it doesn't exist.
+ * Represents a single Onyx entry, that can be either `TOnyxValue` or `undefined` if it doesn't exist.
  *
  * It can be used to specify data retrieved from Onyx e.g. `withOnyx` HOC mappings.
  *
@@ -163,13 +139,7 @@ type Selector<TKey extends OnyxKey, TOnyxProps, TReturnType> = (value: OnyxEntry
  */
 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.
+ * Represents an Onyx collection of entries, that can be either a record of `TOnyxValue`s or `undefined` if it is empty or doesn't exist.
  *
  * It can be used to specify collection data retrieved from Onyx e.g. `withOnyx` HOC mappings.
  *
@@ -197,6 +167,22 @@ type OnyxInput<TOnyxValue> = TOnyxValue | null;
  * ```
  */
 type OnyxCollection<TOnyxValue> = OnyxEntry<Record<string, TOnyxValue | undefined>>;
+/**
+ * Represents a mapping of Onyx keys to values, where keys are either normal or collection Onyx keys
+ * and values are the corresponding values in Onyx's state.
+ *
+ * For collection keys, `KeyValueMapping` allows any string to be appended
+ * to the key (e.g., 'report_some-id', 'download_some-id').
+ *
+ * The mapping is derived from the `values` property of the `TypeOptions` type.
+ */
+type KeyValueMapping = {
+    [TKey in keyof TypeOptions['values'] as TKey extends CollectionKeyBase ? `${TKey}${string}` : TKey]: TypeOptions['values'][TKey];
+};
+/**
+ * Represents a Onyx value that can be either a single entry or a collection of entries, depending on the `TKey` provided.
+ */
+type OnyxValue<TKey extends OnyxKey> = string extends TKey ? unknown : TKey extends CollectionKeyBase ? OnyxCollection<KeyValueMapping[TKey]> : OnyxEntry<KeyValueMapping[TKey]>;
 /** 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[];
@@ -251,7 +237,7 @@ type WithOnyxConnectOptions<TKey extends OnyxKey> = {
     selector?: Selector<TKey, unknown, unknown>;
     canEvict?: boolean;
 };
-type DefaultConnectCallback<TKey extends OnyxKey> = (value: NonUndefined<OnyxEntry<KeyValueMapping[TKey]>>, key: TKey) => void;
+type DefaultConnectCallback<TKey extends OnyxKey> = (value: OnyxEntry<KeyValueMapping[TKey]>, key: TKey) => void;
 type CollectionConnectCallback<TKey extends OnyxKey> = (value: NonUndefined<OnyxCollection<KeyValueMapping[TKey]>>) => void;
 /** Represents the callback function used in `Onyx.connect()` method with a regular key. */
 type DefaultConnectOptions<TKey extends OnyxKey> = {
@@ -282,22 +268,46 @@ type ConnectOptions<TKey extends OnyxKey> = (CollectionConnectOptions<TKey> | De
 type Mapping<TKey extends OnyxKey> = ConnectOptions<TKey> & {
     connectionID: number;
 };
+/**
+ * Represents a single Onyx input value, that can be either `TOnyxValue` or `null` if the key should be deleted.
+ * This type is used for data passed to Onyx e.g. in `Onyx.merge` and `Onyx.set`.
+ */
+type OnyxInputValue<TOnyxValue> = TOnyxValue | null;
+/**
+ * Represents an Onyx collection input, that can be either a record of `TOnyxValue`s or `null` if the key should be deleted.
+ */
+type OnyxCollectionInputValue<TOnyxValue> = OnyxInputValue<Record<string, TOnyxValue | null>>;
+/**
+ * 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<TKey extends OnyxKey> = OnyxInputValue<NullishDeep<KeyValueMapping[TKey]>>;
+/**
+ * Represents a mapping object where each `OnyxKey` maps to either a value of its corresponding type in `KeyValueMapping` or `null`.
+ *
+ * It's very similar to `KeyValueMapping` but this type is used for inputs to Onyx
+ * (set, merge, mergeCollection) and therefore accepts using `null` to remove a key from Onyx.
+ */
+type OnyxInputKeyValueMapping = {
+    [TKey in OnyxKey]: OnyxInput<TKey>;
+};
 /**
  * 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]>;
+type OnyxSetInput<TKey extends OnyxKey> = OnyxInput<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>;
+type OnyxMultiSetInput = Partial<OnyxInputKeyValueMapping>;
 /**
  * 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]>>;
+type OnyxMergeInput<TKey extends OnyxKey> = OnyxInput<TKey>;
 /**
  * This represents the value that can be passed to `Onyx.merge` and to `Onyx.update` with the method "MERGE"
  */
-type OnyxMergeCollectionInput<TKey extends OnyxKey, TMap = object> = Collection<TKey, NullishDeep<KeyValueMapping[TKey]>, TMap>;
+type OnyxMergeCollectionInput<TKey extends OnyxKey, TMap = object> = Collection<TKey, NonNullable<OnyxInput<TKey>>, TMap>;
 /**
  * Represents different kinds of updates that can be passed to `Onyx.update()` method. It is a discriminated union of
  * different update methods (`SET`, `MERGE`, `MERGE_COLLECTION`), each with their own key and value structure.
@@ -334,7 +344,7 @@ type InitOptions = {
     /** `ONYXKEYS` constants object */
     keys?: DeepRecord<string, OnyxKey>;
     /** initial data to set when `init()` and `clear()` is called */
-    initialKeyStates?: Partial<NullableKeyValueMapping>;
+    initialKeyStates?: Partial<OnyxInputKeyValueMapping>;
     /**
      * This is an array of keys (individual or collection patterns) that when provided to Onyx are flagged
      * as "safe" for removal. Any components subscribing to these keys must also implement a canEvict option. See the README for more info.
@@ -355,4 +365,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, OnyxInput, OnyxKey, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, 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, OnyxInputKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxUpdate, OnyxValue, Selector, WithOnyxConnectOptions, };

package/dist/useOnyx.d.ts

@@ -1,10 +1,5 @@
 import type { IsEqual } from 'type-fest';
-import type { CollectionKeyBase, KeyValueMapping, NonNull, OnyxCollection, OnyxEntry, OnyxKey, Selector } from './types';
-/**
- * Represents a Onyx value that can be either a single entry or a collection of entries, depending on the `TKey` provided.
- * It's a variation of `OnyxValue` type that is read-only and excludes the `null` type.
- */
-type UseOnyxValue<TKey extends OnyxKey> = string extends TKey ? unknown : TKey extends CollectionKeyBase ? NonNull<OnyxCollection<KeyValueMapping[TKey]>> : NonNull<OnyxEntry<KeyValueMapping[TKey]>>;
+import type { CollectionKeyBase, OnyxCollection, OnyxKey, OnyxValue, Selector } from './types';
 type BaseUseOnyxOptions = {
     /**
      * Determines if this key in this subscription is safe to be evicted.
@@ -35,12 +30,12 @@ type UseOnyxSelectorOption<TKey extends OnyxKey, TReturnValue> = {
     selector?: Selector<TKey, unknown, TReturnValue>;
 };
 type FetchStatus = 'loading' | 'loaded';
-type CachedValue<TKey extends OnyxKey, TValue> = IsEqual<TValue, UseOnyxValue<TKey>> extends true ? TValue : TKey extends CollectionKeyBase ? NonNullable<OnyxCollection<TValue>> : TValue;
+type CachedValue<TKey extends OnyxKey, TValue> = IsEqual<TValue, OnyxValue<TKey>> extends true ? TValue : TKey extends CollectionKeyBase ? NonNullable<OnyxCollection<TValue>> : TValue;
 type ResultMetadata = {
     status: FetchStatus;
 };
 type UseOnyxResult<TKey extends OnyxKey, TValue> = [CachedValue<TKey, TValue>, ResultMetadata];
-declare function useOnyx<TKey extends OnyxKey, TReturnValue = UseOnyxValue<TKey>>(key: TKey, options?: BaseUseOnyxOptions & UseOnyxInitialValueOption<TReturnValue> & Required<UseOnyxSelectorOption<TKey, TReturnValue>>): UseOnyxResult<TKey, TReturnValue>;
-declare function useOnyx<TKey extends OnyxKey, TReturnValue = UseOnyxValue<TKey>>(key: TKey, options?: BaseUseOnyxOptions & UseOnyxInitialValueOption<NoInfer<TReturnValue>>): UseOnyxResult<TKey, TReturnValue>;
+declare function useOnyx<TKey extends OnyxKey, TReturnValue = OnyxValue<TKey>>(key: TKey, options?: BaseUseOnyxOptions & UseOnyxInitialValueOption<TReturnValue> & Required<UseOnyxSelectorOption<TKey, TReturnValue>>): UseOnyxResult<TKey, TReturnValue>;
+declare function useOnyx<TKey extends OnyxKey, TReturnValue = OnyxValue<TKey>>(key: TKey, options?: BaseUseOnyxOptions & UseOnyxInitialValueOption<NoInfer<TReturnValue>>): UseOnyxResult<TKey, TReturnValue>;
 export default useOnyx;
 export type { UseOnyxResult, ResultMetadata, FetchStatus };

package/dist/useOnyx.js

@@ -9,8 +9,10 @@ const OnyxUtils_1 = __importDefault(require("./OnyxUtils"));
 const useLiveRef_1 = __importDefault(require("./useLiveRef"));
 const usePrevious_1 = __importDefault(require("./usePrevious"));
 const Onyx_1 = __importDefault(require("./Onyx"));
+const OnyxCache_1 = __importDefault(require("./OnyxCache"));
 function getCachedValue(key, selector) {
-    return OnyxUtils_1.default.tryGetCachedValue(key, { selector });
+    var _a;
+    return ((_a = OnyxUtils_1.default.tryGetCachedValue(key, { selector })) !== null && _a !== void 0 ? _a : undefined);
 }
 function useOnyx(key, options) {
     const connectionIDRef = (0, react_1.useRef)(null);
@@ -18,8 +20,8 @@ function useOnyx(key, options) {
     // Used to stabilize the selector reference and avoid unnecessary calls to `getSnapshot()`.
     const selectorRef = (0, useLiveRef_1.default)(options === null || options === void 0 ? void 0 : options.selector);
     // Stores the previous cached value as it's necessary to compare with the new value in `getSnapshot()`.
-    // We initialize it to `undefined` to simulate that we don't have any value from cache yet.
-    const cachedValueRef = (0, react_1.useRef)(undefined);
+    // We initialize it to `null` to simulate that we don't have any value from cache yet.
+    const cachedValueRef = (0, react_1.useRef)(null);
     // Stores the previously result returned by the hook, containing the data from cache and the fetch status.
     // We initialize it to `undefined` and `loading` fetch status to simulate the initial result when the hook is loading from the cache.
     // However, if `initWithStoredValues` is `true` we set the fetch status to `loaded` since we want to signal that data is ready.
@@ -50,13 +52,14 @@ function useOnyx(key, options) {
         throw new Error(`'${previousKey}' key can't be changed to '${key}'. useOnyx() only supports dynamic keys if they are both collection member keys from the same collection e.g. from 'collection_id1' to 'collection_id2'.`);
     }, [previousKey, key]);
     const getSnapshot = (0, react_1.useCallback)(() => {
-        var _a;
+        var _a, _b;
         // We get the value from the cache, supplying a selector too in case it's defined.
         // If `newValue` is `undefined` it means that the cache doesn't have a value for that key yet.
-        // If `newValue` is `null` or any other value if means that the cache does have a value for that key.
+        // If `newValue` is `null` or any other value it means that the cache does have a value for that key.
         // This difference between `undefined` and other values is crucial and it's used to address the following
         // conditions and use cases.
         let newValue = getCachedValue(key, selectorRef.current);
+        const hasCacheForKey = OnyxCache_1.default.hasCacheForKey(key);
         // Since the fetch status can be different given the use cases below, we define the variable right away.
         let newFetchStatus;
         // If we have pending merge operations for the key during the first connection, we set the new value to `undefined`
@@ -66,18 +69,19 @@ function useOnyx(key, options) {
             newValue = undefined;
             newFetchStatus = 'loading';
         }
-        // If data is not present in cache (if it's `undefined`) and `initialValue` is set during the first connection,
+        // If data is not present in cache and `initialValue` is set during the first connection,
         // we set the new value to `initialValue` and fetch status to `loaded` since we already have some data to return to the consumer.
-        if (isFirstConnectionRef.current && newValue === undefined && (options === null || options === void 0 ? void 0 : options.initialValue) !== undefined) {
-            newValue = options === null || options === void 0 ? void 0 : options.initialValue;
+        if (isFirstConnectionRef.current && !hasCacheForKey && (options === null || options === void 0 ? void 0 : options.initialValue) !== undefined) {
+            newValue = ((_a = options === null || options === void 0 ? void 0 : options.initialValue) !== null && _a !== void 0 ? _a : undefined);
             newFetchStatus = 'loaded';
         }
         // If the previously cached value is different from the new value, we update both cached value
         // and the result to be returned by the hook.
-        if (!(0, fast_equals_1.deepEqual)(cachedValueRef.current, newValue)) {
+        // If the cache was set for the first time, we also update the cached value and the result.
+        const isCacheSetFirstTime = cachedValueRef.current === null && hasCacheForKey;
+        if (isCacheSetFirstTime || !(0, fast_equals_1.deepEqual)((_b = cachedValueRef.current) !== null && _b !== void 0 ? _b : undefined, newValue)) {
             cachedValueRef.current = newValue;
-            // If the new value is `null` we default it to `undefined` to ensure the consumer get a consistent result from the hook.
-            resultRef.current = [((_a = cachedValueRef.current) !== null && _a !== void 0 ? _a : undefined), { status: newFetchStatus !== null && newFetchStatus !== void 0 ? newFetchStatus : 'loaded' }];
+            resultRef.current = [cachedValueRef.current, { status: newFetchStatus !== null && newFetchStatus !== void 0 ? newFetchStatus : 'loaded' }];
         }
         return resultRef.current;
     }, [key, selectorRef, options === null || options === void 0 ? void 0 : options.allowStaleData, options === null || options === void 0 ? void 0 : options.initialValue]);

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import type { OnyxKey, OnyxValue } from './types';
+import type { OnyxInput, OnyxKey } from './types';
 type EmptyObject = Record<string, never>;
 type EmptyValue = EmptyObject | null | undefined;
 /** Checks whether the given object is an object and not null/undefined. */
@@ -10,9 +10,9 @@ declare function isEmptyObject<T>(obj: T | EmptyValue): obj is EmptyValue;
  * On native, when merging an existing value with new changes, SQLite will use JSON_PATCH, which removes top-level nullish values.
  * To be consistent with the behaviour for merge, we'll also want to remove null values for "set" operations.
  */
-declare function fastMerge<TObject extends Record<string, unknown>>(target: TObject | null, source: TObject | null, shouldRemoveNestedNulls?: boolean): TObject | null;
+declare function fastMerge<TValue>(target: TValue, source: TValue, shouldRemoveNestedNulls?: boolean): TValue;
 /** Deep removes the nested null values from the given value. */
-declare function removeNestedNullValues<TValue extends OnyxValue<OnyxKey> | unknown | unknown[]>(value: TValue | null): TValue | null;
+declare function removeNestedNullValues<TValue extends OnyxInput<OnyxKey> | null>(value: TValue): TValue;
 /** 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

@@ -22,19 +22,23 @@ function isMergeableObject(value) {
  */
 function mergeObject(target, source, shouldRemoveNestedNulls = true) {
     const destination = {};
+    const targetObject = isMergeableObject(target) ? target : undefined;
     // First we want to copy over all keys from the target into the destination object,
     // in case "target" is a mergable object.
     // If "shouldRemoveNestedNulls" is true, we want to remove null values from the merged object
     // and therefore we need to omit keys where either the source or target value is null.
-    if (isMergeableObject(target)) {
-        const targetKeys = Object.keys(target);
+    if (targetObject) {
+        const targetKeys = Object.keys(targetObject);
         for (let i = 0; i < targetKeys.length; ++i) {
             const key = targetKeys[i];
             const sourceValue = source === null || source === void 0 ? void 0 : source[key];
-            const targetValue = target === null || target === void 0 ? void 0 : target[key];
+            const targetValue = targetObject === null || targetObject === void 0 ? void 0 : targetObject[key];
             // If "shouldRemoveNestedNulls" is true, we want to remove null values from the merged object.
             // Therefore, if either target or source value is null, we want to prevent the key from being set.
-            const isSourceOrTargetNull = targetValue === null || sourceValue === null;
+            // targetValue should techincally never be "undefined", because it will always be a value from cache or storage
+            // and we never set "undefined" there. Still, if there targetValue is undefined we don't want to set
+            // the key explicitly to prevent loose undefined values in objects in cache and storage.
+            const isSourceOrTargetNull = targetValue === undefined || targetValue === null || sourceValue === null;
             const shouldOmitTargetKey = shouldRemoveNestedNulls && isSourceOrTargetNull;
             if (!shouldOmitTargetKey) {
                 destination[key] = targetValue;
@@ -46,7 +50,7 @@ function mergeObject(target, source, shouldRemoveNestedNulls = true) {
     for (let i = 0; i < sourceKeys.length; ++i) {
         const key = sourceKeys[i];
         const sourceValue = source === null || source === void 0 ? void 0 : source[key];
-        const targetValue = target === null || target === void 0 ? void 0 : target[key];
+        const targetValue = targetObject === null || targetObject === void 0 ? void 0 : targetObject[key];
         // If undefined is passed as the source value for a key, we want to generally ignore it.
         // If "shouldRemoveNestedNulls" is set to true and the source value is null,
         // we don't want to set/merge the source value into the merged object.

package/dist/withOnyx/index.js

@@ -207,7 +207,7 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
                 }
                 this.tempState[statePropertyName] = val;
                 // If some key does not have a value yet, do not update the state yet
-                const tempStateIsMissingKey = requiredKeysForInit.some((key) => { var _a; return ((_a = this.tempState) === null || _a === void 0 ? void 0 : _a[key]) === undefined; });
+                const tempStateIsMissingKey = requiredKeysForInit.some((key) => { var _a; return !(key in ((_a = this.tempState) !== null && _a !== void 0 ? _a : {})); });
                 if (tempStateIsMissingKey) {
                     return;
                 }

package/package.json

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