Experiment with selector stability idea.

Author: ben.durrant

src/components/Context.ts

@@ -1,6 +1,7 @@
 import { createContext } from 'react'
 import type { Action, AnyAction, Store } from 'redux'
 import type { Subscription } from '../utils/Subscription'
+import { StabilityCheck } from '../hooks/useSelector'
 
 export interface ReactReduxContextValue<
   SS = any,
@@ -9,6 +10,7 @@ export interface ReactReduxContextValue<
   store: Store<SS, A>
   subscription: Subscription
   getServerState?: () => SS
+  stabilityCheck: StabilityCheck
 }
 
 export const ReactReduxContext =

src/components/Provider.tsx

@@ -3,6 +3,7 @@ import { ReactReduxContext, ReactReduxContextValue } from './Context'
 import { createSubscription } from '../utils/Subscription'
 import { useIsomorphicLayoutEffect } from '../utils/useIsomorphicLayoutEffect'
 import { Action, AnyAction, Store } from 'redux'
+import { StabilityCheck } from '../hooks/useSelector'
 
 export interface ProviderProps<A extends Action = AnyAction, S = unknown> {
   /**
@@ -21,6 +22,8 @@ export interface ProviderProps<A extends Action = AnyAction, S = unknown> {
    * Initial value doesn't matter, as it is overwritten with the internal state of Provider.
    */
   context?: Context<ReactReduxContextValue<S, A>>
+
+  stabilityCheck?: StabilityCheck
   children: ReactNode
 }
 
@@ -29,15 +32,17 @@ function Provider<A extends Action = AnyAction, S = unknown>({
   context,
   children,
   serverState,
+  stabilityCheck = 'once',
 }: ProviderProps<A, S>) {
   const contextValue = useMemo(() => {
     const subscription = createSubscription(store)
     return {
       store,
       subscription,
       getServerState: serverState ? () => serverState : undefined,
+      stabilityCheck,
     }
-  }, [store, serverState])
+  }, [store, serverState, stabilityCheck])
 
   const previousState = useMemo(() => store.getState(), [store])
 

src/hooks/useSelector.ts

