@karjala/foo123-boardstreams NPM

BOARDSTREAMS

Desciption

A simple-to-use client library to build realtime features on your websites.

Part of the boardstreams client/server suite.

Features

multiple channels to send messages (events) through, over the same websocket connection
- broadcast channels, where all users receive the same events
- private channels for only one user
channels can have a shared state object, identical for all users
reconnections are handled transparently:
- messages missed during a disconnection will eventually reach the user upon their reconnection
- the state object is refreshed on the browser upon reconnection
easily configure a channel's authorization routine in your own server's programming language
the server-side library is available for a variety of frameworks and programming languages

Installation

Webpack:

$ npm i boardstreams@~0.1

...and then in your code:

import BoardStreams from 'boardstreams';

CDN:

<script src="https://unpkg.com/boardstreams@~0.1"></script>

Usage:

In your browser code:

/* connect and automatically reconnect to the websocket server */
let BS = new BoardStreams('ws://example.com/ws');

/* or if on the same host, just */
let BS = new BoardStreams('/ws');

Receiving and processing data from the server:

Properties ending in '$' are RxJS observables:

/* let the server know you want to start receiving data from some channels */
let channel1 = BS.joinChannel('my_channel_name');
let channel2 = BS.joinChannel('another_channel_name');

/* handle incoming data */
channel1.state$.subscribe(state => console.log(state));
channel1.events$.subscribe(event => console.log(event));

You will receive the shared state object through channel.state$ upon connection (and also upon reconnection), if the channel is configured for that on the server.

You will receive an event whenever the server decides to send one to everybody in that channel.

The data types of events & state can be any JSON-compatible value. They will not come out of order, which means you can use the incoming events to update your local state object appropriately and keep it in sync with the other users of the channel.

You should subscribe to state$, events$ immediately after calling joinChannel to avoid missing any incoming data.

In channels for which the server does not send a state (as in a chatroom's message board), when you reconnect to the websocket server after temporary network problem you will receive all the events you missed while offline (up to a limit defined by the server).

Sending actions to the server:

channel1.send('some_action_name');
channel1.send('another_action_name', payload);

These actions will not be sent to the other users of the channel (unless the server decides to act upon them and send an event).

Private channels:

If the server has associated a unique sid value with your connection, then channels containing the $sid substring are private.

E.g.:

/* only you will be receiving events from this channel */
let myNotificationsChannel = BS.joinChannel('notifications:$sid');

/* show the notifications */
myNotificationsChannel.events$.subscribe(message => alert(message));

Any substring that starts with $ may be used instead of $sid (such as $user_id).