serega 0.38.0 → 0.40.0

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

@@ -17,11 +17,11 @@ class Serega
           #
           # @return [void]
           #
-          def call(serializer_class, opts, block)
+          def call(serializer_class, opts)
             return unless opts.key?(:batch)
 
             check_opt_batch(opts, serializer_class)
-            check_usage_with_other_params(opts, block)
+            check_usage_with_other_params(opts)
           end
 
           private
@@ -72,22 +72,22 @@ class Serega
             Utils::CheckAllowedKeys.call(batch_opts, %i[use id], :batch)
           end
 
-          def check_usage_with_other_params(opts, block)
+          def check_usage_with_other_params(opts)
             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
+            value_added = opts.key?(:value)
 
             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"
+              raise SeregaError, "Attribute :value option 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"
+              raise SeregaError, "Option `batch.id` should not be used when :value option provided directly"
             end
 
             raise SeregaError, "Option :batch can not be used together with option :method" if opts.key?(:method)

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

@@ -17,19 +17,18 @@ class Serega
           #
           # @return [void]
           #
-          def call(opts, block = nil)
+          def call(opts)
             return unless opts.key?(:const)
 
-            check_usage_with_other_params(opts, block)
+            check_usage_with_other_params(opts)
           end
 
           private
 
-          def check_usage_with_other_params(opts, block)
+          def check_usage_with_other_params(opts)
             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
       end

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

@@ -18,11 +18,11 @@ class Serega
           #
           # @return [void]
           #
-          def call(opts, block = nil)
+          def call(opts)
             return unless opts.key?(:delegate)
 
             check_opt_delegate(opts)
-            check_usage_with_other_params(opts, block)
+            check_usage_with_other_params(opts)
           end
 
           private
@@ -34,6 +34,8 @@ class Serega
             check_opt_delegate_to(delegate_opts)
             check_opt_delegate_method(delegate_opts)
             check_opt_delegate_allow_nil(delegate_opts)
+            check_opt_delegate_to_hash_access(delegate_opts)
+            check_opt_delegate_hash_access(delegate_opts)
             check_opt_delegate_extra_opts(delegate_opts)
           end
 
@@ -48,20 +50,58 @@ class Serega
             Utils::CheckOptIsStringOrSymbol.call(delegate_opts, :method)
           end
 
+          # Covers only the intermediate object being nil — a missing key on
+          # either step is each step's own :allow_missing_key sub-option.
           def check_opt_delegate_allow_nil(delegate_opts)
             Utils::CheckOptIsBool.call(delegate_opts, :allow_nil)
           end
 
+          # Hash access of the intermediate (:to) step. Accepts the same
+          # forms as the final (:method) step.
+          def check_opt_delegate_to_hash_access(delegate_opts)
+            check_hash_access_value(delegate_opts, :to_hash_access)
+          end
+
+          # Hash access of the final (:method) step. Accepts the same forms
+          # as the attribute :hash_access option.
+          def check_opt_delegate_hash_access(delegate_opts)
+            check_hash_access_value(delegate_opts, :hash_access)
+          end
+
+          def check_hash_access_value(delegate_opts, opt_name)
+            return unless delegate_opts.key?(opt_name)
+
+            value = delegate_opts[opt_name]
+            case value
+            when true, false then nil
+            when Symbol then check_hash_access_mode(value)
+            when Hash
+              Utils::CheckAllowedKeys.call(value, %i[mode allow_missing_key], opt_name)
+              check_hash_access_mode(value[:mode]) if value.key?(:mode)
+              Utils::CheckOptIsBool.call(value, :allow_missing_key)
+            else
+              raise SeregaError,
+                "Invalid delegate option :#{opt_name} => #{value.inspect}." \
+                " It must be a Boolean, a Symbol mode (:symbol, :string)" \
+                " or a Hash with :mode and :allow_missing_key keys"
+            end
+          end
+
+          def check_hash_access_mode(mode)
+            return true if AttributeValueResolvers::HashAccessResolver::MODES.include?(mode)
+
+            raise SeregaError, "Invalid :hash_access mode #{mode.inspect}. Allowed modes: :symbol, :string"
+          end
+
           def check_opt_delegate_extra_opts(delegate_opts)
