feat: Custom loader components

refactor: Refactored a lot of code, added comments.
test: Wrote test for custom loader components

Author: imp-dance

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryfylke-react/rtk-query-loader",
-  "version": "0.3.34",
+  "version": "0.3.35",
   "description": "Lets you create loaders that contain multiple RTK queries.",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",

src/RTKLoader.tsx

@@ -1,32 +1,17 @@
 import { SerializedError } from "@reduxjs/toolkit";
-import { FetchBaseQueryError } from "@reduxjs/toolkit/dist/query";
 import * as React from "react";
-import { UseQueryResult } from "./types";
-
-type Props<T> = {
-  query: UseQueryResult<T>;
-  onSuccess: (data: T) => React.ReactElement;
-  onError?: (
-    error: FetchBaseQueryError | SerializedError
-  ) => React.ReactElement;
-  onFetching?: React.ReactElement;
-  whileFetching?: {
-    append?: React.ReactElement;
-    prepend?: React.ReactElement;
-  };
-  loader?: React.ReactElement;
-};
+import { CustomLoaderProps } from "./types";
 
 export function RTKLoader<T>(
-  props: Props<T>
+  props: CustomLoaderProps<T>
 ): React.ReactElement {
   const shouldLoad =
     props.query.isLoading || props.query.isUninitialized;
   const hasError = props.query.isError && props.query.error;
   const isFetching = props.query.isFetching;
 
   if (shouldLoad) {
-    return props.loader ?? <React.Fragment />;
+    return props.onLoading ?? <React.Fragment />;
   }
 
   if (hasError) {

src/createLoader.ts

@@ -1,4 +1,5 @@
 import { aggregateToQuery } from "./aggregateToQuery";
+import { RTKLoader } from "./RTKLoader";
 import * as Types from "./types";
 
 export const createUseLoader = <
@@ -53,6 +54,8 @@ export const createLoader = <
     onFetching: createLoaderArgs.onFetching,
     whileFetching: createLoaderArgs.whileFetching,
     queriesArg: createLoaderArgs.queriesArg,
+    LoaderComponent:
+      createLoaderArgs.loaderComponent ?? RTKLoader,
     extend: function <
       QRUb extends readonly Types.UseQueryResult<unknown>[],
       Pb extends unknown = P,

src/index.ts

@@ -4,9 +4,10 @@ export { RTKLoader } from "./RTKLoader";
 export type {
   Component,
   ComponentWithLoaderData,
-  CreateLoaderType,
   CreateUseLoaderArgs,
+  CustomLoaderProps,
   InferLoaderData,
+  Loader,
   LoaderTransformFunction,
   OptionalGenericArg,
   UseLoader,

src/types.ts

@@ -2,25 +2,40 @@ import { SerializedError } from "@reduxjs/toolkit";
 import { FetchBaseQueryError } from "@reduxjs/toolkit/dist/query";
 import { ReactElement } from "react";
 
+/** Result of a RTK useQuery hook */
 export type UseQueryResult<T> = {
   // Base query state
-  originalArgs?: unknown; // Arguments passed to the query
-  data?: T; // The latest returned result regardless of hook arg, if present
-  currentData?: T; // The latest returned result for the current hook arg, if present
-  error?: unknown; // Error result if present
-  requestId?: string; // A string generated by RTK Query
-  endpointName?: string; // The name of the given endpoint for the query
-  startedTimeStamp?: number; // Timestamp for when the query was initiated
-  fulfilledTimeStamp?: number; // Timestamp for when the query was completed
+  /** Arguments passed to the query */
+  originalArgs?: unknown;
+  /** The latest returned result regardless of hook arg, if present */
+  data?: T;
+  /** The latest returned result for the current hook arg, if present */
+  currentData?: T;
+  /** Error result if present */
+  error?: unknown;
+  /** A string generated by RTK Query */
+  requestId?: string;
+  /** The name of the given endpoint for the query */
+  endpointName?: string;
+  /** Timestamp for when the query was initiated */
+  startedTimeStamp?: number;
+  /** Timestamp for when the query was completed */
+  fulfilledTimeStamp?: number;
 
   // Derived request status booleans
-  isUninitialized: boolean; // Query has not started yet.
-  isLoading: boolean; // Query is currently loading for the first time. No data yet.
-  isFetching: boolean; // Query is currently fetching, but might have data from an earlier request.
-  isSuccess: boolean; // Query has data from a successful load.
-  isError: boolean; // Query is currently in an "error" state.
-
-  refetch: () => void; // A function to force refetch the query
+  /** Query has not started yet */
+  isUninitialized: boolean;
+  /** Query is currently loading for the first time. No data yet. */
+  isLoading: boolean;
+  /** Query is currently fetching, but might have data from an earlier request. */
+  isFetching: boolean;
+  /** Query has data from a successful load */
+  isSuccess: boolean;
+  /** Query is currently in an "error" state */
+  isError: boolean;
+
+  /** A function to force refetch the query */
+  refetch: () => void;
 };
 
 export type MakeDataRequired<
@@ -30,39 +45,45 @@ export type MakeDataRequired<
   [K in keyof T]: T[K] & { data: NonNullable<T[K]["data"]> };
 };
 
+/** Use: `(...args: OptionalGenericArg<T>) => void;`
+ * Allows either `T` or `none` for the parameter
+ */
+export type OptionalGenericArg<T> = T extends never ? [] : [T];
+
 export type LoaderTransformFunction<
   QRU extends readonly UseQueryResult<unknown>[],
   R extends unknown
 > = (queries: MakeDataRequired<QRU>) => R;
 
-export type OptionalGenericArg<T> = T extends never ? [] : [T];
-
 export type CreateUseLoaderArgs<
   QRU extends readonly UseQueryResult<unknown>[],
   R extends unknown,
   A = never
 > = {
+  /** Should return a list of RTK useQuery results.
+   * Example:
+   * ```typescript
+   * (args: Args) => [
+   *    useGetPokemonQuery(args.pokemonId),
+   *    useGetSomethingElse(args.someArg)
+   * ] as const
+   * ```
+   */
   queries: (...args: OptionalGenericArg<A>) => QRU;
+  /** Transforms the output of the queries */
   transform?: LoaderTransformFunction<QRU, R>;
 };
 
 export type UseLoader<A, R> = (
   ...args: OptionalGenericArg<A>
 ) => UseQueryResult<R>;
 
-export type CreateLoaderType = <
-  QRU extends readonly UseQueryResult<unknown>[],
-  R extends unknown = MakeDataRequired<QRU>,
-  A = never
->(
-  createLoaderArgs: CreateUseLoaderArgs<QRU, R, A>
-) => UseLoader<A, R>;
-
 export type ComponentWithLoaderData<
   P extends Record<string, any>,
   R extends unknown
 > = (props: P, loaderData: R) => ReactElement;
 
+/** Use: `InferLoaderData<typeof loader>`. Returns the return-value of the given loader's aggregated query. */
 export type InferLoaderData<T> = T extends Loader<
   any,
   infer X,
@@ -79,28 +100,49 @@ export type Component<P extends Record<string, any>> = (
   props: P
 ) => ReactElement;
 
-export type WithLoaderArgs<
-  P extends unknown,
-  R extends unknown,
-  A = never
-> = Loader<P, R, A>;
-
 export type WhileFetchingArgs<
   P extends unknown,
   R extends unknown
 > = {
+  /** Will be prepended before the component while the query is fetching */
   prepend?: (props: P, data?: R) => ReactElement;
+  /** Will be appended after the component while the query is fetching */
   append?: (props: P, data?: R) => ReactElement;
 };
 
+export type CustomLoaderProps<T = unknown> = {
+  /** What the loader requests be rendered while fetching data */
+  onFetching?: React.ReactElement;
+  /** What the loader requests be rendered while fetching data */
+  whileFetching?: {
+    /** Should be appended to the success result while fetching */
+    append?: React.ReactElement;
+    /** Should be prepended to the success result while fetching */
+    prepend?: React.ReactElement;
+  };
+  /** What the loader requests be rendered when data is available */
+  onSuccess: (data: T) => React.ReactElement;
+  /** What the loader requests be rendered when the query fails */
+  onError?: (
+    error: SerializedError | FetchBaseQueryError
+  ) => JSX.Element;
+  /** What the loader requests be rendered while loading data */
+  onLoading?: React.ReactElement;
+  /** The joined query for the loader */
+  query: UseQueryResult<T>;
+};
+
 export type CreateLoaderArgs<
   P extends unknown,
   QRU extends readonly UseQueryResult<unknown>[],
   R extends unknown = MakeDataRequired<QRU>,
   A = never
 > = Partial<CreateUseLoaderArgs<QRU, 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) */
   onLoading?: (props: P) => ReactElement;
+  /** Determines what to render when query fails. */
   onError?: (
     props: P,
     error: FetchBaseQueryError | SerializedError,
@@ -111,17 +153,24 @@ export type CreateLoaderArgs<
     props: P,
     renderBody: () => ReactElement
   ) => ReactElement;
+  /** Determines what to render besides success-result while query is fetching. */
   whileFetching?: WhileFetchingArgs<P, R>;
+  /** The component to use to switch between rendering the different query states. */
+  loaderComponent?: Component<CustomLoaderProps>;
 };
 
 export type Loader<
   P extends unknown,
   R extends unknown,
   A = never
 > = {
+  /** A hook that runs all queries and returns aggregated result */
   useLoader: UseLoader<A, R>;
+  /** 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) */
   onLoading?: (props: P) => ReactElement;
+  /** Determines what to render when query fails. */
   onError?: (
     props: P,
     error: SerializedError | FetchBaseQueryError,
@@ -132,7 +181,9 @@ export type Loader<
     props: P,
     renderBody: () => ReactElement
   ) => ReactElement;
+  /** Determines what to render besides success-result while query is fetching. */
   whileFetching?: WhileFetchingArgs<P, R>;
+  /** Returns a new `Loader` extended from this `Loader`, with given overrides. */
   extend: <
     QRUb extends readonly UseQueryResult<unknown>[],
     Pb extends unknown = P,
@@ -143,4 +194,14 @@ export type Loader<
   >(
     newLoader: Partial<CreateLoaderArgs<Pb, QRUb, Rb, Ab>>
   ) => Loader<Pb, Rb, Ab>;
+  /** The component to use to switch between rendering the different query states. */
+  LoaderComponent: Component<CustomLoaderProps>;
 };
