Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update onyx doc #343

Merged
merged 1 commit into from
Sep 15, 2023
Merged

Update onyx doc #343

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 72 additions & 17 deletions API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

<dl>
<dt><a href="#getSubsetOfData">getSubsetOfData(sourceData, selector, [withOnyxInstanceState])</a> ⇒ <code>Mixed</code></dt>
<dd><p>Uses a selector string or function to return a simplified version of sourceData</p>
<dd><p>Uses a selector function to return a simplified version of sourceData</p>
</dd>
<dt><a href="#reduceCollectionWithSelector">reduceCollectionWithSelector(collection, selector, [withOnyxInstanceState])</a> ⇒ <code>Object</code></dt>
<dd><p>Takes a collection of items (eg. {testKey_1:{a:&#39;a&#39;}, testKey_2:{b:&#39;b&#39;}})
Expand All @@ -15,6 +15,10 @@ The resulting collection will only contain items that are returned by the select
</dd>
<dt><a href="#isCollectionMemberKey">isCollectionMemberKey(collectionKey, key)</a> ⇒ <code>Boolean</code></dt>
<dd></dd>
<dt><a href="#tryGetCachedValue">tryGetCachedValue(key, mapping)</a> ⇒ <code>Mixed</code></dt>
<dd><p>Tries to get a value from the cache. If the value is not present in cache it will return the default value or undefined.
If the requested key is a collection, it will return an object with all the collection members.</p>
</dd>
<dt><a href="#connect">connect(mapping)</a> ⇒ <code>Number</code></dt>
<dd><p>Subscribes a react component&#39;s state directly to a store key</p>
</dd>
Expand All @@ -32,18 +36,21 @@ behavior just yet.</p>
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>
<dd><p>Notifys subscribers and writes current value to cache</p>
</dd>
<dt><a href="#hasPendingMergeForKey">hasPendingMergeForKey(key)</a> ⇒ <code>Boolean</code></dt>
<dd></dd>
<dt><a href="#set">set(key, value)</a> ⇒ <code>Promise</code></dt>
<dd><p>Write a value to our store with the given key</p>
</dd>
<dt><a href="#multiSet">multiSet(data)</a> ⇒ <code>Promise</code></dt>
<dd><p>Sets multiple keys and values</p>
</dd>
<dt><a href="#merge">merge(key, value)</a> ⇒ <code>Promise</code></dt>
<dt><a href="#merge">merge(key, changes)</a> ⇒ <code>Promise</code></dt>
<dd><p>Merge a new value into an existing value at a key.</p>
<p>The types of values that can be merged are <code>Object</code> and <code>Array</code>. To set another type of value use <code>Onyx.set()</code>. Merge
behavior uses lodash/merge under the hood for <code>Object</code> and simple concatenation for <code>Array</code>. However, it&#39;s important
to note that if you have an array value property on an <code>Object</code> that the default behavior of lodash/merge is not to
concatenate. See here: <a href="https://github.com/lodash/lodash/issues/2872">https://github.com/lodash/lodash/issues/2872</a></p>
<p>The types of values that can be merged are <code>Object</code> and <code>Array</code>. To set another type of value use <code>Onyx.set()</code>.
Values of type <code>Object</code> get merged with the old value, whilst for <code>Array</code>&#39;s we simply replace the current value with the new one.</p>
<p>Calls to <code>Onyx.merge()</code> are batched so that any calls performed in a single tick will stack in a queue and get
applied in the order they were called. Note: <code>Onyx.set()</code> calls do not work this way so use caution when mixing
<code>Onyx.merge()</code> and <code>Onyx.set()</code>.</p>
Expand All @@ -70,6 +77,9 @@ value will be saved to storage after the default value.</p>
<dt><a href="#update">update(data)</a> ⇒ <code>Promise</code></dt>
<dd><p>Insert API responses and lifecycle data into Onyx</p>
</dd>
<dt><a href="#setMemoryOnlyKeys">setMemoryOnlyKeys(keyList)</a></dt>
<dd><p>When set these keys will not be persisted to storage</p>
</dd>
<dt><a href="#init">init([options])</a></dt>
<dd><p>Initialize the store with actions and listening for storage events</p>
</dd>
Expand All @@ -78,15 +88,15 @@ value will be saved to storage after the default value.</p>
<a name="getSubsetOfData"></a>

## getSubsetOfData(sourceData, selector, [withOnyxInstanceState]) ⇒ <code>Mixed</code>
Uses a selector string or function to return a simplified version of sourceData
Uses a selector function to return a simplified version of sourceData

**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| sourceData | <code>Mixed</code> | |
| selector | <code>String</code> \| <code>function</code> | |
| [withOnyxInstanceState] | <code>Object</code> | If it's a string, the selector is passed to lodashGet on the sourceData If it's a function, it is passed the sourceData and it should return the simplified data |
| selector | <code>function</code> | Function that takes sourceData and returns a simplified version of it |
| [withOnyxInstanceState] | <code>Object</code> | |

<a name="reduceCollectionWithSelector"></a>

Expand All @@ -113,6 +123,19 @@ The resulting collection will only contain items that are returned by the select
| collectionKey | <code>String</code> |
| key | <code>String</code> |

<a name="tryGetCachedValue"></a>

## tryGetCachedValue(key, mapping) ⇒ <code>Mixed</code>
Tries to get a value from the cache. If the value is not present in cache it will return the default value or undefined.
If the requested key is a collection, it will return an object with all the collection members.

**Kind**: global function

| Param | Type |
| --- | --- |
| key | <code>String</code> |
| mapping | <code>Object</code> |

<a name="connect"></a>

## connect(mapping) ⇒ <code>Number</code>
Expand All @@ -130,7 +153,7 @@ Subscribes a react component's state directly to a store key
| [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 |
| [mapping.selector] | <code>String</code> \| <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. If the selector is a string, the selector is passed to lodashGet on the sourceData. If the selector is a function, 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.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). |

**Example**
```js
Expand Down Expand Up @@ -189,6 +212,29 @@ subscriber callbacks receive the data in a different format than they normally e
| key | <code>String</code> |
| value | <code>\*</code> |

<a name="broadcastUpdate"></a>

## broadcastUpdate(key, value, hasChanged, method)
Notifys subscribers and writes current value to cache

**Kind**: global function

| Param | Type |
| --- | --- |
| key | <code>String</code> |
| value | <code>\*</code> |
| hasChanged | <code>Boolean</code> |
| method | <code>String</code> |

<a name="hasPendingMergeForKey"></a>

## hasPendingMergeForKey(key) ⇒ <code>Boolean</code>
**Kind**: global function

| Param | Type |
| --- | --- |
| key | <code>String</code> |

<a name="set"></a>

## set(key, value) ⇒ <code>Promise</code>
Expand Down Expand Up @@ -218,13 +264,11 @@ Onyx.multiSet({'key1': 'a', 'key2': 'b'});
```
<a name="merge"></a>

## merge(key, value) ⇒ <code>Promise</code>
## merge(key, changes) ⇒ <code>Promise</code>
Merge a new value into an existing value at a key.

The types of values that can be merged are `Object` and `Array`. To set another type of value use `Onyx.set()`. Merge
behavior uses lodash/merge under the hood for `Object` and simple concatenation for `Array`. However, it's important
to note that if you have an array value property on an `Object` that the default behavior of lodash/merge is not to
concatenate. See here: https://github.com/lodash/lodash/issues/2872
The types of values that can be merged are `Object` and `Array`. To set another type of value use `Onyx.set()`.
Values of type `Object` get merged with the old value, whilst for `Array`'s we simply replace the current value with the new one.

Calls to `Onyx.merge()` are batched so that any calls performed in a single tick will stack in a queue and get
applied in the order they were called. Note: `Onyx.set()` calls do not work this way so use caution when mixing
Expand All @@ -235,7 +279,7 @@ applied in the order they were called. Note: `Onyx.set()` calls do not work this
| Param | Type | Description |
| --- | --- | --- |
| key | <code>String</code> | ONYXKEYS key |
| value | <code>Object</code> \| <code>Array</code> | Object or Array value to merge |
| changes | <code>Object</code> \| <code>Array</code> | Object or Array value to merge |

**Example**
```js
Expand Down Expand Up @@ -300,7 +344,18 @@ Insert API responses and lifecycle data into Onyx

| Param | Type | Description |
| --- | --- | --- |
| data | <code>Array</code> | An array of objects with shape {onyxMethod: oneOf('set', 'merge', 'mergeCollection'), key: string, value: *} |
| data | <code>Array</code> | An array of objects with shape {onyxMethod: oneOf('set', 'merge', 'mergeCollection', 'multiSet', 'clear'), key: string, value: *} |

<a name="setMemoryOnlyKeys"></a>

## setMemoryOnlyKeys(keyList)
When set these keys will not be persisted to storage

**Kind**: global function

| Param | Type |
| --- | --- |
| keyList | <code>Array.&lt;string&gt;</code> |

<a name="init"></a>

Expand Down