react-native-onyx 1.0.13 → 1.0.16

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

@@ -63,7 +63,7 @@ The data will then be cached and stored via [`AsyncStorage`](https://github.com/
 
 We can also use `Onyx.merge()` to merge new `Object` or `Array` data in with existing data.
 
-For `Array` the default behavior is to concatenate new items.
+For `Array` the default behavior is to concatenate replace it fully, effectively making it equivalent to set:
 
 ```javascript
 Onyx.merge(ONYXKEYS.EMPLOYEE_LIST, ['Joe']); // -> ['Joe']
@@ -77,20 +77,27 @@ Onyx.merge(ONYXKEYS.POLICY, {id: 1}); // -> {id: 1}
 Onyx.merge(ONYXKEYS.POLICY, {name: 'My Workspace'}); // -> {id: 1, name: 'My Workspace'}
 ```
 
-One caveat to be aware of is that `lodash/merge` [follows the behavior of jQuery's deep extend](https://github.com/lodash/lodash/issues/2872) and will not concatenate nested arrays in objects. It might seem like this code would concat these arrays, but it does not.
+Arrays inside objects will NOT be concatenated and instead will be replaced fully, same as arrays not inside objects:
 
 ```javascript
-Onyx.merge(ONYXKEYS.POLICY, {employeeList: ['Joe']}); // -> {employeeList: ['Joe']}
+Onyx.merge(ONYXKEYS.POLICY, {employeeList: ['Joe', 'Jack']}); // -> {employeeList: ['Joe', 'Jack']}
 Onyx.merge(ONYXKEYS.POLICY, {employeeList: ['Jack']}); // -> {employeeList: ['Jack']}
 ```
 
 ### 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

@@ -1,13 +1,13 @@
 (function webpackUniversalModuleDefinition(root, factory) {
 	if(typeof exports === 'object' && typeof module === 'object')
-		module.exports = factory(require("underscore"), require("expensify-common/lib/str"), require("lodash/merge"), require("lodash/get"), require("localforage"), require("react"));
+		module.exports = factory(require("underscore"), require("expensify-common/lib/str"), require("lodash/merge"), require("lodash/mergeWith"), require("lodash/get"), require("localforage"), require("react"));
 	else if(typeof define === 'function' && define.amd)
-		define(["underscore", "expensify-common/lib/str", "lodash/merge", "lodash/get", "localforage", "react"], factory);
+		define(["underscore", "expensify-common/lib/str", "lodash/merge", "lodash/mergeWith", "lodash/get", "localforage", "react"], factory);
 	else if(typeof exports === 'object')
-		exports["react-native-onyx/web"] = factory(require("underscore"), require("expensify-common/lib/str"), require("lodash/merge"), require("lodash/get"), require("localforage"), require("react"));
+		exports["react-native-onyx/web"] = factory(require("underscore"), require("expensify-common/lib/str"), require("lodash/merge"), require("lodash/mergeWith"), require("lodash/get"), require("localforage"), require("react"));
 	else
-		root["react-native-onyx/web"] = factory(root["underscore"], root["expensify-common/lib/str"], root["lodash/merge"], root["lodash/get"], root["localforage"], root["react"]);
-})(self, (__WEBPACK_EXTERNAL_MODULE_underscore__, __WEBPACK_EXTERNAL_MODULE_expensify_common_lib_str__, __WEBPACK_EXTERNAL_MODULE_lodash_merge__, __WEBPACK_EXTERNAL_MODULE_lodash_get__, __WEBPACK_EXTERNAL_MODULE_localforage__, __WEBPACK_EXTERNAL_MODULE_react__) => {
+		root["react-native-onyx/web"] = factory(root["underscore"], root["expensify-common/lib/str"], root["lodash/merge"], root["lodash/mergeWith"], root["lodash/get"], root["localforage"], root["react"]);
+})(self, (__WEBPACK_EXTERNAL_MODULE_underscore__, __WEBPACK_EXTERNAL_MODULE_expensify_common_lib_str__, __WEBPACK_EXTERNAL_MODULE_lodash_merge__, __WEBPACK_EXTERNAL_MODULE_lodash_mergeWith__, __WEBPACK_EXTERNAL_MODULE_lodash_get__, __WEBPACK_EXTERNAL_MODULE_localforage__, __WEBPACK_EXTERNAL_MODULE_react__) => {
 return /******/ (() => { // webpackBootstrap
 /******/ 	var __webpack_modules__ = ({
 
@@ -492,11 +492,13 @@ function logInfo(message) {
 var _interopRequireDefault = __webpack_require__(/*! @babel/runtime/helpers/interopRequireDefault */ "./node_modules/@babel/runtime/helpers/interopRequireDefault.js");Object.defineProperty(exports, "__esModule", ({ value: true }));exports["default"] = void 0;var _slicedToArray2 = _interopRequireDefault(__webpack_require__(/*! @babel/runtime/helpers/slicedToArray */ "./node_modules/@babel/runtime/helpers/slicedToArray.js"));var _toConsumableArray2 = _interopRequireDefault(__webpack_require__(/*! @babel/runtime/helpers/toConsumableArray */ "./node_modules/@babel/runtime/helpers/toConsumableArray.js"));var _extends2 = _interopRequireDefault(__webpack_require__(/*! @babel/runtime/helpers/extends */ "./node_modules/@babel/runtime/helpers/extends.js"));var _defineProperty2 = _interopRequireDefault(__webpack_require__(/*! @babel/runtime/helpers/defineProperty */ "./node_modules/@babel/runtime/helpers/defineProperty.js"));var _underscore = _interopRequireDefault(__webpack_require__(/*! underscore */ "underscore"));
 var _str = _interopRequireDefault(__webpack_require__(/*! expensify-common/lib/str */ "expensify-common/lib/str"));
 var _merge = _interopRequireDefault(__webpack_require__(/*! lodash/merge */ "lodash/merge"));
+var _mergeWith = _interopRequireDefault(__webpack_require__(/*! lodash/mergeWith */ "lodash/mergeWith"));
 var _get = _interopRequireDefault(__webpack_require__(/*! lodash/get */ "lodash/get"));
 var _storage = _interopRequireDefault(__webpack_require__(/*! ./storage */ "./lib/storage/index.web.js"));
 var Logger = _interopRequireWildcard(__webpack_require__(/*! ./Logger */ "./lib/Logger.js"));
 var _OnyxCache = _interopRequireDefault(__webpack_require__(/*! ./OnyxCache */ "./lib/OnyxCache.js"));
-var _createDeferredTask = _interopRequireDefault(__webpack_require__(/*! ./createDeferredTask */ "./lib/createDeferredTask.js"));function _getRequireWildcardCache(nodeInterop) {if (typeof WeakMap !== "function") return null;var cacheBabelInterop = new WeakMap();var cacheNodeInterop = new WeakMap();return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) {return nodeInterop ? cacheNodeInterop : cacheBabelInterop;})(nodeInterop);}function _interopRequireWildcard(obj, nodeInterop) {if (!nodeInterop && obj && obj.__esModule) {return obj;}if (obj === null || typeof obj !== "object" && typeof obj !== "function") {return { default: obj };}var cache = _getRequireWildcardCache(nodeInterop);if (cache && cache.has(obj)) {return cache.get(obj);}var newObj = {};var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;for (var key in obj) {if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;if (desc && (desc.get || desc.set)) {Object.defineProperty(newObj, key, desc);} else {newObj[key] = obj[key];}}}newObj.default = obj;if (cache) {cache.set(obj, newObj);}return newObj;}
+var _createDeferredTask = _interopRequireDefault(__webpack_require__(/*! ./createDeferredTask */ "./lib/createDeferredTask.js"));
+var _customizerForMergeWith = _interopRequireDefault(__webpack_require__(/*! ./customizerForMergeWith */ "./lib/customizerForMergeWith.js"));function _getRequireWildcardCache(nodeInterop) {if (typeof WeakMap !== "function") return null;var cacheBabelInterop = new WeakMap();var cacheNodeInterop = new WeakMap();return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) {return nodeInterop ? cacheNodeInterop : cacheBabelInterop;})(nodeInterop);}function _interopRequireWildcard(obj, nodeInterop) {if (!nodeInterop && obj && obj.__esModule) {return obj;}if (obj === null || typeof obj !== "object" && typeof obj !== "function") {return { default: obj };}var cache = _getRequireWildcardCache(nodeInterop);if (cache && cache.has(obj)) {return cache.get(obj);}var newObj = {};var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;for (var key in obj) {if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;if (desc && (desc.get || desc.set)) {Object.defineProperty(newObj, key, desc);} else {newObj[key] = obj[key];}}}newObj.default = obj;if (cache) {cache.set(obj, newObj);}return newObj;}
 
 // Keeps track of the last connectionID that was used so we can keep incrementing it
 var lastConnectionID = 0;
@@ -744,8 +746,15 @@ 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) {
@@ -819,7 +828,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) {
@@ -888,7 +905,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) {
@@ -1137,7 +1154,7 @@ function applyMerge(key, data) {
   if (_underscore.default.isObject(data) || _underscore.default.every(mergeValues, _underscore.default.isObject)) {
     // Object values are merged one after the other
     return _underscore.default.reduce(mergeValues, function (modifiedData, mergeValue) {
-      var newData = (0, _merge.default)({}, modifiedData, mergeValue);
+      var newData = (0, _mergeWith.default)({}, modifiedData, mergeValue, _customizerForMergeWith.default);
 
       // We will also delete any object keys that are undefined or null.
       // Deleting keys is not supported by AsyncStorage so we do it this way.
@@ -1208,7 +1225,7 @@ function initializeWithDefaultKeyStates() {
   then(function (pairs) {
     var asObject = _underscore.default.object(pairs);
 
-    var merged = (0, _merge.default)(asObject, defaultKeyStates);
+    var merged = (0, _mergeWith.default)(asObject, defaultKeyStates, _customizerForMergeWith.default);
     _OnyxCache.default.merge(merged);
     _underscore.default.each(merged, function (val, key) {return keyChanged(key, val);});
   });
@@ -1478,7 +1495,8 @@ Onyx;exports["default"] = _default;
 /***/ ((__unused_webpack_module, exports, __webpack_require__) => {
 
 var _interopRequireDefault = __webpack_require__(/*! @babel/runtime/helpers/interopRequireDefault */ "./node_modules/@babel/runtime/helpers/interopRequireDefault.js");Object.defineProperty(exports, "__esModule", ({ value: true }));exports["default"] = void 0;var _toConsumableArray2 = _interopRequireDefault(__webpack_require__(/*! @babel/runtime/helpers/toConsumableArray */ "./node_modules/@babel/runtime/helpers/toConsumableArray.js"));var _classCallCheck2 = _interopRequireDefault(__webpack_require__(/*! @babel/runtime/helpers/classCallCheck */ "./node_modules/@babel/runtime/helpers/classCallCheck.js"));var _createClass2 = _interopRequireDefault(__webpack_require__(/*! @babel/runtime/helpers/createClass */ "./node_modules/@babel/runtime/helpers/createClass.js"));var _underscore = _interopRequireDefault(__webpack_require__(/*! underscore */ "underscore"));
-var _merge = _interopRequireDefault(__webpack_require__(/*! lodash/merge */ "lodash/merge"));
+var _mergeWith = _interopRequireDefault(__webpack_require__(/*! lodash/mergeWith */ "lodash/mergeWith"));
+var _customizerForMergeWith = _interopRequireDefault(__webpack_require__(/*! ./customizerForMergeWith */ "./lib/customizerForMergeWith.js"));
 
 var isDefined = _underscore.default.negate(_underscore.default.isUndefined);
 
@@ -1589,7 +1607,7 @@ OnyxCache = /*#__PURE__*/function () {
      * @param {Record<string, *>} data - a map of (cache) key - values
      */ }, { key: "merge", value: function merge(
     data) {var _this = this;
-      this.storageMap = (0, _merge.default)({}, this.storageMap, data);
+      this.storageMap = (0, _mergeWith.default)({}, this.storageMap, data, _customizerForMergeWith.default);
 
       var storageKeys = this.getAllKeys();
       var mergedKeys = _underscore.default.keys(data);
@@ -1760,6 +1778,36 @@ function createDeferredTask() {
 
 /***/ }),
 
+/***/ "./lib/customizerForMergeWith.js":
+/*!***************************************!*\
+  !*** ./lib/customizerForMergeWith.js ***!
+  \***************************************/
+/***/ ((__unused_webpack_module, exports, __webpack_require__) => {
+
+var _interopRequireDefault = __webpack_require__(/*! @babel/runtime/helpers/interopRequireDefault */ "./node_modules/@babel/runtime/helpers/interopRequireDefault.js");Object.defineProperty(exports, "__esModule", ({ value: true }));exports["default"] = void 0;var _underscore = _interopRequireDefault(__webpack_require__(/*! underscore */ "underscore"));
+
+/**
+ * When merging 2 objects into onyx that contain an array, we want to completely replace the array instead of the default
+ * behavior which is to merge each item by its index.
+ * ie:
+ * merge({a: [1]}, {a: [2,3]}):
+ *  - In the default implementation would produce {a:[1,3]}
+ *  - With this function would produce: {a: [2,3]}
+ * @param {*} objValue
+ * @param {*} srcValue
+ * @return {*}
+ */
+// eslint-disable-next-line rulesdir/prefer-early-return
+function customizerForMergeWith(objValue, srcValue) {
+  if (_underscore.default.isArray(objValue)) {
+    return srcValue;
+  }
+}var _default =
+
+customizerForMergeWith;exports["default"] = _default;
+
+/***/ }),
+
 /***/ "./lib/metrics/index.web.js":
 /*!**********************************!*\
   !*** ./lib/metrics/index.web.js ***!
@@ -1866,8 +1914,9 @@ var _interopRequireDefault = __webpack_require__(/*! @babel/runtime/helpers/inte
 
 var _localforage = _interopRequireDefault(__webpack_require__(/*! localforage */ "localforage"));
 var _underscore = _interopRequireDefault(__webpack_require__(/*! underscore */ "underscore"));
-var _merge = _interopRequireDefault(__webpack_require__(/*! lodash/merge */ "lodash/merge"));
-var _SyncQueue = _interopRequireDefault(__webpack_require__(/*! ../../SyncQueue */ "./lib/SyncQueue.js")); /**
+var _mergeWith = _interopRequireDefault(__webpack_require__(/*! lodash/mergeWith */ "lodash/mergeWith"));
+var _SyncQueue = _interopRequireDefault(__webpack_require__(/*! ../../SyncQueue */ "./lib/SyncQueue.js"));
+var _customizerForMergeWith = _interopRequireDefault(__webpack_require__(/*! ../../customizerForMergeWith */ "./lib/customizerForMergeWith.js")); /**
  * @file
  * The storage provider based on localforage allows us to store most anything in its
  * natural form in the underlying DB without having to stringify or de-stringify it
@@ -1884,7 +1933,7 @@ var provider = {
       return _localforage.default.getItem(key).
       then(function (existingValue) {
         var newValue = _underscore.default.isObject(existingValue) ?
-        (0, _merge.default)({}, existingValue, value) :
+        (0, _mergeWith.default)({}, existingValue, value, _customizerForMergeWith.default) :
         value;
         return _localforage.default.setItem(key, newValue);
       });
@@ -3297,6 +3346,17 @@ module.exports = __WEBPACK_EXTERNAL_MODULE_lodash_merge__;
 
 /***/ }),
 
+/***/ "lodash/mergeWith":
+/*!***********************************!*\
+  !*** external "lodash/mergeWith" ***!
+  \***********************************/
+/***/ ((module) => {
+
+"use strict";
+module.exports = __WEBPACK_EXTERNAL_MODULE_lodash_mergeWith__;
+
+/***/ }),
+
 /***/ "react":
 /*!************************!*\
   !*** external "react" ***!