useMutation()

The Hook enables you to perform asynchronous data mutation operations, such as POST, PUT, PATCH, or DELETE requests. It not only handles the loading state, but also provides an APIs for optimistic updates and error handling. See the TanStack useMutation(...) 🌴 documentation for more details.

const query = api.<service>.<operation>.useMutation(
  parameters,
  mutationOptions
)

Arguments

1. parameters?: { path, query, header }

   • Optional, OpenAPI request parameters for the query, strictly-typed ✨
   • When parameters provided, it will be used to generate the mutationKey

2. mutationOptions?: UseMutationOptions

   • Optional, represents the options of the useMutation(...) 🌴 Hook
   • When api.<srv>.<op>.useMutation(parameters) is used (with the predefined parameters), mutationKey will contain the parameters and operation schema
   • When api.<srv>.<op>.useMutation(undefined) is used (without predefined parameters), mutationKey will contain just operation schema
   • mutationOptions.mutationFn could be provided to override the default mutationFn used by Qraft, strictly-typed ✨
   • mutationOptions.mutationKey could be provided to override the generated key from parameters, strictly-typed ✨

Returns

• mutation: MutationResult
  • Object from the useMutation(...) 🌴 Hook
  • mutation.mutate(parameters | {parameters, body}) initiates the request
  • mutation.variables will contain the parameters and body of the request, after calling mutation.mutate(...).

Examples

With parameters 📖

When the parameters are known, the useMutation hook can be used with parameters to generate the mutationKey.

• mutation.mutate(...) will accept the body of the request as the single argument.

src/EntityEditForm.tsx

import { createAPIClient } from './api'; // generated by OpenAPI Qraft

import { requestFn } from '@openapi-qraft/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

const api = createAPIClient({
  requestFn,
  queryClient,
  baseUrl: 'https://api.sandbox.monite.com/v1',
});

function EntityEditForm({ entityId }: { entityId: string }) {
  const mutation = api.entities.entitiesIdDocuments.useMutation({
    path: {
      entity_id: entityId
    },
    header: {
      'x-monite-version': '2023-09-01',
    },
  });

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const formData = new FormData(event.currentTarget);
        /**
         * `mutation.mutate(...)` triggers the submission of a 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: [
            `${formData.get('company_tax_id_verification')}`,
          ],
        });
      }}
    >
      <input name="company_tax_id_verification" />
      <button disabled={mutation.isPending}>Submit</button>
    </form>
  );
}

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <EntityEditForm entityId="123" />
    </QueryClientProvider>
  );
}

No parameters 📓

When the parameters are not known, the useMutation hook can be used without parameters.

• mutation.mutate(...) will accept the object with parameters and body of the request as the single argument.

src/EntityForm.tsx

import { createAPIClient } from './api'; // generated by OpenAPI Qraft

import { requestFn } from '@openapi-qraft/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

const api = createAPIClient({
  requestFn,
  queryClient,
  baseUrl: 'https://api.sandbox.monite.com/v1',
});

function EntityForm() {
  const mutation = api.entities.entitiesIdDocuments.useMutation();

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const formData = new FormData(event.currentTarget);
        /**
         * `mutation.mutate(...)` triggers the submission of a request:
         * ###
         * POST /entities/3e3e-3e3e-3e3e/documents
         * x-monite-version: 2023-09-01
         *
         * {"company_tax_id_verification": ["verification-id"]}
         **/
        mutation.mutate({
          parameters: {
            path: {
              entity_id: `${formData.get('entity_id')}`
            },
            header: {
              'x-monite-version': '2023-09-01',
            },
          },
          body: {
            company_tax_id_verification: [
              `${formData.get('company_tax_id_verification')}`,
            ],
          }
        });
      }}
    >
      <input name="entity_id" readOnly={mutation.isPending} />
      <input name="company_tax_id_verification" readOnly={mutation.isPending} />
      <button disabled={mutation.isPending}>Submit</button>
    </form>
  );
}

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <EntityForm />
    </QueryClientProvider>
  );
}