backbone-filtered-collection 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rvmrc

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional.
+environment_id="1.9.3-head@filtered-collection"
+
+#
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficicent compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+#
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments" \
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]] ; then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+
+  [[ -s ".rvm/hooks/after_use" ]] && . ".rvm/hooks/after_use"
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  rvm --create  "$environment_id"
+fi
+
+#
+# If you use an RVM gemset file to install a list of gems (*.gems), you can have
+# it be automatically loaded. Uncomment the following and adjust the filename if
+# necessary.
+#
+# filename=".gems"
+# if [[ -s "$filename" ]] ; then
+#   rvm gemset import "$filename" | grep -v already | grep -v listed | grep -v complete | sed '/^$/d'
+# fi
+
+#
+# If you use bundler and would like to run bundle each time you enter the
+# directory, you can uncomment the following code.
+#
+#   # Ensure that Bundler is installed. Install it if it is not.
+#   if ! command -v bundle >/dev/null; then
+#      printf "The rubygem 'bundler' is not installed. Installing it now.\n"
+#      gem install bundler
+#   fi
+#
+#   # Bundle while reducing excess noise.
+#   printf "Bundling your gems. This may take a few minutes on a fresh clone.\n"
+#   bundle | grep -v '^Using ' | grep -v ' is complete' | sed '/^$/d'
+#
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in backbone_filtered_collection.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Dmitriy Likhten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Dmitriy Likhten
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,66 @@
+# Filtered Collection
+
+This is a simple filtered collection implemented using
+Backbone.Collection. The goal here is to create a collection which,
+given a filter function, will just contain elements of the original
+which pass the filter. Supports add/remove/reset events of the original
+to modify the filtered version.
+
+# Why not just extend backbone?
+
+The main reason I did not just extend backbone is because by extending
+it, you shove all behaviors into one model, making it a
+jack-of-all-trades and potentially conflicting with behaviors of other
+extentions, not to mention making normal operaitons potentially slower.
+So the intention is to compose a filter chain pattern using
+these guys.
+
+# Installation to rails
+
+With bundler
+
+    gem 'backbone-filtered-collection', git: "git://github.com/dlikhten/filtered-collection.git"
+
+Inside your sprockets file:
+
+    //= require backbone-filtered-collection
+
+# Usage
+
+    var YourCollection = Backbone.Collection.extend({model: YourModel});
+    var YourFilteredCollection = Backbone.FilteredCollection.extend({model: YourModel});
+    var allItems = new YourCollection(...);
+    // note the null, backbone collections want the pre-populated model here
+    // we can't do that since this collection does not accept mutations, it
+    // only mutates as a proxy for the underlying collection
+    var filteredItems = new YourFilteredCollection(null, {collection: allItems});
+    var filteredItems.setFilter(function(item) { return item.get('included') == true;});
+
+And now filteredItems contains only those items that pass the filter.
+You can still manipulate the original:
+
+    allItems.add(..., {at: 5}); // at is supported too...
+
+However, if you invoke {silent: true} on the original model, then you
+must reset the filter by invoking:
+
+    filteredItems.setFilter(); // no args = just re-filter
+
+Same goes for remove and reset.
+
+To clear the filtering completely, pass the value false to setFilter.
+
+# Testing
+
+    bundle install
+    rake jasmine
+
+I also included a .rvmrc file incase you have rvm installed.
+
+# Contributing
+
+Please, do not contribute without a spec. Being tested is critically important 
+to this project, as it's a framework level component, and so its failure 
+will be damn hard to detect.
+
+Also, no tab characters, 2 spaces only. Minifiers can handle this stuff for you.

data/Rakefile

@@ -0,0 +1,4 @@
+require "bundler/gem_tasks"
+
+require 'jasmine'
+load 'jasmine/tasks/jasmine.rake'

