Relayx-js NPM | npm.io

Relay NodeJS Library

A powerful library for integrating real-time communication into your software stack, powered by the Relay Network.

Features

Real-time communication made easy—connect, publish, and subscribe with minimal effort.
Automatic reconnection built-in, with a 2-minute retry window for network disruptions.
Message persistence during reconnection ensures no data loss when the client reconnects.

Installation

Install the relay library by running the command below in your terminal npm install relayx-js

Usage

Prerequisites

Obtain API key and Secret key

Initialize the library

import { Realtime, CONNECTED, RECONNECT, DISCONNECTED } from "relayx-js"

var realtime = new Realtime({
    api_key: process.env.api_key,
    secret: process.env.secret,
});
realtime.init();

// Initialization of topic listeners go here... (look at examples/example_chat.js for full implementation)

realtime.connect();

// Other application logic...

Usage

Publish Send a message to a topic:

```javascript
var sent = await realtime.publish("power_telemetry", {
    "voltage_V": 5,
    "current_mA": 400,
    "power_W": 2 
});

if(sent){
    console.log("Message was successfully sent to topic => power_telemetry");
}else{
    console.log("Message was not sent to topic => power_telemetry");
}
```

Listen Subscribe to a topic to receive messages:

```javascript
await realtime.on("power_telemetry", (data) => {
    console.log(data);
});
```

Turn Off Listener Unsubscribe from a topic:

```javascript
var unsubscribed = await realtime.off("power_telemetry");

if(unsubscribed){
    console.log("Successfully unsubscribed from power_telemetry");
}else{
    console.log("Unable to unsubscribe from power_telemetry");
}
```

History Get previously published messages between a start date and end date

```javascript
var start = new Date();
var past = start.setDate(start.getDate() - 4) // Get start date from 4 days ago
var startDate = new Date(past)

var end = new Date();
var past = end.setDate(end.getDate() - 2) // Get end date from 2 days ago
var endDate = new Date(past)

var history = await realtime.history(topic, startDate, endDate)
```
The end date is optional. Supplying only the start time will fetch all messages from the start time to now.
```javascript
var start = new Date();
var past = start.setDate(start.getDate() - 4) // Get start date from 4 days ago
var startDate = new Date(past)

// This will get all messages from 4 days ago to now
var history = await realtime.history(topic, startDate)
```

Valid Topic Check Utility function to check if a particular topic is valid

```javascript
var isValid = realtime.isTopicValid("topic");

console.log(`Topic Valid => ${isValid}`);
```

Sleep Utility async function to delay code execution

```javascript
console.log("Starting code execution...");
await realtime.sleep(2000) // arg is in ms
console.log("This line executed after 2 seconds");
```

Close Connection to Relay Manually disconnect from the Relay Network
```
```javascript
// Logic here

realtime.close();
```
```

System Events

CONNECTED This event is fired when the library connects to the Relay Network.

```javascript
await realtime.on(CONNECTED, () => {
    console.log("Connected to the Relay Network!");
});
```

RECONNECT This event is fired when the library reconnects to the Relay Network. This is only fired when the disconnection event is not manual, i.e, disconnection due to network issues.

```javascript
await realtime.on(RECONNECT, (status) => {
    console.log(`Reconnected! => ${status}`);
});
```
`status` can have values of `RECONNECTING` & `RECONNECTED`.

`RECONNECTING` => Reconnection attempts have begun. If `status == RECONNECTING`, the `RECONNECT` event is fired every 1 second.<br>
`RECONNECTED` => Reconnected to the Relay Network.

DISCONNECTED This event is fired when the library disconnects from the Relay Network. This includes disconnection due to network issues as well.
```
```javascript
await realtime.on(DISCONNECTED, () => {
    console.log("Disconnected from the Relay Network");
});
```
```

MESSAGE_RESEND This event is fired when the library resends the messages upon reconnection to the Relay Network.

```javascript
await realtime.on(MESSAGE_RESEND, (messages) => {
    console.log("Offline messages may have been resent");
    console.log("Messages");
    console.log(messages);
});
```
`messages` is an array of the following object,<br>
```json
{
    "topic": "<topic the message belongs to>",
    "message": "<message you sent>",
    "resent": "<boolean, indicating if the message was sent successully>"
}
```

API Reference

init() Initializes library with configuration options
connect() Connects the library to the Relay Network. This is an async function.
close() Disconnects the library from the Relay Network.
on() Subscribes to a topic. This is an async function. @param {string} topic - Name of the event @param {function} func - Callback function to call on user thread * @returns {boolean} - To check if topic subscription was successful
off() Deletes reference to user defined event callback for a topic. This will stop listening to a topic. This is an async function. @param {string} topic @returns {boolean} - To check if topic unsubscribe was successful
history() Get a list of messages published in the past. This is an async function. A list of messages can be obtained using a start time and end time. End time is optional. If end time is not specified, all messages from the start time to now is returned. @param {string} topic @param {Date} start @param {Date} end @returns {JSON Array} - List of messages published in the past
isTopicValid() Checks if a topic can be used to send messages to. @param {string} topic - Name of event @returns {boolean} - If topic is valid or not
sleep() Pauses code execution for a user defined time. Time passed into the method is in milliseconds. This is an async function.