feat: deal with memoization issues

Author: yf-yang

README.md

@@ -59,6 +59,7 @@ The **`options`** object can include several properties to customize the behavio
 - **`delay`**: If you need to introduce a delay in state updates, you can specify it here. Optional.
 - **`effect`**: A React component that can be used to run effects inside the provider. Optional.
 - **`extend`**: Extend the store with derived atoms based on the store state. Optional.
+- **`infiniteRenderDetectionLimit`**: In non production mode, it will throw an error if the number of `useValue` hook calls exceeds this limit during the same render. Optional.
 
 #### Return Value
 
@@ -73,14 +74,20 @@ The **`createAtomStore`** function returns an object (**`AtomStoreApi`**) contai
       // alternative
       const element = useElementStore().useValue('element');
     ```
-    - Advanced: `useValue` supports parameters `selector`, which is a function that takes the current value and returns a new value and parameter `equalityFn`, which is a function that compares the previous and new values and only re-renders if they are not equal. Internally, it uses [selectAtom](https://jotai.org/docs/utilities/select#selectatom)
+    - Advanced: `useValue` supports parameters `selector`, which is a function that takes the current value and returns a new value and parameter `equalityFn`, which is a function that compares the previous and new values and only re-renders if they are not equal. Internally, it uses [selectAtom](https://jotai.org/docs/utilities/select#selectatom). You must memoize `selector`/`equalityFn` adequately.
     ``` js
       const store = useElementStore();
+
+      // Memoize the selector yourself
       const toUpperCase = useCallback((element) => element.toUpperCase(), []);
       // Now it will only re-render if the uppercase value changes
       const element = store.useElementValue(toUpperCase);
       // alternative
       const element = useElementStore().useValue('element', toUpperCase);
+
+      // Pass an dependency array to prevent re-renders
+      const [n, setN] = useState(0); // n may change during re-renders
+      const numNthCharacter = useCallback((element) => element[n], [n]);
     ```
   - **`useSet`**: Hooks for setting a state within a component. See [useSetAtom](https://jotai.org/docs/core/use-atom#usesetatom).
     ``` js
@@ -296,7 +303,32 @@ const Component = () => {
 };
 ```
 
-## Migrate from v1 to v2
+## **Troubleshooting**
+### Error: use<Key>Value/useValue has rendered `num` times in the same render
+When calling `use<Key>Value` or `useValue` with `selector` and `equalityFn`, those two functions must be memoized. Otherwise, the component will re-render infinitely. In order to prevent developers from making this mistake, in non-production mode (`process.env.NODE_ENV !== 'production'`), we will throw an error if the number of `useValue` hook calls exceeds a certain limit.
+
+Usually, this error is caused by not memoizing the `selector` or `equalityFn` functions. To fix this, you can use `useCallback` to memoize the functions, or pass a dependency array yourselves. We support multiple alternatives:
+
+```tsx
+// No selector at all
+useValue('key')
+
+// Memoize with useCallback yourself
+const memoizedSelector = useCallback(selector, [...]);
+const memoizedEqualityFn = useCallback(equalityFn, [...]);
+// memoizedEqualityFn is an optional parameter
+useValue('key', memoizedSelector, memoizedEqualityFn);
+
+// Provide selector and its deps
+useValue('key', selector, [...]);
+
+// Provide selector and equalityFn and all of their deps
+useValue('key', selector, equalityFn, [...]);
+```
+
+The error could also be a false positive, since the internal counter is shared across all `useValue` calls of the same store. If your component tree is very deep and uses the same store's `useValue` multiple times, then the limit could be reached. To deal with that, `createAtomStore` supports an optional parameter `infiniteRenderDetectionLimit`. You can configure that with a higher limit.
+
+## **Migrate from v1 to v2**
 
 1. Return of `use<Name>Store`: `get` is renamed to `use<Key>Value`, `set` is renamed to `useSet<Key>`, `use` is renamed to `useState`.
 ``` diff

packages/jotai-x/README.md

@@ -59,6 +59,7 @@ The **`options`** object can include several properties to customize the behavio
 - **`delay`**: If you need to introduce a delay in state updates, you can specify it here. Optional.
 - **`effect`**: A React component that can be used to run effects inside the provider. Optional.
 - **`extend`**: Extend the store with derived atoms based on the store state. Optional.
+- **`infiniteRenderDetectionLimit`**: In non production mode, it will throw an error if the number of `useValue` hook calls exceeds this limit during the same render. Optional.
 
 #### Return Value
 
