feat: deferred queries in loader

README.md

@@ -199,6 +199,35 @@ const Component = () => {
 };
 ```
 
+## Deferring queries
+
+You can defer queries by using the `deferredQueries` argument in `createLoader` (or `createUseLoader`). These queries are passed as the second argument to `transform` which has to be used to access the deferred queries in your loaded component.
+
+Example usage:
+
+```tsx
+const loader = createLoader({
+  queries: () => [useImportantQuery()] as const,
+  deferredQueries: () => [useSlowButNotImportantQuery()] as const,
+  transform: (queries, deferredQueries) => ({
+    important: queries[0].data,
+    not_important: deferredQueries[0].data,
+  }),
+});
+
+const Component = withLoader((props, loaderData) => {
+  const { important, not_important } = loaderData;
+  // not_important could be undefined
+
+  return (
+    <div>
+      {important.person.name}
+      {not_important ? "it has resolved : "some fallback"}
+    </div>
+  )
+}, loader);
+```
+
 ## InferLoaderData
 
 Infers the type of the data the loader returns. Use:

deploy.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env zx
+try {
+  await Promise.all([
+    $`yarn build`,
+    $`npm version patch --force`,
+  ]);
+  const version = require("./package.json").version;
+  await Promise.all([
+    $`git commit --allow-empty -m "version: ${version}"`,
+    $`git push`,
+    $`npm publish --access public`,
+    $`echo "======================"`,
+    $`echo "Deployed! 🚀 (${version})"`,
+    $`echo "======================"`,
+  ]);
+} catch (err) {
+  await Promise.all([
+    $`echo "======================"`,
+    $`echo "Deploy failed! 😭"`,
+    $`echo "======================"`,
+    $`echo "${err}"`,
+  ]);
+}

src/createLoader.ts

@@ -4,19 +4,23 @@ import * as Types from "./types";
 
 export const createUseLoader = <
   QRU extends readonly Types.UseQueryResult<unknown>[],
+  QRUD extends readonly Types.UseQueryResult<unknown>[],
   R extends unknown = Types.MakeDataRequired<QRU>,
   A = never
 >(
-  createUseLoaderArgs: Types.CreateUseLoaderArgs<QRU, R, A>
+  createUseLoaderArgs: Types.CreateUseLoaderArgs<QRU, QRUD, R, A>
 ): Types.UseLoader<A, R> => {
   const useLoader = (...args: Types.OptionalGenericArg<A>) => {
     const createdQueries = createUseLoaderArgs.queries(...args);
+    const deferredQueries =
+      createUseLoaderArgs.deferredQueries?.(...args) ?? [];
     const aggregatedQuery = aggregateToQuery(createdQueries);
 
     if (aggregatedQuery.isSuccess) {
       const data = createUseLoaderArgs.transform
         ? createUseLoaderArgs.transform(
-            createdQueries as unknown as Types.MakeDataRequired<QRU>
+            createdQueries as unknown as Types.MakeDataRequired<QRU>,
+            deferredQueries as QRUD
           )
         : createdQueries;
 
@@ -36,15 +40,17 @@ export const createUseLoader = <
 export const createLoader = <
   P extends unknown,
   QRU extends readonly Types.UseQueryResult<unknown>[] = [],
+  QRUD extends readonly Types.UseQueryResult<unknown>[] = [],
   R extends unknown = Types.MakeDataRequired<QRU>,
   A = never
 >(
-  createLoaderArgs: Types.CreateLoaderArgs<P, QRU, R, A>
+  createLoaderArgs: Types.CreateLoaderArgs<P, QRU, QRUD, R, A>
 ): Types.Loader<P, R, QRU, A> => {
   const useLoader = createUseLoader({
     queries:
       createLoaderArgs.queries ?? (() => [] as unknown as QRU),
     transform: createLoaderArgs.transform,
+    deferredQueries: createLoaderArgs.deferredQueries,
   });
 
   const loader: Types.Loader<P, R, QRU, A> = {
@@ -58,6 +64,7 @@ export const createLoader = <
       createLoaderArgs.loaderComponent ?? RTKLoader,
     extend: function <
       QRUb extends readonly Types.UseQueryResult<unknown>[],
+      QRUDb extends readonly Types.UseQueryResult<unknown>[],
       Pb extends unknown = P,
       Rb = QRUb extends unknown
         ? R
@@ -67,7 +74,9 @@ export const createLoader = <
       queries,
       transform,
       ...loaderArgs
-    }: Partial<Types.CreateLoaderArgs<Pb, QRUb, Rb, Ab>>) {
+    }: Partial<
+      Types.CreateLoaderArgs<Pb, QRUb, QRUDb, Rb, Ab>
+    >) {
       const extendedLoader = {
         ...(this as unknown as Types.Loader<Pb, Rb, QRUb, Ab>),
         ...loaderArgs,

src/types.ts

@@ -52,11 +52,13 @@ export type OptionalGenericArg<T> = T extends never ? [] : [T];
 
 export type LoaderTransformFunction<
   QRU extends readonly UseQueryResult<unknown>[],
+  QRUD extends readonly UseQueryResult<unknown>[],
   R extends unknown
-> = (queries: MakeDataRequired<QRU>) => R;
+> = (queries: MakeDataRequired<QRU>, deferredQueries: QRUD) => R;
 
 export type CreateUseLoaderArgs<
   QRU extends readonly UseQueryResult<unknown>[],
+  QRUD extends readonly UseQueryResult<unknown>[],
   R extends unknown,
   A = never
 > = {
@@ -70,8 +72,18 @@ export type CreateUseLoaderArgs<
    * ```
    */
   queries: (...args: OptionalGenericArg<A>) => QRU;
+  /** Should return a list of RTK useQuery results.
+   * Example:
+   * ```typescript
+   * (args: Args) => [
+   *    useGetPokemonQuery(args.pokemonId),
+   *    useGetSomethingElse(args.someArg)
+   * ] as const
+   * ```
+   */
+  deferredQueries?: (...args: OptionalGenericArg<A>) => QRUD;
   /** Transforms the output of the queries */
-  transform?: LoaderTransformFunction<QRU, R>;
+  transform?: LoaderTransformFunction<QRU, QRUD, R>;
 };
 
 export type UseLoader<A, R> = (
@@ -136,9 +148,10 @@ export type CustomLoaderProps<T = unknown> = {
 export type CreateLoaderArgs<
   P extends unknown,
   QRU extends readonly UseQueryResult<unknown>[],
+  QRUD extends readonly UseQueryResult<unknown>[],
   R extends unknown = MakeDataRequired<QRU>,
   A = never
-> = Partial<CreateUseLoaderArgs<QRU, R, A>> & {
+> = Partial<CreateUseLoaderArgs<QRU, QRUD, R, A>> & {
   /** Generates an argument for the `queries` based on component props */
   queriesArg?: (props: P) => A;
   /** Determines what to render while loading (with no data to fallback on) */
@@ -188,6 +201,7 @@ export type Loader<
   /** Returns a new `Loader` extended from this `Loader`, with given overrides. */
   extend: <
     QRUb extends readonly UseQueryResult<unknown>[] = QRU,
+    QRUDb extends readonly UseQueryResult<unknown>[] = [],
     Pb extends unknown = P,
     Rb extends unknown = QRUb extends QRU
       ? R extends never
@@ -196,7 +210,7 @@ export type Loader<
       : MakeDataRequired<QRUb>,
     Ab = A
   >(
-    newLoader: Partial<CreateLoaderArgs<Pb, QRUb, Rb, Ab>>
+    newLoader: Partial<CreateLoaderArgs<Pb, QRUb, QRUDb, Rb, Ab>>
   ) => Loader<Pb, Rb, QRUb extends never ? QRU : QRUb, Ab>;
   /** The component to use to switch between rendering the different query states. */
   LoaderComponent: Component<CustomLoaderProps>;

testing-app/src/mocks.ts

@@ -23,8 +23,12 @@ export const handlers = [
     if (req.params.name === "error") {
       return res(c.delay(RESPONSE_DELAY), c.status(500));
     }
+    const delay =
+      req.params.name === "delay"
+        ? RESPONSE_DELAY + 100
+        : RESPONSE_DELAY;
     return res(
-      c.delay(RESPONSE_DELAY),
+      c.delay(delay),
       c.status(200),
       c.json({
         name: req.params.name,

testing-app/src/tests.test.tsx

@@ -152,6 +152,44 @@ describe("withLoader", () => {
     );
   });
 
+  test("Can defer some queries", async () => {
+    const Component = withLoader(
+      (props, { charizard, delay }) => {
+        return (
+          <>
+            <div>{charizard.name}</div>
+            <div>
+              {delay ? "loaded-deferred" : "loading-deferred"}
+            </div>
+          </>
+        );
+      },
+      createLoader({
+        queries: () =>
+          [useGetPokemonByNameQuery("charizard")] as const,
+        deferredQueries: () => {
+          const delayQ = useGetPokemonByNameQuery("delay");
+          return [delayQ] as const;
+        },
+        transform: (queries, deferred) => ({
+          charizard: queries[0].data,
+          delay: deferred[0].data,
+        }),
+        onLoading: () => <div>Loading</div>,
+        onError: () => <div>Error</div>,
+      })
+    );
+    render(<Component />);
+    expect(screen.getByText("Loading")).toBeVisible();
+    await waitFor(() =>
+      expect(screen.getByText("charizard")).toBeVisible()
+    );
+    expect(screen.getByText("loading-deferred")).toBeVisible();
+    await waitFor(() =>
+      expect(screen.getByText("loaded-deferred")).toBeVisible()
+    );
+  });
+
   describe(".extend()", () => {
     test("Can extend onLoading", async () => {
       render(<ExtendedLoaderComponent />);