brainstem 0.2.6.1 → 1.0.0.pre.1

data/lib/brainstem/presenter_validator.rb

@@ -0,0 +1,96 @@
+# Brainstem::PresenterValidator is a helper class that performs validity checks on a given presenter class.
+
+module Brainstem
+  class PresenterValidator
+    include ActiveModel::Validations
+    include ActiveModel::Validations::Callbacks
+
+    attr_accessor :presenter_class
+
+    def initialize(presenter_class)
+      @presenter_class = presenter_class
+    end
+
+    validate :preloads_exist
+    validate :fields_exist
+    validate :associations_exist
+    validate :conditionals_exist
+    validate :default_sort_is_used
+    validate :default_sort_matches_sort_order
+    validate :brainstem_key_is_provided
+
+    def preloads_exist
+      presenter_class.configuration[:preloads].each do |preload|
+        Array(preload.is_a?(Hash) ? preload.keys : preload).each do |association_name|
+          if presenter_class.presents.any? { |klass| !klass.new.respond_to?(association_name) }
+            errors.add(:preload, "not all presented classes respond to '#{association_name}'")
+          end
+        end
+      end
+    end
+
+    def fields_exist(fields = presenter_class.configuration[:fields])
+      fields.each do |name, field_or_fields|
+        case field_or_fields
+          when DSL::Field
+            method_name = field_or_fields.method_name
+            if method_name && presenter_class.presents.any? { |klass| !klass.new.respond_to?(method_name) }
+              errors.add(:fields, "'#{name}' is not valid because not all presented classes respond to '#{method_name}'")
+            end
+          when DSL::Configuration
+            fields_exist(field_or_fields)
+        end
+      end
+    end
+
+    def associations_exist(associations = presenter_class.configuration[:associations])
+      associations.each do |name, association|
+        method_name = association.method_name
+
+        if !association.polymorphic? && !Brainstem.presenter_collection.for(association.target_class)
+          errors.add(:associations, "'#{name}' is not valid because no presenter could be found for the #{association.target_class} class")
+        end
+
+        if method_name && presenter_class.presents.any? { |klass| !klass.new.respond_to?(method_name) }
+          errors.add(:associations, "'#{name}' is not valid because not all presented classes respond to '#{method_name}'")
+        end
+      end
+    end
+
+    def conditionals_exist(fields = presenter_class.configuration[:fields])
+      fields.each do |name, field_or_fields|
+        case field_or_fields
+          when DSL::Field
+            if field_or_fields.options[:if].present?
+              if Array.wrap(field_or_fields.options[:if]).any? { |conditional| presenter_class.configuration[:conditionals][conditional].nil? }
+                errors.add(:fields, "'#{name}' is not valid because one or more of the specified conditionals does not exist")
+              end
+            end
+          when DSL::Configuration
+            conditionals_exist(field_or_fields)
+        end
+      end
+    end
+
+    def default_sort_is_used
+      if presenter_class.configuration[:sort_orders].length > 0 && presenter_class.configuration[:default_sort_order].blank?
+        errors.add(:default_sort_order, "A default_sort_order is highly recommended if any sort_orders are declared")
+      end
+    end
+
+    def default_sort_matches_sort_order
+      if presenter_class.configuration[:default_sort_order].present?
+        default_sort_order = presenter_class.configuration[:default_sort_order].split(":").first.to_sym
+        if !presenter_class.configuration[:sort_orders][default_sort_order]
+          errors.add(:default_sort_order, "The declared default_sort_order ('#{default_sort_order}') does not match an existing sort_order")
+        end
+      end
+    end
+
+    def brainstem_key_is_provided
+      if !presenter_class.configuration[:brainstem_key] && presenter_class.presents.length > 1
+        errors.add(:brainstem_key, "a brainstem_key must be provided when multiple classes are presented.")
+      end
+    end
+  end
+end

data/lib/brainstem/query_strategies/README.md

