Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

subscriptions-transport-ws-dotan

0.3.3 • Public • Published

npm version GitHub license

subscriptions-transport-ws

(Work in progress!)

A GraphQL websocket server and client to facilitate GraphQL subscriptions.

See GitHunt-API and GitHunt-React for an example server and client integration.

Client

Constructor(url, options)

  • url: string : url that the client will connect to
  • options?: Object : optional object to modify default client behavior
    • timeout: number : how long the client should wait in ms for a subscription to be started (default 5000 ms)
    • connectRequestHeaders: Object : object defines the headers for the WebSocket - those will be added to the SUBSCRIPTION_START message and will be available in the server side on onSubscribe

Methods

subscribe(options, handler) => id

  • options: {SubscriptionOptions}
    • query: string : GraphQL subscription
    • variables: Object : GraphQL subscription variables
    • operationName: string : operation name of the subscription
  • handler: (errors: Error[], result?: any) => void : function to handle any errors and results from the subscription response

unsubscribe(id) => void

  • id: string : the subscription ID of the subscription to unsubscribe from

Server

Constructor(options, httpServer)

  • options: {ServerOptions}
    • subscriptionManager: SubscriptionManager : GraphQL subscription manager
    • onSubscribe?: (message: SubscribeMessage, params: SubscriptionOptions, webSocketRequest: WebSocketRequest, headers: HeadersObject) : optional method to create custom params that will be used when resolving this subscription
    • keepAlive?: number : optional interval in ms to send SUBSCRIPTION_KEEPALIVE messages to all clients

Client-server messages

Each message has a type, as well as associated fields depending on the message type.

Client -> Server

SUBSCRIPTION_START

Client sends this message to start a subscription for a query.

  • query: GraphQLDocument : GraphQL subscription
  • variables: Object : GraphQL subscription variables
  • operationName: string : operation name of the subscription
  • id: string : subscription ID

SUBSCRIPTION_END

Client sends this message to end a subscription.

  • id: string : subscription ID of the subscription to be terminated

Server -> Client

SUBSCRIPTION_SUCCESS

The server sends this message to confirm that it has validated the subscription query and is subscribed to the triggers.

  • id: string : ID of the subscription that was successfully set up

SUBSCRIPTION_FAIL

Server sends this message upon failing to register a subscription. It may also send this message at any point during the subscription to notify the client the the subscription has been stopped.

  • errors: Array<Object> : array of errors attributed to the subscription failing on the server
  • id: string : subscription ID of the subscription that failed on the server

SUBSCRIPTION_DATA

GraphQL result sent periodically from server to client according to subscription.

  • payload: GraphQLResult : GraphQL result from running the subscription
  • id: string : subscription ID

SUBSCRIPTION_KEEPALIVE

Server message sent periodically to keep the client connection alive.

Keywords

none

Install

npm i subscriptions-transport-ws-dotan

DownloadsWeekly Downloads

0

Version

0.3.3

License

MIT

Last publish

Collaborators

  • avatar