serega 0.39.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a223242ae8bce14755fa2cbb444ff78728d95fccb0ce3077c212706e39e4ddcc
-  data.tar.gz: b8e1d3bdf11a57091cfd22eb31bb017979382df4b2166b05f746d064dc486f6e
+  metadata.gz: 42da0ff66dc5eeb282fbb72144f78bcfc8ded1aa8609122ded10093f6c83dd96
+  data.tar.gz: f9fb2a2628756540cd08a5449a21883b0cf28ec45db8f461ee0944fd0f3812e9
 SHA512:
-  metadata.gz: d815a4a17625533c34659451851c33806bd4d1e0bf862945b2118d52315726184322c55d989378cf8ac7f9b4d04a392dfa344af196491b984ddc1d094d15c063
-  data.tar.gz: ecf2be1cff661bfe8e99103748276969f72442b04b8308dd136d137dc88f28dfb543ad73a5e0880a31eb6f6c4a6a51e6ccab307a92f867551ff4b19b56d38f73
+  metadata.gz: 1355573b7cb8d30ffbf844be46c03c4a5233fa9c190fa5e03fd39c0d1a396b9f7a19e7e2d4cf3afbd0445cd1d8dfc8ebbd1df6d77d91d338c0ede561c836fb99
+  data.tar.gz: 90ccd454b970598f9921ec1a6c9feab325a373d5628f884515141d34a3a72e7012273e37aa903046e064876f92bd956783ef3a9b93732ee23a8bcc8bec154ee3

data/README.md

@@ -26,6 +26,7 @@ It has some great features:
   keeping the code dry
 - Conditional attributes - ([if][if] plugin)
 - Auto camelCase keys - [camel_case][camel_case] plugin
+- Serializing Hash records - [hash_access][hash_access] attribute option
 
 ## Installation
 
@@ -74,8 +75,9 @@ class UserSerializer < Serega
   # Regular attribute
   attribute :first_name
 
-  # Option :method specifies the method that must be called on the
-  # serialized object
+  # Option :method specifies the name used to read the attribute's value —
+  # a method called on the serialized object by default, or a Hash key when
+  # combined with :hash_access
   attribute :first_name, method: :old_first_name
 
   # Attribute blocks below require a base serializer for nested serializers.
@@ -494,6 +496,12 @@ class AppSerializer < Serega
   #   proc { |object, batches:| batches[:counter][object.id] }
   config.batch_id_option = :id
 
+  # Defaults for the `hash_access:` attribute option — `default_mode` is
+  # what `hash_access: true` (and a Hash form omitting :mode) resolves to.
+  # See "Serializing Hash records".
+  config.hash_access.default_mode = :symbol # the default
+  config.hash_access.default_allow_missing_key = false # the default
+
   # Parent class for nested serializers defined with attribute blocks.
   # Usually a settings-only serializer, e.g. `config.base_serializer = self`
   # in an application base serializer class. There is no default — an
@@ -664,6 +672,69 @@ end
 
 ---
 
