brainstem 0.2.1 → 0.2.2

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brainstem (0.2.1)
+    brainstem (0.2.2)
       activerecord (~> 3.0)
 
 GEM

data/README.md

@@ -1,5 +1,7 @@
 # Brainstem
 
+[![Build Status](https://travis-ci.org/mavenlink/brainstem.png)](https://travis-ci.org/mavenlink/brainstem)
+
 Brainstem is designed to power rich APIs in Rails. The Brainstem gem provides a presenter library that handles converting ActiveRecord objects into structured JSON and a set of API abstractions that allow users to request sorts, filters, and association loads, allowing for simpler implementations, fewer requests, and smaller responses.
 
 ## Why Brainstem?
@@ -12,6 +14,8 @@ Brainstem is designed to power rich APIs in Rails. The Brainstem gem provides a
 * Prevent data duplication by pulling associations into top-level hashes, easily indexable by ID.
 * Easy integration with Backbone.js.  "It's like Ember Data for Backbone.js!"
 
+Please [watch our talk about Brainstem from RailsConf 2013](http://www.confreaks.com/videos/2457-railsconf2013-introducing-brainstem-your-companion-for-rich-rails-apis).
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/brainstem/association_field.rb

@@ -3,19 +3,26 @@ module Brainstem
   # @api private
   class AssociationField
     # @!attribute [r] method_name
-    # @return [Symbol] The name of the method that is being proxied.
+    # @return [String] The name of the method that is being proxied.
     attr_reader :method_name
 
     # @!attribute [r] json_name
-    # @return [Symbol] The name of the top-level JSON key for objects provided by this association.
+    # @return [String] The name of the top-level JSON key for objects provided by this association.
     attr_accessor :json_name
 
+    # @!attribute [r] block
+    # @return [Proc] The block to be called when fetching models instead of calling a method on the model
+    attr_reader :block
+
     # @param method_name The name of the method being proxied. Not required if
     #   a block is passed instead.
     # @option options [Boolean] :json_name The name of the top-level JSON key for objects provided by this association.
-    def initialize(method_name = nil, options = {}, &block)
+    def initialize(*args, &block)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      method_name = args.first.to_sym if args.first.is_a?(String) || args.first.is_a?(Symbol)
       @json_name = options[:json_name]
       if block_given?
+        raise ArgumentError, "options[:json_name] is required when using a block" unless options[:json_name]
         raise ArgumentError, "Method name is invalid with a block" if method_name
         @block = block
       elsif method_name
@@ -29,7 +36,7 @@ module Brainstem
     # @param model The object to call the proxied method on.
     # @return The value returned by calling the method or block being proxied.
     def call(model)
-      @block ? @block.call : model.send(@method_name)
+      @block ? @block.call(model) : model.send(@method_name)
     end
   end
 end

data/lib/brainstem/presenter.rb

@@ -38,7 +38,7 @@ module Brainstem
     # @raise [ArgumentError] if neither an order string or block is given.
     def self.sort_order(name, order = nil, &block)
       raise ArgumentError, "A sort order must be given" unless block_given? || order
-      @sort_orders ||= {}
+      @sort_orders ||= HashWithIndifferentAccess.new
       @sort_orders[name] = (block_given? ? block : order)
     end
 
@@ -56,7 +56,7 @@ module Brainstem
     #   @yieldparam arg [Object] The argument passed when the filter was requested.
     #   @yieldreturn [ActiveRecord::Relation] A new scope that filters the scope that was yielded.
     def self.filter(name, options = {}, &block)
-      @filters ||= {}
+      @filters ||= HashWithIndifferentAccess.new
       @filters[name] = [options, (block_given? ? block : nil)]
     end
 
@@ -160,9 +160,9 @@ module Brainstem
             if reflection && reflection.options[:polymorphic]
               struct["#{key.to_s.singularize}_type".to_sym] = model.send("#{value.method_name}_type")
             end
-          elsif associations.include?(key)
+          elsif associations.include?(key.to_s)
             result = value.call(model)
-            if result.is_a?(Array)
+            if result.is_a?(Array) || result.is_a?(ActiveRecord::Relation)
               struct["#{key.to_s.singularize}_ids".to_sym] = result.map {|a| to_s_except_nil(a.is_a?(ActiveRecord::Base) ? a.id : a) }
             else
               if result.is_a?(ActiveRecord::Base)
@@ -199,8 +199,8 @@ module Brainstem
     end
 
     # An association on the object being presented that should be included in the presented data.
-    def association(method_name = nil, options = {}, &block)
-      AssociationField.new method_name, options, &block
+    def association(*args, &block)
+      AssociationField.new *args, &block
     end
 
     def to_s_except_nil(thing)

data/lib/brainstem/presenter_collection.rb

@@ -1,4 +1,5 @@
 require 'brainstem/association_field'
+require 'brainstem/search_unavailable_error'
 
 module Brainstem
   class PresenterCollection
@@ -18,6 +19,8 @@ module Brainstem
     end
 
     # The main presentation method, converting a model name and an optional scope into a hash structure, ready to be converted into JSON.
+    # If searching, Brainstem filtering, only, pagination, and ordering are skipped and should be implemented with your search solution.
+    # All request options are passed to the +search_block+ for your convenience.
     # @param [Class, String] name The class of the objects to be presented.
     # @param [Hash] options The options that will be applied as the objects are converted.
     # @option options [Hash] :params The +params+ hash included in a request for the presented object.
@@ -29,10 +32,11 @@ module Brainstem
     # @yield Must return a scope on the model +name+, which will then be presented.
     # @return [Hash] A hash of arrays of hashes. Top-level hash keys are pluralized model names, with values of arrays containing one hash per object that was found by the given given options.
     def presenting(name, options = {}, &block)
-      options[:params] ||= {}
+      options[:params] = HashWithIndifferentAccess.new(options[:params] || {})
       presented_class = (options[:model] || name)
       presented_class = presented_class.classify.constantize if presented_class.is_a?(String)
       scope = presented_class.instance_eval(&block)
+      count = 0
 
       # grab the presenter that knows about filters and sorting etc.
       options[:presenter] = for!(presented_class)
@@ -43,29 +47,36 @@ module Brainstem
       # key these models will use in the struct that is output
       options[:as] = (options[:as] || name.to_s.tableize).to_sym
 
-      # Filter
-      scope = run_filters scope, options
-
-      # Search
-      scope = run_search scope, options
+      allowed_includes = calculate_allowed_includes options[:presenter], presented_class
+      includes_hash = filter_includes options[:params][:include], allowed_includes
 
-      if options[:params][:only].present?
-        # Handle Only
-        scope, count = handle_only(scope, options[:params][:only])
+      if searching? options
+        # Search
+        sort_name, direction = calculate_sort_name_and_direction options
+        scope, count, ordered_search_ids = run_search(scope, includes_hash.keys.map(&:to_s), sort_name, direction, options)
       else
-        # Paginate
-        scope, count = paginate scope, options
-      end
+        # Filter
+        scope = run_filters scope, options
+
+        if options[:params][:only].present?
+          # Handle Only
+          scope, count = handle_only(scope, options[:params][:only])
+        else
+          # Paginate
+          scope, count = paginate scope, options
+        end
 
-      # Ordering
-      scope = handle_ordering scope, options
+        count = count.keys.length if count.is_a?(Hash)
+
+        # Ordering
+        scope = handle_ordering scope, options
+      end
 
       # Load Includes
       records = scope.to_a
+      records = order_for_search(records, ordered_search_ids) if searching? options
       model = records.first
 
-      allowed_includes = calculate_allowed_includes options[:presenter], presented_class, records
-      includes_hash = filter_includes options[:params][:include], allowed_includes
       models = perform_preloading records, includes_hash
       primary_models, associated_models = gather_associations(models, includes_hash)
       struct = { :count => count, options[:as] => [], :results => [] }
@@ -76,7 +87,7 @@ module Brainstem
 
         if models.length > 0
           presenter = for!(models.first.class)
-          assoc = includes_hash.to_a.find { |k, v| v[:json_name] == json_name }
+          assoc = includes_hash.to_a.find { |k, v| v.json_name == json_name }
           struct[json_name] = presenter.group_present(models, [])
         else
           struct[json_name] = []
@@ -118,34 +129,38 @@ module Brainstem
       self.for(klass) || raise(ArgumentError, "Unable to find a presenter for class #{klass}")
     end
 
-  private
+    private
 
     def paginate(scope, options)
-      max_per_page = (options[:max_per_page] || default_max_per_page).to_i
-      per_page = (options[:params][:per_page] || options[:per_page] || default_per_page).to_i
-      per_page = max_per_page if per_page > max_per_page
-      per_page = (options[:per_page] || default_per_page).to_i if per_page < 1
-
-      page = (options[:params][:page] || 1).to_i
-      page = 1 if page < 1
+      per_page = calculate_per_page(options)
+      page = calculate_page(options)
 
       [scope.limit(per_page).offset(per_page * (page - 1)).uniq, scope.select("distinct `#{options[:table_name]}`.id").count] # as of Rails 3.2.5, uniq.count generates the wrong SQL.
     end
 
+    def calculate_per_page(options)
+      per_page = [(options[:params][:per_page] || options[:per_page] || default_per_page).to_i, (options[:max_per_page] || default_max_per_page).to_i].min
+      per_page = default_per_page if per_page < 1
+      per_page
+    end
+
+    def calculate_page(options)
+      [(options[:params][:page] || 1).to_i, 1].max
+    end
+
     # Gather allowed includes by inspecting the presented hash.  For now, this requires that a new instance of the
     # presented class always be presentable.
-    def calculate_allowed_includes(presenter, presented_class, records)
+    def calculate_allowed_includes(presenter, presented_class)
       allowed_includes = {}
-      model = records.first || presented_class.new
+      model = presented_class.new
       presenter.present(model).each do |k, v|
         next unless v.is_a?(AssociationField)
-
         if v.json_name
-          v.json_name = v.json_name.tableize
+          v.json_name = v.json_name.tableize.to_sym
         else
           association = model.class.reflections[v.method_name]
           if !association.options[:polymorphic]
-            v.json_name = association && association.table_name
+            v.json_name = association && association.table_name.to_sym
             if v.json_name.nil?
               raise ":json_name is a required option for method-based associations (#{presented_class}##{v.method_name})"
             end
@@ -158,16 +173,13 @@ module Brainstem
 
     def filter_includes(user_includes, allowed_includes)
       filtered_includes = {}
-      (user_includes || "").split(',').each do |k|
+
+      (user_includes || '').split(',').each do |k|
         allowed = allowed_includes[k]
         if allowed
-          filtered_includes[k.to_sym] = {
-            :association => allowed.method_name.to_sym,
-            :json_name => allowed.json_name.try(:to_sym)
-          }
+          filtered_includes[k] = allowed
         end
       end
-
       filtered_includes
     end
 
@@ -177,6 +189,22 @@ module Brainstem
     end
 
     def run_filters(scope, options)
+      extract_filters(options).each do |filter_name, arg|
+        next if arg.nil?
+        filter_lambda = options[:presenter].filters[filter_name][1]
+
+        if filter_lambda
+          scope = filter_lambda.call(scope, *arg)
+        else
+          scope = scope.send(filter_name, *arg)
+        end
+      end
+
+      scope
+    end
+
+    def extract_filters(options)
+      filters_hash = {}
       run_defaults = options.has_key?(:apply_default_filters) ? options[:apply_default_filters] : true
 
       (options[:presenter].filters || {}).each do |filter_name, filter|
@@ -184,52 +212,92 @@ module Brainstem
         requested = requested.present? ? requested.to_s : nil
         requested = requested == "true" ? true : (requested == "false" ? false : requested)
 
-        filter_options, filter_lambda = filter
-        args = run_defaults ? (requested || filter_options[:default]) : requested
-        next if args.nil?
+        filter_options = filter[0]
+        args = run_defaults && requested.nil? ? filter_options[:default] : requested
+        filters_hash[filter_name] = args unless args.nil?
+      end
 
-        if filter_lambda
-          scope = filter_lambda.call(scope, *args)
-        else
-          scope = scope.send(filter_name, *args)
-        end
+      filters_hash
+    end
+
+    # Runs the current search_block and returns an array of [scope of the resulting ids, result count, result ids]
+    # If the search_block returns a falsy value a SearchUnavailableError is raised.
+    # Your search block should return a list of ids and the count of ids found, or false if search is unavailable.
+    def run_search(scope, includes, sort_name, direction, options)
+      return scope unless searching? options
+
+      search_options = HashWithIndifferentAccess.new(
+          :include => includes,
+          :order => { :sort_order => sort_name, :direction => direction },
+          :per_page => calculate_per_page(options),
+          :page => calculate_page(options)
+      )
+
+      search_options.reverse_merge!(extract_filters(options))
+
+      result_ids, count = options[:presenter].search_block.call(options[:params][:search], search_options)
+      if result_ids
+        [scope.where(:id => result_ids ), count, result_ids]
+      else
+        raise(SearchUnavailableError, 'Search is currently unavailable')
       end
+    end
 
-      scope
+    def searching?(options)
+      options[:params][:search] && options[:presenter].search_block.present?
     end
 
-    def run_search(scope, options)
-      return scope unless options[:params][:search] && options[:presenter].search_block.present?
+    def order_for_search(records, ordered_search_ids)
+      ids_to_position = {}
+      ordered_records = []
 
-      result_ids = options[:presenter].search_block.call(options[:params][:search])
-      scope.where(:id => result_ids )
+      ordered_search_ids.each_with_index do |id, index|
+        ids_to_position[id] = index
+      end
+
+      records.each do |record|
+        ordered_records[ids_to_position[record.id]] = record
+      end
+
+      ordered_records
     end
 
     def handle_ordering(scope, options)
-      default_column, default_direction = (options[:presenter].default_sort_order || "updated_at:desc").split(":")
-      sort_name, direction = (options[:params][:order] || "").split(":")
+      order, direction = calculate_order_and_direction(options)
+
+      case order
+        when Proc
+          order.call(scope, direction == "desc" ? "desc" : "asc")
+        when nil
+          scope
+        else
+          scope.order(order.to_s + " " + (direction == "desc" ? "desc" : "asc"))
+      end
+    end
+
+    def calculate_order_and_direction(options)
+      sort_name, direction = calculate_sort_name_and_direction(options)
       sort_orders = (options[:presenter].sort_orders || {})
+      order = sort_orders[sort_name]
 
-      if sort_name.present? && sort_orders[sort_name.to_sym]
-        order = sort_orders[sort_name.to_sym]
-      else
-        order = sort_orders[default_column.to_sym]
+      [order, direction]
+    end
+
+    def calculate_sort_name_and_direction(options)
+      default_column, default_direction = (options[:presenter].default_sort_order || "updated_at:desc").split(":")
+      sort_name, direction = (options[:params][:order] || "").split(":")
+      sort_orders = options[:presenter].sort_orders || {}
+      unless sort_name.present? && sort_orders[sort_name]
+        sort_name = default_column
         direction = default_direction
       end
 
-      case order
-      when Proc
-        order.call(scope, direction == "desc" ? "desc" : "asc")
-      when nil
-        scope
-      else
-        scope.order(order.to_s + " " + (direction == "desc" ? "desc" : "asc"))
-      end
+      [sort_name, direction]
     end
 
     def perform_preloading(records, includes_hash)
       records.tap do |models|
-        association_names_to_preload = includes_hash.values.map {|i| i[:association] }
+        association_names_to_preload = includes_hash.values.map {|i| i.method_name }
         if models.first
           reflections = models.first.reflections
           association_names_to_preload.reject! { |association| !reflections.has_key?(association) }
@@ -246,16 +314,17 @@ module Brainstem
       primary_models = []
 
       includes_hash.each do |include, include_data|
-        record_hash[include_data[:json_name]] ||= [] if include_data[:json_name]
+        record_hash[include_data.json_name] ||= [] if include_data.json_name
       end
 
       models.each do |model|
         primary_models << model
 
         includes_hash.each do |include, include_data|
-          models = Array(model.send(include_data[:association]))
-          if include_data[:json_name]
-            record_hash[include_data[:json_name]] += models
+          models = Array(include_data.call(model))
+
+          if include_data.json_name
+            record_hash[include_data.json_name] += models
           else
             # polymorphic associations' tables must be figured out now
             models.each do |record|

data/lib/brainstem/search_unavailable_error.rb

@@ -0,0 +1,4 @@
+module Brainstem
+  class SearchUnavailableError < StandardError
+  end
+end

data/lib/brainstem/version.rb

@@ -1,3 +1,3 @@
 module Brainstem
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/spec/brainstem/presenter_collection_spec.rb

@@ -10,6 +10,10 @@ describe Brainstem::PresenterCollection do
     @presenter_collection = Brainstem.presenter_collection
   end
 
+  let(:bob) { User.where(:username => "bob").first }
+  let(:bob_workspaces_ids) { bob.workspaces.map(&:id) }
+  let(:jane) { User.where(:username => "jane").first }
+
   describe "#presenting" do
     describe "#pagination" do
       before do
@@ -23,6 +27,7 @@ describe Brainstem::PresenterCollection do
 
       it "will not accept a per_page less than 1" do
         @presenter_collection.presenting("workspaces", :params => { :per_page => 0 }) { Workspace.order('id desc') }[:workspaces].length.should == 2
+        @presenter_collection.presenting("workspaces", :per_page => 0) { Workspace.order('id desc') }[:workspaces].length.should == 2
       end
 
       it "will accept strings" do
@@ -187,6 +192,12 @@ describe Brainstem::PresenterCollection do
         result[:users][Workspace.first.lead_user.id.to_s].should be_present
       end
 
+      it "can accept a lambda for the association and uses that when present" do
+        result = @presenter_collection.presenting("users", :params => { :include => "odd_workspaces" }) { User.where(:id => 1) }
+        result[:odd_workspaces][Workspace.first.id.to_s].should be_present
+        result[:users][Workspace.first.lead_user.id.to_s].should be_present
+      end
+
       describe "polymorphic associations" do
         it "works with polymorphic associations" do
           result = @presenter_collection.presenting("posts", :params => { :include => "subject" }) { Post.order('id desc') }
@@ -235,9 +246,6 @@ describe Brainstem::PresenterCollection do
         WorkspacePresenter.filter(:title) { |scope, title| scope.where(:title => title) }
       end
 
-      let(:bob) { User.where(:username => "bob").first }
-      let(:bob_workspaces_ids) { bob.workspaces.map(&:id) }
-
       it "limits records to those matching given filters" do
         result = @presenter_collection.presenting("workspaces", :params => { :owned_by => bob.id.to_s }) { Workspace.order("id desc") } # hit the API, filtering on owned_by:bob
         result[:workspaces].should be_present
@@ -260,9 +268,10 @@ describe Brainstem::PresenterCollection do
       end
 
       it "converts boolean parameters from strings to booleans" do
-        WorkspacePresenter.filter(:owned_by_bob) { |scope, boolean| boolean ? scope.where(:user_id => bob.id) : scope }
+        WorkspacePresenter.filter(:owned_by_bob) { |scope, boolean| boolean ? scope.where(:user_id => bob.id) : scope.where(:user_id => jane.id) }
         result = @presenter_collection.presenting("workspaces", :params => { :owned_by_bob => "false" }) { Workspace.scoped }
         result[:workspaces].values.find { |workspace| workspace[:title].include?("jane") }.should be
+        result[:workspaces].values.find { |workspace| workspace[:title].include?("bob") }.should_not be
       end
 
       it "ensures arguments are strings" do
@@ -320,6 +329,10 @@ describe Brainstem::PresenterCollection do
         it "allows the default value to be overridden" do
           result = @presenter_collection.presenting("workspaces", :params => { :owner => jane.id.to_s }) { Workspace.order('id desc') }
           result[:workspaces].keys.should match_array(jane.workspaces.map(&:id).map(&:to_s))
+
+          WorkspacePresenter.filter(:include_early_workspaces, :default => true) { |scope, bool| bool ? scope : scope.where("id > 3") }
+          result = @presenter_collection.presenting("workspaces", :params => { :include_early_workspaces => "false" }) { Workspace.unscoped }
+          result[:workspaces]["2"].should_not be_present
         end
       end
 
@@ -342,14 +355,19 @@ describe Brainstem::PresenterCollection do
           result[:workspaces].keys.should eq(jane.workspaces.pluck(:id).map(&:to_s))
         end
 
-        it "allows scopes that take no arguments" do
+        it "can use filters without lambdas in the presenter or model, but behaves strangely when false is given" do
           WorkspacePresenter.filter(:numeric_description)
+
           result = @presenter_collection.presenting("workspaces") { Workspace.scoped }
-          result[:workspaces].keys.should eq(bob.workspaces.pluck(:id).map(&:to_s))
+          result[:workspaces].keys.should eq(%w[1 2 3 4])
+
           result = @presenter_collection.presenting("workspaces", :params => { :numeric_description => "true" }) { Workspace.scoped }
-          result[:workspaces].keys.should =~ ["2", "4"]
-          result = @presenter_collection.presenting("workspaces", :params => { :numeric_description => "fadlse" }) { Workspace.scoped }
-          result[:workspaces].keys.should eq(bob.workspaces.pluck(:id).map(&:to_s))
+          result[:workspaces].keys.should eq(%w[2 4])
+
+          # This is probably not the behavior that the developer or user intends.  You should always use a one-argument lambda in your
+          # model scope declaration!
+          result = @presenter_collection.presenting("workspaces", :params => { :numeric_description => "false" }) { Workspace.scoped }
+          result[:workspaces].keys.should eq(%w[2 4])
         end
       end
     end
@@ -358,14 +376,133 @@ describe Brainstem::PresenterCollection do
       context "with search method defined" do
         before do
           WorkspacePresenter.search do |string|
-            [3,5]
+            [[5, 3], 2]
           end
         end
 
         context "and a search request is made" do
-          it "calls the search method" do
+          it "calls the search method and maintains the resulting order" do
+            result = @presenter_collection.presenting("workspaces", :params => { :search => "blah" }) { Workspace.order("id asc") }
+            result[:workspaces].keys.should eq(%w[5 3])
+            result[:count].should eq(2)
+          end
+
+          it "does not apply filters" do
+            mock(@presenter_collection).run_filters(anything, anything).times(0)
             result = @presenter_collection.presenting("workspaces", :params => { :search => "blah" }) { Workspace.order("id asc") }
-            result[:workspaces].keys.should eq(%w[3 5])
+          end
+
+          it "does not apply ordering" do
+            mock(@presenter_collection).handle_ordering(anything, anything).times(0)
+            result = @presenter_collection.presenting("workspaces", :params => { :search => "blah" }) { Workspace.order("id asc") }
+          end
+
+          it "does not try to handle only's" do
+            mock(@presenter_collection).handle_only(anything, anything).times(0)
+            result = @presenter_collection.presenting("workspaces", :params => { :search => "blah" }) { Workspace.order("id asc") }
+          end
+
+          it "does not apply pagination" do
+            mock(@presenter_collection).paginate(anything, anything).times(0)
+            result = @presenter_collection.presenting("workspaces", :params => { :search => "blah" }) { Workspace.order("id asc") }
+          end
+
+          it "keeps the records in the order returned by search" do
+            result = @presenter_collection.presenting("workspaces", :params => { :search => "blah" }) { Workspace.unscoped }
+
+          end
+
+          it "throws a SearchUnavailableError if the search block returns false" do
+            WorkspacePresenter.search do |string|
+              false
+            end
+
+            lambda {
+              @presenter_collection.presenting("workspaces", :params => { :search => "blah" }) { Workspace.unscoped }
+            }.should raise_error(Brainstem::SearchUnavailableError)
+          end
+
+          describe "passing options to the search block" do
+            it "passes the search method, the search string, includes, order, and paging options" do
+              WorkspacePresenter.filter(:owned_by) { |scope| scope }
+              WorkspacePresenter.search do |string, options|
+                string.should == "blah"
+                options[:include].should == ["tasks", "lead_user"]
+                options[:owned_by].should == false
+                options[:order][:sort_order].should == "updated_at"
+                options[:order][:direction].should == "desc"
+                options[:page].should == 2
+                options[:per_page].should == 5
+                [[1], 1] # returned ids, count - not testing this in this set of specs
+              end
+
+              @presenter_collection.presenting("workspaces", :params => { :search => "blah", :include => "tasks,lead_user", :owned_by => "false", :order => "updated_at:desc", :page => 2, :per_page => 5 }) { Workspace.order("id asc") }
+            end
+
+            describe "includes" do
+              it "throws out requested inlcudes that the presenter does not have associations for" do
+                WorkspacePresenter.search do |string, options|
+                  options[:include].should == []
+                  [[1], 1]
+                end
+
+                @presenter_collection.presenting("workspaces", :params => { :search => "blah", :include => "users"}) { Workspace.order("id asc") }
+              end
+            end
+
+            describe "filters" do
+              it "passes through the default filters if no filter is requested" do
+                WorkspacePresenter.filter(:owned_by, :default => true) { |scope| scope }
+                WorkspacePresenter.search do |string, options|
+                  options[:owned_by].should == true
+                  [[1], 1]
+                end
+
+                @presenter_collection.presenting("workspaces", :params => { :search => "blah" }) { Workspace.order("id asc") }
+              end
+
+              it "throws out requested filters that the presenter does not have" do
+                WorkspacePresenter.search do |string, options|
+                  options[:highest_rated].should be_nil
+                  [[1], 1]
+                end
+
+                @presenter_collection.presenting("workspaces", :params => { :search => "blah", :highest_rated => true}) { Workspace.order("id asc") }
+              end
+
+              it "does not pass through existing non-default filters that are not requested" do
+                WorkspacePresenter.filter(:owned_by) { |scope| scope }
+                WorkspacePresenter.search do |string, options|
+                  options.has_key?(:owned_by).should == false
+                  [[1], 1]
+                end
+
+                @presenter_collection.presenting("workspaces", :params => { :search => "blah"}) { Workspace.order("id asc") }
+              end
+            end
+
+            describe "orders" do
+              it "passes through the default sort order if no order is requested" do
+                WorkspacePresenter.default_sort_order("description:desc")
+                WorkspacePresenter.search do |string, options|
+                  options[:order][:sort_order].should == "description"
+                  options[:order][:direction].should == "desc"
+                  [[1], 1]
+                end
+
+                @presenter_collection.presenting("workspaces", :params => { :search => "blah"}) { Workspace.order("id asc") }
+              end
+
+              it "makes the sort order 'updated_at:desc' if the requested order doesn't match an existing sort order and there is no default" do
+                WorkspacePresenter.search do |string, options|
+                  options[:order][:sort_order].should == "updated_at"
+                  options[:order][:direction].should == "desc"
+                  [[1], 1]
+                end
+
+                @presenter_collection.presenting("workspaces", :params => { :search => "blah", :order => "created_at:asc"}) { Workspace.order("id asc") }
+              end
+            end
           end
         end
 
@@ -428,16 +565,33 @@ describe Brainstem::PresenterCollection do
         result[:results].map {|i| result[:workspaces][i[:id]][:description] }.should eq(%w(1 2 3 a b c))
       end
 
-      it "cleans the direction param" do
+      it "cleans the params" do
+        WorkspacePresenter.sort_order(:description, "workspaces.description")
+        WorkspacePresenter.default_sort_order("description:desc")
+
         result = @presenter_collection.presenting("workspaces", :params => { :order => "updated_at:drop table" }) { Workspace.where("id is not null") }
         result.keys.should =~ [:count, :workspaces, :results]
+
+        result = @presenter_collection.presenting("workspaces", :params => { :order => "drop table:desc" }) { Workspace.where("id is not null") }
+        result.keys.should =~ [:count, :workspaces, :results]
+        result[:results].map {|i| result[:workspaces][i[:id]][:description] }.should eq(%w(c b a 3 2 1))
       end
 
       it "can take a proc" do
-        WorkspacePresenter.sort_order(:description){ Workspace.order("workspaces.description") }
-        WorkspacePresenter.default_sort_order("description:asc")
+        WorkspacePresenter.sort_order(:id) { |scope, direction| scope.order("workspaces.id #{direction}") }
+        WorkspacePresenter.default_sort_order("id:asc")
+
+        # Default
         result = @presenter_collection.presenting("workspaces") { Workspace.where("id is not null") }
-        result[:results].map {|i| result[:workspaces][i[:id]][:description] }.should eq(%w(1 2 3 a b c))
+        result[:results].map {|i| result[:workspaces][i[:id]][:description] }.should eq(%w(a 1 b 2 c 3))
+
+        # Asc
+        result = @presenter_collection.presenting("workspaces", :params => { :order => "id:asc" }) { Workspace.where("id is not null") }
+        result[:results].map {|i| result[:workspaces][i[:id]][:description] }.should eq(%w(a 1 b 2 c 3))
+
+        # Desc
+        result = @presenter_collection.presenting("workspaces", :params => { :order => "id:desc" }) { Workspace.where("id is not null") }
+        result[:results].map {|i| result[:workspaces][i[:id]][:description] }.should eq(%w(3 c 2 b 1 a))
       end
     end
 
@@ -447,6 +601,24 @@ describe Brainstem::PresenterCollection do
         result.keys.should eq([:count, :my_workspaces, :results])
       end
     end
+
+    describe "the count top level key" do
+      it "should return the total number of matched records" do
+        WorkspacePresenter.filter(:owned_by) { |scope, user_id| scope.owned_by(user_id.to_i) }
+
+        result = @presenter_collection.presenting("workspaces") { Workspace.where(:id => 1) }
+        result[:count].should == 1
+
+        result = @presenter_collection.presenting("workspaces") { Workspace.unscoped }
+        result[:count].should == Workspace.count
+
+        result = @presenter_collection.presenting("workspaces", :params => { :owned_by => bob.to_param }) { Workspace.unscoped }
+        result[:count].should == Workspace.owned_by(bob.to_param).count
+
+        result = @presenter_collection.presenting("workspaces", :params => { :owned_by => bob.to_param }) { Workspace.group(:id) }
+        result[:count].should == Workspace.owned_by(bob.to_param).count
+      end
+    end
   end
 
   describe "collection methods" do

data/spec/brainstem/presenter_spec.rb

@@ -71,7 +71,7 @@ describe Brainstem::Presenter do
 
       it "creates an entry in the filters class ivar" do
         @klass.filter(:foo, :default => true) { 1 }
-        @klass.filters[:foo][0].should eq({:default => true})
+        @klass.filters[:foo][0].should eq({"default" => true})
         @klass.filters[:foo][1].should be_a(Proc)
       end
 
@@ -189,7 +189,8 @@ describe Brainstem::Presenter do
                 :user                       => association(:user),
                 :something                  => association(:user),
                 :lead_user                  => association(:lead_user),
-                :lead_user_with_lambda      => association { model.user },
+                :lead_user_with_lambda      => association(:json_name => "users") { |model| model.user },
+                :tasks_with_lambda          => association(:json_name => "tasks") { |model| Task.where(:workspace_id => model) },
                 :synthetic                  => association(:synthetic)
             }
           end
@@ -206,23 +207,24 @@ describe Brainstem::Presenter do
 
       it "should convert requested has_many associations (includes) into the <association>_ids format" do
         @workspace.tasks.length.should > 0
-        @presenter.present_and_post_process(@workspace, [:tasks])[:task_ids].should =~ @workspace.tasks.map(&:id).map(&:to_s)
+        @presenter.present_and_post_process(@workspace, ["tasks"])[:task_ids].should =~ @workspace.tasks.map(&:id).map(&:to_s)
       end
 
       it "should convert requested belongs_to and has_one associations into the <association>_id format when requested" do
-        @presenter.present_and_post_process(@workspace, [:user])[:user_id].should == @workspace.user.id.to_s
+        @presenter.present_and_post_process(@workspace, ["user"])[:user_id].should == @workspace.user.id.to_s
       end
 
       it "converts non-association models into <model>_id format when they are requested" do
-        @presenter.present_and_post_process(@workspace, [:lead_user])[:lead_user_id].should == @workspace.lead_user.id.to_s
+        @presenter.present_and_post_process(@workspace, ["lead_user"])[:lead_user_id].should == @workspace.lead_user.id.to_s
       end
 
       it "handles associations provided with lambdas" do
-        @presenter.present_and_post_process(@workspace, [:lead_user_with_lambda])[:lead_user_with_lambda_id].should == @workspace.lead_user.id.to_s
+        @presenter.present_and_post_process(@workspace, ["lead_user_with_lambda"])[:lead_user_with_lambda_id].should == @workspace.lead_user.id.to_s
+        @presenter.present_and_post_process(@workspace, ["tasks_with_lambda"])[:tasks_with_lambda_ids].should == @workspace.tasks.map(&:id).map(&:to_s)
       end
 
       it "should return <association>_id fields when the given association ids exist on the model whether it is requested or not" do
-        @presenter.present_and_post_process(@workspace, [:user])[:user_id].should == @workspace.user_id.to_s
+        @presenter.present_and_post_process(@workspace, ["user"])[:user_id].should == @workspace.user_id.to_s
 
         json = @presenter.present_and_post_process(@workspace, [])
         json.keys.should =~ [:user_id, :something_id, :id, :updated_at]
@@ -233,10 +235,10 @@ describe Brainstem::Presenter do
       it "should return null, not empty string when ids are missing" do
         @workspace.user = nil
         @workspace.tasks = []
-        @presenter.present_and_post_process(@workspace, [:lead_user_with_lambda])[:lead_user_with_lambda_id].should == nil
-        @presenter.present_and_post_process(@workspace, [:user])[:user_id].should == nil
-        @presenter.present_and_post_process(@workspace, [:something])[:something_id].should == nil
-        @presenter.present_and_post_process(@workspace, [:tasks])[:task_ids].should == []
+        @presenter.present_and_post_process(@workspace, ["lead_user_with_lambda"])[:lead_user_with_lambda_id].should == nil
+        @presenter.present_and_post_process(@workspace, ["user"])[:user_id].should == nil
+        @presenter.present_and_post_process(@workspace, ["something"])[:something_id].should == nil
+        @presenter.present_and_post_process(@workspace, ["tasks"])[:task_ids].should == []
       end
 
       context "when the model has an <association>_id method but no column" do

data/spec/spec_helpers/presenters.rb

@@ -24,7 +24,10 @@ end
 class UserPresenter < Brainstem::Presenter
   def present(model)
     {
-      :username => model.username
+      :username => model.username,
+      :odd_workspaces => association(:json_name => "odd_workspaces") { |user|
+        user.workspaces.select { |workspace| workspace.id % 2 == 1 }
+      }
     }
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainstem
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-29 00:00:00.000000000 Z
+date: 2013-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -140,11 +140,14 @@ files:
 - lib/brainstem/engine.rb
 - lib/brainstem/presenter.rb
 - lib/brainstem/presenter_collection.rb
+- lib/brainstem/search_unavailable_error.rb
 - lib/brainstem/time_classes.rb
 - lib/brainstem/version.rb
 - lib/brainstem.rb
 - LICENSE
 - pkg/brainstem-0.0.2.gem
+- pkg/brainstem-0.2.1.gem
+- pkg/brainstem-0.2.2.gem
 - pkg/brainstem-0.2.gem
 - Rakefile
 - README.md
@@ -171,7 +174,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1746661046555689868
+      hash: 1101488451032288843
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -180,7 +183,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1746661046555689868
+      hash: 1101488451032288843
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25