brainstem 0.2.2 → 0.2.4

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
++ **0.2.4** - _01/9/2014_
+
+  + `Brainstem::ControllerMethods#present_object` now simulates an only request (by providing the `only` parameter to Brainstem) when attempting to present a single model.
+
++ **0.2.3** - _11/21/2013_
+
+  + `Brainstem::ControllerMethods#present_object` now runs the default filters that are defined in the presenter.
+  
+  + `Brainstem.presenter_collection` now takes two optional options:
+    + `raise_on_empty` - Boolean that defaults to false and when set to true will raise an exception (default: `ActiveRecord::RecordNotFound`) when the result set is empty.
+    + `empty_error_class` - Exception class to raise when `raise_on_empty` is true.

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    brainstem (0.2.2)
-      activerecord (~> 3.0)
+    brainstem (0.2.4)
+      activerecord (>= 3.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -6,7 +6,7 @@ Brainstem is designed to power rich APIs in Rails. The Brainstem gem provides a
 
 ## Why Brainstem?
 
-* Seperate business and presentation logic with Presenters.
+* Separate business and presentation logic with Presenters.
 * Version your Presenters for consistency as your API evolves.
 * Expose end-user selectable filters and sorts.
 * Whitelist your existing scopes to act as API filters for your users.

data/brainstem.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Brainstem::VERSION
 
-  gem.add_dependency "activerecord", "~> 3.0"
+  gem.add_dependency "activerecord", ">= 3.0"
 
   gem.add_development_dependency "rake"
   gem.add_development_dependency "redcarpet" # for markdown in yard

data/lib/brainstem/association_field.rb

@@ -6,10 +6,14 @@ module Brainstem
     # @return [String] The name of the method that is being proxied.
     attr_reader :method_name
 
-    # @!attribute [r] json_name
+    # @!attribute [rw] json_name
     # @return [String] The name of the top-level JSON key for objects provided by this association.
     attr_accessor :json_name
 
+    # @!attribute [rw] restrict_to_only
+    # @return [Boolean] Option for this association to be restricted to only queries.
+    attr_accessor :restrict_to_only
+
     # @!attribute [r] block
     # @return [Proc] The block to be called when fetching models instead of calling a method on the model
     attr_reader :block
@@ -21,6 +25,7 @@ module Brainstem
       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]
+      @restrict_to_only = options[:restrict_to_only] || false
       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

data/lib/brainstem/controller_methods.rb

@@ -27,7 +27,8 @@ module Brainstem
     #                           only required if the name cannot be inferred.
     # @return (see PresenterCollection#presenting)
     def present_object(objects, options = {})
-      options.reverse_merge(:params => params)
+      options.merge!(:params => params)
+
       if objects.is_a?(ActiveRecord::Relation) || objects.is_a?(Array)
         raise ActiveRecord::RecordNotFound if objects.empty?
         klass = objects.first.class
@@ -35,9 +36,11 @@ module Brainstem
       else
         klass = objects.class
         ids = objects.id
+        options[:params][:only] = ids.to_s
       end
-      json_key = (options[:key_map] || {})[klass.to_s] || klass.table_name
-      present(klass, :as => json_key, :apply_default_filters => false){ klass.where(:id => ids) }
+
+      options[:as] = (options[:key_map] || {})[klass.to_s] || klass.table_name
+      present(klass, options) { klass.where(:id => ids) }
     end
     alias_method :present_objects, :present_object
   end

data/lib/brainstem/presenter_collection.rb

@@ -47,7 +47,7 @@ module Brainstem
       # key these models will use in the struct that is output
       options[:as] = (options[:as] || name.to_s.tableize).to_sym
 
-      allowed_includes = calculate_allowed_includes options[:presenter], presented_class
+      allowed_includes = calculate_allowed_includes options[:presenter], presented_class, options[:params][:only].present?
       includes_hash = filter_includes options[:params][:include], allowed_includes
 
       if searching? options
@@ -74,6 +74,12 @@ module Brainstem
 
       # Load Includes
       records = scope.to_a
+
+      # Determine if an exception should be raised on an empty result set.
+      if options[:raise_on_empty] && records.empty?
+        raise options[:empty_error_class] || ActiveRecord::RecordNotFound
+      end
+
       records = order_for_search(records, ordered_search_ids) if searching? options
       model = records.first
 
