Nodejs MQTT client for emitter.io.
Clone or download
dawsontoth and Florimond Various Non-Breaking Enhancements (#8)
* Whitespace Consistency

Added .editorconfig with settings that match the majority of the codebase, fixed diversions where appropriate.

* Made Various Non-Breaking Enhancements

1. The public methods are now all fluent, so you can chain method calls: `emitter.me().subscribe(EmitterEvents.me, me => console.log(me))` etc.
2. The internal utility methods now appear at the bottom of the class definition, making it a bit easier to understand the implementation.
3. A event enumeration is now exposed, making it possible to use strong typing for the `on` method, as well as the new `off` method.
4. Added `off` to make event removal possible.
5. Added support for multiple callbacks per event.
6. Renamed the internal method logError to _throwError to better describe what it does.
7. Updated the `on` parameter check to accurately describe all possible events (calculated from the new enum so it doesn’t go out of style easily again)
8. Made consistent usage of double quotes across the file, which seemed to be the predominant pattern in place already.
9. Made other minor consistency fixes with whitespace.
Latest commit 62f4d9f Dec 21, 2018

README.md

NPM NPM

This repository contains JavaScript client for both NodeJS and the Browser for Emitter (see also on Emitter GitHub). Emitter is an open-source real-time communication service for connecting online devices. At its core, emitter.io is a distributed, scalable and fault-tolerant publish-subscribe messaging platform based on MQTT protocol and featuring message storage.

Installation

Emitter for NodeJS:

npm install emitter-io --save

Emitter for the Browser:

Example

// connect to emitter.io and get the client
var client = emitter.connect(); // or: require('emitter-io') on NodeJS 

// once we're connected, subscribe to the 'chat' channel
client.subscribe({
	key: "<channel key>",
	channel: "chat"
});
    
// on every message, print it out
client.on('message', function(msg){
	console.log( msg.asString() );
});

// publish a message to the chat channel
client.publish({
	key: "<channel key>",
	channel: "chat/my_name",
	message: "hello, emitter!"
});

API


connect(host: string, port: number)

Connects to the emitter api broker specified by the given url and options and returns an Emitter instance. The URL can be on the following protocols: 'mqtt', 'mqtts', 'tcp', 'tls', 'ws', 'wss'. The URL can also be an object as returned by URL.parse(), in that case the two objects are merged, i.e. you can pass a single object with both the URL and the connect options.


Emitter()

The Emitter class wraps a client connection to an emitter.io MQTT broker over an arbitrary transport method (TCP, TLS, WebSocket, ecc). It automatically handles the following by with help of MQTT.js client:

  • Regular server pings
  • QoS flow
  • Automatic reconnections
  • Start publishing before being connected

Event 'connect'

function(connack) {}

Emitted on successful (re)connection (i.e. connack rc=0).

  • connack received connack packet. When clean connection option is false and server has a previous session for clientId connection option, then connack.sessionPresent flag is true. When that is the case, you may rely on stored session and prefer not to send subscribe commands for the client.

Event 'disconnect'

function() {}

Emitted after a disconnection.

Event 'offline'

function() {}

Emitted when the client goes offline.

Event 'error'

function(error) {}

Emitted when the client cannot connect (i.e. connack rc != 0) or when a parsing error occurs.

Event 'keygen'

function(keyJson) {}

Emitted when the client generate a key to a channel using Emitter#keygen() function.

Event 'message'

function(message) {}

Emitted when the client receives a message packet. The message object will be of EmitterMessage class, encapsulating the channel and the payload.


Emitter#publish({ key: string; channel: string; message: any; })

Publish a message to a channel

  • key is security key to use for the operation, String
  • channel is the channel string to publish to, String
  • message is the message to publish, Buffer or String

Emitter#subscribe({ key: string; channel: string; })

Subscribes to a channel

  • key is security key to use for the operation, String
  • channel is the channel string to subscribe to, String

Emitter#unsubscribe({ key: string; channel: string; })

Unsubscribes from a channel

  • key is security key to use for the operation, String
  • channel is the channel string to unsubscribe from, String

Emitter#keygen({ key: string; channel: string; type: string; ttl: number; })

Sends a key generation request to the server.

  • key is master/secret key to use for the operation, String
  • channel is the channel string to generate a key for, String
  • type the type of the key to generate. Possible options include r for read-only, w for write-only and rw for read-write keys, String
  • ttl is the time-to-live of the key, in seconds.

Emitter#presence({ key: string; channel: string; status: boolean; changes: boolean; })

Requests the presence for a particular channel.

  • key is master/secret key to use for the operation, String
  • channel is the channel string to generate a key for, String
  • status whether the current state should be retrieved or not
  • changes whether the future changes should be received or not

Emitter#me()

Retrieves information about the underlying client connection.


Emitter#disconnect()

Disconnects from the remote broker


EmitterMessage()

The EmitterMessage class wraps a message received from the broker. It contains several properties:

  • channel is channel the message was published to, String
  • binary is the buffer associated with the payload, Buffer

EmitterMessage#asString()

Returns the payload as a utf-8 String.


EmitterMessage#asBinary()

Returns the payload as the Buffer.


EmitterMessage#asObject()

Returns the payload as JSON-deserialized Object.

License

The MIT License (MIT) Copyright (c) 2016 Misakai Ltd.