serega 0.16.0 → 0.17.0

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

@@ -26,54 +26,22 @@ class Serega
 
           private
 
-          def check_type(value)
-            return if value.is_a?(Symbol)
-
-            raise SeregaError, must_be_callable unless value.respond_to?(:call)
-
-            if value.is_a?(Proc)
-              check_block(value)
-            else
-              check_callable(value)
-            end
-          end
-
           def check_usage_with_other_params(opts)
             raise SeregaError, "Option :if_value can not be used together with option :serializer" if opts.key?(:serializer)
           end
 
-          def check_block(block)
-            return if valid_parameters?(block, accepted_count: 0..2)
-
-            raise SeregaError, block_parameters_error
-          end
-
-          def check_callable(callable)
-            return if valid_parameters?(callable.method(:call), accepted_count: 2..2)
-
-            raise SeregaError, callable_parameters_error
-          end
+          def check_type(value)
+            return if value.is_a?(Symbol)
+            raise SeregaError, must_be_callable unless value.respond_to?(:call)
 
-          def valid_parameters?(data, accepted_count:)
-            params = data.parameters
-            accepted_count.include?(params.count) && valid_parameters_types?(params)
-          end
+            SeregaValidations::Utils::CheckExtraKeywordArg.call(value, ":if_value option")
+            params_count = SeregaUtils::ParamsCount.call(value, max_count: 2)
 
-          def valid_parameters_types?(params)
-            params.all? do |param|
-              type = param[0]
-              (type == :req) || (type == :opt)
+            if params_count > 2
+              raise SeregaError, "Option :if_value value should have up to 2 parameters (value, context)"
             end
           end
 
-          def block_parameters_error
-            "Invalid attribute option :if_value. When it is a Proc it can have maximum two regular parameters (object, context)"
-          end
-
-          def callable_parameters_error
-            "Invalid attribute option :if_value. When it is a callable object it must have two regular parameters (object, context)"
-          end
-
           def must_be_callable
             "Invalid attribute option :if_value. It must be a Symbol, a Proc or respond to :call"
           end

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

@@ -25,59 +25,18 @@ class Serega
 
           private
 
-          #
-          # Checks attribute :unless option
-          #
-          # @param value [nil, Symbol, Proc, #call] Attribute :unless option
-          #
-          # @raise [SeregaError] validation error
-          #
-          # @return [void]
-          #
           def check_type(value)
             return if value.is_a?(Symbol)
-
             raise SeregaError, must_be_callable unless value.respond_to?(:call)
 
-            if value.is_a?(Proc)
-              check_block(value)
-            else
-              check_callable(value)
-            end
-          end
+            SeregaValidations::Utils::CheckExtraKeywordArg.call(value, ":unless option")
+            params_count = SeregaUtils::ParamsCount.call(value, max_count: 2)
 
-          def check_block(block)
-            return if valid_parameters?(block, accepted_count: 0..2)
-
-            raise SeregaError, block_parameters_error
-          end
-
-          def check_callable(callable)
-            return if valid_parameters?(callable.method(:call), accepted_count: 2..2)
-
-            raise SeregaError, callable_parameters_error
-          end
-
-          def valid_parameters?(data, accepted_count:)
-            params = data.parameters
-            accepted_count.include?(params.count) && valid_parameters_types?(params)
-          end
-
-          def valid_parameters_types?(params)
-            params.all? do |param|
-              type = param[0]
-              (type == :req) || (type == :opt)
+            if params_count > 2
+              raise SeregaError, "Option :unless value should have up to 2 parameters (object, context)"
             end
           end
 
-          def block_parameters_error
-            "Invalid attribute option :unless. When it is a Proc it can have maximum two regular parameters (object, context)"
-          end
-
-          def callable_parameters_error
-            "Invalid attribute option :unless. When it is a callable object it must have two regular parameters (object, context)"
-          end
-
           def must_be_callable
             "Invalid attribute option :unless. It must be a Symbol, a Proc or respond to :call"
           end

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

