serega 0.42.0 → 0.50.0

data/lib/serega/attribute_normalizer.rb

@@ -4,398 +4,217 @@ class Serega
   #
   # Prepares provided attribute options
   #
-  # @private
-  class SeregaAttributeNormalizer
-    #
-    # AttributeNormalizer instance methods
-    #
-    # @private
-    module AttributeNormalizerInstanceMethods
-      # Attribute initial params
-      # @return [Hash] Attribute initial params
-      attr_reader :init_name, :init_opts, :init_block
-
-      #
-      # Instantiates attribute options normalizer
-      #
-      # @param initials [Hash] new attribute options
-      #
-      # @return [SeregaAttributeNormalizer] Instantiated attribute options normalizer
-      #
-      def initialize(initials)
-        @init_name = initials[:name]
-        @init_opts = initials[:opts]
-        @init_block = initials[:block]
-      end
-
-      #
-      # Symbolized initial attribute name
-      #
-      # @return [Symbol] Attribute normalized name
-      #
-      def name
-        @name ||= prepare_name
-      end
-
-      #
-      # Symbolized initial attribute method name
-      #
-      # @return [Symbol] Attribute normalized method name
-      #
-      def method_name
-        @method_name ||= prepare_method_name
-      end
-
-      #
-      # Combines all options to return single block that will be used to find
-      # attribute value during serialization
-      #
-      # @return [#call] Attribute normalized callable value block
-      #
-      def value_block
-        @value_block ||= prepare_value_block
-      end
-
-      #
-      # Detects value block parameters signature
-      #
-      # @return [String] value block parameters signature
-      #
-      def value_block_signature
-        @value_block_signature ||= SeregaUtils::MethodSignature.call(value_block, pos_limit: 2, keyword_args: [:ctx])
-      end
-
-      #
-      # Shows if attribute is specified to be hidden
-      #
-      # @return [Boolean, nil] if attribute must be hidden by default
-      #
-      def hide
-        return @hide if instance_variable_defined?(:@hide)
-
-        @hide = prepare_hide
-      end
-
-      #
-      # Shows if attribute is specified to be a one-to-many relationship
-      #
-      # @return [Boolean, nil] if attribute is specified to be a one-to-many relationship
-      #
-      def many
-        return @many if instance_variable_defined?(:@many)
+  class SeregaAttributeNormalizer # :nodoc:
+    # Attribute initial params
+    attr_reader :init_name, :init_opts, :init_block
+
+    # Instantiates attribute options normalizer
+    def initialize(serializer_class, initials)
+      @serializer_class = serializer_class
+      @init_name = initials[:name]
+      @init_opts = initials[:opts]
+      @init_block = initials[:block]
+      @method_name = nil
+    end
 
-        @many = prepare_many
-      end
+    # Symbolized initial attribute name
+    def name
+      @name ||= prepare_name
+    end
 
-      #
-      # Shows specified attribute serializer
-      # @return [Serega, String, #callable, nil] specified serializer
-      #
-      def serializer
-        return @serializer if instance_variable_defined?(:@serializer)
+    # Symbolized initial attribute method name
+    def method_name
+      @method_name ||= prepare_method_name
+    end
 
-        @serializer = prepare_serializer
-      end
+    # Combines all options to return single block that will be used to find
+    # attribute value during serialization
+    def value_block
+      @value_block ||= prepare_value_block
+    end
 
-      #
-      # Shows the default attribute value. It is a value that replaces found nils.
-      #
-      # When custom :default is not specified, we set empty array as default when `many: true` specified
-      #
-      # @return [Object] Attribute default value
-      #
-      def default
-        return @default if instance_variable_defined?(:@default)
-
-        @default = prepare_default
-      end
+    # Detects value block parameters signature
+    def value_block_signature
+      @value_block_signature ||= SeregaUtils::MethodSignature.call(value_block, pos_limit: 2, keyword_args: [:ctx])
+    end
 
-      #
-      # Preloads declared for this attribute, passed through as provided.
-      #
-      # @return [Object, nil] declared preloads, or nil when the attribute has none
-      #
-      def preloads
-        return @preloads if instance_variable_defined?(:@preloads)
+    # Shows if attribute is specified to be hidden
+    def hide
+      return @hide if instance_variable_defined?(:@hide)
 
