feat(encoders/decoders): add encoder/decoder support, closes #1

- adds `text`, `json`, `binary`, and `base64` encoders and decoders to
  be used with `publish()` and `subscribe()`, respectively
- can set defaults with options to `connect()`
- the default is `text` for both encoder and decoder
- update docs, tests
- `unsubscribe` returns `true` if actual unsubscription occurs; `false`
  otherwise

Author: boneskull

README.md

@@ -30,10 +30,10 @@ Also, `Promise`s.
 There are two (2) main issues which users of MQTT.js will quickly encounter:
 
 1.  You can't just set a listener function for a subscribed topic; you have to stuff logic into a listener on the `message` event, and figure out what to do with the topic.
-2.  Received messages are all `Buffer`s, and when publishing, your message must be a `string`, `Buffer`.
+2.  Received messages are all `Buffer` objects, and you can only publish a `Buffer` or `string`.
 3. (BONUS ISSUE) It doesn't use `Promise`s, which some people prefer over callbacks.
 
-`mqttletoad` solves the *first* problem and the *third* problem.
+`mqttletoad` solves the above problems.  These are problems I have, and likely many others have as well.
 
 ### Listeners for Specific Topics
 
@@ -57,42 +57,96 @@ We need something like a *router* (think [express](https://www.npmjs.com/package
 
 What's better is that `EventEmitter`s are standardized.  They are easy to consume.  Think [RxJs](https://npm.im/rxjs)'s `Observable.fromEvent()`.  This should help those using a "reactive" programming model.
 
-### Promise Support
+### Encoding and Decoding
 
-[async-mqtt](https://npm.im/async-mqtt) does the same thing here--more or less.
+MQTT makes no prescriptions about what a message looks like.  It's just a [blob](https://en.wikipedia.org/wiki/Binary_large_object).
+
+But as a developer, you know your data.  Maybe that message is JSON, maybe it's base64-encoded, or maybe it's just a string.  You are unlikely to be surprised about what you get. 
+
+Out-of-the-box, `mqttletoad` provides several common *decoders* for received messages, and *encoders* for publishing messages.
+
+These are:
 
-### WONTFIX: Message Formats
+- `json` - Convert to/from a JSON representation of an object
+- `text` - Convert to/from a UTF-8 encoded string
+- `binary` - Convert to a `Buffer` (all received messages are `Buffer`s, so no decoding necessary)
+- `base64` - Convert to/from a base64 (string) representation of just about anything
 
-MQTT makes no prescriptions about what your message looks like.  It's just a [blob](https://en.wikipedia.org/wiki/Binary_large_object).  A JavaScript object is neither of these!  If you need to publish an object, call `JSON.stringify` on it first:
+To use these, you can specify a *default* encoder and/or decoder when connecting:
 
 ```js
-const obj = {goin: 'on'};
-client.emit('fever/flavor', JSON.stringify(obj));
+const toad = require('mqttletoad');
+
+(async function () {
+  const client = await toad.connect('wss://test.mosquitto.org', {
+    encoder: 'json',
+    decoder: 'json'
+  });
+  
+  await client.subscribe('foo/bar', message => {
+    console.log(message.baz); // quux
+  });
+  
+  // see listener above
+  await client.publish('foo/bar', {baz: 'quux'});  
+}());
 ```
 
-When subscribing, you will *always* receive a `Buffer`.  You'll need to unwrap it yourself:
+Or you can do this on a per-subscription/publish basis:
 
 ```js
-client.on('a/licky/boom/boom/down', buf => {
-  const obj = JSON.stringify(String(buf));
-});
-``` 
+const toad = require('mqttletoad');
+
+(async function () {
+  // "text" is the default encoder/decoder
+  const client = await toad.connect('wss://test.mosquitto.org', {
+    encoder: 'text',
+    decoder: 'text'
+  });
+  
+  await client.subscribe('foo/bar', message => {
+    console.log(message.baz); // quux
+  }, {decoder: 'json'});
+  
+  // see listener above
+  await client.publish('foo/bar', {baz: 'quux'}, {encoder: 'json'});   
+}());
+```
 
-A better idea may be to put some metadata in your topic about the message format, but again, this is up to you:
+You can also provide your own either way:
 
 ```js
-const formatters = {
-  json: val => String(JSON.stringify),
-  text: String,
-  yaml: parseYaml
-};
-
-client.on('radscript/4ever/format/+', (buf, {topic})=> {
-  const format = topic.split('/').pop();
-  const result = formatters[format](buf);
-});
+const toad = require('mqttletoad');
+
+(async function() {
+  const client = await toad.connect('wss://test.mosquitto.org', {
+    decoder: parseFloat 
+  });
+  
+  await client.subscribe('foo/bar', message => {
+    console.log(message); // 123.4
+  });
+  
+  await client.subscribe('foo/bar', message => {
+    console.log(message); // '123.4'
+  }, {decoder: 'text'});
+  
+  // see listeners above
+  await client.publish('foo/bar', 123.4); // default encoder is "text"  
+}());
 ```
 
+### Promise Support
+
+[async-mqtt](https://npm.im/async-mqtt) does the same thing here--more or less.
+
+The following functions are promisified:
+
+- `MqttClient#publish`
+- `MqttClient#subscribe`
+- `MqttClient#unsubscribe`
+- `MqttClient#end`
+
 ## Install
 
 **Node.js v7.0.0 or greater required**.
@@ -103,6 +157,8 @@ $ npm install mqttletoad
 
 ## Usage
 
+This is a fancypants wrapper around [MQTT.js](https://npm.im/mqtt), so most everything there applies here, except the differences noted above. 
+
 ```js
 const toad = require('mqttletoad');
 
@@ -116,28 +172,48 @@ const myfunc = async () => {
     console.warn('client offline; reconnecting...');
   });
 
-  // yes, `buf` is still a Buffer.
-  const suback = await client.subscribe('winken/+/nod', (buf, packet) => {
-    console.log(`topic: "${packet.topic}", message: "${String(buf)}"`);
+  // uses default "text" decoder
+  const suback = await client.subscribe('winken/+/nod', (str, packet) => {
+    console.log(`topic: "${packet.topic}", message: "${str}"`);
   }, {qos: 1});
 
   console.log(`subscribed to ${suback.topic} w/ QoS ${suback.qos}`);
 
+  // uses default "text" encoder
   await client.publish('winken/blinken/nod', 'foo');
+  
+  const someOtherListener = (message, packet) => {
+    // does stuff with MESSAGE
+  };
+  
+  // a custom decoder
+  await client.subscribe('winken/+/nod', someOtherListener, {
+    decoder: value => String(value).toUpperCase()
+  });
+  
+  // remove only this particular listener for this topic;
+  // no actual unsubscription occurs because this isn't the only listener
+  // on the topic.
+  await client.unsubscribe('winken/+/nod', someOtherListener);
+  
+  // remove ALL listeners from this topic and unsubscribe
+  await client.unsubscribe('winken/+/nod');
+  
+  // disconnect
+  await client.end();
 }
 ```
 
-## API
-
-Basically it's [async-mqtt](https://npm.im/async-mqtt) (which is [mqtt](https://npm.im/mqtt)) except:
-
 - Use `client.subscribe(topic, [opts], listener)` to *register a listener* for the topic. 
-  - `opts` are the standard options `mqtt.Client#subscribe()` supports
-  - While `mqtt.Client#subscribe()` supports an `Array` of topics, our `topic` is singular, and must be a string.
+  - `opts` are the standard options `MqttClient#subscribe()` supports, including `decoder`
+  - While `MqttClient#subscribe()` supports an `Array` of topics, our `topic` is singular, and *must* be a string.
   - Standard MQTT topic wildcards are supported, and listeners are executed first in order of specificity; i.e. `foo/bar` will take precedence over `foo/+` and `foo/+` will take precedence over `foo/#`.
 - Use `client.unsubscribe(topic, listener)` to remove the listener for the topic.
   - This will not necessarily *unsubscribe* from the topic (at the broker level), because there may be other listeners, but it *will* remove the listener.
-- `client.end()` won't throw a fit if already disconnected
+  - If `listener` is omitted, all listeners are removed, which forces unsubscription.
+- Use `client.end(force=false)` to disconnect 
+- Use `client.publish(topic, message, [opts])` with standard `MqttClient#publish()` options, including `encoder`
+- Use `connect(url, [opts])` to connect; `url` is a `string`, or you could just pass an `opts` object.  Includes `encoder` and `decoder` options, which set the default encoder and decoder, respectively.  The default is `text` in both cases.
 
 ## Roadmap
 

lib/decoders.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const atob = require('atob');
+
+/**
+ * JSON decoder
+ * @param {Buffer} value - Value to decode
+ * @returns {*} JSON representation of value
+ */
+const json = value => JSON.parse(value.toString('utf-8'));
+
+/**
+ * Base64 decoder
+ * @param {Buffer} value - Value to decode
+ * @returns {string} base64-encoded string
+ */
+const base64 = value => atob(value.toString('utf-8'));
+
+/**
+ * Text decoder
+ * @param {Buffer} value - Value to decode
+ * @returns {string} utf-8 encoded string
+ */
+const text = value => value.toString('utf-8');
+
+/**
+ * Binary decoder (does nothing)
+ * @param {Buffer} value - Value to decode
+ * @returns {Buffer} Unmolested `value`
+ */
+const binary = value => value;
+
+exports.json = json;
+exports.base64 = base64;
+exports.text = text;
+exports.binary = binary;

lib/encoders.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const btoa = require('btoa');
+
+/**
+ * JSON encoder
+ * @param {*} value - Value to encode
+ * @returns {string} JSON representation of value
+ */
+const json = JSON.stringify;
+
+/**
+ * Base64 encoder
+ * @param {*} value - Value to encode
+ * @returns {string} base64-encoded string
+ */
+const base64 = btoa;
+
+/**
+ * Text encoder
+ * @param {*} value - Value to encode
+ * @returns {string} text representation of string
+ */
+const text = String;
+
+/**
+ * Binary encoder
+ * @param {*} value - Value to encode
+ * @returns {Buffer} A Buffer representing the value
+ */
+const binary = value => Buffer.from(value);
+
+exports.json = json;
+exports.base64 = base64;
+exports.text = text;
+exports.binary = binary;