- DISK_PRESSURE_LOG_INTERVAL_MS
Minimum interval between disk-pressure alerts. One disk-pressure burst fails every queued operation with the identical error, so per-operation logging would amplify the very storm it reports.
- NOT_DELIVERED
Sentinel for "nothing delivered yet" in
connect()'s per-subscription dedup. A Symbol can't collide with any real Onyx value, so the firstObject.ischeck never matches and the initial fire runs even when a key's genuine first value isundefined. It only needs to be distinct from real values, not unique per subscription, so one module-level instance is reused by every connection.
- resetDiskPressureLogThrottle()
Test-only: clears the disk-pressure log throttle so each test observes its own alert.
- getMergeQueue()
Getter - returns the merge queue.
- getMergeQueuePromise()
Getter - returns the merge queue promise.
- getDefaultKeyStates()
Getter - returns the default key states.
- getDeferredInitTask()
Getter - returns the deffered init task.
- afterInit(action) ⇒
Executes an action after Onyx has been initialized. If Onyx is already initialized, the action is executed immediately. Otherwise, it waits for initialization to complete before executing.
- getSkippableCollectionMemberIDs()
Getter - returns the skippable collection member IDs.
- getSnapshotMergeKeys()
Getter - returns the snapshot merge keys allowlist.
- setSkippableCollectionMemberIDs()
Setter - sets the skippable collection member IDs.
- setSnapshotMergeKeys()
Setter - sets the snapshot merge keys allowlist.
- initStoreValues(keys, initialKeyStates, evictableKeys)
Sets the initial values for the Onyx store
- reduceCollectionWithSelector()
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.
- get()
Get some data from the store
- tupleGet()
This helper exists to map an array of Onyx keys such as
['report_', 'conciergeReportID']to the values for those keys (correctly typed) such as[OnyxCollection<Report>, OnyxEntry<string>]Note: just using
.map, you'd end up withArray<OnyxCollection<Report>|OnyxEntry<string>>, which is not what we want. This preserves the order of the keys provided.- getAllKeys()
Returns current key names stored in persisted storage
- notifyKey()
Notify subscribers of a single-key write. Wrapper over
onyxSubscriptionManager.notifyKey()that also performs LRU bookkeeping for eviction.- notifyCollection()
Notify subscribers of a batch collection update. Wrapper over
onyxSubscriptionManager.notifyCollection()that also performs LRU bookkeeping per changed member.- remove()
Remove a key from Onyx and update the subscribers.
- retryOperation()
Handles storage operation failures based on the error class (see lib/storage/errors.ts). The connection layer (createStore) owns connection/transport recovery; this operation layer owns capacity recovery (eviction) so that a given failure is retried by exactly one layer:
- INVALID_DATA: logs an alert and throws (the same data will always fail).
- TRANSIENT / FATAL: the connection layer already retried (transient) or spent a heal attempt (fatal). Retrying here would only re-amplify, so we skip the write quietly.
- CAPACITY: evicts the least recently accessed evictable key and retries, under a session-level circuit breaker (see lib/StorageCircuitBreaker.ts) that halts the loop once eviction stops making progress or failures storm — the per-operation budget alone cannot stop a session-wide storm.
- DISK_PRESSURE: the device disk itself is full (or the database files are unreadable), so neither retries nor in-DB eviction can free space — the write is dropped (cache stays authoritative) with a single throttled alert + quota snapshot per burst.
- UNAVAILABLE: the storage engine does not exist in this environment or its heal budget ran out, so the storage layer has already degraded to the in-memory provider. No retry.
- UNKNOWN: the provider couldn't classify it — log the full error shape (name + message + provider) once so it's visible, then bounded retry without eviction.
- broadcastUpdate()
Notifies subscribers and writes current value to cache
- prepareKeyValuePairsForStorage()
Storage expects array like: [["@MyApp_user", value_1], ["@MyApp_key", value_2]] This method transforms an object like {'@MyApp_user': myUserValue, '@MyApp_key': myKeyValue} to an array of key-value pairs in the above format, and collects the keys of null values into
keysToRemovefor the caller to delete as one batch (cache drop + notification + batched storage removal).- mergeChanges(changes, existingValue)
Merges an array of changes with an existing value or creates a single change.
- mergeAndMarkChanges(changes, existingValue)
Merges an array of changes with an existing value or creates a single change. It will also mark deep nested objects that need to be entirely replaced during the merge.
- mergeInternal(changes, existingValue)
Merges an array of changes with an existing value or creates a single change.
- initializeWithDefaultKeyStates()
Merge user provided default key value pairs.
- isValidNonEmptyCollectionForMerge()
Validate the collection is not empty and has a correct type before applying mergeCollection()
- doAllCollectionItemsBelongToSameParent()
Verify if all the collection keys belong to the same parent
- setWithRetry(params, retryAttempt)
Writes a value to our store with the given key. Serves as core implementation for
Onyx.set()public function, the difference being that this internal function allows passing an additionalretryAttemptparameter to retry on failure.- multiSetWithRetry(data, retryAttempt)
Sets multiple keys and values. Serves as core implementation for
Onyx.multiSet()public function, the difference being that this internal function allows passing an additionalretryAttemptparameter to retry on failure.- setCollectionWithRetry(params, retryAttempt)
Sets a collection by replacing all existing collection members with new values. Any existing collection members not included in the new data will be removed. Serves as core implementation for
Onyx.setCollection()public function, the difference being that this internal function allows passing an additionalretryAttemptparameter to retry on failure.- mergeCollectionWithPatches(params, retryAttempt)
Merges a collection based on their keys. Serves as core implementation for
Onyx.mergeCollection()public function, the difference being that this internal function allows passing an additionalmergeReplaceNullPatchesparameter and retries on failure.- partialSetCollection(params, retryAttempt)
Sets keys in a collection by replacing all targeted collection members with new values. Any existing collection members not included in the new data will not be removed. Retries on failure.
- resetDeferredInitTask()
Put Onyx back to "not initialised" state, useful for tests that need a cold start.
- clearOnyxUtilsInternals()
Clear internal variables used in this file, useful in test environments.
Minimum interval between disk-pressure alerts. One disk-pressure burst fails every queued operation with the identical error, so per-operation logging would amplify the very storm it reports.
Sentinel for "nothing delivered yet" in connect()'s per-subscription dedup. A Symbol
can't collide with any real Onyx value, so the first Object.is check never matches and
the initial fire runs even when a key's genuine first value is undefined. It only needs
to be distinct from real values, not unique per subscription, so one module-level instance
is reused by every connection.
Test-only: clears the disk-pressure log throttle so each test observes its own alert.
Getter - returns the merge queue.
Getter - returns the merge queue promise.
Getter - returns the default key states.
Getter - returns the deffered init task.
Executes an action after Onyx has been initialized. If Onyx is already initialized, the action is executed immediately. Otherwise, it waits for initialization to complete before executing.
Kind: global function
Returns: The result of the action
| Param | Description |
|---|---|
| action | The action to execute after initialization |
Getter - returns the skippable collection member IDs.
Getter - returns the snapshot merge keys allowlist.
Setter - sets the skippable collection member IDs.
Setter - sets the snapshot merge keys allowlist.
Sets the initial values for the Onyx store
Kind: global function
| Param | Description |
|---|---|
| keys | ONYXKEYS constants object from Onyx.init() |
| initialKeyStates | initial data to set when init() and clear() are called |
| evictableKeys | This is an array of keys (individual or collection patterns) that when provided to Onyx are flagged as "safe" for removal. |
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.
Get some data from the store
This helper exists to map an array of Onyx keys such as ['report_', 'conciergeReportID']
to the values for those keys (correctly typed) such as [OnyxCollection<Report>, OnyxEntry<string>]
Note: just using .map, you'd end up with Array<OnyxCollection<Report>|OnyxEntry<string>>, which is not what we want. This preserves the order of the keys provided.
Returns current key names stored in persisted storage
Notify subscribers of a single-key write. Wrapper over onyxSubscriptionManager.notifyKey()
that also performs LRU bookkeeping for eviction.
Notify subscribers of a batch collection update. Wrapper over
onyxSubscriptionManager.notifyCollection() that also performs LRU bookkeeping per
changed member.
Remove a key from Onyx and update the subscribers.
Handles storage operation failures based on the error class (see lib/storage/errors.ts). The connection layer (createStore) owns connection/transport recovery; this operation layer owns capacity recovery (eviction) so that a given failure is retried by exactly one layer:
- INVALID_DATA: logs an alert and throws (the same data will always fail).
- TRANSIENT / FATAL: the connection layer already retried (transient) or spent a heal attempt (fatal). Retrying here would only re-amplify, so we skip the write quietly.
- CAPACITY: evicts the least recently accessed evictable key and retries, under a session-level circuit breaker (see lib/StorageCircuitBreaker.ts) that halts the loop once eviction stops making progress or failures storm — the per-operation budget alone cannot stop a session-wide storm.
- DISK_PRESSURE: the device disk itself is full (or the database files are unreadable), so neither retries nor in-DB eviction can free space — the write is dropped (cache stays authoritative) with a single throttled alert + quota snapshot per burst.
- UNAVAILABLE: the storage engine does not exist in this environment or its heal budget ran out, so the storage layer has already degraded to the in-memory provider. No retry.
- UNKNOWN: the provider couldn't classify it — log the full error shape (name + message + provider) once so it's visible, then bounded retry without eviction.
Notifies subscribers and writes current value to cache
Storage expects array like: [["@MyApp_user", value_1], ["@MyApp_key", value_2]]
This method transforms an object like {'@MyApp_user': myUserValue, '@MyApp_key': myKeyValue}
to an array of key-value pairs in the above format, and collects the keys of null values into
keysToRemove for the caller to delete as one batch (cache drop + notification + batched storage removal).
Merges an array of changes with an existing value or creates a single change.
Kind: global function
| Param | Description |
|---|---|
| changes | Array of changes that should be merged |
| existingValue | The existing value that should be merged with the changes |
Merges an array of changes with an existing value or creates a single change. It will also mark deep nested objects that need to be entirely replaced during the merge.
Kind: global function
| Param | Description |
|---|---|
| changes | Array of changes that should be merged |
| existingValue | The existing value that should be merged with the changes |
Merges an array of changes with an existing value or creates a single change.
Kind: global function
| Param | Description |
|---|---|
| changes | Array of changes that should be merged |
| existingValue | The existing value that should be merged with the changes |
Merge user provided default key value pairs.
Validate the collection is not empty and has a correct type before applying mergeCollection()
Verify if all the collection keys belong to the same parent
Writes a value to our store with the given key.
Serves as core implementation for Onyx.set() public function, the difference being
that this internal function allows passing an additional retryAttempt parameter to retry on failure.
Kind: global function
| Param | Description |
|---|---|
| params | set parameters |
| params.key | ONYXKEY to set |
| params.value | value to store |
| params.options | optional configuration object |
| retryAttempt | retry attempt |
Sets multiple keys and values.
Serves as core implementation for Onyx.multiSet() public function, the difference being
that this internal function allows passing an additional retryAttempt parameter to retry on failure.
Kind: global function
| Param | Description |
|---|---|
| data | object keyed by ONYXKEYS and the values to set |
| retryAttempt | retry attempt |
Sets a collection by replacing all existing collection members with new values.
Any existing collection members not included in the new data will be removed.
Serves as core implementation for Onyx.setCollection() public function, the difference being
that this internal function allows passing an additional retryAttempt parameter to retry on failure.
Kind: global function
| Param | Description |
|---|---|
| params | collection parameters |
| params.collectionKey | e.g. ONYXKEYS.COLLECTION.REPORT |
| params.collection | Object collection keyed by individual collection member keys and values |
| retryAttempt | retry attempt |
Merges a collection based on their keys.
Serves as core implementation for Onyx.mergeCollection() public function, the difference being
that this internal function allows passing an additional mergeReplaceNullPatches parameter and retries on failure.
Kind: global function
| Param | Description |
|---|---|
| params | mergeCollection parameters |
| params.collectionKey | e.g. ONYXKEYS.COLLECTION.REPORT |
| params.collection | Object collection keyed by individual collection member keys and values |
| params.mergeReplaceNullPatches | Record where the key is a collection member key and the value is a list of tuples that we'll use to replace the nested objects of that collection member record with something else. |
| retryAttempt | retry attempt |
Sets keys in a collection by replacing all targeted collection members with new values. Any existing collection members not included in the new data will not be removed. Retries on failure.
Kind: global function
| Param | Description |
|---|---|
| params | collection parameters |
| params.collectionKey | e.g. ONYXKEYS.COLLECTION.REPORT |
| params.collection | Object collection keyed by individual collection member keys and values |
| retryAttempt | retry attempt |
Put Onyx back to "not initialised" state, useful for tests that need a cold start.
Clear internal variables used in this file, useful in test environments.
Kind: global function