brainstem 0.2.6.1 → 1.0.0.pre.1

data/brainstem.gemspec

@@ -17,12 +17,16 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Brainstem::VERSION
 
-  gem.add_dependency "activerecord", ">= 3.2"
+  gem.add_dependency "activerecord", ">= 4.1"
+  gem.add_dependency "activesupport", ">= 4.1"
 
   gem.add_development_dependency "rake"
   gem.add_development_dependency "redcarpet" # for markdown in yard
   gem.add_development_dependency "rr"
-  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "rspec", "~> 3.5"
   gem.add_development_dependency "sqlite3"
+  gem.add_development_dependency "database_cleaner"
   gem.add_development_dependency "yard"
+  gem.add_development_dependency "pry"
+  gem.add_development_dependency "pry-nav"
 end

data/lib/brainstem.rb

@@ -2,6 +2,9 @@ require "brainstem/version"
 require "brainstem/presenter"
 require "brainstem/presenter_collection"
 require "brainstem/controller_methods"
+require "brainstem/query_strategies/base_strategy"
+require "brainstem/query_strategies/filter_and_search"
+require "brainstem/query_strategies/filter_or_search"
 
 # The Brainstem module itself contains a +default_namespace+ class attribute and a few helpers that make managing +PresenterCollections+ and their corresponding namespaces easier.
 module Brainstem
@@ -26,18 +29,13 @@ module Brainstem
     @presenter_collection[namespace.to_s.downcase] ||= PresenterCollection.new
   end
 
+  # TODO: pull these into the presenter
+
   # Helper method to quickly add presenter classes that are in a namespace. For example, +add_presenter_class(Api::V1::UserPresenter, "User")+ would add +UserPresenter+ to the PresenterCollection for the +:v1+ namespace as the presenter for the +User+ class.
   # @param [Brainstem::Presenter] presenter_class The presenter class that is being registered.
   # @param [Array<String, Class>] klasses Classes that will be presented by the given presenter.
-  def self.add_presenter_class(presenter_class, *klasses)
-    presenter_collection(namespace_of(presenter_class)).add_presenter_class(presenter_class, *klasses)
-  end
-
-  # @param [Class] klass The Ruby class whose namespace we would like to know.
-  # @return [String] The name of the module containing the passed-in class.
-  def self.namespace_of(klass)
-    names = klass.to_s.split("::")
-    names[-2] ? names[-2] : default_namespace
+  def self.add_presenter_class(presenter_class, namespace, *klasses)
+    presenter_collection(namespace).add_presenter_class(presenter_class, *klasses)
   end
 
   # @return [Logger] The Brainstem logger. If Rails is loaded, defaults to the Rails logger. If Rails is not loaded, defaults to a STDOUT logger.
@@ -58,4 +56,22 @@ module Brainstem
   def self.logger=(logger)
     @logger = logger
   end
+
+  # Reset all PresenterCollection's Presenters, clear the known collections, and reset the default namespace.
+  # This is mostly intended for resetting between tests.
+  def self.reset!
+    if @presenter_collection
+      @presenter_collection.each do |namespace, collection|
+        collection.presenters.each do |klass, presenter|
+          presenter.reset! if presenter.respond_to?(:reset!)
+        end
+      end
+    end
+
+    Brainstem::Presenter.reset!
+    Brainstem::Presenter.reset_configuration!
+
+    @presenter_collection = {}
+    @default_namespace = nil
+  end
 end

data/lib/brainstem/concerns/controller_param_management.rb

@@ -0,0 +1,22 @@
+# Provide `brainstem_model_name` and `brainstem_plural_model_name` in controllers for use when accessing the `params` hash.
+
+module Brainstem
+  module Concerns
+    module ControllerParamManagement
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :brainstem_plural_model_name, :brainstem_model_name,
+                        instance_accessor: false, instance_reader: false, instance_writer: false
+      end
+
+      def brainstem_model_name
+        self.class.brainstem_model_name.to_s.presence || controller_name.singularize
+      end
+
+      def brainstem_plural_model_name
+        self.class.brainstem_plural_model_name.to_s.presence || brainstem_model_name.pluralize
+      end
+    end
+  end
+end

