serega 0.42.0 → 0.50.0

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

@@ -1,31 +1,17 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaValidations
-    # @private
-    module Attribute
+  module SeregaValidations # :nodoc:
+    module Attribute # :nodoc:
       #
       # Attribute `:serializer` option validator
       #
-      # @private
-      class CheckOptSerializer
+      class CheckOptSerializer # :nodoc:
         class << self
-          #
           # Checks attribute :serializer option
-          #
-          # @param opts [Hash] Attribute options
-          # @param block [nil, Proc] Attribute block (defines a nested serializer)
-          #
-          # @raise [SeregaError] SeregaError that option has invalid value
-          #
-          # @return [void]
-          #
-          def call(opts, block = nil)
+          def call(opts)
             return unless opts.key?(:serializer)
 
-            raise SeregaError, "Option :serializer can not be used together with block" if block
-
             value = opts[:serializer]
             return if valid_serializer?(value)
 

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

@@ -1,40 +1,22 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaValidations
-    # @private
-    module Attribute
+  module SeregaValidations # :nodoc:
+    module Attribute # :nodoc:
       #
       # Attribute `:value` option validator
       #
-      # @private
-      class CheckOptValue
+      class CheckOptValue # :nodoc:
         class << self
-          #
           # Checks attribute :value option
-          #
-          # @param opts [Hash] Attribute options
-          #
-          # @raise [SeregaError] SeregaError that option has invalid value
-          #
-          # @return [void]
-          #
           def call(opts)
             return unless opts.key?(:value)
 
-            check_usage_with_other_params(opts)
-
             check_value(opts[:value])
           end
 
           private
 
-          def check_usage_with_other_params(opts)
-            raise SeregaError, "Option :value can not be used together with option :method" if opts.key?(:method)
-            raise SeregaError, "Option :value can not be used together with option :const" if opts.key?(:const)
-          end
-
           def check_value(value)
             check_value_type(value)
             signature = SeregaUtils::MethodSignature.call(value, pos_limit: 2, keyword_args: %i[ctx batches])

data/lib/serega/validations/check_attribute_params.rb

@@ -4,92 +4,113 @@ class Serega
   #
   # Validations
   #
-  # @private
-  module SeregaValidations
+  module SeregaValidations # :nodoc:
     #
     # Validations for attribute params
     #
-    # @private
-    class CheckAttributeParams
+    class CheckAttributeParams # :nodoc:
+      # Options of `Serega.attribute`
+      ATTRIBUTE_KEYS = %i[
+        method value serializer many hide const delegate default format preload batch
+        base_serializer hash_access if unless if_value unless_value
+      ].freeze
+
+      # Options that can't be given together, `block` for the attribute
+      # block. Each option lists every option it conflicts with, and the error
+      # names the option that comes first here. :hash_access with :delegate is
+      # left to CheckOptHashAccess, which points to the delegate sub-options.
+      CONFLICTS = {
+        method: %i[value const delegate batch],
+        value: %i[method const delegate hash_access],
+        const: %i[method value delegate batch hash_access preload],
+        delegate: %i[method value const batch],
+        batch: %i[method const delegate hash_access],
+        hash_access: %i[value const batch],
+        preload: %i[const],
+        serializer: %i[block if_value unless_value],
+        if_value: %i[serializer block],
+        unless_value: %i[serializer block]
+      }.freeze
+
+      # Validated attribute name
+      attr_reader :name
+
+      # Validated attribute options
+      attr_reader :opts
+
+      # Validated attribute block
+      attr_reader :block
+
+      # Initializes attribute params validator
+      def initialize(serializer_class, name, opts, block)
+        @serializer_class = serializer_class
+        @name = name
+        @opts = opts
+        @block = block
+      end
+
       #
-      # Validations for attribute params instance methods
+      # Validates attribute params
       #
-      # @private
-      module InstanceMethods
-        # @return [Symbol] validated attribute name
-        attr_reader :name
-
-        # @return [Hash] validated attribute options
-        attr_reader :opts
-
-        # @return [nil, Proc] validated attribute block
-        attr_reader :block
-
-        #
-        # Initializes attribute params validator
-        #
-        # @param name [Symbol] attribute name
-        # @param opts [Hash] attribute options
-        # @param block [nil, Proc] block provided to attribute
-        #
-        # @return [void]
-        #
-        def initialize(name, opts, block)
-          @name = name
-          @opts = opts
-          @block = block
-        end
+      def validate
+        check_name if check_attribute_name
+        check_opts
+        check_block
+      end
 
