serega 0.42.0 → 0.50.0

data/lib/serega/attribute_normalizers/block.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+class Serega
+  module AttributeNormalizers # :nodoc:
+    #
+    # Builds an anonymous nested serializer from the attribute block.
+    #
+    # The serializer is a regular subclass of an explicitly chosen base —
+    # the :base_serializer attribute option or `config.base_serializer` —
+    # so it inherits everything the base has: plugins, config, attributes,
+    # batch loaders, the preload handler. Nested values can be any objects,
+    # which is why the base is chosen explicitly instead of inheriting from
+    # the current serializer. Its `inspect` is overridden to
+    # `CurrentSerializer.<attribute_name>` so error messages and debugging
+    # output point back to the defining attribute.
+    #
+    class Block # :nodoc:
+      class << self
+        # Builds the nested serializer of the attribute block. `base_serializer`
+        # is the :base_serializer attribute option.
+        #
+        # Guards against cyclic definitions before building: inheriting the base
+        # serializer copies its attributes, and copying a block attribute builds
+        # its nested serializer — meeting the same block again while it is being
+        # built means the base serializer (transitively) contains the block
+        # attribute being built, so inheriting from it would recurse forever.
+        # The "in progress" mark is kept on the block itself — its identity is
+        # what defines the cycle (the same Proc object is shared by all copies
+        # of the attribute).
+        def call(serializer_class, attribute_name, block, base_serializer)
+          base_serializer = chosen_base_serializer(serializer_class, base_serializer)
+
+          if block.instance_variable_defined?(:@serega_building_nested_serializer)
+            raise SeregaError,
+              "Can not define a nested serializer for attribute :#{attribute_name} —" \
+              " its base serializer #{base_serializer.inspect} (transitively)" \
+              " contains this same block attribute (cyclic definition)"
+          end
+
+          block.instance_variable_set(:@serega_building_nested_serializer, true)
+          begin
+            build(serializer_class, attribute_name, block, base_serializer)
+          ensure
+            block.remove_instance_variable(:@serega_building_nested_serializer)
+          end
+        end
+
+        private
+
+        def build(serializer_class, attribute_name, block, base_serializer)
+          label = "#{serializer_class.inspect}.<#{attribute_name}>"
+
+          serializer = Class.new(base_serializer) do
+            define_singleton_method(:inspect) { label }
+            define_singleton_method(:to_s) { label }
+            instance_exec(&block)
+          end
+
+          # An empty nested serializer means the block was intended as an
+          # old-style value block — raise the explaining error.
+          raise SeregaError, SeregaValidations::Attribute::CheckBlock::ERROR_MESSAGE if serializer.attributes.empty?
+
+          serializer
+        end
+
+        # Base class for the nested serializer. Must be chosen explicitly —
+        # usually a settings-only serializer holding plugins and configuration
+        # (e.g. `config.base_serializer = self` in an application base class).
+        def chosen_base_serializer(serializer_class, base_serializer)
+          base_serializer ||= serializer_class.config.base_serializer
+          return base_serializer if base_serializer
+
+          raise SeregaError,
+            "Attribute block requires a base serializer for the nested serializer." \
+            " Provide the `base_serializer: <SerializerClass>` attribute option" \
+            " or set `config.base_serializer = <SerializerClass>`"
+        end
+      end
+    end
+  end
+end

data/lib/serega/attribute_normalizers/delegate.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class Serega
+  module AttributeNormalizers # :nodoc:
+    #
+    # Builds the value resolver of the attribute :delegate option
+    #
+    class Delegate # :nodoc:
+      class << self
+        # Resolver that reads `delegate[:to]` of the object, then
+        # `delegate[:method]` (the attribute method by default) of the result.
+        # `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 call(delegate, method_name, config)
+          key_method_name = delegate[:method] || method_name
+          delegate_to = delegate[:to]
+          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, allow_nil)
+          end
+
+          to_step = HashAccess.call(to_access, delegate_to, config.hash_access)
+          final_step = HashAccess.call(final_access, key_method_name, config.hash_access)
+          AttributeValueResolvers::HashAccessDelegateResolver.get(to_step, final_step, allow_nil)
+        end
+      end
+    end
+  end
+end

data/lib/serega/attribute_normalizers/hash_access.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class Serega
+  module AttributeNormalizers # :nodoc:
+    #
+    # Builds the value resolver of one read: a method call, or a Hash read when
+    # a :hash_access option is given
+    #
+    class HashAccess # :nodoc:
+      class << self
+        # Resolver that reads `key` of the object. `option` is a :hash_access
+        # value: `true`, a Symbol mode or a `{mode:, allow_missing_key:}` Hash;
+        # `true` and a Hash without a key take `config.hash_access` defaults.
+        # Without the option the resolver calls the method `key`.
+        def call(option, key, defaults)
+          return AttributeValueResolvers::Keyword.new(key) unless option
+
+          mode, allow_missing_key = parse(option, defaults)
+          AttributeValueResolvers::HashAccessKeyword.new(key, mode, allow_missing_key)
+        end
+
+        private
+
+        def parse(option, defaults)
+          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
+      end
+    end
+  end
+end