data/lib/brainstem/concerns/error_presentation.rb

@@ -0,0 +1,58 @@
+module Brainstem
+  module Concerns
+    module ErrorPresentation
+      extend ActiveSupport::Concern
+
+      # Given one or more error messages, return Brainstem-style errors, defaulting to type 'system'.
+      def brainstem_system_error(*messages)
+        options = messages.last.is_a?(Hash) ? messages.pop : {}
+        response = { :errors => [] }
+        messages.flatten.uniq.each do |message|
+          response[:errors] << {
+            :type => options[:type] || :system,
+            :message => message
+          }
+        end
+        response
+      end
+
+      # Given a model or models, outputs Brainstem-style errors, for example:
+      #  { :errors => [{ :type => 'validation', :field => :thing_id, :message => "Thing is required" }] }
+      # If given a rewrite_params hash, it will convert from an internal column name to an external name.
+      # Note: you must validate models prior to passing them into this method.  It does not call `valid?` on them.
+      def brainstem_model_error(object_or_objects, options = {})
+        json = { :errors => [] }
+
+        [object_or_objects].flatten.each.with_index do |object, index|
+          case object
+            when Hash
+              attribute = object[:field] || :base
+              json[:errors] << {
+                :type => object[:type] || 'validation',
+                :field => (options[:rewrite_params] || {}).reverse_merge(attribute => attribute).invert[attribute],
+                :message => object[:message] || raise(ArgumentError, "message required")
+              }
+            when String
+              json[:errors] << { :type => 'validation', :field => :base, :message => object }
+            else
+              object.errors.each do |attribute, attribute_error|
+                json[:errors] << {
+                  :type => 'validation',
+                  :field => (options[:rewrite_params] || {}).reverse_merge(attribute => attribute).invert[attribute],
+                  :message => brainstem_full_error_message(object, attribute, attribute_error),
+                  :index => index
+                }
+              end
+          end
+        end
+        json
+      end
+
+      # Helper to convert an attribute name (e.g., "thing_id") and error (e.g., "is invalid") into a combined full message.
+      # Also handles traditional "^You messed up"-style errors that should not be combined with humanized attribute names.
+      def brainstem_full_error_message(object, attribute, text)
+        text[0] == "^" ? text[1..-1] : object.errors.full_message(attribute, text)
+      end
+    end
+  end
+end

data/lib/brainstem/concerns/inheritable_configuration.rb

@@ -0,0 +1,29 @@
+require 'brainstem/dsl/configuration'
+
+module Brainstem
+  module Concerns
+    module InheritableConfiguration
+      extend ActiveSupport::Concern
+  
+      module ClassMethods
+        def configuration
+          @configuration ||= begin
+            if superclass.respond_to?(:configuration)
+              DSL::Configuration.new(superclass.configuration)
+            else
+              DSL::Configuration.new
+            end
+          end
+        end
+
+        def clear_configuration!
+          @configuration = nil
+        end
+      end
+
+      def configuration
+        self.class.configuration
+      end
+    end
+  end
+end

data/lib/brainstem/concerns/lookup.rb

@@ -0,0 +1,30 @@
+module Brainstem
+  module Concerns
+    module Lookup
+      extend ActiveSupport::Concern
+
+      def run_on_with_lookup(model, context, helper_instance)
+        context[:lookup][key_for_lookup][name] ||= begin
+          proc = options[:lookup]
+          lookup = helper_instance.instance_exec(context[:models], &proc)
+          if !options[:lookup_fetch].present? && !lookup.respond_to?(:[])
+            raise(StandardError, 'Brainstem expects the return result of the `lookup` to be a Hash since it must respond to [] in order to access the model\'s assocation(s). Default: lookup_fetch: lambda { |lookup, model| lookup[model.id] }`')
+          end
+
+          lookup
+        end
+
+        if options[:lookup_fetch]
+          proc = options[:lookup_fetch]
+          helper_instance.instance_exec(context[:lookup][key_for_lookup][name], model, &proc)
+        else
+          context[:lookup][key_for_lookup][name][model.id]
+        end
+      end
+
+      def key_for_lookup
+        raise(StandardError 'Implement `key_for_lookup` when including Lookup Module.')
+      end
+    end
+  end
+end

