react-native-onyx 3.0.115 → 3.0.117

package/dist/OnyxUtils.js

@@ -37,13 +37,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clearOnyxUtilsInternals = clearOnyxUtilsInternals;
-const fast_equals_1 = require("fast-equals");
+exports.resetDeferredInitTask = resetDeferredInitTask;
 const underscore_1 = __importDefault(require("underscore"));
 const DevTools_1 = __importDefault(require("./DevTools"));
 const Logger = __importStar(require("./Logger"));
 const OnyxCache_1 = __importStar(require("./OnyxCache"));
 const OnyxKeys_1 = __importDefault(require("./OnyxKeys"));
+const PendingWrites_1 = __importDefault(require("./PendingWrites"));
 const StorageCircuitBreaker_1 = __importDefault(require("./StorageCircuitBreaker"));
+const OnyxSubscriptionManager_1 = __importDefault(require("./OnyxSubscriptionManager"));
 const storage_1 = __importDefault(require("./storage"));
 const errors_1 = require("./storage/errors");
 const utils_1 = __importDefault(require("./utils"));
@@ -68,25 +70,24 @@ let lastDiskPressureLogTime = 0;
 function resetDiskPressureLogThrottle() {
     lastDiskPressureLogTime = 0;
 }
-function formatCaughtError(error) {
-    return error instanceof Error ? error.toString() : String(error);
-}
 // Key/value store of Onyx key and arrays of values to merge
 let mergeQueue = {};
 let mergeQueuePromise = {};
-// Holds a mapping of all the React components that want their state subscribed to a store key
-let callbackToStateMapping = {};
-// Holds a mapping of the connected key to the subscriptionID for faster lookups
-let onyxKeyToSubscriptionIDs = new Map();
+const mergeQueuesWithStaleRead = new WeakSet();
 // Optional user-provided key value states set when Onyx initializes or clears
 let defaultKeyStates = {};
-// Used for comparison with a new update to avoid invoking the Onyx.connect callback with the same data.
-let lastConnectionCallbackData = new Map();
 let snapshotKey = null;
-// Keeps track of the last subscriptionID that was used so we can keep incrementing it
-let lastSubscriptionID = 0;
-// Connections can be made before `Onyx.init`. They would wait for this task before resolving
-const deferredInitTask = (0, createDeferredTask_1.default)();
+// Connections can be made before `Onyx.init`. They would wait for this task before resolving.
+let deferredInitTask = (0, createDeferredTask_1.default)();
+/**
+ * Sentinel for "nothing delivered yet" in `connect()`'s per-subscription dedup. A Symbol
+ * can't collide with any real Onyx value, so the first `Object.is` check never matches and
+ * the initial fire runs even when a key's genuine first value is `undefined`. It only needs
+ * to be distinct from real values, not unique per subscription, so one module-level instance
+ * is reused by every connection.
+ */
+// eslint-disable-next-line rulesdir/no-negated-variables
+const NOT_DELIVERED = Symbol('NOT_DELIVERED');
 // Collection member IDs that Onyx should silently ignore across all operations — reads, writes, cache, and subscriber
 // notifications. This is used to filter out keys formed from invalid/default IDs (e.g. "-1", "0",
 // "undefined", "null", "NaN") that can appear when an ID variable is accidentally coerced to string.
@@ -348,31 +349,6 @@ function multiGet(keys) {
 function tupleGet(keys) {
     return Promise.all(keys.map((key) => get(key)));
 }
-/**
- * Stores a subscription ID associated with a given key.
- *
- * @param subscriptionID - A subscription ID of the subscriber.
- * @param key - A key that the subscriber is subscribed to.
- */
-function storeKeyBySubscriptions(key, subscriptionID) {
-    if (!onyxKeyToSubscriptionIDs.has(key)) {
-        onyxKeyToSubscriptionIDs.set(key, []);
-    }
-    onyxKeyToSubscriptionIDs.get(key).push(subscriptionID);
-}
-/**
- * Deletes a subscription ID associated with its corresponding key.
- *
- * @param subscriptionID - The subscription ID to be deleted.
- */
-function deleteKeyBySubscriptions(subscriptionID) {
-    const subscriber = callbackToStateMapping[subscriptionID];
-    if (subscriber && onyxKeyToSubscriptionIDs.has(subscriber.key)) {
-        const updatedSubscriptionsIDs = onyxKeyToSubscriptionIDs.get(subscriber.key).filter((id) => id !== subscriptionID);
-        onyxKeyToSubscriptionIDs.set(subscriber.key, updatedSubscriptionsIDs);
-    }
-    lastConnectionCallbackData.delete(subscriptionID);
-}
 /** Returns current key names stored in persisted storage */
 function getAllKeys() {
     // When we've already read stored keys, resolve right away
@@ -395,28 +371,6 @@ function getAllKeys() {
     });
     return OnyxCache_1.default.captureTask(OnyxCache_1.TASK.GET_ALL_KEYS, promise);
 }
