API.md

API Reference

Functions

init()

Initialize the store with actions and listening for storage events

connect(mapping) ⇒

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

disconnect(connectionID)

Remove the listener for a react component

set(key, value)

Write a value to our store with the given key

multiSet(data)

Sets multiple keys and values

merge()

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

mergeCollection(collectionKey, collection)

Merges a collection based on their keys

clear(keysToPreserve)

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.

update(data) ⇒

Insert API responses and lifecycle data into Onyx

init()

Initialize the store with actions and listening for storage events

Kind: global function

connect(mapping) ⇒

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

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

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

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

disconnect(connectionID)

Remove the listener for a react component

Kind: global function

Param	Description
connectionID	unique id returned by call to Onyx.connect()

Example

Onyx.disconnect(connectionID);

set(key, value)

Write a value to our store with the given key

Kind: global function

Param	Description
key	ONYXKEY to set
value	value to store

multiSet(data)

Sets multiple keys and values

Kind: global function

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

Example

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

merge()

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

Kind: global function
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'}

mergeCollection(collectionKey, collection)

Merges a collection based on their keys

Kind: global function

Param	Description
collectionKey	e.g. ONYXKEYS.COLLECTION.REPORT
collection	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,
});

clear(keysToPreserve)

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	Description
keysToPreserve	is a list of ONYXKEYS that should not be cleared with the rest of the data

update(data) ⇒

Insert API responses and lifecycle data into Onyx

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

Param	Description
data	An array of objects with update expressions