Begrip: useMutation

De useMutation hook (uit TanStack Query) wordt gebruikt om data aan te passen op de server en bevat verschillende mogelijkheden om functies uit te voeren als de aanpassingen succesvol afgerond zijn, mislukken of juist beginnen.

De hook neemt een object als parameter dat één verplichte property (mutationFn) heeft en verschillende optionele properties (onMutate, onSuccess, onError, onSettled, ...). We bespreken in deze cursus enkel de meest courante properties.

In volgend codefragment wordt gebruik gemaakt van de data, error, variables en context parameters die volgende betekenis hebben:

• data: Hetgeen dat teruggegeven wordt door de mutationFn, i.e. de aangepaste data, het resultaat van een POST, PUT, PATCH of DELETE request. Het type, TData moet dus overeenkomen met de returnwaarde van de mutationFn.
• error: Een eventuele error die opgegooid wordt door de mutationFn in het geval dat deze niet succesvol afgerond kon worden. _ variables: Een object met parameters die aan de mutationFn doorgegeven worden, TVariables moet dus overeenkomen met de eerste (en enige) parameter van de mutationFn. Gebruik dus altijd een object als parameter voor de mutationFn en nooit een primitieve variabele zoals een string, number, boolean of array. _ context: Data die van de onMutate functie doorgegeven wordt naar de onSuccess, onError en onSettled functies.

const {
    isError,
    mutate, 
    data, 
    isSuccess,
    isIdle
}: UseMutationResult<TData, TError, TVariables, TContext> = useMutation({
    mutationFn: (variables: TVariables) => {
        // Wordt uitgevoerd als de mutate property in de returnvalue opgeroepen wordt.
        // Via deze functie wordt de data server-side aangepast. 
        // POST, PUT, DELETE of PATCH geen GET!
    },
    onMutate: (variables: TVariables): TContext => {
        // Wordt opgeroepen vlak voordat de mutation functie opgeroepen is.
        // Wordt meestal gebruik om optimistische updates uit te voeren.
    },
    onSuccess: (data: TData, variables: TVariables, context: TContext) => {
        // Wordt uitgevoerd als de mutationFn zonder problemen afgerond is.
    },
    onError: (error: TError, variables: TVariables, context: TContext) => {
        // Wordt uitgevoerd als de mutationFn met errors afgerond is.
    },
    onSettled: (data: TData | undefined, error: TError | undefined, variables: TVariables, context: TContext) => {
        // Wordt uitgevoerd als de onSuccess en onError functies afgehandeld zijn, of
        // nadat de mutation afgerond is in het geval dat onSucess en onError niet gedefinieerd zijn.
    }
})