@@ -26,54 +26,22 @@ class Serega
 
           private
 
-          def check_type(value)
-            return if value.is_a?(Symbol)
-
-            raise SeregaError, must_be_callable unless value.respond_to?(:call)
-
-            if value.is_a?(Proc)
-              check_block(value)
-            else
-              check_callable(value)
-            end
-          end
-
           def check_usage_with_other_params(opts)
             raise SeregaError, "Option :unless_value can not be used together with option :serializer" if opts.key?(:serializer)
           end
 
-          def check_block(block)
-            return if valid_parameters?(block, accepted_count: 0..2)
-
-            raise SeregaError, block_parameters_error
-          end
-
-          def check_callable(callable)
-            return if valid_parameters?(callable.method(:call), accepted_count: 2..2)
-
-            raise SeregaError, callable_parameters_error
-          end
+          def check_type(value)
+            return if value.is_a?(Symbol)
+            raise SeregaError, must_be_callable unless value.respond_to?(:call)
 
-          def valid_parameters?(data, accepted_count:)
-            params = data.parameters
-            accepted_count.include?(params.count) && valid_parameters_types?(params)
-          end
+            SeregaValidations::Utils::CheckExtraKeywordArg.call(value, ":unless_value option")
+            params_count = SeregaUtils::ParamsCount.call(value, max_count: 2)
 
-          def valid_parameters_types?(params)
-            params.all? do |param|
-              type = param[0]
-              (type == :req) || (type == :opt)
+            if params_count > 2
+              raise SeregaError, "Option :unless_value value should have up to 2 parameters (value, context)"
             end
           end
 
-          def block_parameters_error
-            "Invalid attribute option :unless_value. When it is a Proc it can have maximum two regular parameters (object, context)"
-          end
-
-          def callable_parameters_error
-            "Invalid attribute option :unless_value. When it is a callable object it must have two regular parameters (object, context)"
-          end
-
           def must_be_callable
             "Invalid attribute option :unless_value. It must be a Symbol, a Proc or respond to :call"
           end

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

@@ -20,7 +20,7 @@ class Serega
           # @return [Proc] Meta attribute options
           attr_reader :opts
 
-          # @return [Proc] Meta attribute originally added block
+          # @return [Proc,nil] Meta attribute originally added block
           attr_reader :block
 
           #
@@ -39,6 +39,7 @@ class Serega
             @path = SeregaUtils::EnumDeepDup.call(path)
             @opts = SeregaUtils::EnumDeepDup.call(opts)
             @block = block
+            @normalized_block = normalize_block(opts[:value], opts[:const], block)
           end
 
           #
@@ -50,19 +51,34 @@ class Serega
           # @return [Object] Serialized meta attribute value
           #
           def value(object, context)
-            block.call(object, context)
+            normalized_block.call(object, context)
           end
 
           def hide?(value)
-            (opts[:hide_nil] && value.nil?) || (opts[:hide_empty] && value.empty?)
+            (!!opts[:hide_nil] && value.nil?) || (!!opts[:hide_empty] && (value.nil? || (value.respond_to?(:empty?) && value.empty?)))
           end
 
           private
 
+          attr_reader :normalized_block
+
+          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
+          end
+
           def check(path, opts, block)
             CheckPath.call(path) if check_attribute_name
-            CheckOpts.call(opts, attribute_keys)
-            CheckBlock.call(block)
+            CheckOpts.call(opts, block, attribute_keys)
+            CheckBlock.call(block) if block
           end
 
           def attribute_keys

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

@@ -10,17 +10,24 @@ class Serega
     # Adds ability to describe metadata that must be added to serialized response
     #
     # Added class-level method `:meta_attribute`, to define metadata, it accepts:
