Package Exports

gqless-hooks

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (gqless-hooks) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

gqless-hooks

yarn add gqless-hooks
# or
npm install gqless-hooks

This library creates a couple of hooks to interact with gqless, all while being type-safe.

If you are not familiar with gqless please check https://gqless.dev/

Table of Contents

Usage
Features
Docs and API Reference
Usage tips
About it
Future

Usage

This library should ideally be imported and used at src/graphql/client.ts (this is default location, could be anywhere you previously set it up)

import { Client, QueryFetcher } from 'gqless';

import { Mutation, Query, schema } from './generated';

import { createUseMutation, createUseQuery } from 'gqless-hooks';

const endpoint = '...';

// ...
export const query = client.query;

export const useMutation = createUseMutation<Mutation>({
  endpoint,
  schema,
});
export const useQuery = createUseQuery<Query>({
  endpoint,
  schema,
});

Then anywhere you want to use them, you import them just like the default vanilla query.

import { useMutation, useQuery } from '../src/graphql';

const Component = () => {
  const [helloWorldMutation, helloWorldData] = useMutation(
    ({ helloWorldMutation }) => {
      const { id, label } = helloWorldMutation({ arg: 'hello' });

      return { id, label };
    }
  );

  // helloWorldData === { data, state = "loading" | "error" | "waiting" | "done", errors = GraphqlError[] | undefined }

  // helloWorldMutation works as initiator of the mutation or recall.

  const [helloWorldData, { callback, refetch, cacheRefetch }] = useQuery(
    ({ helloWorldQuery: { id, label } }) => ({ id, label }),
    {
      // if lazy == true, wait until function from returned array is called
      lazy: true,
    }
  );

  // helloWorldData === { data = { id,label } | undefined | null, state = "loading" | "error" | "waiting" | "done", errors = GraphqlError[] | undefined }

  // callback and refetch work as initiators of the query or refetch.
};

Features

Shared global cache using policies.
Polling
Automatic refetch on variables change
Shared hooks pool through unique identifiers, available via onCompleted event on every hook.

Docs and API Reference

You can check https://pabloszx.github.io/gqless-hooks/ for some documentation and API Reference, all generated through it's strong type-safety using TypeDoc.

Also keep in mind that these hooks are heavily inspired by React Apollo GraphQL

useQuery is inspired by Apollo useQuery
useMutation is inspired by Apollo useMutation

Usage tips

Due to how gqless works, in the query and mutation hook functions, when you return some data, you have to explicitly access it's properties for it to detect it's requirements, this means in practice that if you have an object, you have to explictly explore its properties (destructuring for example) and return them, and for arrays is the same, but for them it's recommended to use array.map(...).

For example

useQuery(
  (schema, variables) => {
    // variables === { b: 2 }
    const { field1, field2 } = schema.helloWorldObj;

    return { field1, field2 };

    // return helloWorldObj; <- would return an empty object
  },
  {
    variables: {
      b: 2,
    },
  }
);
useQuery(
  (schema, variables) => {
    // variables === { a: 1 }
    const array = schema.helloWorldArray;

    return array.map(({ fieldA, fieldB }) => ({ fieldA, fieldB }));

    // return array; <- would return an empty array
  },
  {
    variables: {
      a: 1,
    },
  }
);

About it

These hooks are a proof of concept that ended up working and is a good workaround until React Suspense is officially released (with good SSR support) and Mutation are officially supported by gqless.

If you are only using these hooks and not the default query from gqless, you don't need to use the graphql HOC.

Future

Add more examples of usage
Add support for Subscriptions
Add support for Pagination with a fetchMore-alike (since gqless doesn't have planned support for it for the foreseeable future)