serega 0.35.0 → 0.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a32fcd6506959b5498ef6357c27110bd7623d0bf16e28d0485703016704e6cf4
-  data.tar.gz: 4e2bf60aba2c1db746587b1135a3d852e34858606ac30c6947c960d4e2dba726
+  metadata.gz: 461e4c9b6b9dcaf1c93cc490c8a4270bcc8ae576eed523ef14ee3bc1e6be0944
+  data.tar.gz: 7ac9f86f0952070deb5c6a5a812ec9384d9cadab9f783fa5ae5e705ff6cd3116
 SHA512:
-  metadata.gz: 8cb7d76c325320e144dd7de3dcfc376a03386a7742f7eea68cae1bbb421b0cbe969e2c858fbae253114bbb3ed86e63d4c689395976ac94463813a8229ae66f9e
-  data.tar.gz: e4595313b09bb2fcb7f37c6e26ebe9376a5caf86c66ed2ab4a19091aae854f1c51fafd0adea54cae0ac97eeb69e770e74f7e66d1aee44a8714d50ae225b8683a
+  metadata.gz: addb468352c4adc023c4f04e30dc6533fefbf7faba9755e02cd243e9f4631c30a0b3b4dd65b160a0f5c012e76717e2d67ddf3c0ac712e5cd0b3008ea3cd8df7d
+  data.tar.gz: da936fb8dd2fac9bafe4e670da795f3b3075d591b3c88411b306898d9a59f944354dc8b69941e19b7b2012bda6a6111a25f9dd0347d5ad8c76b56f310c0353ec

data/README.md

@@ -141,7 +141,7 @@ end
 
 ### Serializing
 
-We can serialize objects using class method `.call` aliased ad `.to_h` and
+We can serialize objects using class method `.call` aliased as `.to_h` and
 same instance methods `#call` and its alias `#to_h`.
 
 ```ruby
@@ -155,6 +155,18 @@ UserSerializer.to_h(user) # => {username: "serega"}
 UserSerializer.to_h([user]) # => [{username: "serega"}]
 ```
 
+Use `.to_data` / `#to_data` to get the same result as Ruby `Data` objects
+(immutable value objects, Ruby 3.2+). Nested serialized relations are also
+converted to `Data` objects.
+
+```ruby
+result = UserSerializer.to_data(user)
+result         # => #<data username="serega">
+result.username # => "serega"
+
+UserSerializer.to_data([user]) # => [#<data username="serega">]
+```
+
 If serialized fields are constant, then it's a good idea to initiate the
 serializer and reuse it.
 It will be a bit faster (the serialization plan will be prepared only once).

data/VERSION

@@ -1 +1 @@
-0.35.0
+0.36.0

data/lib/serega/batch/attribute_loaders.rb

@@ -18,7 +18,7 @@ class Serega
         @point_index = {}.compare_by_identity
       end
 
-      # Remembers data for batch seryalization:
+      # Remembers data for batch serialization:
       #
       # @param point [SeregaPlanPoint] Serialization plan point
       # @param object [Object] Serialized object

data/lib/serega/data_builder.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Builds Data objects from serialized hashes.
+  # Used by `#to_data` / `.to_data`.
+  #
+  class SeregaDataBuilder
+    # SeregaDataBuilder class methods
+    module SeregaDataBuilderClassMethods
+      #
+      # Converts serialized Hash/Array result into a tree of Ruby Data objects
+      # following the serializer's plan structure.
+      #
+      # @param serializer [Serega] Serializer instance carrying the plan
+      # @param serialized [Hash, Array, nil] Serialized output from `#to_h`
+      #
+      # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
+      #
+      def call(serializer, serialized)
+        build(serialized, serializer.plan)
+      end
+
+      private
+
+      def build(serialized, plan)
+        case serialized
+        when Array then serialized.map { |item| hash_to_data(item, plan) }
+        when Hash then hash_to_data(serialized, plan)
+        else serialized
+        end
+      end
+
+      def hash_to_data(hash, plan)
+        hash_data = hash.to_h do |key, value|
+          child_plan = plan.points_hash.fetch(key).child_plan
+          value = build(value, child_plan) if child_plan
+          [key, value]
+        end
+
+        build_data_object(plan, hash_data)
+      end
+
+      def build_data_object(plan, hash_data)
+        plan.data_class.new(**hash_data)
+      end
+    end
+
+    extend SeregaHelpers::SerializerClassHelper
+    extend SeregaDataBuilderClassMethods
+  end
+end

