EaseMqtt - Documentation¶
Current Version: v0.1.0
I developed EaseMqtt from the need of a simpler approach to developing services that communicate via MQTT, and also an extension to the existing functionality of the mqtt
package.
Basic Usage¶
The main difference in implementation is mqtt
uses a slash /
delimiter, by default EaseMqtt
uses a dot .
delimiter, of course this can be overriden by providing a delimiter
property to the EaseMqtt
constructor. It’s also possible to use wildcards in the topic name, by default this is disabled but can be enabled with the wildcard
property.
import { connect } from 'mqtt';
import { EaseMqtt } from 'easemqtt';
const client = connect('mqtt://localhost');
const easemqtt = new EaseMqtt(client);
// subscribe
easemqtt.subscribe('some.topic', 2); // topic, optional qos (default 1)
// publish
easemqtt.publish('some.topic', 'hello world'); // topic(s), content (string/object)
easemqtt.on('some.topic', (req, res) => {
const body = req.body;
const replyTo = req.replyTo;
if (replyTo)
return res.reply('all done'); // string or object
});
Exceptions¶
EaseError
- thrown if arguments are invalidEaseClientError
- thrown if themqtt
client fails to subscribe
Class: EaseMqtt¶
Added: v0.1.0
This is the main constructor of the EaseMqtt
package, and provides all the functionality by integrating the different classes together.
Properties¶
wildcard
-boolean
- enable wildcard support (defaultfalse
)delimiter
-string
- set the delimiter that’s used (default.
)subscribe
-string[]
- a list of topics to subscribe to (default[]
)qos
-QoS
- set the default qos level (default1
)
Method: publish(topic, message, qos?)¶
Added: v0.1.0
Publish a message to topic(s) returning the message id.
Arguments¶
topic
-string | string[]
- the topic(s) to publish the message toomessage
-IEaseMessage
- the unencoded message contentqos
-QoS
- optional: override the default qos level
Return¶
Promise<number>
- when resolved, the message ID is returned.
Method: subscribe(topic, qos?)¶
Added: v0.1.0
This method has no return value Subscribe to topic(s) in order to receive published messages.
Arguments¶
topic
-string | string[]
- the topic(s) to subscribe toqos
-QoS
- override the default qos level
Method: end()¶
Added: v0.1.0
This method has no arguments, or return value Terminate the connected client and handle clean up.
Class: EaseEventHandler¶
Added: v0.1.0
EaseEventHandler
is responsible for converting the MqttClient
events, to an EaseMqtt
event. It also handles incoming messages and firing the relevant events.
Method: handleIncoming(topic, msgbuf)¶
Added: v0.1.0
An Event
listener that’s creates the EaseRequest
and EaseResponse
objects, and emits the event from the topic name. This method also handles topic name translation, and message decoding.
Arguments¶
topic
-string
- the topic the incoming message came onmsgbuf
-Buffer | string
- the encoded message content
Return¶
EaseRequest
- for testing purposes, this function returns theEaseRequest
object.
Method: handleConnection()¶
Added: v0.1.0
This method has no arguments, or return value
An Event
listener that emits a mqtt:connect
event when a MqttClient
has successfully made a connection to the broker.
Method: handleError()¶
Added: v0.1.0
This method has no arguments, or return value
An Event
listener that emits a mqtt:error
event when a MqttClient
reported an Error
.
Class: EaseRequest¶
Added: v0.1.0
Contains the information relating to an incoming request. This class is mainly a collection of properties but will likely include methods in future.
Properties¶
topic
-string
- the topic the message appeared onreplyTo
-string
- the topic to send a response toobody
-IEaseMessage
- the decoded message contenteaseMqtt
-IEaseMqtt
- theEaseMqtt
instance
Class: EaseResponse¶
Added: v0.1.0
Contains the information relating to a response. This class includes a method that’s used to easily reply to a message. It also contains properties.
Properties¶
request
-IEaseRequest
- the request instance and propertiestopic
-string
- the topic the request was made onreplyTo
-string
- the topic to send the response too
Util¶
There are a number of Utility functions available which are not exported by default. These will be documented soon.