+## Serializing Hash records
+
+(objects should implement `#[]`, `#fetch`, and `#key?` - Hash already has them)
+
+The `hash_access: <mode>` attribute option makes an attribute read its value from
+Hash keys instead of calling a method.
+
+Allowed `<mode>`:
+
+- `:symbol` reads record[:name]
+- `:string` reads record["name"]
+- `true` shorthand for `config.hash_access.default_mode` (`:symbol` by default)
+
+By default missing keys will raise `KeyError`.
+
+`config.hash_access.default_allow_missing_key = true` will change `KeyError`
+to return `nil` value instead. `config.hash_access.default_mode = <mode>`
+changes what `true` (and a Hash form omitting `:mode`) resolves to.
+
+```ruby
+class UserSerializer < Serega
+  config.hash_access.default_mode = :symbol             # the default
+  config.hash_access.default_allow_missing_key = true    # false by default
+
+  attribute :name, hash_access: true     # reads record[:name] (config.hash_access.default_mode)
+  attribute :name, hash_access: :symbol  # reads record[:name]
+  attribute :name, hash_access: :string  # reads record["name"]
+
+  # Use long form if you need to override `allow_missing_key`
+  attribute :name, hash_access: { allow_missing_key: false }
+  attribute :name, hash_access: { mode: :symbol, allow_missing_key: false }
+  attribute :name, hash_access: { mode: :string, allow_missing_key: false }
+end
+```
+
+Delegated attributes configure hash access **per step**:
+
+- `to_hash_access` configures reading `<mode>` for intermediate object
+- `hash_access` configures reading `<mode>` for final key
+
+```ruby
+# reads `record.address.city` (no hash access)
+attribute :city, delegate: { to: :address } # record.address.city
+
+# reads record.address[:city]
+attribute :city, delegate: { to: :address, hash_access: :symbol }
+
+# reads record[:address].city
+attribute :city, delegate: { to: :address, to_hash_access: :symbol }
+
+# reads record[:address][:city]
+attribute :city, delegate: { to: :address, to_hash_access: :symbol, hash_access: :symbol }
+
+# reads record["address"] and if exists returns record["address"][:city]
+attribute :city,
+  delegate: {
+    to: :address,
+    allow_nil: true,
+    to_hash_access: { mode: :string, allow_missing_key: true },
+    hash_access: { mode: :symbol, allow_missing_key: false }
+  }
+```
+
 ## Plugins
 
 ### Plugin :activerecord_preloads
@@ -1128,6 +1199,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 [context_metadata]: #plugin-context_metadata
 [depth_limit]: #plugin-depth_limit
 [formatters]: #plugin-formatters
+[hash_access]: #serializing-hash-records
 [metadata]: #plugin-metadata
 [preloads]: #preloads
 [presenter]: #plugin-presenter

data/VERSION

@@ -1 +1 @@
-0.39.0
+0.40.0

data/lib/serega/attribute_normalizer.rb

@@ -254,7 +254,10 @@ class Serega
       end
 
       def prepare_keyword_block
-        AttributeValueResolvers::KeywordResolver.get(method_name)
+        mode, allow_nil = hash_access
+        return AttributeValueResolvers::KeywordResolver.get(method_name) unless mode
+
+        AttributeValueResolvers::HashAccessResolver.get(method_name, mode, allow_nil)
       end
 
       def prepare_batch_loader_block
@@ -291,15 +294,68 @@ class Serega
         init_opts.fetch(:default) { many ? FROZEN_EMPTY_ARRAY : nil }
       end
 
+      # `delegate: {to_hash_access: ...}` configures hash access for the
+      # intermediate (:to) read, `delegate: {hash_access: ...}` for the
+      # final (:method) read. A step without its sub-option keeps a plain
+      # method read.
       def prepare_delegate_block
         delegate = init_opts[:delegate]
         return unless delegate
 
         key_method_name = delegate[:method] || method_name
         delegate_to = delegate[:to]
+        delegate_allow_nil = delegate.fetch(:allow_nil) { config.delegate_default_allow_nil }
+
+        to_access = delegate[:to_hash_access]
+        final_access = delegate[:hash_access]
+        unless to_access || final_access
+          return AttributeValueResolvers::DelegateResolver.get(delegate_to, key_method_name, delegate_allow_nil)
+        end
+
+        to_step = delegate_to_step(delegate_to, to_access)
+        final_step = delegate_final_step(key_method_name, final_access)
+        AttributeValueResolvers::HashAccessDelegateResolver.get(to_step, final_step, delegate_allow_nil)
+      end
+
+      def delegate_to_step(delegate_to, access)
+        return AttributeValueResolvers::Keyword.new(delegate_to) unless access
+
+        mode, allow_missing_key = parse_hash_access(access)
+        AttributeValueResolvers::HashAccessKeyword.new(delegate_to, mode, allow_missing_key)
+      end
+
+      def delegate_final_step(key_method_name, access)
+        return AttributeValueResolvers::Keyword.new(key_method_name) unless access
 