data/lib/serega/plan.rb

@@ -27,6 +27,18 @@ class Serega
         cached_plan_for(opts, max_cache_size)
       end
 
+      #
+      # Returns (and caches) the Data class for the given set of field names.
+      # Uses the Array as cache key so the same Data class is reused across
+      # all plan instances with identical fields.
+      #
+      # @param point_names [Array<Symbol>] Attribute names for the Data members
+      # @return [Class] Subclass of Data
+      #
+      def data_class_for(point_names)
+        (@data_classes ||= {})[point_names] ||= Data.define(*point_names)
+      end
+
       private
 
       def cached_plan_for(opts, max_cache_size)
@@ -57,6 +69,10 @@ class Serega
     # SeregaPlan instance methods
     #
     module InstanceMethods
+      # Shows if plan includes batch points
+      # @return [Array<SeregaPlanPoint>] points to serialize
+      attr_reader :has_batch_points
+
       # Parent plan point
       # @return [SeregaPlanPoint, nil]
       attr_reader :parent_plan_point
@@ -65,9 +81,9 @@ class Serega
       # @return [Array<SeregaPlanPoint>] points to serialize
       attr_reader :points
 
-      # Shows if plan includes batch points
-      # @return [Array<SeregaPlanPoint>] points to serialize
-      attr_reader :has_batch_points
+      # Named serialization points
+      # @return [Hash] Named points
+      attr_reader :points_hash
 
       #
       # Instantiate new serialization plan
@@ -87,6 +103,7 @@ class Serega
         @has_batch_points = false # should be before assigning points, generated points can change this attribute
         @parent_plan_point = parent_plan_point
         @points = attributes_points(modifiers)
+        @points_hash = points.to_h { |point| [point.name, point] }
       end
 
       #
@@ -96,6 +113,15 @@ class Serega
         self.class.serializer_class
       end
 
+      # Returns the Data class whose members match this plan's serialized fields.
+      # Delegates to the class-level cache so identical field sets share one Data class.
+      #
+      # @return [Class] Subclass of Data
+      #
+      def data_class
+        @data_class ||= self.class.data_class_for(point_names)
+      end
+
       #
       # Marks current plan and top-level plans as `has_batch_points`
       # It is needed to initialize Batch Attribute Loaders when serialization starts
@@ -130,6 +156,10 @@ class Serega
 
         points.freeze
       end
+
+      def point_names
+        @point_names ||= points.map(&:name)
+      end
     end
 
     extend ClassMethods

data/lib/serega/plugins/if/if.rb

@@ -69,6 +69,7 @@ class Serega
         serializer_class::SeregaPlanPoint.include(PlanPointInstanceMethods)
         serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
         serializer_class::SeregaObjectSerializer.include(ObjectSerializerInstanceMethods)
+        serializer_class::SeregaDataBuilder.extend(DataBuilderClassMethods)
       end
 
       #
@@ -215,6 +216,7 @@ class Serega
           when "1" then condition.call(object)
           when "2" then condition.call(object, context)
           when "1_ctx" then condition.call(object, ctx: context)
+          when "2_ctx" then condition.call(object, context, ctx: context)
           else # "0"
             condition.call
           end
@@ -239,6 +241,27 @@ class Serega
         end
       end
 
+      #
+      # SeregaDataBuilder additional/patched class methods
+      #
+      # Overrides `build_data_object` to handle plans where some keys were skipped
+      # by `:if`/`:unless`/`:if_value`/`:unless_value` conditions, so the Data class
+      # is built from the actually-present keys rather than the full plan.
+      #
+      # @see Serega::SeregaDataBuilder
+      #
+      module DataBuilderClassMethods
+        private
+
+        def build_data_object(plan, hash_data)
+          if hash_data.size < plan.points.size
+            plan.class.data_class_for(hash_data.keys).new(**hash_data)
+          else
+            super
+          end
+        end
+      end
+
       #
       # SeregaObjectSerializer additional/patched class methods
       #

data/lib/serega/plugins/if/validations/check_opt_if.rb

@@ -47,6 +47,8 @@ class Serega
               true
             when "1_ctx"  # (object, :ctx)
               true
+            when "2_ctx"  # (object, context, :ctx)
+              true
             else
               false
             end
@@ -55,10 +57,11 @@ class Serega
           def signature_error
             <<~ERROR.strip
               Invalid attribute option :if parameters, valid parameters signatures:
