README.md

channels-api-client

This package aims to provide a simple, reliable, and generic interface to consume channels-api powered WebSocket APIs.

Features

• Promises encapsulating the request/response cycle
• Subscribe to updates with a callback
• Automatically reconnect when connection is broken (with backoff — thanks to reconnecting-websocket)
• Automatically restart subscriptions on reconnection
• Requests are queued until a connection is made (no need to wait for connection before sending requests)

Install

npm install --save @usslc/channels-api

Usage

const channelsApi = require('channels-api');
const client = channelsApi.connect('wss://example.com');

client.create('people', {name: 'Alex'}).then(person => {
  console.info('Created:', person);
});

client.retrieve('people', 4).then(person => {
  console.info('Retrieved person 4:', person);
});

client.update('people', 4, {name: 'Johannes'}).then(person => {
  console.info('Changed name of person 4. Properties after change:', person);
});

client.delete('people', 4).then(() => {
  console.info('Deleted person 4. No one liked them, anyway :)');
});


// Subscribe to updates to any person
const subscription = client.subscribe('people', 'update', person => {
  console.info('A person was updated:', person);
});

// Stop listening for updates
subscription.cancel();


// Subscribe to updates to person 1
const personalSubscription = client.subscribe('people', 'update', 1, person => {
  console.info('Person 1 was updated:', person);
});

// Stop listening
personalSubscription.cancel();


// Make a generic request to a multiplexer stream
client.request('mystream', {key: 'value'}).then(response => {
  console.info('Got mystream response, yo:', response);
});

Configuration

The client can be customized by passing an object as the second argument to connect() or createClient(). The available options are described below.

const client = channelsApi.connect('wss://example.com', {
  preprocessPayload: (stream, payload, requestId) => {
    // Modify payload any way you see fit, before it's sent over the wire
    // For instance, add a custom authentication token:
    payload.token = '123';
    // Be sure not to return anything if you modify payload

    // Or, you can overwrite the payload by returning a new object:
    return {'this': 'is my new payload'};
  },

  preprocessMessage: (message) => {
    // The "message" is the final value which will be serialized and sent over the wire.
    // It includes the stream and the payload.

    // Modify the message any way you see fit, before its sent over the wire.
    message.token = 'abc';
    // Don't return anything if you modify message

    // Or, you can overwrite the the message by returning a new object:
    return {stream: 'creek', payload: 'craycrayload'};
  },

  // Options to be passed to ReconnectingWebsocket
  // See https://github.com/pladaria/reconnecting-websocket#configure for more info
  websocket: {
    constructor: isGlobalWebSocket() ? WebSocket : null,
    maxReconnectionDelay: 10000,
    minReconnectionDelay: 1500,
    reconnectionDelayGrowFactor: 1.3,
    connectionTimeout: 4000,
    maxRetries: Infinity,
    debug: false,
  }
});