react-native-onyx 2.0.63 → 2.0.65

package/dist/OnyxUtils.d.ts

@@ -1,6 +1,7 @@
 import type { ValueOf } from 'type-fest';
 import type Onyx from './Onyx';
-import type { CollectionKey, CollectionKeyBase, DeepRecord, KeyValueMapping, Mapping, OnyxCollection, OnyxEntry, OnyxInput, OnyxKey, OnyxMergeCollectionInput, OnyxValue, WithOnyxConnectOptions } from './types';
+import type { CollectionKey, CollectionKeyBase, ConnectOptions, DeepRecord, KeyValueMapping, Mapping, OnyxCollection, OnyxEntry, OnyxInput, OnyxKey, OnyxMergeCollectionInput, OnyxValue } from './types';
+import type { DeferredTask } from './createDeferredTask';
 declare const METHOD: {
     readonly SET: "set";
     readonly MERGE: "merge";
@@ -18,14 +19,18 @@ declare function getMergeQueue(): Record<OnyxKey, Array<OnyxValue<OnyxKey>>>;
  * Getter - returns the merge queue promise.
  */
 declare function getMergeQueuePromise(): Record<OnyxKey, Promise<void>>;
-/**
- * Getter - returns the callback to state mapping.
- */
-declare function getCallbackToStateMapping(): Record<string, Mapping<OnyxKey>>;
 /**
  * Getter - returns the default key states.
  */
 declare function getDefaultKeyStates(): Record<OnyxKey, OnyxValue<OnyxKey>>;
+/**
+ * Getter - returns the deffered init task.
+ */
+declare function getDeferredInitTask(): DeferredTask;
+/**
+ * Getter - returns the eviction block list.
+ */
+declare function getEvictionBlocklist(): Record<OnyxKey, string[] | undefined>;
 /**
  * Sets the initial values for the Onyx store
  *
@@ -55,19 +60,6 @@ declare function batchUpdates(updates: () => void): Promise<void>;
 /** Get some data from the store */
 declare function get<TKey extends OnyxKey, TValue extends OnyxValue<TKey>>(key: TKey): Promise<TValue>;
 declare function multiGet<TKey extends OnyxKey>(keys: CollectionKeyBase[]): Promise<Map<OnyxKey, OnyxValue<TKey>>>;
-/**
- * Stores a connection ID associated with a given key.
- *
- * @param connectionID - a connection ID of the subscriber
- * @param key - a key that the subscriber is connected to
- */
-declare function storeKeyByConnections(key: OnyxKey, connectionID: number): void;
-/**
- * Deletes a connection ID associated with its corresponding key.
- *
- * @param {number} connectionID - The connection ID to be deleted.
- */
-declare function deleteKeyByConnections(connectionID: number): void;
 /** Returns current key names stored in persisted storage */
 declare function getAllKeys(): Promise<Set<OnyxKey>>;
 /**
@@ -85,7 +77,7 @@ declare function isCollectionMemberKey<TCollectionKey extends CollectionKeyBase>
  * @param key - The collection member key to split.
  * @returns A tuple where the first element is the collection part and the second element is the ID part.
  */
-declare function splitCollectionMemberKey<TKey extends CollectionKey>(key: TKey): [TKey extends `${infer Prefix}_${string}` ? `${Prefix}_` : never, string];
+declare function splitCollectionMemberKey<TKey extends CollectionKey, CollectionKeyType = TKey extends `${infer Prefix}_${string}` ? `${Prefix}_` : never>(key: TKey): [CollectionKeyType, string];
 /**
  * Checks to see if a provided key is the exact configured key of our connected subscriber
  * or if the provided key is a collection member key (in case our configured key is a "collection key")
@@ -109,7 +101,7 @@ declare function getCollectionKey(key: OnyxKey): string;
  * 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.
  */
-declare function tryGetCachedValue<TKey extends OnyxKey>(key: TKey, mapping?: Partial<WithOnyxConnectOptions<TKey>>): OnyxValue<OnyxKey>;
+declare function tryGetCachedValue<TKey extends OnyxKey>(key: TKey, mapping?: Partial<Mapping<TKey>>): OnyxValue<OnyxKey>;
 /**
  * Remove a key from the recently accessed key list.
  */
@@ -120,13 +112,6 @@ declare function removeLastAccessedKey(key: OnyxKey): void;
  * recently accessed key at the tail.
  */
 declare function addLastAccessedKey(key: OnyxKey): void;
-/**
- * Removes a key previously added to this list
- * which will enable it to be deleted again.
- */
-declare function removeFromEvictionBlockList(key: OnyxKey, connectionID: number): void;
-/** Keys added to this list can never be deleted. */
-declare function addToEvictionBlockList(key: OnyxKey, connectionID: number): void;
 /**
  * Take all the keys that are safe to evict and add them to
  * the recently accessed list when initializing the app. This
@@ -152,11 +137,6 @@ declare function keyChanged<TKey extends OnyxKey>(key: TKey, value: OnyxValue<TK
  *     - triggers the callback function
  */
 declare function sendDataToConnection<TKey extends OnyxKey>(mapping: Mapping<TKey>, value: OnyxValue<TKey> | null, matchedKey: TKey | undefined, isBatched: boolean): void;
-/**
- * We check to see if this key is flagged as safe for eviction and add it to the recentlyAccessedKeys list so that when we
- * run out of storage the least recently accessed key can be removed.
- */
-declare function addKeyToRecentlyAccessedIfNeeded<TKey extends OnyxKey>(mapping: Mapping<TKey>): void;
 /**
  * Gets the data for a given an array of matching keys, combines them into an object, and sends the result back to the subscriber.
  */
@@ -228,6 +208,19 @@ declare function isValidNonEmptyCollectionForMerge<TKey extends CollectionKeyBas
  * Verify if all the collection keys belong to the same parent
  */
 declare function doAllCollectionItemsBelongToSameParent<TKey extends CollectionKeyBase>(collectionKey: TKey, collectionKeys: string[]): boolean;
+/**
+ * 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()`.
+ */
+declare function subscribeToKey<TKey extends OnyxKey>(connectOptions: ConnectOptions<TKey>): number;
+/**
+ * Disconnects and removes the listener from the Onyx key.
+ *
+ * @param subscriptionID Subscription ID returned by calling `OnyxUtils.subscribeToKey()`.
+ */
+declare function unsubscribeFromKey(subscriptionID: number): void;
 declare const OnyxUtils: {
     METHOD: {
         readonly SET: "set";
@@ -238,8 +231,8 @@ declare const OnyxUtils: {
     };
     getMergeQueue: typeof getMergeQueue;
     getMergeQueuePromise: typeof getMergeQueuePromise;
-    getCallbackToStateMapping: typeof getCallbackToStateMapping;
     getDefaultKeyStates: typeof getDefaultKeyStates;
+    getDeferredInitTask: typeof getDeferredInitTask;
     initStoreValues: typeof initStoreValues;
     sendActionToDevTools: typeof sendActionToDevTools;
     maybeFlushBatchUpdates: typeof maybeFlushBatchUpdates;
@@ -255,14 +248,11 @@ declare const OnyxUtils: {
     tryGetCachedValue: typeof tryGetCachedValue;
     removeLastAccessedKey: typeof removeLastAccessedKey;
     addLastAccessedKey: typeof addLastAccessedKey;
-    removeFromEvictionBlockList: typeof removeFromEvictionBlockList;
-    addToEvictionBlockList: typeof addToEvictionBlockList;
     addAllSafeEvictionKeysToRecentlyAccessedList: typeof addAllSafeEvictionKeysToRecentlyAccessedList;
     getCachedCollection: typeof getCachedCollection;
     keysChanged: typeof keysChanged;
     keyChanged: typeof keyChanged;
     sendDataToConnection: typeof sendDataToConnection;
-    addKeyToRecentlyAccessedIfNeeded: typeof addKeyToRecentlyAccessedIfNeeded;
     getCollectionKey: typeof getCollectionKey;
     getCollectionDataAndSendAsObject: typeof getCollectionDataAndSendAsObject;
     scheduleSubscriberUpdate: typeof scheduleSubscriberUpdate;
@@ -276,11 +266,12 @@ declare const OnyxUtils: {
     prepareKeyValuePairsForStorage: typeof prepareKeyValuePairsForStorage;
     applyMerge: typeof applyMerge;
     initializeWithDefaultKeyStates: typeof initializeWithDefaultKeyStates;
-    storeKeyByConnections: typeof storeKeyByConnections;
-    deleteKeyByConnections: typeof deleteKeyByConnections;
     getSnapshotKey: typeof getSnapshotKey;
     multiGet: typeof multiGet;
     isValidNonEmptyCollectionForMerge: typeof isValidNonEmptyCollectionForMerge;
     doAllCollectionItemsBelongToSameParent: typeof doAllCollectionItemsBelongToSameParent;
+    subscribeToKey: typeof subscribeToKey;
+    unsubscribeFromKey: typeof unsubscribeFromKey;
+    getEvictionBlocklist: typeof getEvictionBlocklist;
 };
 export default OnyxUtils;

package/dist/OnyxUtils.js

@@ -38,6 +38,7 @@ const Str = __importStar(require("./Str"));
 const batch_1 = __importDefault(require("./batch"));
 const storage_1 = __importDefault(require("./storage"));
 const utils_1 = __importDefault(require("./utils"));
+const createDeferredTask_1 = __importDefault(require("./createDeferredTask"));
 // Method constants
 const METHOD = {
     SET: 'set',
@@ -53,14 +54,14 @@ const mergeQueuePromise = {};
 const callbackToStateMapping = {};
 // Keeps a copy of the values of the onyx collection keys as a map for faster lookups
 let onyxCollectionKeySet = new Set();
-// Holds a mapping of the connected key to the connectionID for faster lookups
-const onyxKeyToConnectionIDs = new Map();
+// Holds a mapping of the connected key to the subscriptionID for faster lookups
+const onyxKeyToSubscriptionIDs = new Map();
 // Holds a list of keys that have been directly subscribed to or recently modified from least to most recent
 let recentlyAccessedKeys = [];
 // Holds a list of keys that are safe to remove when we reach max storage. If a key does not match with
 // whatever appears in this list it will NEVER be a candidate for eviction.
 let evictionAllowList = [];
-// Holds a map of keys and connectionID arrays whose keys will never be automatically evicted as
+// Holds a map of keys and connection arrays whose keys will never be automatically evicted as
 // long as we have at least one subscriber that returns false for the canEvict property.
 const evictionBlocklist = {};
 // Optional user-provided key value states set when Onyx initializes or clears
@@ -70,6 +71,10 @@ let batchUpdatesQueue = [];
 // Used for comparison with a new update to avoid invoking the Onyx.connect callback with the same data.
 const 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)();
 function getSnapshotKey() {
     return snapshotKey;
 }
@@ -85,18 +90,24 @@ function getMergeQueue() {
 function getMergeQueuePromise() {
     return mergeQueuePromise;
 }
-/**
- * Getter - returns the callback to state mapping.
- */
-function getCallbackToStateMapping() {
-    return callbackToStateMapping;
-}
 /**
  * Getter - returns the default key states.
  */
 function getDefaultKeyStates() {
     return defaultKeyStates;
 }
+/**
+ * Getter - returns the deffered init task.
+ */
+function getDeferredInitTask() {
+    return deferredInitTask;
+}
+/**
+ * Getter - returns the eviction block list.
+ */
+function getEvictionBlocklist() {
+    return evictionBlocklist;
+}
 /**
  * Sets the initial values for the Onyx store
  *
@@ -258,29 +269,29 @@ function multiGet(keys) {
     }));
 }
 /**
- * Stores a connection ID associated with a given key.
+ * Stores a subscription ID associated with a given key.
  *
- * @param connectionID - a connection ID of the subscriber
- * @param key - a key that the subscriber is connected to
+ * @param subscriptionID - A subscription ID of the subscriber.
+ * @param key - A key that the subscriber is subscribed to.
  */
-function storeKeyByConnections(key, connectionID) {
-    if (!onyxKeyToConnectionIDs.has(key)) {
-        onyxKeyToConnectionIDs.set(key, []);
+function storeKeyBySubscriptions(key, subscriptionID) {
+    if (!onyxKeyToSubscriptionIDs.has(key)) {
+        onyxKeyToSubscriptionIDs.set(key, []);
     }
-    onyxKeyToConnectionIDs.get(key).push(connectionID);
+    onyxKeyToSubscriptionIDs.get(key).push(subscriptionID);
 }
 /**
- * Deletes a connection ID associated with its corresponding key.
+ * Deletes a subscription ID associated with its corresponding key.
  *
- * @param {number} connectionID - The connection ID to be deleted.
+ * @param subscriptionID - The subscription ID to be deleted.
  */
-function deleteKeyByConnections(connectionID) {
-    const subscriber = callbackToStateMapping[connectionID];
-    if (subscriber && onyxKeyToConnectionIDs.has(subscriber.key)) {
-        const updatedConnectionIDs = onyxKeyToConnectionIDs.get(subscriber.key).filter((id) => id !== connectionID);
-        onyxKeyToConnectionIDs.set(subscriber.key, updatedConnectionIDs);
+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(connectionID);
+    lastConnectionCallbackData.delete(subscriptionID);
 }
 /** Returns current key names stored in persisted storage */
 function getAllKeys() {
@@ -328,7 +339,9 @@ function splitCollectionMemberKey(key) {
     if (underscoreIndex === -1) {
         throw new Error(`Invalid ${key} key provided, only collection keys are allowed.`);
     }
-    return [key.substring(0, underscoreIndex + 1), key.substring(underscoreIndex + 1)];
+    const collectionKey = key.substring(0, underscoreIndex + 1);
+    const memberKey = key.substring(underscoreIndex + 1);
+    return [collectionKey, memberKey];
 }
 /**
  * Checks to see if a provided key is the exact configured key of our connected subscriber
@@ -409,26 +422,6 @@ function addLastAccessedKey(key) {
     removeLastAccessedKey(key);
     recentlyAccessedKeys.push(key);
 }
-/**
- * Removes a key previously added to this list
- * which will enable it to be deleted again.
- */
-function removeFromEvictionBlockList(key, connectionID) {
-    var _a, _b, _c;
-    evictionBlocklist[key] = (_b = (_a = evictionBlocklist[key]) === null || _a === void 0 ? void 0 : _a.filter((evictionKey) => evictionKey !== connectionID)) !== null && _b !== void 0 ? _b : [];
-    // Remove the key if there are no more subscribers
-    if (((_c = evictionBlocklist[key]) === null || _c === void 0 ? void 0 : _c.length) === 0) {
-        delete evictionBlocklist[key];
-    }
-}
-/** Keys added to this list can never be deleted. */
-function addToEvictionBlockList(key, connectionID) {
-    removeFromEvictionBlockList(key, connectionID);
-    if (!evictionBlocklist[key]) {
-        evictionBlocklist[key] = [];
-    }
-    evictionBlocklist[key].push(connectionID);
-}
 /**
  * Take all the keys that are safe to evict and add them to
  * the recently accessed list when initializing the app. This
@@ -506,7 +499,7 @@ function keysChanged(collectionKey, partialCollection, partialPreviousCollection
             // send the whole cached collection.
             if (isSubscribedToCollectionKey) {
                 if (subscriber.waitForCollectionCallback) {
-                    subscriber.callback(cachedCollection);
+                    subscriber.callback(cachedCollection, subscriber.key);
                     continue;
                 }
                 // If they are not using waitForCollectionCallback then we notify the subscriber with
@@ -534,7 +527,7 @@ function keysChanged(collectionKey, partialCollection, partialPreviousCollection
             continue;
         }
         // React component subscriber found.
-        if ('withOnyxInstance' in subscriber && subscriber.withOnyxInstance) {
+        if (utils_1.default.hasWithOnyxInstance(subscriber)) {
             if (!notifyWithOnyxSubscibers) {
                 continue;
             }
@@ -645,12 +638,12 @@ function keyChanged(key, value, previousValue, canUpdateSubscriber = () => true,
     // 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 = onyxKeyToConnectionIDs.get(key)) !== null && _a !== void 0 ? _a : [];
+    let stateMappingKeys = (_a = onyxKeyToSubscriptionIDs.get(key)) !== null && _a !== void 0 ? _a : [];
     const collectionKey = getCollectionKey(key);
     const plainCollectionKey = collectionKey.lastIndexOf('_') !== -1 ? collectionKey : undefined;
     if (plainCollectionKey) {
         // Getting the collection key from the specific key because only collection keys were stored in the mapping.
-        stateMappingKeys = [...stateMappingKeys, ...((_b = onyxKeyToConnectionIDs.get(plainCollectionKey)) !== null && _b !== void 0 ? _b : [])];
+        stateMappingKeys = [...stateMappingKeys, ...((_b = onyxKeyToSubscriptionIDs.get(plainCollectionKey)) !== null && _b !== void 0 ? _b : [])];
         if (stateMappingKeys.length === 0) {
             return;
         }
@@ -666,7 +659,7 @@ function keyChanged(key, value, previousValue, canUpdateSubscriber = () => true,
             if (!notifyConnectSubscribers) {
                 continue;
             }
-            if (lastConnectionCallbackData.has(subscriber.connectionID) && lastConnectionCallbackData.get(subscriber.connectionID) === value) {
+            if (lastConnectionCallbackData.has(subscriber.subscriptionID) && lastConnectionCallbackData.get(subscriber.subscriptionID) === value) {
                 continue;
             }
             if (isCollectionKey(subscriber.key) && subscriber.waitForCollectionCallback) {
@@ -676,16 +669,16 @@ function keyChanged(key, value, previousValue, canUpdateSubscriber = () => true,
                     cachedCollections[subscriber.key] = cachedCollection;
                 }
                 cachedCollection[key] = value;
-                subscriber.callback(cachedCollection);
+                subscriber.callback(cachedCollection, subscriber.key);
                 continue;
             }
             const subscriberCallback = subscriber.callback;
             subscriberCallback(value, key);
-            lastConnectionCallbackData.set(subscriber.connectionID, value);
+            lastConnectionCallbackData.set(subscriber.subscriptionID, value);
             continue;
         }
         // Subscriber connected via withOnyx() HOC
-        if ('withOnyxInstance' in subscriber && subscriber.withOnyxInstance) {
+        if (utils_1.default.hasWithOnyxInstance(subscriber)) {
             if (!notifyWithOnyxSubscribers) {
                 continue;
             }
@@ -768,10 +761,10 @@ function sendDataToConnection(mapping, value, matchedKey, isBatched) {
     var _a, _b;
     // If the mapping no longer exists then we should not send any data.
     // This means our subscriber disconnected or withOnyx wrapped component unmounted.
-    if (!callbackToStateMapping[mapping.connectionID]) {
+    if (!callbackToStateMapping[mapping.subscriptionID]) {
         return;
     }
-    if ('withOnyxInstance' in mapping && mapping.withOnyxInstance) {
+    if (utils_1.default.hasWithOnyxInstance(mapping)) {
         let newData = value;
         // If the mapping has a selector, then the component's state must only be updated with the data
         // returned by the selector.
@@ -799,10 +792,10 @@ function sendDataToConnection(mapping, value, matchedKey, isBatched) {
     // withOnyx will internally replace null values with undefined and never pass null values to wrapped components.
     // For regular callbacks, we never want to pass null values, but always just undefined if a value is not set in cache or storage.
     const valueToPass = value === null ? undefined : value;
-    const lastValue = lastConnectionCallbackData.get(mapping.connectionID);
-    lastConnectionCallbackData.get(mapping.connectionID);
+    const lastValue = lastConnectionCallbackData.get(mapping.subscriptionID);
+    lastConnectionCallbackData.get(mapping.subscriptionID);
     // If the value has not changed we do not need to trigger the callback
-    if (lastConnectionCallbackData.has(mapping.connectionID) && valueToPass === lastValue) {
+    if (lastConnectionCallbackData.has(mapping.subscriptionID) && valueToPass === lastValue) {
         return;
     }
     (_b = (_a = mapping).callback) === null || _b === void 0 ? void 0 : _b.call(_a, valueToPass, matchedKey);
@@ -817,7 +810,7 @@ function addKeyToRecentlyAccessedIfNeeded(mapping) {
     }
     // Try to free some cache whenever we connect to a safe eviction key
     OnyxCache_1.default.removeLeastRecentlyUsedKeys();
-    if ('withOnyxInstance' in mapping && mapping.withOnyxInstance && !isCollectionKey(mapping.key)) {
+    if (utils_1.default.hasWithOnyxInstance(mapping) && !isCollectionKey(mapping.key)) {
         // All React components subscribing to a key flagged as a safe eviction key must implement the canEvict property.
         if (mapping.canEvict === undefined) {
             throw new Error(`Cannot subscribe to safe eviction key '${mapping.key}' without providing a canEvict value.`);
@@ -994,7 +987,7 @@ function isValidNonEmptyCollectionForMerge(collection) {
 function doAllCollectionItemsBelongToSameParent(collectionKey, collectionKeys) {
     let hasCollectionKeyCheckFailed = false;
     collectionKeys.forEach((dataKey) => {
-        if (OnyxUtils.isKeyMatch(collectionKey, dataKey)) {
+        if (isKeyMatch(collectionKey, dataKey)) {
             return;
         }
         if (process.env.NODE_ENV === 'development') {
@@ -1005,12 +998,116 @@ 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);
+    if (mapping.initWithStoredValues === false) {
+        return subscriptionID;
+    }
+    // Commit connection only after init passes
+    deferredInitTask.promise
+        .then(() => addKeyToRecentlyAccessedIfNeeded(mapping))
+        .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 (Boolean(mapping.key) && typeof mapping.key === 'string' && !mapping.key.endsWith('_') && 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 = [];
+        keys.forEach((key) => {
+            if (!isKeyMatch(mapping.key, key)) {
+                return;
+            }
+            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. In withOnyx() we wait for all connected keys to return a value before rendering the child
+        // component. This null value will be filtered out so that the connected component can utilize defaultProps.
+        if (matchingKeys.length === 0) {
+            if (mapping.key && !isCollectionKey(mapping.key)) {
+                OnyxCache_1.default.addNullishStorageKey(mapping.key);
+            }
+            // 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, null, undefined, false);
+            return;
+        }
+        // When using a callback subscriber we will either trigger the provided callback for each key we find or combine all values
+        // into an object and just make a single call. The latter behavior is enabled by providing a waitForCollectionCallback key
+        // combined with a subscription to a collection key.
+        if (typeof mapping.callback === 'function') {
+            if (isCollectionKey(mapping.key)) {
+                if (mapping.waitForCollectionCallback) {
+                    getCollectionDataAndSendAsObject(matchingKeys, mapping);
+                    return;
+                }
+                // We did not opt into using waitForCollectionCallback mode so the callback is called for every matching key.
+                multiGet(matchingKeys).then((values) => {
+                    values.forEach((val, key) => {
+                        sendDataToConnection(mapping, val, key, true);
+                    });
+                });
+                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((val) => sendDataToConnection(mapping, val, mapping.key, true));
+            return;
+        }
+        // If we have a withOnyxInstance that means a React component has subscribed via the withOnyx() HOC and we need to
+        // group collection key member data into an object.
+        if (utils_1.default.hasWithOnyxInstance(mapping)) {
+            if (isCollectionKey(mapping.key)) {
+                getCollectionDataAndSendAsObject(matchingKeys, mapping);
+                return;
+            }
+            // If the subscriber is not using a collection key then we just send a single value back to the subscriber
+            get(mapping.key).then((val) => sendDataToConnection(mapping, val, mapping.key, true));
+            return;
+        }
+        console.error('Warning: Onyx.connect() was found without a callback or withOnyxInstance');
+    });
+    // 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(lastSubscriptionID);
+    delete callbackToStateMapping[subscriptionID];
+}
 const OnyxUtils = {
     METHOD,
     getMergeQueue,
     getMergeQueuePromise,
-    getCallbackToStateMapping,
     getDefaultKeyStates,
+    getDeferredInitTask,
     initStoreValues,
     sendActionToDevTools,
     maybeFlushBatchUpdates,
@@ -1026,14 +1123,11 @@ const OnyxUtils = {
     tryGetCachedValue,
     removeLastAccessedKey,
     addLastAccessedKey,
-    removeFromEvictionBlockList,
-    addToEvictionBlockList,
     addAllSafeEvictionKeysToRecentlyAccessedList,
     getCachedCollection,
     keysChanged,
     keyChanged,
     sendDataToConnection,
-    addKeyToRecentlyAccessedIfNeeded,
     getCollectionKey,
     getCollectionDataAndSendAsObject,
     scheduleSubscriberUpdate,
@@ -1047,11 +1141,12 @@ const OnyxUtils = {
     prepareKeyValuePairsForStorage,
     applyMerge,
     initializeWithDefaultKeyStates,
-    storeKeyByConnections,
-    deleteKeyByConnections,
     getSnapshotKey,
     multiGet,
     isValidNonEmptyCollectionForMerge,
     doAllCollectionItemsBelongToSameParent,
+    subscribeToKey,
+    unsubscribeFromKey,
+    getEvictionBlocklist,
 };
 exports.default = OnyxUtils;

package/dist/Str.d.ts

@@ -14,4 +14,8 @@ declare function startsWith(haystack: string, needle: string): boolean;
  */
 declare function result(parameter: string): string;
 declare function result<TFunction extends (...a: TArgs) => unknown, TArgs extends unknown[]>(parameter: TFunction, ...args: TArgs): ReturnType<TFunction>;
-export { startsWith, result };
+/**
+ * A simple GUID generator taken from https://stackoverflow.com/a/32760401/9114791
+ */
+declare function guid(): string;
+export { guid, result, startsWith };

package/dist/Str.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.result = exports.startsWith = void 0;
+exports.startsWith = exports.result = exports.guid = void 0;
 /**
  * Returns true if the haystack begins with the needle
  *
@@ -16,3 +16,15 @@ function result(parameter, ...args) {
     return typeof parameter === 'function' ? parameter(...args) : parameter;
 }
 exports.result = result;
+/**
+ * A simple GUID generator taken from https://stackoverflow.com/a/32760401/9114791
+ */
+function guid() {
+    function s4() {
+        return Math.floor((1 + Math.random()) * 0x10000)
+            .toString(16)
+            .substring(1);
+    }
+    return `${s4()}${s4()}-${s4()}-${s4()}-${s4()}-${s4()}${s4()}${s4()}`;
+}
+exports.guid = guid;

package/dist/createDeferredTask.d.ts

@@ -8,4 +8,4 @@ type DeferredTask = {
  * Useful when we want to wait for a tasks that is resolved from an external action
  */
 export default function createDeferredTask(): DeferredTask;
-export {};
+export type { DeferredTask };

package/dist/index.d.ts

@@ -2,9 +2,10 @@ import type { ConnectOptions, OnyxUpdate } from './Onyx';
 import Onyx from './Onyx';
 import type { CustomTypeOptions, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxValue, Selector, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput } from './types';
 import type { FetchStatus, ResultMetadata, UseOnyxResult } from './useOnyx';
+import type { Connection } from './OnyxConnectionManager';
 import useOnyx from './useOnyx';
 import withOnyx from './withOnyx';
 import type { WithOnyxState } from './withOnyx/types';
 export default Onyx;
 export { useOnyx, withOnyx };
-export type { ConnectOptions, CustomTypeOptions, FetchStatus, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxUpdate, OnyxValue, ResultMetadata, Selector, UseOnyxResult, WithOnyxState, };
+export type { ConnectOptions, CustomTypeOptions, FetchStatus, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxUpdate, OnyxValue, ResultMetadata, Selector, UseOnyxResult, WithOnyxState, Connection, };