@openapi-qraft/react 2.3.2 → 2.4.1

package/README.md

@@ -35,103 +35,208 @@ npm install @tanstack/react-query
 
 ## Getting Started
 
-To get started with `@openapi-qraft/react`, you'll need to set up your client by passing in your API services and a set
-of
-callbacks to handle various React Query functionalities.
+To get started with OpenAPI Qraft, you need to generate types and service definitions from your OpenAPI Document.
+These are used to create type-safe hooks and interact with your API.
 
 ### 1. Generate OpenAPI Types & Services
 
-Before utilizing `@openapi-qraft/react` to make typed requests, you need to define your API services by generating types
-and schemas from your OpenAPI Document.
-
-To generate both TypeScript definitions and services using `openapi-qraft`, run the following command in the root directory of your project:
+Run the following command in the root directory of your project using your package manager:
 
 ```bash
-npx @openapi-qraft/cli --plugin tanstack-query-react --plugin openapi-typescript https://api.dev.monite.com/openapi.json?version=2023-09-01 --output-dir src/api
+npx @openapi-qraft/cli --plugin tanstack-query-react --plugin openapi-typescript \
+  --output-dir src/api https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml
 ```
 
-By completing this step, you will generate `src/api/schema.d.ts`, which serves as a TypeScript representation of the specified OpenAPI,
-along with a set of services in `src/api/services/`.
+> 💡 For stable project maintenance, it's recommended to install the CLI generator as a dev dependency.
+> Read more about installation in the [documentation](https://openapi-qraft.github.io/openapi-qraft/docs/getting-started/installation).
 
-### 2. Create API Client
+### 2. Use the generated services in your React application
 
-Now, create the API Client to utilize typed React Hooks for your API endpoints.
+Below are examples demonstrating how to use the generated services in your React application with
+`useQuery`, `useMutation`, and `useInfiniteQuery` hooks from [TanStack Query](https://tanstack.com/query/latest).
 
-```ts
-// where `./api` is the '--output-dir' path to the services you generated
-import { createAPIClient } from './api';
+#### Example with `useQuery()`
 
-const qraft = createAPIClient();
-```
+```tsx title="src/App.tsx"
+import { requestFn } from '@openapi-qraft/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { createAPIClient } from './api'; // generated by OpenAPI Qraft
+
+const queryClient = new QueryClient();
+
+// Use `createAPIClient(...)` to initialize the API client as needed.
+// It's a lightweight 🪶 shortcut for working with TanStack Query 🌴
+const api = createAPIClient({
+  requestFn,
+  queryClient,
+  baseUrl: 'https://petstore3.swagger.io/api/v3',
+});
 
-This setup provides you with a powerful, type-safe way to interact with your backend APIs using React Query.
-The `createAPIClient` function generates a client that allows you to make API calls with type-checked
-parameters, ensuring that your application remains robust and error-free.
+function ExamplePetDetails({ petId }: { petId: number }) {
+  /**
+   * Executes the request to the API on mount:
+   * ###
+   * GET /pet/123456
+   **/
+  const {
+    data: pet,
+    isPending,
+    error,
+  } = api.pet.getPetById.useQuery({
+    path: { petId },
+  });
+
+  if (isPending) {
+    return <div>Loading...</div>;
+  }
 
-### 3. Provide Request Client
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
 
-Finally, provide the request client to the `QraftContext` to enable the generated hooks to make API requests.
+  return <div>Pet Name: {pet?.name}</div>;
+}
+
+export default function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ExamplePetDetails petId={123456} />
+    </QueryClientProvider>
+  );
+}
+```
 
-Every request will be handled by `request` function, which can be customized to fit your project's needs.
+#### Example with `useMutation()`
 
-```tsx
-import { QraftContext, requestFn } from '@openapi-qraft/react';
+```tsx title="src/App.tsx"
+import { requestFn } from '@openapi-qraft/react';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { useMemo } from 'react';
-// where `./api` is the '--output-dir' path to the services you generated with `@openapi-qraft/cli`
-import { createAPIClient } from './api';
+import { createAPIClient } from './api'; // generated by OpenAPI Qraft
+
+const queryClient = new QueryClient();
 
-// create a client anywhere
-const qraft = createAPIClient();
+const api = createAPIClient({
+  requestFn,
+  queryClient,
+  baseUrl: 'https://petstore3.swagger.io/api/v3',
+});
 
-function Providers({ children }: { children: React.ReactNode }) {
-  const queryClient = useMemo(() => new QueryClient(), []);
+function EntityForm({ entityId }: { entityId: string }) {
+  const mutation = api.entities.postEntitiesIdDocuments.useMutation({
+    // ☝️ useMutation() can be used with `undefined` parameters
+    path: {
+      entity_id: entityId,
+    },
+    header: {
+      'x-monite-version': '2023-09-01',
+    },
+  });
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        const formData = new FormData(event.currentTarget);
+        /**
+         * Executes the request`:
+         * ###
+         * POST /entities/3e3e-3e3e-3e3e/documents
+         * x-monite-version: 2023-09-01
+         *
+         * {"company_tax_id_verification": ["verification-id"]}
+         **/
+        mutation.mutate({
+          company_tax_id_verification: [
+            String(formData.get('company_tax_id_verification')),
+          ],
+        });
+      }}
+    >
+      <input name="company_tax_id_verification" />
+      <button>Submit</button>
+    </form>
+  );
+}
 
