react-native-onyx 3.0.33 → 3.0.34

package/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.

package/dist/Onyx.d.ts

@@ -2,7 +2,7 @@ import * as Logger from './Logger';
 import type { CollectionKeyBase, ConnectOptions, InitOptions, OnyxKey, OnyxMergeCollectionInput, OnyxSetCollectionInput, 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, enablePerformanceMetrics, enableDevTools, skippableCollectionMemberIDs, snapshotMergeKeys, }: InitOptions): void;
+declare function init({ keys, initialKeyStates, evictableKeys, maxCachedKeysCount, shouldSyncMultipleInstances, enablePerformanceMetrics, enableDevTools, skippableCollectionMemberIDs, ramOnlyKeys, snapshotMergeKeys, }: InitOptions): void;
 /**
  * Connects to an Onyx key given the options passed and listens to its changes.
  * This method will be deprecated soon. Please use `Onyx.connectWithoutView()` instead.

package/dist/Onyx.js

@@ -48,7 +48,7 @@ const GlobalSettings = __importStar(require("./GlobalSettings"));
 const metrics_1 = __importDefault(require("./metrics"));
 const OnyxMerge_1 = __importDefault(require("./OnyxMerge"));
 /** Initialize the store with actions and listening for storage events */
-function init({ keys = {}, initialKeyStates = {}, evictableKeys = [], maxCachedKeysCount = 1000, shouldSyncMultipleInstances = !!global.localStorage, enablePerformanceMetrics = false, enableDevTools = true, skippableCollectionMemberIDs = [], snapshotMergeKeys = [], }) {
+function init({ keys = {}, initialKeyStates = {}, evictableKeys = [], maxCachedKeysCount = 1000, shouldSyncMultipleInstances = !!global.localStorage, enablePerformanceMetrics = false, enableDevTools = true, skippableCollectionMemberIDs = [], ramOnlyKeys = [], snapshotMergeKeys = [], }) {
     var _a;
     if (enablePerformanceMetrics) {
         GlobalSettings.setPerformanceMetricsEnabled(true);
@@ -58,6 +58,7 @@ function init({ keys = {}, initialKeyStates = {}, evictableKeys = [], maxCachedK
     storage_1.default.init();
     OnyxUtils_1.default.setSkippableCollectionMemberIDs(new Set(skippableCollectionMemberIDs));
     OnyxUtils_1.default.setSnapshotMergeKeys(new Set(snapshotMergeKeys));
+    OnyxCache_1.default.setRamOnlyKeys(new Set(ramOnlyKeys));
     if (shouldSyncMultipleInstances) {
         (_a = storage_1.default.keepInstancesSync) === null || _a === void 0 ? void 0 : _a.call(storage_1.default, (key, value) => {
             OnyxCache_1.default.set(key, value);
@@ -347,8 +348,9 @@ function clear(keysToPreserve = []) {
         for (const [key, value] of Object.entries(keyValuesToResetAsCollection)) {
             updatePromises.push(OnyxUtils_1.default.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_1.default.isRamOnlyKey(key))
             .reduce((obj, key) => {
             // eslint-disable-next-line no-param-reassign
             obj[key] = defaultKeyStates[key];

package/dist/OnyxCache.d.ts

@@ -36,6 +36,8 @@ declare class OnyxCache {
     private recentlyAccessedKeys;
     /** Set of collection keys for fast lookup */
     private collectionKeys;
+    /** Set of RAM-only keys for fast lookup */
+    private ramOnlyKeys;
     constructor();
     /** Get all the storage keys */
     getAllKeys(): Set<OnyxKey>;
@@ -165,6 +167,14 @@ declare class OnyxCache {
      * Get all data for a collection key
      */
     getCollectionData(collectionKey: OnyxKey): Record<OnyxKey, OnyxValue<OnyxKey>> | undefined;
+    /**
+     * Set the RAM-only keys for optimized storage
+     */
+    setRamOnlyKeys(ramOnlyKeys: Set<OnyxKey>): void;
+    /**
+     * Check if a key is a RAM-only key
+     */
+    isRamOnlyKey(key: OnyxKey): boolean;
 }
 declare const instance: OnyxCache;
 export default instance;

package/dist/OnyxCache.js

@@ -64,6 +64,8 @@ class OnyxCache {
         this.recentlyAccessedKeys = new Set();
         /** Set of collection keys for fast lookup */
         this.collectionKeys = new Set();
+        /** Set of RAM-only keys for fast lookup */
+        this.ramOnlyKeys = new Set();
         this.storageKeys = new Set();
         this.nullishStorageKeys = new Set();
         this.recentKeys = new Set();
@@ -71,7 +73,7 @@ class OnyxCache {
         this.collectionData = {};
         this.pendingPromises = new Map();
         // bind all public methods to prevent problems with `this`
-        (0, bindAll_1.default)(this, 'getAllKeys', 'get', 'hasCacheForKey', 'addKey', 'addNullishStorageKey', 'hasNullishStorageKey', 'clearNullishStorageKeys', 'set', 'drop', 'merge', 'hasPendingTask', 'getTaskPromise', 'captureTask', 'addToAccessedKeys', 'removeLeastRecentlyUsedKeys', 'setRecentKeysLimit', 'setAllKeys', 'setEvictionAllowList', 'getEvictionBlocklist', 'isEvictableKey', 'removeLastAccessedKey', 'addLastAccessedKey', 'addEvictableKeysToRecentlyAccessedList', 'getKeyForEviction', 'setCollectionKeys', 'isCollectionKey', 'getCollectionKey', 'getCollectionData');
+        (0, bindAll_1.default)(this, 'getAllKeys', 'get', 'hasCacheForKey', 'addKey', 'addNullishStorageKey', 'hasNullishStorageKey', 'clearNullishStorageKeys', 'set', 'drop', 'merge', 'hasPendingTask', 'getTaskPromise', 'captureTask', 'addToAccessedKeys', 'removeLeastRecentlyUsedKeys', 'setRecentKeysLimit', 'setAllKeys', 'setEvictionAllowList', 'getEvictionBlocklist', 'isEvictableKey', 'removeLastAccessedKey', 'addLastAccessedKey', 'addEvictableKeysToRecentlyAccessedList', 'getKeyForEviction', 'setCollectionKeys', 'isCollectionKey', 'getCollectionKey', 'getCollectionData', 'setRamOnlyKeys', 'isRamOnlyKey');
     }
     /** Get all the storage keys */
     getAllKeys() {
@@ -394,6 +396,18 @@ class OnyxCache {
         // Return a shallow copy to ensure React detects changes when items are added/removed
         return Object.assign({}, cachedCollection);
     }
+    /**
+     * Set the RAM-only keys for optimized storage
+     */
+    setRamOnlyKeys(ramOnlyKeys) {
+        this.ramOnlyKeys = ramOnlyKeys;
+    }
+    /**
+     * Check if a key is a RAM-only key
+     */
+    isRamOnlyKey(key) {
+        return this.ramOnlyKeys.has(key);
+    }
 }
 const instance = new OnyxCache();
 exports.default = instance;

package/dist/OnyxMerge/index.js

@@ -14,8 +14,10 @@ const applyMerge = (key, existingValue, validChanges) => {
     OnyxUtils_1.default.logKeyChanged(OnyxUtils_1.default.METHOD.MERGE, key, mergedValue, hasChanged);
     // This approach prioritizes fast UI changes without waiting for data to be stored in device storage.
     const updatePromise = OnyxUtils_1.default.broadcastUpdate(key, mergedValue, hasChanged);
+    const shouldSkipStorageOperations = !hasChanged || OnyxUtils_1.default.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 });
     }
     // For web platforms we use `setItem` since the object was already merged with its changes before.

package/dist/OnyxMerge/index.native.js

@@ -20,8 +20,10 @@ const applyMerge = (key, existingValue, validChanges) => {
     OnyxUtils_1.default.logKeyChanged(OnyxUtils_1.default.METHOD.MERGE, key, mergedValue, hasChanged);
     // This approach prioritizes fast UI changes without waiting for data to be stored in device storage.
     const updatePromise = OnyxUtils_1.default.broadcastUpdate(key, mergedValue, hasChanged);
+    const shouldSkipStorageOperations = !hasChanged || OnyxUtils_1.default.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 });
     }
     // For native platforms we use `mergeItem` that will take advantage of JSON_PATCH and JSON_REPLACE SQL operations to

package/dist/OnyxUtils.d.ts

@@ -113,6 +113,24 @@ declare function isCollectionMemberKey<TCollectionKey extends CollectionKeyBase>
  * @returns true if the key is a collection member, false otherwise
  */
 declare 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
+ */
+declare function isRamOnlyKey(key: OnyxKey): boolean;
 /**
  * Splits a collection member key into the collection key part and the ID part.
  * @param key - The collection member key to split.
@@ -376,6 +394,7 @@ declare const OnyxUtils: {
     setWithRetry: typeof setWithRetry;
     multiSetWithRetry: typeof multiSetWithRetry;
     setCollectionWithRetry: typeof setCollectionWithRetry;
+    isRamOnlyKey: typeof isRamOnlyKey;
 };
 export type { OnyxMethod };
 export default OnyxUtils;

package/dist/OnyxUtils.js

@@ -385,6 +385,34 @@ function isCollectionMember(key) {
         return false;
     }
 }
+/**
+ * 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) {
+    try {
+        const collectionKey = getCollectionKey(key);
+        // If collectionKey exists for a given key, check if it's a RAM-only key
+        return OnyxCache_1.default.isRamOnlyKey(collectionKey);
+    }
+    catch (_a) {
+        // If getCollectionKey throws, the key is not a collection member
+    }
+    return OnyxCache_1.default.isRamOnlyKey(key);
+}
 /**
  * Splits a collection member key into the collection key part and the ID part.
  * @param key - The collection member key to split.
@@ -713,6 +741,9 @@ function scheduleNotifyCollectionSubscribers(key, value, previousValue) {
 function remove(key, isProcessingCollectionUpdate) {
     OnyxCache_1.default.drop(key);
     scheduleSubscriberUpdate(key, undefined, undefined, isProcessingCollectionUpdate);
+    if (isRamOnlyKey(key)) {
+        return Promise.resolve();
+    }
     return storage_1.default.removeItem(key).then(() => undefined);
 }
 function reportStorageQuota() {
@@ -1103,6 +1134,11 @@ function setWithRetry({ key, value, options }, retryAttempt) {
     if (!hasChanged && !retryAttempt) {
         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_1.default.setItem(key, valueWithoutNestedNullValues)
         .catch((error) => OnyxUtils.retryOperation(error, setWithRetry, { key, value: valueWithoutNestedNullValues, options }, retryAttempt))
         .then(() => {
@@ -1147,7 +1183,12 @@ function multiSetWithRetry(data, retryAttempt) {
         OnyxCache_1.default.set(key, value);
         return OnyxUtils.scheduleSubscriberUpdate(key, value);
     });
-    return storage_1.default.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_1.default.multiSet(keyValuePairsToStore)
         .catch((error) => OnyxUtils.retryOperation(error, multiSetWithRetry, newData, retryAttempt))
         .then(() => {
         OnyxUtils.sendActionToDevTools(OnyxUtils.METHOD.MULTI_SET, undefined, newData);
@@ -1207,6 +1248,11 @@ function setCollectionWithRetry({ collectionKey, collection }, retryAttempt) {
         for (const [key, value] of keyValuePairs)
             OnyxCache_1.default.set(key, value);
         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_1.default.multiSet(keyValuePairs)
             .catch((error) => OnyxUtils.retryOperation(error, setCollectionWithRetry, { collectionKey, collection }, retryAttempt))
             .then(() => {
@@ -1298,10 +1344,12 @@ function mergeCollectionWithPatches({ collectionKey, collection, mergeReplaceNul
         const previousCollectionPromise = Promise.all(existingKeys.map((key) => get(key).then((value) => [key, value]))).then(Object.fromEntries);
         // 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_1.default.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_1.default.multiSet(keyValuePairsForNewCollection));
         }
         // finalMergedCollection contains all the keys that were merged, without the keys of incompatible updates
@@ -1364,6 +1412,10 @@ function partialSetCollection({ collectionKey, collection }, retryAttempt) {
         for (const [key, value] of keyValuePairs)
             OnyxCache_1.default.set(key, value);
         const updatePromise = scheduleNotifyCollectionSubscribers(collectionKey, mutableCollection, previousCollection);
+        if (isRamOnlyKey(collectionKey)) {
+            sendActionToDevTools(METHOD.SET_COLLECTION, undefined, mutableCollection);
+            return updatePromise;
+        }
         return storage_1.default.multiSet(keyValuePairs)
             .catch((error) => retryOperation(error, partialSetCollection, { collectionKey, collection }, retryAttempt))
             .then(() => {
@@ -1445,6 +1497,7 @@ const OnyxUtils = {
     setWithRetry,
     multiSetWithRetry,
     setCollectionWithRetry,
+    isRamOnlyKey,
 };
 GlobalSettings.addGlobalSettingsChangeListener(({ enablePerformanceMetrics }) => {
     if (!enablePerformanceMetrics) {

package/dist/types.d.ts

@@ -364,6 +364,10 @@ type InitOptions = {
      * Additionally, any subscribers from these keys to won't receive any data from Onyx.
      */
     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

package/dist/useOnyx.d.ts

@@ -8,6 +8,7 @@ type UseOnyxOptions<TKey extends OnyxKey, TReturnValue> = {
     canEvict?: boolean;
     /**
      * 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;
     /**

package/package.json

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