Add warning when keyExtractor is not defined with maintainVisibleContentPosition (#1862)

* Add warning when keyExtractor is not defined with maintainVisibleContentPosition

When using maintainVisibleContentPosition (through onStartReached), keyExtractor is essential for proper item tracking. This warning helps developers identify potential issues early.

* Add tests for keyExtractor warning with maintainVisibleContentPosition

Tests verify that the warning is shown when onStartReached is used without keyExtractor, and that no warnings appear in other scenarios.

* Fix test ts errors

Author: naqvitalha

src/__tests__/RecyclerViewManager.test.ts

@@ -0,0 +1,74 @@
+import { RecyclerViewManager } from "../recyclerview/RecyclerViewManager";
+import { WarningMessages } from "../errors/WarningMessages";
+import { FlashListProps } from "../FlashListProps";
+
+describe("RecyclerViewManager", () => {
+  let consoleWarnSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    consoleWarnSpy = jest.spyOn(console, "warn").mockImplementation();
+  });
+
+  afterEach(() => {
+    consoleWarnSpy.mockRestore();
+  });
+
+  describe("keyExtractor warning with maintainVisibleContentPosition", () => {
+    const createMockProps = (overrides = {}) =>
+      ({
+        data: [{ id: 1 }, { id: 2 }, { id: 3 }],
+        renderItem: jest.fn(),
+        ...overrides,
+      } as FlashListProps<unknown>);
+
+    const createManager = (props: FlashListProps<unknown>) => {
+      return new RecyclerViewManager(props);
+    };
+
+    it("should warn when onStartReached is defined but keyExtractor is not", () => {
+      const props = createMockProps({
+        onStartReached: jest.fn(),
+        keyExtractor: undefined,
+      });
+
+      createManager(props);
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        WarningMessages.keyExtractorNotDefinedForMVCP
+      );
+    });
+
+    it("should not warn when both onStartReached and keyExtractor are defined", () => {
+      const props = createMockProps({
+        onStartReached: jest.fn(),
+        keyExtractor: (item: any) => item.id.toString(),
+      });
+
+      createManager(props);
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+    });
+
+    it("should not warn when onStartReached is not defined", () => {
+      const props = createMockProps({
+        onStartReached: undefined,
+        keyExtractor: undefined,
+      });
+
+      createManager(props);
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+    });
+
+    it("should not warn when onStartReached is not defined but keyExtractor is", () => {
+      const props = createMockProps({
+        onStartReached: undefined,
+        keyExtractor: (item: any) => item.id.toString(),
+      });
+
+      createManager(props);
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+    });
+  });
+});

src/errors/WarningMessages.ts

@@ -1,6 +1,8 @@
 export const WarningMessages = {
   keyExtractorNotDefinedForAnimation:
     "keyExtractor is not defined. This might cause the animations to not work as expected.",
+  keyExtractorNotDefinedForMVCP:
+    "keyExtractor is not defined, maintainVisibleContentPosition may not work as expected.",
   exceededMaxRendersWithoutCommit:
     "Exceeded max renders without commit. This might mean that you have duplicate keys in your keyExtractor output or your list is nested in a ScrollView causing a lot of items to render at once. " +
     "If it's none of those and is causing a real issue or error, consider reporing this on FlashList Github",

src/recyclerview/RecyclerViewManager.ts

@@ -1,4 +1,5 @@
 import { ErrorMessages } from "../errors/ErrorMessages";
+import { WarningMessages } from "../errors/WarningMessages";
 
 import ViewabilityManager from "./viewability/ViewabilityManager";
 import { ConsecutiveNumbers } from "./helpers/ConsecutiveNumbers";
@@ -69,6 +70,7 @@ export class RecyclerViewManager<T> {
       props.maxItemsInRecyclePool
     );
     this.itemViewabilityManager = new ViewabilityManager<T>(this as any);
+    this.checkPropsAndWarn();
   }
 
   // updates render stack based on the engaged indices which are sorted. Recycles unused keys.
@@ -446,4 +448,10 @@ export class RecyclerViewManager<T> {
       this.propsRef.extraData
     );
   }
+
+  private checkPropsAndWarn() {
+    if (this.propsRef.onStartReached && !this.propsRef.keyExtractor) {
+      console.warn(WarningMessages.keyExtractorNotDefinedForMVCP);
+    }
+  }
 }