react-native-onyx 2.0.135 → 2.0.136

package/dist/OnyxConnectionManager.js

@@ -42,6 +42,7 @@ const OnyxUtils_1 = __importDefault(require("./OnyxUtils"));
 const Str = __importStar(require("./Str"));
 const utils_1 = __importDefault(require("./utils"));
 const OnyxCache_1 = __importDefault(require("./OnyxCache"));
+const OnyxSnapshotCache_1 = __importDefault(require("./OnyxSnapshotCache"));
 /**
  * Manages Onyx connections of `Onyx.connect()`, `useOnyx()` and `withOnyx()` subscribers.
  */
@@ -182,12 +183,16 @@ class OnyxConnectionManager {
             });
         });
         this.connectionsMap.clear();
+        // Clear snapshot cache when all connections are disconnected
+        OnyxSnapshotCache_1.default.clear();
     }
     /**
      * Refreshes the connection manager's session ID.
      */
     refreshSessionID() {
         this.sessionID = Str.guid();
+        // Clear snapshot cache when session refreshes to avoid stale cache issues
+        OnyxSnapshotCache_1.default.clear();
     }
     /**
      * Adds the connection to the eviction block list. Connections added to this list can never be evicted.

package/dist/OnyxSnapshotCache.d.ts

@@ -0,0 +1,78 @@
+import type { OnyxKey, OnyxValue } from './types';
+import type { UseOnyxOptions, UseOnyxResult, UseOnyxSelector } from './useOnyx';
+/**
+ * Manages snapshot caching for useOnyx hook performance optimization.
+ * Handles selector function tracking and memoized getSnapshot results.
+ */
+declare class OnyxSnapshotCache {
+    /**
+     * Snapshot cache is a two-level map. The top-level keys are Onyx keys. The top-level values maps.
+     * The second-level keys are a custom composite string defined by this.registerConsumer. These represent a unique useOnyx config, which is not fully represented by the Onyx key alone.
+     * The reason we have two levels is for performance: not to make cache access faster, but to make cache invalidation faster.
+     * We can invalidate the snapshot cache for a given Onyx key with one map.delete operation on the top-level map, rather than having to loop through a large single-level map and delete any matching keys.
+     */
+    private snapshotCache;
+    /**
+     * Maps selector functions to unique IDs for cache key generation
+     */
+    private selectorIDMap;
+    /**
+     * Counter for generating incremental selector IDs
+     */
+    private selectorIDCounter;
+    /**
+     * Reference counting for cache keys to enable automatic cleanup.
+     * Maps cache key (string) to number of consumers using it.
+     */
+    private cacheKeyRefCounts;
+    constructor();
+    /**
+     * Generate unique ID for selector functions using incrementing numbers
+     */
+    getSelectorID<TKey extends OnyxKey, TReturnValue>(selector: UseOnyxSelector<TKey, TReturnValue>): number;
+    /**
+     * Register a consumer for a cache key and return the cache key.
+     * Generates cache key and increments reference counter.
+     *
+     * The properties used to generate the cache key are handpicked for performance reasons and
+     * according to their purpose and effect they produce in the useOnyx hook behavior:
+     *
+     * - `selector`: Different selectors produce different results, so each selector needs its own cache entry
+     * - `initWithStoredValues`: This flag changes the initial loading behavior and affects the returned fetch status
+     * - `allowStaleData`: Controls whether stale data can be returned during pending merges, affecting result timing
+     * - `canBeMissing`: Determines logging behavior for missing data, but doesn't affect the actual data returned
+     *
+     * Other options like `canEvict`, `reuseConnection`, and `allowDynamicKey` don't affect the data transformation
+     * or timing behavior of getSnapshot, so they're excluded from the cache key for better cache hit rates.
+     */
+    registerConsumer<TKey extends OnyxKey, TReturnValue>(options: Pick<UseOnyxOptions<TKey, TReturnValue>, 'selector' | 'initWithStoredValues' | 'allowStaleData' | 'canBeMissing'>): string;
+    /**
+     * Deregister a consumer for a cache key.
+     * Decrements reference counter and removes cache entry if no consumers remain.
+     */
+    deregisterConsumer(key: OnyxKey, cacheKey: string): void;
+    /**
+     * Get cached snapshot result for a key and cache key combination
+     */
+    getCachedResult<TResult extends UseOnyxResult<OnyxValue<OnyxKey>>>(key: OnyxKey, cacheKey: string): TResult | undefined;
+    /**
+     * Set cached snapshot result for a key and cache key combination
+     */
+    setCachedResult<TResult extends UseOnyxResult<OnyxValue<OnyxKey>>>(key: OnyxKey, cacheKey: string, result: TResult): void;
+    /**
+     * Selective cache invalidation to prevent data unavailability
+     * Collection members invalidate upward, collections don't cascade downward
+     */
+    invalidateForKey(keyToInvalidate: OnyxKey): void;
+    /**
+     * Clear all snapshot cache
+     */
+    clear(): void;
+    /**
+     * Clear selector ID mappings (useful for testing)
+     */
+    clearSelectorIds(): void;
+}
+declare const onyxSnapshotCache: OnyxSnapshotCache;
+export default onyxSnapshotCache;
+export { OnyxSnapshotCache };

