wallaby 5.1.5 → 5.1.6

data/lib/services/wallaby/map.rb

@@ -1,90 +1,128 @@
 module Wallaby
-  # Global storage of all the maps for model classes
+  # @private
+  # Global mappings
   class Map
-    # { model => mode }
-    def self.mode_map
-      @mode_map ||= ModeMapper.new(Mode.descendants).map.freeze
-    end
+    class << self
+      # { model => mode }
+      # @return [Hash] { model => mode }
+      def mode_map
+        @mode_map ||= ModeMapper.new(Mode.descendants).map.freeze
+      end
 
-    # [ model classes ]
-    def self.model_classes
-      @model_classes ||=
-        ModelClassCollector.new(::Wallaby.configuration).collect.freeze
-    end
+      # @return [Array] [ model classes ]
+      def model_classes
+        @model_classes ||= ModelClassCollector.new(configuration).collect.freeze
+      end
 
-    # { model => controller }
-    def self.controller_map(model_class)
-      @controller_map ||= ModelClassMapper.new(ResourcesController).map
-      @controller_map[model_class] ||= ResourcesController
-    end
+      # { model => controller }
+      # @param model_class [Class]
+      # @return [Class] controller class
+      #   default to `mapping.resources_controller`
+      def controller_map(model_class)
+        @controller_map ||=
+          ModelClassMapper.new(mapping.resources_controller).map
+        @controller_map[model_class] ||= mapping.resources_controller
+      end
 
-    # { model => model decorator }
-    def self.model_decorator_map(model_class)
-      @model_decorator_map ||= {}
-      @model_decorator_map[model_class] ||= begin
-        mode = mode_map[model_class]
-        mode.model_decorator.new model_class if mode
+      # { model => model decorator }
+      # @param model_class [Class]
+      # @return [Wallaby::ModelDecorator] model decorator instance
+      def model_decorator_map(model_class)
+        @model_decorator_map ||= {}
+        @model_decorator_map[model_class] ||= begin
+          mode = mode_map[model_class]
+          mode.model_decorator.new model_class if mode # rubocop:disable Style/SafeNavigation, Metrics/LineLength
+        end
       end
-    end
 
-    # { model => resource decorator }
-    def self.resource_decorator_map(model_class)
-      @resource_decorator_map ||= ModelClassMapper.new(ResourceDecorator).map
-      @resource_decorator_map[model_class] ||= begin
-        ResourceDecorator if mode_map[model_class]
+      # { model => resource decorator }
+      # @param model_class [Class]
+      # @return [Class] resource decorator class
+      #   default to `mapping.resource_decorator`
+      def resource_decorator_map(model_class)
+        @resource_decorator_map ||=
+          ModelClassMapper.new(mapping.resource_decorator).map
+        @resource_decorator_map[model_class] ||= begin
+          mapping.resource_decorator if mode_map[model_class]
+        end
       end
-    end
 
-    # { model => servicer }
-    def self.servicer_map(model_class)
-      @servicer_map ||= ModelClassMapper.new(ModelServicer).map
-      @servicer_map[model_class] ||= begin
-        ModelServicer if mode_map[model_class]
+      # { model => servicer }
+      # @param model_class [Class]
+      # @return [Class] resource servicer class
+      #   default to `mapping.resource_servicer`
+      def servicer_map(model_class)
+        @servicer_map ||= ModelClassMapper.new(mapping.model_servicer).map
+        @servicer_map[model_class] ||= begin
+          mapping.model_servicer if mode_map[model_class]
+        end
       end
-    end
 
-    # { model => service_provider }
-    def self.service_provider_map(model_class)
-      @service_provider_map ||= {}
-      @service_provider_map[model_class] ||= begin
-        mode = mode_map[model_class]
-        mode.model_service_provider.new model_class if mode
+      # { model => service_provider }
+      # @param model_class [Class]
+      # @return [Wallaby::ModelServiceProvider] model service provider instance
+      def service_provider_map(model_class)
+        @service_provider_map ||= {}
+        @service_provider_map[model_class] ||= begin
+          mode = mode_map[model_class]
+          mode.model_service_provider.new model_class if mode # rubocop:disable Style/SafeNavigation, Metrics/LineLength
+        end
       end
-    end
 
