graphql-quest

Quest

A minimal library for making GraphQL requests in JavaScript, coming in at < 700 bytes gzipped.

Why?

I needed an ultra-light, minimally-scoped client for talking to a GraphQL API. Prisma's graphql-request has the feature set I needed, and it's pretty small in size, but I wanted to go even thinner. For most use cases, Quest has an extremely similar feature set with a gzipped size that's ~9.5 times smaller than Prisma's alternative.

Installation

Package Manager

npm install graphql-quest or yarn add graphql-quest

CDN

Grab the link for the latest version and load it via <script> tag.

Simplest Usage

Quest provides a simple function for sending quick queries and doing something with the returned payload.

import { quest } from "graphql-quest";

const query = `
  {
    comments(domain: "macarthur.me") {
      createdAt
      name
      content
    }
  }
`;

quest("http://some-domain.com/graphql", query).then((result) => {
  console.log(result);

  // result will be formed as such:
  // {
  //   data?: {},
  //   errors?: []
  // }
});

You can also provide a variables object to be used with a respective query or mutation.

import { quest } from "graphql-quest";

const query = `
  query Comments($domain: String!) {
    comments(domain: $domain) {
      createdAt
      name
      content
    }
  }
`;

const variables = {
  domain: "macarthur.me",
};

quest("http://some-domain.com/graphql", query, variables).then((result) => {
  console.log(result);
});

More Complicated Usage

If you're going to be making repeated requests to the same server, you can preserve your endpoint, headers, etc. by creating a QuestClient instance and making queries with .send().

import { QuestClient } from "graphql-quest";

const client = QuestClient({
  endpoint: "http://some-domain.com/graphql",
  headers: {
    "x-api-key": "ABC-123",
  },
});

const query = `
  query Comments($domain: String!) {
    comments(domain: $domain) {
      createdAt
      name
      content
    }
  }
`;

const variables = {
  domain: "macarthur.me",
};

client.send(query, variables).then((result) => {
  console.log(result);
});

Returned Payload

Every request (even those that throw exceptions) will return an object containing data, errors, or both. This pattern is generally intended to stay in line with the GraphQL specification, but doesn't require that you .catch() any errors on your own. Instead, exceptions that are thrown are represented in the errors array.

{
  data?: object;
  errors?: any[];
}

So, checking the success of the request can be basically performed by checking if the errors property exists on the returned payload:

import { quest } from "grahpql-quest";

(async () => {
  const query = `your query`;
  const variables = { your: "variables" };

  const result = await quest(
    "http://some-domain.com/graphql",
    query,
    variables
  );

  if (result.errors) {
    console.log("Something went wrong!");
  }
})();

POST vs. GET

By default, requests are sent via POST, and the query & variables are sent along with the request body. If you'd like to send them via GET, set the method parameter accordingly. Instead, the query and variables will be parsed and attached as query string parameters to the endpoint, preserving any parameters that might already be set on the URL.

import { quest, QuestClient } from "graphql-quest";

const client = QuestClient({
  endpoint: "http://some-domain.com/graphql",
  method: "GET",
  headers: {
    "x-api-key": "ABC-123",
  },
});

// or...

const result = await quest("http://some-domain.com/graphql", query, variables, {
  method: "GET",
});

Usage in Node

You'll need to polyfill the Fetch API before using this library in Node. I tend to use isomorphic-fetch, but it's up to you.

require("isomorphic-fetch");
const { quest } = require("graphql-quest");

// The rest of your code...

Usage w/o a Bundler

If not using the ES module, you can access quest or QuestClient on the global Quest object after loading the source in the browser.

<script src="./dist/quest.js"></script>
<script>
  const { quest, QuestClient } = window.Quest;

  // ... the rest of your code.
</script>

Options

quest(
  endpoint: string,
  query: string,
  variables?: object,
  fetchOptions?: object
);

Option	Description
endpoint	the endpoint that'll be hit for the request
query	the query or mutation you're firing
variables	variables to be supplied to your query or mutation
fetchOptions	additional options to be passed into the fetch implementation under the hood (currently only supports headers and method)

QuestClient({
  endpoint,
  method,
  headers,
} : {
  endpoint: string,
  method?: string,
  headers?: object
})

Option	Description
endpoint	the endpoint that'll be hit for the request
method	HTTP method for sending request (default is POST)
headers	headers to include in request