serega 0.38.0 → 0.40.0

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

@@ -24,6 +24,8 @@ class Serega
         default
         preload
         batch
+        base_serializer
+        hash_access
       ].freeze,
       serialize_keys: %i[context many].freeze,
       check_attribute_name: true,
@@ -31,8 +33,11 @@ class Serega
       delegate_default_allow_nil: false,
       max_cached_plans_per_serializer_count: 0,
       auto_preload: {has_delegate_option: false, has_serializer_option: false},
+      auto_preload_excluded_methods: %i[itself].freeze,
       hide_by_default: false,
-      batch_id_option: :id
+      batch_id_option: :id,
+      base_serializer: nil,
+      hash_access: {default_mode: :symbol, default_allow_missing_key: false}
     }.freeze
     # :nocov:
 
@@ -114,6 +119,50 @@ class Serega
         opts[:delegate_default_allow_nil] = value
       end
 
+      # Returns :auto_preload_excluded_methods config option — methods that are
+      # never auto-preloaded, as they return the serialized object itself and
+      # not an association
+      # @return [Array<Symbol>] Current :auto_preload_excluded_methods config option
+      def auto_preload_excluded_methods
+        opts.fetch(:auto_preload_excluded_methods)
+      end
+
+      # Sets :auto_preload_excluded_methods config option — methods that are
+      # never auto-preloaded. Applies to the `:method` option of attributes
+      # with a serializer and to the `delegate: {to: ...}` option.
+      #
+      # @param value [Array<Symbol>] Method names to skip in auto-preload
+      #
+      # @return [Array<Symbol>] New :auto_preload_excluded_methods config option
+      def auto_preload_excluded_methods=(value)
+        unless value.is_a?(Array) && value.all?(Symbol)
+          raise SeregaError, "Must be an Array of Symbols, #{value.inspect} provided"
+        end
+
+        opts[:auto_preload_excluded_methods] = value
+      end
+
+      # Returns :base_serializer config option — the parent class for nested
+      # serializers defined with attribute blocks
+      # @return [Class, nil] Current :base_serializer config option
+      def base_serializer
+        opts.fetch(:base_serializer)
+      end
+
+      # Sets :base_serializer config option — the 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.
+      #
+      # @param value [Class] Serega or its subclass
+      #
+      # @return [Class] New :base_serializer config option
+      def base_serializer=(value)
+        raise SeregaError, "Must be a Serega subclass, #{value.inspect} provided" if !value.is_a?(Class) || !(value <= Serega)
+
+        opts[:base_serializer] = value
+      end
+
       # Returns :hide_by_default config option
       # @return [Boolean, Symbol] Current :hide_by_default config option
       def hide_by_default
@@ -158,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
@@ -205,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/object_serializer.rb

@@ -97,14 +97,14 @@ class Serega
       end
 
       # How to serialize `object`, deciding whether the result is a collection or a
-      # single object and reading `Enumerable` only once:
+      # single object and checking the object type only once:
       # - :many         — `many` is on and the object is a collection
       # - :many_for_one — `many` is on but a sole object was given (wrap it, don't raise)
       # - :one          — serialize the object on its own
       def serialize_mode(object)
         case many
-        when NilClass then object.is_a?(Enumerable) ? :many : :one
-        when TrueClass then object.is_a?(Enumerable) ? :many : :many_for_one
+        when NilClass then SeregaUtils::CollectionDetector.call(object) ? :many : :one
+        when TrueClass then SeregaUtils::CollectionDetector.call(object) ? :many : :many_for_one
         else :one # many == false
         end
       end

data/lib/serega/plugins/activerecord_preloads/activerecord_preloads.rb

@@ -91,6 +91,7 @@ class Serega
       # The underlying records to preload onto. The :presenter plugin wraps every
       # serialized object in a SimpleDelegator, but ActiveRecord's Preloader needs
       # the real records, so unwrap them via #__getobj__ when presenter is used.