+
+/** Legacy/unused, for backwards compatibility */
+
+export type WithLoaderArgs<
+  P extends unknown,
+  R extends unknown,
+  A = never
+> = Loader<P, R, A>;

src/withLoader.tsx

@@ -1,7 +1,6 @@
 import { SerializedError } from "@reduxjs/toolkit";
 import { FetchBaseQueryError } from "@reduxjs/toolkit/dist/query";
 import React from "react";
-import { RTKLoader } from "./RTKLoader";
 import * as Types from "./types";
 
 export const withLoader = <
@@ -10,15 +9,15 @@ export const withLoader = <
   A = never
 >(
   Component: Types.ComponentWithLoaderData<P, R>,
-  args: Types.WithLoaderArgs<P, R, A>
+  loader: Types.Loader<P, R, A>
 ): Types.Component<P> => {
   let CachedComponent: Types.ComponentWithLoaderData<P, R>;
-  const LoaderComponent = (props: P) => {
+  const LoadedComponent = (props: P) => {
     const useLoaderArgs = [];
-    if (args.queriesArg) {
-      useLoaderArgs.push(args.queriesArg(props));
+    if (loader.queriesArg) {
+      useLoaderArgs.push(loader.queriesArg(props));
     }
-    const query = args.useLoader(
+    const query = loader.useLoader(
       ...(useLoaderArgs as Types.OptionalGenericArg<A>)
     );
     if (!CachedComponent) {
@@ -27,12 +26,12 @@ export const withLoader = <
       ) as unknown as Types.ComponentWithLoaderData<P, R>;
     }
 
-    const onLoading = args.onLoading?.(props);
+    const onLoading = loader.onLoading?.(props);
 
-    const onError = args.onError
+    const onError = loader.onError
       ? (error: SerializedError | FetchBaseQueryError) => {
-          if (!args.onError) return <React.Fragment />;
-          return args.onError(
+          if (!loader.onError) return <React.Fragment />;
+          return loader.onError(
             props,
             error,
             query as Types.UseQueryResult<undefined>
@@ -44,36 +43,40 @@ export const withLoader = <
       <CachedComponent {...props} ref={data} />
     );
 
-    const whileFetching = args.whileFetching
+    const whileFetching = loader.whileFetching
       ? {
-          prepend: args.whileFetching.prepend?.(
+          prepend: loader.whileFetching.prepend?.(
             props,
             query?.data
           ),
-          append: args.whileFetching.append?.(
+          append: loader.whileFetching.append?.(
             props,
             query?.data
           ),
         }
       : undefined;
 
-    const onFetching = args?.onFetching?.(
+    const onFetching = loader?.onFetching?.(
       props,
       query.data
         ? () => onSuccess(query.data as R)
         : () => <React.Fragment />
     );
 
+    const { LoaderComponent } = loader;
+
     return (
-      <RTKLoader
-        query={query}
-        onSuccess={onSuccess}
-        onError={onError}
-        loader={onLoading}
+      <LoaderComponent
         onFetching={onFetching}
         whileFetching={whileFetching}
+        onSuccess={
+          onSuccess as (data: unknown) => React.ReactElement
+        }
+        onError={onError}
+        onLoading={onLoading}
+        query={query}
       />
     );
   };
-  return LoaderComponent;
+  return LoadedComponent;
 };