Merge pull request #4 from streamr-dev/node-support

CORE-467 Node-friendliness

Author: hpihkala

README.md

@@ -1,23 +1,30 @@
 # streamr-client
 
-streamr-client is a JavaScript client for connecting to Streamr data. You can subscribe to user interface widget updates or even raw data streams.
+This is a JavaScript client for subscribing to realtime streams from [Streamr](http://www.streamr.com). Streamr is a realtime stream processing and analytics platform. This client allows you to write JS applications that leverage the stream computing and pub/sub features of Streamr. It works both in the browser and in node.js.
 
-## Requirements
+The streamr-client uses [socket.io](http://socket.io/) under the hood for streaming message delivery. It works in virtually all browsers by using websockets where available, or fallback methods on legacy browsers.
 
-* socket.io
+## Dependencies
+
+* [socket.io-client](https://cdn.socket.io/socket.io-1.3.7.js)
+* [debug](https://github.com/visionmedia/debug) (optional)
+
+In node.js, dependencies will be installed automatically with `npm install`. In the browser, make sure you include `socket.io-client` before `streamr-client`.
 
 ## Usage
 
+The `examples` directory contains snippets for both browser and node.js.
+
 ```javascript
 client = new StreamrClient({ 
-	// Connection options and default values
-	server: 'data.streamr.com',
+	// Connection options can be omitted, these are the default values
+	server: 'https://data.streamr.com',
 	autoConnect: true,
 	autoDisconnect: true
 })
-client.subscribe(
+var sub = client.subscribe(
 	'stream-id', 
-	function(message, streamId, counter) {
+	function(message, streamId, timestamp, counter) {
 		// Do something with the message, which is an object
 	},
 	{ 
@@ -29,7 +36,7 @@ client.connect()
 
 ## Handling messages
 
-The second argument to client.subscribe() is the callback function that will be called for each message as they arrive. Its arguments are as follows:
+The second argument to `client.subscribe(streamId, callback, resendOptions)` is the callback function that will be called for each message as they arrive. Its arguments are as follows:
 
 Argument | Description
 -------- | -----------
@@ -75,16 +82,51 @@ getSubscriptions(`streamId`) | Returns a list of `Subscriptions` for `streamId`.
 bind(eventName, function) | Binds a `function` to an event called `eventName`
 unbind(eventName, function) | Unbinds the `function` from events called `eventName`
 
-## Events on the client
+## Binding to events
+
+The client and the subscriptions can fire events as detailed below. You can bind to them using `bind`:
+
+```javascript
+	function hello() {
+		console.log('Hello!')
+	}
+
+	client.bind('connected', hello)
+
+	var sub = client.subscribe(...)
+	sub.bind('subscribed', function() {
+		console.log('Subscribed to '+sub.streamId)
+	})
+```
+
+You can unbind using `unbind`:
+
+```javascript
+	client.unbind('connected', hello)
+```
+
+
+## Events on the StreamrClient instance
 
 Name | Handler Arguments | Description
 ---- | ----------------- | -----------
 connected |  | Fired when the client has connected (or reconnected).
 disconnected |  | Fired when the client has disconnected (or paused).
 
-## Events on the `Subscription` object
+## Events on the Subscription object
 
 Name | Handler Arguments | Description
 ---- | ----------------- | -----------
 subscribed | {from: number} | Fired when a subscription request is acknowledged by the server.
 unsubscribed |  | Fired when an unsubscription is acknowledged by the server.
+resending |  | Fired when the subscription starts resending.
+resent |  | Fired after `resending` when the subscription has finished resending.
+no_resend |  | Fired after `resending` in case there was nothing to resend.
+
+## Logging
+
+This library supports the [debug](https://github.com/visionmedia/debug) library for logging.
+
+In node.js, start your app like this: `DEBUG=StreamrClient node your-app.js`
+
+In the browser, include `debug.js` and set `localStorage.debug = 'StreamrClient'`

examples/browser.html

@@ -0,0 +1,53 @@
+<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>
+		<script src="../streamr-client.js"></script>
+
+		<script>
+			function log(msg) {
+				var elem = document.createElement('p')
+				elem.innerHTML = msg
+				document.body.appendChild(elem)
+			}
+
+			// Create the client with default options
+			var client = new StreamrClient()
+			// Subscribe to a stream
+			var subscription = client.subscribe(
+			    '1ef8TbyGTFiAlZ8R2gCaJw', 
+			    function(message) {
+			    	// Handle the messages in this stream
+			    	log(JSON.stringify(message))
+			    },
+			    {
+			    	// Resend the last 10 messages on connect
+			        resend_last: 10
+			    }
+			)
+
+			// Event binding examples
+			client.bind('connected', function() {
+				log('A connection has been established!')
+			})
+
+			subscription.bind('subscribed', function() {
+				log('Subscribed to '+subscription.streamId)
+			})
+
+			subscription.bind('resending', function() {
+				log('Resending from '+subscription.streamId)
+			})
+
+			subscription.bind('resent', function() {
+				log('Resend complete for '+subscription.streamId)
+			})
+
+			subscription.bind('no_resend', function() {
+				log('Nothing to resend for '+subscription.streamId)
+			})
+		</script>
+	</head>
+	<body>
+	</body>
+</html>

examples/node.js

@@ -0,0 +1,41 @@
+// To enable debug logging:
+// DEBUG=StreamrClient node examples/node.js
+
+// In your own app, use require('streamr-client') and get it from npm
+var StreamrClient = require('../streamr-client')
+
+// Create the client with default options
+var client = new StreamrClient()
+// Subscribe to a stream
+var subscription = client.subscribe(
+    '1ef8TbyGTFiAlZ8R2gCaJw', 
+    function(message) {
+    	// Handle the messages in this stream
+		console.log(message)
+    },
+    {
+    	// Resend the last 10 messages on connect
+        resend_last: 10
+    }
+)
+
+// Event binding examples
+client.bind('connected', function() {
+	console.log('A connection has been established!')
+})
+
+subscription.bind('subscribed', function() {
+	console.log('Subscribed to '+subscription.streamId)
+})
+
+subscription.bind('resending', function() {
+	console.log('Resending from '+subscription.streamId)
+})
+
+subscription.bind('resent', function() {
+	console.log('Resend complete for '+subscription.streamId)
+})
+
+subscription.bind('no_resend', function() {
+	console.log('Nothing to resend for '+subscription.streamId)
+})

package.json

@@ -1,7 +1,11 @@
 {
   "name": "streamr-client",
-  "version": "0.0.1",
-  "description": "",
+  "version": "0.8.0",
+  "description": "JS client for subscribing to Streamr streams",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/streamr-dev/streamr-client.git"
+  },
   "main": "streamr-client.js",
   "directories": {
     "test": "test"
@@ -12,10 +16,12 @@
   "author": "",
   "license": "",
   "dependencies": {
-
+    "socket.io-client": "1.3.7",
+    "debug": "*"
   },
   "devDependencies": {
     "mocha": "*",
-    "eventemitter2": "*"
+    "eventemitter2": "*",
+    "mockery": "*"
   }
 }