-              - ()                # no parameters
-              - (object)          # one positional parameter
-              - (object, context) # two positional parameters
-              - (object, :ctx)    # one positional parameter and :ctx keyword
+              - ()                     # no parameters
+              - (object)               # one positional parameter
+              - (object, context)      # two positional parameters
+              - (object, :ctx)         # one positional parameter and :ctx keyword
+              - (object, context, :ctx) # two positional parameters and :ctx keyword
             ERROR
           end
         end

data/lib/serega/plugins/if/validations/check_opt_if_value.rb

@@ -52,6 +52,8 @@ class Serega
               true
             when "1_ctx"  # (value, :ctx)
               true
+            when "2_ctx"  # (value, context, :ctx)
+              true
             else
               false
             end
@@ -60,10 +62,11 @@ class Serega
           def signature_error
             <<~ERROR.strip
               Invalid attribute option :if_value parameters, valid parameters signatures:
-              - ()               # no parameters
-              - (value)          # one positional parameter
-              - (value, context) # two positional parameters
-              - (value, :ctx)    # one positional parameter and :ctx keyword
+              - ()                     # no parameters
+              - (value)                # one positional parameter
+              - (value, context)       # two positional parameters
+              - (value, :ctx)          # one positional parameter and :ctx keyword
+              - (value, context, :ctx) # two positional parameters and :ctx keyword
             ERROR
           end
         end

data/lib/serega/plugins/if/validations/check_opt_unless.rb

@@ -47,6 +47,8 @@ class Serega
               true
             when "1_ctx"  # (object, :ctx)
               true
+            when "2_ctx"  # (object, context, :ctx)
+              true
             else
               false
             end
@@ -55,10 +57,11 @@ class Serega
           def signature_error
             <<~ERROR.strip
               Invalid attribute option :unless parameters, valid parameters signatures:
-              - ()                # no parameters
-              - (object)          # one positional parameter
-              - (object, context) # two positional parameters
-              - (object, :ctx)    # one positional parameter and :ctx keyword
+              - ()                      # no parameters
+              - (object)                # one positional parameter
+              - (object, context)       # two positional parameters
+              - (object, :ctx)          # one positional parameter and :ctx keyword
+              - (object, context, :ctx) # two positional parameters and :ctx keyword
             ERROR
           end
         end

data/lib/serega/plugins/if/validations/check_opt_unless_value.rb

@@ -52,6 +52,8 @@ class Serega
               true
             when "1_ctx"  # (value, :ctx)
               true
+            when "2_ctx"  # (value, context, :ctx)
+              true
             else
               false
             end
@@ -60,10 +62,11 @@ class Serega
           def signature_error
             <<~ERROR.strip
               Invalid attribute option :unless_value parameters, valid parameters signatures:
-              - ()               # no parameters
-              - (value)          # one positional parameter
-              - (value, context) # two positional parameters
-              - (value, :ctx)    # one positional parameter and :ctx keyword
+              - ()                     # no parameters
+              - (value)                # one positional parameter
+              - (value, context)       # two positional parameters
+              - (value, :ctx)          # one positional parameter and :ctx keyword
+              - (value, context, :ctx) # two positional parameters and :ctx keyword
             ERROR
           end
         end

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

