serega 0.10.0 → 0.11.0

data/lib/serega/plugins/batch/batch.rb

@@ -3,33 +3,62 @@
 class Serega
   module SeregaPlugins
     #
-    # Plugin that can be used to load attributes values in batches.
-    #   Each batch loader accepts list of selected keys, context and current attribute point.
-    #   Each batch loader must return Hash with values grouped by provided keys.
-    #   There are specific `:default` option that can be used to add default value for missing key.
+    # Plugin `:batch`
+    #
+    # Adds ability to load nested attributes values in batches.
+    #
+    # It can be used to find value for attributes in optimal way:
+    # - load associations for multiple objects
+    # - load counters for multiple objects
+    # - make any heavy calculations for multiple objects only once
+    #
+    # After including plugin, attributes gain new `:batch` option.
+    #
+    # `:batch` option must be a hash with this keys:
+    # - `key` (required) [Symbol, Proc, callable] - Defines current object identifier.
+    #   Later `loader` will accept array of `keys` to find `values`.
+    # - `loader` (required) [Symbol, Proc, callable] - Defines how to fetch values for
+    #   batch of keys. Receives 3 parameters: keys, context, plan_point.
+    # - `default` (optional) - Default value for attribute.
+    #   By default it is `nil` or `[]` when attribute has option `many: true`
+    #
+    # If `:loader` was defined using name (as Symbol) then batch loader must be
+    # defined in serializer config: `config.batch.define(:loader_name) { ... }` method.
+    #
+    # *Result of this `:loader` callable must be a **Hash** where*:
+    # - keys - provided keys
+    # - values - values for according keys
+    #
+    # `Batch` plugin can be defined with two specific attributes:
+    # - `auto_hide: true` - Marks attributes with defined :batch as hidden, so it
+    #   will not be serialized by default
+    # - `default_key: :id` - Set default object key (in this case :id) that will be used for all attributes with :batch option specified.
+    #
+    # This options (`auto_hide`, `default_key`) also can be set as config options in
+    # any nested serializer.
     #
     # @example
     #   class PostSerializer < Serega
-    #     plugin :batch
+    #     plugin :batch, auto_hide: true, default_key: :id
     #
-    #     # Define batch loader via callable class, it must accept three args (keys, context, map_point)
-    #     attribute :comments_count, batch: { key: :id, loader: PostCommentsCountBatchLoader, default: 0}
+    #     # Define batch loader via callable class, it must accept three args (keys, context, plan_point)
+    #     attribute :comments_count, batch: { loader: PostCommentsCountBatchLoader, default: 0}
     #
-    #     # Define batch loader via Symbol, later we should define this loader via config.batch_loaders.define(:posts_comments_counter) { ... }
-    #     attribute :comments_count, batch: { key: :id, loader: :posts_comments_counter, default: 0}
+    #     # Define batch loader via Symbol, later we should define this loader via config.batch.define(:posts_comments_counter) { ... }
+    #     attribute :comments_count, batch: { loader: :posts_comments_counter, default: 0}
     #
     #     # Define batch loader with serializer
-    #     attribute :comments, serializer: CommentSerializer, batch: { key: :id, loader: :posts_comments, default: []}
+    #     attribute :comments, serializer: CommentSerializer, batch: { loader: :posts_comments, default: []}
     #
     #     # Resulted block must return hash like { key => value(s) }
-    #     config.batch_loaders.define(:posts_comments_counter) do |keys|
+    #     config.batch.define(:posts_comments_counter) do |keys|
     #       Comment.group(:post_id).where(post_id: keys).count
     #     end
     #
     #     # We can return objects that will be automatically serialized if attribute defined with :serializer
     #     # Parameter `context` can be used when loading batch
-    #     # Parameter `map_point` can be used to find nested attributes that will be serialized (`map_point.preloads`)
-    #     config.batch_loaders.define(:posts_comments) do |keys, context, map_point|
+    #     # Parameter `plan_point` can be used to find nested attributes that will be serialized (`plan_point.preloads`)
+    #     config.batch.define(:posts_comments) do |keys, context, plan_point|
     #       Comment.where(post_id: keys).where(is_spam: false).group_by(&:post_id)
     #     end
     #   end
