Merge branch 'main' into feature/sqliteprovider-improvements

Author: fabioh8010

.github/actionlint.yml

@@ -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) ⇒

API-INTERNAL.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.

README.md

@@ -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/Onyx.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/OnyxCache.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/OnyxMerge/index.native.ts

@@ -137,6 +137,21 @@ function getDeferredInitTask(): DeferredTask {
     return deferredInitTask;
 }
 
+/**
+ * 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.
+ *
+ * @param action The action to execute after initialization
+ * @returns The result of the action
+ */
+function afterInit<T>(action: () => Promise<T>): Promise<T> {
+    if (deferredInitTask.isResolved) {
+        return action();
+    }
+    return deferredInitTask.promise.then(action);
+}
+
 /**
  * Getter - returns the skippable collection member IDs.
  */
@@ -470,6 +485,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 +913,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 +1393,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 +1449,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 +1524,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 +1640,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 +1725,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(() => {
@@ -1690,6 +1764,7 @@ const OnyxUtils = {
     getMergeQueuePromise,
     getDefaultKeyStates,
     getDeferredInitTask,
+    afterInit,
     initStoreValues,
     sendActionToDevTools,
     get,
@@ -1741,6 +1816,7 @@ const OnyxUtils = {
     setWithRetry,
     multiSetWithRetry,
     setCollectionWithRetry,
+    isRamOnlyKey,
 };
 
 GlobalSettings.addGlobalSettingsChangeListener(({enablePerformanceMetrics}) => {

lib/OnyxMerge/index.ts

@@ -1,6 +1,7 @@
 type DeferredTask = {
     promise: Promise<void>;
-    resolve?: () => void;
+    resolve: () => void;
+    isResolved: boolean;
 };
 
 /**
@@ -9,11 +10,16 @@ type DeferredTask = {
  * Useful when we want to wait for a tasks that is resolved from an external action
  */
 export default function createDeferredTask(): DeferredTask {
-    const deferred = {} as DeferredTask;
+    const {promise, resolve: originalResolve} = Promise.withResolvers<void>();
 
-    deferred.promise = new Promise((res) => {
-        deferred.resolve = res;
-    });
+    const deferred: DeferredTask = {
+        promise,
+        resolve: () => {
+            deferred.isResolved = true;
+            originalResolve();
+        },
+        isResolved: false,
+    };
 
     return deferred;
 }

lib/OnyxUtils.ts

@@ -334,7 +334,7 @@ type ExpandOnyxKeys<TKey extends OnyxKey> = TKey extends CollectionKeyBase ? NoI
  * If a new method is added to OnyxUtils.METHOD constant, it must be added to OnyxMethodValueMap type.
  * Otherwise it will show static type errors.
  */
-type OnyxUpdate<TKey extends OnyxKey = OnyxKey> = {
+type OnyxUpdate<TKey extends OnyxKey> = {
     // ⚠️ DO NOT CHANGE THIS TYPE, UNLESS YOU KNOW WHAT YOU ARE DOING. ⚠️
     [K in TKey]:
         | {onyxMethod: typeof OnyxUtils.METHOD.SET; key: ExpandOnyxKeys<K>; value: OnyxSetInput<K>}
@@ -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