wallaby 5.1.5 → 5.1.6

data/lib/adaptors/wallaby/active_record/model_finder.rb

@@ -2,7 +2,7 @@ module Wallaby
   class ActiveRecord
     # Model finder
     class ModelFinder < ::Wallaby::ModelFinder
-      # @return [Array] a list of ActiveRecord subclasses
+      # @return [Array<Class>] a list of ActiveRecord subclasses
       def all
         self.class.base.descendants.reject do |model_class|
           abstract?(model_class) || anonymous?(model_class) \
@@ -10,7 +10,8 @@ module Wallaby
         end.sort_by(&:to_s)
       end
 
-      # Base class should be either ApplicationRecord or ActiveRecord::Base
+      # This is only for ActiveRecord
+      # @return [ApplicationRecord, ActiveRecord::Base] base ActiveRecord class
       def self.base
         return ::ApplicationRecord if defined? ::ApplicationRecord
         ::ActiveRecord::Base
@@ -29,7 +30,7 @@ module Wallaby
       # @param [Class] model class
       # @return [Boolean]
       def anonymous?(model_class)
-        model_class.to_s.start_with? '#<Class'
+        Utils.anonymous_class? model_class
       end
 
       # Is model class the shcema migration class?

data/lib/adaptors/wallaby/active_record/model_pagination_provider.rb

@@ -8,20 +8,17 @@ module Wallaby
         @collection.respond_to? :total_count
       end
 
-      # Total count for the query
-      # @return [Integer]
+      # @return [Integer] total count for the query
       def total
         @collection.total_count
       end
 
-      # Page size
-      # @return [Integer]
+      # @return [Integer] page size from parameters or configuration
       def page_size
         @params[:per].try(:to_i) || Wallaby.configuration.pagination.page_size
       end
 
-      # Page number
-      # @return [Integer]
+      # @return [Integer] page number from parameters
       def page_number
         [@params[:page].to_i, 1].max
       end

data/lib/adaptors/wallaby/active_record/model_service_provider.rb

@@ -4,20 +4,29 @@ module Wallaby
     # @see Wallaby::ModelServiceProvider
     class ModelServiceProvider < ::Wallaby::ModelServiceProvider
       # @see Wallaby::ModelServiceProvider#permit
+      # @param params [ActionController::Parameters]
+      # @return [ActionController::Parameters] whitelisted parameters
       def permit(params)
         params.require(param_key).permit permitted_fields
       end
 
+      # NOTE: pagination free here.
+      # Since somewhere might need the collection without any pagination
       # @see Wallaby::ModelServiceProvider#collection
+      # @param params [ActionController::Parameters]
+      # @param authorizer [Ability] for now
+      # @return [ActiveRecord::Relation]
       def collection(params, authorizer)
-        # NOTE: pagination free here
-        # since somewhere might use it without pagination
         query = querier.search params
         query = query.order params[:sort] if params[:sort].present?
         query.accessible_by authorizer
       end
 
+      # Paginate
       # @see Wallaby::ModelServiceProvider#paginate
+      # @param query [ActiveRecord::Relation]
+      # @param params [ActionController::Parameters]
+      # @param [ActiveRecord::Relation] paginated query
       def paginate(query, params)
         per = params[:per] || Wallaby.configuration.pagination.page_size
         query = query.page params[:page] if query.respond_to? :page
@@ -60,7 +69,7 @@ module Wallaby
 
       protected
 
-      # Save the active record
+      # Save the ActiveRecord
       # @param action [String] `create`, `update`
       # @param resource [Object]
       # @param _params [ActionController::Parameters]

data/lib/adaptors/wallaby/active_record/model_service_provider/normalizer.rb

@@ -1,12 +1,15 @@
 module Wallaby
   class ActiveRecord
     class ModelServiceProvider
-      # Normalizer
+      # @private
+      # Normalize the values for a model
       class Normalizer
+        # @param model_decorator [Wallaby::ModelDecorator]
         def initialize(model_decorator)
           @model_decorator = model_decorator
         end
 
