Add additional documentation for handling collections. Fix behavior of waitForCollectionCallback.

API.md

@@ -76,6 +76,7 @@ Subscribes a react component's state directly to a store key
 | [mapping.withOnyxInstance] | <code>Object</code> | whose setState() method will be called with any changed data      This is used by React components to connect to Onyx |
 | [mapping.callback] | <code>function</code> | a method that will be called with changed data      This is used by any non-React code to connect to Onyx |
 | [mapping.initWithStoredValues] | <code>Boolean</code> | If set to false, then no data will be prefilled into the  component |
+| [mapping.waitForCollectionCallback] | <code>Boolean</code> | If set to true, it will return the entire collection to the callback as a single object |
 
 **Example**
 ```js

README.md

@@ -137,6 +137,70 @@ export default withOnyx({
 
 It is preferable to use the HOC over `Onyx.connect()` in React code as `withOnyx()` will delay the rendering of the wrapped component until all keys have been accessed and made available.
 
+## 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. `chat_42`).
+
+```javascript
+const ONYXKEYS = {
+    COLLECTION: {
+        CHAT: 'chat_',
+    },
+};
+```
+
+### Setting Collection Values
+
+To save a new collection key we can either do:
+
+```js
+Onyx.merge(`${ONYXKEYS.COLLECTION.CHAT}${chat1.id}`, chat1);
+```
+
+or we can set many at once with `mergeCollection()`:
+
+```js
+Onyx.mergeCollection(ONYXKEYS.COLLECTION.CHAT, {
+    [`${ONYXKEYS.COLLECTION.CHAT}${chat1.id}`]: chat1,
+    [`${ONYXKEYS.COLLECTION.CHAT}${chat2.id}`]: chat2,
+    [`${ONYXKEYS.COLLECTION.CHAT}${chat3.id}`]: chat3,
+});
+```
+
+### Subscribing to Collections
+
+There are several ways to subscribe to these keys:
+
+```javascript
+withOnyx({
+    allChats: {key: ONYXKEYS.COLLECTION.CHAT},
+})(MyComponent);
+```
+
+This will return the initial collection as an object of collection member key/values. Changes to the individual member keys will modify the entire object and new props will be passed with each individual key update.
+
+```js
+Onyx.connect({key: ONYXKEYS.COLLECTION.CHAT}, callback: (memberValue, memberKey) => {...}});
+```
+
+This will fire the callback `n` times depending on how many collection member keys have been stored. Changes to those keys after the initial callbacks fire will occur when each individual key is updated.
+
+```js
+Onyx.connect({
+    key: ONYXKEYS.COLLECTION.CHAT,
+    waitForCollectionCallback: true,
+    callback: (allChats) => {...}},
+});
+```
+
+This final option forces `Onyx.connect()` to behave more like `withOnyx()` and only update the callback once with the entire collection initially and later with an updated version of the collection when individual keys update.
+
+### Performance Considerations When Using Collections
+
+Be cautious when using collections as things can get out of hand if you have a subscriber hooked up to a collection key that has large numbers of individual keys. If this is the case, it is critical to use `mergeCollection()` over `merge()`.
+
+Remember, `mergeCollection()` will notify a subscriber only *once* with the total collected values whereas each call to `Onyx.merge()` would re-render a connected component `n` times per key that you call it on.
+
 ## Clean up
 
 To clear all data from `Onyx` we can use `Onyx.clear()`.

lib/Onyx.js

@@ -253,8 +253,15 @@ function keysChanged(collectionKey, collection) {
             return;
         }
 
+        /**
+         * e.g. Onyx.connect({key: ONYXKEYS.COLLECTION.REPORT, callback: ...});
+         */
         const isSubscribedToCollectionKey = isKeyMatch(subscriber.key, collectionKey)
             && isCollectionKey(subscriber.key);
+
+        /**
+         * e.g. Onyx.connect({key: `${ONYXKEYS.COLLECTION.REPORT}{reportID}`, callback: ...});
+         */
         const isSubscribedToCollectionMemberKey = subscriber.key.startsWith(collectionKey);
 
         if (isSubscribedToCollectionKey) {
@@ -328,7 +335,15 @@ function keyChanged(key, data) {
         }
 
         if (_.isFunction(subscriber.callback)) {
+            if (subscriber.waitForCollectionCallback) {
+                const cachedCollection = getCachedCollection(subscriber.key);
+                cachedCollection[key] = data;
+                subscriber.callback(cachedCollection);
+                return;
+            }
+
             subscriber.callback(data, key);
+            return;
         }
 
         if (!subscriber.withOnyxInstance) {
@@ -397,7 +412,7 @@ function sendDataToConnection(config, val, key) {
  *      This is used by any non-React code to connect to Onyx
  * @param {Boolean} [mapping.initWithStoredValues] If set to false, then no data will be prefilled into the
  *  component
- * @param {Boolean} [mapping.waitForCollectionCallback] If set to true, it will trigger the callback once and return all data as a single object
+ * @param {Boolean} [mapping.waitForCollectionCallback] If set to true, it will return the entire collection to the callback as a single object
  * @returns {Number} an ID to use when calling disconnect
  */
 function connect(mapping) {