+export default function App() {
   return (
     <QueryClientProvider client={queryClient}>
-      <QraftContext.Provider
-        value={{
-          baseUrl: 'https://api.sandbox.monite.com/v1', // base URL for all requests
-          requestFn, // `requestFn(...)` will be invoked for every request
-        }}
-      >
-        {children}
-      </QraftContext.Provider>
+      <EntityForm entityId="3e3e-3e3e-3e3e" />
     </QueryClientProvider>
   );
 }
+```
 
-function Example() {
-  const { isPending, error, data } =
-    qraft.approvalPolicies.getApprovalPoliciesId.useQuery({
-      header: {
-        'x-monite-version': '2023-09-01',
-        'x-monite-entity-id': '3e3e-3e3e-3e3e',
-      },
-      path: {
-        approval_policy_id: '1',
-      },
-    });
+#### Example with `useInfiniteQuery()`
+
+```tsx title="src/PostList.tsx"
+import { requestFn } from '@openapi-qraft/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { createAPIClient } from './api'; // generated by OpenAPI Qraft
+
+const queryClient = new QueryClient();
 
-  if (isPending) return 'Loading...';
+const api = createAPIClient({
+  requestFn,
+  queryClient,
+  baseUrl: 'https://petstore3.swagger.io/api/v3',
+});
 
-  if (error) return 'An error has occurred: ' + error.message;
+/**
+ * Executes the initial request:
+ * ###
+ * GET /posts?limit=10&page=1
+ **/
+function PostList() {
+  const infiniteQuery = api.posts.getPosts.useInfiniteQuery(
+    { query: { limit: 10 } },
+    {
+      getNextPageParam: (lastPage, allPages, lastPageParams) => {
+        if (lastPage.length < 10) return; // if less than 10 items, there are no more pages
+        return {
+          query: {
+            page: Number(lastPageParams.query?.page) + 1,
+          },
+        };
+      },
+      initialPageParam: {
+        query: {
+          page: 1, // will be used in initial request
+        },
+      },
+    }
+  );
 
-  return <div>Name: {data?.name}</div>;
+  return (
+    <div>
+      {infiniteQuery.data?.pages.map((page, pageIndex) => (
+        <ul key={pageIndex}>
+          {page.map((post) => (
+            <li key={post.id}>{post.title}</li>
+          ))}
+        </ul>
+      ))}
+      <button
+        onClick={() => {
+          // ⬇︎ Executes GET /posts?limit=10&page=2
+          infiniteQuery.fetchNextPage();
+        }}
+      >
+        Load More
+      </button>
+    </div>
+  );
 }
 