-        allow_nil = delegate.fetch(:allow_nil) { config.delegate_default_allow_nil }
-        AttributeValueResolvers::DelegateResolver.get(delegate_to, key_method_name, allow_nil)
+        mode, allow_missing_key = parse_hash_access(access)
+        AttributeValueResolvers::HashAccessKeyword.new(key_method_name, mode, allow_missing_key)
+      end
+
+      # Resolves the :hash_access option of plain attributes
+      # @return [Array(Symbol, Boolean), nil] mode and allow_missing_key pair,
+      #   or nil when hash access is not enabled for this attribute
+      def hash_access
+        option = init_opts[:hash_access]
+        return unless option
+
+        parse_hash_access(option)
+      end
+
+      # Resolves a :hash_access value (`true`, a Symbol mode or a
+      # `{mode:, allow_missing_key:}` Hash) into a mode and allow_missing_key
+      # pair. `true` and a Hash omitting :mode resolve to
+      # `config.hash_access.default_mode`.
+      def parse_hash_access(option)
+        defaults = config.hash_access
+
+        case option
+        when true then [defaults.default_mode, defaults.default_allow_missing_key]
+        when Symbol then [option, defaults.default_allow_missing_key]
+        else
+          mode = option.fetch(:mode) { defaults.default_mode }
+          allow_missing_key = option.fetch(:allow_missing_key) { defaults.default_allow_missing_key }
+          [mode, allow_missing_key]
+        end
       end
 
       # Prepares preloads for this attribute.

data/lib/serega/attribute_value_resolvers/hash_access.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+class Serega
+  module AttributeValueResolvers
+    #
+    # Builds value resolver for attributes with the :hash_access option
+    #
+    class HashAccessResolver
+      # Allowed hash access modes
+      MODES = %i[symbol string].freeze
+
+      #
+      # Creates resolver that reads a key from Hash records
+      #
+      # @param name [Symbol, String] hash key
+      # @param mode [Symbol] hash access mode (:symbol, :string)
+      # @param allow_missing_key [Boolean] whether a missing key is read via `record[key]` rather than raising
+      #
+      # @return [HashAccessKeyword] resolver instance
+      #
+      def self.get(name, mode, allow_missing_key)
+        HashAccessKeyword.new(name, mode, allow_missing_key)
+      end
+    end
+
+    #
+    # Builds value resolver for attributes with the :delegate option using
+    # hash access on any of its steps
+    #
+    class HashAccessDelegateResolver
+      #
+      # Creates resolver that delegates through the provided step readers
+      #
+      # @param to_step [#call] reader of the intermediate object
+      # @param final_step [#call] reader of the final value
+      # @param delegate_allow_nil [Boolean] whether a nil intermediate object resolves to nil
+      #
+      # @return [HashAccessDelegate, HashAccessDelegateAllowNil] resolver instance
+      #
+      def self.get(to_step, final_step, delegate_allow_nil)
+        delegate_allow_nil ? HashAccessDelegateAllowNil.new(to_step, final_step) : HashAccessDelegate.new(to_step, final_step)
+      end
+    end
+
+    #
+    # Value resolver for attributes with the :hash_access option
+    #
+    class HashAccessKeyword
+      def initialize(name, mode, allow_missing_key)
+        @key = (mode == :symbol) ? name.to_sym : name.to_s
+        @allow_missing_key = allow_missing_key
+      end
+
+      #
+      # Reads the key from the record
+      #
+      # @param object [Object] serialized object or delegation step value
+      # @return [Object] the value found
+      #
+      def call(object)
+        return object[@key] if @allow_missing_key
+
+        object.fetch(@key) do
+          default = object[@key]
+          next default unless default.nil?
+
+          raise KeyError.new("key not found: #{@key.inspect}", key: @key, receiver: object)
+        end
+      end
+    end
+
+    #
+    # Value resolver for attributes with :hash_access and :delegate (without :allow_nil) options
+    #
+    class HashAccessDelegate
+      def initialize(to_step, final_step)
+        @to_step = to_step
+        @final_step = final_step
+      end
+
+      #
+      # Delegates the value reading through the intermediate object
+      #
+      # @param object [Object] serialized object
+      # @return [Object] the value found
+      #
+      def call(object)
+        @final_step.call(@to_step.call(object))
+      end
+    end
+
+    #
+    # Value resolver for attributes with :hash_access and :delegate (with :allow_nil) options
+    #
+    class HashAccessDelegateAllowNil
+      def initialize(to_step, final_step)
+        @to_step = to_step
+        @final_step = final_step
+      end
+
+      #
+      # Delegates the value reading through the intermediate object,
+      # resolving a nil intermediate to nil
+      #
+      # @param object [Object] serialized object
+      # @return [Object, nil] the value found
+      #
+      def call(object)
+        intermediate = @to_step.call(object)
+        return if intermediate.nil?
+
+        @final_step.call(intermediate)
+      end
+    end
+  end
+end