@@ -132,10 +138,15 @@ module Brainstem
     private
 
     def paginate(scope, options)
-      per_page = calculate_per_page(options)
-      page = calculate_page(options)
+      if options[:params][:limit].present? && options[:params][:offset].present?
+        limit = calculate_limit(options)
+        offset = calculate_offset(options)
+      else
+        limit = calculate_per_page(options)
+        offset = limit * (calculate_page(options) - 1)
+      end
 
-      [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.
+      [scope.limit(limit).offset(offset).uniq, scope.select("distinct #{scope.connection.quote_table_name options[:table_name]}.id").count] # as of Rails 3.2.5, uniq.count generates the wrong SQL.
     end
 
     def calculate_per_page(options)
@@ -148,13 +159,23 @@ module Brainstem
       [(options[:params][:page] || 1).to_i, 1].max
     end
 
+    def calculate_limit(options)
+      [[options[:params][:limit].to_i, 1].max, default_max_per_page].min
+    end
+
+    def calculate_offset(options)
+      [options[:params][:offset].to_i, 0].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)
+    def calculate_allowed_includes(presenter, presented_class, is_only_query)
       allowed_includes = {}
       model = presented_class.new
       presenter.present(model).each do |k, v|
         next unless v.is_a?(AssociationField)
+        next if v.restrict_to_only && !is_only_query
+
         if v.json_name
           v.json_name = v.json_name.tableize.to_sym
         else
@@ -229,10 +250,16 @@ module Brainstem
       search_options = HashWithIndifferentAccess.new(
           :include => includes,
           :order => { :sort_order => sort_name, :direction => direction },
-          :per_page => calculate_per_page(options),
-          :page => calculate_page(options)
       )
 
+      if options[:params][:limit].present? && options[:params][:offset].present?
+        search_options[:limit] = calculate_limit(options)
+        search_options[:offset] = calculate_offset(options)
+      else
+        search_options[:per_page] = calculate_per_page(options)
+        search_options[:page] = calculate_page(options)
+      end
+
       search_options.reverse_merge!(extract_filters(options))
 
       result_ids, count = options[:presenter].search_block.call(options[:params][:search], search_options)

data/lib/brainstem/version.rb

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

data/spec/brainstem/controller_methods_spec.rb

@@ -59,9 +59,22 @@ describe Brainstem::ControllerMethods do
         @controller.call_results[:block_result].pluck(:id).should == [1]
       end
 
-      it "passes :apply_default_filters => false to the PresenterCollection so that filters are not applied by default" do
+      it "passes through the controller params" do
+        @controller.present_object(Workspace.find(1), :key_map => { "Workspace" => "your_workspaces" })
+        @controller.call_results[:options][:params].should == @controller.params.merge(:only => '1')
+      end
+
+      it "passes through supplied options" do
+        @controller.present_object(Workspace.find(1), :foo => :bar)
+        @controller.call_results[:options][:foo].should == :bar
+      end
+
+      it "adds an only param if there is only one object to present" do
         @controller.present_object(Workspace.find(1))
-        @controller.call_results[:options][:apply_default_filters].should == false
+        @controller.call_results[:options][:params][:only].should == "1"
+
+        @controller.present_object(Workspace.all)
+        @controller.call_results[:options][:params][:only].should be_nil
       end
     end
   end

data/spec/brainstem/presenter_collection_spec.rb

@@ -44,20 +44,98 @@ describe Brainstem::PresenterCollection do
       end
 
       describe "limits and offsets" do
-        it "honors the user's requested page size and page and returns counts" do
-          result = @presenter_collection.presenting("workspaces", :params => { :per_page => 1, :page => 2 }) { Workspace.order('id desc') }[:results]
-          result.length.should == 1
-          result.first[:id].should == Workspace.order('id desc')[1].id.to_s
-
-          result = @presenter_collection.presenting("workspaces", :params => { :per_page => 2, :page => 2 }) { Workspace.order('id desc') }[:results]
-          result.length.should == 2
-          result.map { |m| m[:id] }.should == Workspace.order('id desc')[2..3].map(&:id).map(&:to_s)
+        context "when only per_page and page are present" do
+          it "honors the user's requested page size and page and returns counts" do
+            result = @presenter_collection.presenting("workspaces", :params => { :per_page => 1, :page => 2 }) { Workspace.order('id desc') }[:results]
+            result.length.should == 1
+            result.first[:id].should == Workspace.order('id desc')[1].id.to_s
+
+            result = @presenter_collection.presenting("workspaces", :params => { :per_page => 2, :page => 2 }) { Workspace.order('id desc') }[:results]
+            result.length.should == 2
+            result.map { |m| m[:id] }.should == Workspace.order('id desc')[2..3].map(&:id).map(&:to_s)
+          end
+
+          it "defaults to 1 if the page number is less than 1" do
+            result = @presenter_collection.presenting("workspaces", :params => { :per_page => 1, :page => 0 }) { Workspace.order('id desc') }[:results]
+            result.length.should == 1
+            result.first[:id].should == Workspace.order('id desc')[0].id.to_s
+          end
         end
 