-    # - *path [Array<Symbol>] - nested hash keys beginning from the root object.
-    # - **options [Hash] - defaults are `hide_nil: false, hide_empty: false`
-    # - &block [Proc] - describes value for current meta attribute
+    #
+    # - `*path` [Array of Symbols] - nested hash keys.
+    # - `**options` [Hash]
+    #
+    #   - `:const` - describes metadata value (if it is constant)
+    #   - `:value` - describes metadata value as any `#callable` instance
+    #   - `:hide_nil` - does not show metadata key if value is nil, `false` by default
+    #   - `:hide_empty`, does not show metadata key if value is nil or empty, `false` by default
+    #
+    # - `&block` [Proc] - describes value for current meta attribute
     #
     # @example
     #  class AppSerializer < Serega
     #    plugin :root
     #    plugin :metadata
     #
-    #    meta_attribute(:version) { '1.2.3' }
-    #    meta_attribute(:ab_tests, :names) { %i[foo bar] }
+    #    meta_attribute(:version, const: '1.2.3')
+    #    meta_attribute(:ab_tests, :names, value: ABTests.new.method(:names))
     #    meta_attribute(:meta, :paging, hide_nil: true) do |records, ctx|
     #      next unless records.respond_to?(:total_count)
     #
@@ -28,7 +35,7 @@ class Serega
     #    end
     #  end
     #
-    #  AppSerializer.to_h(nil) # => {:data=>nil, :version=>"1.2.3", :ab_tests=>{:names=>[:foo, :bar]}}
+    #  AppSerializer.to_h(nil) # => {:data=>nil, :version=>"1.2.3", :ab_tests=>{:names=> ... }}
     #
     module Metadata
       # @return [Symbol] Plugin name
@@ -64,8 +71,10 @@ class Serega
 
         require_relative "meta_attribute"
         require_relative "validations/check_block"
+        require_relative "validations/check_opt_const"
         require_relative "validations/check_opt_hide_nil"
         require_relative "validations/check_opt_hide_empty"
+        require_relative "validations/check_opt_value"
         require_relative "validations/check_opts"
         require_relative "validations/check_path"
 
@@ -83,7 +92,7 @@ class Serega
       # @return [void]
       #
       def self.after_load_plugin(serializer_class, **_opts)
-        serializer_class.config.opts[:metadata] = {attribute_keys: %i[path hide_nil hide_empty]}
+        serializer_class.config.opts[:metadata] = {attribute_keys: %i[const hide_nil hide_empty value]}
       end
 
       #

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

@@ -8,14 +8,10 @@ class Serega
         # Validator for meta_attribute block parameter
         #
         class CheckBlock
-          ALLOWED_PARAM_TYPES = %i[opt req]
-          private_constant :ALLOWED_PARAM_TYPES
-
           class << self
             #
             # Checks block provided with attribute
-            # Block must have up to two arguments - object and context.
-            # It should not have any *rest or **key arguments
+            # Block must have up to two arguments - object(s) and context.
             #
             # @example without arguments
             #   metadata(:version) { CONSTANT_VERSION }
@@ -24,7 +20,7 @@ class Serega
             #   metadata(:paging) { |scope| { { page: scope.page, per_page: scope.per_page, total_count: scope.total_count } }
             #
             # @example with two arguments
-            #   metadata(:paging) { |scope, context| { { ... } if context[:with_paging] }
+            #   metadata(:paging) { |scope, context| { { ... } if context[:pagy] }
             #
             # @param block [Proc] Block that returns serialized meta attribute value
             #
@@ -33,12 +29,16 @@ class Serega
             # @return [void]
             #
             def call(block)
-              raise SeregaError, "Block must be provided when defining meta attribute" unless block
+              SeregaValidations::Utils::CheckExtraKeywordArg.call(block, "block")
+              params_count = SeregaUtils::ParamsCount.call(block, max_count: 2)
+
+              raise SeregaError, block_error if params_count > 2
+            end
 
-              params = block.parameters
-              return if (params.count <= 2) && params.all? { |par| ALLOWED_PARAM_TYPES.include?(par[0]) }
+            private
 