-            Utils::CheckAllowedKeys.call(delegate_opts, %i[to method allow_nil], :delegate)
+            Utils::CheckAllowedKeys.call(delegate_opts, %i[to method allow_nil to_hash_access hash_access], :delegate)
           end
 
-          def check_usage_with_other_params(opts, block)
+          def check_usage_with_other_params(opts)
             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
       end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaValidations
+    module Attribute
+      #
+      # Attribute `:hash_access` option validator
+      #
+      class CheckOptHashAccess
+        class << self
+          #
+          # Checks attribute :hash_access option
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
+          def call(opts)
+            return unless opts.key?(:hash_access)
+
+            value = opts[:hash_access]
+            check_value(value)
+            check_usage_with_other_params(opts) if value
+          end
+
+          private
+
+          def check_value(value)
+            case value
+            when true, false then nil
+            when Symbol then check_mode(value)
+            when Hash
+              Utils::CheckAllowedKeys.call(value, %i[mode allow_missing_key], :hash_access)
+              check_mode(value[:mode]) if value.key?(:mode)
+              check_allow_missing_key(value[:allow_missing_key]) if value.key?(:allow_missing_key)
+            else
+              raise SeregaError,
+                "Invalid option :hash_access => #{value.inspect}." \
+                " It must be a Boolean, a Symbol mode (:symbol, :string)" \
+                " or a Hash with :mode and :allow_missing_key keys"
+            end
+          end
+
+          def check_mode(mode)
+            return if AttributeValueResolvers::HashAccessResolver::MODES.include?(mode)
+
+            raise SeregaError, "Invalid :hash_access mode #{mode.inspect}. Allowed modes: :symbol, :string"
+          end
+
+          def check_allow_missing_key(allow_missing_key)
+            return if allow_missing_key == true || allow_missing_key == false
+
+            raise SeregaError, "Invalid :hash_access option :allow_missing_key => #{allow_missing_key.inspect}. Must be a Boolean"
+          end
+
+          # The :const, :value and :batch options do not read the serialized
+          # object by attribute name, so hash access can not affect them.
+          # Delegated attributes configure hash access per step with the
+          # `delegate: {to_hash_access:, hash_access:}` sub-options.
+          def check_usage_with_other_params(opts)
+            raise SeregaError, "Option :hash_access can not be used together with option :const" if opts.key?(:const)
+            raise SeregaError, "Option :hash_access can not be used together with option :value" if opts.key?(:value)
+            raise SeregaError, "Option :hash_access can not be used together with option :batch" if opts.key?(:batch)
+
+            if opts.key?(:delegate)
+              raise SeregaError,
+                "Option :hash_access can not be used together with option :delegate." \
+                " Use the delegate :to_hash_access (intermediate step) and" \
+                " :hash_access (final step) sub-options instead"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -12,28 +12,29 @@ class Serega
           # Checks attribute :many option
           #
           # @param opts [Hash] Attribute options
+          # @param block [nil, Proc] Attribute block
           #
           # @raise [SeregaError] SeregaError that option has invalid value
           #
           # @return [void]
           #
-          def call(opts)
+          def call(opts, block = nil)
             return unless opts.key?(:many)
 
-            check_many_option_makes_sence(opts)
+            check_many_option_makes_sence(opts, block)
             Utils::CheckOptIsBool.call(opts, :many)
           end
 
           private
 
-          def check_many_option_makes_sence(opts)
-            return if many_option_makes_sence?(opts)
+          def check_many_option_makes_sence(opts, block)
+            return if many_option_makes_sence?(opts, block)
 
-            raise SeregaError, "Option :many can be provided only together with :serializer or :batch option"
+            raise SeregaError, "Option :many can be provided only together with :serializer, :batch option or a block"
           end
 
-          def many_option_makes_sence?(opts)
-            opts[:serializer] || opts[:batch]
+          def many_option_makes_sence?(opts, block)
+            opts[:serializer] || opts[:batch] || block
           end
         end
       end

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

