react-native-onyx 1.0.17 → 1.0.18

package/lib/Onyx.js

@@ -1,6 +1,6 @@
+/* eslint-disable no-continue */
 import _ from 'underscore';
 import Str from 'expensify-common/lib/str';
-import lodashMerge from 'lodash/merge';
 import lodashGet from 'lodash/get';
 import Storage from './storage';
 import * as Logger from './Logger';
@@ -107,8 +107,17 @@ function isCollectionKey(key) {
 }
 
 /**
- * Checks to see if a given key matches with the
- * configured key of our connected subscriber
+ * @param {String} collectionKey
+ * @param {String} key
+ * @returns {Boolean}
+ */
+function isCollectionMemberKey(collectionKey, key) {
+    return Str.startsWith(key, collectionKey) && key.length > collectionKey.length;
+}
+
+/**
+ * Checks to see if a provided key is the exact configured key of our connected subscriber
+ * or if the provided key is a collection member key (in case our configured key is a "collection key")
  *
  * @private
  * @param {String} configKey
@@ -225,7 +234,7 @@ function addAllSafeEvictionKeysToRecentlyAccessedList() {
  */
 function getCachedCollection(collectionKey) {
     const collectionMemberKeys = _.filter(cache.getAllKeys(), (
-        storedKey => isKeyMatch(collectionKey, storedKey)
+        storedKey => isCollectionMemberKey(collectionKey, storedKey)
     ));
 
     return _.reduce(collectionMemberKeys, (prev, curr) => {
@@ -245,73 +254,103 @@ function getCachedCollection(collectionKey) {
  *
  * @private
  * @param {String} collectionKey
- * @param {Object} collection
+ * @param {Object} partialCollection - a partial collection of grouped member keys
  */
-function keysChanged(collectionKey, collection) {
-    // Find all subscribers that were added with connect() and trigger the callback or setState() with the new data
-    _.each(callbackToStateMapping, (subscriber) => {
+function keysChanged(collectionKey, partialCollection) {
+    // 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().
+    const stateMappingKeys = _.keys(callbackToStateMapping);
+    for (let i = stateMappingKeys.length; i--;) {
+        const subscriber = callbackToStateMapping[stateMappingKeys[i]];
         if (!subscriber) {
-            return;
+            continue;
+        }
+
+        // Skip iteration if we do not have a collection key or a collection member key on this subscriber
+        if (!Str.startsWith(subscriber.key, collectionKey)) {
+            continue;
         }
 
         /**
          * e.g. Onyx.connect({key: ONYXKEYS.COLLECTION.REPORT, callback: ...});
          */
-        const isSubscribedToCollectionKey = isKeyMatch(subscriber.key, collectionKey)
-            && isCollectionKey(subscriber.key);
+        const isSubscribedToCollectionKey = subscriber.key === collectionKey;
 
         /**
          * e.g. Onyx.connect({key: `${ONYXKEYS.COLLECTION.REPORT}{reportID}`, callback: ...});
          */
-        const isSubscribedToCollectionMemberKey = subscriber.key.startsWith(collectionKey);
+        const isSubscribedToCollectionMemberKey = isCollectionMemberKey(collectionKey, subscriber.key);
 
-        if (isSubscribedToCollectionKey) {
-            if (_.isFunction(subscriber.callback)) {
-                const cachedCollection = getCachedCollection(collectionKey);
+        // We prepare the "cached collection" which is the entire collection + the new partial data that
+        // was merged in via mergeCollection().
+        const cachedCollection = getCachedCollection(collectionKey);
 
+        // Regular Onyx.connect() subscriber found.
+        if (_.isFunction(subscriber.callback)) {
+            // If they are subscribed to the collection key and using waitForCollectionCallback then we'll
+            // send the whole cached collection.
+            if (isSubscribedToCollectionKey) {
                 if (subscriber.waitForCollectionCallback) {
                     subscriber.callback(cachedCollection);
-                    return;
+                    continue;
                 }
 
-                _.each(collection, (data, dataKey) => {
+                // If they are not using waitForCollectionCallback then we notify the subscriber with
+                // the new merged data but only for any keys in the partial collection.
+                const dataKeys = _.keys(partialCollection);
+                for (let j = 0; j < dataKeys.length; j++) {
+                    const dataKey = dataKeys[j];
                     subscriber.callback(cachedCollection[dataKey], dataKey);
-                });
-            } else if (subscriber.withOnyxInstance) {
+                }
+                continue;
+            }
+
+            // And if the subscriber is specifically only tracking a particular collection member key then we will
+            // notify them with the cached data for that key only.
+            if (isSubscribedToCollectionMemberKey) {
+                subscriber.callback(cachedCollection[subscriber.key], subscriber.key);
+                continue;
+            }
+
+            continue;
+        }
+
+        // React component subscriber found.
+        if (subscriber.withOnyxInstance) {
+            // We are subscribed to a collection key so we must update the data in state with the new
+            // collection member key values from the partial update.
+            if (isSubscribedToCollectionKey) {
                 subscriber.withOnyxInstance.setState((prevState) => {
                     const finalCollection = _.clone(prevState[subscriber.statePropertyName] || {});
-                    _.each(collection, (data, dataKey) => {
-                        if (finalCollection[dataKey]) {
-                            lodashMerge(finalCollection[dataKey], data);
-                        } else {
-                            finalCollection[dataKey] = data;
-                        }
-                    });
 
+                    const dataKeys = _.keys(partialCollection);
+                    for (let j = 0; j < dataKeys.length; j++) {
+                        const dataKey = dataKeys[j];
+                        finalCollection[dataKey] = cachedCollection[dataKey];
+                    }
                     return {
                         [subscriber.statePropertyName]: finalCollection,
                     };
                 });
+                continue;
             }
-        } else if (isSubscribedToCollectionMemberKey) {
-            const dataFromCollection = collection[subscriber.key];
 
-            // If `dataFromCollection` happens to not exist, then return early so that there are no unnecessary
-            // re-renderings of the component
-            if (_.isUndefined(dataFromCollection)) {
-                return;
-            }
+            // 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) {
+                // 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[subscriber.key];
+                if (_.isUndefined(dataFromCollection)) {
+                    continue;
+                }
 
-            subscriber.withOnyxInstance.setState(prevState => ({
-                [subscriber.statePropertyName]: _.isObject(dataFromCollection)
-                    ? {
-                        ...prevState[subscriber.statePropertyName],
-                        ...dataFromCollection,
-                    }
-                    : dataFromCollection,
-            }));
+                subscriber.withOnyxInstance.setState({
+                    [subscriber.statePropertyName]: cachedCollection[subscriber.key],
+                });
+            }
         }
-    });
+    }
 }
 
 /**
@@ -329,43 +368,54 @@ function keyChanged(key, data) {
         removeLastAccessedKey(key);
     }
 
-    // Find all subscribers that were added with connect() and trigger the callback or setState() with the new data
-    _.each(callbackToStateMapping, (subscriber) => {
+    // We are iterating over all subscribers to see if they are interested in the key that has just changed. If the subscriber's  key is a collection key then we will
+    // notify them if the key that changed is a collection member. Or if it is a regular key notify them when there is an exact match. Depending on whether the subscriber
+    // was connected via withOnyx we will call setState() directly on the withOnyx instance. If it is a regular connection we will pass the data to the provided callback.
+    const stateMappingKeys = _.keys(callbackToStateMapping);
+    for (let i = stateMappingKeys.length; i--;) {
+        const subscriber = callbackToStateMapping[stateMappingKeys[i]];
         if (!subscriber || !isKeyMatch(subscriber.key, key)) {
-            return;
+            continue;
         }
 
+        // Subscriber is a regular call to connect() and provided a callback
         if (_.isFunction(subscriber.callback)) {
-            if (subscriber.waitForCollectionCallback) {
+            if (isCollectionKey(subscriber.key) && subscriber.waitForCollectionCallback) {
                 const cachedCollection = getCachedCollection(subscriber.key);
                 cachedCollection[key] = data;
                 subscriber.callback(cachedCollection);
-                return;
+                continue;
             }
 
             subscriber.callback(data, key);
-            return;
+            continue;
         }
 
-        if (!subscriber.withOnyxInstance) {
-            return;
-        }
+        // Subscriber connected via withOnyx() HOC
+        if (subscriber.withOnyxInstance) {
+            // Check if we are subscribing to a collection key and overwrite the collection member key value in state
+            if (isCollectionKey(subscriber.key)) {
+                subscriber.withOnyxInstance.setState((prevState) => {
+                    const collection = prevState[subscriber.statePropertyName] || {};
+                    return {
+                        [subscriber.statePropertyName]: {
+                            ...collection,
+                            [key]: data,
+                        },
+                    };
+                });
+                continue;
+            }
 
-        // Check if we are subscribing to a collection key and add this item as a collection
-        if (isCollectionKey(subscriber.key)) {
-            subscriber.withOnyxInstance.setState((prevState) => {
-                const collection = _.clone(prevState[subscriber.statePropertyName] || {});
-                collection[key] = data;
-                return {
-                    [subscriber.statePropertyName]: collection,
-                };
-            });
-        } else {
+            // If we did not match on a collection key then we just set the new data to the state property
             subscriber.withOnyxInstance.setState({
                 [subscriber.statePropertyName]: data,
             });
+            continue;
         }
-    });
+
+        console.error('Warning: Found a matching subscriber to a key that changed, but no callback or withOnyxInstance could be found.');
+    }
 }
 
 /**
@@ -379,9 +429,9 @@ function keyChanged(key, data) {
  * @param {string} [config.statePropertyName]
  * @param {function} [config.callback]
  * @param {*|null} val
- * @param {String} key
+ * @param {String} matchedKey
  */
-function sendDataToConnection(config, val, key) {
+function sendDataToConnection(config, val, matchedKey) {
     // If the mapping no longer exists then we should not send any data.
     // This means our subscriber disconnected or withOnyx wrapped component unmounted.
     if (!callbackToStateMapping[config.connectionID]) {
@@ -391,10 +441,54 @@ function sendDataToConnection(config, val, key) {
     if (config.withOnyxInstance) {
         config.withOnyxInstance.setWithOnyxState(config.statePropertyName, val);
     } else if (_.isFunction(config.callback)) {
-        config.callback(val, key);
+        config.callback(val, matchedKey);
     }
 }
 
+/**
+ * We check to see if this key is flagged as safe for eviction and add it to the recentlyAccessedKeys list so that when we
+ * run out of storage the least recently accessed key can be removed.
+ *
+ * @private
+ * @param {Object} mapping
+ */
+function addKeyToRecentlyAccessedIfNeeded(mapping) {
+    if (!isSafeEvictionKey(mapping.key)) {
+        return;
+    }
+
+    // Try to free some cache whenever we connect to a safe eviction key
+    cache.removeLeastRecentlyUsedKeys();
+
+    if (mapping.withOnyxInstance && !isCollectionKey(mapping.key)) {
+        // All React components subscribing to a key flagged as a safe eviction key must implement the canEvict property.
+        if (_.isUndefined(mapping.canEvict)) {
+            throw new Error(
+                `Cannot subscribe to safe eviction key '${mapping.key}' without providing a canEvict value.`,
+            );
+        }
+
+        addLastAccessedKey(mapping.key);
+    }
+}
+
+/**
+ * Gets the data for a given an array of matching keys, combines them into an object, and sends the result back to the subscriber.
+ *
+ * @private
+ * @param {Array} matchingKeys
+ * @param {Object} mapping
+ */
+function getCollectionDataAndSendAsObject(matchingKeys, mapping) {
+    Promise.all(_.map(matchingKeys, key => get(key)))
+        .then(values => _.reduce(values, (finalObject, value, i) => {
+            // eslint-disable-next-line no-param-reassign
+            finalObject[matchingKeys[i]] = value;
+            return finalObject;
+        }, {}))
+        .then(val => sendDataToConnection(mapping, val));
+}
+
 /**
  * Subscribes a react component's state directly to a store key
  *
@@ -427,58 +521,63 @@ function connect(mapping) {
 
     // Commit connection only after init passes
     deferredInitTask.promise
-        .then(() => {
-            // Check to see if this key is flagged as a safe eviction key and add it to the recentlyAccessedKeys list
-            if (!isSafeEvictionKey(mapping.key)) {
+        .then(() => addKeyToRecentlyAccessedIfNeeded(mapping))
+        .then(getAllKeys)
+        .then((keys) => {
+            // We search all the keys in storage to see if any are a "match" for the subscriber we are connecting so that we
+            // can send data back to the subscriber. Note that multiple keys can match as a subscriber could either be
+            // subscribed to a "collection key" or a single key.
+            const matchingKeys = _.filter(keys, key => isKeyMatch(mapping.key, key));
+
+            // If the key being connected to does not exist we initialize the value with null. For subscribers that connected
+            // directly via connect() they will simply get a null value sent to them without any information about which key matched
+            // since there are none matched. In withOnyx() we wait for all connected keys to return a value before rendering the child
+            // component. This null value will be filtered out so that the connected component can utilize defaultProps.
+            if (matchingKeys.length === 0) {
+                sendDataToConnection(mapping, null);
                 return;
             }
 
-            // Try to free some cache whenever we connect to a safe eviction key
-            cache.removeLeastRecentlyUsedKeys();
+            // When using a callback subscriber we will either trigger the provided callback for each key we find or combine all values
+            // into an object and just make a single call. The latter behavior is enabled by providing a waitForCollectionCallback key
+            // combined with a subscription to a collection key.
+            if (_.isFunction(mapping.callback)) {
+                if (isCollectionKey(mapping.key)) {
+                    if (mapping.waitForCollectionCallback) {
+                        getCollectionDataAndSendAsObject(matchingKeys, mapping);
+                        return;
+                    }
 
-            if (mapping.withOnyxInstance && !isCollectionKey(mapping.key)) {
-                // All React components subscribing to a key flagged as a safe eviction
-                // key must implement the canEvict property.
-                if (_.isUndefined(mapping.canEvict)) {
-                    throw new Error(
-                        `Cannot subscribe to safe eviction key '${mapping.key}' without providing a canEvict value.`,
-                    );
+                    // We did not opt into using waitForCollectionCallback mode so the callback is called for every matching key.
+                    for (let i = 0; i < matchingKeys.length; i++) {
+                        get(matchingKeys[i]).then(val => sendDataToConnection(mapping, val, matchingKeys[i]));
+                    }
+                    return;
                 }
 
-                addLastAccessedKey(mapping.key);
+                // If we are not subscribed to a collection key then there's only a single key to send an update for.
+                get(mapping.key).then(val => sendDataToConnection(mapping, val, mapping.key));
+                return;
             }
-        })
-        .then(getAllKeys)
-        .then((keys) => {
-            // Find all the keys matched by the config key
-            const matchingKeys = _.filter(keys, key => isKeyMatch(mapping.key, key));
 
-            // If the key being connected to does not exist, initialize the value with null
-            if (matchingKeys.length === 0) {
-                sendDataToConnection(mapping, null);
+            // If we have a withOnyxInstance that means a React component has subscribed via the withOnyx() HOC and we need to
+            // group collection key member data into an object.
+            if (mapping.withOnyxInstance) {
+                if (isCollectionKey(mapping.key)) {
+                    getCollectionDataAndSendAsObject(matchingKeys, mapping);
+                    return;
+                }
+
+                // If the subscriber is not using a collection key then we just send a single value back to the subscriber
+                get(mapping.key).then(val => sendDataToConnection(mapping, val, mapping.key));
                 return;
             }
 
-            // When using a callback subscriber we will trigger the callback
-            // for each key we find. It's up to the subscriber to know whether
-            // to expect a single key or multiple keys in the case of a collection.
-            // React components are an exception since we'll want to send their
-            // initial data as a single object when using collection keys.
-            if ((mapping.withOnyxInstance && isCollectionKey(mapping.key)) || mapping.waitForCollectionCallback) {
-                Promise.all(_.map(matchingKeys, key => get(key)))
-                    .then(values => _.reduce(values, (finalObject, value, i) => {
-                        // eslint-disable-next-line no-param-reassign
-                        finalObject[matchingKeys[i]] = value;
-                        return finalObject;
-                    }, {}))
-                    .then(val => sendDataToConnection(mapping, val));
-            } else {
-                _.each(matchingKeys, (key) => {
-                    get(key).then(val => sendDataToConnection(mapping, val, key));
-                });
-            }
+            console.error('Warning: Onyx.connect() was found without a callback or withOnyxInstance');
         });
 
+    // The connectionID is returned back to the caller so that it can be used to clean up the connection when it's no longer needed
+    // by calling Onyx.disconnect(connectionID).
     return connectionID;
 }
 
@@ -788,7 +887,7 @@ function clear() {
  */
 function mergeCollection(collectionKey, collection) {
     // Confirm all the collection keys belong to the same parent
-    _.each(collection, (data, dataKey) => {
+    _.each(collection, (_data, dataKey) => {
         if (isKeyMatch(collectionKey, dataKey)) {
             return;
         }

package/package.json

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