Query ​

What is a Query ​

Farfetched provides a simple way to work with remote data. The minimal piece of remote data is represented by Query. All you need to know about Query:

1. it has handler that returns an actual data from the remote source
2. it stores some data inside
   • received data if the handler finished with a success
   • error if the handler finished with a failure
   • status that describes current state of the query
3. it can be started with some parameters

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

Query creation ​

Farfetched does not restrict Query 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 createQuery, let's start with it.

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

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

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

So handler have to be asynchronous function that accepts some parameters and returns some data. Since Farfetched is created for handling remote data, the most common use case of handler is function that calls some API and returns data from it.

Let's create a Query that represents a single character from the API by character ID:

const characterQuery = createQuery({
  handler: async ({ id }) => {
    const response = await fetch(
      `https://rickandmortyapi.com/api/character/${id}`
    );

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

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

characterQuery.start({ id: 1 });

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

Data extraction ​

Farfetched is built as a reactive library, so all data is stored inside Stores. Query is no exception, it stores result of the request inside Stores in field .$data, in the most common use case you will subscribe on this field to get the result:

characterQuery.$data.watch((data) => {
  // render some UI based on data
});

Whoa whoa whoa, wait! Direct watchers? Are we in 2010? Do not worry, it is just an example.

Farfetched provided a set of nice integrations to subscribe on Query in the most popular UI frameworks.

import { createQueryResource } from '@farfetched/solid';

const Character = () => {
  const [character] = createQueryResource(characterQuery);

  return (
    <Suspense fallback="Loading...">
      <h1>{character()?.name}</h1>
      <img src={character()?.image} />
    </Suspense>
  );
};

Read more in [Solid-specific](/tutorial/solid/) tutorial.

import { useUnit } from 'effector-react';

const Character = () => {
  const { data: character } = useUnit(characterQuery);

  if (!character) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <h1>{character.name}</h1>
      <img src={character.image} />
    </div>
  );
};

To extract error from Query, you can subscribe on .$error or use your favorite integration as well.

Query status ​

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