serega 0.35.0 → 0.37.0

data/lib/serega.rb

@@ -11,16 +11,17 @@ 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"
 require_relative "serega/helpers/serializer_class_helper"
 require_relative "serega/utils/enum_deep_dup"
 require_relative "serega/utils/enum_deep_freeze"
-require_relative "serega/utils/format_user_preloads"
 require_relative "serega/utils/method_signature"
-require_relative "serega/utils/preload_paths"
-require_relative "serega/utils/preloads_constructor"
 require_relative "serega/utils/symbol_name"
 require_relative "serega/utils/to_hash"
 require_relative "serega/attribute_value_resolvers/batch"
@@ -31,6 +32,7 @@ require_relative "serega/attribute"
 require_relative "serega/attribute_normalizer"
 require_relative "serega/batch/attribute_loader"
 require_relative "serega/batch/attribute_loaders"
+require_relative "serega/batch/level"
 require_relative "serega/batch/loader"
 require_relative "serega/validations/utils/check_allowed_keys"
 require_relative "serega/validations/utils/check_opt_is_bool"
@@ -45,7 +47,6 @@ require_relative "serega/validations/attribute/check_opt_batch"
 require_relative "serega/validations/attribute/check_opt_many"
 require_relative "serega/validations/attribute/check_opt_method"
 require_relative "serega/validations/attribute/check_opt_preload"
-require_relative "serega/validations/attribute/check_opt_preload_path"
 require_relative "serega/validations/attribute/check_opt_serializer"
 require_relative "serega/validations/attribute/check_opt_value"
 require_relative "serega/validations/initiate/check_modifiers"
@@ -58,6 +59,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
@@ -215,6 +217,38 @@ class Serega
       batch_loaders[batch_loader.name] = batch_loader
     end
 
+    #
+    # Registers (or returns) the handler used to preload an attribute's
+    # associations onto the records gathered during serialization.
+    #
+    # The handler is called once per preloaded attribute with the gathered
+    # objects and that attribute's preloads. ORM plugins register a handler
+    # that performs the actual eager loading.
+    #
+    # @example with a block
+    #   preload_with { |objects, preloads| MyORM.eager_load(objects, preloads) }
+    #
+    # @example with a callable value
+    #   preload_with MyPreloader
+    #
+    # @param value [#call, nil] Preload handler accepting two positional arguments
+    # @param block [Proc] Preload handler accepting two positional arguments
+    #
+    # @return [#call, nil] The registered preload handler
+    #
+    def preload_with(value = nil, &block)
+      return @preload_with if value.nil? && block.nil?
+      raise SeregaError, "preload_with accepts a single callable or a block, not both" if value && block
+
+      handler = value || block
+      raise SeregaError, "preload_with value must be a Proc or respond to #call" if !handler.is_a?(Proc) && !handler.respond_to?(:call)
+
+      signature = SeregaUtils::MethodSignature.call(handler, pos_limit: 2)
+      raise SeregaError, "preload_with handler must accept two positional arguments: (objects, preloads)" unless signature == "2"
+
+      @preload_with = handler
+    end
+
     #
     # Serializes provided object to Hash
     #
@@ -230,25 +264,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 +320,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)
@@ -313,6 +371,9 @@ class Serega
         subclass.batch(loader.name, loader.block)
       end
 
+      # Assign same preload handler
+      subclass.preload_with(preload_with) if preload_with
+
       super
     end
   end
@@ -355,17 +416,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,9 +432,22 @@ class Serega
       call(object, opts)
     end
 
-    # @return [Hash] merged preloads of all serialized attributes
-    def preloads
-      @preloads ||= SeregaUtils::PreloadsConstructor.call(plan)
+    #
+    # 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
 
     private
@@ -404,15 +475,24 @@ 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(opts[:context])
+      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
       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.37.0
 platform: ruby
 authors:
 - Andrey Glushkov
@@ -35,8 +35,10 @@ files:
 - lib/serega/attribute_value_resolvers/keyword.rb
 - lib/serega/batch/attribute_loader.rb
 - lib/serega/batch/attribute_loaders.rb
+- lib/serega/batch/level.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
@@ -44,7 +46,6 @@ files:
 - lib/serega/plan_point.rb
 - lib/serega/plugins.rb
 - lib/serega/plugins/activerecord_preloads/activerecord_preloads.rb
-- lib/serega/plugins/activerecord_preloads/lib/active_record_objects.rb
 - lib/serega/plugins/activerecord_preloads/lib/preloader.rb
 - lib/serega/plugins/camel_case/camel_case.rb
 - lib/serega/plugins/context_metadata/context_metadata.rb
