urltm.js

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 16)

Universal API for any realtime service

urltm.js Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![](https://raw.githubusercontent.com/universal-realtime/urltm.js/master/assets/urltm.js-logo.png)

Universal API for realtime services. Integrate once and easily switch between Socket.io, Ably and PubNub. We hope to add support for more realtime services and platforms in future.

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

Supported realtime services:

![https://www.ably.io/](https://raw.githubusercontent.com/universal-realtime/urltm.js/master/assets/ably.png)

![](https://raw.githubusercontent.com/universal-realtime/urltm.js/master/assets/socketio.png)

![](https://raw.githubusercontent.com/universal-realtime/urltm.js/master/assets/pubnub.png)

## Background

This project was initially created by PubNub. However, due to a licensing constraint added by PubNub prohibiting the universal API supporting any commercial realtime projects, this project was forked and adopts the original Mozilla free and open source license. Read [the blog post about the launch of urltm.js](https://blog.ably.io/relaunching-the-universal-api-for-realtime-ab36ed749378)

# Setup

## NPM

Install via NPM.

```sh
npm install urltm --save
```

Include library via require.

```js
const urltm = require('urltm');
```

## Web

Install via bower or NPM

```sh
npm install urltm --save
bower install urltm --save
```

Include library in HTML.

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

# Configure

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

```js
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](/guides/socketio.md)

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](/guides/pubnub.md)

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

#### [Set Up With Ably](/guides/ably.md)

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```
1. ```state``` - data associated with this ```user```

You can provide these as parameters during initialization.

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

## Rooms

Realtime communication happens over ```room```s. ```room```s 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. ```user```s who provide the same  identifier will be able to communicate with each other.

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

This returns a ```room``` object which we can use to communicate with other ```user```s.

### Join Event

A room can subscribe to the ```join``` event to find out when other ```user```s join the room.

```js
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.

```js
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.

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

## Online Users

### Here Now

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

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

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

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

### Leave Event

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

```js
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.

```js
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.

```js
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.

```js
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```.

```js
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.

```js
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.

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

## Test

Tests are run with mocha and chai.

```sh
npm install mocha -g
npm install chai -g
```

Set environment variable ```CLIENT``` to test each service.

```sh
env CLIENT=ably mocha
```

```sh
env CLIENT=pubnub mocha
```

```sh
env CLIENT=socketio mocha
```

urltm.js

urltm.js Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

urltm.js

urltm.js Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README