Support for single global changes feed

[ahamid]

This patch adds support for a single global changes feed (it also includes my previous patch for conservative collection name derivation, although that is trivial to separate).

The global feed is enabled like:

Backbone.couch_connector.config.single_feed = true;

When the single global feed is enabled, the way collection change handlers are registered is changed. (Whether they are registered has not been changed, and is still governed by the global_changes or individual collection changes setting.)

When single feed is enabled, each collection handler will be registered with a single changes feed.

Each collection also supports a local_filter irrespective of the single feed. This local_filter function can be used to, you guessed it, filter change results from the changes feed. When coupled with the single changes feed this allows each collection to only observe relevant changes. When single feed is enabled, a default local filter is installed which does this (so if you follow standard conventions you should be able to just enable single_feed).

Default single_feed local_filter:

# default local filter which selects documents of a given collection
filter_collection : (results, collection_name) ->
  entry for entry in results when (entry.deleted == true) || (entry.doc?.collection == collection_name)

Example of custom local_filter:

var NoteList = Backbone.Collection.extend({
    url : "/notes",
    model: Note,
    db: {
        local_filter: function(results) {
          return _.filter(results, function(entry) { entry.doc.importance == "urgent" });
        }
    }
});

On a technical note, change listener registration could probably be factored out into a separate class that is reused for both the per-collection and global feed, but I wanted my changes to be minimal.

[janmonschke]

Have you run the tests on that?

[ahamid]

Hi Jan, we have our own cucumber features and jasmine specs which we've run and confirmed the behavior is as expected, but I did not write any specific tests for just the connector.

I confirmed multi-browser/window support manually as this is currently hard to test in an automated way.

As I noted above, if this is a long-term feature you'd like to support then the code could probably be refactored to be simpler, I just wanted to make a minimal amount of changes for a patch.

[janmonschke]

I would simply merge this if you could also provide the changes to the readme :)

[timblack1]

I found the changes in this pull request essential, because I have several object instances listening for changes. But, merging this pull request into my project meant reverting from backbone-couchdb 1.2.2 to 1.1. So, I'm updating the readme (and will provide a pull request) in the hope this will make it possible to pull these changes into a future version of backbone-couchdb. I know this will require a bit of tricky merge work by someone who knows the code well. In other words, I think the way to integrate these changes into the mainline is to merge them with the 1.1 code, then merge in each subsequent revision which resulted in 1.2.2, then release a new version named 1.2.3 or 1.3, since this is a new feature. I'm not confident I can do this tricky merge work, because I don't understand the code well.

[timblack1]

I attempted to further this work in pull request #55.