package/dist/OnyxSnapshotCache.js

@@ -0,0 +1,130 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnyxSnapshotCache = void 0;
+const OnyxUtils_1 = __importDefault(require("./OnyxUtils"));
+/**
+ * Manages snapshot caching for useOnyx hook performance optimization.
+ * Handles selector function tracking and memoized getSnapshot results.
+ */
+class OnyxSnapshotCache {
+    constructor() {
+        this.snapshotCache = new Map();
+        this.selectorIDMap = new Map();
+        this.selectorIDCounter = 0;
+        this.cacheKeyRefCounts = new Map();
+    }
+    /**
+     * Generate unique ID for selector functions using incrementing numbers
+     */
+    getSelectorID(selector) {
+        const typedSelector = selector;
+        if (!this.selectorIDMap.has(typedSelector)) {
+            const id = this.selectorIDCounter++;
+            this.selectorIDMap.set(typedSelector, id);
+        }
+        return this.selectorIDMap.get(typedSelector);
+    }
+    /**
+     * Register a consumer for a cache key and return the cache key.
+     * Generates cache key and increments reference counter.
+     *
+     * The properties used to generate the cache key are handpicked for performance reasons and
+     * according to their purpose and effect they produce in the useOnyx hook behavior:
+     *
+     * - `selector`: Different selectors produce different results, so each selector needs its own cache entry
+     * - `initWithStoredValues`: This flag changes the initial loading behavior and affects the returned fetch status
+     * - `allowStaleData`: Controls whether stale data can be returned during pending merges, affecting result timing
+     * - `canBeMissing`: Determines logging behavior for missing data, but doesn't affect the actual data returned
+     *
+     * Other options like `canEvict`, `reuseConnection`, and `allowDynamicKey` don't affect the data transformation
+     * or timing behavior of getSnapshot, so they're excluded from the cache key for better cache hit rates.
+     */
+    registerConsumer(options) {
+        var _a, _b, _c;
+        const selectorID = (options === null || options === void 0 ? void 0 : options.selector) ? this.getSelectorID(options.selector) : 'no_selector';
+        // Create options hash without expensive JSON.stringify
+        const initWithStoredValues = (_a = options === null || options === void 0 ? void 0 : options.initWithStoredValues) !== null && _a !== void 0 ? _a : true;
+        const allowStaleData = (_b = options === null || options === void 0 ? void 0 : options.allowStaleData) !== null && _b !== void 0 ? _b : false;
+        const canBeMissing = (_c = options === null || options === void 0 ? void 0 : options.canBeMissing) !== null && _c !== void 0 ? _c : true;
+        const cacheKey = `${selectorID}_${initWithStoredValues}_${allowStaleData}_${canBeMissing}`;
+        // Increment reference count for this cache key
+        const currentCount = this.cacheKeyRefCounts.get(cacheKey) || 0;
+        this.cacheKeyRefCounts.set(cacheKey, currentCount + 1);
+        return cacheKey;
+    }
+    /**
+     * Deregister a consumer for a cache key.
+     * Decrements reference counter and removes cache entry if no consumers remain.
+     */
+    deregisterConsumer(key, cacheKey) {
+        const currentCount = this.cacheKeyRefCounts.get(cacheKey) || 0;
+        if (currentCount <= 1) {
+            // Last consumer - remove from reference counter and cache
+            this.cacheKeyRefCounts.delete(cacheKey);
+            // Remove from snapshot cache
+            const keyCache = this.snapshotCache.get(key);
+            if (keyCache) {
+                keyCache.delete(cacheKey);
+                // If this was the last cache entry for this Onyx key, remove the key entirely
+                if (keyCache.size === 0) {
+                    this.snapshotCache.delete(key);
+                }
+            }
+        }
+        else {
+            // Still has other consumers - just decrement count
+            this.cacheKeyRefCounts.set(cacheKey, currentCount - 1);
+        }
+    }
+    /**
+     * Get cached snapshot result for a key and cache key combination
+     */
+    getCachedResult(key, cacheKey) {
+        const keyCache = this.snapshotCache.get(key);
+        return keyCache === null || keyCache === void 0 ? void 0 : keyCache.get(cacheKey);
+    }
+    /**
+     * Set cached snapshot result for a key and cache key combination
+     */
+    setCachedResult(key, cacheKey, result) {
+        if (!this.snapshotCache.has(key)) {
+            this.snapshotCache.set(key, new Map());
+        }
+        this.snapshotCache.get(key).set(cacheKey, result);
+    }
+    /**
+     * Selective cache invalidation to prevent data unavailability
+     * Collection members invalidate upward, collections don't cascade downward
+     */
+    invalidateForKey(keyToInvalidate) {
+        // Always invalidate the exact key
+        this.snapshotCache.delete(keyToInvalidate);
+        try {
+            // Check if the key is a collection member and invalidate the collection base key
+            const collectionBaseKey = OnyxUtils_1.default.getCollectionKey(keyToInvalidate);
+            this.snapshotCache.delete(collectionBaseKey);
+        }
+        catch (e) {
+            // do nothing - this just means the key is not a collection member
+        }
+    }
+    /**
+     * Clear all snapshot cache
+     */
+    clear() {
+        this.snapshotCache.clear();
+    }
+    /**
+     * Clear selector ID mappings (useful for testing)
+     */
+    clearSelectorIds() {
+        this.selectorIDCounter = 0;
+    }
+}
+exports.OnyxSnapshotCache = OnyxSnapshotCache;
+// Create and export a singleton instance
+const onyxSnapshotCache = new OnyxSnapshotCache();
+exports.default = onyxSnapshotCache;

