Skip to content

mercurius-js/mercurius-subscription-client

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

36 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@mercuriusjs/subscription-client

A websocket client for Mercurius subscriptions.

Quick start

npm i @mercuriusjs/subscription-client

SubscriptionClient

SubscriptionClient: class extends EventEmitter

  • The SubscriptionClient class constructor takes two parameters:

    • uri: string The uri of the websocket server.
    • config: object the configuration object.
      • protocols: Array<string> The WebSocket sub-protocol. default: graphql-transport-ws.
      • reconnect: boolean Enables the client to attempt to reconnect if the connection is interrupted. default: false.
      • maxReconnectAttempts: number The maximum amount of attempts the client should perform when reconnecting. default: Infinity.
      • serviceName: string The service name.
      • connectionCallback: (params: any) : Promise<void> A callback that is executed when the client is successfully connected to the server.
      • failedConnectionCallback: (params: any) : Promise<void> A callback that is executed when the client fails connecting to the server.
      • failedReconnectCallback: (params: any) : Promise<void> A callback that is executed when the client fails reconnecting to the server.
      • connectionInitPayload: any The connection init payload or a function that returns it.
      • rewriteConnectionInitPayload: (connectionInit, context) => void A function that allows to rewrite the default connection init payload.
      • keepAlive: number The milliseconds value of the connection keep-alive interval. default: false
  • subscriptionClient.connect() : void Creates a connection to the server.

  • subscriptionClient.close(tryReconnect, closedByUser?) : void Closes the connection to the server.

  • unsubscribe(operationId, forceUnsubscribe) : void Unsuscribes from the topic with the provided operationId.

  • subscriptionClient.unsubscribeAll() : void Unsuscribes from all topics.

  • subscriptionClient.createSubscription(query, variables, publish, context) : string. Creates a subscription to a query. Returns the SubscriptionOperationId

SubscriptionClient extends EventEmitter class from node:events, and it is possibile add listeners to the following events:

  • SocketOpen Emits when the connection is open.
  • ready Emits when the connection_ack is received and it is ready to communicate.
  • SocketError Emits when an error occurred.
  • SocketClose Emits when the socket is closed.

Examples:

const { SubscriptionClient } = require( "@mercuriusjs/subscription-client")
const { once } = require('events') 

const client = new SubscriptionClient('ws://localhost:3000', {
  protocols: ["graphql-transport-ws"],
  reconnect: true,
  maxReconnectAttempts: 10,
  serviceName: "test-service",
  connectionCallback: () => {
    // executes callback on connection
  },
  failedConnectionCallback: (err) => {
    // executes callback on connection error
  },
  failedReconnectCallback: () => {
    // executes callback on reconnection error
  },
  connectionInitPayload: 'foo', // connection payload
  rewriteConnectionInitPayload: (connectionInit, context) => {
    // rewrite the connection init payload
  },
  keepAlive: 1000
});

client.connect()

await once(client, 'ready')

const operationId1 = client.createSubscription('query', {}, (data)=> {
  // data returned from the query
})

client.unsubscribe(operationId1)

const operationId2 = client.createSubscription('query', {}, (data)=> {
  // data returned from the query
})

client.unsuscribeAll()

client.close()