-/**
- * Tries to get a value from the cache. If the value is not present in cache it will return the default value or undefined.
- * If the requested key is a collection, it will return an object with all the collection members.
- */
-function tryGetCachedValue(key) {
-    let val = OnyxCache_1.default.get(key);
-    if (OnyxKeys_1.default.isCollectionKey(key)) {
-        const collectionData = OnyxCache_1.default.getCollectionData(key);
-        if (collectionData !== undefined) {
-            val = collectionData;
-        }
-        else {
-            // If we haven't loaded all keys yet, we can't determine if the collection exists
-            if (OnyxCache_1.default.getAllKeys().size === 0) {
-                return;
-            }
-            // Set an empty collection object for collections that exist but have no data
-            val = {};
-        }
-    }
-    return val;
-}
 function getCachedCollection(collectionKey, collectionMemberKeys) {
     // Use optimized collection data retrieval when cache is populated
     const collectionData = OnyxCache_1.default.getCollectionData(collectionKey);
@@ -457,187 +411,42 @@ function getCachedCollection(collectionKey, collectionMemberKeys) {
     return collection;
 }
 /**
- * When a collection of keys change, search for any callbacks matching the collection key and trigger those callbacks
- */
-function keysChanged(collectionKey, partialCollection, partialPreviousCollection) {
-    var _a;
-    const cachedCollection = getCachedCollection(collectionKey);
-    const previousCollection = partialPreviousCollection !== null && partialPreviousCollection !== void 0 ? partialPreviousCollection : {};
-    const changedMemberKeys = Object.keys(partialCollection !== null && partialCollection !== void 0 ? partialCollection : {});
-    // Add or remove the keys from the recentlyAccessedKeys list
-    for (const memberKey of changedMemberKeys) {
-        const value = partialCollection === null || partialCollection === void 0 ? void 0 : partialCollection[memberKey];
-        if (value !== null && value !== undefined) {
-            OnyxCache_1.default.addLastAccessedKey(memberKey, false);
-        }
-        else {
-            OnyxCache_1.default.removeLastAccessedKey(memberKey);
-        }
-    }
-    // Use indexed lookup instead of scanning all subscribers.
-    // We need subscribers for: (1) the collection key itself, and (2) individual changed member keys.
-    const collectionSubscriberIDs = (_a = onyxKeyToSubscriptionIDs.get(collectionKey)) !== null && _a !== void 0 ? _a : [];
-    const memberSubscriberIDs = [];
-    for (const memberKey of changedMemberKeys) {
-        const ids = onyxKeyToSubscriptionIDs.get(memberKey);
-        if (ids) {
-            for (const id of ids) {
-                memberSubscriberIDs.push(id);
-            }
-        }
-    }
-    // Notify collection-level subscribers
-    for (const subID of collectionSubscriberIDs) {
-        const subscriber = callbackToStateMapping[subID];
-        if (!subscriber || typeof subscriber.callback !== 'function') {
-            continue;
-        }
-        try {
-            lastConnectionCallbackData.set(subscriber.subscriptionID, { value: cachedCollection, matchedKey: subscriber.key });
-            subscriber.callback(cachedCollection, subscriber.key);
-        }
-        catch (error) {
-            Logger.logAlert(`[OnyxUtils.keysChanged] Subscriber callback threw an error for key '${collectionKey}': ${formatCaughtError(error)}`);
-        }
-    }
-    // Notify member-level subscribers (e.g. subscribed to `report_123`)
-    for (const subID of memberSubscriberIDs) {
-        const subscriber = callbackToStateMapping[subID];
-        if (!subscriber || typeof subscriber.callback !== 'function') {
-            continue;
-        }
-        if (cachedCollection[subscriber.key] === previousCollection[subscriber.key]) {
-            continue;
-        }
-        try {
-            const subscriberCallback = subscriber.callback;
-            subscriberCallback(cachedCollection[subscriber.key], subscriber.key);
-            lastConnectionCallbackData.set(subscriber.subscriptionID, {
-                value: cachedCollection[subscriber.key],
-                matchedKey: subscriber.key,
-            });
-        }
-        catch (error) {
-            Logger.logAlert(`[OnyxUtils.keysChanged] Subscriber callback threw an error for key '${collectionKey}': ${formatCaughtError(error)}`);
-        }
-    }
-}
-/**
- * When a key change happens, search for any callbacks matching the key or collection key and trigger those callbacks
+ * Notify subscribers of a single-key write. Wrapper over `onyxSubscriptionManager.notifyKey()`
+ * that also performs LRU bookkeeping for eviction.
  */
-function keyChanged(key, value, canUpdateSubscriber = () => true) {
-    var _a, _b;
-    // Add or remove this key from the recentlyAccessedKeys list
+function notifyKey(key, value) {
     if (value !== null && value !== undefined) {
         OnyxCache_1.default.addLastAccessedKey(key, OnyxKeys_1.default.isCollectionKey(key));
     }
     else {
         OnyxCache_1.default.removeLastAccessedKey(key);
     }
-    // We get the subscribers interested in the key that has just changed. If the subscriber's  key is a collection key then we will
-    // notify them if the key that changed is a collection member. Or if it is a regular key notify them when there is an exact match.
-    // Given the amount of times this function is called we need to make sure we are not iterating over all subscribers every time. On the other hand, we don't need to
-    // do the same in keysChanged, because we only call that function when a collection key changes, and it doesn't happen that often.
-    // For performance reason, we look for the given key and later if don't find it we look for the collection key, instead of checking if it is a collection key first.
-    let stateMappingKeys = (_a = onyxKeyToSubscriptionIDs.get(key)) !== null && _a !== void 0 ? _a : [];
-    const collectionKey = OnyxKeys_1.default.getCollectionKey(key);
-    if (collectionKey) {
-        // Getting the collection key from the specific key because only collection keys were stored in the mapping.
-        stateMappingKeys = [...stateMappingKeys, ...((_b = onyxKeyToSubscriptionIDs.get(collectionKey)) !== null && _b !== void 0 ? _b : [])];
-        if (stateMappingKeys.length === 0) {
-            return;
-        }
-    }
-    // Cache the collection snapshot per dispatch so all subscribers to the same collection
-    // see a consistent view, even if an earlier subscriber's callback synchronously writes
-    // to the same collection.
-    const cachedCollections = {};
-    for (const stateMappingKey of stateMappingKeys) {
-        const subscriber = callbackToStateMapping[stateMappingKey];
-        if (!subscriber || !OnyxKeys_1.default.isKeyMatch(subscriber.key, key) || !canUpdateSubscriber(subscriber)) {
-            continue;
-        }
-        // Subscriber is a regular call to connect() and provided a callback
-        if (typeof subscriber.callback === 'function') {
-            try {
-                const lastData = lastConnectionCallbackData.get(subscriber.subscriptionID);
-                if (lastData && lastData.matchedKey === key && lastData.value === value) {
-                    continue;
-                }
-                if (OnyxKeys_1.default.isCollectionKey(subscriber.key)) {
-                    // Cache once per dispatch to ensure all subscribers see a consistent snapshot
-                    // even if a previous callback synchronously wrote to the same collection.
-                    let cachedCollection = cachedCollections[subscriber.key];
-                    if (!cachedCollection) {
-                        cachedCollection = getCachedCollection(subscriber.key);
-                        cachedCollections[subscriber.key] = cachedCollection;
-                    }
-                    lastConnectionCallbackData.set(subscriber.subscriptionID, { value: cachedCollection, matchedKey: subscriber.key });
-                    subscriber.callback(cachedCollection, subscriber.key);
-                    continue;
-                }
-                const subscriberCallback = subscriber.callback;
-                subscriberCallback(value, key);
-                lastConnectionCallbackData.set(subscriber.subscriptionID, {
-                    value,
-                    matchedKey: key,
-                });
-                continue;
-            }
-            catch (error) {
-                Logger.logAlert(`[OnyxUtils.keyChanged] Subscriber callback threw an error for key '${key}': ${formatCaughtError(error)}`);
-            }
-            continue;
-        }
-        console.error('Warning: Found a matching subscriber to a key that changed, but no callback could be found.');
-    }
+    OnyxSubscriptionManager_1.default.notifyKey(key, value);
 }
 /**
- * Sends the data obtained from the keys to the connection.
+ * Notify subscribers of a batch collection update. Wrapper over
+ * `onyxSubscriptionManager.notifyCollection()` that also performs LRU bookkeeping per
+ * changed member.
  */
-function sendDataToConnection(mapping, matchedKey) {
-    var _a;
-    // If the mapping no longer exists then we should not send any data.
-    // This means our subscriber was disconnected.
-    if (!callbackToStateMapping[mapping.subscriptionID]) {
-        return;
-    }
-    // Always read the latest value from cache to avoid stale or duplicate data.
-    // For collection-root subscribers, read the full collection.
-    // For individual key subscribers, read just that key's value.
-    let value;
-    if (OnyxKeys_1.default.isCollectionKey(mapping.key)) {
-        const collection = getCachedCollection(mapping.key);
-        value = Object.keys(collection).length > 0 ? collection : undefined;
-    }
-    else {
-        value = OnyxCache_1.default.get(matchedKey !== null && matchedKey !== void 0 ? matchedKey : mapping.key);
-    }
-    // For regular callbacks, we never want to pass null values, but always just undefined if a value is not set in cache or storage.
-    value = value === null ? undefined : value;
-    const lastData = lastConnectionCallbackData.get(mapping.subscriptionID);
-    // If the value has not changed for the same key we do not need to trigger the callback.
-    // We compare matchedKey to avoid suppressing callbacks for different collection members
-    // that happen to have shallow-equal values (e.g. during hydration racing with set()).
-    if (lastData && lastData.matchedKey === matchedKey && (0, fast_equals_1.shallowEqual)(lastData.value, value)) {
-        return;
+function notifyCollection(collectionKey, partialCollection, partialPreviousCollection) {
+    const changedKeys = Object.keys(partialCollection !== null && partialCollection !== void 0 ? partialCollection : {});
+    for (const memberKey of changedKeys) {
+        const value = partialCollection === null || partialCollection === void 0 ? void 0 : partialCollection[memberKey];
+        if (value !== null && value !== undefined) {
+            OnyxCache_1.default.addLastAccessedKey(memberKey, false);
+        }
+        else {
+            OnyxCache_1.default.removeLastAccessedKey(memberKey);
+        }
     }
-    (_a = mapping.callback) === null || _a === void 0 ? void 0 : _a.call(mapping, value, matchedKey);
-}
-/**
- * Gets the data for a given an array of matching keys, combines them into an object, and sends the result back to the subscriber.
- */
-function getCollectionDataAndSendAsObject(matchingKeys, mapping) {
-    multiGet(matchingKeys).then(() => {
-        sendDataToConnection(mapping, mapping.key);
-    });
+    OnyxSubscriptionManager_1.default.notifyCollection(collectionKey, partialCollection, partialPreviousCollection);
 }
 /**
- * Remove a key from Onyx and update the subscribers
+ * Remove a key from Onyx and update the subscribers.
  */
 function remove(key) {
     OnyxCache_1.default.drop(key);
-    keyChanged(key, undefined);
+    notifyKey(key, undefined);
     if (OnyxKeys_1.default.isRamOnlyKey(key)) {
         return Promise.resolve();
     }
@@ -768,11 +577,57 @@ function broadcastUpdate(key, value, hasChanged) {
         return;
     }
     OnyxCache_1.default.set(key, value);
-    keyChanged(key, value);
+    notifyKey(key, value);
 }
 function hasPendingMergeForKey(key) {
     return !!mergeQueue[key];
 }
+function cancelPendingMergesForKey(key) {
+    delete mergeQueue[key];
+    delete mergeQueuePromise[key];
+}
+function cancelPendingMergesForCollection(collectionKey) {
+    for (const key of Object.keys(mergeQueue)) {
+        if (!OnyxKeys_1.default.isCollectionMemberKey(collectionKey, key)) {
+            continue;
+        }
+        cancelPendingMergesForKey(key);
+    }
+}
+function getPendingMergeEntries(keysToPreserve) {
+    return Object.entries(mergeQueue)
+        .filter(([key]) => !keysToPreserve.some((preserveKey) => OnyxKeys_1.default.isKeyMatch(preserveKey, key)))
+        .map(([key, queuedChanges]) => [key, queuedChanges, queuedChanges.length]);
+}
+function cancelPendingMerges(entries) {
+    for (const [key, queuedChanges, capturedLength] of entries) {
+        if (mergeQueue[key] !== queuedChanges) {
+            continue;
+        }
+        if (queuedChanges.length === capturedLength) {
+            cancelPendingMergesForKey(key);
+            continue;
+        }
+        queuedChanges.splice(0, capturedLength);
+        mergeQueuesWithStaleRead.add(queuedChanges);
+    }
+}
+function hasStaleMergeRead(queuedChanges) {
+    return mergeQueuesWithStaleRead.has(queuedChanges);
+}
+function cancelPendingMergesForKeys(keys) {
+    for (const key of keys) {
+        cancelPendingMergesForKey(key);
+    }
+}
+function cancelPendingMergesForNullMembers(collection) {
+    for (const [key, value] of Object.entries(collection)) {
+        if (value !== null) {
+            continue;
+        }
+        cancelPendingMergesForKey(key);
+    }
+}
 /**
  * Storage expects array like: [["@MyApp_user", value_1], ["@MyApp_key", value_2]]
  * This method transforms an object like {'@MyApp_user': myUserValue, '@MyApp_key': myKeyValue}
@@ -892,7 +747,7 @@ function initializeWithDefaultKeyStates() {
         // Notify subscribers about default key states so that any subscriber that connected
         // before init (e.g. during module load) receives the merged default values immediately
         for (const [key, value] of Object.entries(merged !== null && merged !== void 0 ? merged : {})) {
-            keyChanged(key, value);
+            notifyKey(key, value);
         }
     })
         .catch((error) => {
@@ -907,7 +762,7 @@ function initializeWithDefaultKeyStates() {
         // Notify subscribers about default key states so that any subscriber that connected
         // before init (e.g. during module load) receives the merged default values immediately
         for (const [key, value] of Object.entries(defaultKeyStates)) {
-            keyChanged(key, value);
+            notifyKey(key, value);
         }
     });
 }
@@ -934,97 +789,6 @@ function doAllCollectionItemsBelongToSameParent(collectionKey, collectionKeys) {
     }
     return !hasCollectionKeyCheckFailed;
 }
-/**
- * Subscribes to an Onyx key and listens to its changes.
- *
- * @param connectOptions The options object that will define the behavior of the connection.
- * @returns The subscription ID to use when calling `OnyxUtils.unsubscribeFromKey()`.
- */
-function subscribeToKey(connectOptions) {
-    const mapping = connectOptions;
-    const subscriptionID = lastSubscriptionID++;
-    callbackToStateMapping[subscriptionID] = mapping;
-    callbackToStateMapping[subscriptionID].subscriptionID = subscriptionID;
-    // When keyChanged is called, a key is passed and the method looks through all the Subscribers in callbackToStateMapping for the matching key to get the subscriptionID
-    // to avoid having to loop through all the Subscribers all the time (even when just one connection belongs to one key),
-    // We create a mapping from key to lists of subscriptionIDs to access the specific list of subscriptionIDs.
-    storeKeyBySubscriptions(mapping.key, callbackToStateMapping[subscriptionID].subscriptionID);
-    // Commit connection only after init passes
-    deferredInitTask.promise
-        // This first .then() adds a microtask tick for compatibility reasons and
-        // to ensure subscribers don't receive an extra initial callback before Onyx.update() data arrives.
-        .then(() => undefined)
-        .then(() => {
-        // Performance improvement
-        // If the mapping is connected to an onyx key that is not a collection
-        // we can skip the call to getAllKeys() and return an array with a single item
-        if (!!mapping.key && typeof mapping.key === 'string' && !OnyxKeys_1.default.isCollectionKey(mapping.key) && OnyxCache_1.default.getAllKeys().has(mapping.key)) {
-            return new Set([mapping.key]);
-        }
-        return getAllKeys();
-    })
-        .then((keys) => {
-        // We search all the keys in storage to see if any are a "match" for the subscriber we are connecting so that we
-        // can send data back to the subscriber. Note that multiple keys can match as a subscriber could either be
-        // subscribed to a "collection key" or a single key.
-        const matchingKeys = [];
-        // Performance optimization: For single key subscriptions, avoid O(n) iteration
-        if (!OnyxKeys_1.default.isCollectionKey(mapping.key)) {
-            if (keys.has(mapping.key)) {
-                matchingKeys.push(mapping.key);
-            }
-        }
-        else {
-            // Collection case - need to iterate through all keys to find matches (O(n))
-            for (const key of keys) {
-                if (!OnyxKeys_1.default.isKeyMatch(mapping.key, key)) {
-                    continue;
-                }
-                matchingKeys.push(key);
-            }
-        }
-        // If the key being connected to does not exist we initialize the value with null. For subscribers that connected
-        // directly via connect() they will simply get a null value sent to them without any information about which key matched
-        // since there are none matched.
-        if (matchingKeys.length === 0) {
-            if (mapping.key) {
-                OnyxCache_1.default.addNullishStorageKey(mapping.key);
-            }
-            const matchedKey = OnyxKeys_1.default.isCollectionKey(mapping.key) ? mapping.key : undefined;
-            // Here we cannot use batching because the nullish value is expected to be set immediately for default props
-            // or they will be undefined.
-            sendDataToConnection(mapping, matchedKey);
-            return;
-        }
-        // When using a callback subscriber, a subscription to a collection key combines all matching
-        // member values into a single object and makes one call with the whole collection object.
-        if (typeof mapping.callback === 'function') {
-            if (OnyxKeys_1.default.isCollectionKey(mapping.key)) {
-                getCollectionDataAndSendAsObject(matchingKeys, mapping);
-                return;
-            }
-            // If we are not subscribed to a collection key then there's only a single key to send an update for.
-            get(mapping.key).then(() => sendDataToConnection(mapping, mapping.key));
-            return;
-        }
-        console.error('Warning: Onyx.connect() was found without a callback');
-    });
-    // The subscriptionID is returned back to the caller so that it can be used to clean up the connection when it's no longer needed
-    // by calling OnyxUtils.unsubscribeFromKey(subscriptionID).
-    return subscriptionID;
-}
-/**
- * Disconnects and removes the listener from the Onyx key.
- *
- * @param subscriptionID Subscription ID returned by calling `OnyxUtils.subscribeToKey()`.
- */
-function unsubscribeFromKey(subscriptionID) {
-    if (!callbackToStateMapping[subscriptionID]) {
-        return;
-    }
-    deleteKeyBySubscriptions(subscriptionID);
-    delete callbackToStateMapping[subscriptionID];
-}
 function updateSnapshots(data, mergeFn) {
     const snapshotCollectionKey = getSnapshotKey();
     if (!snapshotCollectionKey)
@@ -1197,14 +961,17 @@ function multiSetWithRetry(data, retryAttempt) {
         }, {});
     }
     const { pairs: keyValuePairsToSet, keysToRemove: removalCandidates } = OnyxUtils.prepareKeyValuePairsForStorage(newData, true);
+    if (!retryAttempt) {
+        cancelPendingMergesForKeys(removalCandidates);
+    }
     // Removals of keys that are neither cached nor persisted are no-ops and skipped. When the key
     // index has not been loaded yet (empty set), keep the removal to be safe.
     const persistedKeys = OnyxCache_1.default.getAllKeys();
     const keysToRemove = removalCandidates.filter((key) => OnyxCache_1.default.get(key) !== undefined || persistedKeys.size === 0 || persistedKeys.has(key));
     // Group collection members by their parent collection key so each collection can be notified
-    // via a single batched keysChanged() call instead of one keyChanged() per member. For each
+    // via a single batched notifyCollection() call instead of one notifyKey() per member. For each
     // collection, `partial` holds the new values being set and `previous` holds the cached values
-    // from before the set, which keysChanged() uses to skip subscribers whose value didn't change.
+    // from before the set, which notifyCollection() uses to skip subscribers whose value didn't change.
     const collectionBatches = new Map();
     for (const [key, value] of keyValuePairsToSet) {
         // When we use multiSet to set a key we want to clear the current delta changes from Onyx.merge that were queued
@@ -1214,7 +981,7 @@ function multiSetWithRetry(data, retryAttempt) {
         }
         const collectionKey = OnyxKeys_1.default.getCollectionKey(key);
         if (collectionKey && OnyxKeys_1.default.isCollectionMemberKey(collectionKey, key)) {
-            // Capture the previous cached value BEFORE calling cache.set() so keysChanged()
+            // Capture the previous cached value before calling cache.set() so notifyCollection()
             // can diff old vs new per-member.
             const previousValue = OnyxCache_1.default.get(key);
             OnyxCache_1.default.set(key, value);
@@ -1227,14 +994,13 @@ function multiSetWithRetry(data, retryAttempt) {
             batch.previous[key] = previousValue;
         }
         else {
-            // Non-collection keys are notified inline (cache.set + keyChanged in iteration order)
+            // Non-collection keys are notified inline (cache.set + notifyKey in iteration order)
             // so re-entrant callbacks (e.g. Onyx.set inside a callback) see consistent cache
             // and subscriber state, matching the original per-key notification semantics.
             OnyxCache_1.default.set(key, value);
             // Skip subscriber notification on retry — already notified on attempt 0.
-            // Collection-root subscribers re-fire on every keyChanged by contract.
             if (!retryAttempt) {
-                keyChanged(key, value);
+                notifyKey(key, value);
             }
         }
     }
@@ -1255,15 +1021,15 @@ function multiSetWithRetry(data, retryAttempt) {
         }
         else if (!retryAttempt) {
             // Skip subscriber notification on retry — already notified on attempt 0.
-            keyChanged(key, undefined);
+            notifyKey(key, undefined);
         }
     }
-    // One keysChanged() per collection — fires each collection-level subscriber once and lets
-    // keysChanged() internally decide which individual member subscribers need notification.
+    // One notifyCollection() per collection: fires each collection-level subscriber once and lets
+    // notifyCollection() internally decide which individual member subscribers need notification.
     // Skip on retry — already notified on attempt 0 (see same-reason comment above).
     if (!retryAttempt) {
         for (const [collectionKey, batch] of collectionBatches) {
-            keysChanged(collectionKey, batch.partial, batch.previous);
+            notifyCollection(collectionKey, batch.partial, batch.previous);
         }
     }
     const keyValuePairsToStore = keyValuePairsToSet.filter((keyValuePair) => {
@@ -1321,6 +1087,9 @@ function setCollectionWithRetry({ collectionKey, collection }, retryAttempt) {
         }, {});
     }
     resultCollectionKeys = Object.keys(resultCollection);
+    if (!retryAttempt) {
+        cancelPendingMergesForCollection(collectionKey);
+    }
     return OnyxUtils.getAllKeys().then((persistedKeys) => {
         const mutableCollection = Object.assign({}, resultCollection);
         for (const key of persistedKeys) {
@@ -1335,18 +1104,17 @@ function setCollectionWithRetry({ collectionKey, collection }, retryAttempt) {
         const { pairs: keyValuePairs, keysToRemove: removalCandidates } = OnyxUtils.prepareKeyValuePairsForStorage(mutableCollection, true);
         // Removals of keys that are neither cached nor persisted are no-ops and skipped.
         const keysToRemove = removalCandidates.filter((key) => OnyxCache_1.default.get(key) !== undefined || persistedKeys.has(key));
-        // Snapshot before cache mutations so keysChanged() can diff removed members.
+        // Capture the previous collection before cache mutations so notifyCollection() can diff removed members.
         const previousCollection = OnyxUtils.getCachedCollection(collectionKey);
         for (const [key, value] of keyValuePairs)
             OnyxCache_1.default.set(key, value);
         for (const key of keysToRemove)
             OnyxCache_1.default.drop(key);
         // Skip subscriber notification on retry — already notified on attempt 0.
-        // Collection-root subscribers re-fire on every keysChanged by contract.
         if (!retryAttempt) {
             // Removed members are notified as undefined, matching mergeCollection/multiSet.
             const partialForNotify = Object.fromEntries(Object.entries(mutableCollection).map(([key, value]) => [key, value !== null && value !== void 0 ? value : undefined]));
-            keysChanged(collectionKey, partialForNotify, previousCollection);
+            notifyCollection(collectionKey, partialForNotify, previousCollection);
         }
         // RAM-only keys are not supposed to be saved to storage
         if (OnyxKeys_1.default.isRamOnlyKey(collectionKey)) {
@@ -1408,6 +1176,9 @@ function mergeCollectionWithPatches({ collectionKey, collection, mergeReplaceNul
         }, {});
     }
     resultCollectionKeys = Object.keys(resultCollection);
+    if (!retryAttempt) {
+        cancelPendingMergesForNullMembers(resultCollection);
+    }
     return getAllKeys()
         .then((persistedKeys) => {
         // Split to keys that exist in storage and keys that don't. Null members are collected
@@ -1473,13 +1244,13 @@ function mergeCollectionWithPatches({ collectionKey, collection, mergeReplaceNul
         // promise-chain depth; slow path batches the misses into one Storage.multiGet.
         const hasColdExistingKey = existingKeys.some((key) => !OnyxCache_1.default.hasCacheForKey(key));
         // Swallow pre-warm read failures so a transient Storage.multiGet rejection doesn't
-        // skip the cache.merge() + keysChanged() below. Subscribers still see the merge even
+        // skip the cache.merge() + notifyCollection() below. Subscribers still see the merge even
         // when storage reads fail.
         const prewarmPromise = hasColdExistingKey
             ? multiGet(existingKeys).catch((err) => Logger.logInfo(`mergeCollectionWithPatches pre-warm failed; proceeding with cache-only merge. Error: ${err}`))
             : Promise.resolve();
         return prewarmPromise.then(() => {
-            // Snapshot previous values from the (now-warm) cache for keysChanged's diff, then update
+            // Capture previous values from the (now-warm) cache for the subscriber diff, then update
             // cache and notify subscribers synchronously BEFORE issuing storage writes. This matches
             // the cache-first / storage-second invariant followed by every other Onyx write method
             // (setWithRetry, applyMerge, setCollectionWithRetry, partialSetCollection, clear),
@@ -1488,12 +1259,11 @@ function mergeCollectionWithPatches({ collectionKey, collection, mergeReplaceNul
             const previousCollection = getCachedCollection(collectionKey, existingKeys);
             OnyxCache_1.default.merge(finalMergedCollection);
             // Skip subscriber notification on retry — already notified on attempt 0.
-            // Collection-root subscribers re-fire on every keysChanged by contract.
             if (!retryAttempt) {
                 const partialForNotify = keysToRemove.length > 0 ? Object.assign(Object.assign({}, finalMergedCollection), Object.fromEntries(keysToRemove.map((key) => [key, undefined]))) : finalMergedCollection;
                 const previousForNotify = keysToRemove.length > 0 ? Object.assign(Object.assign({}, previousCollection), removedPreviousValues) : previousCollection;
                 if (Object.keys(partialForNotify).length > 0) {
-                    keysChanged(collectionKey, partialForNotify, previousForNotify);
+                    notifyCollection(collectionKey, partialForNotify, previousForNotify);
                 }
             }
             const promises = [];
@@ -1561,24 +1331,26 @@ function partialSetCollection({ collectionKey, collection }, retryAttempt) {
         }, {});
     }
     resultCollectionKeys = Object.keys(resultCollection);
+    if (!retryAttempt) {
+        cancelPendingMergesForKeys(resultCollectionKeys);
+    }
     return getAllKeys().then((persistedKeys) => {
         const mutableCollection = Object.assign({}, resultCollection);
         const existingKeys = resultCollectionKeys.filter((key) => persistedKeys.has(key));
         const { pairs: keyValuePairs, keysToRemove: removalCandidates } = prepareKeyValuePairsForStorage(mutableCollection, true);
         // Removals of keys that are neither cached nor persisted are no-ops and skipped.
         const keysToRemove = removalCandidates.filter((key) => OnyxCache_1.default.get(key) !== undefined || persistedKeys.has(key));
-        // Snapshot before cache mutations so keysChanged() can diff removed members.
+        // Capture the previous collection before cache mutations so notifyCollection() can diff removed members.
         const previousCollection = getCachedCollection(collectionKey, existingKeys);
         for (const [key, value] of keyValuePairs)
             OnyxCache_1.default.set(key, value);
         for (const key of keysToRemove)
             OnyxCache_1.default.drop(key);
         // Skip subscriber notification on retry — already notified on attempt 0.
-        // Collection-root subscribers re-fire on every keysChanged by contract.
         if (!retryAttempt) {
             // Removed members are notified as undefined, matching mergeCollection/multiSet.
             const partialForNotify = Object.fromEntries(Object.entries(mutableCollection).map(([key, value]) => [key, value !== null && value !== void 0 ? value : undefined]));
-            keysChanged(collectionKey, partialForNotify, previousCollection);
+            notifyCollection(collectionKey, partialForNotify, previousCollection);
         }
         if (OnyxKeys_1.default.isRamOnlyKey(collectionKey)) {
             sendActionToDevTools(METHOD.SET_COLLECTION, undefined, mutableCollection);
@@ -1605,18 +1377,23 @@ function logKeyChanged(onyxMethod, key, value, hasChanged) {
 function logKeyRemoved(onyxMethod, key) {
     Logger.logInfo(`${onyxMethod} called for key: ${key} => null passed, so key was removed`);
 }
+/**
+ * Put Onyx back to "not initialised" state, useful for tests that need a cold start.
+ */
+function resetDeferredInitTask() {
+    deferredInitTask = (0, createDeferredTask_1.default)();
+}
 /**
  * Clear internal variables used in this file, useful in test environments.
  */
 function clearOnyxUtilsInternals() {
     mergeQueue = {};
     mergeQueuePromise = {};
-    callbackToStateMapping = {};
-    onyxKeyToSubscriptionIDs = new Map();
-    lastConnectionCallbackData = new Map();
+    PendingWrites_1.default.clearPendingWrites();
 }
 const OnyxUtils = {
     METHOD,
+    NOT_DELIVERED,
     getMergeQueue,
     getMergeQueuePromise,
     getDefaultKeyStates,
@@ -1626,18 +1403,18 @@ const OnyxUtils = {
     sendActionToDevTools,
     get,
     getAllKeys,
-    tryGetCachedValue,
     getCachedCollection,
-    keysChanged,
-    keyChanged,
-    sendDataToConnection,
-    getCollectionDataAndSendAsObject,
+    notifyKey,
+    notifyCollection,
     remove,
     reportStorageQuota,
     resetDiskPressureLogThrottle,
     retryOperation,
     broadcastUpdate,
     hasPendingMergeForKey,
+    getPendingMergeEntries,
+    cancelPendingMerges,
+    hasStaleMergeRead,
     prepareKeyValuePairsForStorage,
     mergeChanges,
     mergeAndMarkChanges,
@@ -1647,14 +1424,10 @@ const OnyxUtils = {
     tupleGet,
     isValidNonEmptyCollectionForMerge,
     doAllCollectionItemsBelongToSameParent,
-    subscribeToKey,
-    unsubscribeFromKey,
     getSkippableCollectionMemberIDs,
     setSkippableCollectionMemberIDs,
     getSnapshotMergeKeys,
     setSnapshotMergeKeys,
-    storeKeyBySubscriptions,
-    deleteKeyBySubscriptions,
     reduceCollectionWithSelector,
     updateSnapshots,
     mergeCollectionWithPatches,