-        it "defaults to 1 if the page number is less than 1" do
-          result = @presenter_collection.presenting("workspaces", :params => { :per_page => 1, :page => 0 }) { Workspace.order('id desc') }[:results]
-          result.length.should == 1
-          result.first[:id].should == Workspace.order('id desc')[0].id.to_s
+        context "when only limit and offset are present" do
+          it "honors the user's requested limit and offset and returns counts" do
+            result = @presenter_collection.presenting("workspaces", :params => { :limit => 1, :offset => 2 }) { Workspace.order('id desc') }[:results]
+            result.length.should == 1
+            result.first[:id].should == Workspace.order('id desc')[2].id.to_s
+
+            result = @presenter_collection.presenting("workspaces", :params => { :limit => 2, :offset => 2 }) { Workspace.order('id desc') }[:results]
+            result.length.should == 2
+            result.map { |m| m[:id] }.should == Workspace.order('id desc')[2..3].map(&:id).map(&:to_s)
+          end
+
+          it "defaults to offset 0 if the passed offset is less than 0 and limit to 1 if the passed limit is less than 1" do
+            stub.proxy(@presenter_collection).calculate_offset(anything).times(1)
+            stub.proxy(@presenter_collection).calculate_limit(anything).times(1)
+            result = @presenter_collection.presenting("workspaces", :params => { :limit => -1, :offset => -1 }) { Workspace.order('id desc') }[:results]
+            result.length.should == 1
+            result.first[:id].should == Workspace.order('id desc')[0].id.to_s
+          end
+        end
+
+        context "when both sets of params are present" do
+          it "prefers limit and offset over per_page and page" do
+            result = @presenter_collection.presenting("workspaces", :params => { :limit => 1, :offset => 0, :per_page => 2, :page => 2 }) { Workspace.order('id desc') }[:results]
+            result.length.should == 1
+            result.first[:id].should == Workspace.order('id desc')[0].id.to_s
+          end
+
+          it "uses per_page and page if limit and offset are not complete" do
+            result = @presenter_collection.presenting("workspaces", :params => { :limit => 5, :per_page => 1, :page => 0 }) { Workspace.order('id desc') }[:results]
+            result.length.should == 1
+            result.first[:id].should == Workspace.order('id desc')[0].id.to_s
+
+            result = @presenter_collection.presenting("workspaces", :params => { :offset => 5, :per_page => 1, :page => 0 }) { Workspace.order('id desc') }[:results]
+            result.length.should == 1
+            result.first[:id].should == Workspace.order('id desc')[0].id.to_s
+          end
+        end
+      end
+
+      describe "raise_on_empty option" do
+        context "raise_on_empty is true" do
+          context "results are empty" do
+            it "should raise the provided error class when the empty_error_class option is provided" do
+              class MyException < Exception; end
+
+              lambda {
+                @presenter_collection.presenting("workspaces", :raise_on_empty => true, :empty_error_class => MyException) { Workspace.where(:id => nil) }
+              }.should raise_error(MyException)
+            end
+
+            it "should raise ActiveRecord::RecordNotFound when the empty_error_class option is not provided" do
+              lambda {
+                @presenter_collection.presenting("workspaces", :raise_on_empty => true) { Workspace.where(:id => nil) }
+              }.should raise_error(ActiveRecord::RecordNotFound)
+            end
+          end
+
+          context "results are not empty" do
+            it "should not raise an exception" do
+              Workspace.count.should > 0
+
+              lambda {
+                @presenter_collection.presenting("workspaces", :raise_on_empty => true) { Workspace.order('id desc') }
+              }.should_not raise_error
+            end
+          end
+        end
+
+        context "raise_on_empty is false" do
+          it "should not raise an exception when the results are empty" do
+            lambda { 
+              @presenter_collection.presenting("workspaces") { Workspace.where(:id => nil) }
+            }.should_not raise_error
+          end
         end
       end
 