@@ -1,4 +1,4 @@
-import { useDebugValue } from 'react'
+import { useCallback, useDebugValue, useRef } from 'react'
 
 import {
   createReduxContextHook,
@@ -9,6 +9,24 @@ import type { EqualityFn, NoInfer } from '../types'
 import type { uSESWS } from '../utils/useSyncExternalStore'
 import { notInitialized } from '../utils/useSyncExternalStore'
 
+export type StabilityCheck = 'never' | 'once' | 'always'
+
+export interface UseSelectorOptions<Selected = unknown> {
+  equalityFn?: EqualityFn<Selected>
+  stabilityCheck?: StabilityCheck
+}
+
+interface UseSelector {
+  <TState = unknown, Selected = unknown>(
+    selector: (state: TState) => Selected,
+    equalityFn?: EqualityFn<Selected>
+  ): Selected
+  <TState = unknown, Selected = unknown>(
+    selector: (state: TState) => Selected,
+    options?: UseSelectorOptions<Selected>
+  ): Selected
+}
+
 let useSyncExternalStoreWithSelector = notInitialized as uSESWS
 export const initializeUseSelector = (fn: uSESWS) => {
   useSyncExternalStoreWithSelector = fn
@@ -22,21 +40,22 @@ const refEquality: EqualityFn<any> = (a, b) => a === b
  * @param {React.Context} [context=ReactReduxContext] Context passed to your `<Provider>`.
  * @returns {Function} A `useSelector` hook bound to the specified context.
  */
-export function createSelectorHook(
-  context = ReactReduxContext
-): <TState = unknown, Selected = unknown>(
-  selector: (state: TState) => Selected,
-  equalityFn?: EqualityFn<Selected>
-) => Selected {
+export function createSelectorHook(context = ReactReduxContext): UseSelector {
   const useReduxContext =
     context === ReactReduxContext
       ? useDefaultReduxContext
       : createReduxContextHook(context)
 
   return function useSelector<TState, Selected extends unknown>(
     selector: (state: TState) => Selected,
-    equalityFn: EqualityFn<NoInfer<Selected>> = refEquality
+    equalityFnOrOptions:
+      | EqualityFn<NoInfer<Selected>>
+      | UseSelectorOptions<NoInfer<Selected>> = {}
   ): Selected {
+    const { equalityFn = refEquality, stabilityCheck = undefined } =
+      typeof equalityFnOrOptions === 'function'
+        ? { equalityFn: equalityFnOrOptions }
+        : equalityFnOrOptions
     if (process.env.NODE_ENV !== 'production') {
       if (!selector) {
         throw new Error(`You must pass a selector to useSelector`)
@@ -51,13 +70,56 @@ export function createSelectorHook(
       }
     }
 
-    const { store, subscription, getServerState } = useReduxContext()!
+    const {
+      store,
+      subscription,
+      getServerState,
+      stabilityCheck: globalStabilityCheck,
+    } = useReduxContext()!
+
+    const firstRun = useRef(true)
+
+    const wrappedSelector = useCallback<typeof selector>(
+      {
+        [selector.name](state: TState) {
+          const selected = selector(state)
+          const finalStabilityCheck =
+            // are we safe to use ?? here?
+            typeof stabilityCheck === 'undefined'
+              ? globalStabilityCheck
+              : stabilityCheck
+          if (
+            process.env.NODE_ENV !== 'production' &&
+            (finalStabilityCheck === 'always' ||
+              (finalStabilityCheck === 'once' && firstRun.current))
+          ) {
+            const toCompare = selector(state)
+            if (!equalityFn(selected, toCompare)) {
+              console.warn(
+                'Selector ' +
+                  (selector.name || 'unknown') +
+                  ' returned a different result when called with the same parameters. This can lead to unnecessary rerenders.' +
+                  '\n Selectors that return a new reference (such as an object or an array) should be memoized: https://redux.js.org/usage/deriving-data-selectors#optimizing-selectors-with-memoization',
+                {
+                  state,
+                  selected,
+                  selected2: toCompare,
+                }
+              )
+            }
+            firstRun.current = false
+          }
+          return selected
+        },
+      }[selector.name],
+      [selector, globalStabilityCheck, stabilityCheck]
+    )
 
     const selectedState = useSyncExternalStoreWithSelector(
       subscription.addNestedSub,
       store.getState,
       getServerState || store.getState,
-      selector,
+      wrappedSelector,
       equalityFn
     )
 

src/types.ts

@@ -11,6 +11,8 @@ import type { NonReactStatics } from 'hoist-non-react-statics'
 
 import type { ConnectProps } from './components/connect'
 
+import { UseSelectorOptions } from './hooks/useSelector'
+
 export type FixTypeLater = any
 
 export type EqualityFn<T> = (a: T, b: T) => boolean
@@ -167,6 +169,10 @@ export interface TypedUseSelectorHook<TState> {
     selector: (state: TState) => TSelected,
     equalityFn?: EqualityFn<NoInfer<TSelected>>
   ): TSelected
+  <Selected = unknown>(
+    selector: (state: TState) => Selected,
+    options?: UseSelectorOptions<Selected>
+  ): Selected
 }
 
 export type NoInfer<T> = [T][T extends any ? 0 : never]

test/typetests/hooks.tsx

@@ -168,6 +168,10 @@ function testUseSelector() {
   })
 
   const correctlyInferred: State = useSelector(selector, shallowEqual)
+  const correctlyInferred2: State = useSelector(selector, {
+    equalityFn: shallowEqual,
+    stabilityCheck: 'never',
+  })
   // @ts-expect-error
   const inferredTypeIsNotString: string = useSelector(selector, shallowEqual)