react-native-onyx 2.0.94 → 2.0.96

package/README.md

@@ -256,6 +256,21 @@ DO NOT use more than one `withOnyx` component at a time. It adds overhead and pr
 
 It's also beneficial to use a [selector](https://github.com/Expensify/react-native-onyx/blob/main/API.md#connectmapping--number) with the mapping in case you need to grab a single item in a collection (like a single report action).
 
+### useOnyx()'s `canBeMissing` option
+
+You must pass the `canBeMissing` configuration flag to `useOnyx` if you want the hook to log an alert when data is missing from Onyx store. Regarding usage in `Expensify/App` repo, if the component calling this is the one loading the data by calling an action, then you should set this to `true`. If the component calling this does not load the data then you should set it to `false`, which means that if the data is not there, it will log an alert, as it means we are using data that no one loaded and that's most probably a bug.
+
+```javascript
+const Component = ({reportID}) => {
+    // This hook will log an alert (via `Logger.logAlert()`) if `report` is `undefined`.
+    const [report] = useOnyx(`${ONYXKEYS.COLLECTION.REPORT}${reportID}`, {canBeMissing: false});
+    
+    // rest of the component's code.
+};
+
+export default Component;
+```
+
 ## Collections
 
 Collections allow keys with similar value types to be subscribed together by subscribing to the collection key. To define one, it must be included in the `ONYXKEYS.COLLECTION` object and it must be suffixed with an underscore. Member keys should use a unique identifier or index after the collection key prefix (e.g. `report_42`).