data/lib/serega/attribute_normalizers/preloads.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class Serega
+  module AttributeNormalizers # :nodoc:
+    #
+    # Finds the preloads of an attribute
+    #
+    class Preloads # :nodoc:
+      class << self
+        # Preloads of the attribute with options `opts` and block `block`.
+        #
+        # The value is passed through as provided (Symbol, Array, Hash, or any
+        # custom value an ORM understands) — it is the data handed to the
+        # serializer's `preload_with` handler.
+        def call(opts, block, method_name, config)
+          # Explicit preload option (false or nil disables preloading)
+          return opts[:preload] || nil if opts.key?(:preload)
+
+          # Auto-preload the delegated association
+          if config.auto_preload.fetch(:has_delegate_option) && opts[:delegate]
+            return auto_preload_value(opts[:delegate][:to], config)
+          end
+
+          # Auto-preload the nested serializer's association
+          # (a block defines a nested serializer, same as the :serializer option)
+          if config.auto_preload.fetch(:has_serializer_option) && (opts[:serializer] || block) && !opts.key?(:batch)
+            return auto_preload_value(method_name, config)
+          end
+
+          nil
+        end
+
+        private
+
+        # Skips auto-preloading of methods that return the object
+        # itself (:itself by default) — they are not associations,
+        # so preloading them would fail or make no sense.
+        def auto_preload_value(preload_method, config)
+          return nil if config.auto_preload_excluded_methods.include?(preload_method.to_sym)
+
+          preload_method
+        end
+      end
+    end
+  end
+end

data/lib/serega/attribute_value_resolvers/batch.rb

@@ -4,67 +4,18 @@ class Serega
   #
   # Attribute value resolvers
   #
-  # @private
-  module AttributeValueResolvers
+  module AttributeValueResolvers # :nodoc:
     #
-    # Builds value resolver class for attributes with :batch option
+    # Value resolver of attributes with the :batch option and without the
+    # :value option. Reads the value of the object from the loaded batch.
     #
-    # @private
-    class BatchResolver
-      #
-      # Generates callable block to find attribute value when attribute with :batch
-      # option has no block or manual :value option.
-      #
-      # In other cases we should never get here as attribute value/block option must be manually defined.
-      #
-      # It handles this cases:
-      # - `attribute :foo, batch: true`
-      # - `attribute :foo, batch: FooLoader`
-      # - `attribute :foo, batch: :foo_loader`
-      # - `attribute :foo, batch: { id: :foo_id }`
-      # - `attribute :foo, batch: { use: FooLoader, id: foo_id }`
-      # - `attribute :foo, batch: { use: :foo_loader, id: foo_id }`
-      #
-      def self.get(serializer_class, attribute_name, batch_opt)
-        default_method = serializer_class.config.batch_id_option
-
-        if batch_opt == true                        # ex: `batch: true`
-          batch_name = attribute_name
-          batch_id_method = default_method
-        elsif batch_opt.respond_to?(:call)          # ex: `batch: FooLoader`
-          serializer_class.batch(attribute_name, batch_opt)
-          batch_name = attribute_name
-          batch_id_method = default_method
-        elsif batch_opt.is_a?(Symbol) || batch_opt.is_a?(String) # ex: `batch: :foo_loader`
-          batch_name = batch_opt.to_sym
-          batch_id_method = default_method
-        else
-          use = batch_opt[:use]
-          batch_id_method = batch_opt[:id] || default_method
-
-          if use.respond_to?(:call)                 # ex: `batch: { use: FooLoader }`
-            batch_name = attribute_name
-            serializer_class.batch(batch_name, use)
-          else                                      # ex: `batch: { use: :foo }` || batch: { id: :some_id }
-            batch_name = use || attribute_name
-          end
-        end
-
-        Batch.new(batch_name, batch_id_method)
-      end
-    end
-
-    #
-    # Builds value resolver class for attributes with :batch option
-    #
-    # @private
-    class Batch
+    class Batch # :nodoc:
       def initialize(loader_name, id_method)
         @loader_name = loader_name
         @id_method = id_method
       end
 
-      # Finds object attribute value from hash of batch_loaded values
+      # Finds the object attribute value in the loaded batches
       def call(obj, batches:)
         batches.fetch(@loader_name)[obj.public_send(@id_method)]
       end

