react-native-onyx 2.0.35 → 2.0.37

package/dist/Onyx.d.ts

@@ -1,5 +1,5 @@
 import * as Logger from './Logger';
-import type { Collection, CollectionKeyBase, ConnectOptions, InitOptions, KeyValueMapping, Mapping, NullableKeyValueMapping, NullishDeep, OnyxEntry, OnyxKey, OnyxUpdate } from './types';
+import type { Collection, CollectionKeyBase, ConnectOptions, InitOptions, KeyValueMapping, Mapping, NonUndefined, NullableKeyValueMapping, NullishDeep, OnyxEntry, OnyxKey, 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: OnyxEntry<KeyValueMapping[TKey]>): Promise<void>;
+declare function set<TKey extends OnyxKey>(key: TKey, value: NonUndefined<OnyxEntry<KeyValueMapping[TKey]>>): Promise<void>;
 /**
  * Sets multiple keys and values
  *
@@ -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: OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>): Promise<void>;
+declare function merge<TKey extends OnyxKey>(key: TKey, changes: NonUndefined<OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>>): Promise<void>;
 /**
  * Merges a collection based on their keys
  *

package/dist/Onyx.js

@@ -401,6 +401,9 @@ function mergeCollection(collectionKey, collection) {
         // because we will simply overwrite the existing values in storage.
         const keyValuePairsForNewCollection = OnyxUtils_1.default.prepareKeyValuePairsForStorage(newCollection, true);
         const promises = [];
+        // We need to get the previously existing values so we can compare the new ones
+        // against them, to avoid unnecessary subscriber updates.
+        const previousCollectionPromise = Promise.all(existingKeys.map((key) => OnyxUtils_1.default.get(key).then((value) => [key, value]))).then(Object.fromEntries);
         // New keys will be added via multiSet while existing keys will be updated using multiMerge
         // This is because setting a key that doesn't exist yet with multiMerge will throw errors
         if (keyValuePairsForExistingCollection.length > 0) {
@@ -413,9 +416,9 @@ function mergeCollection(collectionKey, collection) {
         const finalMergedCollection = Object.assign(Object.assign({}, existingKeyCollection), newCollection);
         // Prefill cache if necessary by calling get() on any existing keys and then merge original data to cache
         // and update all subscribers
-        const promiseUpdate = Promise.all(existingKeys.map(OnyxUtils_1.default.get)).then(() => {
+        const promiseUpdate = previousCollectionPromise.then((previousCollection) => {
             OnyxCache_1.default.merge(finalMergedCollection);
-            return OnyxUtils_1.default.scheduleNotifyCollectionSubscribers(collectionKey, finalMergedCollection);
+            return OnyxUtils_1.default.scheduleNotifyCollectionSubscribers(collectionKey, finalMergedCollection, previousCollection);
         });
         return Promise.all(promises)
             .catch((error) => OnyxUtils_1.default.evictStorageAndRetry(error, mergeCollection, collectionKey, mergedCollection))

package/dist/OnyxUtils.d.ts

@@ -107,14 +107,14 @@ 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]>, notifyRegularSubscibers?: boolean, notifyWithOnyxSubscibers?: boolean): void;
+declare function keysChanged<TKey extends CollectionKeyBase>(collectionKey: TKey, partialCollection: OnyxCollection<KeyValueMapping[TKey]>, previousPartialCollection: 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
  *
  * @example
  * keyChanged(key, value, subscriber => subscriber.initWithStoredValues === false)
  */
-declare function keyChanged<TKey extends OnyxKey>(key: TKey, data: OnyxValue<TKey>, prevData: OnyxValue<TKey>, canUpdateSubscriber?: (subscriber?: Mapping<OnyxKey>) => boolean, notifyRegularSubscibers?: boolean, notifyWithOnyxSubscibers?: boolean): void;
+declare function keyChanged<TKey extends OnyxKey>(key: TKey, value: OnyxValue<TKey>, previousValue: OnyxValue<TKey>, canUpdateSubscriber?: (subscriber?: Mapping<OnyxKey>) => boolean, notifyRegularSubscibers?: boolean, notifyWithOnyxSubscibers?: boolean): void;
 /**
  * Sends the data obtained from the keys to the connection. It either:
  *     - sets state on the withOnyxInstances
@@ -136,13 +136,13 @@ declare function getCollectionDataAndSendAsObject<TKey extends OnyxKey>(matching
  * @example
  * scheduleSubscriberUpdate(key, value, subscriber => subscriber.initWithStoredValues === false)
  */