@@ -316,11 +331,11 @@ This will fire the callback once per member key depending on how many collection
 Onyx.connect({
     key: ONYXKEYS.COLLECTION.REPORT,
     waitForCollectionCallback: true,
-    callback: (allReports) => {...},
+    callback: (allReports, collectionKey, sourceValue) => {...},
 });
 ```
 
-This final option forces `Onyx.connect()` to behave more like `useOnyx()` and only update the callback once with the entire collection initially and later with an updated version of the collection when individual keys update.
+This final option forces `Onyx.connect()` to behave more like `useOnyx()` and only update the callback once with the entire collection initially and later with an updated version of the collection when individual keys update. The `sourceValue` parameter contains only the specific keys and values that triggered the current update, which can be useful for optimizing your code to only process what changed. This parameter is not available when `waitForCollectionCallback` is false or the key is not a collection key.
 
 ### Performance Considerations When Using Collections
 

package/dist/Logger.d.ts

@@ -1,6 +1,8 @@
+type Parameters = string | Record<string, unknown> | Array<Record<string, unknown>> | Error;
 type LogData = {
     message: string;
     level: 'alert' | 'info' | 'hmmm';
+    parameters?: Parameters;
 };
 type LoggerCallback = (data: LogData) => void;
 /**
@@ -10,13 +12,13 @@ declare function registerLogger(callback: LoggerCallback): void;
 /**
  * Send an alert message to the logger
  */
-declare function logAlert(message: string): void;
+declare function logAlert(message: string, parameters?: Parameters): void;
 /**
  * Send an info message to the logger
  */
-declare function logInfo(message: string): void;
+declare function logInfo(message: string, parameters?: Parameters): void;
 /**
  * Send an hmmm message to the logger
  */
-declare function logHmmm(message: string): void;
+declare function logHmmm(message: string, parameters?: Parameters): void;
 export { registerLogger, logInfo, logAlert, logHmmm };

package/dist/Logger.js

@@ -13,21 +13,21 @@ exports.registerLogger = registerLogger;
 /**
  * Send an alert message to the logger
  */
-function logAlert(message) {
-    logger({ message: `[Onyx] ${message}`, level: 'alert' });
+function logAlert(message, parameters) {
+    logger({ message: `[Onyx] ${message}`, level: 'alert', parameters });
 }
 exports.logAlert = logAlert;
 /**
  * Send an info message to the logger
  */
-function logInfo(message) {
-    logger({ message: `[Onyx] ${message}`, level: 'info' });
+function logInfo(message, parameters) {
+    logger({ message: `[Onyx] ${message}`, level: 'info', parameters });
 }
 exports.logInfo = logInfo;
 /**
  * Send an hmmm message to the logger
  */
-function logHmmm(message) {
-    logger({ message: `[Onyx] ${message}`, level: 'hmmm' });
+function logHmmm(message, parameters) {
+    logger({ message: `[Onyx] ${message}`, level: 'hmmm', parameters });
 }
 exports.logHmmm = logHmmm;

package/dist/OnyxConnectionManager.js

@@ -73,7 +73,12 @@ class OnyxConnectionManager {
     fireCallbacks(connectionID) {
         const connection = this.connectionsMap.get(connectionID);
         connection === null || connection === void 0 ? void 0 : connection.callbacks.forEach((callback) => {
-            callback(connection.cachedCallbackValue, connection.cachedCallbackKey);
+            if (connection.waitForCollectionCallback) {
+                callback(connection.cachedCallbackValue, connection.cachedCallbackKey, connection.sourceValue);
+            }
+            else {
+                callback(connection.cachedCallbackValue, connection.cachedCallbackKey);
+            }
         });
     }
     /**
@@ -93,7 +98,7 @@ class OnyxConnectionManager {
             // If the subscriber is a `withOnyx` HOC we don't define `callback` as the HOC will use
             // its own logic to handle the data.
             if (!utils_1.default.hasWithOnyxInstance(connectOptions)) {
-                callback = (value, key) => {
+                callback = (value, key, sourceValue) => {
                     const createdConnection = this.connectionsMap.get(connectionID);
                     if (createdConnection) {
                         // We signal that the first connection was made and now any new subscribers
@@ -101,16 +106,18 @@ class OnyxConnectionManager {
                         createdConnection.isConnectionMade = true;
                         createdConnection.cachedCallbackValue = value;
                         createdConnection.cachedCallbackKey = key;
+                        createdConnection.sourceValue = sourceValue;
                         this.fireCallbacks(connectionID);
                     }
                 };
             }
-            subscriptionID = OnyxUtils_1.default.subscribeToKey(Object.assign(Object.assign({}, connectOptions), { callback }));
+            subscriptionID = OnyxUtils_1.default.subscribeToKey(Object.assign(Object.assign({}, connectOptions), { callback: callback }));
             connectionMetadata = {
                 subscriptionID,
                 onyxKey: connectOptions.key,
                 isConnectionMade: false,
                 callbacks: new Map(),
+                waitForCollectionCallback: connectOptions.waitForCollectionCallback,
             };
             this.connectionsMap.set(connectionID, connectionMetadata);
         }

package/dist/OnyxUtils.d.ts

@@ -73,7 +73,7 @@ declare function multiGet<TKey extends OnyxKey>(keys: CollectionKeyBase[]): Prom
  * This helper exists to map an array of Onyx keys such as `['report_', 'conciergeReportID']`
  * to the values for those keys (correctly typed) such as `[OnyxCollection<Report>, OnyxEntry<string>]`
  *
- * Note: just using .map, you'd end up with `Array<OnyxCollection<Report>|OnyxEntry<string>>`, which is not what we want. This preserves the order of the keys provided.
+ * Note: just using `.map`, you'd end up with `Array<OnyxCollection<Report>|OnyxEntry<string>>`, which is not what we want. This preserves the order of the keys provided.
  */
 declare function tupleGet<Keys extends readonly OnyxKey[]>(keys: Keys): Promise<{
     [Index in keyof Keys]: OnyxValue<Keys[Index]>;

package/dist/OnyxUtils.js

@@ -314,7 +314,7 @@ function multiGet(keys) {
  * This helper exists to map an array of Onyx keys such as `['report_', 'conciergeReportID']`
  * to the values for those keys (correctly typed) such as `[OnyxCollection<Report>, OnyxEntry<string>]`
  *
- * Note: just using .map, you'd end up with `Array<OnyxCollection<Report>|OnyxEntry<string>>`, which is not what we want. This preserves the order of the keys provided.
+ * Note: just using `.map`, you'd end up with `Array<OnyxCollection<Report>|OnyxEntry<string>>`, which is not what we want. This preserves the order of the keys provided.
  */
 function tupleGet(keys) {
     return Promise.all(keys.map((key) => OnyxUtils.get(key)));
@@ -562,7 +562,7 @@ function keysChanged(collectionKey, partialCollection, partialPreviousCollection
             // send the whole cached collection.
             if (isSubscribedToCollectionKey) {
                 if (subscriber.waitForCollectionCallback) {
-                    subscriber.callback(cachedCollection, subscriber.key);
+                    subscriber.callback(cachedCollection, subscriber.key, partialCollection);
                     continue;
                 }
                 // If they are not using waitForCollectionCallback then we notify the subscriber with
@@ -738,7 +738,7 @@ function keyChanged(key, value, previousValue, canUpdateSubscriber = () => true,
                     cachedCollections[subscriber.key] = cachedCollection;
                 }
                 cachedCollection[key] = value;
-                subscriber.callback(cachedCollection, subscriber.key);
+                subscriber.callback(cachedCollection, subscriber.key, { [key]: value });
                 continue;
             }
             const subscriberCallback = subscriber.callback;

package/dist/types.d.ts

@@ -238,7 +238,7 @@ type BaseConnectOptions = {
 /** Represents the callback function used in `Onyx.connect()` method with a regular key. */
 type DefaultConnectCallback<TKey extends OnyxKey> = (value: OnyxEntry<KeyValueMapping[TKey]>, key: TKey) => void;
 /** Represents the callback function used in `Onyx.connect()` method with a collection key. */
-type CollectionConnectCallback<TKey extends OnyxKey> = (value: NonUndefined<OnyxCollection<KeyValueMapping[TKey]>>, key: TKey) => void;
+type CollectionConnectCallback<TKey extends OnyxKey> = (value: NonUndefined<OnyxCollection<KeyValueMapping[TKey]>>, key: TKey, sourceValue?: OnyxValue<TKey>) => void;
 /** Represents the options used in `Onyx.connect()` method with a regular key. */
 type DefaultConnectOptions<TKey extends OnyxKey> = BaseConnectOptions & {
     /** The Onyx key to subscribe to. */

package/dist/useOnyx.d.ts

@@ -22,6 +22,13 @@ type BaseUseOnyxOptions = {
      * If set to `true`, the key can be changed dynamically during the component lifecycle.
      */
     allowDynamicKey?: boolean;
+    /**
+     * If the component calling this is the one loading the data by calling an action, then you should set this to `true`.
+     *
+     * If the component calling this does not load the data then you should set it to `false`, which means that if the data
+     * is not there, it will log an alert, as it means we are using data that no one loaded and that's most probably a bug.
+     */
+    canBeMissing?: boolean;
 };
 type UseOnyxInitialValueOption<TInitialValue> = {
     /**

package/dist/useOnyx.js

@@ -35,6 +35,7 @@ const GlobalSettings = __importStar(require("./GlobalSettings"));
 const useLiveRef_1 = __importDefault(require("./useLiveRef"));
 const usePrevious_1 = __importDefault(require("./usePrevious"));
 const metrics_1 = __importDefault(require("./metrics"));
+const Logger = __importStar(require("./Logger"));
 /**
  * Gets the cached value from the Onyx cache. If the key is a collection key, it will return all the values in the collection.
  * It is a fork of `tryGetCachedValue` from `OnyxUtils` caused by different selector logic in `useOnyx`. It should be unified in the future, when `withOnyx` is removed.
@@ -58,14 +59,6 @@ function tryGetCachedValue(key) {
     });
     return values;
 }
-/**
- * Gets the value from cache and maps it with selector. It changes `null` to `undefined` for `useOnyx` compatibility.
- */
-function getCachedValue(key, selector) {
-    const value = tryGetCachedValue(key);
-    const selectedValue = selector ? selector(value) : value;
-    return selectedValue !== null && selectedValue !== void 0 ? selectedValue : undefined;
-}
 function useOnyx(key, options, dependencies = []) {
     const connectionRef = (0, react_1.useRef)(null);
     const previousKey = (0, usePrevious_1.default)(key);
@@ -140,7 +133,8 @@ function useOnyx(key, options, dependencies = []) {
         }
     }, [key, options === null || options === void 0 ? void 0 : options.canEvict]);
     const getSnapshot = (0, react_1.useCallback)(() => {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
+        let isOnyxValueDefined = true;
         // We return the initial result right away during the first connection if `initWithStoredValues` is set to `false`.
         if (isFirstConnectionRef.current && (options === null || options === void 0 ? void 0 : options.initWithStoredValues) === false) {
             return resultRef.current;
@@ -149,11 +143,13 @@ function useOnyx(key, options, dependencies = []) {
         // so we can return any cached value right away. After the connection is made, we only
         // update `newValueRef` when `Onyx.connect()` callback is fired.
         if (isFirstConnectionRef.current || shouldGetCachedValueRef.current) {
-            // If `newValueRef.current` is `undefined` it means that the cache doesn't have a value for that key yet.
-            // If `newValueRef.current` 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.
-            newValueRef.current = getCachedValue(key, selectorRef.current);
+            // Gets the value from cache and maps it with selector. It changes `null` to `undefined` for `useOnyx` compatibility.
+            const value = tryGetCachedValue(key);
+            const selectedValue = selectorRef.current ? selectorRef.current(value) : value;
+            newValueRef.current = (selectedValue !== null && selectedValue !== void 0 ? selectedValue : undefined);
+            // This flag is `false` when the original Onyx value (without selector) is not defined yet.
+            // It will be used later to check if we need to log an alert that the value is missing.
+            isOnyxValueDefined = value !== null && value !== undefined;
             // We set this flag to `false` again since we don't want to get the newest cached value every time `getSnapshot()` is executed,
             // and only when `Onyx.connect()` callback is fired.
             shouldGetCachedValueRef.current = false;
@@ -171,7 +167,7 @@ function useOnyx(key, options, dependencies = []) {
         // 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 && !hasCacheForKey && (options === null || options === void 0 ? void 0 : options.initialValue) !== undefined) {
-            newValueRef.current = ((_a = options === null || options === void 0 ? void 0 : options.initialValue) !== null && _a !== void 0 ? _a : undefined);
+            newValueRef.current = options.initialValue;
             newFetchStatus = 'loaded';
         }
         // We do a deep equality check if `selector` is defined, since each `tryGetCachedValue()` call will
@@ -179,12 +175,12 @@ function useOnyx(key, options, dependencies = []) {
         // For the other cases we will only deal with object reference checks, so just a shallow equality check is enough.
         let areValuesEqual;
         if (selectorRef.current) {
-            areValuesEqual = (0, fast_equals_1.deepEqual)((_b = previousValueRef.current) !== null && _b !== void 0 ? _b : undefined, newValueRef.current);
+            areValuesEqual = (0, fast_equals_1.deepEqual)((_a = previousValueRef.current) !== null && _a !== void 0 ? _a : undefined, newValueRef.current);
         }
         else {
-            areValuesEqual = (0, fast_equals_1.shallowEqual)((_c = previousValueRef.current) !== null && _c !== void 0 ? _c : undefined, newValueRef.current);
+            areValuesEqual = (0, fast_equals_1.shallowEqual)((_b = previousValueRef.current) !== null && _b !== void 0 ? _b : undefined, newValueRef.current);
         }
-        // We updated the cached value and the result in the following conditions:
+        // We update the cached value and the result in the following conditions:
         // We will update the cached value and the result in any of the following situations:
         // - The previously cached value is different from the new value.
         // - The previously cached value is `null` (not set from cache yet) and we have cache for this key
@@ -194,10 +190,16 @@ function useOnyx(key, options, dependencies = []) {
         if (shouldUpdateResult) {
             previousValueRef.current = newValueRef.current;
             // If the new value is `null` we default it to `undefined` to ensure the consumer gets a consistent result from the hook.
-            resultRef.current = [(_d = previousValueRef.current) !== null && _d !== void 0 ? _d : undefined, { status: newFetchStatus !== null && newFetchStatus !== void 0 ? newFetchStatus : 'loaded' }];
+            const newStatus = newFetchStatus !== null && newFetchStatus !== void 0 ? newFetchStatus : 'loaded';
+            resultRef.current = [(_c = previousValueRef.current) !== null && _c !== void 0 ? _c : undefined, { status: newStatus }];
+            // If `canBeMissing` is set to `false` and the Onyx value of that key is not defined,
+            // we log an alert so it can be acknowledged by the consumer.
+            if ((options === null || options === void 0 ? void 0 : options.canBeMissing) === false && newStatus === 'loaded' && !isOnyxValueDefined) {
+                Logger.logAlert(`useOnyx returned no data for key with canBeMissing set to false.`, { key, showAlert: true });
+            }
         }
         return resultRef.current;
-    }, [options === null || options === void 0 ? void 0 : options.initWithStoredValues, options === null || options === void 0 ? void 0 : options.allowStaleData, options === null || options === void 0 ? void 0 : options.initialValue, key, selectorRef]);
+    }, [options === null || options === void 0 ? void 0 : options.initWithStoredValues, options === null || options === void 0 ? void 0 : options.allowStaleData, options === null || options === void 0 ? void 0 : options.initialValue, options === null || options === void 0 ? void 0 : options.canBeMissing, key, selectorRef]);
     const subscribe = (0, react_1.useCallback)((onStoreChange) => {
         isConnectingRef.current = true;
         onStoreChangeFnRef.current = onStoreChange;

package/package.json

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