Skip to content

Latest commit

 

History

History
329 lines (265 loc) · 15.2 KB

API.md

File metadata and controls

329 lines (265 loc) · 15.2 KB

API Reference

Functions

getSubsetOfData(sourceData, selector) ⇒ Mixed

Uses a selector string or function to return a simplified version of sourceData

reduceCollectionWithSelector(collection, selector) ⇒ Object

Takes a collection of items (eg. {testKey_1:{a:'a'}, testKey_2:{b:'b'}}) and runs it through a reducer function to return a subset of the data according to a selector. The resulting collection will only contain items that are returned by the selector.

isCollectionMemberKey(collectionKey, key) ⇒ Boolean
connect(mapping) ⇒ Number

Subscribes a react component's state directly to a store key

disconnect(connectionID, [keyToRemoveFromEvictionBlocklist])

Remove the listener for a react component

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.

notifyCollectionSubscribersOnNextTick(key, value)

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.

set(key, value) ⇒ Promise

Write a value to our store with the given key

multiSet(data) ⇒ Promise

Sets multiple keys and values

merge(key, value) ⇒ Promise

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: lodash/lodash#2872

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 Onyx.merge() and Onyx.set().

clear(keysToPreserve) ⇒ Promise.<void>

Clear out all the data in the store

Note that calling Onyx.clear() and then Onyx.set() on a key with a default key state may store an unexpected value in Storage.

E.g. Onyx.clear(); Onyx.set(ONYXKEYS.DEFAULT_KEY, 'default'); Storage.getItem(ONYXKEYS.DEFAULT_KEY) .then((storedValue) => console.log(storedValue)); null is logged instead of the expected 'default'

Onyx.set() might call Storage.setItem() before Onyx.clear() calls Storage.setItem(). Use Onyx.merge() instead if possible. Onyx.merge() calls Onyx.get(key) before calling Storage.setItem() via Onyx.set(). Storage.setItem() from Onyx.clear() will have already finished and the merged value will be saved to storage after the default value.

mergeCollection(collectionKey, collection) ⇒ Promise

Merges a collection based on their keys

update(data) ⇒ Promise

Insert API responses and lifecycle data into Onyx

init([options])

Initialize the store with actions and listening for storage events

getSubsetOfData(sourceData, selector) ⇒ Mixed

Uses a selector string or function to return a simplified version of sourceData

Kind: global function

Param Type Description
sourceData Mixed
selector String | function 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

reduceCollectionWithSelector(collection, selector) ⇒ Object

Takes a collection of items (eg. {testKey_1:{a:'a'}, testKey_2:{b:'b'}}) and runs it through a reducer function to return a subset of the data according to a selector. The resulting collection will only contain items that are returned by the selector.

Kind: global function

Param Type Description
collection Object
selector String | function (see method docs for getSubsetOfData() for full details)

isCollectionMemberKey(collectionKey, key) ⇒ Boolean

Kind: global function

Param Type
collectionKey String
key String

connect(mapping) ⇒ Number

Subscribes a react component's state directly to a store key

Kind: global function
Returns: Number - an ID to use when calling disconnect

Param Type Description
mapping Object the mapping information to connect Onyx to the components state
mapping.key String ONYXKEY to subscribe to
[mapping.statePropertyName] String the name of the property in the state to connect the data to
[mapping.withOnyxInstance] Object whose setState() method will be called with any changed data This is used by React components to connect to Onyx
[mapping.callback] function a method that will be called with changed data This is used by any non-React code to connect to Onyx
[mapping.initWithStoredValues] Boolean If set to false, then no data will be prefilled into the component
[mapping.waitForCollectionCallback] Boolean If set to true, it will return the entire collection to the callback as a single object
[mapping.selector] String | function 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 is 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

const connectionID = Onyx.connect({
    key: ONYXKEYS.SESSION,
    callback: onSessionChange,
});

disconnect(connectionID, [keyToRemoveFromEvictionBlocklist])

Remove the listener for a react component

Kind: global function

Param Type Description
connectionID Number unique id returned by call to Onyx.connect()
[keyToRemoveFromEvictionBlocklist] String

Example

Onyx.disconnect(connectionID);

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.

Kind: global function