+      # Objects are wrapped only when the Presenter class has custom methods.
       #
       # @param serializer_class [Class<Serega>] Current serializer class
       # @param objects [Array] objects serialized at the current level
@@ -99,6 +100,7 @@ class Serega
       #
       def self.records(serializer_class, objects)
         return objects unless serializer_class.plugin_used?(:presenter)
+        return objects unless serializer_class.custom_presenter?
 
         objects.map(&:__getobj__)
       end

data/lib/serega/plugins/explicit_many_option/explicit_many_option.rb

@@ -6,7 +6,8 @@ class Serega
     # Plugin :explicit_many_option
     #
     # Plugin requires to add :many option when adding relationships
-    # (relationships are attributes with :serializer option specified)
+    # (relationships are attributes with the :serializer option or a block
+    # defining a nested serializer)
     #
     # Adding this plugin makes it clearer to find if relationship returns array or single object
     #
@@ -56,7 +57,7 @@ class Serega
         def check_opts
           super
 
-          CheckOptMany.call(opts)
+          CheckOptMany.call(opts, block)
         end
       end
     end

data/lib/serega/plugins/explicit_many_option/validations/check_opt_many.rb

@@ -10,23 +10,25 @@ class Serega
         class << self
           #
           # Checks attribute :many option must be provided with relations
+          # (attributes with the :serializer option or a block defining
+          # a nested serializer)
           #
           # @param opts [Hash] Attribute options
+          # @param block [nil, Proc] Attribute block
           #
           # @raise [SeregaError] Attribute validation error
           #
           # @return [void]
           #
-          def call(opts)
-            serializer = opts[:serializer]
-            return unless serializer
+          def call(opts, block = nil)
+            return if !opts[:serializer] && !block
 
             many_option_exists = opts.key?(:many)
             return if many_option_exists
 
             raise SeregaError,
               "Attribute option :many [Boolean] must be provided" \
-              " for attributes with :serializer option"
+              " for attributes with :serializer option or a block"
           end
         end
       end

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

@@ -15,13 +15,19 @@ class Serega
     # - The original object is accessible via __getobj__ (standard SimpleDelegator API).
     # - The serialization context is accessible via the private method __ctx__.
     #
+    # Objects are wrapped in the Presenter only when the serializer's Presenter
+    # class (or an inherited one) was actually extended with custom methods —
+    # a bare `plugin :presenter` adds no wrapping overhead. The check is
+    # denormalized: `SerializerClass.custom_presenter?` is asked once per
+    # object serializer and the result is reused for the whole level.
+    #
     #   class UserSerializer < Serega
     #     plugin :presenter
     #
     #     attribute :name
     #     attribute :role
     #
-    #     class Presenter
+    #     presenter do
     #       def name
     #         [first_name, last_name].compact.join(' ') # first_name/last_name delegated to object
     #       end
@@ -31,6 +37,9 @@ class Serega
     #       end
     #     end
     #   end
+    #
+    # The `presenter do ... end` block is evaluated inside the serializer's own
+    # Presenter class, so multiple blocks accumulate.
     module Presenter
       # @return [Symbol] Plugin name
       def self.plugin_name
@@ -62,6 +71,11 @@ class Serega
         presenter_class = Class.new(Presenter)
         presenter_class.serializer_class = serializer_class
         serializer_class.const_set(:Presenter, presenter_class)
+
+        # The presenter's unwrap method returns the serialized object itself,
+        # not an association — it must never be auto-preloaded.
+        config = serializer_class.config
+        config.auto_preload_excluded_methods = config.auto_preload_excluded_methods | [:__getobj__]
       end
 
       # Presenter class
@@ -97,6 +111,48 @@ class Serega
         extend SeregaHelpers::SerializerClassHelper
         extend Forwardable
         include InstanceMethods
