mqtt-dispatcher/docs/api.md

Node.js message dispatcher for MQTT

<!-------------------------------------------------------------------->
<!--                            WARNING!                            -->
<!-------------------------------------------------------------------->
<!--                                                                -->
<!-- THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. -->
<!-- but run the following script $ npm run build                   -->
<!--                                                                -->
<!-------------------------------------------------------------------->
<!-------------------------------------------------------------------->

# Mqtt-Dispatcher APIs
## Classes

<dl>
<dt><a href="#MqttDispatcher">MqttDispatcher</a></dt>
<dd><p>MQTT Dispatcher component</p>
</dd>
</dl>

## Typedefs

<dl>
<dt><a href="#InvolvedEntities">InvolvedEntities</a></dt>
<dd></dd>
</dl>

# Specs
<a name="MqttDispatcher"></a>

## MqttDispatcher
MQTT Dispatcher component

**Kind**: global class  

* [MqttDispatcher](#MqttDispatcher)
    * [new MqttDispatcher([options])](#new_MqttDispatcher_new)
    * [.addRule(topicPattern, fn, [options])](#MqttDispatcher+addRule) ⇒ [<code>Promise.&lt;InvolvedEntities&gt;</code>](#InvolvedEntities)
    * [.removeRule(topicPattern, [fn])](#MqttDispatcher+removeRule) ⇒ [<code>Promise.&lt;InvolvedEntities&gt;</code>](#InvolvedEntities)
    * [.destroy()](#MqttDispatcher+destroy) ⇒ <code>Promise.&lt;Object&gt;</code>

<a name="new_MqttDispatcher_new"></a>

### new MqttDispatcher([options])
Creates a MqttDispatcher object.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [options] | <code>Object</code> | <code>{}</code> | Subscription options |
| [options.qos] | <code>number</code> | <code>0</code> | Default QoS. See [addRule](#MqttDispatcher+addRule) options. |
| [options.handleSubscription] | <code>boolean</code> | <code>true</code> | Default subscription strategy. See [addRule](#MqttDispatcher+addRule) options. |

**Example**  
```js
const mqtt = require('mqtt')
const MqttDispatcher = require('mqtt-dispatcher')

const client = mqtt.connect('mqtt://mqtt.broker:1883')
const dispatcher = new MqttDispatcher(client)
```
<a name="MqttDispatcher+addRule"></a>

### mqttDispatcher.addRule(topicPattern, fn, [options]) ⇒ [<code>Promise.&lt;InvolvedEntities&gt;</code>](#InvolvedEntities)
This method is used to register a new handler, associated to a topic pattern. It returns a Promise that is fullfilled when the subscription on the client has been completed or immediately if no subscription is required.

**Kind**: instance method of [<code>MqttDispatcher</code>](#MqttDispatcher)  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| topicPattern | <code>string</code> |  | Mqtt topic on which the handler has to be attached |
| fn | <code>function</code> |  | Handler |
| [options] | <code>Object</code> | <code>{}</code> | Subscription options |
| [options.qos] | <code>number</code> | <code>0</code> | MQTT Quality of Service |
| [options.handleSubscription] | <code>boolean</code> | <code>true</code> | If false, the dispatcher won't subscribe to the provided MQTT client to topics. This mode is useful to reduce the number of subscriptions. Any mqtt subscription is up to the developer that must subscribe the client enough to obtain the required messages (e.g. '#'). Use with caution. |
| [options.subscription] | <code>boolean</code> |  | Use this option to override the subscription for this rule with a new one that is more general and can work across multiple rules ( eg. If you have a rule for command/shutdown and command/reboot you can subscribe the client to command/+ and save subscriptions ) |

<a name="MqttDispatcher+removeRule"></a>

### mqttDispatcher.removeRule(topicPattern, [fn]) ⇒ [<code>Promise.&lt;InvolvedEntities&gt;</code>](#InvolvedEntities)
Unsubscribe from a topic

**Kind**: instance method of [<code>MqttDispatcher</code>](#MqttDispatcher)  

| Param | Type | Description |
| --- | --- | --- |
| topicPattern | <code>string</code> | Mqtt topic on which the handler has to be attached |
| [fn] | <code>function</code> | Handler (if a function is provided removes the associated handler only) |

<a name="MqttDispatcher+destroy"></a>

### mqttDispatcher.destroy() ⇒ <code>Promise.&lt;Object&gt;</code>
Detaches the dispatcher from the MQTT client. After this call, any method on the dispatcher throws an exception.

**Kind**: instance method of [<code>MqttDispatcher</code>](#MqttDispatcher)  
<a name="InvolvedEntities"></a>

## InvolvedEntities
**Kind**: global typedef  
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| topicPattern | <code>Array.&lt;String&gt;</code> | list of patterns involved in the operation |
| subscriptions | <code>Array.&lt;String&gt;</code> | list of subscriptions involved in the operation |