react-native-onyx 1.0.81 → 1.0.83

package/API.md

@@ -25,18 +25,21 @@ If the requested key is a collection, it will return an object with all the coll
 <dt><a href="#disconnect">disconnect(connectionID, [keyToRemoveFromEvictionBlocklist])</a></dt>
 <dd><p>Remove the listener for a react component</p>
 </dd>
-<dt><a href="#notifySubscribersOnNextTick">notifySubscribersOnNextTick(key, value, [canUpdateSubscriber])</a></dt>
-<dd><p>This method mostly exists for historical reasons as this library was initially designed without a memory cache and one was added later.
-For this reason, Onyx works more similar to what you might expect from a native AsyncStorage with reads, writes, etc all becoming
-available async. Since we have code in our main applications that might expect things to work this way it&#39;s not safe to change this
-behavior just yet.</p>
+<dt><a href="#maybeFlushBatchUpdates">maybeFlushBatchUpdates()</a> ⇒ <code>Promise</code></dt>
+<dd><p>We are batching together onyx updates. This helps with use cases where we schedule onyx updates after each other.
+This happens for example in the Onyx.update function, where we process API responses that might contain a lot of
+update operations. Instead of calling the subscribers for each update operation, we batch them together which will
+cause react to schedule the updates at once instead of after each other. This is mainly a performance optimization.</p>
 </dd>
