OneGraph Subscriptions Transport over Websockets

This library is a light wrapper over subscriptions-transport-ws that provides the required configuration to use subscriptions with OneGraph.

Installation

With yarn:

yarn add onegraph-subscription-client

With npm:

npm install --save onegraph-subscription-client

Usage

import {SubscriptionClient} from 'onegraph-subscription-client';

const ONEGRAPH_APP_ID = 'YOUR_APP_ID';

const client = new SubscriptionClient(ONEGRAPH_APP_ID);

client
  .request({
    query: /* GraphQL */ `
      subscription NpmPackagesSubscription {
        npm {
          allPublishActivity {
            package {
              name
            }
          }
        }
      }
    `,
    operationName: 'NpmPackagesSubscription',
  })
  .subscribe(
    next => {
      const npmPackage = next.data.npm.allPublishActivity.package;
      console.log(npmPackage);
    },
    error => console.error(error),
    () => console.log('done'),
  );

With OneGraphAuth

import {SubscriptionClient} from 'onegraph-subscription-client';
import {OneGraphAuth} from 'onegraph-auth';

const ONEGRAPH_APP_ID = 'YOUR_APP_ID';

const auth = new OneGraphAuth(ONEGRAPH_APP_ID);

const client = new SubscriptionClient(ONEGRAPH_APP_ID, {oneGraphAuth: auth});

With Apollo Client

import {SubscriptionClient} from 'onegraph-subscription-client';
import {ApolloClient} from 'apollo-client';
import {InMemoryCache} from 'apollo-cache-inmemory';

const ONEGRAPH_APP_ID = 'YOUR_APP_ID';

const subscriptionClient = new SubscriptionClient(ONEGRAPH_APP_ID);

const apolloClient = new ApolloClient({
  link: subscriptionClient,
  cache: new InMemoryCache(),
});

API Docs

SubscriptionClient

Constructor(url, options, webSocketImpl)

• appId: string : Your OneGraph AppId
• options?: Object : optional, object to modify default client behavior
  • oneGraphAuth?: OneGraphAuth : the OneGraphAuth instance that this subscription should use to authenticate requests
  • timeout?: number : how long the client should wait in ms for a keep-alive message from the server (default 30000 ms), this parameter is ignored if the server does not send keep-alive messages. This will also be used to calculate the max connection time per connect/reconnect
  • lazy?: boolean : use to set lazy mode - connects only when first subscription created, and delay the socket initialization
  • reconnect?: boolean : automatic reconnect in case of connection error
  • reconnectionAttempts?: number : how much reconnect attempts
  • connectionCallback?: (error) => {} : optional, callback that called after the first init message, with the error (if there is one)
  • inactivityTimeout?: number : how long the client should wait in ms, when there are no active subscriptions, before disconnecting from the server. Set to 0 to disable this behavior. (default 0)
• webSocketImpl?: Object - optional, constructor for W3C compliant WebSocket implementation. Use this when your environment does not have a built-in native WebSocket (for example, with NodeJS client)

Methods

request(options) => Observable<ExecutionResult>: returns observable to execute the operation.

• options: {OperationOptions}
  • query: string : GraphQL subscription
  • variables: Object : GraphQL subscription variables
  • operationName: string : operation name of the subscription
  • context: Object : use to override context for a specific call

unsubscribeAll() => void - unsubscribes from all active subscriptions.

on(eventName, callback, thisContext) => Function

• eventName: string: the name of the event, available events are: connecting, connected, reconnecting, reconnected, disconnected and error
• callback: Function: function to be called when websocket connects and initialized.
• thisContext: any: this context to use when calling the callback function.
• => Returns an off method to cancel the event subscription.

onConnected(callback, thisContext) => Function - shorthand for .on('connected', ...)

• callback: Function: function to be called when websocket connects and initialized, after ACK message returned from the server
• thisContext: any: this context to use when calling the callback function.
• => Returns an off method to cancel the event subscription.

onReconnected(callback, thisContext) => Function - shorthand for .on('reconnected', ...)

• callback: Function: function to be called when websocket reconnects and initialized, after ACK message returned from the server
• thisContext: any: this context to use when calling the callback function.
• => Returns an off method to cancel the event subscription.

onConnecting(callback, thisContext) => Function - shorthand for .on('connecting', ...)

• callback: Function: function to be called when websocket starts it's connection
• thisContext: any: this context to use when calling the callback function.
• => Returns an off method to cancel the event subscription.

onReconnecting(callback, thisContext) => Function - shorthand for .on('reconnecting', ...)

• callback: Function: function to be called when websocket starts it's reconnection
• thisContext: any: this context to use when calling the callback function.
• => Returns an off method to cancel the event subscription.

onDisconnected(callback, thisContext) => Function - shorthand for .on('disconnected', ...)

• callback: Function: function to be called when websocket disconnected.
• thisContext: any: this context to use when calling the callback function.
• => Returns an off method to cancel the event subscription.

onError(callback, thisContext) => Function - shorthand for .on('error', ...)

• callback: Function: function to be called when an error occurs.
• thisContext: any: this context to use when calling the callback function.
• => Returns an off method to cancel the event subscription.

close() => void - closes the WebSocket connection manually, and ignores reconnect logic if it was set to true.

use(middlewares: MiddlewareInterface[]) => SubscriptionClient - adds middleware to modify OperationOptions per each request

• middlewares: MiddlewareInterface[] - Array contains list of middlewares (implemented applyMiddleware method) implementation, the SubscriptionClient will use the middlewares to modify OperationOptions for every operation

status: number : returns the current socket's readyState