react-native-onyx 2.0.118 → 2.0.120

package/README.md

@@ -59,6 +59,33 @@ API.Authenticate(params)
 
 The data will then be cached and stored via [`AsyncStorage`](https://github.com/react-native-async-storage/async-storage).
 
+### Performance Options for Large Objects
+
+For performance-critical scenarios with large objects, `Onyx.set()` accepts optional flags to skip expensive operations:
+
+```javascript
+Onyx.set(ONYXKEYS.LARGE_DATA, computedValue, {
+    skipCacheCheck: true,     // Skip deep equality check
+    skipNullRemoval: true,    // Skip null value pruning
+});
+```
+
+**Options:**
+- `skipCacheCheck`: Skips the deep equality comparison with the cached value. By default, Onyx compares new values against cached ones to avoid unnecessary updates. For large objects, this comparison can be expensive.
+- `skipNullRemoval`: Skips the removal of `null` values from nested objects. By default, Onyx removes `null` values before storage. Use this when `null` values are meaningful in your data structure.
+
+#### When to Use SetOptions
+- **Use `skipCacheCheck: true`** for:
+  - Large objects where deep equality checking is expensive
+  - Values that you know have changed
+
+- **Use `skipNullRemoval: true`** for:
+  - Computed values where `null` represents a legitimate result
+  - Data structures where `null` has semantic meaning
+  - Values that should preserve their exact structure
+
+**Note**: These options are recommended only for large objects where performance is critical. Most use cases should use the standard `Onyx.set(key, value)` syntax.
+
 ## Merging data
 
 We can also use `Onyx.merge()` to merge new `Object` or `Array` data in with existing data.

package/dist/Onyx.d.ts

@@ -1,5 +1,5 @@
 import * as Logger from './Logger';
-import type { CollectionKeyBase, ConnectOptions, InitOptions, Mapping, OnyxKey, OnyxMergeCollectionInput, OnyxMergeInput, OnyxMultiSetInput, OnyxSetInput, OnyxUpdate } from './types';
+import type { CollectionKeyBase, ConnectOptions, InitOptions, Mapping, OnyxKey, OnyxMergeCollectionInput, OnyxMergeInput, OnyxMultiSetInput, OnyxSetInput, OnyxUpdate, SetOptions } from './types';
 import type { Connection } from './OnyxConnectionManager';
 /** Initialize the store with actions and listening for storage events */
 declare function init({ keys, initialKeyStates, evictableKeys, maxCachedKeysCount, shouldSyncMultipleInstances, debugSetState, enablePerformanceMetrics, skippableCollectionMemberIDs, fullyMergedSnapshotKeys, }: InitOptions): void;
@@ -49,8 +49,9 @@ declare function disconnect(connection: Connection): void;
  *
  * @param key ONYXKEY to set
  * @param value value to store
+ * @param options optional configuration object
  */
-declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxSetInput<TKey>): Promise<void>;
+declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxSetInput<TKey>, options?: SetOptions): Promise<void>;
 /**
  * Sets multiple keys and values
  *
@@ -155,4 +156,4 @@ declare const Onyx: {
     registerLogger: typeof Logger.registerLogger;
 };
 export default Onyx;
-export type { OnyxUpdate, Mapping, ConnectOptions };
+export type { OnyxUpdate, Mapping, ConnectOptions, SetOptions };

package/dist/Onyx.js

@@ -114,8 +114,9 @@ function disconnect(connection) {
  *
  * @param key ONYXKEY to set
  * @param value value to store
+ * @param options optional configuration object
  */
-function set(key, value) {
+function set(key, value, options) {
     // When we use Onyx.set to set a key we want to clear the current delta changes from Onyx.merge that were queued
     // before the value was set. If Onyx.merge is currently reading the old value from storage, it will then not apply the changes.
     if (OnyxUtils_1.default.hasPendingMergeForKey(key)) {
@@ -157,8 +158,8 @@ function set(key, value) {
         OnyxUtils_1.default.logKeyRemoved(OnyxUtils_1.default.METHOD.SET, key);
         return Promise.resolve();
     }
-    const valueWithoutNestedNullValues = utils_1.default.removeNestedNullValues(value);
-    const hasChanged = OnyxCache_1.default.hasValueChanged(key, valueWithoutNestedNullValues);
+    const valueWithoutNestedNullValues = ((options === null || options === void 0 ? void 0 : options.skipNullRemoval) ? value : utils_1.default.removeNestedNullValues(value));
+    const hasChanged = (options === null || options === void 0 ? void 0 : options.skipCacheCheck) ? true : OnyxCache_1.default.hasValueChanged(key, valueWithoutNestedNullValues);
     OnyxUtils_1.default.logKeyChanged(OnyxUtils_1.default.METHOD.SET, key, value, hasChanged);
     // This approach prioritizes fast UI changes without waiting for data to be stored in device storage.
     const updatePromise = OnyxUtils_1.default.broadcastUpdate(key, valueWithoutNestedNullValues, hasChanged);

package/dist/types.d.ts

@@ -368,6 +368,15 @@ type OnyxUpdate = {
         onyxMethod: Method;
     } & OnyxMethodValueMap[Method];
 }[OnyxMethod];
+/**
+ * Represents the options used in `Onyx.set()` method.
+ */
+type SetOptions = {
+    /** Skip the deep equality check against the cached value. Improves performance for large objects. */
+    skipCacheCheck?: boolean;
+    /** Skip pruning null values from the object. Improves performance for large objects. */
+    skipNullRemoval?: boolean;
+};
 /**
  * Represents the options used in `Onyx.init()` method.
  */
@@ -428,4 +437,4 @@ type MixedOperationsQueue = {
     mergeReplaceNullPatches: MultiMergeReplaceNullPatches;
     set: OnyxInputKeyValueMapping;
 };
-export type { BaseConnectOptions, Collection, CollectionConnectCallback, CollectionConnectOptions, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, DefaultConnectOptions, ExtractOnyxCollectionValue, GenericFunction, InitOptions, Key, KeyValueMapping, Mapping, NonNull, NonUndefined, OnyxInputKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxMethod, OnyxMethodMap, OnyxUpdate, OnyxValue, Selector, WithOnyxConnectOptions, MultiMergeReplaceNullPatches, MixedOperationsQueue, };
+export type { BaseConnectOptions, Collection, CollectionConnectCallback, CollectionConnectOptions, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, DefaultConnectOptions, ExtractOnyxCollectionValue, GenericFunction, InitOptions, Key, KeyValueMapping, Mapping, NonNull, NonUndefined, OnyxInputKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxMethod, OnyxMethodMap, OnyxUpdate, OnyxValue, Selector, SetOptions, WithOnyxConnectOptions, MultiMergeReplaceNullPatches, MixedOperationsQueue, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-onyx",
-  "version": "2.0.118",
+  "version": "2.0.120",
   "author": "Expensify, Inc.",
   "homepage": "https://expensify.com",
   "description": "State management for React Native",