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 = qraft.<service>.<operation>.useMutation(
  parameters,
  mutationOptions,
  queryClient,
)

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 qraft.<srv>.<op>.useMutation(parameters) is used (with the predefined parameters), mutationKey will contain the parameters and operation schema
   • When qraft.<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 ✨

3. queryClient?: QueryClient

   • Optional QueryClient 🌴 to be used
   • If not provided
     • QraftContext.queryClient will be used if available
     • useQueryClient() 🌴 result will be used as a fallback

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

const qraft = createAPIClient();

function EntityEditForm({ entityId }: { entityId: string }) {
  const mutation = qraft.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>
  );
}

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

const qraft = createAPIClient();

function EntityForm() {
  const mutation = qraft.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>
  );
}