graphql-react-subscription v0.1.7

graphql-react-subscription

A GraphQL subscription client for graphql-react.

Inspired by graphql-subscriptions

Work in progress!

Koa server coming soon ...

API

Table of Contents

• GraphQLSocket
  • subscribe
• Consumer
• GraphQLSubscribe
• MessageTypes
• Provider
• Subscribe
• SubscribeRender

GraphQLSocket

GraphQLSocket manages the websocket connections.

Parameters

• wsTimeout number? specify the ws timeout duration. (optional, default Infinity)
• websocket Object? Websocket instance

Examples

import { GraphQLSocket } from 'react-graphql-subscription'

const graphqlSocket = new GraphQLSocket()

subscribe

Handles subscriptions.

Parameters

• url string The ws url.
• query string The GraphQL subscription query.
• variables string query variables.
• keyId number The key Id for the callback listener. (optional, default 0)
• callback function callback listener.

Consumer

A React component that gets the GraphQLSocket instance from the React context provided by the Provider.

Parameters

• children ConsumerRender Render function that receives a GraphQLSocket instance.

Examples

Subscribe component makes use of the GraphQLSocket instance passed via react context..

import { Consumer } from 'graphql-react'

const Subscribe = props => (
  <Consumer>
    {graphqlSocket => (
      <GraphQLSubscribe graphqlSocket={graphqlSocket} {...props} />
    )}
  </Consumer>
)

Returns ReactElement React virtual DOM element.

GraphQLSubscribe

Extends React.Component

A React component that requests subscription data.

Parameters

• props Object Component props.
  • props.graphqlSocket GraphQLSocket GraphQLSocket instance.
  • props.query string GraphQL subscription query.
  • props.url string Websocket server url.
  • props.keyId number? For identical duplicate subscribe components.
  • props.subscribeOnMount boolean should componenet subscribe on mount.
  • props.children RenderQuery Renders the subscription result.

MessageTypes

The WebSocket Client and server communication messages.

Properties

• GQL_CONNECTION_INIT string Client to server string to initialize connection.
• GQL_CONNECTION_ACK string The server response indicationg the websocket connection has been acknowledged.
• GQL_CONNECTION_ERROR string A server connection error response.
• GQL_CONNECTION_KEEP_ALIVE string Hearbeat of the ws subscription.
• GQL_CONNECTION_TERMINATE string Client request to terminate the WebSocket connection.
• GQL_START string Client request to start listening to a GraphQL subscription operation.
• GQL_DATA string Server response with data.
• GQL_ERROR string Server GraphQL Error response.
• GQL_COMPLETE string Server response indicating GraphQL subscription operation is complete.
• GQL_STOP string Client request stop listening to a subscription operation.

Provider

A React component provides a GraphQLSocket instance via React context for nested Consumer components to use.

Parameters

• value GraphQLSocket A GraphQLSocket instance.
• children ReactNode A React node.

Examples

import { GraphQLSocket, Provider } from 'graphql-react-subscription'

const graphqlSocket = new GraphQLSocket()

const Page = () => (
  <Provider value={graphqlSocket}>
    Use Consumer or Subscribe components…
  </Provider>
)

Returns ReactElement React virtual DOM element.

Subscribe

A React component to manage a GraphQL subscription.

Parameters

• props Object Component props.
  • props.url string websocket url.
  • props.query string GraphQL subscription query.
  • props.subscribeOnMount boolean Should the subscription open when the component mounts. (optional, default false)
  • props.keyId number? Use if there are identical duplicate subscribe components.
  • props.children SubscribeRender Renders the Subscribe status.

Examples

A subscription to listen for messages.

import { Subscribe } from 'graphql-react-subscription'

const Notification = () => (
  <Subscribe
    url={'ws://localhost:3000/subscribe'}
    query={`subscription {
             messages {
                 id
                 from
                 message
             }
         }`}
  >
    {({ subscribe, parseError, data, readyState }) => (
      <>
        {parseError && <strong>Error</strong>}
        <ul>
          {data.forEach(({ id, message, from }) => (
            <li key={id}>
              {from}: {message}
            </li>
          ))}
        </ul>
      </>
    )}
  </Subscribe>
)

Returns ReactElement React virtual DOM element.

SubscribeRender

Renders the status of a Subscription.

Type: function

Parameters

• subscribe function Connects a subscription on demand.
• parseError string? Parse error message.
• data object? GraphQL response data.
• readyState number? The ws readyState.

Examples

;({ subscribe, parseError, data, readyState }) => (
  <aside>
    <button onClick={subscribe}>connect</button>
    {parseError && <strong>Error!</strong>}
    {data && <h1>{data.user.name}</h1>}
  </aside>
)

Returns ReactElement React virtual DOM element.