data/lib/brainstem/concerns/presenter_dsl.rb

@@ -0,0 +1,111 @@
+require 'brainstem/concerns/inheritable_configuration'
+require 'brainstem/dsl/association'
+require 'brainstem/dsl/field'
+require 'brainstem/dsl/conditional'
+
+require 'brainstem/dsl/base_block'
+require 'brainstem/dsl/conditionals_block'
+require 'brainstem/dsl/fields_block'
+require 'brainstem/dsl/associations_block'
+
+
+module Brainstem
+  module Concerns
+    module PresenterDSL
+      extend ActiveSupport::Concern
+      include Brainstem::Concerns::InheritableConfiguration
+
+      included do
+        reset_configuration!
+      end
+
+      module ClassMethods
+        def preload(*args)
+          configuration.array!(:preloads).concat args
+        end
+
+        def conditionals(&block)
+          ConditionalsBlock.new(configuration, &block)
+        end
+
+        def fields(&block)
+          FieldsBlock.new(configuration[:fields], &block)
+        end
+
+        def associations(&block)
+          AssociationsBlock.new(configuration, &block)
+        end
+
+        # Declare a helper module or block whose methods will be available in dynamic fields and associations.
+        def helper(mod = nil, &block)
+          if mod
+            configuration[:helpers] << mod
+          end
+
+          if block
+            configuration[:helpers] << Module.new.tap { |mod| mod.module_eval(&block) }
+          end
+        end
+
+        # @overload default_sort_order(sort_string)
+        #   Sets a default sort order.
+        #   @param [String] sort_string The sort order to apply by default while presenting. The string must contain the name of a sort order that has explicitly been declared using {sort_order}. The string may end in +:asc+ or +:desc+ to indicate the default order's direction.
+        #   @return [String] The new default sort order.
+        # @overload default_sort_order
+        #   @return [String] The default sort order, or nil if one is not set.
+        def default_sort_order(sort_string = nil)
+          configuration[:default_sort_order] = sort_string if sort_string
+          configuration[:default_sort_order]
+        end
+
+        # @overload sort_order(name, order)
+        #   @param [Symbol] name The name of the sort order.
+        #   @param [String] order The SQL string to use to sort the presented data.
+        # @overload sort_order(name, &block)
+        #   @yieldparam scope [ActiveRecord::Relation] The scope representing the data being presented.
+        #   @yieldreturn [ActiveRecord::Relation] A new scope that adds ordering requirements to the scope that was yielded.
+        #   Create a named sort order, either containing a string to use as ORDER in a query, or with a block that adds an order Arel predicate to a scope.
+        # @raise [ArgumentError] if neither an order string or block is given.
+        def sort_order(name, order = nil, &block)
+          raise ArgumentError, "A sort order must be given" unless block_given? || order
+          configuration[:sort_orders][name] = (block_given? ? block : order)
+        end
+
+        # @overload filter(name, options = {})
+        #   @param [Symbol] name The name of the scope that may be applied as a filter.
+        #   @option options [Object] :default If set, causes this filter to be applied to every request. If the filter accepts parameters, the value given here will be passed to the filter when it is applied.
+        # @overload filter(name, options = {}, &block)
+        #   @param [Symbol] name The filter can be requested using this name.
+        #   @yieldparam scope [ActiveRecord::Relation] The scope that the filter should use as a base.
+        #   @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 filter(name, options = {}, &block)
+          configuration[:filters][name] = [options, (block_given? ? block : nil)]
+        end
+
+        def search(&block)
+          configuration[:search] = block
+        end
+
+        def brainstem_key(key)
+          configuration[:brainstem_key] = key.to_s
+        end
+
+        def query_strategy(strategy)
+          configuration[:query_strategy] = strategy
+        end
+
+        # @api private
+        def reset_configuration!
+          configuration.array!(:preloads)
+          configuration.array!(:helpers)
+          configuration.nest!(:conditionals)
+          configuration.nest!(:fields)
+          configuration.nest!(:filters)
+          configuration.nest!(:sort_orders)
+          configuration.nest!(:associations)
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/controller_methods.rb

