Implement RAM-only key support to replace initWithStoredValues

API-INTERNAL.md

@@ -58,6 +58,18 @@ is associated with a collection of keys.</p>
 <dt><a href="#isCollectionMember">isCollectionMember(key)</a> ⇒</dt>
 <dd><p>Checks if a given key is a collection member key (not just a collection key).</p>
 </dd>
+<dt><a href="#isRamOnlyKey">isRamOnlyKey(key)</a> ⇒</dt>
+<dd><p>Checks if a given key is a RAM-only key, RAM-only collection key, or a RAM-only collection member</p>
+<p>For example:</p>
+<p>For the following Onyx setup</p>
+<p>ramOnlyKeys: [&quot;ramOnlyKey&quot;, &quot;ramOnlyCollection_&quot;]</p>
+<ul>
+<li><code>isRamOnlyKey(&quot;ramOnlyKey&quot;)</code> would return true</li>
+<li><code>isRamOnlyKey(&quot;ramOnlyCollection_&quot;)</code> would return true</li>
+<li><code>isRamOnlyKey(&quot;ramOnlyCollection_1&quot;)</code> would return true</li>
+<li><code>isRamOnlyKey(&quot;someOtherKey&quot;)</code> would return false</li>
+</ul>
+</dd>
 <dt><a href="#splitCollectionMemberKey">splitCollectionMemberKey(key, collectionKey)</a> ⇒</dt>
 <dd><p>Splits a collection member key into the collection key part and the ID part.</p>
 </dd>
@@ -307,6 +319,29 @@ Checks if a given key is a collection member key (not just a collection key).
 | --- | --- |
 | key | The key to check |
 
+<a name="isRamOnlyKey"></a>
+
+## isRamOnlyKey(key) ⇒
+Checks if a given key is a RAM-only key, RAM-only collection key, or a RAM-only collection member
+
+For example:
+
+For the following Onyx setup
+
+ramOnlyKeys: ["ramOnlyKey", "ramOnlyCollection_"]
+
+- `isRamOnlyKey("ramOnlyKey")` would return true
+- `isRamOnlyKey("ramOnlyCollection_")` would return true
+- `isRamOnlyKey("ramOnlyCollection_1")` would return true
+- `isRamOnlyKey("someOtherKey")` would return false
+
+**Kind**: global function  
+**Returns**: true if key is a RAM-only key, RAM-only collection key, or a RAM-only collection member  
+
+| Param | Description |
+| --- | --- |
+| key | The key to check |
+
 <a name="splitCollectionMemberKey"></a>
 
 ## splitCollectionMemberKey(key, collectionKey) ⇒

README.md

