change signature to subscribe(options, callback)

hpihkala · hpihkala · commit a7072cf1b3f4 · 2017-04-07T12:59:59.000+03:00
diff --git a/README.md b/README.md
@@ -19,42 +19,40 @@ Here's a quick example. More detailed examples for the browser and node.js can b
 ```javascript
 // Create a StreamrClient instance
 var client = new StreamrClient({
-    // See below for connection options
+    // See below for options
 })
 
 // Subscribe to a stream
 var sub = client.subscribe(
-    'stream-id',
-    'auth-key',
-    function(message, streamId, timestamp, counter) {
-        // Do something with a message, which is an object
-    },
     {
-        // Resend options, see below
+        stream: 'streamId',
+        partition: 0,           // Optional, defaults to zero. Use for partitioned streams to select partition.
+        authKey: 'authKey'      // Optional. If not given, uses the authKey given at client creation time.
+        // optional resend options here
+    },
+    function(message, metadata) {
+        // Do something with the message, which is an object
     }
 )
 ```
 
-### Handling messages
-
-The third argument to `client.subscribe(streamId, authKey, callback, resendOptions)` is the callback function that will be called for each message as they arrive. Its arguments are as follows:
-
-Argument | Description
--------- | -----------
-message  | A javascript object containing the message itself
-streamId | The id of the stream the message belongs to
-timestamp| (optional) A javascript Date object containing the timestamp for this message, if available.
-counter  | (optional) A sequence number for this message, if available.
-
-
-### Connection options
+### Client options
 
 Option | Default value | Description
 ------ | ------------- | -----------
 url | ws://www.streamr.com/api/v1/ws | Address of the Streamr websocket endpoint to connect to.
 autoConnect | true | If set to `true`, the client connects automatically on the first call to `subscribe()`. Otherwise an explicit call to `connect()` is required.
 autoDisconnect | true  | If set to `true`, the client automatically disconnects when the last stream is unsubscribed. Otherwise the connection is left open and can be disconnected explicitly by calling `disconnect()`.
-authKey | null | Define default authKey to use when none is specified in subscribe
+authKey | null | Define default authKey to use when none is specified in the call to `client.subscribe`.
+
+### Message handler callback
+
+The second argument to `client.subscribe(options, callback)` is the callback function that will be called for each message as they arrive. Its arguments are as follows:
+
+Argument | Description
+-------- | -----------
+message  | A javascript object containing the message itself
+metadata | Metadata for the message, for example `metadata.timestamp` etc.
 
 ### Resend options
 
diff --git a/examples/browser.html b/examples/browser.html
@@ -1,7 +1,6 @@
 <html>
 	<head>
-		<!-- For debug messages, include debug.js from https://github.com/visionmedia/debug and set localStorage.debug = 'StreamrClient' -->
-		<script src="https://cdn.socket.io/socket.io-1.3.7.js"></script>
+		<!-- For debug messages, include debug.js and set localStorage.debug = 'StreamrClient'. See from https://github.com/visionmedia/debug -->
 		<script src="../streamr-client.js"></script>
 
 		<script>
@@ -15,14 +14,14 @@
 			var client = new StreamrClient()
 			// Subscribe to a stream
 			var subscription = client.subscribe(
-			    '1ef8TbyGTFiAlZ8R2gCaJw', 
+				{
+					stream: '1ef8TbyGTFiAlZ8R2gCaJw',
+					// Resend the last 10 messages on connect
+					resend_last: 10
+				},
 			    function(message) {
 			    	// Handle the messages in this stream
 			    	log(JSON.stringify(message))
-			    },
-			    {
-			    	// Resend the last 10 messages on connect
-			        resend_last: 10
 			    }
 			)
 
diff --git a/examples/node.js b/examples/node.js
@@ -8,14 +8,14 @@ var StreamrClient = require('../streamr-client')
 var client = new StreamrClient()
 // Subscribe to a stream
 var subscription = client.subscribe(
-    '1ef8TbyGTFiAlZ8R2gCaJw', 
+	{
+		stream: '1ef8TbyGTFiAlZ8R2gCaJw',
+		// Resend the last 10 messages on connect
+		resend_last: 10
+	},
     function(message) {
     	// Handle the messages in this stream
 		console.log(message)
-    },
-    {
-    	// Resend the last 10 messages on connect
-        resend_last: 10
     }
 )
 
diff --git a/streamr-client.js b/streamr-client.js
@@ -480,7 +480,7 @@
 		return id.toString()
 	};
 
-	function Subscription(streamId, authKey, callback, options) {
+	function Subscription(streamId, streamPartition, authKey, callback, options) {
 		EventEmitter.call(this); // call parent constructor
 
 		if (!streamId)
@@ -492,6 +492,7 @@
 
 		this.id = generateSubscriptionId()
 		this.streamId = streamId
+		this.streamPartition = streamPartition
 		this.authKey = authKey
 		this.callback = callback
 		this.options = options || {}
@@ -608,7 +609,7 @@
 			// Normal case where prevOffset == null || lastReceivedOffset == null || prevOffset === lastReceivedOffset
 			else {
 				this.lastReceivedOffset = offset
-				this.callback(content, this.streamId, timestamp, offset)
+				this.callback(content, msg)
 				if (content[BYE_KEY]) {
 					this.emit('done')
 				}
@@ -722,21 +723,35 @@
 		return this.subsByStream[streamId] || []
 	}
 
-	StreamrClient.prototype.subscribe = function(streamId, authKey, callback, options) {
+	StreamrClient.prototype.subscribe = function(options, callback, legacyOptions) {
 		var _this = this
 
-		if (!streamId)
-			throw "subscribe: Invalid arguments: stream id is required!"
-		else if (typeof streamId !== 'string')
-			throw "subscribe: stream id must be a string!"
-
-		if (!callback)
+		if (!options) {
+			throw "subscribe: Invalid arguments: subscription options is required!"
+		} else if (!callback) {
 			throw "subscribe: Invalid arguments: callback is required!"
+		}
+
+		// Backwards compatibility for giving a streamId as first argument
+		if (typeof options === 'string') {
+			options = {
+				stream: options
+			}
+		} else if (typeof options !== 'object') {
+			throw "subscribe: options must be an object"
+		}
+
+		// Backwards compatibility for giving an options object as third argument
+		extend(options, legacyOptions)
+
+		if (!options.stream) {
+			throw "subscribe: Invalid arguments: options.stream is not given"
+		}
 
 		// Create the Subscription object and bind handlers
-		var sub = new Subscription(streamId, authKey || this.options.authKey, callback, options)
+		var sub = new Subscription(options.stream, options.partition || 0, options.authKey || this.options.authKey, callback, options)
 		sub.on('gap', function(from, to) {
-			_this._requestResend(sub, {resend_from: from, resend_to: to, authKey: sub.authKey })
+			_this._requestResend(sub, {resend_from: from, resend_to: to})
 		})
 		sub.on('done', function() {
 			debug("done event for sub %d", sub.id)
@@ -1023,7 +1038,7 @@
 
 		sub.resending = true
 
-		var request = extend({}, options, resendOptions, {type: 'resend', stream: sub.streamId, authKey: sub.authKey,sub: sub.id})
+		var request = extend({}, options, resendOptions, {type: 'resend', stream: sub.streamId, partition: sub.streamPartition, authKey: sub.authKey, sub: sub.id})
 		debug("_requestResend: %o", request)
 		this.connection.send(request)
 	}
diff --git a/test/test.streamr-client.js b/test/test.streamr-client.js
