Merge pull request #4 from PsychoLlama/create-merged-list

Expose the ClientList, add super list feature

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v0.2.1
+The `ClientList` constructor has been exposed as `panic.ClientList`, and now accepts an array of smaller lists to pull from.
+
 ## v0.2.0
 `panic.serve` has been replaced with `panic.server`, which accepts `http.Server` instances instead of options.
 

README.md

@@ -127,7 +127,7 @@ Once you have a server listening, point browsers/servers to your address ([here'
 > **Note:** if you're using [PhantomJS](https://github.com/ariya/phantomjs), you'll need to serve the html page over http/s for socket.io to work.
 
 ### `panic.clients`
-Every group is a ClientList instance, and inherits from EventEmitter. They update in real-time as clients are added and disconnected, and have array-like methods for manipulating and subgrouping. `panic.clients` is the root level list, and contains every client currently connected.
+Every group is a ClientList instance, and inherits from EventEmitter. They update in real-time as clients are added and disconnected, and have array-like methods for manipulating and filtering. `panic.clients` is the root level list, and contains every client currently connected.
 
 #### Events
 As the list changes, it will emit one of two mutation events:
@@ -149,6 +149,27 @@ panic.clients.on('remove', function (client, id) {
 })
 ```
 
+#### ClientList
+The list constructor is exposed as `panic.ClientList`, and is useful when composing large groups from smaller ones. For example, you might have a list of both Internet Explorer and Opera Mini clients that you want to join into a new list. To create a group containing both, you'd either write a complex filter, or you can make a new list that simply combines them. Here's what that looks like:
+
+```javascript
+// Grab the List constructor
+var List = panic.ClientList;
+
+var clients = panic.clients;
+
+// Get the list of IE browsers
+var IE = clients.filter('Internet Explorer');
+
+// Get the list of Opera browsers
+var opera = clients.filter('Opera Mini');
+
+// create a new list that represents both
+var pickyBrowsers = new List([ IE, opera ]);
+```
+
+If no array is given, an empty list is returned.
+
 #### Methods
 
 <a name='clients'></a>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "panic-server",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Distributed Javascript runner",
   "main": "src/index.js",
   "scripts": {

src/ClientList.js

@@ -2,9 +2,18 @@
 var Emitter = require('events');
 var match = require('./matcher');
 var Promise = require('bluebird');
-function ClientList() {
+function ClientList(lists) {
+	var list = this;
 	Emitter.call(this);
-	this.clients = {};
+	list.clients = {};
+	function add(client) {
+		list.add(client);
+	}
+	if (lists instanceof Array) {
+		lists.forEach(function (list) {
+			list.each(add).on('add', add);
+		});
+	}
 }
 
 Function.prototype.toJSON = Function.prototype.toString;

src/index.js

@@ -1,6 +1,7 @@
 'use strict';
 var server = require('./server');
 var clients = require('./clients');
+var ClientList = require('./ClientList');
 
 var msg = '\n\nAPI CHANGE: ".serve()" has been renamed to ".server()",\n' +
 'and no longer works the same (see changelog#v0.2.0).\n';
@@ -10,5 +11,6 @@ module.exports = {
 	serve: function () {
 		throw new Error(msg);
 	},
-	clients: clients
+	clients: clients,
+	ClientList: ClientList
 };

test/index.js

@@ -111,3 +111,32 @@ describe('A clientList', function () {
 		});
 	});
 });
+
+describe('The ClientList constructor', function () {
+	var list1, list2, client1, client2;
+
+	beforeEach(function () {
+		list1 = new ClientList();
+		list2 = new ClientList();
+		client1 = new Client();
+		client2 = new Client();
+		list1.add(client1);
+		list2.add(client2);
+	});
+
+	it('should accept an array of clientLists', function () {
+		var list = new ClientList([list1, list2]);
+
+		// it should contain both clients
+		expect(list.get(client1.socket.id)).to.eq(client1);
+		expect(list.get(client2.socket.id)).to.eq(client2);
+	});
+
+	it('should reactively add new clients from source lists', function () {
+		var list = new ClientList([list1, list2]);
+		var client3 = new Client();
+		expect(list.get(client3.socket.id)).to.eq(null);
+		list1.add(client3);
+		expect(list.get(client3.socket.id)).to.eq(client3);
+	});
+});