@@ -17,20 +17,19 @@ class Serega
           #
           # @return [void]
           #
-          def call(opts, block = nil)
+          def call(opts)
             return unless opts.key?(:method)
 
-            check_usage_with_other_params(opts, block)
+            check_usage_with_other_params(opts)
             Utils::CheckOptIsStringOrSymbol.call(opts, :method)
           end
 
           private
 
-          def check_usage_with_other_params(opts, block)
+          def check_usage_with_other_params(opts)
             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
       end

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

@@ -12,14 +12,17 @@ class Serega
           # 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)
+          def call(opts, block = nil)
             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

@@ -17,20 +17,19 @@ class Serega
           #
           # @return [void]
           #
-          def call(opts, block = nil)
+          def call(opts)
             return unless opts.key?(:value)
 
-            check_usage_with_other_params(opts, block)
+            check_usage_with_other_params(opts)
 
             check_value(opts[:value])
           end
 
           private
 
-          def check_usage_with_other_params(opts, block)
+          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)
-            raise SeregaError, "Option :value can not be used together with block" if block
           end
 
           def check_value(value)

data/lib/serega/validations/check_attribute_params.rb

@@ -59,15 +59,17 @@ class Serega
         def check_opts
           Utils::CheckAllowedKeys.call(opts, allowed_opts_keys, :attribute)
 
-          Attribute::CheckOptConst.call(opts, block)
-          Attribute::CheckOptDelegate.call(opts, block)
+          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, block)
-          Attribute::CheckOptMany.call(opts)
+          Attribute::CheckOptMethod.call(opts)
+          Attribute::CheckOptMany.call(opts, block)
           Attribute::CheckOptPreload.call(opts)
-          Attribute::CheckOptSerializer.call(opts)
-          Attribute::CheckOptValue.call(opts, block)
-          Attribute::CheckOptBatch.call(self.class.serializer_class, opts, block)
+          Attribute::CheckOptSerializer.call(opts, block)
+          Attribute::CheckOptValue.call(opts)
+          Attribute::CheckOptBatch.call(self.class.serializer_class, opts)
         end
 
         def check_block

data/lib/serega.rb

@@ -19,6 +19,7 @@ end
 
 require_relative "serega/errors"
 require_relative "serega/helpers/serializer_class_helper"
+require_relative "serega/utils/collection_detector"
 require_relative "serega/utils/enum_deep_dup"
 require_relative "serega/utils/enum_deep_freeze"
 require_relative "serega/utils/method_signature"
@@ -28,6 +29,7 @@ require_relative "serega/utils/to_hash"
 require_relative "serega/attribute_value_resolvers/batch"
 require_relative "serega/attribute_value_resolvers/const"
 require_relative "serega/attribute_value_resolvers/delegate"
+require_relative "serega/attribute_value_resolvers/hash_access"
 require_relative "serega/attribute_value_resolvers/keyword"
 require_relative "serega/attribute"
 require_relative "serega/attribute_normalizer"
@@ -40,10 +42,12 @@ require_relative "serega/validations/utils/check_opt_is_hash"
 require_relative "serega/validations/utils/check_opt_is_string_or_symbol"
 require_relative "serega/validations/attribute/check_block"
 require_relative "serega/validations/attribute/check_name"
+require_relative "serega/validations/attribute/check_opt_base_serializer"
 require_relative "serega/validations/attribute/check_opt_const"
 require_relative "serega/validations/attribute/check_opt_hide"
 require_relative "serega/validations/attribute/check_opt_delegate"
 require_relative "serega/validations/attribute/check_opt_batch"
+require_relative "serega/validations/attribute/check_opt_hash_access"
 require_relative "serega/validations/attribute/check_opt_many"
 require_relative "serega/validations/attribute/check_opt_method"
 require_relative "serega/validations/attribute/check_opt_preload"
@@ -168,7 +172,19 @@ class Serega
     #
     # @param name [Symbol] Attribute name. Attribute value will be found by executing `object.<name>`
     # @param opts [Hash] Options to serialize attribute