@@ -73,14 +74,20 @@ The **`createAtomStore`** function returns an object (**`AtomStoreApi`**) contai
       // alternative
       const element = useElementStore().useValue('element');
     ```
-    - Advanced: `useValue` supports parameters `selector`, which is a function that takes the current value and returns a new value and parameter `equalityFn`, which is a function that compares the previous and new values and only re-renders if they are not equal. Internally, it uses [selectAtom](https://jotai.org/docs/utilities/select#selectatom)
+    - Advanced: `useValue` supports parameters `selector`, which is a function that takes the current value and returns a new value and parameter `equalityFn`, which is a function that compares the previous and new values and only re-renders if they are not equal. Internally, it uses [selectAtom](https://jotai.org/docs/utilities/select#selectatom). You must memoize `selector`/`equalityFn` adequately.
     ``` js
       const store = useElementStore();
+
+      // Memoize the selector yourself
       const toUpperCase = useCallback((element) => element.toUpperCase(), []);
       // Now it will only re-render if the uppercase value changes
       const element = store.useElementValue(toUpperCase);
       // alternative
       const element = useElementStore().useValue('element', toUpperCase);
+
+      // Pass an dependency array to prevent re-renders
+      const [n, setN] = useState(0); // n may change during re-renders
+      const numNthCharacter = useCallback((element) => element[n], [n]);
     ```
   - **`useSet`**: Hooks for setting a state within a component. See [useSetAtom](https://jotai.org/docs/core/use-atom#usesetatom).
     ``` js
@@ -296,7 +303,32 @@ const Component = () => {
 };
 ```
 
-## Migrate from v1 to v2
+## **Troubleshooting**
+### Error: use<Key>Value/useValue has rendered `num` times in the same render
+When calling `use<Key>Value` or `useValue` with `selector` and `equalityFn`, those two functions must be memoized. Otherwise, the component will re-render infinitely. In order to prevent developers from making this mistake, in non-production mode (`process.env.NODE_ENV !== 'production'`), we will throw an error if the number of `useValue` hook calls exceeds a certain limit.
+
+Usually, this error is caused by not memoizing the `selector` or `equalityFn` functions. To fix this, you can use `useCallback` to memoize the functions, or pass a dependency array yourselves. We support multiple alternatives:
+
+```tsx
+// No selector at all
+useValue('key')
+
+// Memoize with useCallback yourself
+const memoizedSelector = useCallback(selector, [...]);
+const memoizedEqualityFn = useCallback(equalityFn, [...]);
+// memoizedEqualityFn is an optional parameter
+useValue('key', memoizedSelector, memoizedEqualityFn);
+
+// Provide selector and its deps
+useValue('key', selector, [...]);
+
+// Provide selector and equalityFn and all of their deps
+useValue('key', selector, equalityFn, [...]);
+```
+
+The error could also be a false positive, since the internal counter is shared across all `useValue` calls of the same store. If your component tree is very deep and uses the same store's `useValue` multiple times, then the limit could be reached. To deal with that, `createAtomStore` supports an optional parameter `infiniteRenderDetectionLimit`. You can configure that with a higher limit.
+
+## **Migrate from v1 to v2**
 
 1. Return of `use<Name>Store`: `get` is renamed to `use<Key>Value`, `set` is renamed to `useSet<Key>`, `use` is renamed to `useState`.
 ``` diff

packages/jotai-x/src/createAtomStore.spec.tsx