-function App() {
+export default function App() {
   return (
-    <Providers>
-      <Example />
-    </Providers>
+    <QueryClientProvider client={queryClient}>
+      <PostList />
+    </QueryClientProvider>
   );
 }
 ```
 
-> The Qraft is designed to be as modular as possible, enabling you to integrate your own request client and serializers.
-> To ensure optimal tree-shaking, we do not include default serializers in the functions.
-
 ## Supported Hooks
 
 - [x] [`useQuery(...)`](https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useQuery)
@@ -173,461 +278,10 @@ function App() {
 - [x] [`getInfiniteQueryState(...)`](https://openapi-qraft.github.io/openapi-qraft/docs/query-client/getInfiniteQueryState)
 - [x] [`getMutationKey(...)`](https://openapi-qraft.github.io/openapi-qraft/docs/query-client/getMutationKey)
 
-## Usage
-
-With the client set up, you can now use the generated Hooks in your React Components to fetch data, execute mutations,
-and more.
-
-### [useQuery(...) 🔗](https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useQuery)
-
-```ts
-/**
- * Will execute the request:
- * ###
- * GET /entities?sort=updated_at
- * x-monite-version: 2023-09-01
- **/
-const { data, error, isPending } = qraft.entities.getEntities.useQuery({
-  header: {
-    'x-monite-version': '2023-09-01',
-  },
-  query: {
-    sort: 'updated_at',
-  },
-});
-```
-
-### [useMutation(...) 🔗](https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useMutation)
-
-#### With predefined parameters
-
-In case you know the query parameters that are needed for mutation, you can preset them. In this case, you must pass
-only `body` when calling `mutate()` function:
-
-```ts
-const mutation = qraft.entities.postEntitiesIdDocuments.useMutation({
-  path: {
-    entity_id: '3e3e-3e3e-3e3e',
-  },
-  header: {
-    'x-monite-version': '2023-09-01',
-  },
-});
-
-/**
- * Will execute the request when call `mutation.mutate(...)`:
- * ###
- * POST /entities/3e3e-3e3e-3e3e/documents
- * x-monite-version: 2023-09-01
- *
- * {"company_tax_id_verification": ["verification-id"]}
- **/
-mutation.mutate({
-  company_tax_id_verification: ['verification-id'],
-});
-```
-
-#### Without predefined parameters
-
-It happens that at the time of calling the Mutation Hook, you don't yet know what query parameters to be passed. In this
-case,
-you will need to pass the _parameters and the body_ of the request when you call `mutate()` function:
-
-```ts
-const mutation = qraft.entities.postEntitiesIdDocuments.useMutation();
-
-/**
- * Will execute the request when call `mutation.mutate(...)`:
- * ###
- * POST /entities/3e3e-3e3e-3e3e/documents
- * x-monite-version: 2023-09-01
- *
- * {"company_tax_id_verification": ["verification-id"]}
- **/
-mutation.mutate({
-  path: {
-    entity_id: '3e3e-3e3e-3e3e',
-  },
-  header: {
-    'x-monite-version': '2023-09-01',
-  },
-  body: {
-    company_tax_id_verification: ['verification-id'],
-  },
-});
-```
-
-### [useMutationState(...) 🔗](https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useMutationState)
-
-Mutation state is a helper hook that provides the current state of a mutation globally.
-It could be used to track the status of a mutation in any component, which is useful for showing loading spinners or
-disabling buttons.
-
-```ts
-const { mutate } = qraft.entities.postEntitiesIdDocuments.useMutation({
-  path: {
-    entity_id: '3e3e-3e3e-3e3e',
-  },
-  header: {
-    'x-monite-version': '2023-09-01',
-  },
-});
-
-const mutationState = qraft.entities.postEntitiesIdDocuments
-  // You can pass Partial parameters, or even `undefined` to specify filters
-  .useMutationState({ path: { entity_id: '3e3e-3e3e-3e3e' } })
-  ?.at(0);
-
-useEffect(() => {
-  if (!mutationState || mutationState.status === 'iddle') {
-    mutate({ company_tax_id_verification: ['verification-id'] });
-  }
-}, [mutate, mutationState?.status]);
-```
-
-### [useInfiniteQuery(...) 🔗](https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useInfiniteQuery)
-
-#### _Offset-based_
-
-```ts
-/**
- * Will execute the initial request:
- * ###
- * GET /posts?limit=10&page=1
- **/
-const infiniteQuery = qraft.posts.getPosts.useInfiniteQuery(
-  { query: { limit: 10 } },
-  {
-    // * required by TanStack Query
-    getNextPageParam: (lastPage, allPages, lastPageParams) => {
-      if (lastPage.length < 10) return; // if less than 10 items, there are no more pages
-      return {
-        query: {
-          page: Number(lastPageParams.query?.page) + 1,
-        },
-      };
-    },
-    // * required by TanStack Query
-    initialPageParam: {
-      query: {
-        page: 1, // will be used in initial request
-      },
-    },
-  }
-);
-
-// ⬇︎ will execute GET /posts?limit=10&page=2
-infiniteQuery.fetchNextPage();
-```
-
-#### _Pagination token_ based
-
-If your API uses pagination tokens, the Infinite Queries implementation becomes quite laconically:
-
-```ts
-/**
- * Will execute the initial request:
- * ###
- * GET /data_exports
- * x-monite-version: 2023-09-01
- * x-monite-entity-id: 3e3e-3e3e-3e3e
- **/
-const infiniteQuery = qraft.dataExports.getDataExports.useInfiniteQuery(
-  {
-    header: {
-      'x-monite-version': '2023-09-01',
-      'x-monite-entity-id': '3e3e-3e3e-3e3e',
-    },
-  },
-  {
-    // * required by TanStack Query
-    initialPageParam: {
-      query: { pagination_token: undefined }, // will be used in initial request
-    },
-    // * required by TanStack Query
-    getNextPageParam: (lastPage, allPages, lastPageParam) => ({
-      query: { pagination_token: lastPage.next_pagination_token },
-    }),
-    // * optional
-    getPreviousPageParam: (firstPage, allPages, firstPageParam) => ({
-      query: { pagination_token: firstPage.prev_pagination_token },
-    }),
-  }
-);
-
-// ⬇︎ will execute GET /data_exports?pagination_token=<NEXT_PAGINATION_TOKEN>
-infiniteQuery.fetchNextPage();
-
-// ⬇︎ will execute GET /data_exports?pagination_token=<PREV_PAGINATION_TOKEN>
-infiniteQuery.fetchPreviousPage();
-```
-
-### [useQueries(...) 🔗](https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useQueries)
-
-```ts
-/**
- * Will execute the request two queries:
- * ###
- * GET /entities/3e3e-3e3e-3e3e
- * x-monite-version: 2023-09-01
- * ###
- * GET /entities/5c5c-5c5c-5c5c
- * x-monite-version: 2023-09-01
- **/
-qraft.entities.getEntities.useQueries({
-  queries: [
-    {
-      parameters: {
-        header: {
-          'x-monite-version': '2023-09-01',
-        },
-        path: {
-          entity_id: '3e3e-3e3e-3e3e',
-        },
-      },
-    },
-    {
-      parameters: {
-        header: {
-          'x-monite-version': '2023-09-01',
-        },
-        path: {
-          entity_id: '5c5c-5c5c-5c5c',
-        },
-      },
-    },
-  ],
-  combine: (results) => results.map((result) => result.data),
-});
-```
-
-## [`QueryClient`](https://tanstack.com/query/latest/docs/reference/QueryClient) Methods
-
-#### [setQueryData(...) 🔗](https://openapi-qraft.github.io/openapi-qraft/docs/query-client/setQueryData)
-
-```ts
-qraft.pet.getPetById.setQueryData(
-  { path: { petId: 123 } }, // Query Key parameters
-  { id: 123, name: 'Rex' }, // Data to set
-  queryClient
-);
-```
-
-### [invalidateQueries(...) 🔗](https://openapi-qraft.github.io/openapi-qraft/docs/query-client/invalidateQueries)
-
-[Queries Invalidation 🔗](https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation) is possible
-using `<operation>.invalidateQueries(...)` method.
-This method is a wrapper around the `queryClient.invalidateQueries(...)`.
-
-##### Invalidation with _parameters_:
-
-To invalidate queries, with the specified parameters, you can use the `invalidateQueries` method:
-
-```ts
-/**
- * Will invalidate the queries with the specified parameters:
- * ###
- * GET /entities/3e3e-3e3e-3e3e
- * x-monite-version: 2023-09-01
- **/
-qraft.entities.getEntities.invalidateQueries(
-  {
-    parameters: {
-      header: {
-        'x-monite-version': '2023-09-01',
-      },
-      path: {
-        entity_id: '3e3e-3e3e-3e3e',
-      },
-    },
-  },
-  queryClient
-);
-```
-
-#### Invalidation without _parameters_:
-
-To invalidate all queries for a specific endpoint, you can call `invalidateQueries` without any parameters:
-
-```ts
-/**
- * Will invalidate the queries matching the specified endpoint:
- * ###
- * GET /entities/3e3e-3e3e-3e3e
- * x-monite-version: 2023-09-01
- * ###
- * GET /entities/4c4c-4c4c-4c4c
- * x-monite-version: 2023-09-01
- **/
-qraft.entities.getEntities.invalidateQueries(queryClient);
-```
-
-#### Invalidation with _queryKey_:
-
-It could be useful to invalidate queries using `queryKey` directly:
-
-```ts
-/**
- * Will invalidate the queries matching the specified endpoint:
- * ###
- * GET /entities/3e3e-3e3e-3e3e
- * x-monite-version: 2023-09-01
- **/
-qraft.entities.getEntities.invalidateQueries(
-  {
-    // `queryKey` is fully typed to `qraft.entities.getEntities`
-    queryKey: qraft.entities.getEntities.getQueryKey({
-      header: {
-        'x-monite-version': '2023-09-01',
-      },
-      path: {
-        entity_id: '3e3e-3e3e-3e3e',
-      },
-    }),
-  },
-  queryClient
-);
-```
-
-#### [Invalidation with predicate: 🔗](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters)
-
-The `predicate(...)` function will be used as a final filter on all matching queries.
-
-```ts
-/**
- * Will invalidate the queries matching the specified endpoint and predicate:
- * ###
- * GET /entities/3e3e-3e3e-3e3e
- * x-monite-version: 2023-09-01
- **/
-qraft.entities.getEntities.invalidateQueries(
-  {
-    parameters, // * optional, or specific parameters, alternatively, you can use `queryKey`
-    predicate: (query) => {
-      // `infinite`⬇︎ property will preset for Infinite Queries
-      if ('infinite' in query.queryKey[0]) return false;
-
-      // `queryKey`⬇︎ is fully typed to `qraft.entities.getEntities` operation parameters
-      if (query.queryKey[1].path.entity_id === '4c4c-4c4c-4c4c') return false;
-
-      return true;
-    },
-  },
-  queryClient
-);
-```
-
-### [fetchQuery(...) 🔗](https://openapi-qraft.github.io/openapi-qraft/docs/query-client/fetchQuery)
-
-```ts
-/**
- * Will execute the request:
- * ###
- * GET /posts?limit=10
- **/
-import { requestFn } from '@openapi-qraft/react';
-import { QueryClient } from '@tanstack/react-query';
-
-const queryClient = new QueryClient();
-
-const posts = qraft.posts.getPosts.fetchQuery(
-  {
-    parameters: { query: { limit: 10 } },
-    /**
-     * Request function should be provided, otherwise it will throw an error
-     * if default `queryFn` is not set previously using
-     * `QueryClient.setDefaultOptions(...)` method
-     */
-    requestFn: requestFn,
-    baseUrl: 'https://api.sandbox.monite.com/v1', // must be provided if `requestFn` is set
-  },
-  queryClient
-);
-```
-
-### [fetchInfiniteQuery(...) 🔗](https://openapi-qraft.github.io/openapi-qraft/docs/query-client/fetchInfiniteQuery)
-
-```ts
-/**
- * Will execute the initial request:
- * ###
- * GET /posts?limit=10&page=1
- * ###
- * And then will execute the next page request:
- * GET /posts?limit=10&page=2
- **/
-import { requestFn } from '@openapi-qraft/react';
-import { QueryClient } from '@tanstack/react-query';
-
-const queryClient = new QueryClient();
-
-const posts = qraft.posts.getPosts.fetchInfiniteQuery(
-  {
-    parameters: { query: { limit: 10 } },
-    pages: 2, // How many pages to fetch
-    initialPageParam: {
-      query: { pagination_token: undefined }, // will be used in initial request
-    },
-    getNextPageParam: (lastPage, allPages, lastPageParam) => ({
-      query: { pagination_token: lastPage.next_pagination_token },
-    }),
-    /**
-     * Request function should be provided, otherwise it will throw an error
-     * if default `queryFn` is not set previously using
-     * `QueryClient.setDefaultOptions(...)` method
-     */
-    requestFn: requestFn,
-    baseUrl: 'https://api.sandbox.monite.com/v1', // must be provided if `requestFn` is set
-  },
-  queryClient
-);
-
-console.log(
-  posts.pages, // all fetched pages
-  posts.pageParams // all page parameters
-);
-```
-
-### Authorization and Custom Requests
-
-To override any request, you can provide a custom `request` function to the `QraftContext`.
-
-In the example below, we provide a custom `request` function to the `QraftContext` to handle the authorization token
-using a custom `fetchToken` async function.
-
-```tsx
-import { QraftContext, requestFn } from '@openapi-qraft/react';
-import { fetchToken } from './auth';
-
-function QraftProvider({ children }: { children: React.ReactNode }) {
-  return (
-    <QraftContext.Provider
-      value={{
-        baseUrl: 'https://api.sandbox.monite.com/v1',
-        async requestFn(schema, requestInfo) {
-          const token = await fetchToken();
-
-          return requestFn(schema, {
-            ...requestInfo,
-            /** Specify your predefined Headers **/
-            headers: {
-              Authorization: `Bearer ${token}`,
-            },
-          });
-        },
-      }}
-    >
-      {children}
-    </QraftContext.Provider>
-  );
-}
-```
-
 ## Contributing
 
 Contributions are welcome! If you have suggestions or want to improve `@openapi-qraft/react`, please feel free to submit
-a
-pull request or open an issue.
+a pull request or open an issue.
 
 ## License