-<dt><a href="#notifyCollectionSubscribersOnNextTick">notifyCollectionSubscribersOnNextTick(key, value)</a></dt>
+<dt><a href="#scheduleSubscriberUpdate">scheduleSubscriberUpdate(key, value, [canUpdateSubscriber])</a> ⇒ <code>Promise</code></dt>
+<dd><p>Schedules an update that will be appended to the macro task queue (so it doesn&#39;t update the subscribers immediately).</p>
+</dd>
+<dt><a href="#scheduleNotifyCollectionSubscribers">scheduleNotifyCollectionSubscribers(key, value)</a> ⇒ <code>Promise</code></dt>
 <dd><p>This method is similar to notifySubscribersOnNextTick but it is built for working specifically with collections
 so that keysChanged() is triggered for the collection and not keyChanged(). If this was not done, then the
 subscriber callbacks receive the data in a different format than they normally expect and it breaks code.</p>
 </dd>
-<dt><a href="#broadcastUpdate">broadcastUpdate(key, value, hasChanged, method)</a></dt>
+<dt><a href="#broadcastUpdate">broadcastUpdate(key, value, hasChanged, method)</a> ⇒ <code>Promise</code></dt>
 <dd><p>Notifys subscribers and writes current value to cache</p>
 </dd>
 <dt><a href="#hasPendingMergeForKey">hasPendingMergeForKey(key)</a> ⇒ <code>Boolean</code></dt>
@@ -154,6 +157,7 @@ Subscribes a react component's state directly to a store key
 | [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 |
 | [mapping.selector] | <code>function</code> | THIS PARAM IS ONLY USED WITH withOnyx(). If included, this will be used to subscribe to a subset of an Onyx key's data.       The sourceData and withOnyx state are passed to the selector and should return the simplified data. Using this setting on `withOnyx` can have very positive       performance benefits because the component will only re-render when the subset of data changes. Otherwise, any change of data on any property would normally       cause the component to re-render (and that can be expensive from a performance standpoint). |
+| [mapping.initialValue] | <code>String</code> \| <code>Number</code> \| <code>Boolean</code> \| <code>Object</code> | THIS PARAM IS ONLY USED WITH withOnyx(). If included, this will be passed to the component so that something can be rendered while data is being fetched from the DB. Note that it will not cause the component to have the loading prop set to true. | |
 
 **Example**  
 ```js
@@ -178,13 +182,19 @@ Remove the listener for a react component
 ```js
 Onyx.disconnect(connectionID);
 ```
-<a name="notifySubscribersOnNextTick"></a>
+<a name="maybeFlushBatchUpdates"></a>
+
+## maybeFlushBatchUpdates() ⇒ <code>Promise</code>
+We are batching together onyx updates. This helps with use cases where we schedule onyx updates after each other.
+This happens for example in the Onyx.update function, where we process API responses that might contain a lot of
+update operations. Instead of calling the subscribers for each update operation, we batch them together which will
+cause react to schedule the updates at once instead of after each other. This is mainly a performance optimization.
+
+**Kind**: global function  
+<a name="scheduleSubscriberUpdate"></a>
 
-## notifySubscribersOnNextTick(key, value, [canUpdateSubscriber])
-This method mostly exists for historical reasons as this library was initially designed without a memory cache and one was added later.
-For this reason, Onyx works more similar to what you might expect from a native AsyncStorage with reads, writes, etc all becoming
-available async. Since we have code in our main applications that might expect things to work this way it's not safe to change this
-behavior just yet.
+## scheduleSubscriberUpdate(key, value, [canUpdateSubscriber]) ⇒ <code>Promise</code>
+Schedules an update that will be appended to the macro task queue (so it doesn't update the subscribers immediately).
 
 **Kind**: global function  
 
@@ -196,11 +206,11 @@ behavior just yet.
 
 **Example**  
 ```js
-notifySubscribersOnNextTick(key, value, subscriber => subscriber.initWithStoredValues === false)
+scheduleSubscriberUpdate(key, value, subscriber => subscriber.initWithStoredValues === false)
 ```
-<a name="notifyCollectionSubscribersOnNextTick"></a>
+<a name="scheduleNotifyCollectionSubscribers"></a>
 
-## notifyCollectionSubscribersOnNextTick(key, value)
+## scheduleNotifyCollectionSubscribers(key, value) ⇒ <code>Promise</code>
 This method is similar to notifySubscribersOnNextTick but it is built for working specifically with collections
 so that keysChanged() is triggered for the collection and not keyChanged(). If this was not done, then the
 subscriber callbacks receive the data in a different format than they normally expect and it breaks code.
@@ -214,7 +224,7 @@ subscriber callbacks receive the data in a different format than they normally e
 
 <a name="broadcastUpdate"></a>
 
-## broadcastUpdate(key, value, hasChanged, method)
+## broadcastUpdate(key, value, hasChanged, method) ⇒ <code>Promise</code>
 Notifys subscribers and writes current value to cache
 
 **Kind**: global function  

package/README.md

@@ -135,7 +135,74 @@ export default withOnyx({
 })(App);
 ```
 
-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.
+While `Onyx.connect()` gives you more control on how your component reacts as data is fetched from disk, `withOnyx()` will delay the rendering of the wrapped component until all keys/entities have been fetched and passed to the component, this can be convenient for simple cases. This however, can really delay your application if many entities are connected to the same component, you can pass an `initialValue` to each key to allow Onyx to eagerly render your component with this value.
+
+```javascript
+export default withOnyx({
+    session: {
+        key: ONYXKEYS.SESSION,
+        initialValue: {}
+    },
+})(App);
+```
+
+Additionally, if your component has many keys/entities when your component will mount but will receive many updates as data is fetched from DB and passed down to it, as every key that gets fetched will trigger a `setState` on the `withOnyx` HOC. This might cause re-renders on the initial mounting, preventing the component from mounting/rendering in reasonable time, making your app feel slow and even delaying animations. You can workaround this by passing an additional object with the `shouldDelayUpdates` property set to true. Onyx will then put all the updates in a queue until you decide when then should be applied, the component will receive a function `markReadyForHydration`. A good place to call this function is on the `onLayout` method, which gets triggered after your component has been rendered.
+
+```javascript
+const App = ({session, markReadyForHydration}) => (
+    <View onLayout={() => markReadyForHydration()}>
+        {session.token ? <Text>Logged in</Text> : <Text>Logged out</Text> }
+    </View>
+);
+
+// Second argument to funciton is `shouldDelayUpdates`
+export default withOnyx({
+    session: {
+        key: ONYXKEYS.SESSION,
+        initialValue: {}
+    },
+}, true)(App);
+```
+
+### Dependent Onyx Keys and withOnyx()
+Some components need to subscribe to multiple Onyx keys at once and sometimes, one key might rely on the data from another key. This is similar to a JOIN in SQL.
+
+Example: To get the policy of a report, the `policy` key depends on the `report` key.
+
+```javascript
+export default withOnyx({
+    report: {
+        key: ({reportID) => `${ONYXKEYS.COLLECTION.REPORT}${reportID}`,
+    },
+    policy: {
+        key: ({report}) => `${ONYXKEYS.COLLECTION.POLICY}${report.policyID}`,
+    },
+})(App);
+```
+
+Background info:
+- The `key` value can be a function that returns the key that Onyx subscribes to
+- The first argument to the `key` function is the `props` from the component
+
+**Detailed explanation of how this is handled and rendered:**
+1. The component mounts with a `reportID={1234}` prop
+2. `withOnyx` evaluates the mapping
+3. `withOnyx` connects to the key `reports_1234` because of the prop passed to the component
+3. `withOnyx` connects to the key `policies_undefined` because `report` doesn't exist in the props yet, so the `policyID` defaults to `undefined`. * (see note below)
+4. Onyx reads the data and updates the state of `withOnyx` with:
+    - `report={{reportID: 1234, policyID: 1, ... the rest of the object ...}}`
+    - `policy={undefined}` (since there is no policy with ID `undefined`)
+5. There is still an `undefined` key in the mapping, so Onyx reads the data again
+6. This time `withOnyx` connects to the key `policies_1` because the `report` object exists in the component's state and it has a `policyID: 1`
+7. Onyx reads the data and updates the state of withOnyx with:
+    - `policy={{policyID: 1, ... the rest of the object ...}`
+8. Now all mappings have values that are defined (not undefined) and the component is rendered with all necessary data
+  
+* It is VERY important to NOT use empty string default values like `report.policyID || ''`. This results in the key returned to `withOnyx` as `policies_` which subscribes to the ENTIRE POLICY COLLECTION and is most assuredly not what you were intending. You can use a default of `0` (as long as you are reasonably sure that there is never a policyID=0). This allows Onyx to return `undefined` as the value of the policy key, which is handled by `withOnyx` appropriately.
+
+DO NOT use more than one `withOnyx` component at a time. It adds overhead and prevents some optimizations like batched rendering from working to its full potential.
+
+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).
 
 ## Collections