-        #
-        # Validates attribute params
-        #
-        def validate
-          check_name if check_attribute_name
-          check_opts
-          check_block
-        end
+      private
 
-        private
+      def check_name
+        Attribute::CheckName.call(name)
+      end
 
-        def check_name
-          Attribute::CheckName.call(name)
-        end
+      def check_opts
+        Utils::CheckAllowedKeys.call(opts, ATTRIBUTE_KEYS, :attribute)
+        check_conflicts
 
-        # Patched in:
-        # - 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)
-        def check_opts
-          Utils::CheckAllowedKeys.call(opts, allowed_opts_keys, :attribute)
-
-          Attribute::CheckOptBaseSerializer.call(opts, block)
-          Attribute::CheckOptConst.call(opts)
-          Attribute::CheckOptDelegate.call(opts)
-          Attribute::CheckOptHashAccess.call(opts)
-          Attribute::CheckOptHide.call(opts)
-          Attribute::CheckOptMethod.call(opts)
-          Attribute::CheckOptMany.call(opts, block)
-          Attribute::CheckOptPreload.call(opts)
-          Attribute::CheckOptSerializer.call(opts, block)
-          Attribute::CheckOptValue.call(opts)
-          Attribute::CheckOptBatch.call(self.class.serializer_class, opts)
-        end
+        Attribute::CheckOptBaseSerializer.call(opts, block)
+        Attribute::CheckOptCondition.call(opts, :if)
+        Attribute::CheckOptCondition.call(opts, :unless)
+        Attribute::CheckOptCondition.call(opts, :if_value)
+        Attribute::CheckOptCondition.call(opts, :unless_value)
+        Attribute::CheckOptDelegate.call(opts)
+        Attribute::CheckOptFormat.call(opts, @serializer_class)
+        Attribute::CheckOptHashAccess.call(opts)
+        Attribute::CheckOptHide.call(opts)
+        Attribute::CheckOptMethod.call(opts)
+        Attribute::CheckOptMany.call(opts, block, require_many)
+        Attribute::CheckOptPreload.call(opts)
+        Attribute::CheckOptSerializer.call(opts)
+        Attribute::CheckOptValue.call(opts)
+        Attribute::CheckOptBatch.call(@serializer_class, name, opts)
+      end
 
-        def check_block
-          Attribute::CheckBlock.call(block)
-        end
+      def check_block
+        Attribute::CheckBlock.call(block)
+      end
 
-        def allowed_opts_keys
-          self.class.serializer_class.config.attribute_keys
-        end
+      def check_conflicts
+        CONFLICTS.each do |option, others|
+          next unless opts.key?(option)
 
-        def check_attribute_name
-          self.class.serializer_class.config.check_attribute_name
+          other = others.find { |key| (key == :block) ? block : opts.key?(key) }
+          raise SeregaError, conflict_message(option, other) if other
         end
       end
 
-      include InstanceMethods
-      extend Serega::SeregaHelpers::SerializerClassHelper
+      def conflict_message(option, other)
+        return "Option #{option.inspect} can not be used together with block" if other == :block
+
+        "Option #{option.inspect} can not be used together with option #{other.inspect}"
+      end
+
+      def check_attribute_name
+        @serializer_class.config.check_attribute_name
+      end
+
+      def require_many
+        @serializer_class.config.require_many
+      end
     end
   end
 end

data/lib/serega/validations/check_batch_loader_params.rb

@@ -1,83 +1,64 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaValidations
+  module SeregaValidations # :nodoc:
     #
     # Batch loader parameters validators
     #
-    # @private
-    class CheckBatchLoaderParams
-      #
-      # batch_loader parameters validation instance methods
-      #
-      # @private
-      module InstanceMethods
-        # @return [Symbol] validated batch_loader name
-        attr_reader :name
+    class CheckBatchLoaderParams # :nodoc:
+      # Validated batch_loader name
+      attr_reader :name
 
-        # @return [nil, #call] validated batch_loader value or block
-        attr_reader :batch_loader
+      # 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
+      # Instantiates batch loader params checker
+      def initialize(name, batch_loader)
+        @name = name
+        @batch_loader = batch_loader
+      end
 
-        private
+      # Checks batch loader parameters
+      def validate
+        check_name
+        check_loader
+      end
 
-        def check_name
-          raise SeregaError, name_type_error if !name.is_a?(Symbol) && !name.is_a?(String)
-        end
+      private
 