data/lib/serega/config.rb

@@ -25,6 +25,7 @@ class Serega
         preload
         batch
         base_serializer
+        hash_access
       ].freeze,
       serialize_keys: %i[context many].freeze,
       check_attribute_name: true,
@@ -35,7 +36,8 @@ class Serega
       auto_preload_excluded_methods: %i[itself].freeze,
       hide_by_default: false,
       batch_id_option: :id,
-      base_serializer: nil
+      base_serializer: nil,
+      hash_access: {default_mode: :symbol, default_allow_missing_key: false}
     }.freeze
     # :nocov:
 
@@ -205,6 +207,12 @@ class Serega
           end
       end
 
+      # Returns the hash_access config object
+      # @return [Serega::SeregaConfig::HashAccessConfig] hash_access config object
+      def hash_access
+        @hash_access ||= HashAccessConfig.new(opts.fetch(:hash_access))
+      end
+
       # Returns :max_cached_plans_per_serializer_count config option
       # @return [Boolean] Current :max_cached_plans_per_serializer_count config option
       def max_cached_plans_per_serializer_count
@@ -252,6 +260,57 @@ class Serega
       end
     end
 
+    #
+    # Config for the `hash_access:` attribute option
+    #
+    class HashAccessConfig
+      # @return [Hash] hash_access config options
+      attr_reader :opts
+
+      #
+      # Initializes HashAccessConfig object
+      #
+      # @param opts [Hash] hash_access config options
+      #
+      # @return [Serega::SeregaConfig::HashAccessConfig]
+      #
+      def initialize(opts)
+        @opts = opts
+      end
+
+      # @return [Symbol] mode used by `hash_access: true` (default :symbol)
+      def default_mode
+        opts.fetch(:default_mode)
+      end
+
+      # Sets the mode used by `hash_access: true`
+      # @param value [Symbol] one of :symbol, :string
+      # @return [Symbol] new default mode
+      def default_mode=(value)
+        unless AttributeValueResolvers::HashAccessResolver::MODES.include?(value)
+          raise SeregaError, "Invalid hash_access default_mode #{value.inspect}. Allowed modes: :symbol, :string"
+        end
+
+        opts[:default_mode] = value
+      end
+
+      # @return [Boolean] allow_missing_key used when an attribute omits it
+      def default_allow_missing_key
+        opts.fetch(:default_allow_missing_key)
+      end
+
+      # Sets the allow_missing_key used when an attribute omits it
+      # @param value [Boolean]
+      # @return [Boolean] new default allow_missing_key
+      def default_allow_missing_key=(value)
+        unless value == true || value == false
+          raise SeregaError, "Invalid hash_access default_allow_missing_key #{value.inspect}. Must be a Boolean"
+        end
+
+        opts[:default_allow_missing_key] = value
+      end
+    end
+
     include SeregaConfigInstanceMethods
     extend Serega::SeregaHelpers::SerializerClassHelper
   end

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

@@ -132,11 +132,15 @@ class Serega
             superclass.modified?
           end
 
+          # Marks the class as modified, then includes the module
+          # @return [void]
           def include(*modules)
             @modified = true
             super
           end
 
+          # Marks the class as modified, then prepends the module
+          # @return [void]
           def prepend(*modules)
             @modified = true
             super

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

@@ -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,12 +50,51 @@ 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)

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/check_attribute_params.rb

@@ -62,6 +62,7 @@ class Serega
           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)

data/lib/serega.rb

@@ -29,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"
@@ -46,6 +47,7 @@ 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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.39.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
@@ -83,6 +84,7 @@ files:
 - 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