data/backbone-filtered-collection.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/backbone/filtered_collection/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = "backbone-filtered-collection"
+  gem.version       = Backbone::FilteredCollection::VERSION
+  gem.platform      = Gem::Platform::RUBY
+  gem.authors       = ["Dmitriy Likhten"]
+  gem.email         = ["dlikhten@gmail.com"]
+  gem.description   = %q{A filtered collection for backbone.js}
+  gem.summary       = %q{Allowing implementation of a chain-of-responsibility pattern in backbone's collection filtering}
+  gem.homepage      = "http://github.com/dlikhten/filtered-collection"
+  gem.license       = "MIT"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "railties", ">= 3.0", "< 5.0"
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'jasmine'
+end

data/lib/backbone/filtered_collection/engine.rb

@@ -0,0 +1,6 @@
+module Backbone
+  module FilteredCollection
+    class Engine < ::Rails::Engine
+    end
+  end
+end

data/lib/backbone/filtered_collection/version.rb

@@ -0,0 +1,5 @@
+module Backbone
+  module FilteredCollection
+    VERSION = "1.0.0"
+  end
+end

data/lib/backbone/filtered_collection.rb

@@ -0,0 +1,7 @@
+require 'backbone/filtered_collection/engine' if ::Rails.version >= '3.1'
+require 'backbone/filtered_collection/version'
+
+module Backbone
+  module FilteredCollection
+  end
+end

data/lib/backbone-filtered-collection.rb

@@ -0,0 +1 @@
+require "backbone/filtered_collection"

data/spec/javascripts/backbone-filtered-collection-spec.js

@@ -0,0 +1,353 @@
+describe("Backbone.FilteredCollection", function() {
+  var TehModel = Backbone.Model.extend({
+    defaults: {value: -1}
+  });
+
+  var RegularModelCollection = Backbone.Collection.extend({
+    model: TehModel
+  });
+
+  var ModelCollection = Backbone.FilteredCollection.extend({
+    model: TehModel
+  });
+
+  var allModels;
+  var collection;
+
+  var createLessthanFilter = function(lessThan) {
+    return function(model) {
+      return model.get('value') < lessThan;
+    }
+  };
+
+  var oddFilter = function(model) {
+    return model.get("value") % 2 == 1;
+  }
+  var evenFilter = function(model) {
+    return model.get("value") % 2 == 0;
+  }
+
+  beforeEach(function() {
+    allModels = new RegularModelCollection();
+    for(var i = 0; i < 10; i++) {
+      allModels.add(new TehModel({id: i, value: i}));
+    }
+
+    collection = new ModelCollection(null, {collection: allModels});
+  });
+
+  describe("#setFilter", function() {
+    it("should filter the given model", function() {
+      collection.setFilter(createLessthanFilter(5));
+
+      expect(collection.length).toEqual(5);
+      expect(collection.at(0).get('value')).toEqual(0);
+    });
+
+    it("should change filters", function() {
+      collection.setFilter(createLessthanFilter(5));
+
+      collection.setFilter(function(model) {
+        return model.get('value') > 7;
+      });
+
+      expect(collection.length).toEqual(2);
+      expect(collection.at(0).get('value')).toEqual(8);
+    });
+
+    it("should take a false filter as a return to no filter", function() {
+      collection.setFilter(createLessthanFilter(5));
+      expect(collection.length).toEqual(5);
+      collection.setFilter(undefined); // no change
+      expect(collection.length).toEqual(5);
+      collection.setFilter(null); // no change
+      expect(collection.length).toEqual(5);
+      collection.setFilter(false); // filter reset
+      expect(collection.length).toEqual(10);
+    });
+
+    it("should work correctly after filtering is changed constantly", function() {
+      collection.setFilter(createLessthanFilter(0));
+      expect(collection.models.length).toEqual(0);
+
+      collection.setFilter(createLessthanFilter(3));
+      expect(collection.models.length).toEqual(3);
+      expect(collection.models[0].get("value")).toEqual(0)
+      expect(collection.models[1].get("value")).toEqual(1)
+      expect(collection.models[2].get("value")).toEqual(2)
+
+      collection.setFilter(evenFilter);
+      expect(collection.models.length).toEqual(5);
+      expect(collection.models[0].get("value")).toEqual(0)
+      expect(collection.models[1].get("value")).toEqual(2)
+      expect(collection.models[2].get("value")).toEqual(4)
+      expect(collection.models[3].get("value")).toEqual(6)
+      expect(collection.models[4].get("value")).toEqual(8)
+    });
+
+    it("should not trigger a filter-complete event if options.silent is true", function() {
+      count = 0;
+      collection.on("filter-complete", function() {
+        count += 1;
+      });
+
+      collection.setFilter(createLessthanFilter(0), {silent: true});
+
+      expect(count).toEqual(0);
+    });
+  });
+
+  describe("event:add", function() {
+    it("should not add the new object, since it is already filtered out", function() {
+      collection.setFilter(createLessthanFilter(5));
+      expect(collection.length).toEqual(5);
+      allModels.add(new TehModel({value: 6}));
+      expect(collection.length).toEqual(5);
+    });
+
+    it("should add the new object, since it passes the filter", function() {
+      collection.setFilter(createLessthanFilter(5));
+      expect(collection.length).toEqual(5);
+      allModels.add(new TehModel({value: 1}));
+      expect(collection.length).toEqual(6);
+      expect(collection.at(5).get('value')).toEqual(1);
+    });
+
+    it("should add the new object to the correct location", function() {
+      collection.setFilter(createLessthanFilter(5));
+      expect(collection.length).toEqual(5);
+      allModels.add(new TehModel({value: 4}), {at: 0});
+      expect(collection.length).toEqual(6);
+      expect(collection.at(0).get('value')).toEqual(4);
+    });
+
+    it("should trigger an add event if the object was added", function() {
+      collection.setFilter(createLessthanFilter(5));
+      expect(collection.length).toEqual(5);
+
+      var newModel = new TehModel({value: 3});
+      count = 0;
+      collection.on("add", function(model, collection, options) {
+        expect(model).toEqual(newModel);
+        expect(options.index).toEqual(0);
+        count += 1;
+      });
+      allModels.add(newModel, {at: 0});
+
+      expect(count).toEqual(1);
+    });
+
+    it("should re-number elements propperly in the mapping according to what the actualy indices are in the original collection", function() {
+      collection.setFilter(createLessthanFilter(10));
+      expect(collection.length).toEqual(10);
+
+      allModels.add(new TehModel({value: 4}), {at: 6});
+
+      expect(collection._mapping).toEqual([0,1,2,3,4,5,6,7,8,9,10])
+    });
+  });
+
+  describe("event:remove", function() {
+    it("should be a noop since the object is filtered", function() {
+      collection.setFilter(createLessthanFilter(5));
+      expect(collection.length).toEqual(5);
+      allModels.remove(allModels.at(6));
+      expect(collection.length).toEqual(5);
+    });
+
+    it("should be a remove the removed object", function() {
+      collection.setFilter(createLessthanFilter(5));
+      expect(collection.length).toEqual(5);
+      allModels.remove(allModels.at(4));
+      expect(collection.length).toEqual(4);
+      expect(collection.at(collection.length - 1).get('value')).toEqual(3);
+    });
+
+    it("should re-number elements propperly in the mapping according to what the actualy indices are in the original collection", function() {
+      collection.setFilter(createLessthanFilter(10));
+      expect(collection.length).toEqual(10);
+
+      allModels.remove(allModels.at(4));
+
+      expect(collection._mapping).toEqual([0,1,2,3,4,5,6,7,8])
+    });
+  });
+
+  describe("event:reset", function() {
+    it("should be a noop since the object is filtered", function() {
+      collection.setFilter(createLessthanFilter(15));
+      var newAll = [];
+      for (var i = 10; i < 20; i++) {
+        newAll.push(new TehModel({value: i}));
+      }
+      allModels.reset(newAll);
+      expect(collection.length).toEqual(5);
+      expect(collection.at(4).get('value')).toEqual(14);
+    });
+  });
+
+  describe("event:sort", function() {
+    it("should continue filtering the collection, except with a new order", function() {
+      collection.setFilter(createLessthanFilter(5));
+      allModels.comparator = function(v1, v2) {
+        return v2.get("value") - v1.get("value");
+      };
+      allModels.sort();
+
+      expect(collection.length).toEqual(5);
+      expect(collection.at(0).get('value')).toEqual(4);
+      expect(collection.at(1).get('value')).toEqual(3);
+      expect(collection.at(2).get('value')).toEqual(2);
+      expect(collection.at(3).get('value')).toEqual(1);
+      expect(collection.at(4).get('value')).toEqual(0);
+    });
+  });
+
+  describe("event:filter-complete", function() {
+    it("should fire when the underlying collection fires it (thus we're done filtering too)", function() {
+      var filterFired = 0;
+      collection.on("filter-complete", function() {
+        filterFired += 1;
+      });
+      allModels.trigger("filter-complete");
+      expect(filterFired).toEqual(1);
+    });
+
+    it("should fire once only at the end of a filter", function() {
+      var filterFired = 0;
+      collection.on("filter-complete", function() {
+        filterFired += 1;
+      });
+      collection.setFilter(createLessthanFilter(3));
+      expect(filterFired).toEqual(1);
+    });
+
+    it("should fire once when a change is propagated from an underlying model", function() {
+      var filterFired = 0;
+      collection.on("filter-complete", function() {
+        filterFired += 1;
+      });
+      collection.setFilter(createLessthanFilter(3));
+      filterFired = 0;
+
+      collection.models[0].trigger("change", collection.models[0], allModels)
+      expect(filterFired).toEqual(1);
+    });
+  });
+
+  describe("model - event:destroy", function() {
+    it("should just remove the model from the base collection like normal, and raise no problems with the filter", function() {
+      collection.setFilter(createLessthanFilter(5));
+      origModelZero = collection.models[0];
+      // simulate an ajax destroy
+      origModelZero.trigger("destroy", origModelZero, origModelZero.collection)
+
+      expect(collection.models[0].get("value")).toEqual(1)
+    });
+
+    it("should remove elements from the model as events occur", function() {
+      collection.setFilter(createLessthanFilter(10));
+
+      // start removing in weird orders, make sure vents are done properly
+      model = collection.models[0];
+      model.trigger("destroy", model, model.collection)
+      expect(collection.models[0].get("value")).toEqual(1)
+
+      model = collection.models[3];
+      model.trigger("destroy", model, model.collection)
+      expect(collection.models[3].get("value")).toEqual(5)
+
+      model = collection.models[3];
+      model.trigger("destroy", model, model.collection)
+      expect(collection.models[3].get("value")).toEqual(6)
+
+      model = collection.models[3];
+      model.trigger("destroy", model, model.collection)
+      expect(collection.models[3].get("value")).toEqual(7)
+
+      model = collection.models[2];
+      model.trigger("destroy", model, model.collection)
+      expect(collection.models[2].get("value")).toEqual(7)
+
+      model = collection.models[1];
+      model.trigger("destroy", model, model.collection)
+      expect(collection.models[1].get("value")).toEqual(7)
+    });
+
+    it("should create remove events for every deleted model", function() {
+      collection.setFilter(createLessthanFilter(10));
+      var lastModelRemoved = null;
+      var count = 0;
+      collection.on("remove", function(removedModel) {
+        lastModelRemoved = removedModel;
+        count += 1;
+      });
+
+      // start removing in weird orders, make sure vents are done properly
+      count = 0;
+      model = collection.models[0];
+      model.trigger("destroy", model, model.collection)
+      expect(lastModelRemoved).toEqual(model);
+      expect(count).toEqual(1);
+
+      count = 0;
+      model = collection.models[3];
+      model.trigger("destroy", model, model.collection)
+      expect(lastModelRemoved).toEqual(model);
+      expect(count).toEqual(1);
+
+      count = 0;
+      model = collection.models[3];
+      model.trigger("destroy", model, model.collection)
+      expect(lastModelRemoved).toEqual(model);
+      expect(count).toEqual(1);
+
+      count = 0;
+      model = collection.models[3];
+      model.trigger("destroy", model, model.collection)
+      expect(lastModelRemoved).toEqual(model);
+      expect(count).toEqual(1);
+
+      count = 0;
+      model = collection.models[2];
+      model.trigger("destroy", model, model.collection)
+      expect(lastModelRemoved).toEqual(model);
+      expect(count).toEqual(1);
+
+      count = 0;
+      model = collection.models[1];
+      model.trigger("destroy", model, model.collection)
+      expect(lastModelRemoved).toEqual(model);
+      expect(count).toEqual(1);
+    });
+  });
+
+  describe("model - event:change", function() {
+    it("should remove the model because it failed the filter post change", function() {
+      collection.setFilter(createLessthanFilter(5));
+      origModelZero = collection.models[0];
+      origModelZero.set("value", 10)
+
+      expect(collection.models.length).toEqual(4)
+      expect(collection.models[0].get("value")).toEqual(1)
+    });
+
+    it("should do nothing if the model is still passing the filter", function() {
+      collection.setFilter(createLessthanFilter(5));
+      origModelZero = collection.models[0];
+      origModelZero.set("value", 3)
+
+      expect(collection.models.length).toEqual(5)
+      expect(collection.models[0].get("value")).toEqual(3)
+    });
+
+    it("should add the model that is now passing the filter", function() {
+      collection.setFilter(createLessthanFilter(5));
+      origModelZero = allModels.models[9];
+      origModelZero.set("value", 2)
+
+      expect(collection.models.length).toEqual(6)
+      expect(collection.models[5].get("value")).toEqual(2)
+    });
+  });
+});