react-native-onyx 2.0.63 → 2.0.65

package/dist/types.d.ts

@@ -226,29 +226,34 @@ type Collection<TKey extends CollectionKeyBase, TValue, TMap = never> = {
 };
 /** Represents the base options used in `Onyx.connect()` method. */
 type BaseConnectOptions = {
+    /** If set to `false`, then the initial data will be only sent to the callback function if it changes. */
     initWithStoredValues?: boolean;
+    /**
+     * If set to `false`, the connection won't be reused between other subscribers that are listening to the same Onyx key
+     * with the same connect configurations.
+     */
+    reuseConnection?: boolean;
 };
-/** Represents additional options used inside withOnyx HOC */
-type WithOnyxConnectOptions<TKey extends OnyxKey> = {
-    withOnyxInstance: WithOnyxInstance;
-    statePropertyName: string;
-    displayName: string;
-    initWithStoredValues?: boolean;
-    selector?: Selector<TKey, unknown, unknown>;
-    canEvict?: boolean;
-};
-type DefaultConnectCallback<TKey extends OnyxKey> = (value: OnyxEntry<KeyValueMapping[TKey]>, key: TKey) => void;
-type CollectionConnectCallback<TKey extends OnyxKey> = (value: NonUndefined<OnyxCollection<KeyValueMapping[TKey]>>) => void;
 /** Represents the callback function used in `Onyx.connect()` method with a regular key. */