-              raise SeregaError, "Block can have maximum 2 regular parameters (no **keyword or *array args)"
+            def block_error
+              "Block can have maximum two parameters (object(s), context)"
             end
           end
         end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Metadata
+      class MetaAttribute
+        #
+        # MetaAttribute `:const` option validator
+        #
+        class CheckOptConst
+          class << self
+            #
+            # Checks meta_attribute :const option
+            #
+            # @param opts [Hash] MetaAttribute options
+            #
+            # @raise [SeregaError] validation error
+            #
+            # @return [void]
+            #
+            def call(opts, block = nil)
+              return unless opts.key?(:const)
+
+              check_usage_with_other_params(opts, block)
+            end
+
+            private
+
+            def check_usage_with_other_params(opts, block)
+              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 block" if block
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Metadata
+      class MetaAttribute
+        #
+        # Validator for meta_attribute :value option
+        #
+        class CheckOptValue
+          class << self
+            #
+            # Checks attribute :value option
+            #
+            # @param opts [Hash] Attribute options
+            #
+            # @raise [SeregaError] SeregaError that option has invalid value
+            #
+            # @return [void]
+            #
+            def call(opts, block = nil)
+              return unless opts.key?(:value)
+
+              check_usage_with_other_params(opts, block)
+
+              check_value(opts[:value])
+            end
+
+            private
+
+            def check_usage_with_other_params(opts, block)
+              raise SeregaError, "Option :value can not be used together with option :const" if opts.key?(:const)
+              raise SeregaError, "Option :value can not be used together with block" if block
+            end
+
+            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
+            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"
+            end
+
+            def params_count_error
+              "Option :value value can have maximum 2 parameters (object(s), context)"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -10,31 +10,45 @@ class Serega
         class CheckOpts
           class << self
             #
-            # Validates attribute options
+            # Validates meta_attribute options
             # Checks used options are allowed and then checks options values.
             #
             # @param opts [Hash] Attribute options
-            # @param attribute_keys [Array<Symbol>] Allowed options keys
+            # @param block [Proc] Attribute block
+            # @param allowed_keys [Array<Symbol>] Allowed options keys
             #
             # @raise [SeregaError] when attribute has invalid options
             #
             # @return [void]
             #
-            def call(opts, attribute_keys)
+            def call(opts, block, allowed_keys)
+              check_allowed_options_keys(opts, allowed_keys)
+              check_each_opt(opts, block)
+              check_any_value_provided(opts, block)
+            end
+
+            private
+
+            def check_allowed_options_keys(opts, allowed_keys)
               opts.each_key do |key|
-                next if attribute_keys.include?(key.to_sym)
+                next if allowed_keys.include?(key.to_sym)
 
-                raise SeregaError, "Invalid option #{key.inspect}. Allowed options are: #{attribute_keys.map(&:inspect).join(", ")}"
+                allowed = allowed_keys.map(&:inspect).join(", ")
+                raise SeregaError, "Invalid option #{key.inspect}. Allowed options are: #{allowed}"
               end
-
-              check_each_opt(opts)
             end
 
-            private
-
-            def check_each_opt(opts)
+            def check_each_opt(opts, block)
               CheckOptHideEmpty.call(opts)
               CheckOptHideNil.call(opts)
+              CheckOptValue.call(opts, block)
+              CheckOptConst.call(opts, block)
+            end
+
+            def check_any_value_provided(opts, block)
+              return if opts.key?(:const) || opts.key?(:value) || block
+
+              raise SeregaError, "Please provide block argument or add :value or :const option"
             end
           end
         end