@@ -72,10 +73,7 @@ files:
 - lib/serega/plugins/string_modifiers/string_modifiers.rb
 - lib/serega/utils/enum_deep_dup.rb
 - lib/serega/utils/enum_deep_freeze.rb
-- lib/serega/utils/format_user_preloads.rb
 - lib/serega/utils/method_signature.rb
-- lib/serega/utils/preload_paths.rb
-- lib/serega/utils/preloads_constructor.rb
 - lib/serega/utils/symbol_name.rb
 - lib/serega/utils/to_hash.rb
 - lib/serega/validations/attribute/check_block.rb
@@ -87,7 +85,6 @@ files:
 - lib/serega/validations/attribute/check_opt_many.rb
 - lib/serega/validations/attribute/check_opt_method.rb
 - lib/serega/validations/attribute/check_opt_preload.rb
-- lib/serega/validations/attribute/check_opt_preload_path.rb
 - lib/serega/validations/attribute/check_opt_serializer.rb
 - lib/serega/validations/attribute/check_opt_value.rb
 - lib/serega/validations/check_attribute_params.rb
@@ -114,14 +111,14 @@ 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:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.13
 specification_version: 4
 summary: JSON Serializer
 test_files: []

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

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaPlugins
-    module ActiverecordPreloads
-      # Detects and returns found ActiveRecord objects
-      class ActiveRecordObjects
-        class << self
-          # Iterates over provided data and selects ActiveRecord objects
-          # @param data [Hash,Array,Object] any data
-          # @return [Array] Found ActiveRecord objects
-          def call(data)
-            res = []
-            extract(data, res)
-            res
-          end
-
-          private
-
-          def extract(data, res)
-            case data
-            when ActiveRecord::Base then res << data
-            when Array then data.each { |value| extract(value, res) }
-            when Hash then data.each_value { |value| extract(value, res) }
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/serega/utils/format_user_preloads.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaUtils
-    #
-    # Utility that helps to transform user provided preloads to hash
-    #
-    class FormatUserPreloads
-      class << self
-        #
-        # Transforms user provided preloads to hash
-        #
-        # @param value [Array,Hash,String,Symbol,nil,false] preloads
-        #
-        # @return [Hash] preloads transformed to hash
-        #
-        def call(value)
-          case value
-          when Array then array_to_hash(value)
-          when FalseClass then nil_to_hash(value)
-          when Hash then hash_to_hash(value)
-          when NilClass then nil_to_hash(value)
-          when String then string_to_hash(value)
-          when Symbol then symbol_to_hash(value)
-          else raise Serega::SeregaError,
-            "Preload option value can consist from Symbols, Arrays, Hashes (#{value.class} #{value.inspect} was provided)"
-          end
-        end
-
-        private
-
-        def array_to_hash(values)
-          values.each_with_object({}) do |value, obj|
-            obj.merge!(call(value))
-          end
-        end
-
-        def hash_to_hash(values)
-          values.each_with_object({}) do |(key, value), obj|
-            obj[key.to_sym] = call(value)
-          end
-        end
-
-        def nil_to_hash(_value)
-          {}
-        end
-
-        def string_to_hash(value)
-          {value.to_sym => {}}
-        end
-
-        def symbol_to_hash(value)
-          {value => {}}
-        end
-      end
-    end
-  end
-end

data/lib/serega/utils/preload_paths.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaUtils
-    #
-    # Utility that helps to transform preloads to array of paths
-    # It is used to validate manually set `:preload_path` attribute option has one of allowed values.
-    # `:preload_path` option can be used to specify where nested preloads must be attached.
-    #
-    # Example:
-    #
-    #   call({ a: { b: { c: {}, d: {} } }, e: {} })
-    #
-    #   => [
-    #        [:a],
-    #        [:a, :b],
-    #        [:a, :b, :c],
-    #        [:a, :b, :d],
-    #        [:e]
-    #      ]
-    class PreloadPaths
-      class << self
-        #
-        # Transforms user provided preloads to array of paths
-        #
-        # @param preloads [Array,Hash,String,Symbol,nil,false] association(s) to preload
-        #
-        # @return [Array] transformed preloads
-        #
-        def call(preloads)
-          formatted_preloads = FormatUserPreloads.call(preloads)
-          return FROZEN_EMPTY_ARRAY if formatted_preloads.empty?
-
-          paths(formatted_preloads, [], [])
-        end
-
-        private
-
-        def paths(formatted_preloads, path, result)
-          formatted_preloads.each do |key, nested_preloads|
-            path << key
-            result << path.dup
-
-            paths(nested_preloads, path, result)
-            path.pop
-          end
-
-          result
-        end
-      end
-    end
-  end
-end