-type DefaultConnectOptions<TKey extends OnyxKey> = {
+type DefaultConnectCallback<TKey extends OnyxKey> = (value: OnyxEntry<KeyValueMapping[TKey]>, key: TKey) => void;
+/** Represents the callback function used in `Onyx.connect()` method with a collection key. */
+type CollectionConnectCallback<TKey extends OnyxKey> = (value: NonUndefined<OnyxCollection<KeyValueMapping[TKey]>>, key: TKey) => void;
+/** Represents the options used in `Onyx.connect()` method with a regular key. */
+type DefaultConnectOptions<TKey extends OnyxKey> = BaseConnectOptions & {
+    /** The Onyx key to subscribe to. */
     key: TKey;
+    /** A function that will be called when the Onyx data we are subscribed changes. */
     callback?: DefaultConnectCallback<TKey>;
+    /** If set to `true`, it will return the entire collection to the callback as a single object. */
     waitForCollectionCallback?: false;
 };
-/** Represents the callback function used in `Onyx.connect()` method with a collection key. */
-type CollectionConnectOptions<TKey extends OnyxKey> = {
+/** Represents the options used in `Onyx.connect()` method with a collection key. */
+type CollectionConnectOptions<TKey extends OnyxKey> = BaseConnectOptions & {
+    /** The Onyx key to subscribe to. */
     key: TKey extends CollectionKeyBase ? TKey : never;
+    /** A function that will be called when the Onyx data we are subscribed changes. */
     callback?: CollectionConnectCallback<TKey>;
+    /** If set to `true`, it will return the entire collection to the callback as a single object. */
     waitForCollectionCallback: true;
 };
 /**
@@ -261,12 +266,28 @@ type CollectionConnectOptions<TKey extends OnyxKey> = {
  *
  * If `waitForCollectionCallback` is `false` or not specified, the `key` can be any Onyx key and `callback` will be triggered with updates of each collection item
  * and will pass `value` as an `OnyxEntry`.
- *
- * The type is also extended with `BaseConnectOptions` and `WithOnyxConnectOptions` to include additional options, depending on the context where it's used.
  */
-type ConnectOptions<TKey extends OnyxKey> = (CollectionConnectOptions<TKey> | DefaultConnectOptions<TKey>) & (BaseConnectOptions | WithOnyxConnectOptions<TKey>);
-type Mapping<TKey extends OnyxKey> = ConnectOptions<TKey> & {
-    connectionID: number;
+type ConnectOptions<TKey extends OnyxKey> = DefaultConnectOptions<TKey> | CollectionConnectOptions<TKey>;
+/** Represents additional `Onyx.connect()` options used inside `withOnyx()` HOC. */
+type WithOnyxConnectOptions<TKey extends OnyxKey> = ConnectOptions<TKey> & {
+    /** The `withOnyx` class instance to be internally passed. */
+    withOnyxInstance: WithOnyxInstance;
+    /** The name of the component's prop that is connected to the Onyx key. */
+    statePropertyName: string;
+    /** The component's display name. */
+    displayName: string;
+    /**
+     * This will be used to subscribe to a subset of an Onyx key's data.
+     * Using this setting on `withOnyx` 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).
+     */
+    selector?: Selector<TKey, unknown, unknown>;
+    /** Determines if this key in this subscription is safe to be evicted. */
+    canEvict?: boolean;
+};
+type Mapping<TKey extends OnyxKey> = WithOnyxConnectOptions<TKey> & {
+    subscriptionID: number;
 };
 /**
  * Represents a single Onyx input value, that can be either `TOnyxValue` or `null` if the key should be deleted.

package/dist/useOnyx.d.ts

@@ -6,11 +6,11 @@ type BaseUseOnyxOptions = {
      */
     canEvict?: boolean;
     /**
-     * If set to false, then no data will be prefilled into the component.
+     * If set to `false`, then no data will be prefilled into the component.
      */
     initWithStoredValues?: boolean;
     /**
-     * If set to true, data will be retrieved from cache during the first render even if there is a pending merge for the key.
+     * If set to `true`, data will be retrieved from cache during the first render even if there is a pending merge for the key.
      */
     allowStaleData?: boolean;
 };

package/dist/useOnyx.js

@@ -5,8 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const fast_equals_1 = require("fast-equals");
 const react_1 = require("react");
-const Onyx_1 = __importDefault(require("./Onyx"));
 const OnyxCache_1 = __importDefault(require("./OnyxCache"));
+const OnyxConnectionManager_1 = __importDefault(require("./OnyxConnectionManager"));
 const OnyxUtils_1 = __importDefault(require("./OnyxUtils"));
 const useLiveRef_1 = __importDefault(require("./useLiveRef"));
 const usePrevious_1 = __importDefault(require("./usePrevious"));
@@ -15,7 +15,7 @@ function getCachedValue(key, selector) {
     return ((_a = OnyxUtils_1.default.tryGetCachedValue(key, { selector })) !== null && _a !== void 0 ? _a : undefined);
 }
 function useOnyx(key, options) {
-    const connectionIDRef = (0, react_1.useRef)(null);
+    const connectionRef = (0, react_1.useRef)(null);
     const previousKey = (0, usePrevious_1.default)(key);
     // Used to stabilize the selector reference and avoid unnecessary calls to `getSnapshot()`.
     const selectorRef = (0, useLiveRef_1.default)(options === null || options === void 0 ? void 0 : options.selector);
@@ -57,6 +57,21 @@ function useOnyx(key, options) {
         }
         throw new Error(`'${previousKey}' key can't be changed to '${key}'. useOnyx() only supports dynamic keys if they are both collection member keys from the same collection e.g. from 'collection_id1' to 'collection_id2'.`);
     }, [previousKey, key]);
+    // Mimics withOnyx's checkEvictableKeys() behavior.
+    const checkEvictableKey = (0, react_1.useCallback)(() => {
+        if ((options === null || options === void 0 ? void 0 : options.canEvict) === undefined || !connectionRef.current) {
+            return;
+        }
+        if (!OnyxUtils_1.default.isSafeEvictionKey(key)) {
+            throw new Error(`canEvict can't be used on key '${key}'. This key must explicitly be flagged as safe for removal by adding it to Onyx.init({safeEvictionKeys: []}).`);
+        }
+        if (options.canEvict) {
+            OnyxConnectionManager_1.default.removeFromEvictionBlockList(connectionRef.current);
+        }
+        else {
+            OnyxConnectionManager_1.default.addToEvictionBlockList(connectionRef.current);
+        }
+    }, [key, options === null || options === void 0 ? void 0 : options.canEvict]);
     const getSnapshot = (0, react_1.useCallback)(() => {
         var _a, _b, _c;
         // We get the value from cache while the first connection to Onyx is being made,
@@ -110,7 +125,7 @@ function useOnyx(key, options) {
         return resultRef.current;
     }, [key, selectorRef, options === null || options === void 0 ? void 0 : options.allowStaleData, options === null || options === void 0 ? void 0 : options.initialValue]);
     const subscribe = (0, react_1.useCallback)((onStoreChange) => {
-        connectionIDRef.current = Onyx_1.default.connect({
+        connectionRef.current = OnyxConnectionManager_1.default.connect({
             key,
             callback: () => {
                 // Signals that the first connection was made, so some logics in `getSnapshot()`
@@ -124,29 +139,18 @@ function useOnyx(key, options) {
             initWithStoredValues: options === null || options === void 0 ? void 0 : options.initWithStoredValues,
             waitForCollectionCallback: OnyxUtils_1.default.isCollectionKey(key),
         });
+        checkEvictableKey();
         return () => {
-            if (!connectionIDRef.current) {
+            if (!connectionRef.current) {
                 return;
             }
-            Onyx_1.default.disconnect(connectionIDRef.current);
+            OnyxConnectionManager_1.default.disconnect(connectionRef.current);
             isFirstConnectionRef.current = false;
         };
-    }, [key, options === null || options === void 0 ? void 0 : options.initWithStoredValues]);
-    // Mimics withOnyx's checkEvictableKeys() behavior.
+    }, [key, options === null || options === void 0 ? void 0 : options.initWithStoredValues, checkEvictableKey]);
     (0, react_1.useEffect)(() => {
-        if ((options === null || options === void 0 ? void 0 : options.canEvict) === undefined || !connectionIDRef.current) {
-            return;
-        }
-        if (!OnyxUtils_1.default.isSafeEvictionKey(key)) {
-            throw new Error(`canEvict can't be used on key '${key}'. This key must explicitly be flagged as safe for removal by adding it to Onyx.init({safeEvictionKeys: []}).`);
-        }
-        if (options.canEvict) {
-            OnyxUtils_1.default.removeFromEvictionBlockList(key, connectionIDRef.current);
-        }
-        else {
-            OnyxUtils_1.default.addToEvictionBlockList(key, connectionIDRef.current);
-        }
-    }, [key, options === null || options === void 0 ? void 0 : options.canEvict]);
+        checkEvictableKey();
+    }, [checkEvictableKey]);
     const result = (0, react_1.useSyncExternalStore)(subscribe, getSnapshot);
     return result;
 }

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import type { OnyxInput, OnyxKey } from './types';
+import type { ConnectOptions, OnyxInput, OnyxKey } from './types';
 type EmptyObject = Record<string, never>;
 type EmptyValue = EmptyObject | null | undefined;
 /** Checks whether the given object is an object and not null/undefined. */
@@ -37,6 +37,10 @@ declare function pick<TValue>(obj: Record<string, TValue>, condition: string | s
  * @returns The object containing only the remaining entries after omission.
  */
 declare function omit<TValue>(obj: Record<string, TValue>, condition: string | string[] | ((entry: [string, TValue]) => boolean)): Record<string, TValue>;
+/**
+ * Whether the connect options has the `withOnyxInstance` property defined, that is, it's used by the `withOnyx()` HOC.
+ */
+declare function hasWithOnyxInstance<TKey extends OnyxKey>(mapping: ConnectOptions<TKey>): unknown;
 declare const _default: {
     isEmptyObject: typeof isEmptyObject;
     fastMerge: typeof fastMerge;
@@ -45,5 +49,6 @@ declare const _default: {
     checkCompatibilityWithExistingValue: typeof checkCompatibilityWithExistingValue;
     pick: typeof pick;
     omit: typeof omit;
+    hasWithOnyxInstance: typeof hasWithOnyxInstance;
 };
 export default _default;

package/dist/utils.js

@@ -170,4 +170,10 @@ function pick(obj, condition) {
 function omit(obj, condition) {
     return filterObject(obj, condition, false);
 }
-exports.default = { isEmptyObject, fastMerge, formatActionName, removeNestedNullValues, checkCompatibilityWithExistingValue, pick, omit };
+/**
+ * Whether the connect options has the `withOnyxInstance` property defined, that is, it's used by the `withOnyx()` HOC.
+ */
+function hasWithOnyxInstance(mapping) {
+    return 'withOnyxInstance' in mapping && mapping.withOnyxInstance;
+}
+exports.default = { isEmptyObject, fastMerge, formatActionName, removeNestedNullValues, checkCompatibilityWithExistingValue, pick, omit, hasWithOnyxInstance };

package/dist/withOnyx/index.js

@@ -32,11 +32,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * will automatically change to reflect the new data.
  */
 const react_1 = __importDefault(require("react"));
-const Onyx_1 = __importDefault(require("../Onyx"));
 const OnyxUtils_1 = __importDefault(require("../OnyxUtils"));
 const Str = __importStar(require("../Str"));
 const utils_1 = __importDefault(require("../utils"));
 const OnyxCache_1 = __importDefault(require("../OnyxCache"));
+const OnyxConnectionManager_1 = __importDefault(require("../OnyxConnectionManager"));
 // This is a list of keys that can exist on a `mapping`, but are not directly related to loading data from Onyx. When the keys of a mapping are looped over to check
 // if a key has changed, it's a good idea to skip looking at these properties since they would have unexpected results.
 const mappingPropertiesToIgnoreChangesTo = ['initialValue', 'allowStaleData'];
@@ -80,9 +80,9 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
                 this.shouldDelayUpdates = shouldDelayUpdates;
                 this.setWithOnyxState = this.setWithOnyxState.bind(this);
                 this.flushPendingSetStates = this.flushPendingSetStates.bind(this);
-                // This stores all the Onyx connection IDs to be used when the component unmounts so everything can be
-                // disconnected. It is a key value store with the format {[mapping.key]: connectionID}.
-                this.activeConnectionIDs = {};
+                // This stores all the Onyx connections to be used when the component unmounts so everything can be
+                // disconnected. It is a key value store with the format {[mapping.key]: connection metadata object}.
+                this.activeConnections = {};
                 const cachedState = mapOnyxToStateEntries(mapOnyxToState).reduce((resultObj, [propName, mapping]) => {
                     const key = Str.result(mapping.key, props);
                     let value = OnyxUtils_1.default.tryGetCachedValue(key, mapping);
@@ -150,8 +150,8 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
                     const previousKey = isFirstTimeUpdatingAfterLoading ? mapping.previousKey : Str.result(mapping.key, Object.assign(Object.assign({}, prevProps), prevOnyxDataFromState));
                     const newKey = Str.result(mapping.key, Object.assign(Object.assign({}, this.props), onyxDataFromState));
                     if (previousKey !== newKey) {
-                        Onyx_1.default.disconnect(this.activeConnectionIDs[previousKey], previousKey);
-                        delete this.activeConnectionIDs[previousKey];
+                        OnyxConnectionManager_1.default.disconnect(this.activeConnections[previousKey]);
+                        delete this.activeConnections[previousKey];
                         this.connectMappingToOnyx(mapping, propName, newKey);
                     }
                 });
@@ -161,7 +161,7 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
                 // Disconnect everything from Onyx
                 mapOnyxToStateEntries(mapOnyxToState).forEach(([, mapping]) => {
                     const key = Str.result(mapping.key, Object.assign(Object.assign({}, this.props), getOnyxDataFromState(this.state, mapOnyxToState)));
-                    Onyx_1.default.disconnect(this.activeConnectionIDs[key], key);
+                    OnyxConnectionManager_1.default.disconnect(this.activeConnections[key]);
                 });
             }
             setStateProxy(modifier) {
@@ -261,10 +261,10 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
                         throw new Error(`canEvict can't be used on key '${key}'. This key must explicitly be flagged as safe for removal by adding it to Onyx.init({safeEvictionKeys: []}).`);
                     }
                     if (canEvict) {
-                        OnyxUtils_1.default.removeFromEvictionBlockList(key, mapping.connectionID);
+                        OnyxConnectionManager_1.default.removeFromEvictionBlockList(this.activeConnections[key]);
                     }
                     else {
-                        OnyxUtils_1.default.addToEvictionBlockList(key, mapping.connectionID);
+                        OnyxConnectionManager_1.default.addToEvictionBlockList(this.activeConnections[key]);
                     }
                 });
             }
@@ -285,7 +285,7 @@ function default_1(mapOnyxToState, shouldDelayUpdates = false) {
                 // eslint-disable-next-line no-param-reassign
                 onyxMapping.previousKey = key;
                 // eslint-disable-next-line rulesdir/prefer-onyx-connect-in-libs
-                this.activeConnectionIDs[key] = Onyx_1.default.connect(Object.assign(Object.assign({}, mapping), { key, statePropertyName: statePropertyName, withOnyxInstance: this, displayName }));
+                this.activeConnections[key] = OnyxConnectionManager_1.default.connect(Object.assign(Object.assign({}, mapping), { key, statePropertyName: statePropertyName, withOnyxInstance: this, displayName }));
             }
             flushPendingSetStates() {
                 if (!this.shouldDelayUpdates) {

package/dist/withOnyx/types.d.ts

@@ -92,7 +92,7 @@ type Mapping<TComponentProps, TOnyxProps, TOnyxProp extends keyof TOnyxProps, TO
  * Represents a superset of `Mapping` type with internal properties included.
  */
 type WithOnyxMapping<TComponentProps, TOnyxProps> = Mapping<TComponentProps, TOnyxProps, keyof TOnyxProps, OnyxKey> & {
-    connectionID: number;
+    subscriptionID: number;
     previousKey?: OnyxKey;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-onyx",
-  "version": "2.0.63",
+  "version": "2.0.65",
   "author": "Expensify, Inc.",
   "homepage": "https://expensify.com",
   "description": "State management for React Native",