@@ -198,6 +276,23 @@ describe Brainstem::PresenterCollection do
         result[:users][Workspace.first.lead_user.id.to_s].should be_present
       end
 
+      describe "restricted associations" do
+        it "does apply includes that are restricted to only queries in an only query" do
+          t = Task.first
+          result = @presenter_collection.presenting("tasks", :params => { :include => "restricted", :only => t.id.to_s }, :max_per_page => 2) { Task.where(:id => t.id) }
+          result[:tasks][t.id.to_s].keys.should include(:restricted_id)
+          result.keys.should include(:restricted_associations)
+        end
+
+        it "does not apply includes that are restricted to only queries in a non-only query" do
+          t = Task.first
+          result = @presenter_collection.presenting("tasks", :params => { :include => "restricted" }, :max_per_page => 2) { Task.where(:id => t.id) }
+
+          result[:tasks][t.id.to_s].keys.should_not include(:restricted_id)
+          result.keys.should_not include(:restricted_associations)
+        end
+      end
+
       describe "polymorphic associations" do
         it "works with polymorphic associations" do
           result = @presenter_collection.presenting("posts", :params => { :include => "subject" }) { Post.order('id desc') }
@@ -269,21 +364,21 @@ describe Brainstem::PresenterCollection do
 
       it "converts boolean parameters from strings to booleans" do
         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 = @presenter_collection.presenting("workspaces", :params => { :owned_by_bob => "false" }) { Workspace.where(nil) }
         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
         WorkspacePresenter.filter(:owned_by_bob) { |scope, string| string.should be_a(String); scope }
-        result = @presenter_collection.presenting("workspaces", :params => { :owned_by_bob => [1, 2] }) { Workspace.scoped }
+        result = @presenter_collection.presenting("workspaces", :params => { :owned_by_bob => [1, 2] }) { Workspace.where(nil) }
       end
 
       it "allows filters to be called with false as an argument" do
         WorkspacePresenter.filter(:nothing) { |scope, bool| bool ? scope.where(:id => nil) : scope }
-        result = @presenter_collection.presenting("workspaces", :params => { :nothing => "true" }) { Workspace.scoped }
+        result = @presenter_collection.presenting("workspaces", :params => { :nothing => "true" }) { Workspace.where(nil) }
         result[:workspaces].length.should eq(0)
-        result = @presenter_collection.presenting("workspaces", :params => { :nothing => "false" }) { Workspace.scoped }
+        result = @presenter_collection.presenting("workspaces", :params => { :nothing => "false" }) { Workspace.where(nil) }
         result[:workspaces].length.should_not eq(0)
       end
 
@@ -295,7 +390,7 @@ describe Brainstem::PresenterCollection do
           scope
         }
 
-        @presenter_collection.presenting("workspaces", :params => { :between => "1:10" }) { Workspace.scoped }
+        @presenter_collection.presenting("workspaces", :params => { :between => "1:10" }) { Workspace.where(nil) }
       end
 
       context "with defaults" do
@@ -346,27 +441,27 @@ describe Brainstem::PresenterCollection do
         end
 
         it "calls the named scope with default arguments" do
-          result = @presenter_collection.presenting("workspaces") { Workspace.scoped }
+          result = @presenter_collection.presenting("workspaces") { Workspace.where(nil) }
           result[:workspaces].keys.should eq(bob.workspaces.pluck(:id).map(&:to_s))
         end
 
         it "calls the named scope with given arguments" do
-          result = @presenter_collection.presenting("workspaces", :params => { :owned_by => jane.id.to_s }) { Workspace.scoped }
+          result = @presenter_collection.presenting("workspaces", :params => { :owned_by => jane.id.to_s }) { Workspace.where(nil) }
           result[:workspaces].keys.should eq(jane.workspaces.pluck(:id).map(&:to_s))
         end
 
         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 = @presenter_collection.presenting("workspaces") { Workspace.where(nil) }
           result[:workspaces].keys.should eq(%w[1 2 3 4])
 
