Mutations

await kweri.mutate(createUser, {
  body: { name: 'Alice', email: '[email protected]' }
})

interface MutationOptions<TParams, TResponse, TContext = unknown> {
  onMutate?:  (params: TParams) => TContext | Promise<TContext>
  onSuccess?: (data: TResponse, params: TParams, context: TContext) => void
  onError?:   (error: Error, params: TParams, context: TContext) => void
  onSettled?: (
    data: TResponse | undefined,
    error: Error | undefined,
    params: TParams,
    context: TContext
  ) => void
  invalidates?: Endpoint[]
}

onMutate() → [network request] → onSuccess() or onError() → onSettled()

await kweri.mutate(deleteUser, { path: { id: userId } }, {
  onMutate: (params) => {
    // 1. Snapshot current data
    const previous = kweri.getCachedData(getUsers, {})

    // 2. Optimistically remove the user
    kweri.setCachedData(getUsers, {}, previous?.filter(u => u.id !== params.path.id))

    // 3. Return snapshot for rollback
    return { previous }
  },
  onError: (_err, _params, context) => {
    // Rollback on failure
    if (context?.previous) {
      kweri.setCachedData(getUsers, {}, context.previous)
    }
  },
  onSuccess: () => {
    // Confirm with fresh server data
    kweri.invalidateByPath('/users')
  }
})

await kweri.mutate(createPost, { body: newPost }, {
  invalidates: [getPosts]
})

import { useMutation } from '@/hooks/useKweri'
import { kweri } from '@/lib/kweri'
import { createUser } from '@/api/users'

function CreateUserForm() {
  const mutation = useMutation(kweri, createUser)

  async function handleSubmit(data) {
    try {
      const user = await mutation.mutateAsync({ body: data })
      console.log('Created:', user)
    } catch (err) {
      console.error('Failed:', err)
    }
  }

  return (
    <button
      onClick={() => handleSubmit(formData)}
      disabled={mutation.isLoading}
    >
      {mutation.isLoading ? 'Saving...' : 'Create User'}
    </button>
  )
}

interface ReactMutationResult<TData, TError> {
  mutate:       (vars?: unknown) => void           // fire-and-forget
  mutateAsync:  (vars?: unknown) => Promise<TData> // awaitable
  status:       CacheEntryStatus
  error:        TError | undefined
  reset:        () => void                         // clear status/error
  isLoading:    boolean
  isSuccess:    boolean
  isError:      boolean
}

<script setup lang="ts">
import { usePost } from '@/composables/useKweri'

const mutation = usePost('/users')

async function createUser(data) {
  try {
    await mutation.mutateAsync({ body: data })
  } catch (err) {
    // mutation.error.value is also set
  }
}
</script>

<template>
  <button @click="createUser(formData)" :disabled="mutation.isLoading.value">
    {{ mutation.isLoading.value ? 'Saving...' : 'Create User' }}
  </button>
  <p v-if="mutation.isError.value">{{ mutation.error.value?.message }}</p>
</template>

interface VueMutationResult<TData, TError> {
  mutate:      (vars?: unknown) => void
  mutateAsync: (vars?: unknown) => Promise<TData>
  status:      Ref<CacheEntryStatus>
  error:       Ref<TError | undefined>
  reset:       () => void
  isLoading:   Ref<boolean>
  isSuccess:   Ref<boolean>
  isError:     Ref<boolean>
}

const deleteUserMutation = useDelete('/users/{id}')
const usersQuery = useGet('/users')

async function deleteUser(user) {
  const prev = usersQuery.data.value ?? []

  // Optimistic remove
  usersQuery.data.value = prev.filter(u => u.id !== user.id)

  try {
    await deleteUserMutation.mutateAsync({ path: { id: String(user.id) } })
    kweri.invalidateByPath('/users')
  } catch {
    usersQuery.data.value = prev  // rollback
  }
}