eventhub-jsclient

eventhub-jsclient is a JavaScript client library for Eventhub. It enables you to easily subscribe and publish to a eventhub server from the browser or Node.js.

Installation

$ npm i --save eventhub-jsclient

Or, if you're oldschool:

$ wget -a scripts/eventhub-jsclient.js https://unpkg.com/eventhub-jsclient/dist/eventhub.umd.js

Or as a module directly from unpkg:

<script src="https://unpkg.com/eventhub-jsclient/dist/eventhub.umd.js" defer></script>
<!-- or -->
<script type="module">
    import Eventhub from 'https://unpkg.com/eventhub-jsclient/dist/eventhub.modern.js?module';
    const evClient = new Eventhub("ws://myeventhubserver.com", "myAuthToken");
</script>

Examples

Look in the examples directory for more examples.

Subscribe to a topic

const Eventhub = require('eventhub-jsclient');
const evClient = new Eventhub("ws://myeventhubserver.com", "myAuthToken");

evClient.connect().then(res => {
	evClient.subscribe("my/topic", function (msg) {
		console.log(`Topic: ${msg.topic}: Message ID: ${msg.id} Message: ${msg.message}`);
	});
}).catch(err => {
	console.log(`Error connecting to Eventhub: ${err}`);
});

Subscribe to a topic and get all historical (cached) events since a given point in time

const Eventhub = require('eventhub-jsclient');
const evClient = new Eventhub("ws://myeventhubserver.com", "myAuthToken");

evClient.connect().then(res => {
	evClient.subscribe("my/topic", function (msg) {
		console.log(`Topic: ${msg.topic}: Message ID: ${msg.id} Message: ${msg.message}`);
	}, {
		since: 1572811274719, // Return all cached events since timestamp specified in milliseconds.
		limit: 100 // Limit the amount of returned historical events to 100.
	);
}).catch(err => {
	console.log(`Error connecting to Eventhub: ${err}`);
});

You can also get all cached events since a given event id using the sinceEventId: <eventid> option instead of since: <timestamp>.

Publish to a topic

const Eventhub = require('eventhub-jsclient');
const evClient = new Eventhub("ws://myeventhubserver.com", "myAuthToken");

evClient.connect().then(res => {
	evClient.publish("my/topic", "This is a test message!", {
		ttl: 3600, // This message expires from the cache after 1 hour.
		timestamp: new Date().getTime() // Timestamp to index message with. If not set receipt time will be used.
	});
}).catch(err => {
	console.log(`Error connecting to Eventhub: ${err}`);
});

Unsubscribe from a topic

eventhub.unsubscribe("my/topic");

Unsubscribe from all subscribed topics

eventhub.unsubscribeAll();

Close connection to client

eventhub.disconnect();

List all current subscribed topics

eventhub.listSubscriptions().then(subscriptions => {
	console.log("Subscriptions:", subscriptions);
});

Get cached events for a topic without subscribing

// In this example we request all cached events from my/topic from the past 10 seconds.
// A negative 'since' number means Date.now() - abs(x).
// You can also speciy 'since' as a literal unix timestamp in milliseconds.
// We also support to request all events since a given message id by
// specifying 'sinceEventId': <id> instead of 'since'.
evClient.getEventlog("my/topic", { since: -10000 }).then((cache) => {
	for (const item of cache.items) {
		console.log(item);
	}
});

Reconnection handling

If the client loses connection with the server it will try to reconnect. When the connection is eventually restored all messages that has been lost during the disconnected period will be sent to the client before new ones.

Some of this behaviour is configureable as the third parameter to the connect() method.

Default options:

{
  pingInterval: 10000,      // Ping the server each 10 seconds.
  pingTimeout: 3000,        // Consider a ping as failed after 3 seconds.
  maxFailedPings: 3,        // How many lost pings before trying to reconnect.
  reconnectInterval: 10000, // 10 seconds between each reconnect attempt.
  disablePingCheck: false   // Disable pings and only rely on WebSocket 'onerror' event for detecting lost connection.
}

Lifecycle events

Library provides lifecycle events. You can subscribe for these events with the below syntax

const evClient = new Eventhub("ws://myeventhubserver.com", "myAuthToken");

evClient.on('connect', callback)

Event 'connect'

Emitted on successful (re)connection.

Event 'reconnect'

Emitted when a reconnect starts.

Event 'disconnect'

Emitted after a connection is being close.

Event 'offline'

Emitted when the client goes offline.

License

eventhub-jsclient is licensed under MIT. See LICENSE.