chore: Merged 1.0.0 update

@ryfylke-react/rtk-query-loader@1.0.0


- [x] **New feature**: Pass any static data through loader
- [x] **New feature**:  Extend _only_ `transform` without `useQueries` (previously `queries`)
- [x] Change: How `createLoader` receives queries. (`useQueries`)
- [x] Change: How `createLoader` receives deferredQueries. (`useQueries`)
- [x] Change: Default loader output format
```typescript
type NewOutputFormat = {
  queries: Record<string, UseQueryResult>;
  deferredQueries: Record<string, UseQueryResult>;
  payload: T;
}
```
- [x] Change: You are no longer required to `transform` when deferring queries

Author: imp-dance

README.md

@@ -28,17 +28,23 @@ import {
 } from "@ryfylke-react/rtk-query-loader";
 
 const loader = createLoader({
-  queries: () => {
+  useQueries: () => {
     const pokemon = useGetPokemon();
     const currentUser = useGetCurrentUser();
-    return [pokemon, currentUser] as const;
+
+    return {
+      queries: {
+        pokemon,
+        currentUser,
+      },
+    };
   },
   onLoading: () => <div>Loading pokemon...</div>,
 });
 
-const Pokemon = withLoader((props, queries) => {
-  const pokemon = queries[0].data;
-  const currentUser = queries[1].data;
+const Pokemon = withLoader((props, loader) => {
+  const pokemon = loader.queries.pokemon.data;
+  const currentUser = loader.queries.currentUser.data;
 
   return (
     <div>
@@ -89,4 +95,5 @@ What if we could instead "join" these queries into one, and then just return ear
 - [x] Easy to write re-usable loaders that can be abstracted away from the components
 
 ## [Documentation](https://rtk-query-loader.ryfylke.dev)
+
 ## [Quick Guide](https://rtk-query-loader.ryfylke.dev/Quick%20Guide/)

docs/docs/Advanced/under-the-hood.md

@@ -2,6 +2,17 @@
 
 How does `rtk-query-loader` work _under the hood_?
 
+## The underlying principles
+
+1. We have a higher-order component (wrapper)
+2. We aggregate the status of a collection of queries that are run through a hook
+3. We conditionally render the appropriate states
+4. We pass the data to the consumer-component through the use of `React.forwardRef`
+
+### Can't I just build this myself?
+
+Yes you can, the concept itself is quite simple. But making it properly type-safe can be difficult, and this package has been thoroughly tested and thought out. And we do offer some killer [features](../Features/index.md).
+
 ## Virtual DOM
 
 Imagine you have this component, rendered through `withLoader`:
@@ -59,20 +70,3 @@ div
 ## RTKLoader
 
 `RTKLoader` simply receives the loader and component, and handles returning the correct state depending on the query. You can take a look at how this component behaves [in the codebase](https://github.com/ryfylke-react-as/rtk-query-loader/blob/main/src/RTKLoader.tsx).
-
-## Custom `loaderComponent`
-
-You could pass a custom `loaderComponent` to your loaders, if you'd like:
-
-```typescript
-const CustomLoader = (props: CustomLoaderProps) => {
-  // Handle rendering
-};
-
-const loader = createLoader({
-  loaderComponent: CustomLoader,
-  // ...
-});
-```
-
-This allows you to have really fine control over how the rendering of components using `withLoader` should work.

docs/docs/Exports/create-loader.md

@@ -13,14 +13,22 @@ type ConsumerProps = Record<string, any> & {
 
 const loader = createLoader({
   queriesArg: (props: ConsumerProps) => props.userId,
-  queries: (userId) => {
-    return [useGetUser(userId)] as const;
+  useQueries: (userId) => {
+    return {
+      queries: {
+        user: useGetUser(userId),
+      },
+      deferredQueries: {
+        relations: useGetUserRelations(userId),
+      },
+      payload: {
+        // Lets you send any static data to your consumer
+        static: "data",
+      },
+    };
   },
-  deferredQueries: (userId) => {
-    return [useGetUserRelations(userId)] as const;
-  },
-  transform: (queries, deferredQueries) => ({
-    queries: [...queries, ...deferredQueries],
+  transform: (loaderData) => ({
+    ...loaderData,
     foo: "bar",
   }),
   onLoading: (props) => <div>Loading...</div>,
@@ -37,57 +45,6 @@ A `Loader` takes ownership over...
 - Data-transformation
 - Fetch-state rendering
 
-Here is the `createLoader` argument:
-
-````typescript
-type CreateLoaderArgs<
-  P extends unknown, // Props
-  QRU extends readonly UseQueryResult<unknown>[], // List of queries returned in `queries`
-  QRUD extends readonly UseQueryResult<unknown>[], // List of queries returned in `deferredQueries`
-  R extends unknown = MakeDataRequired<QRU>, // Return type
-  A = never // Loader argument
-> = {
-  /** 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;
-  /** 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, QRUD, 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: FetchBaseQueryError | SerializedError,
-    joinedQuery: UseQueryResult<undefined>
-  ) => ReactElement;
-  /** @deprecated Using onFetching might result in loss of internal state. Use `whileFetching` instead, or pass the query to the component */
-  onFetching?: (
-    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>;
-};
-```
-````
+:::caution Using version `0.3.51` or earlier?
+Please refer to the [**migration guide**](../Migrations/v0.x).
+:::

docs/docs/Exports/use-create-query.md

@@ -14,15 +14,24 @@ import {
   useCreateQuery,
 } from "@ryfylke-react/rtk-query-loader";
 
+const getUser = async (userId: string) => {
+  const res = await fetch(`users/${userId}`);
+  const json = await res.json();
+  return json as SomeDataType;
+};
+
 const loader = createLoader({
-  queries: (userId: string) => {
-    const query = useCreateQuery(async () => {
-      const res = await fetch(`users/${userId}`);
-      const json = await res.json();
-      return json as SomeDataType;
-      // dependency array
-    }, [userId]);
-    return [query] as const;
+  useQueries: (userId: string) => {
+    const query = useCreateQuery(
+      async () => await getUser(userId),
+      [userId]
+    );
+
+    return {
+      queries: {
+        query,
+      },
+    };
   },
 });
 ```

docs/docs/Features/custom-loader.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 5
+---
+
+# Custom `loaderComponent`
+
+You could pass a custom `loaderComponent` to your loaders, if you'd like:
+
+```typescript
+const CustomLoader = (props: CustomLoaderProps) => {
+  // Handle rendering
+};
+
+const loader = createLoader({
+  loaderComponent: CustomLoader,
+  // ...
+});
+```
+
+:::tip
+This allows you to have really fine control over how the rendering of components using `withLoader` should work.
+:::

docs/docs/Features/defer-queries.md

@@ -8,21 +8,29 @@ Say you have a query that takes a long time to resolve. You want to put it in th
 
 ## Example
 
-```typescript {3-7}
+```typescript {3-13}
 const loader = createLoader({
-  queries: () => [useImportantQuery()] as const,
-  deferredQueries: () => [useSlowQuery()] as const,
-  transform: (queries, deferred) => ({
-    important: queries[0].data,
-    slow: deferred[0].data,
+  useQueries: () => {
+    const importantQuery = useImportantQuery();
+    const slowQuery = useSlowQuery();
+
+    return {
+      queries: {
+        importantQuery,
+      },
+      deferredQueries: {
+        slowQuery,
+      },
+    };
+  },
+  transform: (loader) => ({
+    important: loader.queries.importantQuery.data, // ImportantQueryResponse
+    slow: loader.deferredQueries.slowQuery.data, // SlowQueryResponse | undefined
   }),
 });
 ```
 
-Deferred queries are not automatically passed to the output of the loader, you have to use the `transform` argument (and it's second argument) to expose the queries for the consumers. The format of how you transform it is not important, but it is the only way to _get_ the deferred query result out of the loader.
-
 Deferred queries
 
 - Do not affect the loading state
-- Are only exposed through `transform`
 - Cause the component to rerender when fulfilled

docs/docs/Features/extending.md

@@ -12,18 +12,37 @@ const parentLoader = createLoader({
 });
 
 const childLoader = parentLoader.extend({
-    queries: () => [...] as const,
-})
+    useQueries: () => ({...}),
+    onError: () => <div>Error</div>,
+}).extend({
+    transform: () => ({...}),
+}).extend({
+    onLoading: () => <div>Overwritten loading...</div>,
+});
 ```
 
-It's worth mentioning that queries and transform are linked in this context, meaning that if you supply a new queries argument in the extended loader, but no transform, then you will not inherit the transform from the original loader.
-
-- Supplying just a new `queries` argument will result in transform being undefined in practise.
-- Supplying just a new `transform` argument will result in the new transform being ignored.
-- Supplying a new `transform` and a new `queries` argument will properly overwrite the existing base properties.
+:::caution
+`.extend` will not merge two separate `useQueries` properties. For example, you cannot _just_ inherit the deferredQueries, you must either inherit all or none of the `useQueries` argument.
+:::
+:::tip Reusable transformers
+You can extend as many times as you'd like. You can use this feature to easily inject reusable snippets, like transformers.
+
+```typescript
+type QueryRecord = Record<string, UseQueryResult<unknown>>;
+
+export const transformData = {
+  transform: (data: {
+    queries: QueryRecord;
+    deferredQueries: QueryRecord;
+    payload: unknown;
+  }) => {
+    // handle transformation in generic way
+  },
+};
+```
 
-All other properties in the loader will overwrite as expected. You can, for example, just supply a new `onLoading`, or `onError`.
+```typescript
+const loader = createLoader({...}).extend(transformData);
+```
 
-:::info
-You may extend _extended_ loaders, to create an inheritance model.
 :::

docs/docs/Features/index.md

@@ -7,8 +7,12 @@ sidebar_position: 5
 RTK Query Loader tries to give you all the flexibility you need to create reusable and extendable loaders.
 
 - Supply multiple queries.
-- Supply queries that are [not from RTK](../Exports/use-create-query.md).
 - Supply queries that [don't affect loading state](defer-queries.md).
 - [Transform](./transforming.md) the queries to your desired output-format.
 - [Extend](./extending.md) existing loaders.
 - Re-use existing loaders
+
+And even if you don't use `RTK Query`...
+
+- Supply queries that are [just promises](../Exports/use-create-query.md).
+- [Use with other data loading libraries](./other-libs.md)

docs/docs/Features/other-libs.md

@@ -0,0 +1,74 @@
+---
+sidebar_position: 4
+---
+
+# Use with other libraries
+
+You can use RTK Query Loader with most other similar query-fetching libraries. This is possible through the use of _resolvers_.
+
+:::note
+Although `rtk-query-loader` was build with `@reduxjs/toolkit` in mind, the underlying principles can be applied to any similar data loading solution. [Read more about how RTK Query Loader works under the hood](../Advanced/under-the-hood.md).
+:::
+
+## Tanstack Query
+
+```typescript
+import {
+  useQuery,
+  UseQueryResult as TanstackUseQueryResult,
+  UseQueryOptions,
+} from "@tanstack/react-query";
+
+const tanstackResolver = <T extends unknown>(
+  query: TanstackUseQueryResult<T>
+): UseQueryResult<T> & {
+  orignal_query: TanstackUseQueryResult<T>;
+} => ({
+  isLoading: query.isLoading,
+  isFetching: query.isFetching,
+  isSuccess: query.isSuccess,
+  isError: query.isError,
+  error: query.error,
+  data: query.data,
+  isUninitialized: !query.isFetchedAfterMount,
+  originalArgs: null,
+  refetch: () => query.refetch(),
+  currentData: query.data,
+  endpointName: undefined,
+  original_query: query,
+});
+
+const useTanstackQuery = <T extends unknown>(
+  args: UseQueryOptions<T>
+) => tanstackResolver(useQuery(args));
+```
+
+This is how you would use it:
+
+```typescript
+import { useTanstackQuery } from "../loader-resolvers";
+
+const loader = createLoader({
+  useQueries: () => {
+    const repoData = useTanstackQuery({
+      queryKey: ["repoData"],
+      queryFn: () =>
+        fetch(
+          "https://api.github.com/repos/ryfylke-react-as/rtk-query-loader"
+        ).then((res) => res.json() as Promise<RepoDataResponse>),
+    });
+
+    return {
+      queries: {
+        repoData,
+      },
+    };
+  },
+});
+```
+
+The output format will obviously be a bit different, but in this example you have access to the original query at the `.original_query` property.
+
+## Other libraries
+
+If you are interested in creating resolvers for other libraries, you can [edit this page](https://github.com/ryfylke-react-as/rtk-query-loader/tree/main/docs/docs/Advanced/other-libs.md) and then [submit a pull request](https://github.com/ryfylke-react-as/rtk-query-loader/compare) on GitHub to share your resolver here, as an npm package, or with the code embedded directly in the docs.