data/lib/serega/attribute_value_resolvers/const.rb

@@ -4,38 +4,16 @@ class Serega
   #
   # Attribute value resolvers
   #
-  # @private
-  module AttributeValueResolvers
-    #
-    # Builds value resolver class for attributes with :const option
-    #
-    # @private
-    class ConstResolver
-      #
-      # Creates resolver that returns constant value
-      #
-      # @param const_value [Object] constant value to return
-      # @return [Const] resolver instance
-      #
-      def self.get(const_value)
-        Const.new(const_value)
-      end
-    end
-
+  module AttributeValueResolvers # :nodoc:
     #
     # Value resolver class for attributes with :const option
     #
-    # @private
-    class Const
+    class Const # :nodoc:
       def initialize(const_value)
         @const_value = const_value
       end
 
-      #
       # Returns the constant value
-      #
-      # @return [Object] the constant value
-      #
       def call
         @const_value
       end

data/lib/serega/attribute_value_resolvers/delegate.rb

@@ -4,21 +4,12 @@ class Serega
   #
   # Attribute value resolvers
   #
-  # @private
-  module AttributeValueResolvers
+  module AttributeValueResolvers # :nodoc:
     #
     # Builds value resolver class for attributes with :delegate option
     #
-    # @private
-    class DelegateResolver
-      #
+    class DelegateResolver # :nodoc:
       # Creates resolver that delegates method call to another object
-      #
-      # @param delegate_to [Symbol] method to call on object to get delegated object
-      # @param method_name [Symbol] method to call on delegated object
-      # @param allow_nil [Boolean] whether to use safe navigation when delegated object is nil
-      # @return [Delegate, DelegateAllowNil] resolver instance
-      #
       def self.get(delegate_to, method_name, allow_nil)
         allow_nil ? DelegateAllowNil.new(delegate_to, method_name) : Delegate.new(delegate_to, method_name)
       end
@@ -27,47 +18,45 @@ class Serega
     #
     # Value resolver class for attributes with :delegate (with :allow_nil) option
     #
-    # @private
-    class DelegateAllowNil
+    class DelegateAllowNil # :nodoc:
       def initialize(delegate_to, method_name)
         @delegate_to = delegate_to
         @method_name = method_name
       end
 
-      #
       # Delegates method call to another object with safe navigation
-      #
-      # @param object [Object] the object to delegate from
-      # @return [Object, nil] result of delegated method call or nil if delegated object is nil
-      #
       def call(object)
-        object.public_send(delegate_to)&.public_send(method_name)
+        object.public_send(@delegate_to)&.public_send(@method_name)
       end
 
-      private
+      # Ruby code that delegates the method call
+      def code(source_variable)
+        return unless SeregaResultCode::PLAIN_METHOD_NAME.match?(@delegate_to) && SeregaResultCode::PLAIN_METHOD_NAME.match?(@method_name)
 
-      attr_reader :delegate_to, :method_name
+        "#{source_variable}.#{@delegate_to}&.#{@method_name}"
+      end
     end
 
     #
     # Value resolver class for attributes with :delegate (without :allow_nil) option
     #
-    # @private
-    class Delegate
+    class Delegate # :nodoc:
       def initialize(delegate_to, method_name)
         @delegate_to = delegate_to
         @method_name = method_name
       end
 
-      #
       # Delegates method call to another object
-      #
-      # @param object [Object] the object to delegate from
-      # @return [Object] result of delegated method call
-      #
       def call(object)
         object.public_send(@delegate_to).public_send(@method_name)
       end
+
+      # Ruby code that delegates the method call
+      def code(source_variable)
+        return unless SeregaResultCode::PLAIN_METHOD_NAME.match?(@delegate_to) && SeregaResultCode::PLAIN_METHOD_NAME.match?(@method_name)
+
+        "#{source_variable}.#{@delegate_to}.#{@method_name}"
+      end
     end
   end
 end

data/lib/serega/attribute_value_resolvers/hash_access.rb

@@ -1,45 +1,21 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module AttributeValueResolvers
+  module AttributeValueResolvers # :nodoc:
     #
-    # Builds value resolver for attributes with the :hash_access option
+    # Settings of the :hash_access option
     #
-    # @private
-    class HashAccessResolver
+    class HashAccessResolver # :nodoc:
       # 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
     #
-    # @private
-    class HashAccessDelegateResolver
-      #
+    class HashAccessDelegateResolver # :nodoc:
       # 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
@@ -48,75 +24,81 @@ class Serega
     #
     # Value resolver for attributes with the :hash_access option
     #