-    # { model => paginator }
-    def self.paginator_map(model_class)
-      @paginator_map ||= ModelClassMapper.new(ResourcePaginator).map
-      @paginator_map[model_class] ||= begin
-        ResourcePaginator if mode_map[model_class]
+      # { model => paginator }
+      # @param model_class [Class]
+      # @return [Hash] { model => paginator }
+      def paginator_map(model_class)
+        @paginator_map ||= ModelClassMapper.new(mapping.resource_paginator).map
+        @paginator_map[model_class] ||= begin
+          mapping.resource_paginator if mode_map[model_class]
+        end
       end
-    end
 
-    # { model => pagination_provider }
-    def self.pagination_provider_map(model_class)
-      @pagination_provider_map ||= {}
-      @pagination_provider_map[model_class] ||=
-        mode_map[model_class].try(:model_pagination_provider)
-    end
+      # { model => pagination_provider }
+      # @param model_class [Class]
+      # @return [Class] model pagination provider class
+      def pagination_provider_map(model_class)
+        @pagination_provider_map ||= {}
+        @pagination_provider_map[model_class] ||=
+          mode_map[model_class].try(:model_pagination_provider)
+      end
 
-    # { model => resources name }
-    def self.resources_name_map(model_class)
-      @resources_name_map ||= {}
-      @resources_name_map[model_class] ||= Utils.to_resources_name model_class
-    end
+      # { model => resources name }
+      # @param model_class [Class]
+      # @return [String] resources name
+      def resources_name_map(model_class)
+        @resources_name_map ||= {}
+        @resources_name_map[model_class] ||= Utils.to_resources_name model_class
+      end
 
-    # { resources name => model }
-    def self.model_class_map(resources_name)
-      @model_class_map ||= {}
-      @model_class_map[resources_name] ||= Utils.to_model_class resources_name
-    end
+      # { resources name => model }
+      # @param resources_name [String]
+      # @return [Class] model class
+      def model_class_map(resources_name)
+        @model_class_map ||= {}
+        @model_class_map[resources_name] ||= Utils.to_model_class resources_name
+      end
 
-    # Clear all the class variables to nil
-    def self.clear
-      @mode_map, @model_classes, @controller_map, @model_decorator_map,
-      @resource_decorator_map, @servicer_map, @service_provider_map,
-      @paginator_map, @pagination_provider_map, @model_class_map,
-      @resources_name_map = []
+      # Clear all the class variables to nil
+      def clear
+        @mode_map, @model_classes, @controller_map, @model_decorator_map,
+        @resource_decorator_map, @servicer_map, @service_provider_map,
+        @paginator_map, @pagination_provider_map, @model_class_map,
+        @resources_name_map = []
+      end
+
+      private
+
+      # shorthand method
+      def configuration
+        ::Wallaby.configuration
+      end
+
+      # shorthand method
+      def mapping
+        configuration.mapping
+      end
     end
   end
 end

data/lib/services/wallaby/map/mode_mapper.rb

@@ -2,10 +2,12 @@ module Wallaby
   class Map
     # To map model class to mode class so that we know how to handle a model
     class ModeMapper
+      # @param model_class [Class] model class
       def initialize(mode_classes)
         @mode_classes = mode_classes
       end
 
+      # @return [Hash] { model_class => mode }
       def map
         return {} if @mode_classes.blank?
         @mode_classes.each_with_object({}) do |mode_class, map|

data/lib/services/wallaby/map/model_class_collector.rb

@@ -2,10 +2,12 @@ module Wallaby
   class Map
     # To collect model classes that are configured to be handled by Wallaby
     class ModelClassCollector
+      # @param configuration [Configuration]
       def initialize(configuration)
         @configuration = configuration
       end
 
+      # @return [Array<Class>] model class
       def collect
         return all_models - excluded_models if configured_models.blank?
         invalid_models_check
@@ -14,6 +16,7 @@ module Wallaby
 
       private
 
+      # Check if the models are valid, raise if invalid
       def invalid_models_check
         invalid_models = configured_models - all_models
         return if invalid_models.blank?
@@ -21,18 +24,22 @@ module Wallaby
         raise InvalidError, message
       end
 
+      # @return [Wallaby::Configuration::Models]
       def models
         @configuration.models
       end
 
+      # @return [Array<Class>] all the models that modes recognize
       def all_models
         Map.mode_map.keys
       end
 
+      # @return [Array<Class>] a list of models to exclude
       def excluded_models
         models.excludes
       end
 
+      # @return [Array<Class>] a list of models to set
       def configured_models
         models.presence
       end