@@ -92,6 +92,7 @@ class Serega
         serializer_class.extend(ClassMethods)
         serializer_class.include(InstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
+        serializer_class::SeregaDataBuilder.extend(DataBuilderClassMethods)
       end
 
       #
@@ -214,6 +215,22 @@ class Serega
       # @see Serega
       #
       module InstanceMethods
+        #
+        # Serializes provided object to a tree of Ruby Data objects.
+        # When a root key is configured, the result is wrapped in an outer Data object
+        # whose members include the root key plus any metadata keys.
+        #
+        # @param object [Object] Serialized object
+        # @param opts [Hash, nil] Serializing options (`:root`, `:many`, `:context`, etc.)
+        #
+        # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
+        #
+        def to_data(object, opts = nil)
+          opts = prepare_initial_serialization_opts(object, opts)
+          serialized_data = serialize(object, opts)
+          self.class::SeregaDataBuilder.call(self, serialized_data, opts)
+        end
+
         private
 
         def serialize(object, opts)
@@ -230,6 +247,69 @@ class Serega
           (opts.fetch(:many) { object.is_a?(Enumerable) }) ? root.many : root.one
         end
       end
+
+      #
+      # SeregaDataBuilder additional/patched class methods
+      #
+      # Overrides `call` to handle the root key: the serialized result is
+      # unwrapped from the root key, converted to a Data tree by the base
+      # implementation, and then re-wrapped together with any metadata keys
+      # in an outer Data object. Metadata values (arbitrary hashes/arrays)
+      # are recursively converted to Data objects via `deep_hash_to_data`.
+      #
+      # When the root key is `nil` (disabled), delegates directly to the base.
+      #
+      # @see Serega::SeregaDataBuilder
+      #
+      module DataBuilderClassMethods
+        #
+        # @param serializer [Serega] Serializer instance carrying the plan
+        # @param serialized_result [Hash, Array, nil] Full serialized output (possibly wrapped under root key)
+        # @param serialization_opts [Hash] Serialization options used to determine the root key
+        #
+        # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
+        #
+        def call(serializer, serialized_result, serialization_opts)
+          root_key = resolve_root_key(serializer, serialization_opts)
+          return super(serializer, serialized_result) unless root_key
+
+          root_data = super(serializer, serialized_result.fetch(root_key))
+          build_data_objects(serialized_result, root_key, root_data)
+        end
+
+        private
+
+        def resolve_root_key(serializer, serialization_opts)
+          if serialization_opts.key?(:root)
+            serialization_opts[:root]
+          else
+            config_root = serializer.class.config.root
+            serialization_opts[:many] ? config_root.many : config_root.one
+          end
+        end
+
+        def build_data_objects(serialized_result, root_key, root_data)
+          converted_hash =
+            serialized_result.to_h do |key, val|
+              value = (key == root_key) ? root_data : deep_hash_to_data(val)
+              [key, value]
+            end
+
+          Data.define(*converted_hash.keys).new(**converted_hash)
+        end
+
+        def deep_hash_to_data(value)
+          case value
+          when Hash
+            converted = value.transform_values { |nested| deep_hash_to_data(nested) }
+            Data.define(*value.keys).new(**converted)
+          when Array
+            value.map { |item| deep_hash_to_data(item) }
+          else
+            value
+          end
+        end
+      end
     end
 
     register_plugin(Root.plugin_name, Root)

data/lib/serega.rb

@@ -11,6 +11,10 @@ class Serega
   # Frozen array
   # @return [Array] frozen array
   FROZEN_EMPTY_ARRAY = [].freeze
+
+  # Empty modifiers/serialization options (used when serializing with no opts provided)
+  FROZEN_EMPTY_OPTS = [FROZEN_EMPTY_HASH, nil].freeze
+  private_constant :FROZEN_EMPTY_OPTS
 end
 
 require_relative "serega/errors"
@@ -58,6 +62,7 @@ require_relative "serega/config"
 require_relative "serega/object_serializer"
 require_relative "serega/plan_point"
 require_relative "serega/plan"
+require_relative "serega/data_builder"
 require_relative "serega/plugins"
 
 class Serega
@@ -230,25 +235,45 @@ class Serega
     # @return [Hash] Serialization result
     #
     def call(object, opts = nil)
-      opts ||= FROZEN_EMPTY_HASH
-      initiate_keys = config.initiate_keys
-
-      if opts.empty?
-        modifiers_opts = FROZEN_EMPTY_HASH
-        serialize_opts = nil
-      else
-        opts.transform_keys!(&:to_sym)
-        serialize_opts = opts.except(*initiate_keys)
-        modifiers_opts = opts.slice(*initiate_keys)
-      end
-
+      opts = opts&.transform_keys(&:to_sym)
+      modifiers_opts = init_modifier_opts(opts)
+      serialize_opts = init_serialize_opts(opts)
       new(modifiers_opts).to_h(object, serialize_opts)
     end
 
+    #
+    # Serializes provided object to a tree of Ruby Data objects
+    #
+    # @param object [Object] Serialized object
+    # @param opts [Hash, nil] Serializer modifiers and other instantiating options
+    # @option opts [Array, Hash, String, Symbol] :only The only attributes to serialize
+    # @option opts [Array, Hash, String, Symbol] :except Attributes to hide
+    # @option opts [Array, Hash, String, Symbol] :with Attributes (usually hidden) to serialize additionally
+    # @option opts [Boolean] :validate Validates provided modifiers (Default is true)
+    # @option opts [Hash] :context Serialization context
+    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable)`)
+    #
+    # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
+    #
+    def to_data(object, opts = nil)
+      opts = opts&.transform_keys(&:to_sym)
+      modifiers_opts = init_modifier_opts(opts)
+      serialize_opts = init_serialize_opts(opts)
+      new(modifiers_opts).to_data(object, serialize_opts)
+    end
+
     alias_method :to_h, :call
 
     private
 
+    def init_modifier_opts(opts)
+      (!opts || opts.empty?) ? FROZEN_EMPTY_HASH : opts.slice(*config.initiate_keys)
+    end
+
+    def init_serialize_opts(opts)
+      (!opts || opts.empty?) ? nil : opts.except(*config.initiate_keys)
+    end
+
     # Patched in:
     # - plugin :metadata (defines MetaAttribute and copies meta_attributes to subclasses)
     # - plugin :presenter (defines Presenter)
@@ -266,6 +291,10 @@ class Serega
       attribute_normalizer_class.serializer_class = subclass
       subclass.const_set(:SeregaAttributeNormalizer, attribute_normalizer_class)
 
+      data_builder_class = Class.new(self::SeregaDataBuilder)
+      data_builder_class.serializer_class = subclass
+      subclass.const_set(:SeregaDataBuilder, data_builder_class)
+
       plan_class = Class.new(self::SeregaPlan)
       plan_class.serializer_class = subclass
       subclass.const_set(:SeregaPlan, plan_class)
@@ -355,17 +384,14 @@ class Serega
     # Serializes provided object to Hash
     #
     # @param object [Object] Serialized object
-    # @param opts [Hash, nil] Serializer modifiers and other instantiating options
+    # @param opts [Hash, nil] Serializing options
     # @option opts [Hash] :context Serialization context
     # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable)`)
     #
     # @return [Hash] Serialization result
     #
     def call(object, opts = nil)