@@ -50,7 +79,6 @@ class Serega
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
-        require_relative "./lib/batch_option_model"
         require_relative "./lib/loader"
         require_relative "./lib/loaders"
         require_relative "./lib/validations/check_batch_opt_key"
@@ -61,7 +89,8 @@ class Serega
         serializer_class.include(InstanceMethods)
         serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
         serializer_class::SeregaAttribute.include(AttributeInstanceMethods)
-        serializer_class::SeregaMapPoint.include(MapPointInstanceMethods)
+        serializer_class::SeregaAttributeNormalizer.include(AttributeNormalizerInstanceMethods)
+        serializer_class::SeregaPlanPoint.include(PlanPointInstanceMethods)
         serializer_class::SeregaObjectSerializer.include(SeregaObjectSerializerInstanceMethods)
       end
 
@@ -74,9 +103,6 @@ class Serega
       # @return [void]
       #
       def self.after_load_plugin(serializer_class, **opts)
-        config = serializer_class.config
-        config.attribute_keys << :batch
-        config.opts[:batch] = {loaders: {}}
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
 
         batch_loaders_class = Class.new(SeregaBatchLoaders)
@@ -95,18 +121,24 @@ class Serega
         if serializer_class.plugin_used?(:formatters)
           require_relative "./lib/plugins_extensions/formatters"
           serializer_class::SeregaBatchLoader.include(PluginsExtensions::Formatters::BatchLoaderInstanceMethods)
+          serializer_class::SeregaAttribute.include(PluginsExtensions::Formatters::SeregaAttributeInstanceMethods)
         end
 
         if serializer_class.plugin_used?(:preloads)
           require_relative "./lib/plugins_extensions/preloads"
-          serializer_class::SeregaAttribute.include(PluginsExtensions::Preloads::AttributeInstanceMethods)
+          serializer_class::SeregaAttributeNormalizer.include(PluginsExtensions::Preloads::AttributeNormalizerInstanceMethods)
         end
+
+        config = serializer_class.config
+        config.attribute_keys << :batch
+        config.opts[:batch] = {loaders: {}, default_key: nil, auto_hide: false}
+        config.batch.auto_hide = opts[:auto_hide] if opts.key?(:auto_hide)
       end
 
       #
       # Batch loader config
       #
-      class BatchLoadersConfig
+      class BatchConfig
         attr_reader :opts
 
         def initialize(opts)
@@ -117,22 +149,28 @@ class Serega
         # Defines batch loader
         #
         # @param loader_name [Symbol] Batch loader name, that is used when defining attribute with batch loader.
-        # @param block [Proc] Block that can accept 3 parameters - keys, context, map_point
+        # @param block [Proc] Block that can accept 3 parameters - keys, context, plan_point
         #   and returns hash where ids are keys and values are batch loaded objects/
         #
         # @return [void]
         #
         def define(loader_name, &block)
           unless block
-            raise SeregaError, "Block must be given to batch_loaders.define method"
+            raise SeregaError, "Block must be given to #define method"
           end
 
           params = block.parameters
-          if params.count > 3 || !params.map!(&:first).all? { |type| (type == :req) || (type == :opt) }
+          if params.count > 3 || !params.all? { |param| (param[0] == :req) || (param[0] == :opt) }
             raise SeregaError, "Block can have maximum 3 regular parameters"
           end
 
-          opts[loader_name] = block
+          loaders[loader_name] = block
+        end
+
+        # Shows defined loaders
+        # @return [Hash] defined loaders
+        def loaders
+          opts[:loaders]
         end
 
         #
@@ -141,8 +179,34 @@ class Serega
         # @param loader_name [Symbol]
         #
         # @return [Proc] batch loader block
