README

@barejs/graphql-client

This is a collection of GraphQL clients which support queries, mutations and subscriptions.

It specifically targets the bareASGI GraphQL module from the bareASGI python web framework. This framework provides two novel features.

Server side identification of subscriptions (by returning a 201 if the query was a subscription),
Multiple subscription transports (WebSocket, EventSource (server sent events), and fetch with ReadableStream.

Because the ReadableStream api is a feature of fetch, it can provide headers to the server, allowing CORS and authentication to be maintained. This is a relatively new feature; in particular the pipeThrough and pipeTo methods (which are used by the client) are still marked as "experimental". At the time of writing this is supported by most common browsers with the notable exception of FireFox (and Internet Explorer, obviously).

Usage

Queries and mutations

The graphqlFetchClient function is a thin wrapper around fetch. It can be used for queries and mutations.

import { graphqlFetchClient } from '@barejs/graphql-client'

const url = 'http://www.example.com/graphql'
const init {}

const query = 'query { someQuery { someField someOtherField } }'
const variables = null
const operationName = null

graphqlFetchClient(
  url,
  init,
  query,
  variables,
  operationName,
  error => console.error(error),
  data => console.log(data))

Subscriptions

The graphqlWsSubscriber can be used for subscriptions.

import { graphqlWsSubscriber } from '@barejs/graphql-client'

const url = 'http://www.example.com/sse-subscription'
const init = {}

const query = 'subscription { someSubscription { someField someOtherField } }'
const variables = null
const operationName = null

graphqlWsSubscriber(
  url,
  init,
  query,
  variables,
  operationName,
  error => console.error(error),
  data => console.log(data))

Queries, Mutations and Subscriptions

The graphqlWsClient can be used for queries, mutations, or subscriptions when using the bareASGI-graphql-next server server, using web sockets as the underlying subscription transport.

import { graphqlWsClient } from '@barejs/graphql-client'

const url = 'http://www.example.com/graphql'
const init = {}

// This could be a query, mutation or subscription.
const query = 'subscription { someSubscription { someField someOtherField } }'
const variables = null
const operationName = null

const unsubscribe = graphqlWsClient(
  url,
  init,
  query,
  variables,
  operationName,
  data => console.log(data),
  error => console.log(error),
  () => console.log('complete'))

// Later ...
unsubscribe()

There are three client functions:

graphqlWsClient
graphqlEventSourceClient
graphqlStreamClient

They take the same arguments as graphqlWsClient.

graphqlWsClient

The graphqlWsClient function uses a WebSocket as the subscription transport. This implements the appolo protocol which is supported by all major GraphQL web servers.

graphqlEventSourceClient

The graphqlEventSourceClient function uses an EventSource as the subscription transport. It is more efficient than the WebSocket transport, but is only supported by the bareASGI-graphql-next server server. The underlying EventSource transport requires the subscription query and parameters to be passed in the url as a query string which can be problematic for large queries.

graphqlStreamClient

The graphqlStreamClient uses a streaming fetch with ReadableStreams as the subscription transport. This is the most efficient transport, but is only supported by the bareASGI-graphql-next server server. The request method is POST so large queries are not a problem.

Installation

npm install @barejs/graphql-client

Usage no npm install needed!