Core Basic Usage

The Core of gqless can work in two ways:

With pre-defined functions.
Using a scheduler that catches everything you have requested every few milliseconds.

Prerequisites#
Make sure you've completed Getting Started first
"../gqless" refers to the generated client file/directory

The React bindings uses both, but primarily via the scheduler, and playing with the React Lifecycle to make it work seamlessly.

But gqless is not a React-Exclusive library, you can use it without it in Node.js, or any framework (we might add more bindings for other Frontend frameworks in the future).

Without making extra bindings/helpers, we suggest using pre-defined functions for most use-cases, since you can avoid repeating yourself.

Pre-defined functions#

resolved#

resolved is very straightforward, you give it a function, and it will isolate the requests you are making, and it returns a promise of the data just as you returned it.

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

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

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

inlineResolved#

inlineResolved is similar to resolved, you give it a pre-defined function, but it won't isolate it's requests, instead, it will use the scheduler indirectly, and asynchronously merge your concurrent requests, and it returns either the requested data directly if no fetch is needed, or a promise of the data just as you returned it.

import { query, inlineResolved } from '../gqless';

// ...

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

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

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

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

You can also specify some options in the second argument, like forcing refetch and/or intercepting existing cache while refetching, check InlineResolveOptions for more information.

Using the Scheduler directly#

Using the scheduler consists in basically making the data request, and then awaiting for a possible promise, that resolves when your data has arrived.

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

async function Example() {
  query.helloWorld;

  await client.scheduler.resolving?.promise;

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

Using this method, error handling is also more tricky, since the scheduler.resolving.promise never rejects, instead, it returns the possible error and data in the resulting value.

You could do something like this:

async function Example() {
  query.helloWorld;

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

refetch#

refetch is 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 '../gqless';

// ...

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);