-        def fetch(loader_name)
-          opts[loader_name] || (raise SeregaError, "Batch loader with name `#{loader_name.inspect}` was not defined. Define example: config.batch_loaders.define(:#{loader_name}) { |keys, ctx, points| ... }")
+        def fetch_loader(loader_name)
+          loaders[loader_name] || (raise SeregaError, "Batch loader with name `#{loader_name.inspect}` was not defined. Define example: config.batch.define(:#{loader_name}) { |keys, ctx, points| ... }")
+        end
+
+        # Shows option to auto hide attributes with :batch specified
+        # @return [Boolean, nil] option value
+        def auto_hide
+          opts[:auto_hide]
+        end
+
+        # @param value [Boolean] New :auto_hide option value
+        # @return [Boolean] New option value
+        def auto_hide=(value)
+          raise SeregaError, "Must have boolean value, #{value.inspect} provided" if (value != true) && (value != false)
+          opts[:auto_hide] = value
+        end
+
+        # Shows default key for :batch option
+        # @return [Symbol, nil] default key for :batch option
+        def default_key
+          opts[:default_key]
+        end
+
+        # @param value [Symbol] New :default_key option value
+        # @return [Boolean] New option value
+        def default_key=(value)
+          raise SeregaError, "Must be a Symbol, #{value.inspect} provided" unless value.is_a?(Symbol)
+          opts[:default_key] = value
         end
       end
 
@@ -155,10 +219,10 @@ class Serega
         #
         # Returns all batch loaders registered for current serializer
         #
-        # @return [Serega::SeregaPlugins::Batch::BatchLoadersConfig] configuration for batch loaders
+        # @return [Serega::SeregaPlugins::Batch::BatchConfig] configuration for batch loaded attributes
         #
-        def batch_loaders
-          @batch_loaders ||= BatchLoadersConfig.new(opts.fetch(:batch).fetch(:loaders))
+        def batch
+          @batch ||= BatchConfig.new(opts.fetch(:batch))
         end
       end
 
@@ -194,7 +258,7 @@ class Serega
         def check_opts
           super
 
-          CheckOptBatch.call(opts, block)
+          CheckOptBatch.call(opts, block, self.class.serializer_class)
         end
       end
 
@@ -207,29 +271,111 @@ class Serega
         #
         # @return [nil, Hash] :batch option
         #
-        def batch
-          opts[:batch]
+        attr_reader :batch
+
+        private
+
+        def set_normalized_vars(normalizer)
+          super
+          @batch = normalizer.batch
         end
       end
 
       #
-      # Serega::SeregaMapPoint additional/patched class methods
+      # SeregaAttributeNormalizer additional/patched instance methods
       #
-      # @see SeregaAttribute
+      # @see SeregaAttributeNormalizer::AttributeInstanceMethods
       #
-      module MapPointInstanceMethods
+      module AttributeNormalizerInstanceMethods
         #
-        # Returns BatchOptionModel, an object that combines options and methods needed to load batch
+        # Returns normalized attribute :batch option with prepared :key and
+        # :default options. Option :loader will be prepared at serialization
+        # time as loaders are usually defined after attributes.
         #
-        # @return [BatchOptionModel] Class that combines options and methods needed to load batch.
+        # @return [Hash] attribute :batch normalized options
         #
         def batch
           return @batch if instance_variable_defined?(:@batch)
 