+        # @param params [ActionController::Parameters]
         def normalize(params)
           params.each do |field_name, values|
             type = @model_decorator.metadata_of(field_name)[:type]
@@ -16,6 +19,10 @@ module Wallaby
           end
         end
 
+        # Turn values into range
+        # @param params [ActionController::Parameters]
+        # @param field_name [String]
+        # @param values [Array]
         def normalize_range_values(params, field_name, values)
           normalized = Array(values).map(&:presence).compact
           params[field_name] =
@@ -24,6 +31,10 @@ module Wallaby
             end
         end
 
+        # Turn values into points
+        # @param params [ActionController::Parameters]
+        # @param field_name [String]
+        # @param values [Array]
         def normalize_point_values(params, field_name, values)
           normalized = Array(values).map(&:presence).compact
           params[field_name] =
@@ -31,6 +42,10 @@ module Wallaby
             values.map(&:to_f) || nil
         end
 
+        # Turn values into binary
+        # @param params [ActionController::Parameters]
+        # @param field_name [String]
+        # @param values [Object]
         def normalize_binary_values(params, field_name, values)
           params[field_name] =
             values.is_a?(::ActionDispatch::Http::UploadedFile) &&

data/lib/adaptors/wallaby/active_record/model_service_provider/permitter.rb

@@ -1,12 +1,15 @@
 module Wallaby
   class ActiveRecord
     class ModelServiceProvider
+      # @private
       # Filter the params
       class Permitter
+        # @param model_decorator [Wallaby::ModelDecorator]
         def initialize(model_decorator)
           @model_decorator = model_decorator
         end
 
+        # @return [Array<String>] a list of field names of general types
         def simple_field_names
           field_names =
             non_range_fields.keys +
@@ -17,6 +20,7 @@ module Wallaby
           field_names.reject { |field_name| fields.include? field_name }
         end
 
+        # @return [Array<String>] a list of field names of range and association
         def compound_hashed_fields
           field_names =
             range_fields.keys +
@@ -26,33 +30,41 @@ module Wallaby
 
         protected
 
+        # @return [Array<String>] a list of field names that ain't association
         def non_association_fields
           @model_decorator
             .fields.reject { |_, metadata| metadata[:is_association] }
         end
 
+        # @return [Array<String>] a list of field names that ain't range
         def non_range_fields
           non_association_fields
             .reject { |_, metadata| /range|point/ =~ metadata[:type] }
         end
 
+        # @return [Array<String>] a list of range field names
         def range_fields
           non_association_fields.select do |_, metadata|
             /range|point/ =~ metadata[:type]
           end
         end
 
+        # @return [Array<String>] a list of association field names
         def association_fields
           @model_decorator.fields.select do |_, metadata|
-            metadata[:is_association] &&
-              !metadata[:has_scope] && !metadata[:is_through]
+            metadata[:is_association] \
+              && !metadata[:has_scope] && !metadata[:is_through]
           end
         end
 
+        # @return [Array<String>] a list of many association field names:
+        #   - has_many
+        #   - has_and_belongs_to_many
         def many_association_fields
           association_fields.select { |_, metadata| /many/ =~ metadata[:type] }
         end
 
+        # @return [Array<String>] a list of belongs_to association field names
         def belongs_to_fields
           association_fields.select do |_field_name, metadata|
             metadata[:type] == 'belongs_to'

data/lib/adaptors/wallaby/active_record/model_service_provider/querier.rb

@@ -1,15 +1,22 @@
 module Wallaby
   class ActiveRecord
     class ModelServiceProvider
+      # @private
       # Query builder
       class Querier
         TEXT_FIELDS = %w(string text citext longtext tinytext mediumtext).freeze
 
+        # @param model_decorator [Wallaby::ModelDecorator]
         def initialize(model_decorator)
           @model_decorator = model_decorator
           @model_class = @model_decorator.model_class
         end
 
