[sync] T2396 fix duplicate field schema refresh after realtime updates (#1488) (#2800)

Synced from teableio/teable-ee@02c505a

Co-authored-by: nichenqin <nichenqin@hotmail.com>

Author: tea-artist

packages/sdk/src/context/use-instances/use-instances.spec.tsx

@@ -349,6 +349,166 @@ describe('useInstances hook', () => {
     expect(createSubscribeQuery).toHaveBeenCalledTimes(2);
   });
 
+  it('recreates field queries on schema-driven setField presence with fieldIds', () => {
+    const { connection, createSubscribeQuery, presenceController, collection, queryParams } =
+      createMockConnection({
+        collection: 'fld_tblSchemaRefresh07',
+      });
+
+    renderHook(
+      () =>
+        useInstances({
+          ...mockProps,
+          collection,
+          queryParams,
+        }),
+      {
+        wrapper: createUseInstancesWrap({ ...mockAppContext, connection }),
+      }
+    );
+
+    expect(createSubscribeQuery).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      presenceController.emitReceive([
+        {
+          actionKey: 'setField',
+          payload: {
+            tableId: 'tblSchemaRefresh07',
+            field: {
+              id: 'fldSchemaRefresh07',
+            },
+            fieldIds: ['fldSchemaRefresh07'],
+          },
+        },
+      ]);
+    });
+
+    expect(createSubscribeQuery).toHaveBeenCalledTimes(2);
+  });
+
+  it('preserves field instances during schema refresh until the replacement query is ready', async () => {
+    const presenceController = createMockPresence();
+    const staleDoc = createMockDoc({
+      data: { id: 'fldOld', name: 'Old Field' },
+      collection: 'fld_tblSchemaRefresh09',
+      id: 'fldOld',
+    });
+    const freshDoc = createMockDoc({
+      data: { id: 'fldNew', name: 'New Field' },
+      collection: 'fld_tblSchemaRefresh09',
+      id: 'fldNew',
+    });
+    const queryListeners = new Map<string, Array<(...args: unknown[]) => void>>();
+    const createQuery = (results: any[], ready: boolean) =>
+      ({
+        collection: 'fld_tblSchemaRefresh09',
+        query: {},
+        results,
+        ready,
+        sent: true,
+        on: vi.fn((event: string, cb: (...args: unknown[]) => void) => {
+          const listeners = queryListeners.get(event) ?? [];
+          listeners.push(cb);
+          queryListeners.set(event, listeners);
+        }),
+        once: vi.fn(),
+        removeAllListeners: vi.fn(),
+        removeListener: vi.fn((event: string, cb: (...args: unknown[]) => void) => {
+          const listeners = queryListeners.get(event) ?? [];
+          queryListeners.set(
+            event,
+            listeners.filter((listener) => listener !== cb)
+          );
+        }),
+        destroy: vi.fn((cb?: () => void) => cb?.()),
+      }) as unknown as Query<any>;
+
+    const queries = [createQuery([staleDoc], true), createQuery([freshDoc], false)];
+    const createSubscribeQuery = vi.fn(() => queries.shift() as Query<any>);
+    const connection = {
+      createSubscribeQuery,
+      getPresence: vi.fn(() => presenceController.presence),
+    } as any;
+
+    const { result } = renderHook(
+      () =>
+        useInstances({
+          ...mockProps,
+          collection: 'fld_tblSchemaRefresh09',
+        }),
+      {
+        wrapper: createUseInstancesWrap({ ...mockAppContext, connection }),
+      }
+    );
+
+    expect(result.current.instances[0]?.doc).toBe(staleDoc);
+
+    await act(async () => {
+      presenceController.emitReceive([
+        {
+          actionKey: 'setField',
+          payload: {
+            tableId: 'tblSchemaRefresh09',
+            field: {
+              id: 'fldSchemaRefresh09',
+            },
+            fieldIds: ['fldSchemaRefresh09'],
+          },
+        },
+      ]);
+      await Promise.resolve();
+    });
+
+    expect(createSubscribeQuery).toHaveBeenCalledTimes(2);
+    expect(result.current.instances[0]?.doc).toBe(staleDoc);
+
+    act(() => {
+      const readyListeners = queryListeners.get('ready') ?? [];
+      readyListeners.forEach((listener) => listener());
+    });
+
+    expect(result.current.instances[0]?.doc).toBe(freshDoc);
+  });
+
+  it('recreates view queries on schema-driven setField presence with fieldIds', () => {
+    const { connection, createSubscribeQuery, presenceController, collection, queryParams } =
+      createMockConnection({
+        collection: 'viw_tblSchemaRefresh08',
+      });
+
+    renderHook(
+      () =>
+        useInstances({
+          ...mockProps,
+          collection,
+          queryParams,
+        }),
+      {
+        wrapper: createUseInstancesWrap({ ...mockAppContext, connection }),
+      }
+    );
+
+    expect(createSubscribeQuery).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      presenceController.emitReceive([
+        {
+          actionKey: 'setField',
+          payload: {
+            tableId: 'tblSchemaRefresh08',
+            field: {
+              id: 'fldSchemaRefresh08',
+            },
+            fieldIds: ['fldSchemaRefresh08'],
+          },
+        },
+      ]);
+    });
+
+    expect(createSubscribeQuery).toHaveBeenCalledTimes(2);
+  });
+
   it('recreates record queries on schema-driven setField presence with updatedProperties', () => {
     const { connection, createSubscribeQuery, presenceController, collection, queryParams } =
       createMockConnection({

packages/sdk/src/context/use-instances/useInstances.ts

@@ -91,8 +91,11 @@ const normalizeForKey = (value: any): any => {
   return value;
 };
 
+const makeQueryScopeKey = (collection: string, queryParams: unknown) =>
+  `${collection}|${JSON.stringify(normalizeForKey(queryParams))}`;
+
 const makeQueryKey = (collection: string, queryParams: unknown, refreshToken = 0) =>
-  `${collection}|${JSON.stringify(normalizeForKey(queryParams))}|refresh:${refreshToken}`;
+  `${makeQueryScopeKey(collection, queryParams)}|refresh:${refreshToken}`;
 
 const acquireQuery = <T>(
   collection: string,
@@ -124,9 +127,12 @@ const releaseQuery = (key?: string, cb?: () => void) => {
   cb?.();
 };
 
-const getRecordCollectionTableId = (collection: string): string | undefined => {
+const getSchemaRefreshCollectionTableId = (collection: string): string | undefined => {
   const [prefix, tableId] = collection.split('_');
-  if (prefix !== IdPrefix.Record || !tableId) {
+  if (
+    (prefix !== IdPrefix.Record && prefix !== IdPrefix.Field && prefix !== IdPrefix.View) ||
+    !tableId
+  ) {
     return undefined;
   }
   return tableId;
@@ -201,10 +207,12 @@ export function useInstances<T, R extends { id: string }>({
   initData,
 }: IUseInstancesProps<T, R>): IInstanceState<R> {
   const { connection, connected } = useConnection();
-  const recordCollectionTableId = getRecordCollectionTableId(collection);
+  const schemaRefreshCollectionTableId = getSchemaRefreshCollectionTableId(collection);
   const [query, setQuery] = useState<Query<T>>();
   const [schemaRefreshToken, setSchemaRefreshToken] = useState(0);
   const currentKeyRef = useRef<string>();
+  const currentScopeKeyRef = useRef<string>();
+  const shouldClearInstancesOnQueryCleanupRef = useRef(true);
   const [instances, dispatch] = useReducer(
     (state: IInstanceState<R>, action: IInstanceAction<T>) =>
       instanceReducer(state, action, factory),
@@ -218,12 +226,12 @@ export function useInstances<T, R extends { id: string }>({
   const lastConnectionRef = useRef<typeof connection>();
 
   useEffect(() => {
-    if (!connection || !recordCollectionTableId) {
+    if (!connection || !schemaRefreshCollectionTableId) {
       return;
     }
 
     const presence: Presence = connection.getPresence(
-      getActionTriggerChannel(recordCollectionTableId)
+      getActionTriggerChannel(schemaRefreshCollectionTableId)
     );
     if (!presence.subscribed) {
       presence.subscribe((error) => {
@@ -234,7 +242,7 @@ export function useInstances<T, R extends { id: string }>({
     }
 
     const receiveListener = (_id: string, batch: unknown) => {
-      if (!isSchemaRefreshAction(recordCollectionTableId, batch)) {
+      if (!isSchemaRefreshAction(schemaRefreshCollectionTableId, batch)) {
         return;
       }
       setSchemaRefreshToken((current) => current + 1);
@@ -249,7 +257,7 @@ export function useInstances<T, R extends { id: string }>({
         presence.destroy();
       }
     };
-  }, [connection, recordCollectionTableId]);
+  }, [connection, schemaRefreshCollectionTableId]);
 
   const handleReady = useCallback((query: Query<T>) => {
     console.log(
@@ -315,12 +323,15 @@ export function useInstances<T, R extends { id: string }>({
 
   useEffect(() => {
     if (!collection || !connection) {
+      shouldClearInstancesOnQueryCleanupRef.current = true;
+      currentScopeKeyRef.current = undefined;
       setQuery(undefined);
       return;
     }
 
     // Compute normalized key and short-circuit if unchanged and connection didn't change
     const nextKey = makeQueryKey(collection, queryParams, schemaRefreshToken);
+    const nextScopeKey = makeQueryScopeKey(collection, queryParams);
     const connectionChanged = lastConnectionRef.current !== connection;
     if (!connectionChanged && currentKeyRef.current === nextKey && preQueryRef.current) {
       // Ensure state holds the existing query instance without re-acquiring
@@ -329,12 +340,16 @@ export function useInstances<T, R extends { id: string }>({
     }
 
     const previousKey = currentKeyRef.current;
+    const previousScopeKey = currentScopeKeyRef.current;
+    shouldClearInstancesOnQueryCleanupRef.current =
+      connectionChanged || previousScopeKey !== nextScopeKey;
     if (previousKey && (connectionChanged || previousKey !== nextKey)) {
       releaseQuery(previousKey, () => opListeners.current.clear());
     }
 
     const { key, query } = acquireQuery<T>(collection, connection, queryParams, schemaRefreshToken);
     currentKeyRef.current = key;
+    currentScopeKeyRef.current = nextScopeKey;
     preQueryRef.current = query as Query<T>;
     lastConnectionRef.current = connection;
     setQuery(query as Query<T>);
@@ -349,8 +364,10 @@ export function useInstances<T, R extends { id: string }>({
       if (!hasQuery) {
         return;
       }
-      // for easy component refresh clean data when switch & loading
-      dispatch({ type: 'clear' });
+      // Preserve current instances during same-scope schema refreshes so grids do not flash blank.
+      if (shouldClearInstancesOnQueryCleanupRef.current) {
+        dispatch({ type: 'clear' });
+      }
       // release cached query on unmount or when switching queries
       releaseQuery(keyAtMount, () => listeners.clear());
     };