Mutation ​

What is a Mutation ​

Since we have an abstraction to retrieve data from the remote source, we have to have an abstraction to send data to the remote source. Farfetched provides Mutations for this purpose. All you need to know about Mutation:

1. it has handler that performs operation on the remote source
2. it does not store any data inside, it provides only lifecycle Events
3. it can be started with some parameters

That's it, that is all what you need to know about Mutation. Let's create our first Mutation!

Mutation creation ​

Farfetched does not restrict Mutation creation process, so you can create them in any way you want. However, the most common way is to use one of the provided factories. The simplest one is createMutation, let's start with it.

The basic overload of this factory accepts only a handler function:

import { createMutation } from '@farfetched/core';

const myFirstMutation = createMutation({
  handler: async (params) => {
    // TODO: write handler here
    return null;
  },
});

So handler have to be asynchronous function that accepts some parameters and performs some work. It can return some data or does not return it. Since Farfetched is created for handling remote data, the most common use case of handler is function that calls some API.

Let's create some mutation to create a new entity in the API:

const createEntityMutation = createMutation({
  handler: async ({ name, id }) => {
    const response = await fetch(`https://api.salo.com/api/`, {
      method: 'POST',
      body: JSON.stringify({ name, id }),
    });

    return response.json();
  },
});

That's it, we have created our first Mutation! Now we can start it with some parameters:

createEntityMutation.start({ id: 1, name: 'Some new name' });

After this call Mutation will start its handler with the given parameters and store the result inside. But how will we know this result?

Mutation result ​

Since Mutation does not store any data inside, it provides only lifecycle Events. The most important of them are finished.success and finished.failure. Let's subscribe to these events:

createEntityMutation.finished.success.watch(({ params, data }) => {
  showNotification({
    message: `Entity ${params.id} was created!`,
    type: 'info',
  });
});

createEntityMutation.finished.failure.watch(({ params, data }) => {
  showNotification({
    message: `Entity ${params.id} was not created!`,
    type: 'error',
  });
});

In real applications, we assume that the result of the Mutation will be used as a part of business logic, consider using Effector to describe your control flow.

Mutation status ​

Since Mutation is an asynchronous operation, you can use .$status to get current status of the operation. It is a Store that contains one of the following statuses: "initial", "pending", "success" or "fail".