-    # @param block [Proc] Custom block to find attribute value. Accepts object and context.
+    # @param block [Proc] Defines attributes of a nested anonymous serializer.
+    #   The block is executed in the context of that serializer, so everything
+    #   available in a serializer class body can be used inside. The attribute
+    #   value (found by name/:method/:value/:delegate/:const/:batch as usual)
+    #   is serialized with this nested serializer. The nested serializer
+    #   inherits from the `:base_serializer` attribute option or
+    #   `config.base_serializer` (one of them is required).
+    #
+    # @example
+    #   attribute :statistics, method: :itself do
+    #     attribute :likes_count
+    #     attribute :comments_count
+    #   end
     #
     # @return [Serega::SeregaAttribute] Added attribute
     #
@@ -254,7 +270,7 @@ class Serega
     # @option opts [Array, Hash, String, Symbol] :with Attributes (usually hidden) to serialize additionally
     # @option opts [Boolean] :validate Validates provided modifiers (Default is true)
     # @option opts [Hash] :context Serialization context
-    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable)`)
+    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
     #
     # @return [Hash] Serialization result
     #
@@ -275,7 +291,7 @@ class Serega
     # @option opts [Array, Hash, String, Symbol] :with Attributes (usually hidden) to serialize additionally
     # @option opts [Boolean] :validate Validates provided modifiers (Default is true)
     # @option opts [Hash] :context Serialization context
-    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable)`)
+    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
     #
     # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
     #
@@ -409,7 +425,7 @@ class Serega
     # @param object [Object] Serialized object
     # @param opts [Hash, nil] Serializing options
     # @option opts [Hash] :context Serialization context
-    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable)`)
+    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
     #
     # @return [Hash] Serialization result
     #
@@ -431,7 +447,7 @@ class Serega
     # @param object [Object] Serialized object
     # @param opts [Hash, nil] Serializing options
     # @option opts [Hash] :context Serialization context
-    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable)`)
+    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
     #
     # @return [Data] Serialization result
     #
@@ -472,7 +488,7 @@ class Serega
 
       opts[:context] ||= {}
       opts[:level_queue] = SeregaEngine::LevelQueue.new
-      opts[:many] = object.is_a?(Enumerable) unless opts.key?(:many)
+      opts[:many] = SeregaUtils::CollectionDetector.call(object) unless opts.key?(:many)
       opts[:plan] = plan
       opts
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.38.0
+  version: 0.40.0
 platform: ruby
 authors:
 - Andrey Glushkov
@@ -32,6 +32,7 @@ files:
 - lib/serega/attribute_value_resolvers/batch.rb
 - lib/serega/attribute_value_resolvers/const.rb
 - lib/serega/attribute_value_resolvers/delegate.rb
+- lib/serega/attribute_value_resolvers/hash_access.rb
 - lib/serega/attribute_value_resolvers/keyword.rb
 - lib/serega/config.rb
 - lib/serega/data_builder.rb
@@ -70,6 +71,7 @@ files:
 - lib/serega/plugins/root/root.rb
 - lib/serega/plugins/string_modifiers/parse_string_modifiers.rb
 - lib/serega/plugins/string_modifiers/string_modifiers.rb
+- lib/serega/utils/collection_detector.rb
 - lib/serega/utils/enum_deep_dup.rb
 - lib/serega/utils/enum_deep_freeze.rb
 - lib/serega/utils/method_signature.rb
@@ -78,9 +80,11 @@ files:
 - lib/serega/utils/to_hash.rb
 - lib/serega/validations/attribute/check_block.rb
 - lib/serega/validations/attribute/check_name.rb
+- lib/serega/validations/attribute/check_opt_base_serializer.rb
 - lib/serega/validations/attribute/check_opt_batch.rb
 - lib/serega/validations/attribute/check_opt_const.rb
 - lib/serega/validations/attribute/check_opt_delegate.rb
+- lib/serega/validations/attribute/check_opt_hash_access.rb
 - lib/serega/validations/attribute/check_opt_hide.rb
 - lib/serega/validations/attribute/check_opt_many.rb
 - lib/serega/validations/attribute/check_opt_method.rb