[POC] useOnyx subscribed

API.md

@@ -81,6 +81,7 @@ This method will be deprecated soon. Please use `Onyx.connectWithoutView()` inst
 | 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). |
+| connectOptions.subscribed | Defaults to `true`. **Only used inside `useOnyx()` hook.** When `false`, keeps the connection open        (value stays cache-warm) but stops re-rendering on background writes. It defers the render trigger, not the value: any other        render still reads the latest value, and flipping back to `true` re-renders. |
 
 **Example**  
 ```ts
@@ -103,6 +104,7 @@ Connects to an Onyx key given the options passed and listens to its changes.
 | 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). |
+| connectOptions.subscribed | Defaults to `true`. **Only used inside `useOnyx()` hook.** When `false`, keeps the connection open        (value stays cache-warm) but stops re-rendering on background writes. It defers the render trigger, not the value: any other        render still reads the latest value, and flipping back to `true` re-renders. |
 
 **Example**  
 ```ts

lib/Onyx.ts

@@ -98,6 +98,9 @@ function init({
  *        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).
+ * @param connectOptions.subscribed Defaults to `true`. **Only used inside `useOnyx()` hook.** When `false`, keeps the connection open
+ *        (value stays cache-warm) but stops re-rendering on background writes. It defers the render trigger, not the value: any other
+ *        render still reads the latest value, and flipping back to `true` re-renders.
  * @returns The connection object to use when calling `Onyx.disconnect()`.
  */
 function connect<TKey extends OnyxKey>(connectOptions: ConnectOptions<TKey>): Connection {
@@ -122,6 +125,9 @@ function connect<TKey extends OnyxKey>(connectOptions: ConnectOptions<TKey>): Co
  *        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).
+ * @param connectOptions.subscribed Defaults to `true`. **Only used inside `useOnyx()` hook.** When `false`, keeps the connection open
+ *        (value stays cache-warm) but stops re-rendering on background writes. It defers the render trigger, not the value: any other
+ *        render still reads the latest value, and flipping back to `true` re-renders.
  * @returns The connection object to use when calling `Onyx.disconnect()`.
  */
 function connectWithoutView<TKey extends OnyxKey>(connectOptions: ConnectOptions<TKey>): Connection {

lib/useOnyx.ts

@@ -26,6 +26,13 @@ type UseOnyxOptions<TKey extends OnyxKey, TReturnValue> = {
      * @see `useOnyx` cannot return `null` and so selector will replace `null` with `undefined` to maintain compatibility.
      */
     selector?: UseOnyxSelector<TKey, TReturnValue>;
+
+    /**
+     * Defaults to `true`. When `false`, keeps the connection open (value stays cache-warm) but stops
+     * re-rendering on background writes. It defers the render trigger, not the value: any other render still reads the latest value.
+     * Flipping back to `true` re-renders.
+     */
+    subscribed?: boolean;
 };
 
 type FetchStatus = 'loading' | 'loaded';
@@ -45,6 +52,13 @@ function useOnyx<TKey extends OnyxKey, TReturnValue = OnyxValue<TKey>>(
     const currentDependenciesRef = useLiveRef(dependencies);
     const selector = options?.selector;
 
+    // Read via a ref inside the Onyx callback so toggling `subscribed` never re-subscribes.
+    const subscribed = options?.subscribed !== false;
+    const subscribedRef = useRef(subscribed);
+    useEffect(() => {
+        subscribedRef.current = subscribed;
+    }, [subscribed]);
+
     // Create memoized version of selector for performance
     const memoizedSelector = useMemo((): UseOnyxSelector<TKey, TReturnValue> | null => {
         if (!selector) {
@@ -150,7 +164,10 @@ function useOnyx<TKey extends OnyxKey, TReturnValue = OnyxValue<TKey>>(
         // Invalidate cache when dependencies change so selector runs with new closure values
         onyxSnapshotCache.invalidateForKey(key);
         shouldGetCachedValueRef.current = true;
-        onStoreChangeFnRef.current();
+        // Skip the re-render while paused; the next render picks up the new dependencies via `getSnapshot()`.
+        if (subscribedRef.current) {
+            onStoreChangeFnRef.current();
+        }
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [...dependencies]);
 
@@ -266,7 +283,11 @@ function useOnyx<TKey extends OnyxKey, TReturnValue = OnyxValue<TKey>>(
                     onyxSnapshotCache.invalidateForKey(key);
 
                     // Finally, we signal that the store changed, making `getSnapshot()` be called again.
-                    onStoreChange();
+                    // Skipped while paused so background writes don't re-render; the freshest value is still
+                    // read via `getSnapshot()` on the next render.
+                    if (subscribedRef.current) {
+                        onStoreChange();
+                    }
                 },
                 reuseConnection: options?.reuseConnection,
             });

tests/unit/useOnyxTest.ts

@@ -1318,4 +1318,155 @@ describe('useOnyx', () => {
             expect(renders.length).toBe(3);
         });
     });
+
+    describe('subscribed option', () => {
+        type SubscribedProps = {subscribed?: boolean; tick?: number};
+
+        // While subscribed is false, a background write should not re-render the consumer.
+        it('does not re-render on a background write when subscribed is false', async () => {
+            await Onyx.set(ONYXKEYS.TEST_KEY, 'v1');
+
+            const renders: Array<{value: unknown; status: string}> = [];
+            const {result} = renderHook(
+                ({subscribed}: SubscribedProps) => {
+                    const r = useOnyx(ONYXKEYS.TEST_KEY, {subscribed});
+                    renders.push({value: r[0], status: r[1].status});
+                    return r;
+                },
+                {initialProps: {subscribed: false}},
+            );
+
+            // Mount reads the warm value straight from cache
+            await act(async () => waitForPromisesToResolve());
+            expect(result.current[0]).toEqual('v1');
+            expect(renders.length).toBe(1);
+
+            // Background write while paused — connection stays open but onStoreChange is gated
+            await act(async () => {
+                Onyx.merge(ONYXKEYS.TEST_KEY, 'v2');
+                await waitForPromisesToResolve();
+            });
+
+            // No extra render, and the value is intentionally still the old one
+            expect(renders.length).toBe(1);
+            expect(result.current[0]).toEqual('v1');
+        });
+
+        // A render from any other cause while paused should serve the latest value, not a stale snapshot.
+        // Keeping the connection open and invalidating on each write is what makes this pass.
+        it('serves the latest value on an unrelated re-render while subscribed is false', async () => {
+            await Onyx.set(ONYXKEYS.TEST_KEY, 'v1');
+
+            const {result, rerender} = renderHook(({subscribed}: SubscribedProps) => useOnyx(ONYXKEYS.TEST_KEY, {subscribed}), {
+                initialProps: {subscribed: false, tick: 0} as SubscribedProps,
+            });
+
+            await act(async () => waitForPromisesToResolve());
+            expect(result.current[0]).toEqual('v1');
+
+            // Write while paused — no re-render from Onyx
+            await act(async () => {
+                Onyx.merge(ONYXKEYS.TEST_KEY, 'v2');
+                await waitForPromisesToResolve();
+            });
+            expect(result.current[0]).toEqual('v1'); // Not yet re-rendered
+
+            // Force an unrelated re-render — subscribed stays false, only tick changes
+            await act(async () => {
+                rerender({subscribed: false, tick: 1});
+            });
+
+            // getSnapshot should read fresh: v2, not the stale v1
+            expect(result.current[0]).toEqual('v2');
+        });
+
+        // Flipping subscribed from false to true (re-focus) re-renders with the latest value, and a warm
+        // key shows 'loaded' immediately without a loading flash.
+        it('catches up to the latest value with no loading flash when flipped back to subscribed', async () => {
+            await Onyx.set(ONYXKEYS.TEST_KEY, 'v1');
+
+            const {result, rerender} = renderHook(({subscribed}: SubscribedProps) => useOnyx(ONYXKEYS.TEST_KEY, {subscribed}), {initialProps: {subscribed: false} as SubscribedProps});
+
+            await act(async () => waitForPromisesToResolve());
+            expect(result.current[0]).toEqual('v1');
+
+            await act(async () => {
+                Onyx.merge(ONYXKEYS.TEST_KEY, 'v2');
+                await waitForPromisesToResolve();
+            });
+            expect(result.current[0]).toEqual('v1'); // Paused: still stale
+
+            // Re-focus
+            await act(async () => {
+                rerender({subscribed: true});
+            });
+
+            expect(result.current[0]).toEqual('v2');
+            expect(result.current[1].status).toEqual('loaded');
+
+            // Once subscribed again, later writes re-render
+            await act(async () => {
+                Onyx.merge(ONYXKEYS.TEST_KEY, 'v3');
+                await waitForPromisesToResolve();
+            });
+            expect(result.current[0]).toEqual('v3');
+        });
+
+        // Default (true) is unchanged: writes re-render as before.
+        it('re-renders on background writes when subscribed is omitted (default true)', async () => {
+            await Onyx.set(ONYXKEYS.TEST_KEY, 'v1');
+
+            const renders: Array<{value: unknown; status: string}> = [];
+            const {result} = renderHook(() => {
+                const r = useOnyx(ONYXKEYS.TEST_KEY);
+                renders.push({value: r[0], status: r[1].status});
+                return r;
+            });
+
+            await act(async () => waitForPromisesToResolve());
+            const rendersAfterMount = renders.length;
+
+            await act(async () => {
+                Onyx.merge(ONYXKEYS.TEST_KEY, 'v2');
+                await waitForPromisesToResolve();
+            });
+
+            expect(result.current[0]).toEqual('v2');
+            expect(renders.length).toBeGreaterThan(rendersAfterMount);
+        });
+
+        // With two subscribers on the same key, pausing one should not stop the other from re-rendering.
+        it('isolates paused/active subscribers sharing a connection (reuseConnection)', async () => {
+            await Onyx.set(ONYXKEYS.TEST_KEY, 'v1');
+
+            const activeRenders: unknown[] = [];
+            const pausedRenders: unknown[] = [];
+
+            const active = renderHook(() => {
+                const r = useOnyx(ONYXKEYS.TEST_KEY, {reuseConnection: true});
+                activeRenders.push(r[0]);
+                return r;
+            });
+            const paused = renderHook(() => {
+                const r = useOnyx(ONYXKEYS.TEST_KEY, {reuseConnection: true, subscribed: false});
+                pausedRenders.push(r[0]);
+                return r;
+            });
+
+            await act(async () => waitForPromisesToResolve());
+            const activeAfterMount = activeRenders.length;
+            const pausedAfterMount = pausedRenders.length;
+
+            await act(async () => {
+                Onyx.merge(ONYXKEYS.TEST_KEY, 'v2');
+                await waitForPromisesToResolve();
+            });
+
+            // Active subscriber re-rendered to the new value; paused one did not re-render at all
+            expect(active.result.current[0]).toEqual('v2');
+            expect(activeRenders.length).toBeGreaterThan(activeAfterMount);
+            expect(pausedRenders.length).toBe(pausedAfterMount);
+            expect(paused.result.current[0]).toEqual('v1');
+        });
+    });
 });