react-native-onyx 1.0.12 → 1.0.15

package/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

package/README.md

@@ -86,11 +86,18 @@ Onyx.merge(ONYXKEYS.POLICY, {employeeList: ['Jack']}); // -> {employeeList: ['Ja
 
 ### Should I use `merge()` or `set()` or both?
 
-- Use `merge()` if we want to merge partial data into an existing `Array` or `Object`
-- Use `set()` if we are working with simple values (`String`, `Boolean`, etc), need to completely overwrite a complex property of an `Object`, or reset some data entirely.
+- Use `merge()` when creating a new object
+- Use `merge()` to merge partial data into an existing object
+- Use `merge()` when storing simple values (`String`, `Boolean`, `Number`)
+- Use `set()` when you need to delete an Onyx key completely from storage
+- Use `set()` when you need to completely reset an object or array of data
 
 Consecutive calls to `Onyx.merge()` with the same key are batched in a stack and processed in the order that they were called. This helps avoid race conditions where one merge possibly finishes before another. However, it's important to note that calls to `Onyx.set()` are not batched together with calls to `Onyx.merge()`. For this reason, it is usually preferable to use one or the other, but not both. Onyx is a work-in-progress so always test code to make sure assumptions are correct!
 
+### Should I store things as an array or an object?
+
+You should avoid arrays as much as possible. They do not work well with `merge()` because it can't update a single element in an array, it must always set the entire array each time. This forces you to use `set()` a lot, and as seen above, `merge()` is more performant and better to use in almost any situation. If you are working with an array of objects, then you should be using an Onyx collection because it's optimized for working with arrays of objects.
+
 ## Subscribing to data changes
 
 To set up a basic subscription for a given key use the `Onyx.connect()` method.
@@ -130,6 +137,80 @@ 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. `report_42`).
+
+```javascript
+const ONYXKEYS = {
+    COLLECTION: {
+        REPORT: 'report_',
+    },
+};
+```
+
+### Setting Collection Values
+
+To save a new collection key we can either do:
+
+```js
+Onyx.merge(`${ONYXKEYS.COLLECTION.REPORT}${report1.reportID}`, report1);
+```
+
+or we can set many at once with `mergeCollection()` (see below for guidance on best practices):
+
+```js
+Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, {
+    [`${ONYXKEYS.COLLECTION.REPORT}${report1.reportID}`]: report1,
+    [`${ONYXKEYS.COLLECTION.REPORT}${report2.reportID}`]: report2,
+    [`${ONYXKEYS.COLLECTION.REPORT}${report3.reportID}`]: report3,
+});
+```
+
+### Subscribing to Collections
+
+There are several ways to subscribe to these keys:
+
+```javascript
+withOnyx({
+    allReports: {key: ONYXKEYS.COLLECTION.REPORT},
+})(MyComponent);
+```
+
+This will add a prop to the component called `allReports` which is 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. The prop doesn't update on the initial rendering of the component until the entire collection has been read out of Onyx.
+
+```js
+Onyx.connect({key: ONYXKEYS.COLLECTION.REPORT}, callback: (memberValue, memberKey) => {...}});
+```
+
+This will fire the callback once per member key depending on how many collection member keys are currently stored. Changes to those keys after the initial callbacks fire will occur when each individual key is updated.
+
+```js
+Onyx.connect({
+    key: ONYXKEYS.COLLECTION.REPORT,
+    waitForCollectionCallback: true,
+    callback: (allReports) => {...}},
+});
+```
+
+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 `merge()` would re-render a connected component *each time it is called*. Consider this example where `reports` is an array of reports that we want to index and save.
+
+```js
+// Bad
+_.each(reports, report => Onyx.merge(`${ONYXKEYS.COLLECTION.REPORT}${report.reportID}`, report)); // -> A component using withOnyx() will have it's state updated with each iteration
+
+// Good
+const values = {};
+_.each(reports, report => values[`${ONYXKEYS.COLLECTION.REPORT}${report.reportID}`] = report);
+Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, values); // -> A component using withOnyx() will only have it's state updated once
+```
+
 ## Clean up
 
 To clear all data from `Onyx` we can use `Onyx.clear()`.

package/dist/web.development.js

@@ -744,13 +744,26 @@ function keysChanged(collectionKey, collection) {
       return;
     }
 
+    /**
+     * e.g. Onyx.connect({key: ONYXKEYS.COLLECTION.REPORT, callback: ...});
+     */
     var isSubscribedToCollectionKey = isKeyMatch(subscriber.key, collectionKey) &&
     isCollectionKey(subscriber.key);
+
+    /**
+     * e.g. Onyx.connect({key: `${ONYXKEYS.COLLECTION.REPORT}{reportID}`, callback: ...});
+     */
     var isSubscribedToCollectionMemberKey = subscriber.key.startsWith(collectionKey);
 
     if (isSubscribedToCollectionKey) {
       if (_underscore.default.isFunction(subscriber.callback)) {
         var cachedCollection = getCachedCollection(collectionKey);
+
+        if (subscriber.waitForCollectionCallback) {
+          subscriber.callback(cachedCollection);
+          return;
+        }
+
         _underscore.default.each(collection, function (data, dataKey) {
           subscriber.callback(cachedCollection[dataKey], dataKey);
         });
@@ -813,7 +826,15 @@ function keyChanged(key, data) {
     }
 
     if (_underscore.default.isFunction(subscriber.callback)) {
+      if (subscriber.waitForCollectionCallback) {
+        var cachedCollection = getCachedCollection(subscriber.key);
+        cachedCollection[key] = data;
+        subscriber.callback(cachedCollection);
+        return;
+      }
+
       subscriber.callback(data, key);
+      return;
     }
 
     if (!subscriber.withOnyxInstance) {
@@ -882,7 +903,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) {