-          @batch = begin
-            opts = attribute.batch
-            BatchOptionModel.new(attribute) if opts
+          @batch = prepare_batch
+        end
+
+        private
+
+        #
+        # Patch for original `prepare_hide` method
+        #
+        # Marks attribute hidden if auto_hide option was set and attribute has batch loader
+        #
+        def prepare_hide
+          res = super
+          return res unless res.nil?
+
+          if batch
+            self.class.serializer_class.config.batch.auto_hide || nil
+          end
+        end
+
+        def prepare_batch
+          batch = init_opts[:batch]
+          return unless batch
+
+          # take loader
+          loader = batch[:loader]
+
+          # take key
+          key = batch[:key] || self.class.serializer_class.config.batch.default_key
+          proc_key =
+            if key.is_a?(Symbol)
+              proc do |object|
+                handle_no_method_error { object.public_send(key) }
+              end
+            else
+              key
+            end
+
+          # take default value
+          default = batch.fetch(:default) { many ? FROZEN_EMPTY_ARRAY : nil }
+
+          {loader: loader, key: proc_key, default: default}
+        end
+
+        def handle_no_method_error
+          yield
+        rescue NoMethodError => error
+          raise error, "NoMethodError when serializing '#{name}' attribute in #{self.class.serializer_class}\n\n#{error.message}", error.backtrace
+        end
+      end
+
+      #
+      # Serega::SeregaPlanPoint additional/patched class methods
+      #
+      # @see SeregaAttribute
+      #
+      module PlanPointInstanceMethods
+        #
+        # Returns attribute :batch option with prepared loader
+        # @return [Hash] attribute :batch option
+        #
+        attr_reader :batch
+
+        private
+
+        def set_normalized_vars
+          super
+          @batch = prepare_batch
+        end
+
+        def prepare_batch
+          batch = attribute.batch
+          if batch
+            loader = batch[:loader]
+            if loader.is_a?(Symbol)
+              batch_config = attribute.class.serializer_class.config.batch
+              batch[:loader] = batch_config.fetch_loader(loader)
+            end
           end
+          batch
         end
       end
 
@@ -268,7 +414,7 @@ class Serega
         end
 
         def remember_key_for_batch_loading(batch, object, point, container)
-          key = batch.key.call(object, context)
+          key = batch[:key].call(object, context)
           opts[:batch_loaders].get(point, self).remember(key, container)
           container[point.name] = nil # Reserve attribute place in resulted hash. We will set correct value later
         end

data/lib/serega/plugins/batch/lib/loader.rb

@@ -12,7 +12,7 @@ class Serega
         # Batch Loader instance methods
         #
         module InstanceMethods
-          # @return [Serega::SeregaMapPoint]
+          # @return [Serega::SeregaPlanPoint]
           attr_reader :point
 
           # @return [Serega::SeregaObjectSerializer]
@@ -22,7 +22,7 @@ class Serega
           # Initializes new SeregaBatchLoader
           #
           # @param object_serializer [Serega::SeregaObjectSerializer]
-          # @param point [Serega::SeregaMapPoint]
+          # @param point [Serega::SeregaPlanPoint]
           #
           # @return [Serega::SeregaPlugins::Batch::SeregaBatchLoader]
           #
@@ -52,7 +52,7 @@ class Serega
             keys_values = keys_values()
 
             each_key do |key, container|
-              value = keys_values.fetch(key) { point.batch.default_value }
+              value = keys_values.fetch(key) { point.batch[:default] }
               final_value = object_serializer.__send__(:final_value, value, point)
               object_serializer.__send__(:attach_final_value, final_value, point, container)
             end
@@ -74,7 +74,7 @@ class Serega
           def keys_values
             ids = keys.keys
 
-            point.batch.loader.call(ids, object_serializer.context, point).tap do |vals|
+            point.batch[:loader].call(ids, object_serializer.context, point).tap do |vals|
               next if vals.is_a?(Hash)
 
               attribute_name = "#{point.class.serializer_class}.#{point.name}"

data/lib/serega/plugins/batch/lib/loaders.rb

@@ -10,13 +10,13 @@ class Serega
           #
           # Initializes or fetches already initialized batch loader
           #
-          # @param map_point [Serega::SeregaMapPoint] current map point
+          # @param plan_point [Serega::SeregaPlanPoint] current plan point
           # @param object_serializer[Serega::SeregaObjectSerializer] current object serializer
           #
           # @return [Serega::SeregaPlugins::Batch::SeregaBatchLoader] Batch Loader
           #
-          def get(map_point, object_serializer)
-            batch_loaders[map_point] ||= self.class.serializer_class::SeregaBatchLoader.new(object_serializer, map_point)
+          def get(plan_point, object_serializer)
+            batch_loaders[plan_point] ||= self.class.serializer_class::SeregaBatchLoader.new(object_serializer, plan_point)
           end
 
           #

data/lib/serega/plugins/batch/lib/plugins_extensions/activerecord_preloads.rb

@@ -20,10 +20,10 @@ class Serega
             private
 
             # Preloads required associations to batch-loaded records
