serega 0.21.0 → 0.30.0

data/lib/serega/plugins/presenter/presenter.rb

@@ -62,7 +62,7 @@ class Serega
           # Creates delegator method after first #method_missing hit to improve
           # performance of following serializations.
           #
-          def method_missing(name, *_args, &_block) # rubocop:disable Style/MissingRespondToMissing (base SimpleDelegator class has this method)
+          def method_missing(name, *_args, &_block) # rubocop:disable Style/MissingRespondToMissing -- base SimpleDelegator class has this method
             super.tap do
               self.class.def_delegator :__getobj__, name
             end

data/lib/serega/utils/format_user_preloads.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaUtils
+    #
+    # Utility that helps to transform user provided preloads to hash
+    #
+    class FormatUserPreloads
+      class << self
+        #
+        # Transforms user provided preloads to hash
+        #
+        # @param value [Array,Hash,String,Symbol,nil,false] preloads
+        #
+        # @return [Hash] preloads transformed to hash
+        #
+        def call(value)
+          case value
+          when Array then array_to_hash(value)
+          when FalseClass then nil_to_hash(value)
+          when Hash then hash_to_hash(value)
+          when NilClass then nil_to_hash(value)
+          when String then string_to_hash(value)
+          when Symbol then symbol_to_hash(value)
+          else raise Serega::SeregaError,
+            "Preload option value can consist from Symbols, Arrays, Hashes (#{value.class} #{value.inspect} was provided)"
+          end
+        end
+
+        private
+
+        def array_to_hash(values)
+          values.each_with_object({}) do |value, obj|
+            obj.merge!(call(value))
+          end
+        end
+
+        def hash_to_hash(values)
+          values.each_with_object({}) do |(key, value), obj|
+            obj[key.to_sym] = call(value)
+          end
+        end
+
+        def nil_to_hash(_value)
+          {}
+        end
+
+        def string_to_hash(value)
+          {value.to_sym => {}}
+        end
+
+        def symbol_to_hash(value)
+          {value => {}}
+        end
+      end
+    end
+  end
+end

data/lib/serega/utils/method_signature.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Utilities
+  #
+  module SeregaUtils
+    #
+    # Utility to make method arguments signature
+    #
+    class MethodSignature
+      SYMBOL_TO_PROC_SIGNATURE_RUBY2 = [[:rest]]
+      SYMBOL_TO_PROC_SIGNATURE_RUBY3 = [[:req], [:rest]]
+      private_constant :SYMBOL_TO_PROC_SIGNATURE_RUBY2
+      private_constant :SYMBOL_TO_PROC_SIGNATURE_RUBY3
+
+      class << self
+        #
+        # Generates method arguments signature
+        #
+        # @param callable [#call] callable object
+        # @param pos_limit [Integer] Max count of positional parameters
+        # @param keyword_args [Array<Symbol>] List of accepted keyword argument names
+        #
+        # @return [String] Method signature which consist of number of positional parameters and
+        #    keyword parameter names joined with undescrore.
+        #
+        def call(callable, pos_limit:, keyword_args: [])
+          params = callable.is_a?(Proc) ? callable.parameters : callable.method(:call).parameters
+
+          # Procs (but not lambdas) can accept all provided parameters
+          return full_signature(pos_limit, keyword_args) if params.empty? && callable.is_a?(Proc) && !callable.lambda?
+
+          # Return single positional argument for Symbol#to_proc
+          return "1" if (params == SYMBOL_TO_PROC_SIGNATURE_RUBY2) || (params == SYMBOL_TO_PROC_SIGNATURE_RUBY3)
+
+          keyword_args = keyword_args.dup
+
+          # signature parts
+          positional_parameters = 0
+          keyword_parameters = []
+
+          params.each do |type, name|
+            case type
+            when :req
+              positional_parameters += 1
+              pos_limit -= 1
+            when :opt
+              next if pos_limit <= 0
+
+              positional_parameters += 1
+              pos_limit -= 1
+            when :rest
+              next if pos_limit <= 0
+
+              positional_parameters += pos_limit
+              pos_limit = 0
+            when :keyreq
+              keyword_parameters << name
+              keyword_args.delete(name)
+            when :key
+              next unless keyword_args.include?(name)
+
+              keyword_parameters << name
+              keyword_args.delete(name)
+            when :keyrest
+              keyword_parameters.concat(keyword_args)
+              keyword_args.clear
+            end
+          end
+
+          build_signature_string(positional_parameters, keyword_parameters)
+        end
+
+        private
+
+        def full_signature(pos_limit, keyword_args)
+          build_signature_string(pos_limit, keyword_args)
+        end
+
+        def build_signature_string(positional_parameters, keyword_parameters)
+          sorted_signature_parts = keyword_parameters.sort
+          sorted_signature_parts.unshift(positional_parameters)
+          sorted_signature_parts.join("_")
+        end
+      end
+    end
+  end
+end

