@mercuriusjs/subscription-client

A websocket client for Mercurius subscriptions.

Quick start

1npm 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:

1const { SubscriptionClient } = require( "@mercuriusjs/subscription-client")
2const { once } = require('events') 
3
4const client = new SubscriptionClient('ws://localhost:3000', {
5  protocols: ["graphql-transport-ws"],
6  reconnect: true,
7  maxReconnectAttempts: 10,
8  serviceName: "test-service",
9  connectionCallback: () => {
10    // executes callback on connection
11  },
12  failedConnectionCallback: (err) => {
13    // executes callback on connection error
14  },
15  failedReconnectCallback: () => {
16    // executes callback on reconnection error
17  },
18  connectionInitPayload: 'foo', // connection payload
19  rewriteConnectionInitPayload: (connectionInit, context) => {
20    // rewrite the connection init payload
21  },
22  keepAlive: 1000
23});
24
25client.connect()
26
27await once(client, 'ready')
28
29const operationId1 = client.createSubscription('query', {}, (data)=> {
30  // data returned from the query
31})
32
33client.unsubscribe(operationId1)
34
35const operationId2 = client.createSubscription('query', {}, (data)=> {
36  // data returned from the query
37})
38
39client.unsuscribeAll()
40
41client.close()