-            def keys_values(*)
+            def keys_values
               data = super
 
-              if point.has_nested_points?
+              if point.child_plan
                 associations = point.preloads
                 return data if associations.empty?
 

data/lib/serega/plugins/batch/lib/plugins_extensions/formatters.rb

@@ -20,7 +20,7 @@ class Serega
             private
 
             # Format values after they are prepared
-            def keys_values(*)
+            def keys_values
               data = super
 
               formatter = point.attribute.formatter
@@ -29,6 +29,24 @@ class Serega
               data
             end
           end
+
+          #
+          # SeregaAttribute additional/patched instance methods
+          #
+          # @see Serega::SeregaAttribute
+          #
+          module SeregaAttributeInstanceMethods
+            # Normalized formatter block or callable instance
+            # @return [#call, nil] Normalized formatter block or callable instance
+            attr_reader :formatter
+
+            private
+
+            def set_normalized_vars(normalizer)
+              super
+              @formatter = normalizer.formatter
+            end
+          end
         end
       end
     end

data/lib/serega/plugins/batch/lib/plugins_extensions/preloads.rb

@@ -14,14 +14,16 @@ class Serega
           #
           # Attribute additional/patched instance methods
           #
-          # @see Serega::SeregaPlugins::Preloads::AttributeInstanceMethods
+          # @see Serega::SeregaPlugins::Preloads::AttributeNormalizerInstanceMethods
           #
-          module AttributeInstanceMethods
+          module AttributeNormalizerInstanceMethods
             private
 
             # Do not add any preloads automatically when batch option provided
-            def get_preloads
-              return if batch && !opts.key?(:preload)
+            def prepare_preloads
+              opts = init_opts
+              return if opts.key?(:batch) && !opts.key?(:preload)
+
               super
             end
           end

data/lib/serega/plugins/batch/lib/validations/check_opt_batch.rb

@@ -17,7 +17,7 @@ class Serega
           #
           # @return [void]
           #
-          def call(opts, block)
+          def call(opts, block, serializer_class)
             return unless opts.key?(:batch)
 
             SeregaValidations::Utils::CheckOptIsHash.call(opts, :batch)
@@ -25,21 +25,25 @@ class Serega
             batch = opts[:batch]
             SeregaValidations::Utils::CheckAllowedKeys.call(batch, %i[key loader default])
 
-            check_batch_opt_key(batch[:key])
-            check_batch_opt_loader(batch[:loader])
+            check_batch_opt_key(batch, serializer_class)
+            check_batch_opt_loader(batch)
 
             check_usage_with_other_params(opts, block)
           end
 
           private
 
-          def check_batch_opt_key(key)
+          def check_batch_opt_key(batch, serializer_class)
+            return if !batch.key?(:key) && serializer_class.config.batch.default_key
+
+            key = batch[:key]
             raise SeregaError, "Option :key must present inside :batch option" unless key
 
             CheckBatchOptKey.call(key)
           end
 
-          def check_batch_opt_loader(loader)
+          def check_batch_opt_loader(batch)
+            loader = batch[:loader]
             raise SeregaError, "Option :loader must present inside :batch option" unless loader
 
             CheckBatchOptLoader.call(loader)

data/lib/serega/plugins/formatters/formatters.rb

@@ -67,7 +67,7 @@ class Serega
       #
       def self.load_plugin(serializer_class, **_opts)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
-        serializer_class::SeregaAttribute.include(AttributeInstanceMethods)
+        serializer_class::SeregaAttributeNormalizer.include(AttributeNormalizerInstanceMethods)
       end
 
       #
@@ -115,10 +115,10 @@ class Serega
       #
       # Config class additional/patched instance methods
       #
-      # @see Serega::SeregaConfig
+      # @see SeregaConfig
       #
       module ConfigInstanceMethods
-        # @return [Serega::SeregaPlugins::Formatters::FormattersConfig] current formatters config
+        # @return [SeregaPlugins::Formatters::FormattersConfig] current formatters config
         def formatters
           @formatters ||= FormattersConfig.new(opts.fetch(:formatters))
         end