data/lib/services/wallaby/map/model_class_mapper.rb

@@ -1,27 +1,35 @@
 module Wallaby
   class Map
-    # To map model class to a klass
+    # @private
+    # To find out all descendant classes and convert them if necessary.
     class ModelClassMapper
-      DEFAULT_BLOCK = ->(same) { same }.freeze
-
       def initialize(base_class)
         @base_class = base_class
       end
 
-      def map(&block)
-        block ||= DEFAULT_BLOCK
+      # @return [Array] a list of non-anonymous descendant classes
+      def map
         classes_array.each_with_object({}) do |klass, map|
           next if anonymous? klass
-          map[klass.model_class] = block.call klass
+          begin
+            map[klass.model_class] = block_given? ? yield(klass) : klass
+          rescue Wallaby::ModelNotFound
+            Rails.logger.error Utils.translate_class(
+              self, :missing_model_class, model: klass.name
+            )
+          end
         end
       end
 
       protected
 
+      # @param klass [Class]
+      # @return [Boolean] whether the class is anonymous
       def anonymous?(klass)
-        klass.name.blank?
+        Utils.anonymous_class? klass
       end
 
+      # @return [Array<Class>] all descendants
       def classes_array
         @base_class.try(:descendants) || EMPTY_ARRAY
       end

data/lib/services/wallaby/partial_renderer.rb

@@ -1,4 +1,5 @@
 module Wallaby
+  # @private
   # Partial renderer
   class PartialRenderer
     class << self
@@ -43,12 +44,18 @@ module Wallaby
 
       private
 
+      # Check and see if object and field_name are valid
+      # @param object [Object]
+      # @param field_name [String]
       def partial_arguments_check(object, field_name)
         raise ArgumentError, 'Field name is required.' if field_name.blank?
         raise ArgumentError, 'Object is not decorated.' \
           unless object.is_a? ResourceDecorator
       end
 
+      # Check and see if form and field_name are valid
+      # @param form [Object]
+      # @param field_name [String]
       def form_arguments_check(form, field_name)
         raise ArgumentError, 'Form is required.' if form.blank?
         raise ArgumentError, 'Field name is required.' if field_name.blank?

data/lib/services/wallaby/prefixes_builder.rb

@@ -1,6 +1,11 @@
 module Wallaby
+  # @private
   # Prefix builder
   class PrefixesBuilder
+    # @param origin_prefixes [Array<string>] a list of all the prefixes
+    # @param controller_path [String] controller path
+    # @param resources_name [String] resources name
+    # @param params [ActionController::Parameters]
     def initialize(origin_prefixes, controller_path, resources_name, params)
       @origin_prefixes = origin_prefixes
       @controller_path = controller_path
@@ -8,6 +13,7 @@ module Wallaby
       @params = params
     end
 
+    # @return [Array<String>] a list of all the prefixes
     def build
       prefixes = minimal_prefixes
       prefixes.unshift mounted_prefix if resource_path != @controller_path
@@ -19,26 +25,35 @@ module Wallaby
 
     protected
 
+    # @return [Array<String>] a list of prefixes starting from wallaby
     def minimal_prefixes
       # this should contains only the current controller's path and wallaby path
       index = @origin_prefixes.index wallaby_path
       @origin_prefixes.slice 0..index
     end
 
+    # @return [String] a prefix of the mouted path.
+    #   Given mounted path `admin`, and current resources `products`, it returns
+    #   `admin/products`
     def mounted_prefix
       prefix = mounted_path.try(:slice, 1..-1) || ''
       prefix << SLASH unless prefix.empty?
       prefix << resource_path if resource_path
     end
 
+    # Consolidate action name (new/create/edit/update) as `form`
+    # @param params [ActionController::Parameters]
+    # @return [String]
     def build_suffix(params)
       Utils.to_partial_name params[:action]
     end
 
+    # @return [String] path of `wallaby/resources`
     def wallaby_path
       ResourcesController.controller_path
     end
 
+    # @return [String] the path that Wallaby has mounted to
     def mounted_path
       # TODO: need to find out if this will fail
       # when wallaby is mounted more than once on different namespace?
@@ -47,6 +62,9 @@ module Wallaby
       end
     end
 
+    # Convert the resources name
+    # (e.g. `namespace::products` to `namespace/products`)
+    # @return [String] a path of the resources
     def resource_path
       @resource_path ||= @resources_name.try :gsub, COLONS, SLASH
     end