-        @preloads = prepare_preloads
-      end
+      @hide = prepare_hide
+    end
 
-      # Shows specified batch loaders names
-      # @return [Array<Symbol>] specified serializer
-      #
-      def batch_loaders
-        @batch_loaders ||= prepare_batch_loaders
-      end
+    # Shows if attribute is specified to be a one-to-many relationship
+    def many
+      return @many if instance_variable_defined?(:@many)
 
-      private
+      @many = prepare_many
+    end
 
-      def prepare_name
-        init_name.to_sym
-      end
+    # Shows specified attribute serializer
+    def serializer
+      return @serializer if instance_variable_defined?(:@serializer)
 
-      def prepare_value_block
-        init_opts[:value] \
-          || prepare_const_block \
-          || prepare_delegate_block \
-          || prepare_batch_loader_block \
-          || prepare_keyword_block
-      end
+      @serializer = prepare_serializer
+    end
 
-      def prepare_hide
-        # Return provided directly value
-        hide = init_opts[:hide]
-        return hide if (hide == true) || (hide == false)
+    # Shows the default attribute value. It is a value that replaces found nils.
+    #
+    # When custom :default is not specified, we set empty array as default when `many: true` specified
+    def default
+      return @default if instance_variable_defined?(:@default)
 
-        hide_setting = config.hide_by_default
-        return true if hide_setting == true
-        return true if hide_setting == :auto && preload_or_batch?
+      @default = prepare_default
+    end
 
-        # Return nil for undefined value which means "not hide" but allows
-        # to change this value by plugins
-        nil
-      end
+    # Preloads declared for this attribute, passed through as provided.
+    def preloads
+      return @preloads if instance_variable_defined?(:@preloads)
 
-      # The `hide_by_default = :auto` criterion: hide attributes that fetch extra
-      # data on demand — those declared with `:preload` or an explicit `:batch`.
-      #
-      # This is intentionally narrower than a "goes through the batch mechanism"
-      # check (`SeregaPlanPoint#batch?`): a plain relation (`serializer:` without
-      # `:preload`) is batch-processed too, but it only serializes an already-loaded
-      # nested object, so it stays visible by default.
-      def preload_or_batch?
-        !!(preloads || init_opts.key?(:batch))
-      end
+      @preloads = prepare_preloads
+    end
 
-      def config
-        self.class.serializer_class.config
-      end
+    # Shows specified batch loaders names
+    def batch_loaders
+      @batch_loaders ||= prepare_batch_loaders
+    end
 
-      def prepare_many
-        init_opts[:many]
-      end
+    # Batch loader given directly as the :batch option. It is named after the
+    # attribute and belongs to the attribute only.
+    def inline_batch_loader
+      batch = batch_option
+      return unless batch&.inline?
 
-      def prepare_serializer
-        block = init_block
-        return init_opts[:serializer] unless block
+      SeregaBatchLoader.new(name: name, block: batch.use)
+    end
 
-        prepare_block_serializer(block)
-      end
+    # Callable :if, :unless, :if_value and :unless_value conditions. A Symbol
+    # condition calls the method of this name.
+    def conditions
+      conditions = init_opts.slice(:if, :unless, :if_value, :unless_value)
+      return if conditions.empty?
 
-      # 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.
-      # 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 prepare_block_serializer(block)
-        if block.instance_variable_defined?(:@serega_building_nested_serializer)
-          raise SeregaError,
-            "Can not define a nested serializer for attribute :#{name} —" \
-            " its base serializer #{block_base_serializer.inspect} (transitively)" \
-            " contains this same block attribute (cyclic definition)"
-        end
-
-        block.instance_variable_set(:@serega_building_nested_serializer, true)
-        begin
-          build_block_serializer(block)
-        ensure
-          block.remove_instance_variable(:@serega_building_nested_serializer)
-        end
+      conditions.transform_values do |condition|
+        condition.is_a?(Symbol) ? AttributeValueResolvers::Keyword.new(condition) : condition
       end
+    end
 
-      def build_block_serializer(block)
-        label = "#{self.class.serializer_class.inspect}.<#{name}>"
+    # Formatter of the :format option. A Symbol option is the name of a
+    # formatter defined with `Serega.formatter`.
+    def formatter
+      format = init_opts[:format]
+      return unless format
 