@@ -127,46 +127,43 @@ class Serega
       #
       # Attribute class additional/patched instance methods
       #
-      # @see Serega::SeregaAttribute
+      # @see SeregaAttributeNormalizer
       #
-      module AttributeInstanceMethods
-        # @return [#call] callable formatter
+      module AttributeNormalizerInstanceMethods
+        # Block or callable instance that will format attribute values
+        # @return [Proc, #call, nil] Block or callable instance that will format attribute values
         def formatter
           return @formatter if instance_variable_defined?(:@formatter)
 
-          @formatter = formatter_resolved
+          @formatter = prepare_formatter
         end
 
-        # @return [#call] callable, that should be used to fetch attribute value
-        def value_block
-          return @value_block if instance_variable_defined?(:@value_block)
-          return @value_block = super unless formatter
-
-          new_value_block = formatted_block(formatter, super)
+        private
 
-          # Format :const value in advance
-          if opts.key?(:const)
-            const_value = new_value_block.call
-            new_value_block = proc { const_value }
+        def prepare_value_block
+          return super unless formatter
+
+          if init_opts.key?(:const)
+            # Format const value in advance
+            const_value = formatter.call(init_opts[:const])
+            proc { const_value }
+          else
+            # Wrap original block into formatter block
+            proc do |object, context|
+              value = super.call(object, context)
+              formatter.call(value)
+            end
           end
-
-          @value_block = new_value_block
         end
 
-        private
-
-        def formatter_resolved
-          formatter = opts[:format]
+        def prepare_formatter
+          formatter = init_opts[:format]
           return unless formatter
 
-          formatter = self.class.serializer_class.config.formatters.opts.fetch(formatter) if formatter.is_a?(Symbol)
-          formatter
-        end
-
-        def formatted_block(formatter, original_block)
-          proc do |object, context|
-            value = original_block.call(object, context)
-            formatter.call(value)
+          if formatter.is_a?(Symbol)
+            self.class.serializer_class.config.formatters.opts.fetch(formatter)
+          else
+            formatter # already callable
           end
         end
       end

data/lib/serega/plugins/if/if.rb

@@ -61,7 +61,8 @@ class Serega
         require_relative "./validations/check_opt_unless"
         require_relative "./validations/check_opt_unless_value"
 
-        serializer_class::SeregaMapPoint.include(MapPointInstanceMethods)
+        serializer_class::SeregaAttribute.include(SeregaAttributeInstanceMethods)
+        serializer_class::SeregaPlanPoint.include(PlanPointInstanceMethods)
         serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
         serializer_class::SeregaObjectSerializer.include(SeregaObjectSerializerInstanceMethods)
       end
@@ -79,11 +80,28 @@ class Serega
       end
 
       #
-      # Serega::SeregaMapPoint additional/patched instance methods
+      # SeregaAttribute additional/patched instance methods
       #
-      # @see Serega::SeregaMapPoint::InstanceMethods
+      # @see Serega::SeregaAttribute
       #
-      module MapPointInstanceMethods
+      module SeregaAttributeInstanceMethods
+        # @return provided :if options
+        attr_reader :opt_if
+
+        private
+
+        def set_normalized_vars(normalizer)
+          super
+          @opt_if = initials[:opts].slice(:if, :if_value, :unless, :unless_value).freeze
+        end
+      end
+
+      #
+      # Serega::SeregaPlanPoint additional/patched instance methods
+      #
+      # @see Serega::SeregaPlanPoint::InstanceMethods
+      #
+      module PlanPointInstanceMethods
         #
         # @return [Boolean] Should we show attribute or not
         #   Conditions for this checks are specified by :if and :unless attribute options.
@@ -103,8 +121,8 @@ class Serega
         private
 
         def check_if_unless(obj, ctx, opt_if_name, opt_unless_name)
-          opt_if = attribute.opts[opt_if_name]
-          opt_unless = attribute.opts[opt_unless_name]
+          opt_if = attribute.opt_if[opt_if_name]
+          opt_unless = attribute.opt_if[opt_unless_name]
           return true if opt_if.nil? && opt_unless.nil?
 
           res_if =