@@ -460,6 +460,25 @@ Onyx.init({
 });
 ```
 
+### Using RAM-only keys
+
+You can choose not to save certain keys on disk and keep them RAM-only, that way their values will reset with each session. You just have to pass an array of `ramOnlyKeys` to the `Onyx.init` method. You can mark entire collections as RAM-only by including the collection key (e.g., `ONYXKEYS.COLLECTION.TEMP_DATA`). This will make all members of that collection RAM-only. Individual collection member keys cannot be selectively marked as RAM-only.
+
+```javascript
+import Onyx from 'react-native-onyx';
+
+Onyx.init({
+    keys: ONYXKEYS,
+    ramOnlyKeys: [
+        ONYXKEYS.RAM_ONLY_KEY_1,
+        ONYXKEYS.RAM_ONLY_KEY_2,
+        ONYXKEYS.COLLECTION.TEMP_DATA,
+    ],
+});
+```
+
+> Note: RAM-only keys still consume memory and will remain in cache until explicitly cleared or until Onyx.clear() is called. Use them judiciously for truly ephemeral data.
+
 ### Usage
 
 The extension interface is pretty simple, on the left sidebar you can see all the updates made to the local storage, in ascending order, and on the right pane you can see the whole the current state, payload of an action and the diff between the previous state and the current state after the action was triggered.

lib/Onyx.ts

@@ -40,6 +40,7 @@ function init({
     enablePerformanceMetrics = false,
     enableDevTools = true,
     skippableCollectionMemberIDs = [],
+    ramOnlyKeys = [],
     snapshotMergeKeys = [],
 }: InitOptions): void {
     if (enablePerformanceMetrics) {
@@ -54,6 +55,8 @@ function init({
     OnyxUtils.setSkippableCollectionMemberIDs(new Set(skippableCollectionMemberIDs));
     OnyxUtils.setSnapshotMergeKeys(new Set(snapshotMergeKeys));
 
+    cache.setRamOnlyKeys(new Set<OnyxKey>(ramOnlyKeys));
+
     if (shouldSyncMultipleInstances) {
         Storage.keepInstancesSync?.((key, value) => {
             cache.set(key, value);
@@ -378,9 +381,10 @@ function clear(keysToPreserve: OnyxKey[] = []): Promise<void> {
                 updatePromises.push(OnyxUtils.scheduleNotifyCollectionSubscribers(key, value.newValues, value.oldValues));
             }
 
+            // Exclude RAM-only keys to prevent them from being saved to storage
             const defaultKeyValuePairs = Object.entries(
                 Object.keys(defaultKeyStates)
-                    .filter((key) => !keysToPreserve.includes(key))
+                    .filter((key) => !keysToPreserve.includes(key) && !OnyxUtils.isRamOnlyKey(key))
                     .reduce((obj: KeyValueMapping, key) => {
                         // eslint-disable-next-line no-param-reassign
                         obj[key] = defaultKeyStates[key];

lib/OnyxCache.ts

@@ -55,6 +55,9 @@ class OnyxCache {
     /** Set of collection keys for fast lookup */
     private collectionKeys = new Set<OnyxKey>();
 
+    /** Set of RAM-only keys for fast lookup */
+    private ramOnlyKeys = new Set<OnyxKey>();
+
     constructor() {
         this.storageKeys = new Set();
         this.nullishStorageKeys = new Set();
@@ -94,6 +97,8 @@ class OnyxCache {
             'isCollectionKey',
             'getCollectionKey',
             'getCollectionData',
+            'setRamOnlyKeys',
+            'isRamOnlyKey',
         );
     }
 
@@ -474,6 +479,20 @@ class OnyxCache {
         // Return a shallow copy to ensure React detects changes when items are added/removed
         return {...cachedCollection};
     }
+
+    /**
+     * Set the RAM-only keys for optimized storage
+     */
+    setRamOnlyKeys(ramOnlyKeys: Set<OnyxKey>): void {
+        this.ramOnlyKeys = ramOnlyKeys;
+    }
+
+    /**
+     * Check if a key is a RAM-only key
+     */
+    isRamOnlyKey(key: OnyxKey): boolean {
+        return this.ramOnlyKeys.has(key);
+    }
 }
 
 const instance = new OnyxCache();

lib/OnyxMerge/index.native.ts

@@ -28,8 +28,11 @@ const applyMerge: ApplyMerge = <TKey extends OnyxKey, TValue extends OnyxInput<T
     // This approach prioritizes fast UI changes without waiting for data to be stored in device storage.
     const updatePromise = OnyxUtils.broadcastUpdate(key, mergedValue as OnyxValue<TKey>, hasChanged);
 
+    const shouldSkipStorageOperations = !hasChanged || OnyxUtils.isRamOnlyKey(key);
+
     // If the value has not changed, calling Storage.setItem() would be redundant and a waste of performance, so return early instead.
-    if (!hasChanged) {
+    // If the key is marked as RAM-only, it should not be saved nor updated in the storage.
+    if (shouldSkipStorageOperations) {
         return Promise.resolve({mergedValue, updatePromise});
     }
 

lib/OnyxMerge/index.ts

@@ -20,8 +20,11 @@ const applyMerge: ApplyMerge = <TKey extends OnyxKey, TValue extends OnyxInput<T
     // This approach prioritizes fast UI changes without waiting for data to be stored in device storage.
     const updatePromise = OnyxUtils.broadcastUpdate(key, mergedValue as OnyxValue<TKey>, hasChanged);
 
+    const shouldSkipStorageOperations = !hasChanged || OnyxUtils.isRamOnlyKey(key);
+
     // If the value has not changed, calling Storage.setItem() would be redundant and a waste of performance, so return early instead.
-    if (!hasChanged) {
+    // If the key is marked as RAM-only, it should not be saved nor updated in the storage.
+    if (shouldSkipStorageOperations) {
         return Promise.resolve({mergedValue, updatePromise});
     }
 

lib/OnyxUtils.ts

@@ -470,6 +470,35 @@ function isCollectionMember(key: OnyxKey): boolean {
     }
 }
 
+/**
+ * Checks if a given key is a RAM-only key, RAM-only collection key, or a RAM-only collection member
+ *
+ * For example:
+ *
+ * For the following Onyx setup
+ *
+ * ramOnlyKeys: ["ramOnlyKey", "ramOnlyCollection_"]
+ *
+ * - `isRamOnlyKey("ramOnlyKey")` would return true
+ * - `isRamOnlyKey("ramOnlyCollection_")` would return true
+ * - `isRamOnlyKey("ramOnlyCollection_1")` would return true
+ * - `isRamOnlyKey("someOtherKey")` would return false
+ *
+ * @param key - The key to check
+ * @returns true if key is a RAM-only key, RAM-only collection key, or a RAM-only collection member
+ */
+function isRamOnlyKey(key: OnyxKey): boolean {
+    try {
+        const collectionKey = getCollectionKey(key);
+        // If collectionKey exists for a given key, check if it's a RAM-only key
+        return cache.isRamOnlyKey(collectionKey);
+    } catch {
+        // If getCollectionKey throws, the key is not a collection member
+    }
+
+    return cache.isRamOnlyKey(key);
+}
+
 /**
  * Splits a collection member key into the collection key part and the ID part.
  * @param key - The collection member key to split.
@@ -869,6 +898,11 @@ function scheduleNotifyCollectionSubscribers<TKey extends OnyxKey>(
 function remove<TKey extends OnyxKey>(key: TKey, isProcessingCollectionUpdate?: boolean): Promise<void> {
     cache.drop(key);
     scheduleSubscriberUpdate(key, undefined as OnyxValue<TKey>, undefined, isProcessingCollectionUpdate);
+
+    if (isRamOnlyKey(key)) {
+        return Promise.resolve();
+    }
+
     return Storage.removeItem(key).then(() => undefined);
 }
 
@@ -1344,6 +1378,12 @@ function setWithRetry<TKey extends OnyxKey>({key, value, options}: SetParams<TKe
         return updatePromise;
     }
 
+    // If a key is a RAM-only key or a member of RAM-only collection, we skip the step that modifies the storage
+    if (isRamOnlyKey(key)) {
+        OnyxUtils.sendActionToDevTools(OnyxUtils.METHOD.SET, key, valueWithoutNestedNullValues);
+        return updatePromise;
+    }
+
     return Storage.setItem(key, valueWithoutNestedNullValues)
         .catch((error) => OnyxUtils.retryOperation(error, setWithRetry, {key, value: valueWithoutNestedNullValues, options}, retryAttempt))
         .then(() => {
@@ -1394,7 +1434,13 @@ function multiSetWithRetry(data: OnyxMultiSetInput, retryAttempt?: number): Prom
         return OnyxUtils.scheduleSubscriberUpdate(key, value);
     });
 
-    return Storage.multiSet(keyValuePairsToSet)
+    const keyValuePairsToStore = keyValuePairsToSet.filter((keyValuePair) => {
+        const [key] = keyValuePair;
+        // Filter out the RAM-only key value pairs, as they should not be saved to storage
+        return !isRamOnlyKey(key);
+    });
+
+    return Storage.multiSet(keyValuePairsToStore)
         .catch((error) => OnyxUtils.retryOperation(error, multiSetWithRetry, newData, retryAttempt))
         .then(() => {
             OnyxUtils.sendActionToDevTools(OnyxUtils.METHOD.MULTI_SET, undefined, newData);
@@ -1463,6 +1509,12 @@ function setCollectionWithRetry<TKey extends CollectionKeyBase>({collectionKey,
 
         const updatePromise = OnyxUtils.scheduleNotifyCollectionSubscribers(collectionKey, mutableCollection, previousCollection);
 
+        // RAM-only keys are not supposed to be saved to storage
+        if (isRamOnlyKey(collectionKey)) {
+            OnyxUtils.sendActionToDevTools(OnyxUtils.METHOD.SET_COLLECTION, undefined, mutableCollection);
+            return updatePromise;
+        }
+
         return Storage.multiSet(keyValuePairs)
             .catch((error) => OnyxUtils.retryOperation(error, setCollectionWithRetry, {collectionKey, collection}, retryAttempt))
             .then(() => {
@@ -1573,11 +1625,13 @@ function mergeCollectionWithPatches<TKey extends CollectionKeyBase>(
 
             // New keys will be added via multiSet while existing keys will be updated using multiMerge
             // This is because setting a key that doesn't exist yet with multiMerge will throw errors
-            if (keyValuePairsForExistingCollection.length > 0) {
+            // We can skip this step for RAM-only keys as they should never be saved to storage
+            if (!isRamOnlyKey(collectionKey) && keyValuePairsForExistingCollection.length > 0) {
                 promises.push(Storage.multiMerge(keyValuePairsForExistingCollection));
             }
 
-            if (keyValuePairsForNewCollection.length > 0) {
+            // We can skip this step for RAM-only keys as they should never be saved to storage
+            if (!isRamOnlyKey(collectionKey) && keyValuePairsForNewCollection.length > 0) {
                 promises.push(Storage.multiSet(keyValuePairsForNewCollection));
             }
 
@@ -1656,6 +1710,11 @@ function partialSetCollection<TKey extends CollectionKeyBase>({collectionKey, co
 
         const updatePromise = scheduleNotifyCollectionSubscribers(collectionKey, mutableCollection, previousCollection);
 
+        if (isRamOnlyKey(collectionKey)) {
+            sendActionToDevTools(METHOD.SET_COLLECTION, undefined, mutableCollection);
+            return updatePromise;
+        }
+
         return Storage.multiSet(keyValuePairs)
             .catch((error) => retryOperation(error, partialSetCollection, {collectionKey, collection}, retryAttempt))
             .then(() => {
@@ -1741,6 +1800,7 @@ const OnyxUtils = {
     setWithRetry,
     multiSetWithRetry,
     setCollectionWithRetry,
+    isRamOnlyKey,
 };
 
 GlobalSettings.addGlobalSettingsChangeListener(({enablePerformanceMetrics}) => {

lib/types.ts

@@ -426,6 +426,11 @@ type InitOptions = {
      */
     skippableCollectionMemberIDs?: string[];
 
+    /**
+     * Array of keys that when provided to Onyx are flagged as RAM-only keys, and thus are not saved to disk.
+     */
+    ramOnlyKeys?: OnyxKey[];
+
     /**
      * A list of field names that should always be merged into snapshot entries even if those fields are
      * missing in the snapshot. Snapshots are saved "views" of a key's data used to populate read-only

lib/useOnyx.ts

@@ -23,6 +23,7 @@ type UseOnyxOptions<TKey extends OnyxKey, TReturnValue> = {
 
     /**
      * If set to `false`, then no data will be prefilled into the component.
+     * @deprecated This param is going to be removed soon. Use RAM-only keys instead.
      */
     initWithStoredValues?: boolean;
 

tests/perf-test/OnyxConnectionManager.perf-test.ts

@@ -8,6 +8,7 @@ import {getRandomReportActions} from '../utils/collections/reportActions';
 const ONYXKEYS = {
     TEST_KEY: 'test',
     TEST_KEY_2: 'test2',
+    RAM_ONLY_TEST_KEY: 'ramOnlyTestKey',
     COLLECTION: {
         TEST_KEY: 'test_',
         TEST_NESTED_KEY: 'test_nested_',
@@ -18,6 +19,7 @@ const ONYXKEYS = {
         TEST_KEY_5: 'test5_',
         EVICTABLE_TEST_KEY: 'evictable_test_',
         SNAPSHOT: 'snapshot_',
+        RAM_ONLY_TEST_COLLECTION: 'ramOnlyTestCollection_',
     },
 };
 
@@ -47,6 +49,7 @@ describe('OnyxConnectionManager', () => {
             maxCachedKeysCount: 100000,
             evictableKeys: [ONYXKEYS.COLLECTION.EVICTABLE_TEST_KEY],
             skippableCollectionMemberIDs: ['skippable-id'],
+            ramOnlyKeys: [ONYXKEYS.RAM_ONLY_TEST_KEY, ONYXKEYS.COLLECTION.RAM_ONLY_TEST_COLLECTION],
         });
     });
 

tests/perf-test/OnyxUtils.perf-test.ts

@@ -14,6 +14,7 @@ import type {OnyxEntry, OnyxInputKeyValueMapping, OnyxKey, RetriableOnyxOperatio
 const ONYXKEYS = {
     TEST_KEY: 'test',
     TEST_KEY_2: 'test2',
+    RAM_ONLY_TEST_KEY: 'ramOnlyTestKey',
     COLLECTION: {
         TEST_KEY: 'test_',
         TEST_NESTED_KEY: 'test_nested_',
@@ -24,6 +25,7 @@ const ONYXKEYS = {
         TEST_KEY_5: 'test5_',
         EVICTABLE_TEST_KEY: 'evictable_test_',
         SNAPSHOT: 'snapshot_',
+        RAM_ONLY_TEST_COLLECTION: 'ramOnlyTestCollection_',
     },
 };
 
@@ -54,6 +56,7 @@ describe('OnyxUtils', () => {
             evictableKeys,
             initialKeyStates,
             skippableCollectionMemberIDs: ['skippable-id'],
+            ramOnlyKeys: [ONYXKEYS.RAM_ONLY_TEST_KEY, ONYXKEYS.COLLECTION.RAM_ONLY_TEST_COLLECTION],
         });
     });
 
@@ -144,6 +147,20 @@ describe('OnyxUtils', () => {
         });
     });
 
+    describe('isRamOnlyKey', () => {
+        test('one call for RAM-only key', async () => {
+            await measureFunction(() => OnyxUtils.isRamOnlyKey(ONYXKEYS.RAM_ONLY_TEST_KEY));
+        });
+
+        test('one call for RAM-only collection key', async () => {
+            await measureFunction(() => OnyxUtils.isRamOnlyKey(ONYXKEYS.COLLECTION.RAM_ONLY_TEST_COLLECTION));
+        });
+
+        test('one call for RAM-only collection member key', async () => {
+            await measureFunction(() => OnyxUtils.isRamOnlyKey(`${ONYXKEYS.COLLECTION.RAM_ONLY_TEST_COLLECTION}1`));
+        });
+    });
+
     describe('isCollectionMemberKey', () => {
         test('one call with correct key', async () => {
             await measureFunction(() => OnyxUtils.isCollectionMemberKey(collectionKey, `${collectionKey}entry1`));

tests/perf-test/useOnyx.perf-test.tsx

@@ -11,6 +11,7 @@ const ONYXKEYS = {
     TEST_KEY: 'test',
     TEST_KEY_2: 'test2',
     TEST_KEY_3: 'test3',
+    RAM_ONLY_TEST_KEY: 'ramOnlyTestKey',
 };
 
 const dataMatcher = (onyxKey: OnyxKey, expected: unknown) => `data: ${onyxKey}_${JSON.stringify(expected)}`;
@@ -57,6 +58,7 @@ describe('useOnyx', () => {
         Onyx.init({
             keys: ONYXKEYS,
             maxCachedKeysCount: 100000,
+            ramOnlyKeys: [ONYXKEYS.RAM_ONLY_TEST_KEY],
         });
     });