+
+        # Tracks whether user code was added to the Presenter class.
+        #
+        # These singleton methods are defined after the base class body above,
+        # so the plugin's own includes do not mark the base class as modified.
+        # Lazy delegators defined by #method_missing do mark the class, but
+        # they can appear only on presenters that are already wrapping.
+        class << self
+          #
+          # Checks if this Presenter class (or an inherited one) was extended
+          # with custom user code and therefore objects must be wrapped
+          #
+          # @return [Boolean] whether custom presenter methods were defined
+          #
+          def modified?
+            return true if defined?(@modified)
+            return false if equal?(Presenter) # the plugin's base class — the walk stops here
+
+            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
+          end
+
+          private
+
+          def method_added(name)
+            @modified = true
+            super
+          end
+        end
       end
 
       #
@@ -105,6 +161,36 @@ class Serega
       # @see Serega
       #
       module ClassMethods
+        #
+        # Defines presenter methods — evaluates the block inside the
+        # serializer's own Presenter class. Multiple blocks accumulate.
+        #
+        #   presenter do
+        #     def name
+        #       [first_name, last_name].compact.join(" ")
+        #     end
+        #   end
+        #
+        # @return [void]
+        #
+        def presenter(&block)
+          raise SeregaError, "Provide a block with presenter methods: `presenter do ... end`" unless block
+
+          self::Presenter.class_exec(&block)
+          nil
+        end
+
+        #
+        # Checks if the serializer's Presenter class (or an inherited one) was
+        # extended with custom user code. When it was not, serialized objects
+        # are not wrapped in the Presenter at all.
+        #
+        # @return [Boolean] whether custom presenter methods were defined
+        #
+        def custom_presenter?
+          self::Presenter.modified?
+        end
+
         private
 
         def inherited(subclass)
@@ -122,14 +208,25 @@ class Serega
       # @see Serega::SeregaObjectSerializer
       #
       module SeregaObjectSerializerInstanceMethods
+        # The custom-presenter check is made once per object serializer here
+        # and its result is reused for every enqueued chunk of the level.
+        def initialize(**opts)
+          super
+          @wrap_in_presenter = self.class.serializer_class.custom_presenter?
+        end
+
         private
 
         #
         # Wraps each serialized object in Presenter.new(object, ctx) before it is
         # enqueued, so the whole level — value resolution and batch loaders alike —
-        # sees presenters.
+        # sees presenters. Objects are not wrapped when the Presenter class has
+        # no custom methods — such wrapping would only add overhead and break
+        # class checks (object.is_a?, Hash === object) without changing anything.
         #
         def enqueue(objects)
+          return super unless @wrap_in_presenter
+
           presenter = self.class.serializer_class::Presenter
           presenters = objects.map { |object| presenter.new(object, context) }
           super(presenters)

data/lib/serega/plugins/root/root.rb

@@ -244,7 +244,7 @@ class Serega
           return opts[:root] if opts.key?(:root)
 
           root = self.class.config.root
-          (opts.fetch(:many) { object.is_a?(Enumerable) }) ? root.many : root.one
+          (opts.fetch(:many) { SeregaUtils::CollectionDetector.call(object) }) ? root.many : root.one
         end
       end
 

data/lib/serega/utils/collection_detector.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaUtils
+    #
+    # Utility to check if an object should be serialized as a collection.
+    #
+    # Hashes and Structs are Enumerable, but enumerate their own member
+    # values, so they are treated as single objects.
+    #
+    class CollectionDetector
+      class << self
+        #
+        # Checks if provided object is a collection of objects
+        #
+        # @param object [Object] Serialized object
+        #
+        # @return [Boolean] whether object should be serialized as a collection
+        #
+        def call(object)
+          object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)
+        end
+      end
+    end
+  end
+end

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

@@ -10,25 +10,30 @@ class Serega
       # Attribute `block` parameter validator
       #
       class CheckBlock