@@ -14,7 +14,7 @@ describe('createAtomStore', () => {
       arr: string[];
     };
 
-    const INITIAL_NUM = 42;
+    const INITIAL_NUM = 0;
     const INITIAL_ARR = ['alice', 'bob'];
 
     const initialTestStoreValue: MyTestStoreValue = {
@@ -71,6 +71,38 @@ describe('createAtomStore', () => {
       return <div>{arr1}</div>;
     };
 
+    let arrNumRenderCount = 0;
+    const ArrNumRenderer = () => {
+      arrNumRenderCount += 1;
+      const store = useMyTestStoreStore();
+      const num = store.useNumValue();
+      const selectArrNum = useCallback((v: string[]) => v[num], [num]);
+      const arrNum = store.useArrValue(selectArrNum);
+      return (
+        <div>
+          <div>arrNum: {arrNum}</div>
+        </div>
+      );
+    };
+
+    let arrNumRenderWithDepsCount = 0;
+    const ArrNumRendererWithDeps = () => {
+      arrNumRenderWithDepsCount += 1;
+      const store = useMyTestStoreStore();
+      const num = store.useNumValue();
+      const arrNum = store.useArrValue((v) => v[num], [num]);
+      return (
+        <div>
+          <div>arrNumWithDeps: {arrNum}</div>
+        </div>
+      );
+    };
+
+    const BadSelectorRenderer = () => {
+      const arr0 = useMyTestStoreStore().useArrValue((v) => v[0]);
+      return <div>{arr0}</div>;
+    };
+
     const Buttons = () => {
       const store = useMyTestStoreStore();
       return (
@@ -95,7 +127,10 @@ describe('createAtomStore', () => {
           </button>
           <button
             type="button"
-            onClick={() => store.setArr(['ava', ...store.getArr().slice(1)])}
+            onClick={() => {
+              store.setArr(['ava', ...store.getArr().slice(1)]);
+              store.setNum(0);
+            }}
           >
             modify arr0
           </button>
@@ -111,6 +146,8 @@ describe('createAtomStore', () => {
           <ArrRendererWithShallow />
           <Arr0Renderer />
           <Arr1Renderer />
+          <ArrNumRenderer />
+          <ArrNumRendererWithDeps />
           <Buttons />
         </MyTestStoreProvider>
       );
@@ -121,34 +158,64 @@ describe('createAtomStore', () => {
       expect(arrRendererWithShallowRenderCount).toBe(2);
       expect(arr0RenderCount).toBe(2);
       expect(arr1RenderCount).toBe(2);
+      expect(arrNumRenderCount).toBe(2);
+      expect(arrNumRenderWithDepsCount).toBe(2);
+      expect(getByText('arrNum: alice')).toBeInTheDocument();
+      expect(getByText('arrNumWithDeps: alice')).toBeInTheDocument();
 
       act(() => getByText('increment').click());
       expect(numRenderCount).toBe(3);
       expect(arrRenderCount).toBe(2);
       expect(arrRendererWithShallowRenderCount).toBe(2);
       expect(arr0RenderCount).toBe(2);
       expect(arr1RenderCount).toBe(2);
+      expect(arrNumRenderCount).toBe(5);
+      expect(arrNumRenderWithDepsCount).toBe(5);
+      expect(getByText('arrNum: bob')).toBeInTheDocument();
+      expect(getByText('arrNumWithDeps: bob')).toBeInTheDocument();
 
       act(() => getByText('add one name').click());
       expect(numRenderCount).toBe(3);
       expect(arrRenderCount).toBe(3);
       expect(arrRendererWithShallowRenderCount).toBe(3);
       expect(arr0RenderCount).toBe(2);
       expect(arr1RenderCount).toBe(2);
+      expect(arrNumRenderCount).toBe(5);
+      expect(arrNumRenderWithDepsCount).toBe(5);
+      expect(getByText('arrNum: bob')).toBeInTheDocument();
+      expect(getByText('arrNumWithDeps: bob')).toBeInTheDocument();
 
       act(() => getByText('copy array').click());
       expect(numRenderCount).toBe(3);
       expect(arrRenderCount).toBe(4);
       expect(arrRendererWithShallowRenderCount).toBe(3);
       expect(arr0RenderCount).toBe(2);
       expect(arr1RenderCount).toBe(2);
+      expect(arrNumRenderCount).toBe(5);
+      expect(arrNumRenderWithDepsCount).toBe(5);
+      expect(getByText('arrNum: bob')).toBeInTheDocument();
+      expect(getByText('arrNumWithDeps: bob')).toBeInTheDocument();
 
       act(() => getByText('modify arr0').click());
-      expect(numRenderCount).toBe(3);
+      expect(numRenderCount).toBe(4);
       expect(arrRenderCount).toBe(5);
       expect(arrRendererWithShallowRenderCount).toBe(4);
       expect(arr0RenderCount).toBe(3);
       expect(arr1RenderCount).toBe(2);
+      expect(arrNumRenderCount).toBe(8);
+      expect(arrNumRenderWithDepsCount).toBe(8);
+      expect(getByText('arrNum: ava')).toBeInTheDocument();
+      expect(getByText('arrNumWithDeps: ava')).toBeInTheDocument();
+    });
+
+    it('Throw error if user does not memoize selector', () => {
+      expect(() =>
+        render(
+          <MyTestStoreProvider>
+            <BadSelectorRenderer />
+          </MyTestStoreProvider>
+        )
+      ).toThrow();
     });
   });