react-native-onyx 3.0.115 → 3.0.117

package/API.md

@@ -78,36 +78,40 @@ 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.
 
 **Kind**: global function  
-**Returns**: The connection object to use when calling `Onyx.disconnect()`.  
+**Returns**: The `Connection` handle to use when calling `Onyx.disconnect()`.  
 
 | Param | Description |
 | --- | --- |
 | connectOptions | The options object that will define the behavior of the connection. |
 | connectOptions.key | The Onyx key to subscribe to. |
 | connectOptions.callback | A function that will be called when the Onyx data we are subscribed changes. |
-| connectOptions.selector | This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render        when the subset of data changes. Otherwise, any change of data on any property would normally        cause the component to re-render (and that can be expensive from a performance standpoint). |
 
 **Example**  
 ```ts
-const connection = Onyx.connectWithoutView({
+const connection = Onyx.connect({
     key: ONYXKEYS.SESSION,
     callback: onSessionChange,
 });
 ```
+
+For a collection root key, the callback fires with the entire frozen collection
+object whenever any member changes; signature `(collection, collectionKey)`.
+For any other key, the callback fires with the value at that key; signature
+`(value, key)`. Initial fire is deferred via `scheduleInitialSubscriberNotification` so it reads
+cache after any same-tick writes have applied.
 <a name="connectWithoutView"></a>
 
 ## connectWithoutView(connectOptions) ⇒
 Connects to an Onyx key given the options passed and listens to its changes.
 
 **Kind**: global function  
-**Returns**: The connection object to use when calling `Onyx.disconnect()`.  
+**Returns**: The `Connection` handle to use when calling `Onyx.disconnect()`.  
 
 | Param | Description |
 | --- | --- |
 | connectOptions | The options object that will define the behavior of the connection. |
 | connectOptions.key | The Onyx key to subscribe to. |
 | connectOptions.callback | A function that will be called when the Onyx data we are subscribed changes. |
-| connectOptions.selector | This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render        when the subset of data changes. Otherwise, any change of data on any property would normally        cause the component to re-render (and that can be expensive from a performance standpoint). |
 
 **Example**  
 ```ts
@@ -116,6 +120,12 @@ const connection = Onyx.connectWithoutView({
     callback: onSessionChange,
 });
 ```
+
+For a collection root key, the callback fires with the entire frozen collection
+object whenever any member changes; signature `(collection, collectionKey)`.
+For any other key, the callback fires with the value at that key; signature
+`(value, key)`. Initial fire is deferred via `scheduleInitialSubscriberNotification` so it reads
+cache after any same-tick writes have applied.
 <a name="disconnect"></a>
 
 ## disconnect(connection)

package/README.md

@@ -9,7 +9,7 @@ Awesome persistent storage solution wrapped in a Pub/Sub library.
 - Onyx allows other code to subscribe to changes in data, and then publishes change events whenever data is changed
 - Anything needing to read Onyx data needs to:
     1. Know what key the data is stored in (for web, you can find this by looking in the JS console > Application > local storage)
-    2. Subscribe to changes of the data for a particular key or set of keys. React function components use the `useOnyx()` hook and non-React libs use `Onyx.connect()`.
+    2. Subscribe to changes of the data for a particular key or set of keys. React function components use the `useOnyx()` hook and non-React libs use `Onyx.connectWithoutView()`.
     3. Get initialized with the current value of that key from persistent storage (Onyx does this by calling `setState()` or triggering the `callback` with the values currently on disk as part of the connection process)
 - Subscribing to Onyx keys is done using a constant defined in `ONYXKEYS`. Each Onyx key represents either a collection of items or a specific entry in storage. For example, since all reports are stored as individual keys like `report_1234`, if code needs to know about all the reports (e.g. display a list of them in the nav menu), then it would subscribe to the key `ONYXKEYS.COLLECTION.REPORT`.
 