+        # Explains the changed attribute block behavior. Shown when the block
+        # looks like an old-style value block — it accepts parameters or
+        # defines no attributes.
+        ERROR_MESSAGE =
+          "Attribute block now defines a nested serializer:" \
+          " it is executed in the context of a new serializer class and must define its attributes." \
+          " Defining the attribute value with a block is not supported anymore," \
+          " use the `value: <callable>` option instead."
+
         class << self
           #
           # Checks block parameter provided with attribute.
-          # Must have up to two arguments - object and context. Context can be
-          # also provided as keyword argument :ctx.
-          #
-          # @example without arguments
-          #   attribute(:email) { CONSTANT_EMAIL }
-          #
-          # @example with one argument
-          #   attribute(:email) { |obj| obj.confirmed_email }
           #
-          # @example with two arguments
-          #   attribute(:email) { |obj, context| context['is_current'] ? obj.email : nil }
+          # The block defines attributes of a nested anonymous serializer, so
+          # it is executed in the context of that serializer and must accept
+          # no parameters.
           #
-          # @example with one argument and keyword context
-          #   attribute(:email) { |obj, ctx:| obj.email if ctx[:show] }
+          # @example
+          #   attribute :statistics, method: :itself do
+          #     attribute :likes_count
+          #     attribute :comments_count
+          #   end
           #
-          # @param block [Proc] Block that returns serialized attribute value
+          # @param block [Proc] Block that defines nested serializer attributes
           #
           # @raise [SeregaError] SeregaError that block has invalid arguments
           #
@@ -37,48 +42,8 @@ class Serega
           def call(block)
             return unless block
 
-            check_block(block)
-          end
-
-          private
-
-          def check_block(block)
-            signature = SeregaUtils::MethodSignature.call(block, pos_limit: 2, keyword_args: [:ctx, :batches])
-
-            raise SeregaError, signature_error unless valid_signature?(signature)
-          end
-
-          def valid_signature?(signature)
-            case signature
-            when "0"             # no parameters
-              true
-            when "1"             # call(object)
-              true
-            when "1_ctx"         # call(object, ctx:)
-              true
-            when "1_batches"     # call(object, batches:)
-              true
-            when "1_batches_ctx" # call(object, batches:, ctx:)
-              true
-            when "2"             # call(object, context)
-              true
-            when "2_batches_ctx" # call(object, context, batches:, ctx:) (proc with no params)
-              true
-            else
-              false
-            end
-          end
-
-          def signature_error
-            <<~ERROR.strip
-              Invalid attribute block parameters, valid parameters signatures:
-              - ()                       # no parameters
-              - (object)                 # one positional parameter
-              - (object, ctx:)           # one positional parameter and :ctx keyword
-              - (object, batches:)       # one positional parameter and :batches keyword
-              - (object, ctx:, batches:) # one positional parameter, :ctx, and :batches keywords
-              - (object, context)        # two positional parameters
-            ERROR
+            signature = SeregaUtils::MethodSignature.call(block, pos_limit: 0)
+            raise SeregaError, ERROR_MESSAGE unless signature == "0"
           end
         end
       end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaValidations
+    module Attribute
+      #
+      # Attribute `:base_serializer` option validator
+      #
+      class CheckOptBaseSerializer
+        class << self
+          #
+          # Checks attribute :base_serializer option. It specifies the parent
+          # class for the nested serializer defined with the attribute block,
+          # so it makes sense only when a block is provided.
+          #
+          # @param opts [Hash] Attribute options
+          # @param block [nil, Proc] Attribute block (defines a nested serializer)
+          #
+          # @raise [SeregaError] SeregaError that option has invalid value
+          #
+          # @return [void]
+          #
+          def call(opts, block = nil)
+            return unless opts.key?(:base_serializer)
+
+            raise SeregaError, "Option :base_serializer can be used only with a block" unless block
+
+            value = opts[:base_serializer]
+            return if value.is_a?(Class) && (value <= Serega)
+
+            raise SeregaError, "Invalid option :base_serializer => #{value.inspect}. Must be a Serega subclass"
+          end
+        end
+      end
+    end
+  end
+end