package/dist/useOnyx.d.ts

@@ -47,4 +47,4 @@ type ResultMetadata<TValue> = {
 type UseOnyxResult<TValue> = [NonNullable<TValue> | undefined, ResultMetadata<TValue>];
 declare function useOnyx<TKey extends OnyxKey, TReturnValue = OnyxValue<TKey>>(key: TKey, options?: UseOnyxOptions<TKey, TReturnValue>, dependencies?: DependencyList): UseOnyxResult<TReturnValue>;
 export default useOnyx;
-export type { FetchStatus, ResultMetadata, UseOnyxResult, UseOnyxOptions };
+export type { FetchStatus, ResultMetadata, UseOnyxResult, UseOnyxOptions, UseOnyxSelector };

package/dist/useOnyx.js

@@ -45,6 +45,7 @@ const GlobalSettings = __importStar(require("./GlobalSettings"));
 const usePrevious_1 = __importDefault(require("./usePrevious"));
 const metrics_1 = __importDefault(require("./metrics"));
 const Logger = __importStar(require("./Logger"));
+const OnyxSnapshotCache_1 = __importDefault(require("./OnyxSnapshotCache"));
 const useLiveRef_1 = __importDefault(require("./useLiveRef"));
 function useOnyx(key, options, dependencies = []) {
     const connectionRef = (0, react_1.useRef)(null);
@@ -105,6 +106,14 @@ function useOnyx(key, options, dependencies = []) {
     const shouldGetCachedValueRef = (0, react_1.useRef)(true);
     // Inside useOnyx.ts, we need to track the sourceValue separately
     const sourceValueRef = (0, react_1.useRef)(undefined);
+    // Cache the options key to avoid regenerating it every getSnapshot call
+    const cacheKey = (0, react_1.useMemo)(() => OnyxSnapshotCache_1.default.registerConsumer({
+        selector: options === null || options === void 0 ? void 0 : options.selector,
+        initWithStoredValues: options === null || options === void 0 ? void 0 : options.initWithStoredValues,
+        allowStaleData: options === null || options === void 0 ? void 0 : options.allowStaleData,
+        canBeMissing: options === null || options === void 0 ? void 0 : options.canBeMissing,
+    }), [options === null || options === void 0 ? void 0 : options.selector, options === null || options === void 0 ? void 0 : options.initWithStoredValues, options === null || options === void 0 ? void 0 : options.allowStaleData, options === null || options === void 0 ? void 0 : options.canBeMissing]);
+    (0, react_1.useEffect)(() => () => OnyxSnapshotCache_1.default.deregisterConsumer(key, cacheKey), [key, cacheKey]);
     (0, react_1.useEffect)(() => {
         // These conditions will ensure we can only handle dynamic collection member keys from the same collection.
         if ((options === null || options === void 0 ? void 0 : options.allowDynamicKey) || previousKey === key) {
@@ -137,6 +146,8 @@ function useOnyx(key, options, dependencies = []) {
         if (connectionRef.current === null || isConnectingRef.current || !onStoreChangeFnRef.current) {
             return;
         }
+        // Invalidate cache when dependencies change so selector runs with new closure values
+        OnyxSnapshotCache_1.default.invalidateForKey(key);
         shouldGetCachedValueRef.current = true;
         onStoreChangeFnRef.current();
         // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -158,10 +169,23 @@ function useOnyx(key, options, dependencies = []) {
     }, [key, options === null || options === void 0 ? void 0 : options.canEvict]);
     const getSnapshot = (0, react_1.useCallback)(() => {
         var _a, _b, _c, _d;
+        // Check if we have any cache for this Onyx key
+        // Don't use cache for first connection with initWithStoredValues: false
+        // Also don't use cache during active data updates (when shouldGetCachedValueRef is true)
+        if (!(isFirstConnectionRef.current && (options === null || options === void 0 ? void 0 : options.initWithStoredValues) === false) && !shouldGetCachedValueRef.current) {
+            const cachedResult = OnyxSnapshotCache_1.default.getCachedResult(key, cacheKey);
+            if (cachedResult !== undefined) {
+                resultRef.current = cachedResult;
+                return cachedResult;
+            }
+        }
         let isOnyxValueDefined = true;
         // We return the initial result right away during the first connection if `initWithStoredValues` is set to `false`.
         if (isFirstConnectionRef.current && (options === null || options === void 0 ? void 0 : options.initWithStoredValues) === false) {
-            return resultRef.current;
+            const result = resultRef.current;
+            // Store result in snapshot cache
+            OnyxSnapshotCache_1.default.setCachedResult(key, cacheKey, result);
+            return result;
         }
         // We get the value from cache while the first connection to Onyx is being made,
         // so we can return any cached value right away. After the connection is made, we only
@@ -188,7 +212,7 @@ function useOnyx(key, options, dependencies = []) {
             newValueRef.current = undefined;
             newFetchStatus = 'loading';
         }
-        // Optimized equality checking - eliminated redundant deep equality:
+        // Optimized equality checking:
         // - Memoized selectors already handle deep equality internally, so we can use fast reference equality
         // - Non-selector cases use shallow equality for object reference checks
         // - Normalize null to undefined to ensure consistent comparison (both represent "no value")
@@ -226,8 +250,9 @@ function useOnyx(key, options, dependencies = []) {
                 Logger.logAlert(`useOnyx returned no data for key with canBeMissing set to false for key ${key}`, { showAlert: true });
             }
         }
+        OnyxSnapshotCache_1.default.setCachedResult(key, cacheKey, resultRef.current);
         return resultRef.current;
-    }, [options === null || options === void 0 ? void 0 : options.initWithStoredValues, options === null || options === void 0 ? void 0 : options.allowStaleData, options === null || options === void 0 ? void 0 : options.canBeMissing, key, memoizedSelector]);
+    }, [options === null || options === void 0 ? void 0 : options.initWithStoredValues, options === null || options === void 0 ? void 0 : options.allowStaleData, options === null || options === void 0 ? void 0 : options.canBeMissing, key, memoizedSelector, cacheKey]);
     const subscribe = (0, react_1.useCallback)((onStoreChange) => {
         isConnectingRef.current = true;
         onStoreChangeFnRef.current = onStoreChange;
@@ -243,6 +268,8 @@ function useOnyx(key, options, dependencies = []) {
                 shouldGetCachedValueRef.current = true;
                 // sourceValue is unknown type, so we need to cast it to the correct type.
                 sourceValueRef.current = sourceValue;
+                // Invalidate snapshot cache for this key when data changes
+                OnyxSnapshotCache_1.default.invalidateForKey(key);
                 // Finally, we signal that the store changed, making `getSnapshot()` be called again.
                 onStoreChange();
             },

package/package.json

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