+        # Pull out the query expression string from the parameter `q`,
+        # use parser to understand the expression, then use transformer to run
+        # SQL arel query.
+        # @param params [ActionController::Parameters]
+        # @return [ActiveRecord::Relation]
         def search(params)
           filter_name, keywords, field_queries = extract params
           scope = filtered_by filter_name
@@ -20,18 +27,24 @@ module Wallaby
 
         private
 
+        # @see Wallaby::Parser
         def parser
           @parser ||= Parser.new
         end
 
+        # @see Wallaby::ActiveRecord::ModelServiceProvider::Querier::Transformer
         def transformer
           @transformer ||= Transformer.new
         end
 
+        # @return [Arel::Table] arel table
         def table
           @model_class.arel_table
         end
 
+        # @param params [ActionController::Parameters]
+        # @return [Array<String, Array, Array>] a list of object for other
+        #   method to use.
         def extract(params)
           expressions = to_expressions params
           keywords = expressions.select { |v| v.is_a? String }
@@ -40,33 +53,52 @@ module Wallaby
           [filter_name, keywords, field_queries]
         end
 
+        # @param params [ActionController::Parameters]
+        # @return [Array] a list of transformed operations
         def to_expressions(params)
           parsed = parser.parse(params[:q] || EMPTY_STRING)
           converted = transformer.apply parsed
           converted.is_a?(Array) ? converted : [converted]
         end
 
+        # Use the filter name to find out the scope in the following precedents:
+        # - scope from metadata
+        # - defined scope from the model
+        # - unscoped
+        # @param filter_name [String] filter name
+        # @return [ActiveRecord::Relation]
         def filtered_by(filter_name)
           valid_filter_name =
             Utils.find_filter_name(filter_name, @model_decorator.filters)
           scope = find_scope(valid_filter_name)
           if scope.blank? then unscoped
-          elsif scope.respond_to?(:call) then @model_class.instance_exec(&scope)
+          elsif scope.is_a?(Proc) then @model_class.instance_exec(&scope)
           elsif @model_class.respond_to?(scope)
             @model_class.public_send(scope)
           else unscoped
           end
         end
 
+        # Find out the scope for given filter
+        # - from metadata
+        # - filter name itself
+        # @param filter_name [String] filter name
+        # @return [String]
         def find_scope(filter_name)
           filter = @model_decorator.filters[filter_name] || {}
           filter[:scope] || filter_name
         end
 
+        # Unscoped query
+        # @return [ActiveRecord::Relation]
         def unscoped
           @model_class.where nil
         end
 
+        # Search text for the text columns that appear in `index_field_names`
+        # @param filter_name [String] filter name
+        # @param query [ActiveRecord::Relation, nil]
+        # @return [ActiveRecord::Relation]
         def text_search(keywords, query = nil)
           return query unless keywords_check? keywords
           text_fields.each do |field_name|
@@ -80,6 +112,10 @@ module Wallaby
           query
         end
 
+        # Perform SQL query for the colon query (e.g. data:<2000-01-01)
+        # @param field_queries [Array]
+        # @param query [ActiveRecord::Relation]
+        # @return [ActiveRecord::Relation]
         def field_search(field_queries, query)
           return query unless field_check? field_queries
           field_queries.each do |exp|
@@ -89,6 +125,7 @@ module Wallaby
           query
         end
 
+        # @return [Array<String>] a list of text fields from `index_field_names`
         def text_fields
           @text_fields ||= begin
             index_field_names = @model_decorator.index_field_names.map(&:to_s)
@@ -99,6 +136,10 @@ module Wallaby
           end
         end
 
+        # @param keywords [Array<String>] a list of keywords
+        # @return [Boolean] false when keywords are empty
+        #   true when text fields for query exist
+        #   otherwise, raise exception
         def keywords_check?(keywords)
           return false if keywords.blank?
           return true if text_fields.present?
@@ -106,6 +147,10 @@ module Wallaby
           raise UnprocessableEntity, message
         end
 