data/lib/serega/utils/preload_paths.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaUtils
+    #
+    # Utility that helps to transform preloads to array of paths
+    # It is used to validate manually set `:preload_path` attribute option has one of allowed values.
+    # `:preload_path` option can be used to specify where nested preloads must be attached.
+    #
+    # 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 preloads [Array,Hash,String,Symbol,nil,false] association(s) to preload
+        #
+        # @return [Array] transformed preloads
+        #
+        def call(preloads)
+          formatted_preloads = FormatUserPreloads.call(preloads)
+          return FROZEN_EMPTY_ARRAY if formatted_preloads.empty?
+
+          paths(formatted_preloads, [], [])
+        end
+
+        private
+
+        def paths(formatted_preloads, path, result)
+          formatted_preloads.each do |key, nested_preloads|
+            path << key
+            result << path.dup
+
+            paths(nested_preloads, path, result)
+            path.pop
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/serega/utils/preloads_constructor.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaUtils
+    #
+    # Finds preloads for provided attributes plan
+    #
+    class PreloadsConstructor
+      class << self
+        #
+        # Constructs preloads hash for given attributes plan
+        #
+        # @param plan [Array<SeregaPlanPoint>] Serialization plan
+        #
+        # @return [Hash]
+        #
+        def call(plan)
+          return FROZEN_EMPTY_HASH unless plan
+
+          preloads = {}
+          append_many(preloads, plan)
+          preloads
+        end
+
+        private
+
+        def append_many(preloads, plan)
+          plan.points.each do |point|
+            current_preloads = point.attribute.preloads
+            next unless current_preloads
+
+            child_plan = point.child_plan
+            current_preloads = SeregaUtils::EnumDeepDup.call(current_preloads) if child_plan
+            append_current(preloads, current_preloads)
+            next unless child_plan
+
+            each_child_preloads(preloads, point.preloads_path) do |child_preloads|
+              append_many(child_preloads, child_plan)
+            end
+          end
+        end
+
+        def append_current(preloads, current_preloads)
+          merge(preloads, current_preloads) unless current_preloads.empty?
+        end
+
+        def merge(preloads, current_preloads)
+          preloads.merge!(current_preloads) do |_key, value_one, value_two|
+            merge(value_one, value_two)
+          end
+        end
+
+        def each_child_preloads(preloads, preloads_path)
+          return yield(preloads) if preloads_path.nil?
+
+          if preloads_path[0].is_a?(Array)
+            preloads_path.each do |path|
+              yield dig_fetch(preloads, path)
+            end
+          else
+            yield dig_fetch(preloads, preloads_path)
+          end
+        end
+
+        def dig_fetch(preloads, preloads_path)
+          return preloads if !preloads_path || preloads_path.empty?
+
+          preloads_path.each do |path|
+            preloads = preloads.fetch(path)
+          end
+
+          preloads
+        end
+      end
+    end
+  end
+end

data/lib/serega/validations/attribute/check_block.rb

@@ -13,7 +13,8 @@ class Serega
         class << self
           #
           # Checks block parameter provided with attribute.
-          # Must have up to two arguments - object and context.
+          # Must have up to two arguments - object and context. Context can be
+          # also provided as keyword argument :ctx.
           #
           # @example without arguments
           #   attribute(:email) { CONSTANT_EMAIL }
@@ -24,6 +25,9 @@ class Serega
           # @example with two arguments
           #   attribute(:email) { |obj, context| context['is_current'] ? obj.email : nil }
           #