@@ -0,0 +1,107 @@
+# Filtering/Searching Query Strategies
+
+Traditionally Brainstem has ignored all filters if you defined a `search` block in your presenter.
+Brainstem relies on your search implementation to do any necessary filtering. A downside of this is that you may have to
+implement your filters twice: once inside your presenters and once inside
+your searching solution. This causes extra work, particularly for complex queries and associations that the Brainstem DSL
+is well equipped to handle.
+
+The current version of Brainstem offers a beta feature for allowing both searching and filtering to take place. To enable it,
+add the following to your presenter:
+
+```ruby
+query_strategy :filter_and_search
+```
+
+The `query_strategy` DSL method can take a symbol or a lambda. If you pass it a lambda you can programmatically
+determine what strategy to use. Example:
+
+```ruby
+query_strategy lambda {
+  if current_user.filter_and_search?
+    :filter_and_search
+  else
+    :legacy
+  end
+}
+```
+
+Utilizing this strategy will enable Brainstem to take the intersection of your search results and your filter results,
+effectively giving you the best of both worlds: fast, efficient searching using something like ElasticSearch and in depth
+ActiveRecord filtering provided by Brainstem.
+
+You must take the following important notes into account when using the `filter_and_search` query strategy:
+
+- Your search block should behave the same as it always has: it should return an array where the first element is an array
+  of model ids and the second element is the total number of matched records.
+- This works by retrieving all possible ids from your search block (up to 10,000) and then applying your filters
+  on those returned ids. This has some obvious potential performance considerations as you are potentially returning
+  and querying off of 10,000 results.
+- If you have less than 10,000 possible results you shouldn't have to worry about ordering, because the order will
+  be applied in Brainstem on the intersection of filter and search results. However, if there is more than 10,000 your
+  searching implementation *must* perform the same ordering as your Brainstem filter. Otherwise the 10,000 results
+  from the search might not be the same 10,000 from the filter, and the intersection of the two would be incorrect.
+- This will not work if you have more than 10,000 entities and need to be able to return all of them (this will only
+  give you the first 10,000).
+
+This is not a perfect solution for all situations, which is why all presenters will default to the old behavior. You
+should only use the `filter_and_search` strategy if you've determined that:
+
+A.) Your API will still be fast enough when there are 10,000 possible results.
+
+B.) It's not critical for the user to be able to retrieve ALL possible results when searching.
+
+C.) It's actually important for your API that it support Brainstem filters and searching at the same time.
+
+D.) You either have less than 10,000 entities to search and filter from or do not need to be be able to return more than
+    10,000.
+
+# Other strategies
+
+- The default strategy is `filter_or_search` and is the same behavior that Brainstem has historically employed.
+
+# Implementing a strategy
+
+If you have a different filtering or searching strategy you would like to employ, you can create a strategy class
+in `lib/brainstem/query_strategies`. Your class should inherit from `BaseStrategy` and implement an `execute` method.
+The `execute` method should accept a current scope and return an array of models and the count of all possible modes.
+
+Example:
+
+```ruby
+module Brainstem
+  module QueryStrategies
+    class MyAwesomeFilterStrat < BaseStrategy
+      def execute(scope)
+        scope = do_something_awesome(scope)
+        count = scope.count
+        scope = paginate(scope)
+        [scope.to_a, count]
+      end
+    end
+  end
+end
+```
+
+You should then add the logic for using that strategy in the `strategy` method of `PresenterCollection`.
+
+Example:
+
+```ruby
+def strategy(options, scope)
+  strat = if options[:primary_presenter].configuration.has_key? :query_strategy
+            options[:primary_presenter].configuration[:query_strategy]
+          else
+            :legacy
+          end
+
+  return Brainstem::QueryStrategies::MyAwesomeFilterStrat.new(options) if strat == :my_awesome_filter_strat
+  return Brainstem::QueryStrategies::FilterOrSearch.new(options)
+end
+```
+
+This can then be enabled in a presenter with:
+
+```ruby
+query_strategy :my_awesome_filter_strat`.
+```

data/lib/brainstem/query_strategies/base_strategy.rb

@@ -0,0 +1,62 @@
+module Brainstem
+  module QueryStrategies
+    class NotImplemented < StandardError
+    end
+
+    class BaseStrategy
+      def initialize(options)
+        @options = options
+      end
+
+      def execute(scope)
+        raise NotImplemented, 'Your strategy class must implement an `execute` method'
+      end
+
+      def evaluate_scope(scope)
+        # Load models!
+        # On complex queries, MySQL can sometimes handle 'SELECT id FROM ... ORDER BY ...' much faster than
+        # 'SELECT * FROM ...', so we pluck the ids, then find those specific ids in a separate query.
+        if(ActiveRecord::Base.connection.instance_values["config"][:adapter] =~ /mysql|sqlite/i)
+          ids = scope.pluck("#{scope.table_name}.id")
+          id_lookup = {}
+          ids.each.with_index { |id, index| id_lookup[id] = index }
+          primary_models = scope.klass.where(id: id_lookup.keys).sort_by { |model| id_lookup[model.id] }
+        else
+          primary_models = scope.to_a
+        end
+      end
+
+      private
+
+      def calculate_limit
+        [[@options[:params][:limit].to_i, 1].max, (@options[:max_per_page] || @options[:default_max_per_page]).to_i].min
+      end
+
+      def calculate_offset
+        [@options[:params][:offset].to_i, 0].max
+      end
+
+      def calculate_per_page
+        per_page = [(@options[:params][:per_page] || @options[:per_page] || @options[:default_per_page]).to_i, (@options[:max_per_page] || @options[:default_max_per_page]).to_i].min
+        per_page = @options[:default_per_page] if per_page < 1
+        per_page
+      end
+
+      def calculate_page
+        [(@options[:params][:page] || 1).to_i, 1].max
+      end
+
+      def filter_includes
+        allowed_associations = @options[:primary_presenter].allowed_associations(@options[:params][:only].present?)
+
+        [].tap do |selected_associations|
+          (@options[:params][:include] || '').split(',').each do |k|
+            if association = allowed_associations[k]
+              selected_associations << association
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/query_strategies/filter_and_search.rb

@@ -0,0 +1,50 @@
+module Brainstem
+  module QueryStrategies
+    class FilterAndSearch < BaseStrategy
+      def execute(scope)
+        ordered_search_ids = run_search(scope, filter_includes.map(&:name))
+        scope = scope.where(id: ordered_search_ids)
+        scope = @options[:primary_presenter].apply_filters_to_scope(scope, @options[:params], @options)
+        scope = @options[:primary_presenter].apply_ordering_to_scope(scope, @options[:params])
+        count = scope.count
+        scope = paginate(scope)
+        primary_models = evaluate_scope(scope)
+
+        [primary_models, count]
+      end
+
+      private
+
+      def run_search(scope, includes)
+        sort_name, direction = @options[:primary_presenter].calculate_sort_name_and_direction @options[:params]
+        search_options = HashWithIndifferentAccess.new(
+          include: includes,
+          order: { sort_order: sort_name, direction: direction },
+          limit: @options[:default_max_filter_and_search_page],
+          offset: 0
+        )
+
+        search_options.reverse_merge!(@options[:primary_presenter].extract_filters(@options[:params], @options))
+
+        result_ids, _ = @options[:primary_presenter].run_search(@options[:params][:search], search_options)
+        if result_ids
+          result_ids
+        else
+          raise(SearchUnavailableError, 'Search is currently unavailable')
+        end
+      end
+
+      def paginate(scope)
+        if @options[:params][:limit].present? && @options[:params][:offset].present?
+          limit = calculate_limit
+          offset = calculate_offset
+        else
+          limit = calculate_per_page
+          offset = limit * (calculate_page - 1)
+        end
+
+        scope.limit(limit).offset(offset).distinct
+      end
+    end
+  end
+end

data/lib/brainstem/query_strategies/filter_or_search.rb

@@ -0,0 +1,103 @@
+module Brainstem
+  module QueryStrategies
+    class FilterOrSearch < BaseStrategy
+      def execute(scope)
+        if searching?
+          # Search
+          sort_name, direction = @options[:primary_presenter].calculate_sort_name_and_direction @options[:params]
+          scope, count, ordered_search_ids = run_search(scope, filter_includes.map(&:name), sort_name, direction)
+
+          # Load models!
+          primary_models = scope.to_a
+
+          primary_models = order_for_search(primary_models, ordered_search_ids)
+        else
+          # Filter
+
+          scope = @options[:primary_presenter].apply_filters_to_scope(scope, @options[:params], @options)
+
+          if @options[:params][:only].present?
+            # Handle Only
+            scope, count = handle_only(scope, @options[:params][:only])
+          else
+            # Paginate
+            scope, count = paginate scope
+          end
+
+          count = count.keys.length if count.is_a?(Hash)
+
+          # Ordering
+          scope = @options[:primary_presenter].apply_ordering_to_scope(scope, @options[:params])
+
+          primary_models = evaluate_scope(scope)
+        end
+
+        [primary_models, count]
+      end
+
+      private
+
+      def searching?
+        @options[:params][:search] && @options[:primary_presenter].configuration[:search].present?
+      end
+
+      def run_search(scope, includes, sort_name, direction)
+        return scope unless searching?
+
+        search_options = HashWithIndifferentAccess.new(
+          include: includes,
+          order: { sort_order: sort_name, direction: direction },
+        )
+
+        if @options[:params][:limit].present? && @options[:params][:offset].present?
+          search_options[:limit] = calculate_limit
+          search_options[:offset] = calculate_offset
+        else
+          search_options[:per_page] = calculate_per_page
+          search_options[:page] = calculate_page
+        end
+
+        search_options.reverse_merge!(@options[:primary_presenter].extract_filters(@options[:params], @options))
+
+        result_ids, count = @options[:primary_presenter].run_search(@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
+
+      def paginate(scope)
+        if @options[:params][:limit].present? && @options[:params][:offset].present?
+          limit = calculate_limit
+          offset = calculate_offset
+        else
+          limit = calculate_per_page
+          offset = limit * (calculate_page - 1)
+        end
+
+        [scope.limit(limit).offset(offset).distinct, scope.select("distinct #{scope.connection.quote_table_name @options[:table_name]}.id").count]
+      end
+
+      def handle_only(scope, only)
+        ids = (only || "").split(",").select {|id| id =~ /\A\d+\z/}.uniq
+        [scope.where(:id => ids), scope.where(:id => ids).count]
+      end
+
+      def order_for_search(records, ordered_search_ids)
+        ids_to_position = {}
+        ordered_records = []
+
+        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.compact
+      end
+    end
+  end
+end

data/lib/brainstem/test_helpers.rb

@@ -36,6 +36,10 @@ module Brainstem
         @json = JSON.parse(response_body)
       end
 
+      def results
+        BrainstemHelperCollection.new(@json['results'].map { |ref| @json[ref['key']][ref['id']] })
+      end
+
       def method_missing(name)
         data = @json[name.to_s].try(:values)
         BrainstemHelperCollection.new(data) unless data.nil?
@@ -51,7 +55,7 @@ module Brainstem
         end
 
         def ids
-          map { |item| item.id.to_i }
+          map { |item| item.id }
         end
 
         def by_id(id)

data/lib/brainstem/version.rb

@@ -1,3 +1,3 @@
 module Brainstem
-  VERSION = "0.2.6.1"
+  VERSION = "1.0.0.pre.1"
 end