react-native-onyx 2.0.94 → 2.0.95

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`).

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/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)));

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.95",
   "author": "Expensify, Inc.",
   "homepage": "https://expensify.com",
   "description": "State management for React Native",