+          # @example with one argument and keyword context
+          #   attribute(:email) { |obj, ctx:| obj.email if ctx[:show] }
+          #
           # @param block [Proc] Block that returns serialized attribute value
           #
           # @raise [SeregaError] SeregaError that block has invalid arguments
@@ -39,14 +43,42 @@ class Serega
           private
 
           def check_block(block)
-            SeregaValidations::Utils::CheckExtraKeywordArg.call(block, "block")
-            params_count = SeregaUtils::ParamsCount.call(block, max_count: 2)
+            signature = SeregaUtils::MethodSignature.call(block, pos_limit: 2, keyword_args: [:ctx, :batches])
+
+            raise SeregaError, signature_error unless valid_signature?(signature)
+          end
 
-            raise SeregaError, block_error if params_count > 2
+          def valid_signature?(signature)
+            case signature
+            when "0"             # no parameters
+              true
+            when "1"             # call(object)
+              true
+            when "1_ctx"         # call(object, ctx:)
+              true
+            when "1_batches"     # call(object, batches:)
+              true
+            when "1_batches_ctx" # call(object, batches:, ctx:)
+              true
+            when "2"             # call(object, context)
+              true
+            when "2_batches_ctx" # call(object, context, batches:, ctx:) (proc with no params)
+              true
+            else
+              false
+            end
           end
 
-          def block_error
-            "Block can have maximum two parameters (object, context)"
+          def signature_error
+            <<~ERROR.strip
+              Invalid attribute block parameters, valid parameters signatures:
+              - ()                       # no parameters
+              - (object)                 # one positional parameter
+              - (object, ctx:)           # one positional parameter and :ctx keyword
+              - (object, batches:)       # one positional parameter and :batches keyword
+              - (object, ctx:, batches:) # one positional parameter, :ctx, and :batches keywords
+              - (object, context)        # two positional parameters
+            ERROR
           end
         end
       end

data/lib/serega/validations/attribute/check_opt_batch.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaValidations
+    module Attribute
+      #
+      # Attribute `:batch` option validator
+      #
+      class CheckOptBatch
+        class << self
+          #
+          # Checks attribute :batch option
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
+          def call(serializer_class, opts, block)
+            return unless opts.key?(:batch)
+
+            check_opt_batch(opts, serializer_class)
+            check_usage_with_other_params(opts, block)
+          end
+
+          private
+
+          def check_opt_batch(opts, serializer_class)
+            batch_opts = opts[:batch]
+            return if batch_opts == true
+            return if batch_opts.respond_to?(:call)
+
+            if batch_opts.is_a?(Symbol) || batch_opts.is_a?(String)
+              check_loader_exists?(serializer_class, batch_opts)
+            else
+              Utils::CheckOptIsHash.call(opts, :batch)
+              check_opt_batch_use(serializer_class, batch_opts)
+              check_opt_batch_id(batch_opts)
+              check_opt_batch_extra_opts(batch_opts)
+            end
+          end
+
+          def check_opt_batch_use(serializer_class, batch_opts)
+            return unless batch_opts.key?(:use)
+
+            batch_loader_name = batch_opts[:use]
+            return if batch_loader_name.respond_to?(:call)
+
+            check_loader_exists?(serializer_class, batch_loader_name)
+          end
+
+          def check_opt_batch_id(batch_opts)
+            return unless batch_opts.key?(:id)
+
+            id_method_name = batch_opts[:id]
+            return if id_method_name.is_a?(Symbol) || id_method_name.is_a?(String)
+
+            raise SeregaError, "Invalid batch option `:id` value, it can be a Symbol or a String"
+          end
+
+          def check_loader_exists?(serializer_class, value)
+            values = Array(value)
+            values.each do |batch_loader_name|
+              next if serializer_class.batch_loaders.key?(batch_loader_name.to_sym)
+
+              raise SeregaError, "Batch loader with name `#{batch_loader_name.inspect}` is not defined"
+            end
+          end
+
+          def check_opt_batch_extra_opts(batch_opts)
+            Utils::CheckAllowedKeys.call(batch_opts, %i[use id], :batch)
+          end
+
+          def check_usage_with_other_params(opts, block)
+            batch = opts[:batch]
+            use_id = batch.is_a?(Hash) && batch.key?(:id)
+            use_multiple = batch.is_a?(Hash) && (Array(batch[:use]).size > 1)
+            value_added = opts.key?(:value) || block
+
+            if use_multiple && use_id
+              raise SeregaError, "Option `batch.id` should not be used with multiple loaders provided in `batch.use`"
+            end
+
+            if use_multiple && !value_added
+              raise SeregaError, "Attribute :value option or block should be provided when selecting multiple batch loaders"
+            end
+
+            if use_id && value_added
+              raise SeregaError, "Option `batch.id` should not be used when :value or block provided directly"
+            end
+
+            raise SeregaError, "Option :batch can not be used together with option :method" if opts.key?(:method)
+            raise SeregaError, "Option :batch can not be used together with option :const" if opts.key?(:const)
+            raise SeregaError, "Option :batch can not be used together with option :delegate" if opts.key?(:delegate)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/validations/attribute/check_opt_const.rb