data/lib/serega/utils/preloads_constructor.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaUtils
-    #
-    # Finds preloads for provided attributes plan
-    #
-    class PreloadsConstructor
-      class << self
-        #
-        # Constructs preloads hash for given attributes plan
-        #
-        # @param plan [Array<SeregaPlanPoint>] Serialization plan
-        #
-        # @return [Hash]
-        #
-        def call(plan)
-          return FROZEN_EMPTY_HASH unless plan
-
-          preloads = {}
-          append_many(preloads, plan)
-          preloads
-        end
-
-        private
-
-        def append_many(preloads, plan)
-          plan.points.each do |point|
-            current_preloads = point.attribute.preloads
-            next unless current_preloads
-
-            child_plan = point.child_plan
-            current_preloads = SeregaUtils::EnumDeepDup.call(current_preloads) if child_plan
-            append_current(preloads, current_preloads)
-            next unless child_plan
-
-            each_child_preloads(preloads, point.preloads_path) do |child_preloads|
-              append_many(child_preloads, child_plan)
-            end
-          end
-        end
-
-        def append_current(preloads, current_preloads)
-          merge(preloads, current_preloads) unless current_preloads.empty?
-        end
-
-        def merge(preloads, current_preloads)
-          preloads.merge!(current_preloads) do |_key, value_one, value_two|
-            merge(value_one, value_two)
-          end
-        end
-
-        def each_child_preloads(preloads, preloads_path)
-          return yield(preloads) if preloads_path.nil?
-
-          if preloads_path[0].is_a?(Array)
-            preloads_path.each do |path|
-              yield dig_fetch(preloads, path)
-            end
-          else
-            yield dig_fetch(preloads, preloads_path)
-          end
-        end
-
-        def dig_fetch(preloads, preloads_path)
-          return preloads if !preloads_path || preloads_path.empty?
-
-          preloads_path.each do |path|
-            preloads = preloads.fetch(path)
-          end
-
-          preloads
-        end
-      end
-    end
-  end
-end

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

@@ -1,89 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaValidations
-    module Attribute
-      #
-      # Validator for attribute :preload_path option
-      #
-      class CheckOptPreloadPath
-        class << self
-          #
-          # Checks preload_path option
-          #
-          # @param opts [Hash] Attribute options
-          #
-          # @raise [SeregaError] validation error
-          #
-          # @return [void]
-          #
-          def call(opts)
-            return if exactly_nil?(opts, :preload_path) # allow to provide nil anyway
-
-            path = opts[:preload_path]
-            check_usage_with_other_options(path, opts)
-            return unless opts[:serializer]
-
-            check_allowed(path, opts)
-          end
-
-          private
-
-          def exactly_nil?(opts, opt_name)
-            opts.fetch(opt_name, false).nil?
-          end
-
-          def check_allowed(path, opts)
-            allowed_paths = SeregaUtils::PreloadPaths.call(opts[:preload])
-            check_required_when_many_allowed(path, allowed_paths)
-            check_in_allowed(path, allowed_paths)
-          end
-
-          def check_usage_with_other_options(path, opts)
-            return unless path
-
-            preload = opts[:preload]
-            raise SeregaError, "Invalid option preload_path: #{path.inspect}. Can be provided only when :preload option provided" unless preload
-
-            serializer = opts[:serializer]
-            raise SeregaError, "Invalid option preload_path: #{path.inspect}. Can be provided only when :serializer option provided" unless serializer
-          end
-
-          def check_required_when_many_allowed(path, allowed)
-            return if path || (allowed.size < 2)
-
-            raise SeregaError, "Option :preload_path must be provided. Possible values: #{allowed.inspect[1..-2]}"
-          end
-
-          def check_in_allowed(path, allowed)
-            return if !path && allowed.size <= 1
-
-            if multiple_preload_paths_provided?(path)
-              check_many(path, allowed)
-            else
-              check_one(path, allowed)
-            end
-          end
-
-          def check_one(path, allowed)
-            formatted_path = Array(path).map(&:to_sym)
-            return if allowed.include?(formatted_path)
-
-            raise SeregaError,
-              "Invalid preload_path (#{path.inspect}). " \
-              "Can be one of #{allowed.inspect[1..-2]}"
-          end
-
-          def check_many(paths, allowed)
-            paths.each { |path| check_one(path, allowed) }
-          end
-
-          # Check value is Array in Array
-          def multiple_preload_paths_provided?(value)
-            value.is_a?(Array) && value[0].is_a?(Array)
-          end
-        end
-      end
-    end
-  end
-end