-        def check_loader
-          check_batch_loader_type
-          check_batch_loader_args
-        end
+      def check_name
+        raise SeregaError, name_type_error if !name.is_a?(Symbol) && !name.is_a?(String)
+      end
 
-        def check_batch_loader_type
-          raise SeregaError, type_error if !batch_loader.is_a?(Proc) && !batch_loader.respond_to?(:call)
-        end
+      def check_loader
+        check_batch_loader_type
+        check_batch_loader_args
+      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 check_batch_loader_type
+        raise SeregaError, type_error if !batch_loader.is_a?(Proc) && !batch_loader.respond_to?(:call)
+      end
 
-        def name_type_error
-          "Batch loader name must be a Symbol or String"
-        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 type_error
-          "Batch loader value must be a Proc or respond to #call"
-        end
+      def name_type_error
+        "Batch loader name must be a Symbol or String"
+      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
+      def type_error
+        "Batch loader value must be a Proc or respond to #call"
       end
 
-      include InstanceMethods
-      extend Serega::SeregaHelpers::SerializerClassHelper
+      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
   end
 end

data/lib/serega/validations/check_formatter.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaValidations # :nodoc:
+    #
+    # Validator for formatters defined with `Serega.formatter` or given
+    # directly as the attribute :format option
+    #
+    class CheckFormatter # :nodoc:
+      class << self
+        # Checks the formatter is a callable with valid parameters, a method
+        # name, or an Array of a method name and its arguments. The attribute
+        # :format option also accepts a Hash with one of them as :use and the
+        # :allow_nil option.
+        def call(formatter_name, formatter)
+          if formatter.is_a?(Hash) && !formatter_name
+            Utils::CheckAllowedKeys.call(formatter, %i[use allow_nil], :formatter)
+            Utils::CheckOptIsBool.call(formatter, :allow_nil)
+            formatter = formatter[:use]
+          end
+
+          check_value(formatter_name, formatter)
+        end
+
+        private
+
+        def check_value(formatter_name, formatter)
+          return if formatter.is_a?(Symbol)
+          return if formatter.is_a?(Array) && formatter.first.is_a?(Symbol)
+          raise SeregaError, invalid_formatter(formatter_name) unless formatter.respond_to?(:call)
+
+          signature = SeregaUtils::MethodSignature.call(formatter, pos_limit: 2, keyword_args: [:ctx])
+          raise SeregaError, signature_error unless valid_signature?(signature)
+        end
+
+        def valid_signature?(signature)
+          case signature
+          when "1"      # (value)
+            true
+          when "2"      # (value, context)
+            true
+          when "1_ctx"  # (value, :ctx)
+            true
+          else
+            false
+          end
+        end
+
+        def invalid_formatter(formatter_name)
+          return invalid_format_option unless formatter_name
+
+          <<~ERROR.strip
+            Invalid formatter #{formatter_name.inspect}. A formatter must be one of:
+            - a callable, for example ->(value) { value.round(2) }
+            - a method name, for example :to_s
+            - an Array of a method name and its arguments, for example [:round, 2]
+          ERROR
+        end
+
+        def invalid_format_option
+          <<~ERROR.strip
+            Invalid attribute option :format. It must be a formatter name or one of:
+            - a callable, for example ->(value) { value.round(2) }
+            - an Array of a method name and its arguments, for example [:round, 2]
+            - a Hash with one of them or a method name as :use and the :allow_nil option, for example {use: :to_s, allow_nil: true}
+          ERROR
+        end
+
+        def signature_error
+          <<~ERROR.strip
+            Invalid formatter parameters, valid parameters signatures:
+            - (value)          # one positional parameter
+            - (value, context) # two positional parameters
+            - (value, :ctx)    # one positional parameter and :ctx keyword
+          ERROR
+        end
+      end
+    end
+  end
+end

data/lib/serega/validations/check_serialize_keywords.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaValidations # :nodoc:
+    #
+    # Validator for the :context and :many serialization options
+    #
+    class CheckSerializeKeywords # :nodoc:
+      class << self
+        # Checks the context is a Hash and many is a boolean, when given
+        def call(context, many)
+          unless context.nil? || context.is_a?(Hash)
+            raise SeregaError, "Invalid option :context => #{context.inspect}. Must have a Hash value"
+          end
+
+          return if many.nil? || many.equal?(true) || many.equal?(false)
+
+          raise SeregaError, "Invalid option :many => #{many.inspect}. Must have a boolean value"
+        end
+      end
+    end
+  end
+end

