README

@solid-primitives/graphql

Creates a reactive GraphQL query client.

Installation

npm install @solid-primitives/graphql
# or
yarn add @solid-primitives/graphql

How to use it

Import

import { createGraphQLClient, gql, request } from "@solid-primitives/graphql";
// gql is a helper for creating GraphQL query strings
// request is an additional function to perform GraphQL requests imperatively

Using the client

createGraphQLClient takes 3 arguments:

url - target api endpoint, as string or signal
headers - optional, A list of request headers to supply the client
fetchFn - optional, A fetch function to replace the default one, that is Fetch API on browser and node-fetch on server.

import { createGraphQLClient, gql } from "@solid-primitives/graphql";

const newQuery = createGraphQLClient("https://foobar.com/v1/api");
const [data, { refetch }] = newQuery(
  gql`
    query data($path: ID!) {
      PageItem(id: $path) {
        content {
          body
        }
      }
    }
  `,
  { path: "home" }
);

Preventing immediate requests

Query function is based on createResource, so it can be deferred in the same way - by passing false to the variables.

const newQuery = createGraphQLClient("https://foobar.com/v1/api");
const [data, { refetch }] = newQuery(somequery, false);

// later
refetch();

Providing Response Type

// query function accepts type generic for the response:
const [countries] = newQuery<{ countries: { name: string }[] }>(
  gql`
    query {
      countries {
        name
        code
      }
    }
  `
);
countries(); // T: { countries: { name: string }[] } | undefined

Initial value

By default the returned data type will be T | undefined, to make it always T you need to provide an initial value.

const [countries] = newQuery<{ countries: { name: string }[] }>(
  gql`
    query {
      countries {
        name
        code
      }
    }
  `,
  // no variables
  undefined,
  // the initial value
  { countries: [] }
);
countries(); // T: { countries: { name: string }[] }

Reactive query variables

Variables passed to the query can be reactive. If they change, the resource will be refetched.

const [code, setCode] = createSignal("BR");
const [data] = query(
  gql`
    query data($code: ID!) {
      country(code: $code) {
        name
      }
    }
  `,
  // function returning an object
  () => ({
    code: code()
  })
);

Remember, just like with createResource, you will need an <ErrorBoundary> to catch the errors, even if they are accessible inside the resource. Otherwise, uncaught errors might disrupt your application.

Demo

You may view a working example here:

https://codesandbox.io/s/solid-primitives-graphql-demo-g6fv6?file=/index.tsx

Changelog

Expand Changelog

1.0.0

Initial commit and publish of primitive.

1.0.3

Released with CJS support.

1.0.4

Updated to latest Solid.

1.0.6

Function argument improvements, named exports.

1.0.7

Added export request function to make gql requests more imperative.

Usage no npm install needed!