API.md

API Reference

Functions

init()

Initialize the store with actions and listening for storage events

connect(connectOptions) ⇒

Connects to an Onyx key given the options passed and listens to its changes.

disconnect(connection)

Disconnects and removes the listener from the Onyx key.

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(connectOptions) ⇒

Connects to an Onyx key given the options passed and listens to its changes.

Kind: global function
Returns: The connection object to use when calling Onyx.disconnect().

Param	Description
connectOptions	The options object that will define the behavior of the connection.
connectOptions.key	The Onyx key to subscribe to.
connectOptions.callback	A function that will be called when the Onyx data we are subscribed changes.
connectOptions.waitForCollectionCallback	If set to true, it will return the entire collection to the callback as a single object.
connectOptions.withOnyxInstance	The withOnyx class instance to be internally passed. Only used inside withOnyx() HOC.
connectOptions.statePropertyName	The name of the component's prop that is connected to the Onyx key. Only used inside withOnyx() HOC.
connectOptions.displayName	The component's display name. Only used inside withOnyx() HOC.
connectOptions.selector	This will be used to subscribe to a subset of an Onyx key's data. Only used inside useOnyx() hook or withOnyx() HOC. Using this setting on useOnyx() or 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 connection = Onyx.connect({
    key: ONYXKEYS.SESSION,
    callback: onSessionChange,
});

disconnect(connection)

Disconnects and removes the listener from the Onyx key.

Kind: global function

Param	Description
connection	Connection object returned by calling Onyx.connect().

Example

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

Onyx.disconnect(connection);

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