-declare function scheduleSubscriberUpdate<TKey extends OnyxKey>(key: TKey, value: OnyxValue<TKey>, prevValue: OnyxValue<TKey>, canUpdateSubscriber?: (subscriber?: Mapping<OnyxKey>) => boolean): Promise<void>;
+declare function scheduleSubscriberUpdate<TKey extends OnyxKey>(key: TKey, value: OnyxValue<TKey>, previousValue: OnyxValue<TKey>, canUpdateSubscriber?: (subscriber?: Mapping<OnyxKey>) => boolean): Promise<void>;
 /**
  * This method is similar to notifySubscribersOnNextTick but it is built for working specifically with collections
  * so that keysChanged() is triggered for the collection and not keyChanged(). If this was not done, then the
  * subscriber callbacks receive the data in a different format than they normally expect and it breaks code.
  */
-declare function scheduleNotifyCollectionSubscribers<TKey extends OnyxKey>(key: TKey, value: OnyxCollection<KeyValueMapping[TKey]>): Promise<void>;
+declare function scheduleNotifyCollectionSubscribers<TKey extends OnyxKey>(key: TKey, value: OnyxCollection<KeyValueMapping[TKey]>, previousValue?: OnyxCollection<KeyValueMapping[TKey]>): Promise<void>;
 /**
  * Remove a key from Onyx and update the subscribers
  */

package/dist/OnyxUtils.js

