refactor: extract key utilities into centralized OnyxKeys module

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: fabioh8010

lib/Onyx.ts

@@ -23,6 +23,7 @@ import type {
     SetOptions,
 } from './types';
 import OnyxUtils from './OnyxUtils';
+import OnyxKeys from './OnyxKeys';
 import logMessages from './logMessages';
 import type {Connection} from './OnyxConnectionManager';
 import connectionManager from './OnyxConnectionManager';
@@ -55,13 +56,13 @@ function init({
     OnyxUtils.setSkippableCollectionMemberIDs(new Set(skippableCollectionMemberIDs));
     OnyxUtils.setSnapshotMergeKeys(new Set(snapshotMergeKeys));
 
-    cache.setRamOnlyKeys(new Set<OnyxKey>(ramOnlyKeys));
+    OnyxKeys.setRamOnlyKeys(new Set<OnyxKey>(ramOnlyKeys));
 
     if (shouldSyncMultipleInstances) {
         Storage.keepInstancesSync?.((key, value) => {
             // RAM-only keys should never sync from storage as they may have stale persisted data
             // from before the key was migrated to RAM-only.
-            if (OnyxUtils.isRamOnlyKey(key)) {
+            if (OnyxKeys.isRamOnlyKey(key)) {
                 return;
             }
 
@@ -70,7 +71,7 @@ function init({
             // Check if this is a collection member key to prevent duplicate callbacks
             // When a collection is updated, individual members sync separately to other tabs
             // Setting isProcessingCollectionUpdate=true prevents triggering collection callbacks for each individual update
-            const isKeyCollectionMember = OnyxUtils.isCollectionMember(key);
+            const isKeyCollectionMember = OnyxKeys.isCollectionMember(key);
 
             OnyxUtils.keyChanged(key, value as OnyxValue<typeof key>, undefined, isKeyCollectionMember);
         });
@@ -83,7 +84,7 @@ function init({
     OnyxUtils.initStoreValues(keys, initialKeyStates, evictableKeys);
 
     // Initialize all of our keys with data provided then give green light to any pending connections
-    Promise.all([cache.addEvictableKeysToRecentlyAccessedList(OnyxUtils.isCollectionKey, OnyxUtils.getAllKeys), OnyxUtils.initializeWithDefaultKeyStates()]).then(
+    Promise.all([cache.addEvictableKeysToRecentlyAccessedList(OnyxKeys.isCollectionKey, OnyxUtils.getAllKeys), OnyxUtils.initializeWithDefaultKeyStates()]).then(
         OnyxUtils.getDeferredInitTask().resolve,
     );
 }
@@ -201,7 +202,7 @@ function merge<TKey extends OnyxKey>(key: TKey, changes: OnyxMergeInput<TKey>):
         const skippableCollectionMemberIDs = OnyxUtils.getSkippableCollectionMemberIDs();
         if (skippableCollectionMemberIDs.size) {
             try {
-                const [, collectionMemberID] = OnyxUtils.splitCollectionMemberKey(key);
+                const [, collectionMemberID] = OnyxKeys.splitCollectionMemberKey(key);
                 if (skippableCollectionMemberIDs.has(collectionMemberID)) {
                     // The key is a skippable one, so we set the new changes to undefined.
                     // eslint-disable-next-line no-param-reassign
@@ -351,7 +352,7 @@ function clear(keysToPreserve: OnyxKey[] = []): Promise<void> {
                         if (newValue !== oldValue) {
                             cache.set(key, newValue);
 
-                            const collectionKey = OnyxUtils.getCollectionKey(key);
+                            const collectionKey = OnyxKeys.getCollectionKey(key);
 
                             if (collectionKey) {
                                 if (!keyValuesToResetAsCollection[collectionKey]) {
@@ -376,7 +377,7 @@ function clear(keysToPreserve: OnyxKey[] = []): Promise<void> {
                 // Exclude RAM-only keys to prevent them from being saved to storage
                 const defaultKeyValuePairs = Object.entries(
                     Object.keys(defaultKeyStates)
-                        .filter((key) => !keysToPreserve.includes(key) && !OnyxUtils.isRamOnlyKey(key))
+                        .filter((key) => !keysToPreserve.includes(key) && !OnyxKeys.isRamOnlyKey(key))
                         .reduce((obj: KeyValueMapping, key) => {
                             // eslint-disable-next-line no-param-reassign
                             obj[key] = defaultKeyStates[key];
@@ -486,8 +487,8 @@ function update<TKey extends OnyxKey>(data: Array<OnyxUpdate<TKey>>): Promise<vo
         // Group all the collection-related keys and update each collection in a single `mergeCollection` call.
         // This is needed to prevent multiple `mergeCollection` calls for the same collection and `merge` calls for the individual items of the said collection.
         // This way, we ensure there is no race condition in the queued updates of the same key.
-        for (const collectionKey of OnyxUtils.getCollectionKeys()) {
-            const collectionItemKeys = Object.keys(updateQueue).filter((key) => OnyxUtils.isKeyMatch(collectionKey, key));
+        for (const collectionKey of OnyxKeys.getCollectionKeys()) {
+            const collectionItemKeys = Object.keys(updateQueue).filter((key) => OnyxKeys.isKeyMatch(collectionKey, key));
             if (collectionItemKeys.length <= 1) {
                 // If there are no items of this collection in the updateQueue, we should skip it.
                 // If there is only one item, we should update it individually, therefore retain it in the updateQueue.

lib/OnyxCache.ts

@@ -3,7 +3,7 @@ import bindAll from 'lodash/bindAll';
 import type {ValueOf} from 'type-fest';
 import utils from './utils';
 import type {OnyxKey, OnyxValue} from './types';
-import * as Str from './Str';
+import OnyxKeys from './OnyxKeys';
 
 // Task constants
 const TASK = {
@@ -52,12 +52,6 @@ class OnyxCache {
     /** List of keys that have been directly subscribed to or recently modified from least to most recent */
     private recentlyAccessedKeys = new Set<OnyxKey>();
 
-    /** 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,11 +88,8 @@ class OnyxCache {
             'addEvictableKeysToRecentlyAccessedList',
             'getKeyForEviction',
             'setCollectionKeys',
-            'isCollectionKey',
-            'getCollectionKey',
             'getCollectionData',
-            'setRamOnlyKeys',
-            'isRamOnlyKey',
+            'hasValueChanged',
         );
     }
 
@@ -120,13 +111,17 @@ class OnyxCache {
      */
     setAllKeys(keys: OnyxKey[]) {
         this.storageKeys = new Set(keys);
+        for (const key of keys) {
+            OnyxKeys.registerMemberKey(key);
+        }
     }
 
     /** Saves a key in the storage keys list
      * Serves to keep the result of `getAllKeys` up to date
      */
     addKey(key: OnyxKey): void {
         this.storageKeys.add(key);
+        OnyxKeys.registerMemberKey(key);
     }
 
     /** Used to set keys that are null/undefined in storage without adding null to the storage map */
@@ -172,7 +167,7 @@ class OnyxCache {
         // since it will either be set to a non nullish value or removed from the cache completely.
         this.nullishStorageKeys.delete(key);
 
-        const collectionKey = this.getCollectionKey(key);
+        const collectionKey = OnyxKeys.getCollectionKey(key);
         if (value === null || value === undefined) {
             delete this.storageMap[key];
 
@@ -201,18 +196,19 @@ class OnyxCache {
         delete this.storageMap[key];
 
         // Remove from collection data cache if this is a collection member
-        const collectionKey = this.getCollectionKey(key);
+        const collectionKey = OnyxKeys.getCollectionKey(key);
         if (collectionKey && this.collectionData[collectionKey]) {
             delete this.collectionData[collectionKey][key];
         }
 
         // If this is a collection key, clear its data
-        if (this.isCollectionKey(key)) {
+        if (OnyxKeys.isCollectionKey(key)) {
             delete this.collectionData[key];
         }
 
         this.storageKeys.delete(key);
         this.recentKeys.delete(key);
+        OnyxKeys.deregisterMemberKey(key);
     }
 
     /**
@@ -235,7 +231,7 @@ class OnyxCache {
             this.addKey(key);
             this.addToAccessedKeys(key);
 
-            const collectionKey = this.getCollectionKey(key);
+            const collectionKey = OnyxKeys.getCollectionKey(key);
 
             if (value === null || value === undefined) {
                 this.addNullishStorageKey(key);
@@ -325,7 +321,7 @@ class OnyxCache {
             delete this.storageMap[key];
 
             // Remove from collection data cache if this is a collection member
-            const collectionKey = this.getCollectionKey(key);
+            const collectionKey = OnyxKeys.getCollectionKey(key);
             if (collectionKey && this.collectionData[collectionKey]) {
                 delete this.collectionData[collectionKey][key];
             }
@@ -364,17 +360,7 @@ class OnyxCache {
      * @param testKey - Key to check
      */
     isEvictableKey(testKey: OnyxKey): boolean {
-        return this.evictionAllowList.some((key) => this.isKeyMatch(key, testKey));
-    }
-
-    /**
-     * Check if a given key matches a pattern key
-     * @param configKey - Pattern that may contain a wildcard
-     * @param key - Key to test against the pattern
-     */
-    private isKeyMatch(configKey: OnyxKey, key: OnyxKey): boolean {
-        const isCollectionKey = configKey.endsWith('_');
-        return isCollectionKey ? Str.startsWith(key, configKey) : configKey === key;
+        return this.evictionAllowList.some((key) => OnyxKeys.isKeyMatch(key, testKey));
     }
 
     /**
@@ -411,7 +397,7 @@ class OnyxCache {
         return getAllKeysFn().then((keys: Set<OnyxKey>) => {
             for (const evictableKey of this.evictionAllowList) {
                 for (const key of keys) {
-                    if (!this.isKeyMatch(evictableKey, key)) {
+                    if (!OnyxKeys.isKeyMatch(evictableKey, key)) {
                         continue;
                     }
 
@@ -437,7 +423,7 @@ class OnyxCache {
      * Set the collection keys for optimized storage
      */
     setCollectionKeys(collectionKeys: Set<OnyxKey>): void {
-        this.collectionKeys = collectionKeys;
+        OnyxKeys.setCollectionKeys(collectionKeys);
 
         // Initialize collection data for existing collection keys
         for (const collectionKey of collectionKeys) {
@@ -446,25 +432,11 @@ class OnyxCache {
             }
             this.collectionData[collectionKey] = {};
         }
-    }
-
-    /**
-     * Check if a key is a collection key
-     */
-    isCollectionKey(key: OnyxKey): boolean {
-        return this.collectionKeys.has(key);
-    }
 
-    /**
-     * Get the collection key for a given member key
-     */
-    getCollectionKey(key: OnyxKey): OnyxKey | undefined {
-        for (const collectionKey of this.collectionKeys) {
-            if (key.startsWith(collectionKey) && key.length > collectionKey.length) {
-                return collectionKey;
-            }
+        // Register existing storageKeys with OnyxKeys
+        for (const key of this.storageKeys) {
+            OnyxKeys.registerMemberKey(key);
         }
-        return undefined;
     }
 
     /**
@@ -480,19 +452,6 @@ class OnyxCache {
         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/OnyxConnectionManager.ts

@@ -2,6 +2,7 @@ import bindAll from 'lodash/bindAll';
 import * as Logger from './Logger';
 import type {ConnectOptions} from './Onyx';
 import OnyxUtils from './OnyxUtils';
+import OnyxKeys from './OnyxKeys';
 import * as Str from './Str';
 import type {CollectionConnectCallback, DefaultConnectCallback, DefaultConnectOptions, OnyxKey, OnyxValue} from './types';
 import cache from './OnyxCache';
@@ -129,7 +130,7 @@ class OnyxConnectionManager {
         if (
             reuseConnection === false ||
             initWithStoredValues === false ||
-            (OnyxUtils.isCollectionKey(key) && (waitForCollectionCallback === undefined || waitForCollectionCallback === false))
+            (OnyxKeys.isCollectionKey(key) && (waitForCollectionCallback === undefined || waitForCollectionCallback === false))
         ) {
             suffix += `,uniqueID=${Str.guid()}`;
         }