+        # @param field_queries [Array]
+        # @return [Boolean] false when field queries are blank
+        #   true when the fields used are valid (exist in `fields`)
+        #   otherwise, raise exception
         def field_check?(field_queries)
           return false if field_queries.blank?
           fields = field_queries.map { |exp| exp[:left] }

data/lib/adaptors/wallaby/active_record/model_service_provider/querier/transformer.rb

@@ -2,6 +2,7 @@ module Wallaby
   class ActiveRecord
     class ModelServiceProvider
       class Querier
+        # @private
         # Build up query using the results
         class Transformer < Parslet::Transform
           SIMPLE_OPERATORS = {
@@ -32,28 +33,33 @@ module Wallaby
             ':!()' => :not_between
           }.freeze
 
+          # For single keyword
           rule keyword: simple(:value) do
             value.try :to_str
           end
 
+          # For multiple keywords
           rule keyword: sequence(:value) do
             value.presence.try :map, :to_str
           end
 
+          # For operators
           rule left: simple(:left), op: simple(:op), right: simple(:right) do
             oped = op.try :to_str
             operator = SIMPLE_OPERATORS[oped]
             # skip if the operator is unknown
             next unless operator
             lefted = left.try :to_str
-            convert = case oped
-                      when ':~', ':!~' then "%#{right}%"
-                      when ':^', ':!^' then "#{right}%"
-                      when ':$', ':!$' then "%#{right}"
-                      end
+            convert =
+              case oped
+              when ':~', ':!~' then "%#{right}%"
+              when ':^', ':!^' then "#{right}%"
+              when ':$', ':!$' then "%#{right}"
+              end
             { left: lefted, op: operator, right: convert || right }
           end
 
+          # For operators that have multiple items
           rule left: simple(:left), op: simple(:op), right: sequence(:right) do
             oped = op.try :to_str
             operator = SEQUENCE_OPERATORS[oped]

data/lib/adaptors/wallaby/active_record/model_service_provider/validator.rb

@@ -1,12 +1,16 @@
 module Wallaby
   class ActiveRecord
     class ModelServiceProvider
+      # @private
       # Validator
       class Validator
+        # @param model_decorator [Wallaby::ModelDecorator]
         def initialize(model_decorator)
           @model_decorator = model_decorator
         end
 
+        # @param resource [Object] resource object
+        # @return [Boolean] whether the resource object is valid
         def valid?(resource)
           resource.attributes.each do |field_name, values|
             metadata = @model_decorator.fields[field_name]
@@ -18,6 +22,8 @@ module Wallaby
 
         private
 
+        # @param values [Array]
+        # @return [Boolean] whether the values are valid range values
         def valid_range_type?(values, metadata)
           !metadata \
             || !%w(daterange tsrange tstzrange).include?(metadata[:type]) \

data/lib/concerns/wallaby/resources_helper_methods.rb

@@ -0,0 +1,44 @@
+module Wallaby
+  # This is a collection of the helper methods used in controller and helper
+  module ResourcesHelperMethods
+    extend ActiveSupport::Concern
+
+    protected
+
+    # Shorthand of params[:id]
+    # @return [String, nil] ID param
+    def resource_id
+      params[:id]
+    end
+
+    # @return [#each] a collection of all the records
+    def collection
+      @collection ||= paginate current_model_service.collection params
+    end
+
+    # @return [Object] either persisted or unpersisted resource instance
+    def resource
+      @resource ||= begin
+        # white-listed params
+        whitelisted = action_name.in?(SAVE_ACTIONS) ? resource_params : {}
+        if resource_id.present?
+          current_model_service.find resource_id, whitelisted
+        else
+          current_model_service.new whitelisted
+        end
+      end
+    end
+
+    # @return [Wallaby::ModelDecorator, nil] current model decorator
+    def current_model_decorator
+      @current_model_decorator ||= helpers.model_decorator current_model_class
+    end
+
+    # A wrapper method for authorizer
+    # @todo to add support to pundit in the future
+    # @return [Ability]
+    def authorizer
+      current_ability
+    end
+  end
+end