@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()