@@ -28,6 +28,7 @@ class Serega
           def check_usage_with_other_params(opts, block)
             raise SeregaError, "Option :const can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :const can not be used together with option :value" if opts.key?(:value)
+            raise SeregaError, "Option :const can not be used together with option :batch" if opts.key?(:batch)
             raise SeregaError, "Option :const can not be used together with block" if block
           end
         end

data/lib/serega/validations/attribute/check_opt_delegate.rb

@@ -60,6 +60,7 @@ class Serega
             raise SeregaError, "Option :delegate can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :delegate can not be used together with option :const" if opts.key?(:const)
             raise SeregaError, "Option :delegate can not be used together with option :value" if opts.key?(:value)
+            raise SeregaError, "Option :delegate can not be used together with option :batch" if opts.key?(:batch)
             raise SeregaError, "Option :delegate can not be used together with block" if block
           end
         end

data/lib/serega/validations/attribute/check_opt_method.rb

@@ -29,6 +29,7 @@ class Serega
           def check_usage_with_other_params(opts, block)
             raise SeregaError, "Option :method can not be used together with option :const" if opts.key?(:const)
             raise SeregaError, "Option :method can not be used together with option :value" if opts.key?(:value)
+            raise SeregaError, "Option :method can not be used together with option :batch" if opts.key?(:batch)
             raise SeregaError, "Option :method can not be used together with block" if block
           end
         end

data/lib/serega/{plugins/preloads/validations → validations/attribute}/check_opt_preload.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 class Serega
-  module SeregaPlugins
-    module Preloads
+  module SeregaValidations
+    module Attribute
       #
       # Validator for attribute :preload option
       #

data/lib/serega/{plugins/preloads/validations → validations/attribute}/check_opt_preload_path.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 class Serega
-  module SeregaPlugins
-    module Preloads
+  module SeregaValidations
+    module Attribute
       #
       # Validator for attribute :preload_path option
       #
@@ -34,7 +34,7 @@ class Serega
           end
 
           def check_allowed(path, opts)
-            allowed_paths = PreloadPaths.call(opts[:preload])
+            allowed_paths = SeregaUtils::PreloadPaths.call(opts[:preload])
             check_required_when_many_allowed(path, allowed_paths)
             check_in_allowed(path, allowed_paths)
           end

data/lib/serega/validations/attribute/check_opt_value.rb

@@ -35,23 +35,49 @@ class Serega
 
           def check_value(value)
             check_value_type(value)
-
-            SeregaValidations::Utils::CheckExtraKeywordArg.call(value, ":value option")
-            params_count = SeregaUtils::ParamsCount.call(value, max_count: 2)
-
-            raise SeregaError, params_count_error if params_count > 2
+            signature = SeregaUtils::MethodSignature.call(value, pos_limit: 2, keyword_args: %i[ctx batches])
+            raise SeregaError, signature_error unless valid_signature?(signature)
           end
 
           def check_value_type(value)
             raise SeregaError, type_error if !value.is_a?(Proc) && !value.respond_to?(:call)
           end
 
-          def type_error
-            "Option :value value must be a Proc or respond to #call"
+          def valid_signature?(signature)
+            case signature
+            when "0"             # no parameters
+              true
+            when "1"             # call(object)
+              true
+            when "1_ctx"         # call(object, ctx:)
+              true
+            when "1_batches"     # call(object, batches:)
+              true
+            when "1_batches_ctx" # call(object, ctx:, batches:)
+              true
+            when "2"             # call(object, context)
+              true
+            when "2_batches_ctx" # call(object, context, ctx:, batches:) (proc with no params)
+              true
+            else
+              false
+            end
           end
 
-          def params_count_error
-            "Option :value value can have maximum 2 parameters (object, context)"
+          def signature_error
+            <<~ERROR.strip
+              Invalid attribute :value option parameters, valid parameters signatures:
+              - ()                       # no parameters
+              - (object)                 # one positional parameter
+              - (object, ctx:)           # one positional parameter and :ctx keyword
+              - (object, batches:)       # one positional parameter and :batches keyword
+              - (object, ctx:, batches:) # one positional parameter, :ctx, and :batches keywords
+              - (object, context)        # two positional parameters
+            ERROR
+          end
+
+          def type_error
+            "Option :value value must be a Proc or respond to #call"
           end
         end
       end

data/lib/serega/validations/check_attribute_params.rb

@@ -53,11 +53,9 @@ class Serega
         end
 
         # Patched in:
-        # - plugin :batch (checks :batch option)
         # - plugin :context_metadata (checks context metadata option which is :meta by default)
         # - plugin :formatters (checks :format option)
         # - plugin :if (checks :if, :if_value, :unless, :unless_value options)
-        # - plugin :preloads (checks :preload option)
         def check_opts
           Utils::CheckAllowedKeys.call(opts, allowed_opts_keys, :attribute)
 
@@ -66,8 +64,11 @@ class Serega
           Attribute::CheckOptHide.call(opts)
           Attribute::CheckOptMethod.call(opts, block)
           Attribute::CheckOptMany.call(opts)
+          Attribute::CheckOptPreload.call(opts)
+          Attribute::CheckOptPreloadPath.call(opts)
           Attribute::CheckOptSerializer.call(opts)
           Attribute::CheckOptValue.call(opts, block)
+          Attribute::CheckOptBatch.call(self.class.serializer_class, opts, block)
         end
 
         def check_block

data/lib/serega/validations/check_batch_loader_params.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaValidations
+    #
+    # Batch loader parameters validators
+    #
+    class CheckBatchLoaderParams
+      #
+      # batch_loader parameters validation instance methods
+      #
+      module InstanceMethods
+        # @return [Symbol] validated batch_loader name
+        attr_reader :name
+
+        # @return [nil, #call] validated batch_loader value or block
+        attr_reader :batch_loader
+
+        # Instantiates batch loader params checker
+        # @param name [Symbol, String] Batch loader name
+        # @param batch_loader [Proc, #call] Batch loader
+        def initialize(name, batch_loader)
+          @name = name
+          @batch_loader = batch_loader
+        end
+
+        #
+        # Checks batch loader parameters
+        #
+        # @raise [SeregaError] SeregaError that batch loader has invalid arguments
+        #
+        # @return [void]
+        #
+        def validate
+          check_name
+          check_loader
+        end
+
+        private
+
+        def check_name
+          raise SeregaError, name_type_error if !name.is_a?(Symbol) && !name.is_a?(String)
+        end
+
+        def check_loader
+          check_batch_loader_type
+          check_batch_loader_args
+        end
+
+        def check_batch_loader_type
+          raise SeregaError, type_error if !batch_loader.is_a?(Proc) && !batch_loader.respond_to?(:call)
+        end
+
+        def check_batch_loader_args
+          signature = SeregaUtils::MethodSignature.call(batch_loader, pos_limit: 2, keyword_args: [:ctx])
+          raise SeregaError, arguments_error unless %w[1 2 1_ctx].include?(signature)
+        end
+
+        def name_type_error
+          "Batch loader name must be a Symbol or String"
+        end
+
+        def type_error
+          "Batch loader value must be a Proc or respond to #call"
+        end
+
+        def arguments_error
+          <<~ERR.strip
+            Batch loader arguments should have one of this signatures:
+            - (objects)       # one argument
+            - (objects, :ctx) # one argument and one :ctx keyword argument
+          ERR
+        end
+      end
+
+      include InstanceMethods
+      extend Serega::SeregaHelpers::SerializerClassHelper
+    end
+  end
+end