-        serializer = Class.new(block_base_serializer) do
-          define_singleton_method(:inspect) { label }
-          define_singleton_method(:to_s) { label }
-          instance_exec(&block)
-        end
+      format.is_a?(Symbol) ? @serializer_class.formatters.fetch(format) : SeregaFormatter.new(format)
+    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?
+    private
 
-        serializer
-      end
+    def prepare_name
+      init_name.to_sym
+    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 block_base_serializer
-        base_serializer = init_opts[:base_serializer] || 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
+    def prepare_value_block
+      init_opts[:value] \
+        || prepare_const_block \
+        || prepare_delegate_block \
+        || prepare_batch_loader_block \
+        || prepare_keyword_block
+    end
 
-      def prepare_method_name
-        (init_opts[:method] || init_name).to_sym
-      end
+    def prepare_hide
+      # Return provided directly value
+      hide = init_opts[:hide]
+      return hide if (hide == true) || (hide == false)
 
-      def prepare_const_block
-        return unless init_opts.key?(:const)
+      hide_setting = config.hide_by_default
+      return true if hide_setting == true
+      return true if hide_setting == :auto && preload_or_batch?
 
-        AttributeValueResolvers::ConstResolver.get(init_opts[:const])
-      end
-
-      def prepare_keyword_block
-        mode, allow_nil = hash_access
-        return AttributeValueResolvers::KeywordResolver.get(method_name) unless mode
+      # Return nil for undefined value which means "not hide" but allows
+      # to change this value by plugins
+      nil
+    end
 
-        AttributeValueResolvers::HashAccessResolver.get(method_name, mode, allow_nil)
-      end
+    # The `hide_by_default = :auto` criterion: hide attributes that fetch extra
+    # data on demand — those declared with `:preload` or an explicit `:batch`.
+    #
+    # This is intentionally narrower than a "goes through the batch mechanism"
+    # check (`SeregaPlanPoint#batch?`): a plain relation (`serializer:` without
+    # `:preload`) is batch-processed too, but it only serializes an already-loaded
+    # nested object, so it stays visible by default.
+    def preload_or_batch?
+      !!(preloads || init_opts.key?(:batch))
+    end
 
-      def prepare_batch_loader_block
-        batch_opt = init_opts[:batch]
-        return unless batch_opt
+    def config
+      @serializer_class.config
+    end
 
-        AttributeValueResolvers::BatchResolver.get(self.class.serializer_class, name, batch_opt)
-      end
+    def prepare_many
+      init_opts[:many]
+    end
 
-      # Batch loader names whose loaded data this attribute's value needs. Only
-      # explicit `:batch` attributes have any — everything else resolves its value
-      # from the record itself, so the list is empty (no loader to run).
-      def prepare_batch_loaders
-        batch_opt = init_opts[:batch]
-        return explicit_batch_loaders(batch_opt) if batch_opt
+    def prepare_serializer
+      block = init_block
+      return init_opts[:serializer] unless block
 
-        FROZEN_EMPTY_ARRAY
-      end
+      AttributeNormalizers::Block.call(@serializer_class, name, block, init_opts[:base_serializer])
+    end
 
-      def explicit_batch_loaders(batch_opt)
-        if batch_opt == true || batch_opt.respond_to?(:call)
-          [name]
-        elsif batch_opt.is_a?(Symbol)
-          [batch_opt]
-        elsif batch_opt.is_a?(String)
-          [batch_opt.to_sym]
-        else
-          use_opt = batch_opt.fetch(:use)
-          use_opt.respond_to?(:call) ? [name] : Array(use_opt).map(&:to_sym)
-        end
-      end
+    def prepare_method_name
+      (init_opts[:method] || init_name).to_sym
+    end
 
-      def prepare_default
-        init_opts.fetch(:default) { many ? FROZEN_EMPTY_ARRAY : nil }
-      end
+    def prepare_const_block
+      return unless init_opts.key?(:const)
 
-      # `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
+      AttributeValueResolvers::Const.new(init_opts[:const])
+    end
 
-      def delegate_to_step(delegate_to, access)
-        return AttributeValueResolvers::Keyword.new(delegate_to) unless access
+    def prepare_keyword_block
+      AttributeNormalizers::HashAccess.call(init_opts[:hash_access], method_name, config.hash_access)
+    end
 