-    # @private
-    class HashAccessKeyword
+    class HashAccessKeyword # :nodoc:
       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)
+          default.nil? ? object.fetch(@key) : default
         end
       end
+
+      # Ruby code that reads the key, the same way as #call
+      def code(source_variable)
+        key = @key.is_a?(String) ? "#{@key.inspect}.freeze" : @key.inspect
+        return "#{source_variable}[#{key}]" if @allow_missing_key
+
+        "#{source_variable}.fetch(#{key}) { (found = #{source_variable}[#{key}]).nil? ? #{source_variable}.fetch(#{key}) : found }"
+      end
     end
 
     #
     # Value resolver for attributes with :hash_access and :delegate (without :allow_nil) options
     #
-    # @private
-    class HashAccessDelegate
+    class HashAccessDelegate # :nodoc:
       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
+
+      # Ruby code that delegates the value reading, the same way as #call
+      def code(source_variable)
+        to_code = @to_step.code(source_variable)
+        final_code = @final_step.code("intermediate")
+        return unless to_code && final_code
+
+        "(intermediate = #{to_code}; #{final_code})"
+      end
     end
 
     #
     # Value resolver for attributes with :hash_access and :delegate (with :allow_nil) options
     #
-    # @private
-    class HashAccessDelegateAllowNil
+    class HashAccessDelegateAllowNil # :nodoc:
       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
+
+      # Ruby code that delegates the value reading, the same way as #call
+      def code(source_variable)
+        to_code = @to_step.code(source_variable)
+        final_code = @final_step.code("intermediate")
+        return unless to_code && final_code
+
+        "((intermediate = #{to_code}).nil? ? nil : #{final_code})"
+      end
     end
   end
 end

data/lib/serega/attribute_value_resolvers/keyword.rb

@@ -4,42 +4,27 @@ class Serega
   #
   # Attribute value resolvers
   #
-  # @private
-  module AttributeValueResolvers
-    #
-    # Builds value resolver class for attributes with :keyword option
-    #
-    # @private
-    class KeywordResolver
-      #
-      # Creates resolver that calls method on object
-      #
-      # @param keyword [Symbol] method name to call on object
-      # @return [Keyword] resolver instance
-      #
-      def self.get(keyword)
-        Keyword.new(keyword)
-      end
-    end
-
+  module AttributeValueResolvers # :nodoc:
     #
     # Value resolver class for attributes with :keyword option
     #
-    # @private
-    class Keyword
+    class Keyword # :nodoc:
       def initialize(keyword)
         @keyword = keyword
       end
 
-      #
+      # Name of the method the value comes from
+      attr_reader :keyword
+
       # Calls the keyword method on the object
-      #
-      # @param object [Object] the object to call method on
-      # @return [Object] result of method call
-      #
       def call(object)
         object.public_send(@keyword)
       end
+
+      # Ruby code that calls the keyword method
+      def code(source_variable)
+        "#{source_variable}.#{@keyword}" if SeregaResultCode::PLAIN_METHOD_NAME.match?(@keyword)
+      end
     end
   end
 end

data/lib/serega/attribute_values.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # One generated method per attribute that is read with plain Ruby code,
+  # for example `def read_full_name(source) = source.full_name`. Each method is
+  # defined with the file and line of its attribute, thus a backtrace of an
+  # error points to the attribute.
+  #
+  # `CONSTANTS` and `DEFAULTS` hold the `:const` and `:default` values of the
+  # attributes, `FORMATTERS` the formatter callables and `FORMATTER_ARGS` the
+  # arguments of method formatters, by attribute name.
+  #
+  # Each method name is `read_` and the attribute name with `_` in place of
+  # other characters than letters, digits and `_`, for example
+  # `read_first_name` for `first-name`. A name of another attribute gets a
+  # number: `read_first_name_2`. Thus attribute names do not clash with
+  # methods of Object, and generated code calls the methods directly.
+  #
+  class SeregaAttributeValues # :nodoc:
+    # `:const` values by attribute name
+    CONSTANTS = {}
+
+    # `:default` values by attribute name
+    DEFAULTS = {}
+
+    # Formatter callables by attribute name
+    FORMATTERS = {}
+
+    # Arguments of method formatters by attribute name
+    FORMATTER_ARGS = {}
+
+    # Method names by attribute name
+    METHOD_NAMES = {}
+
+    # Gives each subclass its own values
+    def self.inherited(subclass)
+      super
+      subclass.const_set(:CONSTANTS, {})
+      subclass.const_set(:DEFAULTS, {})
+      subclass.const_set(:FORMATTERS, {})
+      subclass.const_set(:FORMATTER_ARGS, {})
+      subclass.const_set(:METHOD_NAMES, {})
+    end
+  end
+end