perf: skip per-key clone when Onyx.init() hydrates the cache

lib/Onyx.ts

@@ -109,7 +109,7 @@ function init({
 
     // Initialize all of our keys with data provided then give green light to any pending connections.
     // addEvictableKeysToRecentlyAccessedList must run after initializeWithDefaultKeyStates because
-    // eager cache loading populates the key index (cache.setAllKeys) inside initializeWithDefaultKeyStates,
+    // eager cache loading populates the key index (cache.hydrate) inside initializeWithDefaultKeyStates,
     // and the evictable keys list depends on that index being populated.
     OnyxUtils.initializeWithDefaultKeyStates()
         .then(() => cache.addEvictableKeysToRecentlyAccessedList(OnyxKeys.isCollectionKey, OnyxUtils.getAllKeys))

lib/OnyxCache.ts

@@ -2,6 +2,7 @@ import {deepEqual} from 'fast-equals';
 import bindAll from 'lodash/bindAll';
 import type {ValueOf} from 'type-fest';
 import utils from './utils';
+import type {FastMergeOptions} from './utils';
 import type {CollectionKeyBase, KeyValueMapping, NonUndefined, OnyxCollection, OnyxKey, OnyxValue} from './types';
 import OnyxKeys from './OnyxKeys';
 
@@ -15,6 +16,16 @@ type CollectionSnapshot = Readonly<NonUndefined<OnyxCollection<KeyValueMapping[O
  */
 const FROZEN_EMPTY_COLLECTION: Readonly<NonUndefined<OnyxCollection<KeyValueMapping[OnyxKey]>>> = Object.freeze({});
 
+/**
+ * Merge options shared by every cache write path (`merge()` and `hydrate()`'s fallback), so the
+ * three call sites can't drift apart. Cached values must never hold nested nulls, and a source
+ * object carrying the replace mark must replace the target object rather than merge into it.
+ */
+const CACHE_MERGE_OPTIONS: FastMergeOptions = {
+    shouldRemoveNestedNulls: true,
+    objectRemovalMode: 'replace',
+};
+
 // Task constants
 const TASK = {
     GET: 'get',
@@ -77,6 +88,7 @@ class OnyxCache {
             'set',
             'drop',
             'merge',
+            'hydrate',
             'hasPendingTask',
             'getTaskPromise',
             'captureTask',
@@ -199,6 +211,79 @@ class OnyxCache {
         OnyxKeys.deregisterMemberKey(key);
     }
 
+    /**
+     * Bulk-loads values into a cache that's expected to be empty, skipping merge()'s per-key clone when
+     * safe. Falls back to a real merge for any key that already has a value, in case the cache wasn't
+     * empty after all. Used only by `Onyx.init()`.
+     * @param data - a map of (cache) key - values
+     */
+    hydrate(data: Record<OnyxKey, OnyxValue<OnyxKey>>): void {
+        if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+            throw new Error('data passed to cache.hydrate() must be an Object of onyx key/value pairs');
+        }
+
+        const affectedCollections = new Set<OnyxKey>();
+
+        // Use for-in loop to avoid an unnecessary array allocation from Object.keys()
+        // eslint-disable-next-line no-restricted-syntax
+        for (const key in data) {
+            if (!Object.hasOwn(data, key)) {
+                continue;
+            }
+
+            const value = data[key];
+            this.addKey(key);
+
+            if (value === undefined) {
+                this.addNullishStorageKey(key);
+                continue;
+            }
+
+            const collectionKey = OnyxKeys.getCollectionKey(key);
+
+            if (value === null) {
+                this.addNullishStorageKey(key);
+                delete this.storageMap[key];
+
+                if (collectionKey) {
+                    affectedCollections.add(collectionKey);
+                }
+            } else {
+                this.nullishStorageKeys.delete(key);
+
+                const existing = this.storageMap[key];
+
+                if (existing !== undefined) {
+                    // Key already has a value, so the empty-cache assumption doesn't hold here (e.g. a write
+                    // landed while storage was still being read). Fall back to a real merge, which has exactly
+                    // the same semantics as the old `cache.merge(allDataFromStorage)` init path: the value
+                    // loaded from disk is the merge source, so it wins on any overlapping leaf key.
+                    const merged = utils.fastMerge(existing, value, CACHE_MERGE_OPTIONS).result;
+
+                    // fastMerge is reference-stable: returns the original target when nothing changed, so a
+                    // simple === check detects no-ops and avoids dirtying the collection for nothing.
+                    if (merged === existing) {
+                        continue;
+                    }
+
+                    this.storageMap[key] = merged;
+                } else if (utils.needsNormalization(value)) {
+                    this.storageMap[key] = utils.fastMerge(undefined, value, CACHE_MERGE_OPTIONS).result;
+                } else {
+                    this.storageMap[key] = value;
+                }
+
+                if (collectionKey) {
+                    affectedCollections.add(collectionKey);
+                }
+            }
+        }
+
+        for (const collectionKey of affectedCollections) {
+            this.dirtyCollections.add(collectionKey);
+        }
+    }
+
     /**
      * Deep merge data to cache, any non existing keys will be created
      * @param data - a map of (cache) key - values
@@ -233,10 +318,7 @@ class OnyxCache {
 
                 // Per-key merge instead of spreading the entire storageMap
                 const existing = this.storageMap[key];
-                const merged = utils.fastMerge(existing, value, {
-                    shouldRemoveNestedNulls: true,
-                    objectRemovalMode: 'replace',
-                }).result;
+                const merged = utils.fastMerge(existing, value, CACHE_MERGE_OPTIONS).result;
 
                 // fastMerge is reference-stable: returns the original target when
                 // nothing changed, so a simple === check detects no-ops.

lib/OnyxUtils.ts

@@ -1039,9 +1039,12 @@ function initializeWithDefaultKeyStates(): Promise<void> {
                 allDataFromStorage[key] = value;
             }
 
-            // Load all storage data into cache silently (no subscriber notifications)
-            cache.setAllKeys(Object.keys(allDataFromStorage));
-            cache.merge(allDataFromStorage);
+            // Load all storage data into cache silently (no subscriber notifications).
+            // hydrate() rather than merge(): the cache is empty at this point, so a per-key fastMerge
+            // would only deep-clone every row it was handed.
+            // No setAllKeys() call is needed: hydrate() calls addKey() for every key, which populates the
+            // key index and registers collection member keys itself.
+            cache.hydrate(allDataFromStorage);
 
             // For keys that have a developer-defined default (via `initialKeyStates`), merge the
             // persisted value with the default so new properties added in code updates are applied

lib/utils.ts

@@ -196,6 +196,36 @@ function isMergeableObject<TObject extends Record<string, unknown>>(value: unkno
     return isNonNullObject && !(value instanceof RegExp) && !(value instanceof Date) && !Array.isArray(value);
 }
 
+/**
+ * Reports whether a value needs cleaning (nested null/undefined, or the replace-object mark) before it's
+ * safe to store by reference. Read-only, non-allocating.
+ */
+function needsNormalization(value: unknown): boolean {
+    if (value === null || value === undefined || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+
+    // Use for-in loop to avoid an unnecessary array allocation from Object.keys()
+    // eslint-disable-next-line no-restricted-syntax, guard-for-in
+    for (const key in value) {
+        if (key === ONYX_INTERNALS__REPLACE_OBJECT_MARK) {
+            return true;
+        }
+
+        const propertyValue = (value as Record<string, unknown>)[key];
+
+        if (propertyValue === null || propertyValue === undefined) {
+            return true;
+        }
+
+        if (typeof propertyValue === 'object' && !Array.isArray(propertyValue) && needsNormalization(propertyValue)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
 /** Deep removes the nested null values from the given value. Returns the original reference if no nulls were found. */
 function removeNestedNullValues<TValue extends OnyxInput<OnyxKey> | null>(value: TValue): TValue {
     if (value === null || value === undefined || typeof value !== 'object' || Array.isArray(value)) {
@@ -346,6 +376,7 @@ export default {
     isEmptyObject,
     formatActionName,
     removeNestedNullValues,
+    needsNormalization,
     checkCompatibilityWithExistingValue,
     pick,
     omit,