https://github.com/mercurius-js/mercurius-subscription-client
A websocket client for Mercurius subscriptions
https://github.com/mercurius-js/mercurius-subscription-client
graphql mercurius subscriptions websockets
Last synced: 22 days ago
JSON representation
A websocket client for Mercurius subscriptions
- Host: GitHub
- URL: https://github.com/mercurius-js/mercurius-subscription-client
- Owner: mercurius-js
- License: mit
- Created: 2022-12-09T11:45:14.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-09T15:34:52.000Z (8 months ago)
- Last Synced: 2025-04-05T18:52:01.359Z (about 2 months ago)
- Topics: graphql, mercurius, subscriptions, websockets
- Language: JavaScript
- Homepage:
- Size: 49.8 KB
- Stars: 2
- Watchers: 2
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# @mercuriusjs/subscription-client
A websocket client for [Mercurius subscriptions](https://github.com/mercurius-js/mercurius/blob/master/docs/subscriptions.md).
## Quick start
```javascript
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` 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` A callback that is executed when the client is successfully connected to the server.
- `failedConnectionCallback`: `(params: any) : Promise` A callback that is executed when the client fails connecting to the server.
- `failedReconnectCallback`: `(params: any) : Promise` 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:
```cjs
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()
```