data/lib/serega/validations/initiate/check_modifiers.rb

@@ -1,34 +1,28 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaValidations
+  module SeregaValidations # :nodoc:
     #
     # Validations that take place when initializing serializer
     #
-    # @private
-    module Initiate
+    module Initiate # :nodoc:
       #
       # Modifiers validation
       #
-      # @private
-      class CheckModifiers
+      class CheckModifiers # :nodoc:
         #
-        # Validates provided fields names are existing attributes
-        #
-        # @param serializer_class [Serega]
-        # @param only [Hash, nil] `only` modifier
-        # @param with [Hash, nil] `with` modifier
-        # @param except [Hash, nil] `except` modifier
-        #
-        # @raise [Serega::AttributeNotExist] when some checked modifier has not existing attribute
-        #
-        # @return [void]
+        # Instantiates modifiers validator
         #
+        def initialize
+          @parents_names = nil
+          @error_attributes = nil
+        end
+
+        # Validates provided fields names are existing attributes
         def call(serializer_class, only, with, except)
-          validate(serializer_class, only) if only
-          validate(serializer_class, with) if with
-          validate(serializer_class, except) if except
+          validate(serializer_class, only)
+          validate(serializer_class, with)
+          validate(serializer_class, except)
 
           raise_errors(serializer_class) if any_error?
         end
@@ -85,7 +79,7 @@ class Serega
         end
 
         def any_error?
-          defined?(@error_attributes)
+          !@error_attributes.nil?
         end
       end
     end

data/lib/serega/validations/utils/check_allowed_keys.rb

@@ -1,26 +1,16 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaValidations
+  module SeregaValidations # :nodoc:
     #
     # Validations Utilities
     #
-    # @private
-    module Utils
+    module Utils # :nodoc:
       #
       # Utility to check all hash keys are allowed
       #
-      # @private
-      class CheckAllowedKeys
+      class CheckAllowedKeys # :nodoc:
         # Checks hash keys are allowed
-        #
-        # @param opts [Hash] Some options Hash
-        # @param allowed_keys [Array] Allowed hash keys
-        #
-        # @raise [Serega::SeregaError] error when any hash key is not allowed
-        #
-        # @return [void]
         def self.call(opts, allowed_keys, parameter_name)
           opts.each_key do |key|
             next if allowed_keys.include?(key)

data/lib/serega/validations/utils/check_hash_access_value.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaValidations # :nodoc:
+    module Utils # :nodoc:
+      #
+      # Validator of a hash access value: the attribute :hash_access option and
+      # the delegate :to_hash_access and :hash_access sub-options
+      #
+      class CheckHashAccessValue # :nodoc:
+        class << self
+          # Checks that the `key` value is a Boolean, a Symbol mode or a Hash
+          # with :mode and :allow_missing_key
+          def call(opts, key)
+            return unless opts.key?(key)
+
+            value = opts[key]
+            case value
+            when true, false then nil
+            when Symbol then check_mode(value)
+            when Hash
+              CheckAllowedKeys.call(value, %i[mode allow_missing_key], key)
+              check_mode(value[:mode]) if value.key?(:mode)
+              CheckOptIsBool.call(value, :allow_missing_key)
+            else
+              raise SeregaError,
+                "Invalid option #{key.inspect} => #{value.inspect}." \
+                " It must be a Boolean, a Symbol mode (:symbol, :string)" \
+                " or a Hash with :mode and :allow_missing_key keys"
+            end
+          end
+
+          private
+
+          def check_mode(mode)
+            return if AttributeValueResolvers::HashAccessResolver::MODES.include?(mode)
+
+            raise SeregaError, "Invalid :hash_access mode #{mode.inspect}. Allowed modes: :symbol, :string"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/validations/utils/check_opt_is_bool.rb

@@ -1,23 +1,13 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaValidations
-    # @private
-    module Utils
+  module SeregaValidations # :nodoc:
+    module Utils # :nodoc:
       #
       # Utility to check hash key value is boolean
       #
-      # @private
-      class CheckOptIsBool
+      class CheckOptIsBool # :nodoc:
         # Checks hash key has boolean value
-        #
-        # @param opts [Hash] Some options Hash
-        # @param key [Object] Hash key
-        #
-        # @raise [Serega::SeregaError] error when provided key exists and value is not boolean
-        #
-        # @return [void]
         def self.call(opts, key)
           return unless opts.key?(key)