primus-graphql
Primus-GraphQL is a flexible client and server library that can be used to power realtime GraphQL applications. It is similar to Express-GraphQL but with support for Relay and Subscriptions!
This module is a Primus plugin. Primus is a robust realtime abstraction layer that allows you to use WebSockets, Socket.io, Engine.io, SockJS, or any transport-layer. Primus powers sending and receiving data on both the client and the server. Primus-GraphQL makes it easy to send and handle GraphQL queries, mutations, and subscriptions.
Installation
npm i --save primus-graphqlnpm i --save rxjs # peer dependency (server/client) npm i --save graphql # peer dependency (server) npm i --save relay-runtime # optional peer dependency (if using relay in client)
Usage
GraphQL Example
Server Example:
const UserType = name: 'User' description: 'user' fields: id: type: GraphQLString name: type: GraphQLString const Query = name: 'Query' description: 'Root query' fields: user: type: UserType args: {} { return id: 1 name: 'name' } const schema = query: Query const server = /* your http server */const primus = server transport: /* transport */ parser: 'json' primus
Client Example:
const client = const query = 'query { user { id, name } }'// promise apiclient// callback apiclient
Server Options
The primusGraphQL
plugin function accepts the following options:
-
schema
: AGraphQLSchema
instance from [graphql-js
][]. Aschema
must be provided. -
context
: Optional. A value to pass as thecontext
to thegraphql()
function from [graphql-js
][]. If a function is used it will be invoke w/spark
, and must return thecontext
. -
rootValue
: Optional. A value to pass as therootValue
to thegraphql()
function from [graphql-js
][]. If a function is used it will be invoke w/spark
, and must return therootValue
. -
formatError
: Optional. An optional function which will be used to format any errors produced by fulfilling a GraphQL operation. If no function is provided, GraphQL's default spec-compliant [formatError
][] function will be used. -
validationRules
: Optional. Additional validation rules queries must satisfy in addition to those defined by the GraphQL spec.
Relay
Relay Network Options
The PrimusRelayNetwork
class accepts the following options:
timeout
: The max timeout for any graphql query or mutation.retry
: Exponential backoff settings for retryable query, mutation, or subscription errors.retry.maxTimeout
: The max timeout to wait before retrying.retry.minTimeout
: The min timeout to wait before retrying.retry.factor
: The factor in which to increase the retry timeout.retry.retries
: The max number of retries to attempt.
Subscriptions
If primus disconnects and reconnects, any graphql subscriptions that were not disposed will resend the same query and resume. If this behavior is undesired dispose the subscription on primus 'disconnect'.
Relay Example
;; const primus = const network = primus // default options: timeout: 15000 retry: minTimeout: 1000 maxTimeout: 3000 factor: 3 retries: 2 const environment = network: network store: ; ReactDOM
Full query, mutation, and subscriptions examples
Check out the end-to-end tests here: browser_tests/primus-graphql.e2e.js
Changelog
Thank you
Thank you to the contributors of Primus, GraphQL, and Relay!
License
MIT