Param Type Description
key String
value *
[canUpdateSubscriber] function only subscribers that pass this truth test will be updated

Example

notifySubscribersOnNextTick(key, value, subscriber => subscriber.initWithStoredValues === false)

notifyCollectionSubscribersOnNextTick(key, value)

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.

Kind: global function

Param Type
key String
value *

set(key, value) ⇒ Promise

Write a value to our store with the given key

Kind: global function

Param Type Description
key String ONYXKEY to set
value * value to store

multiSet(data) ⇒ Promise

Sets multiple keys and values

Kind: global function

Param Type Description
data Object object keyed by ONYXKEYS and the values to set

Example

Onyx.multiSet({'key1': 'a', 'key2': 'b'});

merge(key, value) ⇒ Promise

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: lodash/lodash#2872

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 Onyx.merge() and Onyx.set().

Kind: global function

Param Type Description
key String ONYXKEYS key
value Object | Array Object or Array value to merge

Example

Onyx.merge(ONYXKEYS.EMPLOYEE_LIST, ['Joe']); // -> ['Joe']
Onyx.merge(ONYXKEYS.EMPLOYEE_LIST, ['Jack']); // -> ['Joe', 'Jack']
Onyx.merge(ONYXKEYS.POLICY, {id: 1}); // -> {id: 1}
Onyx.merge(ONYXKEYS.POLICY, {name: 'My Workspace'}); // -> {id: 1, name: 'My Workspace'}

clear(keysToPreserve) ⇒ Promise.<void>

Clear out all the data in the store

Note that calling Onyx.clear() and then Onyx.set() on a key with a default key state may store an unexpected value in Storage.

E.g. Onyx.clear(); Onyx.set(ONYXKEYS.DEFAULT_KEY, 'default'); Storage.getItem(ONYXKEYS.DEFAULT_KEY) .then((storedValue) => console.log(storedValue)); null is logged instead of the expected 'default'

Onyx.set() might call Storage.setItem() before Onyx.clear() calls Storage.setItem(). Use Onyx.merge() instead if possible. Onyx.merge() calls Onyx.get(key) before calling Storage.setItem() via Onyx.set(). Storage.setItem() from Onyx.clear() will have already finished and the merged value will be saved to storage after the default value.

Kind: global function

Param Type Description
keysToPreserve Array is a list of ONYXKEYS that should not be cleared with the rest of the data

mergeCollection(collectionKey, collection) ⇒ Promise

Merges a collection based on their keys

Kind: global function

Param Type Description
collectionKey String e.g. ONYXKEYS.COLLECTION.REPORT
collection Object Object collection keyed by individual collection member keys and values

Example

Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, {
    [`${ONYXKEYS.COLLECTION.REPORT}1`]: report1,
    [`${ONYXKEYS.COLLECTION.REPORT}2`]: report2,
});

update(data) ⇒ Promise

Insert API responses and lifecycle data into Onyx

Kind: global function
Returns: Promise - resolves when all operations are complete

Param Type Description
data Array An array of objects with shape {onyxMethod: oneOf('set', 'merge', 'mergeCollection'), key: string, value: *}

init([options])

Initialize the store with actions and listening for storage events

Kind: global function

Param Type Default Description
[options] Object {} config object
[options.keys] Object {} ONYXKEYS constants object
[options.initialKeyStates] Object {} initial data to set when init() and clear() is called
[options.safeEvictionKeys] Array.<String> [] This is an array of keys (individual or collection patterns) that when provided to Onyx are flagged as "safe" for removal. Any components subscribing to these keys must also implement a canEvict option. See the README for more info.
[options.maxCachedKeysCount] Number 55 Sets how many recent keys should we try to keep in cache Setting this to 0 would practically mean no cache We try to free cache when we connect to a safe eviction key
[options.captureMetrics] Boolean Enables Onyx benchmarking and exposes the get/print/reset functions
[options.shouldSyncMultipleInstances] Boolean Auto synchronize storage events between multiple instances of Onyx running in different tabs/windows. Defaults to true for platforms that support local storage (web/desktop)
[options.debugSetState] Boolean Enables debugging setState() calls to connected components.

Example

Onyx.init({
    keys: ONYXKEYS,
    initialKeyStates: {
        [ONYXKEYS.SESSION]: {loading: false},
    },
});