split query hooks, add sub-selector (#106)

Co-authored-by: Matt Sutkowski <[email protected]>

Author: phryneas

examples/react/src/features/posts/PostsManager.tsx

@@ -1,4 +1,5 @@
-import React, { useState } from 'react';
+import React, { useCallback, useState } from 'react';
+import { useEffect } from 'react';
 import { useDispatch, useSelector } from 'react-redux';
 import { Route, Switch, useHistory } from 'react-router-dom';
 import {
@@ -7,6 +8,7 @@ import {
   useGetPostsQuery,
   useLoginMutation,
   useGetErrorProneQuery,
+  postApi,
 } from '../../app/services/posts';
 import { selectIsAuthenticated, logout } from '../auth/authSlice';
 import { PostDetail } from './PostDetail';
@@ -71,6 +73,51 @@ const PostList = () => {
   );
 };
 
+const PostFromUseQueryStateSubSelector = () => {
+  const [count, setCount] = useState(0);
+  const id = 5;
+  const idAsString = String(id);
+
+  const post = postApi.endpoints.getPosts.useQueryState(undefined, {
+    subSelector: ({ data }) => data?.find((entry) => entry.id === id),
+  });
+
+  useEffect(() => {
+    setCount((prev) => prev + 1);
+  }, [post]);
+
+  return (
+    <div>
+      <h3>
+        This won't render a post until `id: {idAsString}` exists! <small>(render count: {count})</small>
+      </h3>
+      {post ? <div>{JSON.stringify(post)}</div> : <div>waiting to see id: {idAsString}</div>}
+    </div>
+  );
+};
+
+const PostFromUseQuerySelectorSubSelector = () => {
+  const [count, setCount] = useState(0);
+  const id = 6;
+  const idAsString = String(id);
+  const { refetch, post } = postApi.useGetPostsQuery(undefined, {
+    subSelector: ({ data }) => ({ post: data?.find((entry) => entry.id === id) }),
+  });
+
+  useEffect(() => {
+    setCount((prev) => prev + 1);
+  }, [post]);
+
+  return (
+    <div>
+      <h3>
+        This won't render a post until `id: {idAsString}` exists! <small>(render count: {count})</small>
+      </h3>
+      {post ? <div>{JSON.stringify(post)}</div> : <div>waiting to see id: {idAsString}</div>}
+    </div>
+  );
+};
+
 export const PostsManager = () => {
   const [login] = useLoginMutation();
   const [initRetries, setInitRetries] = useState(false);
@@ -102,6 +149,14 @@ export const PostsManager = () => {
           <Switch>
             <Route path="/posts/:id" component={PostDetail} />
           </Switch>
+
+          <div style={{ marginTop: 0, paddingTop: 20, borderTop: '1px solid #eee' }}>
+            If you look, these components will only rerender when the the selector criteria is met, or when the actual
+            underlying data changes. Try adding a few new posts to see this behavior.
+            <PostFromUseQueryStateSubSelector />
+            <hr />
+            <PostFromUseQuerySelectorSubSelector />
+          </div>
         </div>
       </div>
     </div>

package.json

@@ -106,7 +106,7 @@
     "cross-fetch": "^3.0.6",
     "eslint-plugin-prettier": "^3.1.4",
     "husky": "^4.3.0",
-    "msw": "^0.22.3",
+    "msw": "^0.24.2",
     "node-fetch": "^2.6.1",
     "prettier": "^2.2.0",
     "react": "^16.14.0 || 17.0.0",

src/buildHooks.ts

@@ -1,39 +1,33 @@
-import { AnyAction, ThunkDispatch } from '@reduxjs/toolkit';
+import { AnyAction, createSelector, ThunkDispatch } from '@reduxjs/toolkit';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { useDispatch, useSelector, batch } from 'react-redux';
+import { useDispatch, useSelector, batch, shallowEqual } from 'react-redux';
 import {
   MutationSubState,
   QueryStatus,
   QuerySubState,
   RequestStatusFlags,
   SubscriptionOptions,
   QueryKeys,
+  RootState,
 } from './apiState';
-import {
-  EndpointDefinitions,
-  MutationDefinition,
-  QueryDefinition,
-  QueryArgFrom,
-  ResultTypeFrom,
-} from './endpointDefinitions';
-import { skipSelector } from './buildSelectors';
+import { EndpointDefinitions, MutationDefinition, QueryDefinition, QueryArgFrom } from './endpointDefinitions';
+import { QueryResultSelectorResult, skipSelector } from './buildSelectors';
 import { QueryActionCreatorResult, MutationActionCreatorResult } from './buildActionMaps';
 import { useShallowStableValue } from './utils';
 import { Api, ApiEndpointMutation, ApiEndpointQuery } from './apiTypes';
-import { Id, Override } from './tsHelpers';
+import { Id, NoInfer, Override } from './tsHelpers';
 
-interface QueryHookOptions extends SubscriptionOptions {
-  skip?: boolean;
-  refetchOnMountOrArgChange?: boolean | number;
+interface QueryHooks<Definition extends QueryDefinition<any, any, any, any, any>> {
+  useQuery: UseQuery<Definition>;
+  useQuerySubscription: UseQuerySubscription<Definition>;
+  useQueryState: UseQueryState<Definition>;
 }
 
 declare module './apiTypes' {
   export interface ApiEndpointQuery<
     Definition extends QueryDefinition<any, any, any, any, any>,
     Definitions extends EndpointDefinitions
-  > {
-    useQuery: QueryHook<Definition>;
-  }
+  > extends QueryHooks<Definition> {}
 
   export interface ApiEndpointMutation<
     Definition extends MutationDefinition<any, any, any, any, any>,
@@ -43,12 +37,45 @@ declare module './apiTypes' {
   }
 }
 
-export type QueryHook<D extends QueryDefinition<any, any, any, any>> = (
+export type UseQuery<D extends QueryDefinition<any, any, any, any>> = <R = UseQueryStateDefaultResult<D>>(
   arg: QueryArgFrom<D>,
-  options?: QueryHookOptions
-) => QueryHookResult<D>;
+  options?: UseQuerySubscriptionOptions & UseQueryStateOptions<D, R>
+) => UseQueryStateResult<D, R> & ReturnType<UseQuerySubscription<D>>;
 
-type BaseQueryHookResult<D extends QueryDefinition<any, any, any, any>> = QuerySubState<D> & {
+interface UseQuerySubscriptionOptions extends SubscriptionOptions {
+  skip?: boolean;
+  refetchOnMountOrArgChange?: boolean | number;
+}
+
+export type UseQuerySubscription<D extends QueryDefinition<any, any, any, any>> = (
+  arg: QueryArgFrom<D>,
+  options?: UseQuerySubscriptionOptions
+) => Pick<QueryActionCreatorResult<D>, 'refetch'>;
+
+export type QueryStateSelector<R, D extends QueryDefinition<any, any, any, any>> = (
+  state: QueryResultSelectorResult<D>,
+  lastResult: R | undefined,
+  defaultQueryStateSelector: DefaultQueryStateSelector<D>
+) => R;
+
+export type DefaultQueryStateSelector<D extends QueryDefinition<any, any, any, any>> = (
+  state: QueryResultSelectorResult<D>,
+  lastResult: Pick<UseQueryStateDefaultResult<D>, 'data'>
+) => UseQueryStateDefaultResult<D>;
+
+export type UseQueryState<D extends QueryDefinition<any, any, any, any>> = <R = UseQueryStateDefaultResult<D>>(
+  arg: QueryArgFrom<D>,
+  options?: UseQueryStateOptions<D, R>
+) => UseQueryStateResult<D, R>;
+
+export type UseQueryStateOptions<D extends QueryDefinition<any, any, any, any>, R> = {
+  skip?: boolean;
+  subSelector?: QueryStateSelector<R, D>;
+};
+
+export type UseQueryStateResult<_ extends QueryDefinition<any, any, any, any>, R> = NoInfer<R>;
+
+type UseQueryStateBaseResult<D extends QueryDefinition<any, any, any, any>> = QuerySubState<D> & {
   /**
    * Query has not started yet.
    */
@@ -69,17 +96,17 @@ type BaseQueryHookResult<D extends QueryDefinition<any, any, any, any>> = QueryS
    * Query is currently in "error" state.
    */
   isError: false;
-} & Pick<QueryActionCreatorResult<D>, 'refetch'>;
+};
 
-type QueryHookResult<D extends QueryDefinition<any, any, any, any>> = Id<
-  | Override<Extract<BaseQueryHookResult<D>, { status: QueryStatus.uninitialized }>, { isUninitialized: true }>
+type UseQueryStateDefaultResult<D extends QueryDefinition<any, any, any, any>> = Id<
+  | Override<Extract<UseQueryStateBaseResult<D>, { status: QueryStatus.uninitialized }>, { isUninitialized: true }>
   | Override<
-      BaseQueryHookResult<D>,
+      UseQueryStateBaseResult<D>,
       | { isLoading: true; isFetching: boolean; data: undefined }
       | ({ isSuccess: true; isFetching: boolean; error: undefined } & Required<
-          Pick<BaseQueryHookResult<D>, 'data' | 'fulfilledTimeStamp'>
+          Pick<UseQueryStateBaseResult<D>, 'data' | 'fulfilledTimeStamp'>
         >)
-      | ({ isError: true } & Required<Pick<BaseQueryHookResult<D>, 'error'>>)
+      | ({ isError: true } & Required<Pick<UseQueryStateBaseResult<D>, 'error'>>)
     >
 >;
 
@@ -96,12 +123,26 @@ export type PrefetchOptions =
       ifOlderThan?: false | number;
     };
 
+const defaultQueryStateSelector: DefaultQueryStateSelector<any> = (currentState, lastResult) => {
+  // data is the last known good request result we have tracked - or if none has been tracked yet the last good result for the current args
+  const data = (currentState.isSuccess ? currentState.data : lastResult?.data) ?? currentState.data;
+
+  // isFetching = true any time a request is in flight
+  const isFetching = currentState.isLoading;
+  // isLoading = true only when loading while no data is present yet (initial load with no data in the cache)
+  const isLoading = !data && isFetching;
+  // isSuccess = true when data is present
+  const isSuccess = currentState.isSuccess || (isFetching && !!data);
+
+  return { ...currentState, data, isFetching, isLoading, isSuccess } as UseQueryStateDefaultResult<any>;
+};
+
 export function buildHooks<Definitions extends EndpointDefinitions>({
   api,
 }: {
   api: Api<any, Definitions, any, string>;
 }) {
-  return { buildQueryHook, buildMutationHook, usePrefetch };
+  return { buildQueryHooks, buildMutationHook, usePrefetch };
 
   function usePrefetch<EndpointName extends QueryKeys<Definitions>>(
     endpointName: EndpointName,
@@ -117,24 +158,20 @@ export function buildHooks<Definitions extends EndpointDefinitions>({
     );
   }
 
-  function buildQueryHook(name: string): QueryHook<any> {
-    return (
+  function buildQueryHooks(name: string): QueryHooks<any> {
+    const useQuerySubscription: UseQuerySubscription<any> = (
       arg: any,
       { refetchOnReconnect, refetchOnFocus, refetchOnMountOrArgChange, skip = false, pollingInterval = 0 } = {}
     ) => {
-      const { select, initiate } = api.endpoints[name] as ApiEndpointQuery<
+      const { initiate } = api.endpoints[name] as ApiEndpointQuery<
         QueryDefinition<any, any, any, any, any>,
         Definitions
       >;
       const dispatch = useDispatch<ThunkDispatch<any, any, AnyAction>>();
       const stableArg = useShallowStableValue(arg);
 
-      const lastData = useRef<ResultTypeFrom<Definitions[string]> | undefined>();
       const promiseRef = useRef<QueryActionCreatorResult<any>>();
 
-      const querySelector = useMemo(() => select(skip ? skipSelector : stableArg), [select, skip, stableArg]);
-      const currentState = useSelector(querySelector);
-
       useEffect(() => {
         if (skip) {
           return;
@@ -169,33 +206,55 @@ export function buildHooks<Definitions extends EndpointDefinitions>({
         return () => void promiseRef.current?.unsubscribe();
       }, []);
 
+      return useMemo(
+        () => ({
+          refetch: () => void promiseRef.current?.refetch(),
+        }),
+        []
+      );
+    };
+
+    const useQueryState: UseQueryState<any> = (
+      arg: any,
+      { skip = false, subSelector = defaultQueryStateSelector as QueryStateSelector<any, any> } = {}
+    ) => {
+      const { select } = api.endpoints[name] as ApiEndpointQuery<QueryDefinition<any, any, any, any, any>, Definitions>;
+      const stableArg = useShallowStableValue(arg);
+
+      const lastValue = useRef<any>();
+
+      const querySelector = useMemo(
+        () =>
+          createSelector(
+            [select(skip ? skipSelector : stableArg), (_: any, lastResult: any) => lastResult],
+            (subState, lastResult) => subSelector(subState, lastResult, defaultQueryStateSelector)
+          ),
+        [select, skip, stableArg, subSelector]
+      );
+
+      const currentState = useSelector(
+        (state: RootState<Definitions, any, any>) => querySelector(state, lastValue.current),
+        shallowEqual
+      );
+
       useEffect(() => {
-        if (currentState.status === QueryStatus.fulfilled) {
-          lastData.current = currentState.data;
-        }
+        lastValue.current = currentState;
       }, [currentState]);
 
-      const refetch = useCallback(() => void promiseRef.current?.refetch(), []);
-
-      // data is the last known good request result
-      const data = currentState.status === 'fulfilled' ? currentState.data : lastData.current;
-
-      const isPending = currentState.status === QueryStatus.pending;
-      // isLoading = true only when loading while no data is present yet (initial load)
-      const isLoading: any = !lastData.current && isPending;
-      // isFetching = true any time a request is in flight
-      const isFetching: any = isPending;
-      // isSuccess = true when data is present
-      const isSuccess: any = currentState.status === 'fulfilled' || (isPending && !!data);
-
-      return useMemo(() => ({ ...currentState, data, isFetching, isLoading, isSuccess, refetch }), [
-        currentState,
-        data,
-        isFetching,
-        isLoading,
-        isSuccess,
-        refetch,
-      ]);
+      return currentState;
+    };
+
+    return {
+      useQueryState,
+      useQuerySubscription,
+      useQuery(arg, options) {
+        const querySubscriptionResults = useQuerySubscription(arg, options);
+        const queryStateResults = useQueryState(arg, options);
+        return useMemo(() => ({ ...queryStateResults, ...querySubscriptionResults }), [
+          queryStateResults,
+          querySubscriptionResults,
+        ]);
+      },
     };
   }
 

src/buildSelectors.ts

@@ -43,7 +43,11 @@ declare module './apiTypes' {
 
 type QueryResultSelector<Definition extends QueryDefinition<any, any, any, any>, RootState> = (
   queryArg: QueryArgFrom<Definition> | typeof skipSelector
-) => (state: RootState) => QuerySubState<Definition> & RequestStatusFlags;
+) => (state: RootState) => QueryResultSelectorResult<Definition>;
+
+export type QueryResultSelectorResult<
+  Definition extends QueryDefinition<any, any, any, any>
+> = QuerySubState<Definition> & RequestStatusFlags;
 
 type MutationResultSelector<Definition extends MutationDefinition<any, any, any, any>, RootState> = (
   requestId: string | typeof skipSelector

src/buildSlice.ts

@@ -18,7 +18,7 @@ import type { MutationThunkArg, QueryThunkArg, ThunkResult } from './buildThunks
 import { AssertEntityTypes, calculateProvidedBy, EndpointDefinitions } from './endpointDefinitions';
 import { applyPatches, Patch } from 'immer';
 import { onFocus, onFocusLost, onOffline, onOnline } from './setupListeners';
-import { isDocumentVisible, isOnline } from './utils';
+import { isDocumentVisible, isOnline, copyWithStructuralSharing } from './utils';
 
 function updateQuerySubstateIfExists(
   state: QueryState<any>,
@@ -96,7 +96,7 @@ export function buildSlice({
           updateQuerySubstateIfExists(draft, meta.arg.queryCacheKey, (substate) => {
             if (substate.requestId !== meta.requestId) return;
             substate.status = QueryStatus.fulfilled;
-            substate.data = payload.result;
+            substate.data = copyWithStructuralSharing(substate.data, payload.result);
             substate.error = undefined;
             substate.fulfilledTimeStamp = payload.fulfilledTimeStamp;
           });