Have ideas to improve npm?Join in the discussion! »

    urltm

    1.4.0 • Public • Published

    Universal API for realtime services. Integrate once and easily switch between Socket.io, Ably and PubNub.

    Provides handy methods for rooms, users, message history, and information about connected user.

    Supported realtime services:

    https://www.ably.io/

    Setup

    NPM

    Install via NPM.

    npm install urltm --save

    Include library via require.

    const urltm = require('urltm');

    Web

    Install via bower or NPM

    npm install urltm --save
    bower install urltm --save

    Include library in HTML.

    <script src="./bower_components/web/urltm.js"></script>

    Configure

    Both the NodeJS and web libraries are configured with the urltm variable.

    let user = urltm({
        service: 'pubnub',
        config: {
            // ...
        }
    });
    • service is the name of the realtime service to use (ably, pubnub or socketio)
    • config is a Javascript object with a config for that service.

    PubNub or Socket.io

    Set Up With Socket.io

    Socket.io is an open source websocket framework. To use socket.io, you'll run your own socket.io server on the back end.

    Set Up With PubNub

    PubNub is a hosted realtime solution that doesn't require you to run or maintain any servers.

    Set Up With Ably

    Ably is a hosted realtime solution that doesn't require you to run or maintain any servers.

    Usage

    Users

    Every user connected to urltm.js has two properties:

    1. uuid - a unique way to identify this user
    2. state - data associated with this user

    You can provide these as parameters during initialization.

    let user = urltm({
        service: 'socketio',
        config: {
            endpoint: 'http://localhost:9000',
            uuid: 'MY_UNIQUE_ID',
            state: {admin: true}
        }
    });

    Rooms

    Realtime communication happens over rooms. rooms are like chat rooms, everybody in a room receives events sent by every other user.

    A user can join a room by using the join() method and supplying a room identifier. users who provide the same identifier will be able to communicate with each other.

    room = user.join('room-name');

    This returns a room object which we can use to communicate with other users.

    Join Event

    A room can subscribe to the join event to find out when other users join the room.

    room.on('join', (uuid, state) => {
        console.log('user with uuid', uuid, 'joined with state', state);
    });

    Messages

    Message Event

    When another user sends a message to the room, it will trigger the message event. The room can subscribe to that event with the on() method.

    room.on('message', (uuid, data) => {
        console.log('message received from uuid', uuid, 'with data', data);
    });

    Publish

    To send a message to the entire room, use the message() method. Returns a promise.

    room.message({hello: world}).then(() => {
        console.log('message published');
    });

    Online Users

    Here Now

    A room can get a list of other users who have in the room by using the here() method. Returns a promise.

    room.here().then((users) => {
        console.log('users online', users);
    });

    Successful responses will return a object of users who are currently connected to the room. The keys are the user's uuids and the values are their current state.

    {
        uuid1: {
            username: 'ianjennings'
        },
        uuid2: {
            username: 'stephenblum'
        }
    }

    Leave Event

    A room can subscribe to the leave event to find out when a user leaves.

    room.on('leave', (uuid) => {
        console.log('user with uuid', uuid, 'has left');
    });

    A user can manually leave a room by using the leave() method. Returns a promise.

    room.leave().then(() => {
        console.log('left the room.');
    });

    This will fire the leave event.

    Disconnect

    If a user gets disconnected without leaving the room, the disconnect event will fire.

    room.on('disconnect', (uuid) => {
        console.log('user with uuid', uuid, 'has disconnected');
    });

    Set User State

    A user state can be updated at any time by using the state() method. Supply the new state as the only parameter. Return a promise.

    room.state({idle: true}).then(() => {
        console.log('state set');
    });

    This will fire the state event which you can subscribe to with the room.on() method. When fired you will get the uuid of the user and the new state.

    room.on('state', (uuid, state) => {
        console.log('user with uuid', uuid, 'was given state', state);
    });

    Get Old Messages

    A user can retrieve previously published messages in the room by using the history() method. Returns a promise.

    room.history().then((history) => {
        console.log('got array of all messages in channel', history);
    });

    It will return the last 100 messages as an array of objects containing the uuid and data of every message. The array is sorted newest to oldest.

    [
        {
            uuid: uuid2,
            data: {
                sentTime: '2pm',
                text: 'boy howdy'
            }
        },
        {
            uuid: uuid1,
            data: {
                sentTime: '1pm',
                text: 'hello there'
            }
        }
    ]

    Test

    Tests are run with mocha and chai.

    npm install mocha -g
    npm install chai -g

    Set environment variable CLIENT to test each service.

    env CLIENT=ably mocha
    env CLIENT=pubnub mocha
    env CLIENT=socketio mocha

    Install

    npm i urltm

    DownloadsWeekly Downloads

    0

    Version

    1.4.0

    License

    MIT

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar