serega 0.20.1 → 0.30.0

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

@@ -40,6 +40,8 @@ class Serega
             @opts = SeregaUtils::EnumDeepDup.call(opts)
             @block = block
             @normalized_block = normalize_block(opts[:value], opts[:const], block)
+            @normalized_block_signature =
+              SeregaUtils::MethodSignature.call(@normalized_block, pos_limit: 2, keyword_args: [])
           end
 
           #
@@ -51,7 +53,11 @@ class Serega
           # @return [Object] Serialized meta attribute value
           #
           def value(object, context)
-            normalized_block.call(object, context)
+            case normalized_block_signature
+            when "0" then normalized_block.call
+            when "1" then normalized_block.call(object)
+            else normalized_block.call(object, context)
+            end
           end
 
           def hide?(value)
@@ -60,19 +66,12 @@ class Serega
 
           private
 
-          attr_reader :normalized_block
+          attr_reader :normalized_block, :normalized_block_signature
 
           def normalize_block(value, const, block)
             return proc { const } if const
 
-            callable = value || block
-            params_count = SeregaUtils::ParamsCount.call(callable, max_count: 2)
-
-            case params_count
-            when 0 then proc { callable.call }
-            when 1 then proc { |obj| callable.call(obj) }
-            else callable
-            end
+            value || block
           end
 
           def check(path, opts, block)

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

@@ -29,10 +29,8 @@ class Serega
             # @return [void]
             #
             def call(block)
-              SeregaValidations::Utils::CheckExtraKeywordArg.call(block, "block")
-              params_count = SeregaUtils::ParamsCount.call(block, max_count: 2)
-
-              raise SeregaError, block_error if params_count > 2
+              signature = SeregaUtils::MethodSignature.call(block, pos_limit: 2, keyword_args: [])
+              raise SeregaError, block_error unless %w[0 1 2].include?(signature)
             end
 
             private

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

@@ -36,10 +36,9 @@ 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)
+              signature = SeregaUtils::MethodSignature.call(value, pos_limit: 2, keyword_args: [])
 
-              raise SeregaError, params_count_error if params_count > 2
+              raise SeregaError, params_count_error unless %w[0 1 2].include?(signature)
             end
 
             def check_value_type(value)

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/plugins/string_modifiers/parse_string_modifiers.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "stringio"
-
 class Serega
   module SeregaPlugins
     #
@@ -25,6 +23,14 @@ class Serega
       # Modifiers parser
       #
       class ParseStringModifiers
+        COMMA = ","
+        COMMA_CODEPOINT = COMMA.ord
+        LPAREN = "("
+        LPAREN_CODEPOINT = LPAREN.ord
+        RPAREN = ")"
+        RPAREN_CODEPOINT = RPAREN.ord
+        private_constant :COMMA, :LPAREN, :RPAREN, :COMMA_CODEPOINT, :LPAREN_CODEPOINT, :RPAREN_CODEPOINT
+
         class << self
           #
           # Parses string modifiers
@@ -40,45 +46,52 @@ class Serega
           #   parse("user,comments") => { user: {}, comments: {} }
           #   parse("user(comments(text))") => { user: { comments: { text: {} } } }
           def parse(fields)
-            res = {}
-            attribute = +""
-            char = +""
-            path_stack = nil
-            fields = StringIO.new(fields)
+            result = {}
+            attribute_storage = result
+            path_stack = (fields.include?(LPAREN) || fields.include?(RPAREN)) ? [] : nil
 
-            while fields.read(1, char)
-              case char
-              when ","
-                add_attribute(res, path_stack, attribute, FROZEN_EMPTY_HASH)
-              when ")"
-                add_attribute(res, path_stack, attribute, FROZEN_EMPTY_HASH)
-                path_stack&.pop
-              when "("
-                name = add_attribute(res, path_stack, attribute, {})
-                (path_stack ||= []).push(name) if name
-              else
-                attribute.insert(-1, char)
+            start_index = 0
+            end_index = 0
+            fields.each_codepoint do |codepoint|
+              case codepoint
+              when COMMA_CODEPOINT
+                attribute = extract_attribute(fields, start_index, end_index)
+                add_attribute(attribute_storage, attribute, FROZEN_EMPTY_HASH) if attribute
+                start_index = end_index + 1
+              when LPAREN_CODEPOINT
+                attribute = extract_attribute(fields, start_index, end_index)
+                if attribute
+                  attribute_storage = add_attribute(attribute_storage, attribute, {})
+                  path_stack.push(attribute)
+                end
+                start_index = end_index + 1
+              when RPAREN_CODEPOINT
+                attribute = extract_attribute(fields, start_index, end_index)
+                add_attribute(attribute_storage, attribute, FROZEN_EMPTY_HASH) if attribute
+                path_stack.pop
+                attribute_storage = dig?(result, path_stack)
+                start_index = end_index + 1
               end
+
+              end_index += 1
             end
 
-            add_attribute(res, path_stack, attribute, FROZEN_EMPTY_HASH)
+            attribute = extract_attribute(fields, start_index, end_index)
+            add_attribute(attribute_storage, attribute, FROZEN_EMPTY_HASH) if attribute
 
-            res
+            result
           end
 
           private
 
-          def add_attribute(res, path_stack, attribute, nested_attributes = FROZEN_EMPTY_HASH)
+          def extract_attribute(fields, start_index, end_index)
+            attribute = fields[start_index, end_index - start_index]
             attribute.strip!
-            return if attribute.empty?
-
-            name = attribute.to_sym
-            attribute.clear
-
-            current_attrs = dig?(res, path_stack)
-            current_attrs[name] = nested_attributes
+            attribute.empty? ? nil : attribute.to_sym
+          end
 
-            name
+          def add_attribute(storage, attribute, nested_attributes = FROZEN_EMPTY_HASH)
+            storage[attribute] = nested_attributes
           end
 
           def dig?(hash, path)

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
       #