rapport

A simple websocket wrapper that adds request/response functionality.

Features

• Callback and Promise support for requests
• Wraps node WS objects as well as the browser Websocket object
• Small footprint (7.4kb minified)
• Configurable promise implementation
• Configurable serialization functions
• Zero dependencies

Browser Usage

Simply add rapport.min.js to your HTML page and start using it:

const Rapport = Rapport(Websocket);
const ws = Rapport.create('ws:localhost', wsOptions);

ws.onOpen(() => {
    
    // If the browser supports ES6 promises or a promise library is configured
    ws.request('some request', timeout)
        .then((response) => {})
        .catch((err) => {});
    
    // If you prefer callbacks
    ws.request('some request', timeout, (response, error) => {});
});

// Replying to a request
ws.onMessage((msg, ws) => {
    
    // The message content is in the body
    const content = msg.body;
    
    if (msg.isRequest) {
        ws.respond('hello');
        ws.respondWithError('Error!');
    }
});

// Closes are resolved when onClose is called, with an optional timeout
ws.close(optionalMessage, optionalWsCode, optionalTimeout)
    .then()
    .catch();

// Other functions are also wrapped:
ws.onError((err) => {});
ws.onClose((msg, code) => {});
ws.send(message);

Node.js Usage

Install with npm install --save rapport.

Requesting from clients with an existing socket

const Rapport = require('rapport')();
const wrappedSocket = Rapport.wrap(existingSocket);

wrappedSocket.request('some request', timeout)
    .then((response) => {})
    .catch((err) => {});
    
wrappedSocket.request('some request', timeout, (response, error) => {});

Responding to clients with an existing socket

const Rapport = require('rapport')();
const wrappedSocket = Rapport.wrap(existingSocket);

wrappedSocket.onMessage((msg, ws) => {
    
    // The message content is in the body
    const content = msg.body;
    
    if (msg.isRequest) {   
        ws.respond('Hello');
        ws.respondWithError('Error!');
    }
});

Creating a new client

const Rapport = require('rapport')(require('ws'));
const ws = Rapport.create('ws:localhost', wsOptions);

ws.onOpen(() => {    
    ws.request('some request', timeout)
        .then((response) => {})
        .catch((err) => {});
});

// Replying to a request
ws.onMessage((msg, ws) => {
    
    // The message content is in the body
    const content = msg.body;
    
    if (msg.isRequest) {
        ws.respond('hello');
        ws.respondWithError('Error!');
    }
});

// Closes are resolved when onClose is called, with an optional timeout
ws.close(optionalMessage, optionalWsCode, optionalTimeout)
    .then()
    .catch();

// Other functions are also wrapped:
ws.onError((err) => {});
ws.onClose((msg, code) => {});
ws.send(message);

Configuration Options

There are 6 configurable options for the Rapport library, with the following defaults:

Rapport(Websocket, {
    
    // Set the function for encoding messages
    encodeMessage: (msg) => { return JSON.stringify(msg); },
    
    // Set the function for decoding messages
    decodeMessage: (msg) => { return JSON.parse(msg); },
    
    // Set the function for encoding close messages. This MUST return a string.
    encodeCloseMessage: (msg) => { return JSON.stringify(msg); },
    
    // Set the function for decoding messages. This will always receive a string.
    decodeCloseMessage: (msg) => { return JSON.parse(msg); },
    
    // Set the Promise implementation to use. Set to false to turn off promises.
    Promise: Promise,
    
    // Set the request ID generation function
    generateRequestId: () => { return uuid.v4(); }
});