atomWithQuery API

[aulneau]

I wanted to start a discussion around the jotai/query integration and get some conversion around how it should be framed and built. I recently refactored all the state to use jotai + atomWithQuery for this site -> https://stacking.club which is a next.js based app.

I really love the integration with react-query, however I had to jump through some hoops to get a reliable and good experience with SSR.

Below I've included 3 code snippets:

• a wrapped atomWithQuery that allows for
  • having dynamic data based off of params
  • the ability to provide initial data (to avoid suspense on the server, and for SSR purposes)
• How to use atomFamilyWithQuery
• Use in an example next.js page (with Provider)

I'm wondering if we should change the API of atomWithQuery to make this easier for folks, or to have some of this behavior baked in? cc @dai-shi @Aslemammad

atomFamilyWithQuery

import { Atom, atom } from 'jotai';
import { atomWithQuery } from 'jotai/query';
import { atomFamily } from 'jotai/utils';
import { QueryObserverOptions } from 'react-query';

const DEFAULT_QUERY_INTERVAL_TIME = 10000; // 10 seconds
const IS_SSR = typeof document === 'undefined';

const defaultOptions: QueryObserverOptions = {
  refetchInterval: DEFAULT_QUERY_INTERVAL_TIME,
  refetchOnReconnect: true,
  refetchOnWindowFocus: true,
  refetchOnMount: true,
  keepPreviousData: true,
};

// an atomFamily for any initial data
export const initialDataAtom = atomFamily(params => atom(null));

export const atomFamilyWithQuery = <Data, Variables>(
  key: string,
  fetcher: (variables: Variables) => Promise<Data>,
  equalityFn: (a: Data, b: Data) => boolean = Object.is
): ((params: Variables) => Atom<Data>) => {
  const queryAtom = (params, initialData) =>
    atomWithQuery(
      {
        queryKey: [key, params],
        queryFn: async () => fetcher(params),
        initialData,
        ...defaultOptions,
      },
      equalityFn
    );

  return atomFamily(params =>
    atom<Data>(get => {
      const data = get(initialDataAtom(params));
      if (IS_SSR) return data as Data;
      const queryData = get(queryAtom(params, data));
      if (queryData === null) return data as Data;
      return queryData as Data;
    })
  );
};

Usage

import { QUERY_KEYS } from '@common/constants';
import { cycleInfoFetcher } from '@common/api/cycle-info-client';
import { atomFamilyWithQuery } from './query';
import { CycleInfoApi } from '@common/api/server/cycle-info-api';

function equalityFn(a: CycleInfoApi, b: CycleInfoApi) {
  return a.currentHeight === b.currentHeight;
}

const cycleInfoAtom = atomFamilyWithQuery<CycleInfoApi, number>(
  QUERY_KEYS.CYCLE_INFO,
  cycleInfoFetcher,
  equalityFn
);

In a next.js page

const Cycle = ({ cycle, cycleInfo }) => {
  return (
    <Provider initialValues={[[initialDataAtom(cycle), cycleInfo] as const]}>
      <PageContent />
    </Provider>
  );
};

Cycle.getInitialProps = async (context: NextPageContext & { currentCycle: number }) => {
  const { currentCycle } = context;
  const cycle = parseInt(currentCycle as string, 10);
  const cycleInfo = await fetchCycleInfoClient(cycle as number);
  return {
    cycle,
    cycleInfo,
  };
};

export default Cycle;

[dai-shi]

Wow, I would say you are doing it very well. I don't see any issues, tbh.

I have some comments:

• we want jotai to support ssr, but api should not be too specific to ssr. like initialValues in Provider has ssr use case in mind, but it's useful for testing too.
• for nextjs specific things, we are just started the discussion in Discussion: Provide jotai/nextjs utils #340, and non RQ specific things should be addressed there.
• I see adding default value in atomWithQuery could make sense, but not totally sure yet. How would you deal with your use case with pure RQ useQuery?

[Aslemammad]

Great comments, I think the current API is enough and proper, but the default value looks like a good idea.