fix: make pubsub.unsubscribe async and alter pubsub.subscribe signature

SPEC/PUBSUB.md

@@ -1,19 +1,25 @@
 pubsub API
 ==========
 
+* [pubsub.subscribe](#pubsubsubscribe)
+* [pubsub.unsubscribe](#pubsubunsubscribe)
+* [pubsub.publish](#pubsubpublish)
+* [pubsub.ls](#pubsubls)
+* [pubsub.peers](#pubsubpeers)
+
 #### `pubsub.subscribe`
 
 > Subscribe to a pubsub topic.
 
 ##### `Go` **WIP**
 
-##### `JavaScript` - ipfs.pubsub.subscribe(topic, options, handler, callback)
+##### `JavaScript` - ipfs.pubsub.subscribe(topic, handler, [options], [callback])
 
-- `topic: string`
-- `options: Object` - (Optional), might contain the following properties:
-  - `discover`: type: Boolean - Will use the DHT to find other peers.
-- `handler: (msg) => ()` - Event handler which will be called with a message object everytime one is received. The `msg` has the format `{from: string, seqno: Buffer, data: Buffer, topicIDs: Array<string>}`.
-- `callback: (Error) => ()` (Optional) Called once the subscription is established.
+- `topic: String`
+- `handler: (msg) => {}` - Event handler which will be called with a message object everytime one is received. The `msg` has the format `{from: String, seqno: Buffer, data: Buffer, topicIDs: Array<String>}`.
+- `options: Object` - (Optional) Object containing the following properties:
+  - `discover: Boolean` - (Default: `false`) Will use the DHT to find other peers.
+- `callback: (Error) => {}` - (Optional) Called once the subscription is established.
 
 If no `callback` is passed, a [promise][] is returned.
 
@@ -23,12 +29,14 @@ If no `callback` is passed, a [promise][] is returned.
 
 ```JavaScript
 const topic = 'fruit-of-the-day'
+const receiveMsg = (msg) => console.log(msg.data.toString())
 
-const receiveMsg = (msg) => {
-  console.log(msg.data.toString())
-}
-
-ipfs.pubsub.subscribe(topic, receiveMsg)
+ipfs.pubsub.subscribe(topic, receiveMsg, (err) => {
+  if (err) {
+    return console.error(`failed to subscribe to ${topic}`, err)
+  }
+  console.log(`subscribed to ${topic}`)
+})
 ```
 
 A great source of [examples][] can be found in the tests for this API.
@@ -39,28 +47,40 @@ A great source of [examples][] can be found in the tests for this API.
 
 ##### `Go` **WIP**
 
-##### `JavaScript` - `ipfs.pubsub.unsubscribe(topic, handler)`
+##### `JavaScript` - `ipfs.pubsub.unsubscribe(topic, handler, [callback])`
+
+- `topic: String` - The topic to unsubscribe from
+- `handler: (msg) => {}` - The handler to remove.
+- `callback: (Error) => {}` (Optional) Called once the unsubscribe is done.
 
-- `topic: string` - The topic to unsubscribe from
-- `handler: (msg) => ()` - The handler to remove.
+If no `callback` is passed, a [promise][] is returned.
 
 This works like `EventEmitter.removeListener`, as that only the `handler` passed to a `subscribe` call before is removed from listening. The underlying subscription will only be canceled once all listeners for a topic have been removed.
 
 **Example:**
 
 ```JavaScript
 const topic = 'fruit-of-the-day'
+const receiveMsg = (msg) => console.log(msg.toString())
 
-const receiveMsg = (msg) => {
-  console.log(msg.toString())
-}
+ipfs.pubsub.subscribe(topic, receiveMsg, (err) => {
+  if (err) {
+    return console.error(`failed to subscribe to ${topic}`, err)
+  }
 
-ipfs.pubsub.subscribe(topic, receiveMsg)
+  console.log(`subscribed to ${topic}`)
 
-setTimeout(() => {
   // unsubscribe a second later
-  ipfs.pubsub.unsubscribe(topic, receiveMsg)
-}, 1000)
+  setTimeout(() => {
+    ipfs.pubsub.unsubscribe(topic, receiveMsg, (err) => {
+      if (err) {
+        return console.error(`failed to unsubscribe from ${topic}`, err)
+      }
+
+      console.log(`unsubscribed from ${topic}`)
+    })
+  }, 1000)
+})
 ```
 
 A great source of [examples][] can be found in the tests for this API.
@@ -71,11 +91,11 @@ A great source of [examples][] can be found in the tests for this API.
 
 ##### `Go` **WIP**
 
-##### `JavaScript` - ipfs.pubsub.publish(topic, data, callback)
+##### `JavaScript` - ipfs.pubsub.publish(topic, data, [callback])
 
-- `topic: string`
-- `data: buffer` - The actual message to send
-- `callback: (Error) => ()` - Calls back with an error or nothing if the publish was successfull.
+- `topic: String`
+- `data: Buffer` - The message to send
+- `callback: (Error) => {}` - (Optional) Calls back with an error or nothing if the publish was successful.
 
 If no `callback` is passed, a promise is returned.
 
@@ -87,9 +107,10 @@ const msg = new Buffer('banana')
 
 ipfs.pubsub.publish(topic, msg, (err) => {
   if (err) {
-    throw err
+    return console.error(`failed to publish to ${topic}`, err)
   }
   // msg was broadcasted
+  console.log(`published to ${topic}`)
 })
 ```
 
@@ -101,9 +122,9 @@ A great source of [examples][] can be found in the tests for this API.
 
 ##### `Go` **WIP**
 
-##### `JavaScript` - ipfs.pubsub.ls(callback)
+##### `JavaScript` - ipfs.pubsub.ls([callback])
 
-- `callback: (Error, Array<string>>) => ()` - Calls back with an error or a list of topicCIDs that this peer is subscribed to.
+- `callback: (Error, Array<string>) => {}` - (Optional) Calls back with an error or a list of topicIDs that this peer is subscribed to.
 
 If no `callback` is passed, a promise is returned.
 
@@ -112,7 +133,7 @@ If no `callback` is passed, a promise is returned.
 ```JavaScript
 ipfs.pubsub.ls((err, topics) => {
   if (err) {
-    throw err
+    return console.error('failed to get list of subscription topics', err)
   }
   console.log(topics)
 })
@@ -126,19 +147,21 @@ A great source of [examples][] can be found in the tests for this API.
 
 ##### `Go` **WIP**
 
-##### `JavaScript` - ipfs.pubsub.peers(topic, callback)
+##### `JavaScript` - ipfs.pubsub.peers(topic, [callback])
 
-- `topic: string`
-- `callback: (Error, Array<string>>) => ()` - Calls back with an error or a list of peer ids subscribed to the `topic`.
+- `topic: String`
+- `callback: (Error, Array<String>) => {}` - (Optional) Calls back with an error or a list of peer IDs subscribed to the `topic`.
 
 If no `callback` is passed, a promise is returned.
 
 **Example:**
 
 ```JavaScript
+const topic = 'fruit-of-the-day'
+
 ipfs.pubsub.peers(topic, (err, peerIds) => {
   if (err) {
-    throw err
+    return console.error(`failed to get peers subscribed to ${topic}`, err)
   }
   console.log(peerIds)
 })