-          result = @presenter_collection.presenting("workspaces", :params => { :numeric_description => "true" }) { Workspace.scoped }
+          result = @presenter_collection.presenting("workspaces", :params => { :numeric_description => "true" }) { Workspace.where(nil) }
           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 = @presenter_collection.presenting("workspaces", :params => { :numeric_description => "false" }) { Workspace.where(nil) }
           result[:workspaces].keys.should eq(%w[2 4])
         end
       end
@@ -503,6 +598,66 @@ describe Brainstem::PresenterCollection do
                 @presenter_collection.presenting("workspaces", :params => { :search => "blah", :order => "created_at:asc"}) { Workspace.order("id asc") }
               end
             end
+
+            describe "pagination" do
+              it "passes through limit and offset if they are requested" do
+                WorkspacePresenter.search do |string, options|
+                  options[:limit].should == 1
+                  options[:offset].should == 2
+                  [[1], 1]
+                end
+
+                @presenter_collection.presenting("workspaces", :params => { :search => "blah", :limit => 1, :offset => 2}) { Workspace.order("id asc") }
+              end
+
+              it "passes through only limit and offset if all pagination options are requested" do
+                WorkspacePresenter.search do |string, options|
+                  options[:limit].should == 1
+                  options[:offset].should == 2
+                  options[:per_page].should == nil
+                  options[:page].should == nil
+                  [[1], 1]
+                end
+
+                @presenter_collection.presenting("workspaces", :params => { :search => "blah", :limit => 1, :offset => 2, :per_page => 3, :page => 4}) { Workspace.order("id asc") }
+              end
+
+              it "passes through page and per_page when limit not present" do
+                WorkspacePresenter.search do |string, options|
+                  options[:limit].should == nil
+                  options[:offset].should == nil
+                  options[:per_page].should == 3
+                  options[:page].should == 4
+                  [[1], 1]
+                end
+
+                @presenter_collection.presenting("workspaces", :params => { :search => "blah", :offset => 2, :per_page => 3, :page => 4}) { Workspace.order("id asc") }
+              end
+
+              it "passes through page and per_page when offset not present" do
+                WorkspacePresenter.search do |string, options|
+                  options[:limit].should == nil
+                  options[:offset].should == nil
+                  options[:per_page].should == 3
+                  options[:page].should == 4
+                  [[1], 1]
+                end
+
+                @presenter_collection.presenting("workspaces", :params => { :search => "blah", :limit => 1, :per_page => 3, :page => 4}) { Workspace.order("id asc") }
+              end
+
+              it "passes through page and per_page by default" do
+                WorkspacePresenter.search do |string, options|
+                  options[:limit].should == nil
+                  options[:offset].should == nil
+                  options[:per_page].should == 20
+                  options[:page].should == 1
+                  [[1], 1]
+                end
+
+                @presenter_collection.presenting("workspaces", :params => { :search => "blah"}) { Workspace.order("id asc") }
+              end
+            end
           end
         end
 

data/spec/spec_helpers/db.rb

@@ -49,7 +49,7 @@ class Workspace < ActiveRecord::Base
   has_many :posts
 
   scope :owned_by, -> id { where(:user_id => id) }
-  scope :numeric_description, where(:description => ["1", "2", "3"])
+  scope :numeric_description, -> description { where(:description => ["1", "2", "3"]) }
 
   def lead_user
     user

data/spec/spec_helpers/presenters.rb

@@ -16,7 +16,8 @@ class TaskPresenter < Brainstem::Presenter
       :name         => model.name,
       :sub_tasks    => association(:sub_tasks),
       :other_tasks  => association(:sub_tasks, :json_name => "other_tasks"),
-      :workspace    => association(:workspace)
+      :workspace    => association(:workspace),
+      :restricted   => association(:json_name => "restricted_association", :restrict_to_only => true) { |model| model }
     }
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainstem
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,14 +9,14 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-25 00:00:00.000000000 Z
+date: 2014-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :runtime
@@ -24,7 +24,7 @@ dependencies:
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
@@ -132,6 +132,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - brainstem.gemspec
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - Guardfile
@@ -174,7 +175,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1101488451032288843
+      hash: 1278718761883180932
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -183,7 +184,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1101488451032288843
+      hash: 1278718761883180932
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25