data/lib/serega/utils/params_count.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Utilities
+  #
+  module SeregaUtils
+    #
+    # Utility to count regular parameters of callable object
+    #
+    class ParamsCount
+      NO_NAMED_REST_PARAM = [:rest].freeze
+      private_constant :NO_NAMED_REST_PARAM
+
+      class << self
+        #
+        # Count parameters for callable object
+        #
+        # @param object [#call] callable object
+        #
+        # @return [Integer] count of regular parameters
+        #
+        def call(object, max_count:)
+          # Procs (but not lambdas) can accept all provided parameters
+          parameters = object.is_a?(Proc) ? object.parameters : object.method(:call).parameters
+          return 1 if parameters[0] == NO_NAMED_REST_PARAM
+          return max_count if object.is_a?(Proc) && !object.lambda?
+
+          count = 0
+
+          # If all we have is no-name *rest parameters, then we assume we need to provide
+          # 1 argument. It is now always correct, but in serialization context it's most common that
+          # only one argument is needed.
+          parameters.each do |parameter|
+            next if parameter == NO_NAMED_REST_PARAM # Workaround for procs like :odd?.to_proc
+            param_type = parameter[0]
+
+            case param_type
+            when :req then count += 1
+            when :opt then count += 1 if count < max_count
+            when :rest then count += max_count - count if max_count > count
+            end # else :opt, :keyreq, :key, :keyrest, :block - do nothing
+          end
+
+          count
+        end
+      end
+    end
+  end
+end

data/lib/serega/utils/to_hash.rb

@@ -31,7 +31,7 @@ class Serega
           when NilClass, FalseClass then nil_to_hash(value)
           when String then string_to_hash(value)
           when Symbol then symbol_to_hash(value)
-          else raise SeregaError, "Cant convert #{value.class} class object to hash"
+          else raise SeregaError, "Can't convert #{value.class} class object to hash"
           end
         end
 

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

@@ -14,7 +14,6 @@ class Serega
           #
           # Checks block parameter provided with attribute.
           # Must have up to two arguments - object and context.
-          # It should not have any *rest or **key arguments
           #
           # @example without arguments
           #   attribute(:email) { CONSTANT_EMAIL }
@@ -40,14 +39,14 @@ class Serega
           private
 
           def check_block(block)
-            params = block.parameters
-            return if (params.count <= 2) && params.all? { |par| par[0] == :opt }
+            SeregaValidations::Utils::CheckExtraKeywordArg.call(block, "block")
+            params_count = SeregaUtils::ParamsCount.call(block, max_count: 2)
 
-            raise SeregaError, block_error
+            raise SeregaError, block_error if params_count > 2
           end
 
           def block_error
-            "Block can have maximum two regular parameters (no **keyword or *array args)"
+            "Block can have maximum two parameters (object, context)"
           end
         end
       end

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

@@ -21,7 +21,8 @@ class Serega
             return unless opts.key?(:value)
 
             check_usage_with_other_params(opts, block)
-            check_proc(opts[:value])
+
+            check_value(opts[:value])
           end
 
           private
@@ -32,22 +33,25 @@ class Serega
             raise SeregaError, "Option :value can not be used together with block" if block
           end
 
-          def check_proc(value)
-            raise SeregaError, value_error unless value.is_a?(Proc)
+          def check_value(value)
+            check_value_type(value)
+
+            SeregaValidations::Utils::CheckExtraKeywordArg.call(value, ":value option")
+            params_count = SeregaUtils::ParamsCount.call(value, max_count: 2)
 
-            params = value.parameters
+            raise SeregaError, params_count_error if params_count > 2
+          end
 
-            if value.lambda?
-              return if (params.count == 2) && params.all? { |par| par[0] == :req }
-            elsif (params.count <= 2) && params.all? { |par| par[0] == :opt }
-              return
-            end
+          def check_value_type(value)
+            raise SeregaError, type_error if !value.is_a?(Proc) && !value.respond_to?(:call)
+          end
 
-            raise SeregaError, value_error
+          def type_error
+            "Option :value value must be a Proc or respond to #call"
           end
 
-          def value_error
-            "Option :value must be a Proc that is able to accept two parameters (no **keyword or *array args)"
+          def params_count_error
+            "Option :value value can have maximum 2 parameters (object, context)"
           end
         end
       end

data/lib/serega/validations/check_attribute_params.rb

@@ -55,6 +55,7 @@ class Serega
         # 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