serega 0.11.1 → 0.12.0

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Batch
+      #
+      # Batch plugin config
+      #
+      class BatchConfig
+        attr_reader :opts
+
+        def initialize(opts)
+          @opts = opts
+        end
+
+        #
+        # 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, 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 #define method"
+          end
+
+          params = block.parameters
+          if params.count > 3 || !params.all? { |param| (param[0] == :req) || (param[0] == :opt) }
+            raise SeregaError, "Block can have maximum 3 regular parameters"
+          end
+
+          loaders[loader_name] = block
+        end
+
+        # Shows defined loaders
+        # @return [Hash] defined loaders
+        def loaders
+          opts[:loaders]
+        end
+
+        #
+        # Finds previously defined batch loader by name
+        #
+        # @param loader_name [Symbol]
+        #
+        # @return [Proc] batch loader block
+        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
+    end
+  end
+end

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

@@ -60,6 +60,10 @@ class Serega
 
           private
 
+          def keys
+            @keys ||= {}
+          end
+
           def each_key
             keys.each do |key, containers|
               containers.each do |container|
@@ -74,16 +78,30 @@ class Serega
           def keys_values
             ids = keys.keys
 
-            point.batch[:loader].call(ids, object_serializer.context, point).tap do |vals|
-              next if vals.is_a?(Hash)
+            keys_values = load_keys_values(ids)
+            validate(keys_values)
 
-              attribute_name = "#{point.class.serializer_class}.#{point.name}"
-              raise SeregaError, "Batch loader for `#{attribute_name}` must return Hash, but #{vals.inspect} was returned"
-            end
+            keys_values
           end
 