-        mode, allow_missing_key = parse_hash_access(access)
-        AttributeValueResolvers::HashAccessKeyword.new(delegate_to, mode, allow_missing_key)
-      end
+    # Reads the value from the loaded batch of the only batch loader
+    def prepare_batch_loader_block
+      batch = batch_option
+      return unless batch
 
-      def delegate_final_step(key_method_name, access)
-        return AttributeValueResolvers::Keyword.new(key_method_name) unless access
+      AttributeValueResolvers::Batch.new(batch_loaders.first, batch.id || config.batch_id_option)
+    end
 
-        mode, allow_missing_key = parse_hash_access(access)
-        AttributeValueResolvers::HashAccessKeyword.new(key_method_name, mode, allow_missing_key)
-      end
+    # Batch loader names whose loaded data this attribute's value needs. An
+    # attribute without the :batch option has none.
+    def prepare_batch_loaders
+      batch = batch_option
+      return FROZEN_EMPTY_ARRAY unless batch
 
-      # 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
+      batch.loader_names
+    end
 
-        parse_hash_access(option)
-      end
+    # The parsed :batch option, `nil` without it
+    def batch_option
+      return @batch_option if instance_variable_defined?(:@batch_option)
 
-      # 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
+      batch = init_opts[:batch]
+      @batch_option = batch && AttributeNormalizers::Batch.new(batch, name)
+    end
 
-      # Prepares preloads for this attribute.
-      #
-      # 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.
-      #
-      # @return [Object, nil] preloads as provided, or nil when the attribute has none
-      def prepare_preloads
-        # Explicit preload option (false or nil disables preloading)
-        return init_opts[:preload] || nil if init_opts.key?(:preload)
-
-        # Auto-preload the delegated association
-        if config.auto_preload.fetch(:has_delegate_option) && init_opts[:delegate]
-          return auto_preload_value(init_opts[:delegate][:to])
-        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) && (init_opts[:serializer] || init_block) && !init_opts.key?(:batch)
-          return auto_preload_value(method_name)
-        end
-
-        nil
-      end
+    def prepare_default
+      init_opts.fetch(:default) { many ? FROZEN_EMPTY_ARRAY : nil }
+    end
 
-      # Skips auto-preloading of methods that return the serialized object
-      # itself (:itself by default) — they are not associations,
-      # so preloading them would fail or make no sense.
-      def auto_preload_value(preload_method)
-        return nil if config.auto_preload_excluded_methods.include?(preload_method.to_sym)
+    def prepare_delegate_block
+      delegate = init_opts[:delegate]
+      return unless delegate
 
-        preload_method
-      end
+      AttributeNormalizers::Delegate.call(delegate, method_name, config)
     end
 
-    extend Serega::SeregaHelpers::SerializerClassHelper
-    include AttributeNormalizerInstanceMethods
+    def prepare_preloads
+      AttributeNormalizers::Preloads.call(init_opts, init_block, method_name, config)
+    end
   end
 end

data/lib/serega/attribute_normalizers/batch.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Parsers of attribute options, used by SeregaAttributeNormalizer
+  #
+  module AttributeNormalizers # :nodoc:
+    #
+    # The attribute :batch option, parsed into the loaders and the id method.
+    # `true`, a loader name, a callable or a Hash with `:use` and `:id`; `true`
+    # and a Hash without `:use` use the loader named after the attribute.
+    #
+    class Batch # :nodoc:
+      # Name of the attribute with the option
+      attr_reader :attribute_name
+
+      # Loader name, Array of loader names, or a callable inline loader
+      attr_reader :use
+
+      # Method that gives the id of an object, `nil` when not given
+      attr_reader :id
+
+      # Parses the :batch option of the attribute
+      def initialize(batch, attribute_name)
+        batch = {use: batch} unless batch.is_a?(Hash)
+        use = batch.fetch(:use, true)
+
+        @attribute_name = attribute_name
+        @use = (use == true) ? attribute_name : use
+        @id = batch[:id]
+      end
+
+      # Whether the option is the loader itself, a callable
+      def inline?
+        use.respond_to?(:call)
+      end
+
+      # Names of the batch loaders the attribute value needs. An inline loader
+      # is named after the attribute.
+      def loader_names
+        inline? ? [attribute_name.to_sym] : Array(use).map(&:to_sym)
+      end
+    end
+  end
+end