data/lib/services/wallaby/sorting/hash_builder.rb

@@ -1,9 +1,15 @@
 module Wallaby
   module Sorting
-    # Turn a string `'name asc,id desc'` into sort hash
+    # @private
+    # Turn a string e.g.`'name asc,id desc'` into sort
+    # hash e.g.`{name: 'asc', id: 'desc'}`
     class HashBuilder
       SORT_REGEX = /(([^\s,]+)\s+(asc|desc))\s*,?\s*/i
 
+      # Turn a string e.g.`'name asc,id desc'` into sort
+      # hash e.g.`{name: 'asc', id: 'desc'}`
+      # @param sort_string [String]
+      # @return [Hash] { field_name => 'asc|desc' }
       def self.build(sort_string)
         ::ActiveSupport::HashWithIndifferentAccess.new.tap do |hash|
           (sort_string || EMPTY_STRING).scan SORT_REGEX do |_, key, order|

data/lib/services/wallaby/sorting/link_builder.rb

@@ -1,9 +1,13 @@
 module Wallaby
   module Sorting
+    # @private
     # Build the sorting link
     class LinkBuilder
       delegate :model_class, to: :@model_decorator
 
+      # @param model_decorator [Wallaby::ModelDecorator]
+      # @param params [ActionController::Parameters]
+      # @param helper [ActionView::Helpers]
       def initialize(model_decorator, params, helper)
         @model_decorator = model_decorator
         @params = params
@@ -35,7 +39,8 @@ module Wallaby
         @next_builder ||= NextBuilder.new @params, current_sort
       end
 
-      # If it's non-association field or custom sorting field
+      # @return [Boolean]
+      #   whether it's non-association field or custom sorting field
       def sortable?(field_name, metadata)
         @model_decorator.fields[field_name] && !metadata[:is_association] \
           || metadata[:sort_field_name]

data/lib/services/wallaby/sorting/next_builder.rb

@@ -1,15 +1,25 @@
 module Wallaby
   module Sorting
-    # Pass field_name to generate sort param
+    # @private
+    # Pass field_name to generate sort param for its next sort order
+    # (e.g. from empty to `asc`, from `asc` to `desc`, from `desc` to empty)
     class NextBuilder
       ASC = 'asc'.freeze
       DESC = 'desc'.freeze
 
+      # @param params [ActionController::Parameters]
+      # @param hash [Hash, nil] sorting hash
       def initialize(params, hash = nil)
         @params = params
         @hash = hash || HashBuilder.build(params[:sort])
       end
 
+      # Update the `sort` parameter.
+      # @example for param `{sort: 'name asc'}`, it will update the parameters
+      #   to `{sort: 'name desc'}`
+      # @param field_name [String] field name
+      # @return [ActionController::Parameters]
+      #   updated parameters that update the sort order for given field
       def next_params(field_name)
         params = clean_params
         update params, :sort, complete_sorting_str_with(field_name)
@@ -18,10 +28,13 @@ module Wallaby
 
       protected
 
+      # @return [ActionController::Parameters] whitelisted parameters
       def clean_params
         @params.except :resources, :controller, :action
       end
 
+      # @param field_name [String] field name
+      # @return [String] a sort order string, e.g. `'name asc'`
       def complete_sorting_str_with(field_name)
         hash = @hash.except field_name
         current_sort = @hash[field_name]
@@ -30,13 +43,17 @@ module Wallaby
         rebuild_str_from hash
       end
 
+      # @param hash [Hash] sort order hash
+      # @return [String] a sort order string, e.g. `'name asc'`
       def rebuild_str_from(hash)
-        hash.each_with_object '' do |(name, sort), str|
+        hash.each_with_object('') do |(name, sort), str|
           str << (str == EMPTY_STRING ? str : COMMA)
           str << name << SPACE << sort
         end
       end
 
+      # @param current [String, nil] current sort order
+      # @return [String, nil] next state of sort order
       def next_value_for(current)
         case current
         when ASC then DESC
@@ -45,6 +62,10 @@ module Wallaby
         end
       end
 
+      # Update the value for given key. Remove the key if value is blank
+      # @param hash [Hash] sort order hash
+      # @param key [String] key name
+      # @param value [Object, nil] value
       def update(hash, key, value)
         return hash.delete key if value.blank?
         hash[key] = value