Fetching data#

Prerequisites#

Make sure you've completed Getting Started first.

../gqty refers to the generated directory.

GQty is a framework-agnostic GraphQL client, and can be used anywhere (we might add more bindings for other Frontend frameworks in the future).

Fetching data#

resolved#

Accepts a callback, which will be recursively executed, until the data has been fetched (or an error occurs). The final result of the callback is returned as a promise.

If your request has any error, either from syntax or from the GraphQL API, it will always throw an instance of GQtyError (which is itself, an instance of Error)

import { query, resolved } from '../gqty';

resolved(() => {
  return query.helloWorld!;
})
  .then((data) => {
    // data == string
  })
  .catch((err) => {
    // err == import("gqty").GQtyError
  });

You can specify options in the second argument, like forcing a refetch or isolating from existing cache.

inlineResolved#

inlineResolved is the exact same as resolved, but it returns the data straight away if it can.

const possibleData = inlineResolved(() => {
  return query.helloWorld!;
});

if (possibleData instanceof Promise) {
  // data == Promise<string>

  // Waiting for data from API
  const data = await possibleData;

  // data == string
} else {
  // possibleData == string
}

Refetching data#

refetch#

A special function that accepts object proxies, or functions.

When dealing with object proxies, it recovers all the history of the specific object down the tree of selections, and refetchs them, returning the same object back after all the resolutions are done.

On the other hand, when used with a function, it calls the function (using the core scheduler) ignoring possible nulls in the middle in the first pass, and returns whatever the function gave back as a promise.

import { query, refetch, resolved } from '../gqty';

// ...

const data = await resolved(() => {
  const user = query.user;

  if (user) {
    return {
      id: user.name,
      name: user.name,
    };
  }
  return null;
});

// Later...

// It will refetch 'id' & 'name' of 'query.user'
const refetchedUser = await refetch(query.user);

Advanced Usages#

Operation name#

A custom operation name can be added to GraphQL queries, mutations and subscriptions.

This is useful when mocking for unit tests, and advanced server logics.

import { query, resolved, inlineResolved } from '../gqty';

resolved(() => query.helloWorld, { operationName: 'MyQuery' });

inlineResolved(() => query.helloWorld, { operationName: 'MyQuery' });

Both resolved and inlineResolved above will generate the following query:

query MyQuery {
  helloWorld
}

track#

The function track accepts a callback that gets automatically called every time related data arrives or related cache changes, particularly useful for subscriptions, but it also works for queries.

The returned function stop unsubscribes and stops tracking and data is an object that has a field .current that has the latest returned value from the callback.

import { track, subscription } from '../gqty';

const { stop, data } = track(() => {
  return subscription.newNotification;
});

// data.current === string | undefined

setTimeout(() => {
  stop();
}, 5000);

track options#

track(
  (info) => {
    /**
     * info === { type: "initial" | "cache_change" }
     **/
  },
  {
    onError(err) {
      /**
       * err === GQtyError
       **/

      console.error(err);
    },
    // Refetch on initial call
    refetch: true,
  }
);

The scheduler#

GQty exposes the Scheduler API, which is used by the helper functions above.

import { query, client } from '../gqty';

async function Example() {
  query.helloWorld;

  await client.scheduler.resolving?.promise;

  // string
  const helloWorld = query.helloWorld!;
}

Error handling#

The scheduler resolves to a promise of a GQtyError:

async function Example() {
  query.helloWorld;

  await client.scheduler.resolving?.promise.then(({ error }) => {
    // error == import("gqty").GQtyError | undefined
    if (error) {
      throw error;
    }
  });
}