@@ -120,20 +120,20 @@ You should avoid arrays as much as possible. They do not work well with `merge()
 
 ## Subscribing to data changes
 
-To set up a basic subscription for a given key use the `Onyx.connect()` method.
+To set up a basic subscription for a given key outside of a React component use the `Onyx.connectWithoutView()` method. It returns a connection handle.
 
 ```javascript
 let session;
-const connectionID = Onyx.connect({
+const connection = Onyx.connectWithoutView({
     key: ONYXKEYS.SESSION,
     callback: (val) => session = val || {},
 });
 ```
 
-To teardown the subscription call `Onyx.disconnect()` with the `connectionID` returned from `Onyx.connect()`. It's recommended to clean up subscriptions anytime you are connecting from within a function to prevent memory leaks.
+To teardown the subscription call `Onyx.disconnect()` with the connection returned from `Onyx.connectWithoutView()`. It's recommended to clean up subscriptions anytime you are connecting from within a function to prevent memory leaks.
 
 ```javascript
-Onyx.disconnect(connectionID);
+Onyx.disconnect(connection);
 ```
 
 We can also access values inside React function components via the `useOnyx()` [hook](https://react.dev/reference/react/hooks). When the data changes the component will re-render.
@@ -204,7 +204,7 @@ export default App;
   
 * It is VERY important to NOT use empty string default values like `report.policyID || ''`. This results in the key returned to `useOnyx` as `policies_`, which subscribes to the ENTIRE POLICY COLLECTION and is most assuredly not what you were intending. You can use a default of `0` (as long as you are reasonably sure that there is never a policyID=0). This allows Onyx to return `undefined` as the value of the policy key, which is handled by `useOnyx` appropriately.
 
-It's also beneficial to use a [selector](https://github.com/Expensify/react-native-onyx/blob/main/API.md#connectmapping--number) with the mapping in case you need to grab a single item in a collection (like a single report action).
+It's also beneficial to use `useOnyx()`'s `selector` option in case you need to grab a single item in a collection (like a single report action).
 
 ## Collections
 
@@ -257,7 +257,7 @@ export default MyComponent;
 This will add a prop to the component called `allReports` which is an object of collection member key/values. Changes to the individual member keys will modify the entire object and new props will be passed with each individual key update. The prop doesn't update on the initial rendering of the component until the entire collection has been read out of Onyx.
 
 ```js
-Onyx.connect({key: ONYXKEYS.COLLECTION.REPORT}, callback: (allReports, collectionKey) => {...});
+Onyx.connectWithoutView({key: ONYXKEYS.COLLECTION.REPORT, callback: (allReports, collectionKey) => {...}});
 ```
 
 This will fire the callback once with the entire collection initially and later with an updated version of the collection when individual keys update.
@@ -293,7 +293,7 @@ function signOut() {
 `Onyx.exportState()` returns a plain object containing persisted keys and values from the active storage provider. It works on native and web without opening another database connection. The export excludes stale persisted rows for keys that are now RAM-only. Current RAM-only values and writes still in progress are never included. Treat the returned object and its nested values as read-only because some providers return references to their stored values. The result can contain sensitive data; callers should redact it before sharing.
 
 ## Storage Providers
-`Onyx.get`, `Onyx.set`, and the rest of the API accesses the underlying storage
+`Onyx.set`, `Onyx.merge`, and the rest of the API accesses the underlying storage
 differently depending on the platform
 
 Under the hood storage access calls are delegated to a [`StorageProvider`](lib/storage/index.js)

package/dist/Onyx.d.ts

@@ -1,6 +1,5 @@
 import * as Logger from './Logger';
-import type { CollectionKeyBase, ConnectOptions, InitOptions, OnyxKey, OnyxMergeCollectionInput, OnyxMergeInput, OnyxMultiSetInput, OnyxSetCollectionInput, OnyxSetInput, OnyxUpdate, OnyxValue, SetOptions } from './types';
-import type { Connection } from './OnyxConnectionManager';
+import type { CollectionKeyBase, Connection, ConnectOptions, InitOptions, OnyxKey, OnyxMergeCollectionInput, OnyxMergeInput, OnyxMultiSetInput, OnyxSetCollectionInput, OnyxSetInput, OnyxUpdate, OnyxValue, SetOptions } from './types';
 /** Initialize the store with actions and listening for storage events */
 declare function init({ keys, initialKeyStates, evictableKeys, shouldSyncMultipleInstances, enableDevTools, skippableCollectionMemberIDs, ramOnlyKeys, snapshotMergeKeys, }: InitOptions): void;
 /**
@@ -9,20 +8,22 @@ declare function init({ keys, initialKeyStates, evictableKeys, shouldSyncMultipl
  *
  * @example
  * ```ts
- * const connection = Onyx.connectWithoutView({
+ * const connection = Onyx.connect({
  *     key: ONYXKEYS.SESSION,
  *     callback: onSessionChange,
  * });
  * ```
  *
+ * For a collection root key, the callback fires with the entire frozen collection
+ * object whenever any member changes; signature `(collection, collectionKey)`.
+ * For any other key, the callback fires with the value at that key; signature
+ * `(value, key)`. Initial fire is deferred via `scheduleInitialSubscriberNotification` so it reads
+ * cache after any same-tick writes have applied.
+ *
  * @param connectOptions The options object that will define the behavior of the connection.
  * @param connectOptions.key The Onyx key to subscribe to.
  * @param connectOptions.callback A function that will be called when the Onyx data we are subscribed changes.
- * @param connectOptions.selector This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**
- *        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render
- *        when the subset of data changes. Otherwise, any change of data on any property would normally
- *        cause the component to re-render (and that can be expensive from a performance standpoint).
- * @returns The connection object to use when calling `Onyx.disconnect()`.
+ * @returns The `Connection` handle to use when calling `Onyx.disconnect()`.
  */
 declare function connect<TKey extends OnyxKey>(connectOptions: ConnectOptions<TKey>): Connection;
 /**
@@ -36,14 +37,16 @@ declare function connect<TKey extends OnyxKey>(connectOptions: ConnectOptions<TK
  * });
  * ```
  *
+ * For a collection root key, the callback fires with the entire frozen collection
+ * object whenever any member changes; signature `(collection, collectionKey)`.
+ * For any other key, the callback fires with the value at that key; signature
+ * `(value, key)`. Initial fire is deferred via `scheduleInitialSubscriberNotification` so it reads
+ * cache after any same-tick writes have applied.
+ *
  * @param connectOptions The options object that will define the behavior of the connection.
  * @param connectOptions.key The Onyx key to subscribe to.
  * @param connectOptions.callback A function that will be called when the Onyx data we are subscribed changes.
- * @param connectOptions.selector This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**
- *        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render
- *        when the subset of data changes. Otherwise, any change of data on any property would normally
- *        cause the component to re-render (and that can be expensive from a performance standpoint).
- * @returns The connection object to use when calling `Onyx.disconnect()`.
+ * @returns The `Connection` handle to use when calling `Onyx.disconnect()`.
  */
 declare function connectWithoutView<TKey extends OnyxKey>(connectOptions: ConnectOptions<TKey>): Connection;
 /**
@@ -182,4 +185,4 @@ declare const Onyx: {
     registerLogger: typeof Logger.registerLogger;
 };
 export default Onyx;
-export type { OnyxUpdate, ConnectOptions, SetOptions };
+export type { OnyxUpdate, ConnectOptions, SetOptions, Connection };

package/dist/Onyx.js

@@ -43,8 +43,9 @@ const utils_1 = __importDefault(require("./utils"));
 const DevTools_1 = __importStar(require("./DevTools"));
 const OnyxUtils_1 = __importDefault(require("./OnyxUtils"));
 const OnyxKeys_1 = __importDefault(require("./OnyxKeys"));
+const PendingWrites_1 = __importDefault(require("./PendingWrites"));
 const logMessages_1 = __importDefault(require("./logMessages"));
-const OnyxConnectionManager_1 = __importDefault(require("./OnyxConnectionManager"));
+const OnyxSubscriptionManager_1 = __importDefault(require("./OnyxSubscriptionManager"));
 const OnyxMerge_1 = __importDefault(require("./OnyxMerge"));
 /** Initialize the store with actions and listening for storage events */
 function init({ keys = {}, initialKeyStates = {}, evictableKeys = [], shouldSyncMultipleInstances = !!global.localStorage, enableDevTools = true, skippableCollectionMemberIDs = [], ramOnlyKeys = [], snapshotMergeKeys = [], }) {
@@ -70,7 +71,7 @@ function init({ keys = {}, initialKeyStates = {}, evictableKeys = [], shouldSync
                 }
                 const collectionKey = OnyxKeys_1.default.getCollectionKey(key);
                 const isCollectionMember = !!collectionKey && OnyxKeys_1.default.isCollectionMemberKey(collectionKey, key);
-                // Capture the previous cached value BEFORE cache.set() so keysChanged() can diff old vs new per member.
+                // Capture the previous cached value before cache.set() so notifyCollection() can diff old vs new per member.
                 const previousValue = isCollectionMember ? OnyxCache_1.default.get(key) : undefined;
                 OnyxCache_1.default.set(key, value);
                 if (isCollectionMember && collectionKey) {
@@ -89,14 +90,14 @@ function init({ keys = {}, initialKeyStates = {}, evictableKeys = [], shouldSync
                     individual.push([key, value]);
                 }
             }
-            // Non-collection keys: notify individually, matching keyChanged() semantics for exact keys.
+            // Non-collection keys: notify individually, matching notifyKey() semantics for exact keys.
             for (const [key, value] of individual) {
-                OnyxUtils_1.default.keyChanged(key, value);
+                OnyxUtils_1.default.notifyKey(key, value);
             }
-            // One keysChanged() per collection notifies the collection-root subscriber once and lets
-            // keysChanged() decide which individual member subscribers actually changed.
+            // One notifyCollection() per collection notifies the collection-root subscriber once and lets
+            // notifyCollection() decide which individual member subscribers actually changed.
             for (const [collectionKey, { partial, previous }] of collectionBatches) {
-                OnyxUtils_1.default.keysChanged(collectionKey, partial, previous);
+                OnyxUtils_1.default.notifyCollection(collectionKey, partial, previous);
             }
         });
     }
@@ -115,23 +116,89 @@ function init({ keys = {}, initialKeyStates = {}, evictableKeys = [], shouldSync
  *
  * @example
  * ```ts
- * const connection = Onyx.connectWithoutView({
+ * const connection = Onyx.connect({
  *     key: ONYXKEYS.SESSION,
  *     callback: onSessionChange,
  * });
  * ```
  *
+ * For a collection root key, the callback fires with the entire frozen collection
+ * object whenever any member changes; signature `(collection, collectionKey)`.
+ * For any other key, the callback fires with the value at that key; signature
+ * `(value, key)`. Initial fire is deferred via `scheduleInitialSubscriberNotification` so it reads
+ * cache after any same-tick writes have applied.
+ *
  * @param connectOptions The options object that will define the behavior of the connection.
  * @param connectOptions.key The Onyx key to subscribe to.
  * @param connectOptions.callback A function that will be called when the Onyx data we are subscribed changes.
- * @param connectOptions.selector This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**
- *        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render
- *        when the subset of data changes. Otherwise, any change of data on any property would normally
- *        cause the component to re-render (and that can be expensive from a performance standpoint).
- * @returns The connection object to use when calling `Onyx.disconnect()`.
+ * @returns The `Connection` handle to use when calling `Onyx.disconnect()`.
  */
 function connect(connectOptions) {
-    return OnyxConnectionManager_1.default.connect(connectOptions);
+    const { key, callback } = connectOptions;
+    let active = true;
+    let unsubscribeFn = null;
+    const startSubscription = () => {
+        if (!active) {
+            return;
+        }
+        if (OnyxKeys_1.default.isCollectionKey(key)) {
+            // Collection-root mode: dedup skips identical collection refs. Initial fire delivers
+            // the current collection object: frozen `{}` for an empty-but-known collection,
+            // `undefined` only if the collection key has not been seen yet.
+            let lastDeliveredCollection = OnyxUtils_1.default.NOT_DELIVERED;
+            const deliverCollection = (rawCollection, k) => {
+                if (Object.is(lastDeliveredCollection, rawCollection)) {
+                    return;
+                }
+                lastDeliveredCollection = rawCollection;
+                callback === null || callback === void 0 ? void 0 : callback(rawCollection, k);
+            };
+            unsubscribeFn = OnyxSubscriptionManager_1.default.subscribe(key, (value, k) => {
+                deliverCollection(value, k);
+            });
+            PendingWrites_1.default.scheduleInitialSubscriberNotification(key, () => {
+                if (!active) {
+                    return;
+                }
+                deliverCollection(OnyxSubscriptionManager_1.default.getState(key), key);
+            });
+            return;
+        }
+        // Non-collection key (or a specific collection member): single-value subscription.
+        let lastDelivered = OnyxUtils_1.default.NOT_DELIVERED;
+        const deliverValue = (value, k) => {
+            if (Object.is(lastDelivered, value)) {
+                return;
+            }
+            lastDelivered = value;
+            callback === null || callback === void 0 ? void 0 : callback(value, k);
+        };
+        unsubscribeFn = OnyxSubscriptionManager_1.default.subscribe(key, (value, k) => {
+            deliverValue(value, k);
+        });
+        PendingWrites_1.default.scheduleInitialSubscriberNotification(key, () => {
+            if (!active) {
+                return;
+            }
+            deliverValue(OnyxSubscriptionManager_1.default.getState(key), key);
+        });
+    };
+    OnyxUtils_1.default.afterInit(() => {
+        startSubscription();
+        return Promise.resolve();
+    });
+    return {
+        unsubscribe: () => {
+            if (!active) {
+                return;
+            }
+            active = false;
+            if (unsubscribeFn) {
+                unsubscribeFn();
+                unsubscribeFn = null;
+            }
+        },
+    };
 }
 /**
  * Connects to an Onyx key given the options passed and listens to its changes.
@@ -144,17 +211,19 @@ function connect(connectOptions) {
  * });
  * ```
  *
+ * For a collection root key, the callback fires with the entire frozen collection
+ * object whenever any member changes; signature `(collection, collectionKey)`.
+ * For any other key, the callback fires with the value at that key; signature
+ * `(value, key)`. Initial fire is deferred via `scheduleInitialSubscriberNotification` so it reads
+ * cache after any same-tick writes have applied.
+ *
  * @param connectOptions The options object that will define the behavior of the connection.
  * @param connectOptions.key The Onyx key to subscribe to.
  * @param connectOptions.callback A function that will be called when the Onyx data we are subscribed changes.
- * @param connectOptions.selector This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**
- *        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render
- *        when the subset of data changes. Otherwise, any change of data on any property would normally
- *        cause the component to re-render (and that can be expensive from a performance standpoint).
- * @returns The connection object to use when calling `Onyx.disconnect()`.
+ * @returns The `Connection` handle to use when calling `Onyx.disconnect()`.
  */
 function connectWithoutView(connectOptions) {
-    return OnyxConnectionManager_1.default.connect(connectOptions);
+    return connect(connectOptions);
 }
 /**
  * Disconnects and removes the listener from the Onyx key.
@@ -172,7 +241,10 @@ function connectWithoutView(connectOptions) {
  * @param connection Connection object returned by calling `Onyx.connect()` or `Onyx.connectWithoutView()`.
  */
 function disconnect(connection) {
-    OnyxConnectionManager_1.default.disconnect(connection);
+    if (!connection) {
+        return;
+    }
+    connection.unsubscribe();
 }
 /**
  * Write a value to our store with the given key
@@ -182,7 +254,7 @@ function disconnect(connection) {
  * @param options optional configuration object
  */
 function set(key, value, options) {
-    return OnyxUtils_1.default.afterInit(() => OnyxUtils_1.default.setWithRetry({ key, value, options }));
+    return PendingWrites_1.default.trackPendingWrite(key, OnyxUtils_1.default.afterInit(() => OnyxUtils_1.default.setWithRetry({ key, value, options })));
 }
 /**
  * Sets multiple keys and values
@@ -192,7 +264,7 @@ function set(key, value, options) {
  * @param data object keyed by ONYXKEYS and the values to set
  */
 function multiSet(data) {
-    return OnyxUtils_1.default.afterInit(() => OnyxUtils_1.default.multiSetWithRetry(data));
+    return PendingWrites_1.default.trackPendingWrite(Object.keys(data), OnyxUtils_1.default.afterInit(() => OnyxUtils_1.default.multiSetWithRetry(data)));
 }
 /**
  * Merge a new value into an existing value at a key.
@@ -211,7 +283,7 @@ function multiSet(data) {
  * Onyx.merge(ONYXKEYS.POLICY, {name: 'My Workspace'}); // -> {id: 1, name: 'My Workspace'}
  */
 function merge(key, changes) {
-    return OnyxUtils_1.default.afterInit(() => {
+    return PendingWrites_1.default.trackPendingWrite(key, OnyxUtils_1.default.afterInit(() => {
         const skippableCollectionMemberIDs = OnyxUtils_1.default.getSkippableCollectionMemberIDs();
         if (skippableCollectionMemberIDs.size) {
             try {
@@ -233,22 +305,30 @@ function merge(key, changes) {
         if (changes === undefined) {
             return mergeQueue[key] ? mergeQueuePromise[key] : Promise.resolve();
         }
-        // Merge attempts are batched together. The delta should be applied after a single call to get() to prevent a race condition.
-        // Using the initial value from storage in subsequent merge attempts will lead to an incorrect final merged value.
+        // Merge attempts are batched together. The delta should be applied after a single read of the
+        // existing value to prevent a race condition. Using the initial value from storage in subsequent
+        // merge attempts will lead to an incorrect final merged value.
         if (mergeQueue[key]) {
             mergeQueue[key].push(changes);
             return mergeQueuePromise[key];
         }
-        mergeQueue[key] = [changes];
-        mergeQueuePromise[key] = OnyxUtils_1.default.get(key).then((valueFromGet) => {
+        const queuedChanges = [changes];
+        mergeQueue[key] = queuedChanges;
+        // Eager hydration means an uncached key has nothing stored, and a storage round trip would land
+        // this write after the same update's cached keys, where subscribers can see a half-applied batch.
+        // A running `Onyx.clear` resets keys, so read what it leaves.
+        const readMergeBase = () => (OnyxCache_1.default.hasCacheForKey(key) ? OnyxCache_1.default.get(key) : undefined);
+        const pendingClear = OnyxCache_1.default.getTaskPromise(OnyxCache_1.TASK.CLEAR);
+        mergeQueuePromise[key] = (pendingClear ? pendingClear.then(readMergeBase) : Promise.resolve(readMergeBase())).then((valueFromGet) => {
             // Calls to Onyx.set after a merge will terminate the current merge process and clear the merge queue
-            if (mergeQueue[key] == null) {
+            if (mergeQueue[key] !== queuedChanges) {
                 return Promise.resolve();
             }
             // Other writers (notably Onyx.update's mergeCollection path, which doesn't participate in mergeQueue)
-            // can land between get() resolving and this callback running. Applying the delta on top of the value
+            // can land between the read above and this callback running. Applying the delta on top of the value
             // captured back then and broadcasting it would overwrite those writes wholesale, so re-read the cache.
-            const existingValue = OnyxCache_1.default.hasCacheForKey(key) ? OnyxCache_1.default.get(key) : valueFromGet;
+            const baseValue = OnyxUtils_1.default.hasStaleMergeRead(queuedChanges) ? undefined : valueFromGet;
+            const existingValue = OnyxCache_1.default.hasCacheForKey(key) ? OnyxCache_1.default.get(key) : baseValue;
             try {
                 const validChanges = mergeQueue[key].filter((change) => {
                     const { isCompatible, existingValueType, newValueType, isEmptyArrayCoercion } = utils_1.default.checkCompatibilityWithExistingValue(change, existingValue);
@@ -286,7 +366,7 @@ function merge(key, changes) {
             }
         });
         return mergeQueuePromise[key];
-    });
+    }));
 }
 /**
  * Merges a collection based on their keys.
@@ -302,7 +382,7 @@ function merge(key, changes) {
  * @param collection Object collection keyed by individual collection member keys and values
  */
 function mergeCollection(collectionKey, collection) {
-    return OnyxUtils_1.default.afterInit(() => OnyxUtils_1.default.mergeCollectionWithPatches({ collectionKey, collection }));
+    return PendingWrites_1.default.trackPendingWrite(Object.keys(collection), OnyxUtils_1.default.afterInit(() => OnyxUtils_1.default.mergeCollectionWithPatches({ collectionKey, collection })));
 }
 /**
  * Clear out all the data in the store
@@ -326,7 +406,8 @@ function mergeCollection(collectionKey, collection) {
  * @param keysToPreserve is a list of ONYXKEYS that should not be cleared with the rest of the data
  */
 function clear(keysToPreserve = []) {
-    return OnyxUtils_1.default.afterInit(() => {
+    return PendingWrites_1.default.trackPendingGlobalWrite(OnyxUtils_1.default.afterInit(() => {
+        const pendingMergeEntries = OnyxUtils_1.default.getPendingMergeEntries(keysToPreserve);
         const defaultKeyStates = OnyxUtils_1.default.getDefaultKeyStates();
         const initialKeys = Object.keys(defaultKeyStates);
         const promise = OnyxUtils_1.default.getAllKeys()
@@ -339,6 +420,7 @@ function clear(keysToPreserve = []) {
             // because the notification process needs the old values in cache but at that point they will be already removed from it.
             const keyValuesToResetAsCollection = {};
             const allKeys = new Set([...cachedKeys, ...initialKeys]);
+            OnyxUtils_1.default.cancelPendingMerges(pendingMergeEntries);
             // The only keys that should not be cleared are:
             // 1. Anything specifically passed in keysToPreserve (because some keys like language preferences, offline
             //      status, or activeClients need to remain in Onyx even when signed out)
@@ -388,22 +470,21 @@ function clear(keysToPreserve = []) {
             for (const key of keysToBeClearedFromStorage)
                 OnyxCache_1.default.drop(key);
             return storage_1.default.removeItems(keysToBeClearedFromStorage)
-                .then(() => OnyxConnectionManager_1.default.refreshSessionID())
                 .then(() => storage_1.default.multiSet(defaultKeyValuePairs))
                 .then(() => {
                 DevTools_1.default.clearState(keysToPreserve);
                 // Notify the subscribers for each key/value group so they can receive the new values
                 for (const [key, value] of Object.entries(keyValuesToResetIndividually)) {
-                    OnyxUtils_1.default.keyChanged(key, value);
+                    OnyxUtils_1.default.notifyKey(key, value);
                 }
                 for (const [key, value] of Object.entries(keyValuesToResetAsCollection)) {
-                    OnyxUtils_1.default.keysChanged(key, value.newValues, value.oldValues);
+                    OnyxUtils_1.default.notifyCollection(key, value.newValues, value.oldValues);
                 }
             });
         })
             .then(() => undefined);
         return OnyxCache_1.default.captureTask(OnyxCache_1.TASK.CLEAR, promise);
-    });
+    }));
 }
 /**
  * Insert API responses and lifecycle data into Onyx
@@ -412,7 +493,17 @@ function clear(keysToPreserve = []) {
  * @returns resolves when all operations are complete
  */
 function update(data) {
-    return OnyxUtils_1.default.afterInit(() => {
+    return PendingWrites_1.default.trackPendingWrite(
+    // multiSet/collection items keep their keys in `.value`, not `.key`.
+    data.flatMap((updateItem) => {
+        var _a;
+        if (updateItem.onyxMethod === OnyxUtils_1.default.METHOD.MULTI_SET ||
+            updateItem.onyxMethod === OnyxUtils_1.default.METHOD.MERGE_COLLECTION ||
+            updateItem.onyxMethod === OnyxUtils_1.default.METHOD.SET_COLLECTION) {
+            return Object.keys((_a = updateItem.value) !== null && _a !== void 0 ? _a : {});
+        }
+        return updateItem.key;
+    }), OnyxUtils_1.default.afterInit(() => {
         // The queue of operations within a single `update` call in the format of <item key - list of operations updating the item>.
         // This allows us to batch the operations per item and merge them into one operation in the order they were requested.
         const updateQueue = {};
@@ -536,7 +627,7 @@ function update(data) {
         // We need to run the snapshot updates before the other updates so the snapshot data can be updated before the loading state in the snapshot
         const finalPromises = snapshotPromises.concat(promises);
         return clearPromise.then(() => Promise.all(finalPromises.map((p) => p()))).then(() => undefined);
-    });
+    }));
 }
 /**
  * Sets a collection by replacing all existing collection members with new values.
@@ -552,7 +643,7 @@ function update(data) {
  * @param collection Object collection keyed by individual collection member keys and values
  */
 function setCollection(collectionKey, collection) {
-    return OnyxUtils_1.default.afterInit(() => OnyxUtils_1.default.setCollectionWithRetry({ collectionKey, collection }));
+    return PendingWrites_1.default.trackPendingWrite(Object.keys(collection), OnyxUtils_1.default.afterInit(() => OnyxUtils_1.default.setCollectionWithRetry({ collectionKey, collection })));
 }
 /**
  * Returns persisted Onyx key-value pairs as a plain object.

package/dist/OnyxCache.d.ts

@@ -1,5 +1,5 @@
 import type { ValueOf } from 'type-fest';
-import type { OnyxKey, OnyxValue } from './types';
+import type { KeyValueMapping, OnyxCollection, OnyxKey, OnyxValue } from './types';
 declare const TASK: {
     readonly GET: "get";
     readonly GET_ALL_KEYS: "getAllKeys";
@@ -151,7 +151,7 @@ declare class OnyxCache {
      * Returns a frozen snapshot with structural sharing — safe to return by reference.
      * Lazily rebuilds the snapshot if the collection was modified since the last read.
      */
-    getCollectionData(collectionKey: OnyxKey): Record<OnyxKey, OnyxValue<OnyxKey>> | undefined;
+    getCollectionData(collectionKey: OnyxKey): OnyxCollection<KeyValueMapping[OnyxKey]> | undefined;
 }
 declare const instance: OnyxCache;
 export default instance;

package/dist/OnyxCache.js

@@ -437,18 +437,13 @@ class OnyxCache {
             this.dirtyCollections.delete(collectionKey);
         }
         const snapshot = this.collectionSnapshots.get(collectionKey);
-        // We never stored anything for this collection key.
+        // Returning `undefined` for this collection key means init hasn't seeded it yet (pre-load), so there's
+        // nothing to return. `setCollectionKeys()` (called inside `Onyx.init`) seeds every
+        // known collection with a frozen empty entry, so the presence of an entry is the reliable
+        // post-init "loaded" signal.
         if (snapshot === undefined) {
             return undefined;
         }
-        // The collection is empty (it holds our shared empty object). But "empty" is ambiguous
-        // during startup: we can't tell an actually-empty collection apart from one whose data
-        // hasn't loaded yet. Once any key exists, we know setAllKeys has run and loaded everything,
-        // so an empty collection really is empty. Before that, return undefined so subscribers
-        // don't briefly see a collection as empty when it just hasn't loaded.
-        if (snapshot === FROZEN_EMPTY_COLLECTION) {
-            return this.storageKeys.size > 0 ? FROZEN_EMPTY_COLLECTION : undefined;
-        }
         return snapshot;
     }
 }