-          def keys
-            @keys ||= {}
+          def load_keys_values(ids)
+            point.batch[:loader].call(ids, object_serializer.context, point)
+          rescue => error
+            raise reraise_with_serialized_attribute_details(error, point)
+          end
+
+          def validate(keys_values)
+            return if keys_values.is_a?(Hash)
+
+            attribute_name = "#{point.class.serializer_class}.#{point.name}"
+            raise SeregaError, "Batch loader for `#{attribute_name}` must return Hash, but #{keys_values.inspect} was returned"
+          end
+
+          def reraise_with_serialized_attribute_details(error, point)
+            raise error.exception(<<~MESSAGE.strip)
+              #{error.message}
+              (when serializing '#{point.name}' attribute in #{self.class.serializer_class})
+            MESSAGE
           end
         end
 

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Batch
+      #
+      # Serega::SeregaAttribute additional/patched class methods
+      #
+      # @see Serega::SeregaAttribute
+      #
+      module AttributeInstanceMethods
+        #
+        # @return [nil, Hash] :batch option
+        #
+        attr_reader :batch
+
+        private
+
+        def set_normalized_vars(normalizer)
+          super
+          @batch = normalizer.batch
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Batch
+      #
+      # SeregaAttributeNormalizer additional/patched instance methods
+      #
+      # @see SeregaAttributeNormalizer::AttributeInstanceMethods
+      #
+      module AttributeNormalizerInstanceMethods
+        #
+        # 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 [Hash] attribute :batch normalized options
+        #
+        def batch
+          return @batch if instance_variable_defined?(:@batch)
+
+          @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 { |object| object.public_send(key) }
+            else
+              key
+            end
+
+          # take default value
+          default = batch.fetch(:default) { many ? FROZEN_EMPTY_ARRAY : nil }
+
+          {loader: loader, key: proc_key, default: default}
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Batch
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
+      module CheckAttributeParamsInstanceMethods
+        private
+
+        def check_opts
+          super
+
+          CheckOptBatch.call(opts, block, self.class.serializer_class)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Batch
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
+      module ConfigInstanceMethods
+        #
+        # Returns all batch loaders registered for current serializer
+        #
+        # @return [Serega::SeregaPlugins::Batch::BatchConfig] configuration for batch loaded attributes
+        #
+        def batch
+          @batch ||= BatchConfig.new(opts.fetch(:batch))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Batch
+      #
+      # SeregaObjectSerializer additional/patched class methods
+      #
+      # @see Serega::SeregaObjectSerializer
+      #
+      module SeregaObjectSerializerInstanceMethods
+        private
+
+        def attach_value(object, point, container)
+          batch = point.batch
+          return super unless batch
+
+          remember_key_for_batch_loading(batch, object, point, container)
+        end
+
+        def remember_key_for_batch_loading(batch, object, point, container)
+          key = batch[:key].call(object, context)
+          batch_loader(point).remember(key, container)
+          container[point.name] = nil # Reserve attribute place in resulted hash. We will set correct value later
+        end
+
+        def batch_loader(point)
+          batch_loaders = opts[:batch_loaders]
+          raise_batch_plugin_for_serializer_not_defined(point) unless batch_loaders
+          batch_loaders.get(point, self)
+        end
+
+        def raise_batch_plugin_for_serializer_not_defined(point)
+          root_plan = point.plan
+          root_plan = plan.parent_plan_point.plan while root_plan.parent_plan_point
+          current_serializer = root_plan.serializer_class
+          nested_serializer = self.class.serializer_class
+
+          raise SeregaError,
+            "Plugin :batch must be added to current serializer (#{current_serializer})" \
+            " to load attributes with :batch option in nested serializer (#{nested_serializer})"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Batch
+      #
+      # 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
+    end
+  end
+end

data/lib/serega/plugins/metadata/metadata.rb

@@ -194,6 +194,11 @@ class Serega
             next unless metadata
 
             deep_merge_metadata(hash, metadata)
+          rescue => error
+            raise error.exception(<<~MESSAGE.strip)
+              #{error.message}
+              (when serializing meta_attribute #{meta_attribute.path.inspect} in #{self.class})
+            MESSAGE
           end
         end
 

data/lib/serega/plugins/preloads/lib/modules/attribute.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaAttribute additional/patched instance methods
+      #
+      # @see Serega::SeregaAttribute::AttributeInstanceMethods
+      #
+      module AttributeInstanceMethods
+        # @return [Hash, nil] normalized preloads of current attribute
+        attr_reader :preloads
+
+        # @return [Array] normalized preloads_path of current attribute
+        attr_reader :preloads_path
+
+        private
+
+        def set_normalized_vars(normalizer)
+          super
+          @preloads = normalizer.preloads
+          @preloads_path = normalizer.preloads_path
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/modules/attribute_normalizer.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaAttributeNormalizer additional/patched instance methods
+      #
+      # @see SeregaAttributeNormalizer::AttributeNormalizerInstanceMethods
+      #
+      module AttributeNormalizerInstanceMethods
+        # @return [Hash,nil] normalized attribute preloads
+        def preloads
+          return @preloads if instance_variable_defined?(:@preloads)
+
+          @preloads = prepare_preloads
+        end
+
+        # @return [Array, nil] normalized attribute preloads path
+        def preloads_path
+          return @preloads_path if instance_variable_defined?(:@preloads_path)
+
+          @preloads_path = prepare_preloads_path
+        end
+
+        private
+
+        #
+        # Patched in:
+        # - plugin :batch (extension :preloads - skips auto preloads when batch option provided)
+        #
+        def prepare_preloads
+          opts = init_opts
+          preloads_provided = opts.key?(:preload)
+          preloads =
+            if preloads_provided
+              opts[:preload]
+            elsif opts.key?(:serializer) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_serializer
+              key
+            elsif opts.key?(:delegate) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_delegate
+              opts[:delegate].fetch(:to)
+            end
+
+          # Nil and empty hash differs as we can preload nested results to
+          # empty hash, but we will skip nested preloading if nil or false provided
+          return if preloads_provided && !preloads
+
+          FormatUserPreloads.call(preloads)
+        end
+
+        def prepare_preloads_path
+          path = init_opts.fetch(:preload_path) { default_preload_path(preloads) }
+
+          if path && path[0].is_a?(Array)
+            prepare_many_preload_paths(path)
+          else
+            prepare_one_preload_path(path)
+          end
+        end
+
+        def prepare_one_preload_path(path)
+          return unless path
+
+          case path
+          when Array
+            path.map(&:to_sym).freeze
+          else
+            [path.to_sym].freeze
+          end
+        end
+
+        def prepare_many_preload_paths(paths)
+          paths.map { |path| prepare_one_preload_path(path) }.freeze
+        end
+
+        def default_preload_path(preloads)
+          return FROZEN_EMPTY_ARRAY if !preloads || preloads.empty?
+
+          [preloads.keys.first]
+        end
+
+        #
+        # Patch for original `prepare_hide` method
+        # @see
+        #
+        # Marks attribute hidden if auto_hide_attribute_with_preloads option was set and attribute has preloads
+        #
+        def prepare_hide
+          res = super
+          return res unless res.nil?
+
+          if preloads && !preloads.empty?
+            self.class.serializer_class.config.preloads.auto_hide_attributes_with_preload || nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/modules/check_attribute_params.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
+      module CheckAttributeParamsInstanceMethods
+        private
+
+        def check_opts
+          super
+          CheckOptPreload.call(opts)
+          CheckOptPreloadPath.call(opts)
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/modules/config.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
+      module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::Preloads::PreloadsConfig] `preloads` plugin config
+        def preloads
+          @preloads ||= PreloadsConfig.new(opts.fetch(:preloads))
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/modules/plan_point.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaPlanPoint additional/patched instance methods
+      #
+      # @see Serega::SeregaPlanPoint::InstanceMethods
+      #
+      module PlanPointInstanceMethods
+        #
+        # @return [Hash] preloads for nested attributes
+        #
+        attr_reader :preloads
+
+        #
+        # @return [Array<Symbol>] preloads path for current attribute
+        #
+        attr_reader :preloads_path
+
+        private
+
+        def set_normalized_vars
+          super
+
+          @preloads = prepare_preloads
+          @preloads_path = prepare_preloads_path
+        end
+
+        def prepare_preloads
+          PreloadsConstructor.call(child_plan)
+        end
+
+        def prepare_preloads_path
+          attribute.preloads_path
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/preload_paths.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Utility that helps to transform preloads to array of paths
+      #
+      # Example:
+      #
+      #   call({ a: { b: { c: {}, d: {} } }, e: {} })
+      #
+      #   => [
+      #        [:a],
+      #        [:a, :b],
+      #        [:a, :b, :c],
+      #        [:a, :b, :d],
+      #        [:e]
+      #      ]
+      class PreloadPaths
+        class << self
+          #
+          # Transforms user provided preloads to array of paths
+          #
+          # @param value [Array,Hash,String,Symbol,nil,false] preloads
+          #
+          # @return [Hash] preloads transformed to hash
+          #
+          def call(preloads, path = [], result = [])
+            preloads = FormatUserPreloads.call(preloads)
+
+            preloads.each do |key, nested_preloads|
+              path << key
+              result << path.dup
+
+              call(nested_preloads, path, result)
+              path.pop
+            end
+
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/preloads_config.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Config for `preloads` plugin
+      #
+      class PreloadsConfig
+        # @return [Hash] preloads plugin options
+        attr_reader :opts
+
+        #
+        # Initializes context_metadata config object
+        #
+        # @param opts [Hash] options
+        #
+        # @return [Serega::SeregaPlugins::Metadata::MetadataConfig]
+        #
+        def initialize(opts)
+          @opts = opts
+        end
+
+        # @!method auto_preload_attributes_with_delegate
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_preload_attributes_with_delegate=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
+        # @!method auto_preload_attributes_with_serializer
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_preload_attributes_with_serializer=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
+        # @!method auto_hide_attributes_with_preload
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_hide_attributes_with_preload=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
+        %i[
+          auto_preload_attributes_with_delegate
+          auto_preload_attributes_with_serializer
+          auto_hide_attributes_with_preload
+        ].each do |method_name|
+          define_method(method_name) do
+            opts.fetch(method_name)
+          end
+
+          define_method("#{method_name}=") do |value|
+            raise SeregaError, "Must have boolean value, #{value.inspect} provided" if (value != true) && (value != false)
+            opts[method_name] = value
+          end
+        end
+      end
+    end
+  end
+end