@testmail.app/graphql-request

Clone of graphql-request (minimal GraphQL client) with improvements like built-in retries.

Highlights

• Simple and lightweight GraphQL client with a promise-based API (works with async / await) and typescript support
• API compatible with graphql-request (no breaking changes; drop-in replacement)
• Configurable retries (see docs below)

Install

1npm install @testmail.app/graphql-request

Quickstart

1import { request } from '@testmail.app/graphql-request'
2
3const query = `{
4  Movie(title: "Inception") {
5    releaseDate
6    actors {
7      name
8    }
9  }
10}`;
11
12request('https://api.graph.cool/simple/v1/movies', query).then(data =>
13  console.log(data)
14);

Usage (with retries)

1import { request, GraphQLClient } from '@testmail.app/graphql-request'
2
3// Run GraphQL queries/mutations using a static function
4request(endpoint, query, variables).then(data => console.log(data));
5
6// ... or create a GraphQL client instance to send requests
7const client = new GraphQLClient(endpoint, { headers: {} });
8client.request(query, variables).then(data => console.log(data));
9
10// This is the default retry policy:
11const client = new GraphQLClient(endpoint, {
12  retries: 9,
13  retryDelay: function (attempt) {
14    // Exponential backoff: 1s, 2s, 4s, etc. upto 40s (max)
15    return Math.min(Math.pow(2, attempt) * 1000, 40000);
16  },
17  retryOn: [500, 502, 503, 504] // response status codes to retry on
18  // network connection errors are always retried
19});

To override the default retry policy, replace any of those three arguments: retries, retryDelay, and retryOn.

The options object (2nd argument to GraphQLClient constructor) passes along any additional parameters to fetch - so you can easily configure the underlying fetch API :)

Examples

Authentication via HTTP header

1import { GraphQLClient } from '@testmail.app/graphql-request'
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const graphQLClient = new GraphQLClient(endpoint, {
7    headers: {
8      authorization: 'Bearer MY_TOKEN',
9    },
10  })
11
12  const query = /* GraphQL */ `
13    {
14      Movie(title: "Inception") {
15        releaseDate
16        actors {
17          name
18        }
19      }
20    }
21  `
22
23  const data = await graphQLClient.request(query)
24  console.log(JSON.stringify(data, undefined, 2))
25}
26
27main().catch(error => console.error(error))

Passing more options to fetch

1import { GraphQLClient } from '@testmail.app/graphql-request'
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const graphQLClient = new GraphQLClient(endpoint, {
7    credentials: 'include',
8    mode: 'cors',
9  })
10
11  const query = /* GraphQL */ `
12    {
13      Movie(title: "Inception") {
14        releaseDate
15        actors {
16          name
17        }
18      }
19    }
20  `
21
22  const data = await graphQLClient.request(query)
23  console.log(JSON.stringify(data, undefined, 2))
24}
25
26main().catch(error => console.error(error))

Using variables

1import { request } from '@testmail.app/graphql-request'
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const query = /* GraphQL */ `
7    query getMovie($title: String!) {
8      Movie(title: $title) {
9        releaseDate
10        actors {
11          name
12        }
13      }
14    }
15  `
16
17  const variables = {
18    title: 'Inception',
19  }
20
21  const data = await request(endpoint, query, variables)
22  console.log(JSON.stringify(data, undefined, 2))
23}
24
25main().catch(error => console.error(error))

Error handling

1import { request } from '@testmail.app/graphql-request'
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const query = /* GraphQL */ `
7    {
8      Movie(title: "Inception") {
9        releaseDate
10        actors {
11          fullname # "Cannot query field 'fullname' on type 'Actor'. Did you mean 'name'?"
12        }
13      }
14    }
15  `
16
17  try {
18    const data = await request(endpoint, query)
19    console.log(JSON.stringify(data, undefined, 2))
20  } catch (error) {
21    console.error(JSON.stringify(error, undefined, 2))
22    process.exit(1)
23  }
24}
25
26main().catch(error => console.error(error))

Using require instead of import

1const { request } = require('graphql-request')
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const query = /* GraphQL */ `
7    {
8      Movie(title: "Inception") {
9        releaseDate
10        actors {
11          name
12        }
13      }
14    }
15  `
16
17  const data = await request(endpoint, query)
18  console.log(JSON.stringify(data, undefined, 2))
19}
20
21main().catch(error => console.error(error))

Receiving a raw response

The request method will return the data or errors key from the response. If you need to access the extensions key you can use the rawRequest method:

1import { rawRequest } from '@testmail.app/graphql-request'
2
3async function main() {
4  const endpoint = 'https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr'
5
6  const query = /* GraphQL */ `
7    {
8      Movie(title: "Inception") {
9        releaseDate
10        actors {
11          name
12        }
13      }
14    }
15  `
16
17  const { data, errors, extensions, headers, status } = await rawRequest(
18    endpoint,
19    query
20  )
21  console.log(
22    JSON.stringify({ data, errors, extensions, headers, status }, undefined, 2)
23  )
24}
25
26main().catch(error => console.error(error))