@@ -338,7 +338,16 @@ function getCachedCollection(collectionKey, collectionMemberKeys) {
 /**
  * When a collection of keys change, search for any callbacks matching the collection key and trigger those callbacks
  */
-function keysChanged(collectionKey, partialCollection, notifyRegularSubscibers = true, notifyWithOnyxSubscibers = true) {
+function keysChanged(collectionKey, partialCollection, previousPartialCollection, notifyRegularSubscibers = true, notifyWithOnyxSubscibers = true) {
+    const previousCollectionWithoutNestedNulls = previousPartialCollection === undefined ? {} : utils_1.default.removeNestedNullValues(previousPartialCollection);
+    // 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)) {
+        return;
+    }
     // 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().
@@ -360,10 +369,6 @@ function keysChanged(collectionKey, partialCollection, notifyRegularSubscibers =
          * e.g. Onyx.connect({key: `${ONYXKEYS.COLLECTION.REPORT}{reportID}`, callback: ...});
          */
         const isSubscribedToCollectionMemberKey = isCollectionMemberKey(collectionKey, subscriber.key);
-        // 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);
         // Regular Onyx.connect() subscriber found.
         if (typeof subscriber.callback === 'function') {
             if (!notifyRegularSubscibers) {
@@ -381,6 +386,9 @@ function keysChanged(collectionKey, partialCollection, notifyRegularSubscibers =
                 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])) {
+                        continue;
+                    }
                     subscriber.callback(cachedCollectionWithoutNestedNulls[dataKey], dataKey);
                 }
                 continue;
@@ -388,6 +396,9 @@ function keysChanged(collectionKey, partialCollection, notifyRegularSubscibers =
             // 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])) {
+                    continue;
+                }
                 const subscriberCallback = subscriber.callback;
                 subscriberCallback(cachedCollectionWithoutNestedNulls[subscriber.key], subscriber.key);
                 continue;
@@ -435,6 +446,9 @@ function keysChanged(collectionKey, partialCollection, notifyRegularSubscibers =
             }
             // 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])) {
+                    continue;
+                }
                 // However, we only want to update this subscriber if the partial data contains a change.
                 // Otherwise, we would update them with a value they already have and trigger an unnecessary re-render.
                 const dataFromCollection = partialCollection === null || partialCollection === void 0 ? void 0 : partialCollection[subscriber.key];
@@ -484,9 +498,9 @@ function keysChanged(collectionKey, partialCollection, notifyRegularSubscibers =
  * @example
  * keyChanged(key, value, subscriber => subscriber.initWithStoredValues === false)
  */
-function keyChanged(key, data, prevData, canUpdateSubscriber = () => true, notifyRegularSubscibers = true, notifyWithOnyxSubscibers = true) {
+function keyChanged(key, value, previousValue, canUpdateSubscriber = () => true, notifyRegularSubscibers = true, notifyWithOnyxSubscibers = true) {
     // Add or remove this key from the recentlyAccessedKeys lists
-    if (data !== null) {
+    if (value !== null) {
         addLastAccessedKey(key);
     }
     else {
@@ -509,13 +523,13 @@ function keyChanged(key, data, prevData, canUpdateSubscriber = () => true, notif
             if (isCollectionKey(subscriber.key) && subscriber.waitForCollectionCallback) {
                 const cachedCollection = getCachedCollection(subscriber.key);
                 const cachedCollectionWithoutNestedNulls = utils_1.default.removeNestedNullValues(cachedCollection);
-                cachedCollectionWithoutNestedNulls[key] = data;
+                cachedCollectionWithoutNestedNulls[key] = value;
                 subscriber.callback(cachedCollectionWithoutNestedNulls);
                 continue;
             }
-            const dataWithoutNestedNulls = utils_1.default.removeNestedNullValues(data);
+            const valueWithoutNestedNulls = utils_1.default.removeNestedNullValues(value);
             const subscriberCallback = subscriber.callback;
-            subscriberCallback(dataWithoutNestedNulls, key);
+            subscriberCallback(valueWithoutNestedNulls, key);
             continue;
         }
         // Subscriber connected via withOnyx() HOC
@@ -532,7 +546,7 @@ function keyChanged(key, data, prevData, canUpdateSubscriber = () => true, notif
                     subscriber.withOnyxInstance.setStateProxy((prevState) => {
                         const prevWithOnyxData = prevState[subscriber.statePropertyName];
                         const newWithOnyxData = {
-                            [key]: selector(data, subscriber.withOnyxInstance.state),
+                            [key]: selector(value, subscriber.withOnyxInstance.state),
                         };
                         const prevDataWithNewData = Object.assign(Object.assign({}, prevWithOnyxData), newWithOnyxData);
                         if (!(0, fast_equals_1.deepEqual)(prevWithOnyxData, prevDataWithNewData)) {
@@ -547,7 +561,7 @@ function keyChanged(key, data, prevData, canUpdateSubscriber = () => true, notif
                 }
                 subscriber.withOnyxInstance.setStateProxy((prevState) => {
                     const collection = prevState[subscriber.statePropertyName] || {};
-                    const newCollection = Object.assign(Object.assign({}, collection), { [key]: data });
+                    const newCollection = Object.assign(Object.assign({}, collection), { [key]: value });
                     PerformanceUtils.logSetStateCall(subscriber, collection, newCollection, 'keyChanged', key);
                     return {
                         [subscriber.statePropertyName]: newCollection,
@@ -559,9 +573,9 @@ function keyChanged(key, data, prevData, canUpdateSubscriber = () => true, notif
             // returned by the selector and only if the selected data has changed.
             if (selector) {
                 subscriber.withOnyxInstance.setStateProxy(() => {
-                    const previousValue = selector(prevData, subscriber.withOnyxInstance.state);
-                    const newValue = selector(data, subscriber.withOnyxInstance.state);
-                    if (!(0, fast_equals_1.deepEqual)(previousValue, newValue)) {
+                    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,
                         };
@@ -572,17 +586,17 @@ function keyChanged(key, data, prevData, canUpdateSubscriber = () => true, notif
             }
             // If we did not match on a collection key then we just set the new data to the state property
             subscriber.withOnyxInstance.setStateProxy((prevState) => {
-                const prevWithOnyxData = prevState[subscriber.statePropertyName];
+                const prevWithOnyxValue = prevState[subscriber.statePropertyName];
                 // Avoids triggering unnecessary re-renders when feeding empty objects
-                if (utils_1.default.isEmptyObject(data) && utils_1.default.isEmptyObject(prevWithOnyxData)) {
+                if (utils_1.default.isEmptyObject(value) && utils_1.default.isEmptyObject(prevWithOnyxValue)) {
                     return null;
                 }
-                if (prevWithOnyxData === data) {
+                if (prevWithOnyxValue === value) {
                     return null;
                 }
-                PerformanceUtils.logSetStateCall(subscriber, prevData, data, 'keyChanged', key);
+                PerformanceUtils.logSetStateCall(subscriber, previousValue, value, 'keyChanged', key);
                 return {
-                    [subscriber.statePropertyName]: data,
+                    [subscriber.statePropertyName]: value,
                 };
             });
             continue;
@@ -719,9 +733,9 @@ function getCollectionDataAndSendAsObject(matchingKeys, mapping) {
  * @example
  * scheduleSubscriberUpdate(key, value, subscriber => subscriber.initWithStoredValues === false)
  */
-function scheduleSubscriberUpdate(key, value, prevValue, canUpdateSubscriber = () => true) {
-    const promise = Promise.resolve().then(() => keyChanged(key, value, prevValue, canUpdateSubscriber, true, false));
-    batchUpdates(() => keyChanged(key, value, prevValue, canUpdateSubscriber, false, true));
+function scheduleSubscriberUpdate(key, value, previousValue, canUpdateSubscriber = () => true) {
+    const promise = Promise.resolve().then(() => keyChanged(key, value, previousValue, canUpdateSubscriber, true, false));
+    batchUpdates(() => keyChanged(key, value, previousValue, canUpdateSubscriber, false, true));
     return Promise.all([maybeFlushBatchUpdates(), promise]).then(() => undefined);
 }
 /**
@@ -729,9 +743,9 @@ function scheduleSubscriberUpdate(key, value, prevValue, canUpdateSubscriber = (
  * so that keysChanged() is triggered for the collection and not keyChanged(). If this was not done, then the
  * subscriber callbacks receive the data in a different format than they normally expect and it breaks code.
  */
-function scheduleNotifyCollectionSubscribers(key, value) {
-    const promise = Promise.resolve().then(() => keysChanged(key, value, true, false));
-    batchUpdates(() => keysChanged(key, value, false, true));
+function scheduleNotifyCollectionSubscribers(key, value, previousValue) {
+    const promise = Promise.resolve().then(() => keysChanged(key, value, previousValue, true, false));
+    batchUpdates(() => keysChanged(key, value, previousValue, false, true));
     return Promise.all([maybeFlushBatchUpdates(), promise]).then(() => undefined);
 }
 /**

package/dist/types.d.ts

@@ -2,6 +2,14 @@ import type { Component } from 'react';
 import type { Merge } from 'type-fest';
 import type { BuiltIns } from 'type-fest/source/internal';
 import type OnyxUtils from './OnyxUtils';
+/**
+ * Utility type that excludes `null` from the type `TValue`.
+ */
+type NonNull<TValue> = TValue extends null ? never : TValue;
+/**
+ * Utility type that excludes `undefined` from the type `TValue`.
+ */
+type NonUndefined<TValue> = TValue extends undefined ? never : TValue;
 /**
  * Represents a deeply nested record. It maps keys to values,
  * and those values can either be of type `TValue` or further nested `DeepRecord` instances.
@@ -126,7 +134,7 @@ type NullableKeyValueMapping = {
  */
 type Selector<TKey extends OnyxKey, TOnyxProps, TReturnType> = (value: OnyxEntry<KeyValueMapping[TKey]>, state: WithOnyxInstanceState<TOnyxProps>) => TReturnType;
 /**
- * Represents a single Onyx entry, that can be either `TOnyxValue` or `null` if it doesn't exist.
+ * Represents a single Onyx entry, that can be either `TOnyxValue` or `null` / `undefined` if it doesn't exist.
  *
  * It can be used to specify data retrieved from Onyx e.g. `withOnyx` HOC mappings.
  *
@@ -153,9 +161,9 @@ type Selector<TKey extends OnyxKey, TOnyxProps, TReturnType> = (value: OnyxEntry
  * })(Component);
  * ```
  */
-type OnyxEntry<TOnyxValue> = TOnyxValue | null;
+type OnyxEntry<TOnyxValue> = TOnyxValue | null | undefined;
 /**
- * Represents an Onyx collection of entries, that can be either a record of `TOnyxValue`s or `null` if it is empty or doesn't exist.
+ * 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.
  *
  * It can be used to specify collection data retrieved from Onyx e.g. `withOnyx` HOC mappings.
  *
@@ -182,7 +190,7 @@ type OnyxEntry<TOnyxValue> = TOnyxValue | null;
  * })(Component);
  * ```
  */
-type OnyxCollection<TOnyxValue> = OnyxEntry<Record<string, TOnyxValue | null>>;
+type OnyxCollection<TOnyxValue> = OnyxEntry<Record<string, TOnyxValue | null | 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[];
@@ -247,8 +255,8 @@ type WithOnyxConnectOptions<TKey extends OnyxKey> = {
     selector?: Selector<TKey, unknown, unknown>;
     canEvict?: boolean;
 };
-type DefaultConnectCallback<TKey extends OnyxKey> = (value: OnyxEntry<KeyValueMapping[TKey]>, key: TKey) => void;
-type CollectionConnectCallback<TKey extends OnyxKey> = (value: OnyxCollection<KeyValueMapping[TKey]>) => void;
+type DefaultConnectCallback<TKey extends OnyxKey> = (value: NonUndefined<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> = {
     key: TKey;
@@ -286,11 +294,11 @@ type OnyxUpdate = {
     [TKey in OnyxKey]: {
         onyxMethod: typeof OnyxUtils.METHOD.SET;
         key: TKey;
-        value: OnyxEntry<KeyValueMapping[TKey]>;
+        value: NonUndefined<OnyxEntry<KeyValueMapping[TKey]>>;
     } | {
         onyxMethod: typeof OnyxUtils.METHOD.MERGE;
         key: TKey;
-        value: OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>;
+        value: NonUndefined<OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>>;
     } | {
         onyxMethod: typeof OnyxUtils.METHOD.MULTI_SET;
         key: TKey;
@@ -334,4 +342,4 @@ type InitOptions = {
     /** Enables debugging setState() calls to connected components */
     debugSetState?: boolean;
 };
-export type { CollectionKey, CollectionKeyBase, CustomTypeOptions, DeepRecord, Key, KeyValueMapping, NullableKeyValueMapping, OnyxCollection, OnyxEntry, OnyxKey, OnyxValue, Selector, NullishDeep, WithOnyxInstanceState, ExtractOnyxCollectionValue, Collection, WithOnyxInstance, BaseConnectOptions, WithOnyxConnectOptions, DefaultConnectCallback, CollectionConnectCallback, DefaultConnectOptions, CollectionConnectOptions, ConnectOptions, Mapping, OnyxUpdate, InitOptions, };
+export type { BaseConnectOptions, Collection, CollectionConnectCallback, CollectionConnectOptions, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, DefaultConnectOptions, ExtractOnyxCollectionValue, InitOptions, Key, KeyValueMapping, Mapping, NonNull, NonUndefined, NullableKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxUpdate, OnyxValue, Selector, WithOnyxConnectOptions, WithOnyxInstance, WithOnyxInstanceState, };

package/dist/useOnyx.d.ts

@@ -1,6 +1,11 @@
 import type { IsEqual } from 'type-fest';
-import type { CollectionKeyBase, OnyxCollection, OnyxKey, OnyxValue, Selector } from './types';
-type UseOnyxOptions<TKey extends OnyxKey, TReturnValue> = {
+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 ? Readonly<NonNull<OnyxCollection<KeyValueMapping[TKey]>>> : Readonly<NonNull<OnyxEntry<KeyValueMapping[TKey]>>>;
+type BaseUseOnyxOptions = {
     /**
      * Determines if this key in this subscription is safe to be evicted.
      */
@@ -13,10 +18,14 @@ type UseOnyxOptions<TKey extends OnyxKey, TReturnValue> = {
      * If set to true, data will be retrieved from cache during the first render even if there is a pending merge for the key.
      */
     allowStaleData?: boolean;
+};
+type UseOnyxInitialValueOption<TInitialValue> = {
     /**
      * This value will be returned by the hook on the first render while the data is being read from Onyx.
      */
-    initialValue?: TReturnValue;
+    initialValue?: TInitialValue;
+};
+type UseOnyxSelectorOption<TKey extends OnyxKey, TReturnValue> = {
     /**
      * This will be used to subscribe to a subset of an Onyx key's data.
      * Using this setting on `useOnyx` can have very positive performance benefits because the component will only re-render
@@ -26,11 +35,12 @@ type UseOnyxOptions<TKey extends OnyxKey, TReturnValue> = {
     selector?: Selector<TKey, unknown, TReturnValue>;
 };
 type FetchStatus = 'loading' | 'loaded';
-type CachedValue<TKey extends OnyxKey, TValue> = IsEqual<TValue, OnyxValue<TKey>> extends true ? TValue : TKey extends CollectionKeyBase ? NonNullable<OnyxCollection<TValue>> : TValue;
+type CachedValue<TKey extends OnyxKey, TValue> = IsEqual<TValue, UseOnyxValue<TKey>> extends true ? TValue : TKey extends CollectionKeyBase ? Readonly<NonNullable<OnyxCollection<TValue>>> : Readonly<TValue>;
 type ResultMetadata = {
     status: FetchStatus;
 };
 type UseOnyxResult<TKey extends OnyxKey, TValue> = [CachedValue<TKey, TValue>, ResultMetadata];
-declare function useOnyx<TKey extends OnyxKey, TReturnValue = OnyxValue<TKey>>(key: TKey, options?: UseOnyxOptions<TKey, TReturnValue>): UseOnyxResult<TKey, TReturnValue>;
+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>;
 export default useOnyx;
 export type { UseOnyxResult, ResultMetadata, FetchStatus };

package/dist/useOnyx.js

@@ -21,10 +21,10 @@ function useOnyx(key, options) {
     // We initialize it to `undefined` to simulate that we don't have any value from cache yet.
     const cachedValueRef = (0, react_1.useRef)(undefined);
     // Stores the previously result returned by the hook, containing the data from cache and the fetch status.
-    // We initialize it to `null` and `loading` fetch status to simulate the initial result when the hook is loading from the cache.
+    // 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.
     const resultRef = (0, react_1.useRef)([
-        null,
+        undefined,
         {
             status: (options === null || options === void 0 ? void 0 : options.initWithStoredValues) === false ? 'loaded' : 'loading',
         },
@@ -76,8 +76,8 @@ function useOnyx(key, options) {
         // and the result to be returned by the hook.
         if (!(0, fast_equals_1.deepEqual)(cachedValueRef.current, newValue)) {
             cachedValueRef.current = newValue;
-            // If the new value is `undefined` we default it to `null` to ensure the consumer get a consistent result from the hook.
-            resultRef.current = [((_a = cachedValueRef.current) !== null && _a !== void 0 ? _a : null), { status: newFetchStatus !== null && newFetchStatus !== void 0 ? newFetchStatus : 'loaded' }];
+            // 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' }];
         }
         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/withOnyx.d.ts

@@ -125,6 +125,8 @@ type OnyxPropCollectionMapping<TComponentProps, TOnyxProps, TOnyxProp extends ke
 }[CollectionKeyBase];
 
 /**
+ * @deprecated Use `useOnyx` instead of `withOnyx` whenever possible.
+ *
  * This is a higher order component that provides the ability to map a state property directly to
  * something in Onyx (a key/value store). That way, as soon as data in Onyx changes, the state will be set and the view
  * will automatically change to reflect the new data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-onyx",
-  "version": "2.0.35",
+  "version": "2.0.37",
   "author": "Expensify, Inc.",
   "homepage": "https://expensify.com",
   "description": "State management for React Native",
@@ -85,7 +85,7 @@
     "reassure": "^0.11.0",
     "ts-node": "^10.9.2",
     "type-fest": "^3.12.0",
-    "typescript": "^5.3.3"
+    "typescript": "^5.4.5"
   },
   "peerDependencies": {
     "idb-keyval": "^6.2.1",