-      opts = opts ? opts.transform_keys!(&:to_sym) : {}
-      self.class::CheckSerializeParams.new(opts).validate unless opts.empty?
-
-      opts[:context] ||= {}
+      opts = prepare_initial_serialization_opts(object, opts)
       serialize(object, opts)
     end
 
@@ -374,6 +400,24 @@ class Serega
       call(object, opts)
     end
 
+    #
+    # Serializes provided object to Data objects
+    # Patched in:
+    # - plugin :root (adds a data-object for a root level keys)
+    #
+    # @param object [Object] Serialized object
+    # @param opts [Hash, nil] Serializing options
+    # @option opts [Hash] :context Serialization context
+    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable)`)
+    #
+    # @return [Data] Serialization result
+    #
+    def to_data(object, opts = nil)
+      opts = prepare_initial_serialization_opts(object, opts)
+      serialized_data = serialize(object, opts)
+      self.class::SeregaDataBuilder.call(self, serialized_data)
+    end
+
     # @return [Hash] merged preloads of all serialized attributes
     def preloads
       @preloads ||= SeregaUtils::PreloadsConstructor.call(plan)
@@ -404,15 +448,25 @@ class Serega
       SeregaUtils::ToHash.call(value)
     end
 
+    def prepare_initial_serialization_opts(object, opts)
+      opts = opts ? opts.transform_keys(&:to_sym) : {}
+      self.class::CheckSerializeParams.new(opts).validate unless opts.empty?
+
+      opts[:context] ||= {}
+      opts[:batch_loaders] = SeregaBatch::AttributeLoaders.new if plan.has_batch_points
+      opts[:many] = object.is_a?(Enumerable) unless opts.key?(:many)
+      opts[:plan] = plan
+      opts
+    end
+
     # Patched in:
     # - plugin :activerecord_preloads (loads defined :preloads to object)
     # - plugin :root (wraps result `{ root => result }`)
     # - plugin :context_metadata (adds context metadata to final result)
     # - plugin :metadata (adds metadata to final result)
     def serialize(object, opts)
-      batch_loaders = plan.has_batch_points ? SeregaBatch::AttributeLoaders.new : nil
-      result = self.class::SeregaObjectSerializer.new(**opts, batch_loaders: batch_loaders, plan: plan).serialize(object)
-      batch_loaders&.load_all(opts[:context])
+      result = self.class::SeregaObjectSerializer.new(**opts).serialize(object)
+      opts[:batch_loaders]&.load_all(opts[:context])
       result
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.35.0
+  version: 0.36.0
 platform: ruby
 authors:
 - Andrey Glushkov
@@ -37,6 +37,7 @@ files:
 - lib/serega/batch/attribute_loaders.rb
 - lib/serega/batch/loader.rb
 - lib/serega/config.rb
+- lib/serega/data_builder.rb
 - lib/serega/errors.rb
 - lib/serega/helpers/serializer_class_helper.rb
 - lib/serega/object_serializer.rb
@@ -114,7 +115,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="