v0.1.8 -> v0.2.0 Migration Guide

tl;dr

Rewrite everything that uses mqtt#createClient to use the new API, everything else should work okay.

See example

Introduction

The jump to v0.2.0 has brought a few API breaking changes to mqttjs. This document will describe what they are and how to update your app to comply with the new api.

mqtt#createClient and mqtt#createConnection

mqtt#createClient has been repurposed for the creation of the new MqttClient class. The old behaviour (simply wrapping an MqttConnection) can be accessed through the mqtt#createConnection method, but this is not advised.

MqttClient

Bare MqttConnections are deprecated in favour of using MqttClients, which take away a lot of the MqttConnection boilerplate.

Changes to invalid argument behaviour in Connection

If invalid arguments are supplied to methods of Connection, instead of that method returning null the connection emits an error event describing the invalid argument.

Important: not handling these errors causes nodejs to terminate the app due to its default handling of uncaughtException

Changes to keys in Connection#connect

The following keys have changed in the Connection#connect options argument:

• version is now protocolId
• versionNum is now protocolVersion
• client is now clientId

Changes to keys in Connection#subscribe

The option to specify a single subscription topic has been removed from Connection#subscribe, subscriptions must be supplied as an array of {topic: x, qos: 0} objects.

Changes to keys in Connection#unsubscribe

Similar to the above, a single topic can no longer be specified as an unsubscription, unsubscriptions must be an array of topic strings.

Changes to default handling in Connection

For all methods of Connection, all fields required to be present by the MQTT standard must be present in the options argument.

Affected keys include:

connect

• protocolId
• versionNum
• client
• keepalive

connack

• returnCode

publish

• messageId - (if qos > 0)

subscribe

• messageId

unsubscribe

• messageId