@@ -1,32 +1,38 @@
+require 'brainstem/concerns/controller_param_management'
+require 'brainstem/concerns/error_presentation'
+
 module Brainstem
 
   # ControllerMethods are intended to be included into controllers that will be handling requests for presented objects.
   # The present method will pass through +params+, so that any allowed and requested includes, filters, sort orders
   # will be applied to the presented data.
   module ControllerMethods
+    extend ActiveSupport::Concern
+    include Concerns::ControllerParamManagement
+    include Concerns::ErrorPresentation
 
     # Return a Ruby hash that contains models requested by the user's params and allowed
     # by the +name+ presenter's configuration.
     #
     # Pass the returned hash to the render method to convert it into a useful format.
     # For example:
-    #    render :json => present("post"){ Post.where(:draft => false) }
+    #    render :json => brainstem_present("post"){ Post.where(:draft => false) }
     # @param (see PresenterCollection#presenting)
     # @option options [String] :namespace ("none") the namespace to be presented from
     # @yield (see PresenterCollection#presenting)
     # @return (see PresenterCollection#presenting)
-    def present(name, options = {}, &block)
+    def brainstem_present(name, options = {}, &block)
       Brainstem.presenter_collection(options[:namespace]).presenting(name, options.reverse_merge(:params => params), &block)
     end
 
-    # Similar to ControllerMethods#present, but always returns all of the given objects, not just those that match any provided
-    # filters.
+    # Similar to ControllerMethods#brainstem_present, but always returns all of the given objects, not just those that
+    # match any provided filters.
     # @option options [String] :namespace ("none") the namespace to be presented from
     # @option options [Hash]   :key_map a Hash from Class name to json key name, if desired.
     #                           e.g., map 'SystemWidgets' objects to the 'widgets' key in the JSON.  This is
     #                           only required if the name cannot be inferred.
     # @return (see PresenterCollection#presenting)
-    def present_object(objects, options = {})
+    def brainstem_present_object(objects, options = {})
       options.merge!(:params => params, :apply_default_filters => false)
 
       if objects.is_a?(ActiveRecord::Relation) || objects.is_a?(Array)
@@ -39,9 +45,12 @@ module Brainstem
         options[:params][:only] = ids.to_s
       end
 
-      options[:as] = (options[:key_map] || {})[klass.to_s] || klass.table_name
-      present(klass, options) { klass.where(:id => ids) }
+      if options[:key_map]
+        raise "brainstem_present_object no longer accepts a :key_map.  Use brainstem_key annotations on your presenters instead."
+      end
+
+      brainstem_present(klass, options) { klass.where(:id => ids) }
     end
-    alias_method :present_objects, :present_object
+    alias_method :brainstem_present_objects, :brainstem_present_object
   end
 end

data/lib/brainstem/dsl/association.rb

@@ -0,0 +1,55 @@
+require 'brainstem/concerns/lookup'
+
+module Brainstem
+  module DSL
+    class Association
+      include Brainstem::Concerns::Lookup
+
+      attr_reader :name, :target_class, :description, :options
+
+      def initialize(name, target_class, description, options)
+        @name = name.to_s
+        @target_class = target_class
+        @description = description
+        @options = options
+      end
+
+      def method_name
+        if options[:dynamic] || options[:lookup]
+          nil
+        else
+          (options[:via].presence || name).to_s
+        end
+      end
+
+      def run_on(model, context, helper_instance = Object.new)
+        if options[:lookup]
+          run_on_with_lookup(model, context, helper_instance)
+        elsif options[:dynamic]
+          proc = options[:dynamic]
+          if proc.arity == 1
+            helper_instance.instance_exec(model, &proc)
+          else
+            helper_instance.instance_exec(&proc)
+          end
+        else
+          model.send(method_name)
+        end
+      end
+
+      def polymorphic?
+        target_class == :polymorphic
+      end
+
+      def always_return_ref_with_sti_base?
+        options[:always_return_ref_with_sti_base]
+      end
+
+      private
+
+      def key_for_lookup
+        :associations
+      end
+    end
+  end
+end