graphql-request

Minimal GraphQL client compliant with GraphQL-over-HTTP

GraphQL request built on Request object

GraphQLRequest is almost the same as the Request object. You create a Request instance by passing GraphQL parameters to the constructor.

import { GraphQLRequest } from "https://deno.land/x/gql_request@$VERSION/mod.ts";

const query = `query {
  person(personID: "1") {
    name
  }
}`;
const request = new GraphQLRequest(
  "https://swapi-graphql.netlify.app/.netlify/functions/index",
  query,
);

fetch(request);

It is fully compatible with the Request object, so the constructor accepts all options.

GraphQL request options

GraphQL-over-HTTP allows the following values as GraphQL request options:

Example specifying variables:

import { GraphQLRequest } from "https://deno.land/x/gql_request@$VERSION/mod.ts";

const query = `query PersonQuery($id: ID!) {
  person(personID: $id) {
    name
  }
}`;
const request = new GraphQLRequest(
  "https://swapi-graphql.netlify.app/.netlify/functions/index",
  query,
  {
    variables: {
      id: "1",
    },
  },
);

Request init options

GraphQLRequest accepts all RequestInit options.

By default, the HTTP method of the Request is set to POST.

The GraphQL-over-HTTP specification states that a GraphQL server must support the POST and GET methods.

Therefore, GraphQLRequest also supports the GET method. For GET, set the GraphQL request option as a query string.

import { GraphQLRequest } from "https://deno.land/x/gql_request@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const query = `query {
  person(personID: "1") {
    name
  }
}`;
const request = new GraphQLRequest(
  "https://swapi-graphql.netlify.app/.netlify/functions/index",
  query,
  {
    method: "GET",
  },
);
assertEquals(
  request.url,
  "https://swapi-graphql.netlify.app/.netlify/functions/index?query=query...",
);

GET or POST

GraphQL-over-HTTP is not very explicit about the use of different methods.

However, the following indicators are helpful

• If the GraphQL request is not a query, it should be a POST. [MUST]
• GET if the length of the request URL is less than or equal to the limit of the server implementation. [SHOULD]

HTTP GET methods are cacheable and should be used with GET if available.

However, since POST is safe to use in all situations, the POST method is set by default.

Throwing

The constructor may throw an error under the same conditions as a Request object. It may throw errors.

import { GraphQLRequest } from "https://deno.land/x/gql_request@$VERSION/mod.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

assertThrows(() => new GraphQLRequest("", ""), TypeError, "Invalid URL");

Fetch GraphQL

Supports GraphQL-specific fetch functions.

It conforms to the GraphQL-over-HTTP specification and supports the following media types.

• application/graphql-response+json
• application/json

properly handles HTTP response statuses and accepts generics types.

It also has an API similar to fetch and can be fully customized with RequestInit.

import { gqlFetch } from "https://deno.land/x/gql_request@$VERSION/mod.ts";

const query = `query {
  person(personID: "1") {
    name
  }
}`;
const { data, errors, extensions } = await gqlFetch<
  { person: { name: string } }
>("https://swapi-graphql.netlify.app/.netlify/functions/index", query);

Throwing Error

It may throw the following errors:

Client error

Client errors are thrown when the response status is not 2XX or the response media type is unsupported.

Client errors contain request and response data, allowing detailed analysis of the actual request and response.

Compress document

Provides utilities to compress GraphQL documents. It simply removes extra characters from the GraphQL document.

Compressing documents reduces bandwidth and increases the operational feasibility of the HTTP GET method.

import { gql } from "https://deno.land/x/gql_request@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std@$VERSION/testing/asserts.ts";

const document = gql`query Test {
  hello
}`;
assertEquals(document, "query Test{hello}");

License

Copyright © 2022-present graphqland.

Released under the MIT license