serega 0.20.1 → 0.30.0

data/lib/serega/{plugins/preloads/validations → validations/attribute}/check_opt_preload_path.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 class Serega
-  module SeregaPlugins
-    module Preloads
+  module SeregaValidations
+    module Attribute
       #
       # Validator for attribute :preload_path option
       #
@@ -34,7 +34,7 @@ class Serega
           end
 
           def check_allowed(path, opts)
-            allowed_paths = PreloadPaths.call(opts[:preload])
+            allowed_paths = SeregaUtils::PreloadPaths.call(opts[:preload])
             check_required_when_many_allowed(path, allowed_paths)
             check_in_allowed(path, allowed_paths)
           end

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

@@ -35,23 +35,49 @@ class Serega
 
           def check_value(value)
             check_value_type(value)
-
-            SeregaValidations::Utils::CheckExtraKeywordArg.call(value, ":value option")
-            params_count = SeregaUtils::ParamsCount.call(value, max_count: 2)
-
-            raise SeregaError, params_count_error if params_count > 2
+            signature = SeregaUtils::MethodSignature.call(value, pos_limit: 2, keyword_args: %i[ctx batches])
+            raise SeregaError, signature_error unless valid_signature?(signature)
           end
 
           def check_value_type(value)
             raise SeregaError, type_error if !value.is_a?(Proc) && !value.respond_to?(:call)
           end
 
-          def type_error
-            "Option :value value must be a Proc or respond to #call"
+          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, ctx:, batches:)
+              true
+            when "2"             # call(object, context)
+              true
+            when "2_batches_ctx" # call(object, context, ctx:, batches:) (proc with no params)
+              true
+            else
+              false
+            end
           end
 
-          def params_count_error
-            "Option :value value can have maximum 2 parameters (object, context)"
+          def signature_error
+            <<~ERROR.strip
+              Invalid attribute :value option 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
+          end
+
+          def type_error
+            "Option :value value must be a Proc or respond to #call"
           end
         end
       end

data/lib/serega/validations/check_attribute_params.rb

@@ -53,11 +53,9 @@ class Serega
         end
 
         # Patched in:
-        # - plugin :batch (checks :batch option)
         # - plugin :context_metadata (checks context metadata option which is :meta by default)
         # - plugin :formatters (checks :format option)
         # - plugin :if (checks :if, :if_value, :unless, :unless_value options)
-        # - plugin :preloads (checks :preload option)
         def check_opts
           Utils::CheckAllowedKeys.call(opts, allowed_opts_keys, :attribute)
 
@@ -66,8 +64,11 @@ class Serega
           Attribute::CheckOptHide.call(opts)
           Attribute::CheckOptMethod.call(opts, block)
           Attribute::CheckOptMany.call(opts)
+          Attribute::CheckOptPreload.call(opts)
+          Attribute::CheckOptPreloadPath.call(opts)
           Attribute::CheckOptSerializer.call(opts)
           Attribute::CheckOptValue.call(opts, block)
+          Attribute::CheckOptBatch.call(self.class.serializer_class, opts, block)
         end
 
         def check_block

data/lib/serega/validations/check_batch_loader_params.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaValidations
+    #
+    # Batch loader parameters validators
+    #
+    class CheckBatchLoaderParams
+      #
+      # batch_loader parameters validation instance methods
+      #
+      module InstanceMethods
+        # @return [Symbol] validated batch_loader name
+        attr_reader :name
+
+        # @return [nil, #call] validated batch_loader value or block
+        attr_reader :batch_loader
+
+        # Instantiates batch loader params checker
+        # @param name [Symbol, String] Batch loader name
+        # @param batch_loader [Proc, #call] Batch loader
+        def initialize(name, batch_loader)
+          @name = name
+          @batch_loader = batch_loader
+        end
+
+        #
+        # Checks batch loader parameters
+        #
+        # @raise [SeregaError] SeregaError that batch loader has invalid arguments
+        #
+        # @return [void]
+        #
+        def validate
+          check_name
+          check_loader
+        end
+
+        private
+
+        def check_name
+          raise SeregaError, name_type_error if !name.is_a?(Symbol) && !name.is_a?(String)
+        end
+
+        def check_loader
+          check_batch_loader_type
+          check_batch_loader_args
+        end
+
+        def check_batch_loader_type
+          raise SeregaError, type_error if !batch_loader.is_a?(Proc) && !batch_loader.respond_to?(:call)
+        end
+
+        def check_batch_loader_args
+          signature = SeregaUtils::MethodSignature.call(batch_loader, pos_limit: 2, keyword_args: [:ctx])
+          raise SeregaError, arguments_error unless %w[1 2 1_ctx].include?(signature)
+        end
+
+        def name_type_error
+          "Batch loader name must be a Symbol or String"
+        end
+
+        def type_error
+          "Batch loader value must be a Proc or respond to #call"
+        end
+
+        def arguments_error
+          <<~ERR.strip
+            Batch loader arguments should have one of this signatures:
+            - (objects)       # one argument
+            - (objects, :ctx) # one argument and one :ctx keyword argument
+          ERR
+        end
+      end
+
+      include InstanceMethods
+      extend Serega::SeregaHelpers::SerializerClassHelper
+    end
+  end
+end

data/lib/serega/validations/initiate/check_modifiers.rb

@@ -71,7 +71,7 @@ class Serega
 
         def build_full_attribute_name(*names)
           head, *nested = *names
-          result = head.to_s # names are symbols, we need not frozen string
+          result = +head.to_s # names are symbols, we need not frozen string
           nested.each { |nested_name| result << "(" << nested_name.to_s }
           nested.each { result << ")" }
           result

data/lib/serega.rb

@@ -17,15 +17,22 @@ 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/params_count"
+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/json/adapter"
 
 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/auto_resolver"
+require_relative "serega/batch/auto_resolver_factory"
+require_relative "serega/batch/loader"
 require_relative "serega/validations/utils/check_allowed_keys"
-require_relative "serega/validations/utils/check_extra_keyword_arg"
 require_relative "serega/validations/utils/check_opt_is_bool"
 require_relative "serega/validations/utils/check_opt_is_hash"
 require_relative "serega/validations/utils/check_opt_is_string_or_symbol"
@@ -34,13 +41,17 @@ require_relative "serega/validations/attribute/check_name"
 require_relative "serega/validations/attribute/check_opt_const"
 require_relative "serega/validations/attribute/check_opt_hide"
 require_relative "serega/validations/attribute/check_opt_delegate"
+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"
 require_relative "serega/validations/check_attribute_params"
 require_relative "serega/validations/check_initiate_params"
+require_relative "serega/validations/check_batch_loader_params"
 require_relative "serega/validations/check_serialize_params"
 
 require_relative "serega/config"
@@ -67,6 +78,21 @@ class Serega
   check_serialize_params_class.serializer_class = self
   const_set(:CheckSerializeParams, check_serialize_params_class)
 
+  # Validates `Serializer.batch_loader` params
+  check_batch_loader_params_class = Class.new(SeregaValidations::CheckBatchLoaderParams)
+  check_batch_loader_params_class.serializer_class = self
+  const_set(:CheckBatchLoaderParams, check_batch_loader_params_class)
+
+  # Assigns `SeregaBatchLoader` constant to current class
+  batch_loader_class = Class.new(SeregaBatch::Loader)
+  batch_loader_class.serializer_class = self
+  const_set(:SeregaBatchLoader, batch_loader_class)
+
+  # Assigns `SeregaBatchAttributeLoader` constant to current class
+  batch_attribute_loader_class = Class.new(SeregaBatch::AttributeLoader)
+  batch_attribute_loader_class.serializer_class = self
+  const_set(:SeregaBatchAttributeLoader, batch_attribute_loader_class)
+
   #
   # Serializers class methods
   #
@@ -128,6 +154,15 @@ class Serega
       @attributes ||= {}
     end
 
+    #
+    # Lists batch loaders
+    #
+    # @return [Hash] batch loaders list
+    #
+    def batch_loaders
+      @batch_loaders ||= {}
+    end
+
     #
     # Adds attribute
     #
@@ -145,6 +180,41 @@ class Serega
       attributes[attribute.name] = attribute
     end
 
+    #
+    # Defines a batch loader
+    #
+    # @example
+    #   batch_loader :tags, PostTagsLoader
+    #
+    # @example with block
+    #   batch_loader(:tags) do |posts|
+    #     Tags.where(post: posts).group(:post_id).pluck(:post_id, Arel.sql('ARRAY_AGG(tags.tag ORDER BY tag)')).to_h
+    #   end
+    #
+    #   attribute :tags, batch: :tags, value: { |post, batch:| batch[:tags][post.id] }
+    #
+    # @example with context
+    #   batch_loader(:tags) do |posts, ctx:|
+    #     next {} if ctx[:bot]
+    #
+    #     Tags.where(post: posts).group(:post_id).pluck(:post_id, Arel.sql('ARRAY_AGG(tags.tag ORDER BY tag)')).to_h
+    #   end
+    #
+    #   attribute :tags, batch: :tags, value: { |post, batch:| batch[:tags][post.id] }
+    #
+    # @param name [Symbol] A batch loader name
+    # @param value [#call] Batch loader
+    # @param block [Proc] Batch loader
+    #
+    # @return [#call] Batch loader
+    #
+    def batch_loader(name, value = nil, &block)
+      raise SeregaError, "Batch loader must be defined with a callable value or block" if (value && block) || (!value && !block)
+
+      batch_loader = self::SeregaBatchLoader.new(name: name, block: value || block)
+      batch_loaders[batch_loader.name] = batch_loader
+    end
+
     #
     # Serializes provided object to Hash
     #
@@ -167,6 +237,7 @@ class Serega
         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
@@ -231,7 +302,6 @@ class Serega
     private
 
     # Patched in:
-    # - plugin :batch (defines SeregaBatchLoaders, SeregaBatchLoader)
     # - plugin :metadata (defines MetaAttribute and copies meta_attributes to subclasses)
     # - plugin :presenter (defines Presenter)
     def inherited(subclass)
@@ -256,6 +326,14 @@ class Serega
       plan_point_class.serializer_class = subclass
       subclass.const_set(:SeregaPlanPoint, plan_point_class)
 
+      batch_loader_class = Class.new(self::SeregaBatchLoader)
+      batch_loader_class.serializer_class = subclass
+      subclass.const_set(:SeregaBatchLoader, batch_loader_class)
+
+      batch_attribute_loader_class = Class.new(self::SeregaBatchAttributeLoader)
+      batch_attribute_loader_class.serializer_class = subclass
+      subclass.const_set(:SeregaBatchAttributeLoader, batch_attribute_loader_class)
+
       object_serializer_class = Class.new(self::SeregaObjectSerializer)
       object_serializer_class.serializer_class = subclass
       subclass.const_set(:SeregaObjectSerializer, object_serializer_class)
@@ -272,12 +350,21 @@ class Serega
       check_serialize_params_class.serializer_class = subclass
       subclass.const_set(:CheckSerializeParams, check_serialize_params_class)
 
+      check_batch_loader_params_class = Class.new(self::CheckBatchLoaderParams)
+      check_batch_loader_params_class.serializer_class = self
+      subclass.const_set(:CheckBatchLoaderParams, check_batch_loader_params_class)
+
       # Assign same attributes
       attributes.each_value do |attr|
         params = attr.initials
         subclass.attribute(params[:name], **params[:opts], &params[:block])
       end
 
+      # Assign same batch loaders
+      batch_loaders.each_value do |loader|
+        subclass.batch_loader(loader.name, loader.block)
+      end
+
       super
     end
   end
@@ -296,7 +383,14 @@ class Serega
     # @option opts [Boolean] :validate Validates provided modifiers (Default is true)
     #
     def initialize(opts = nil)
-      @opts = (opts.nil? || opts.empty?) ? FROZEN_EMPTY_HASH : parse_modifiers(opts)
+      @opts =
+        if opts.nil? || opts.empty?
+          FROZEN_EMPTY_HASH
+        else
+          opts.transform_keys!(&:to_sym)
+          parse_modifiers(opts)
+        end
+
       self.class::CheckInitiateParams.new(@opts).validate if opts&.fetch(:check_initiate_params) { config.check_initiate_params }
 
       @plan = self.class::SeregaPlan.call(@opts)
@@ -320,10 +414,10 @@ class Serega
     # @return [Hash] Serialization result
     #
     def call(object, opts = nil)
-      self.class::CheckSerializeParams.new(opts).validate if opts&.any?
-      opts ||= {}
-      opts[:context] ||= {}
+      opts = opts ? opts.transform_keys!(&:to_sym) : {}
+      self.class::CheckSerializeParams.new(opts).validate unless opts.empty?
 
+      opts[:context] ||= {}
       serialize(object, opts)
     end
 
@@ -332,6 +426,11 @@ class Serega
       call(object, opts)
     end
 
+    # @return [Hash] merged preloads of all serialized attributes
+    def preloads
+      @preloads ||= SeregaUtils::PreloadsConstructor.call(plan)
+    end
+
     #
     # Serializes provided object to JSON string
     #
@@ -389,14 +488,14 @@ class Serega
 
     # Patched in:
     # - plugin :activerecord_preloads (loads defined :preloads to object)
-    # - plugin :batch (runs serialization of collected batches)
     # - 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)
-      self.class::SeregaObjectSerializer
-        .new(**opts, plan: plan)
-        .serialize(object)
+      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
     end
   end
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.20.1
+  version: 0.30.0
 platform: ruby
 authors:
 - Andrey Glushkov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-25 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
   JSON Serializer
@@ -30,6 +29,11 @@ files:
 - lib/serega.rb
 - lib/serega/attribute.rb
 - lib/serega/attribute_normalizer.rb
+- lib/serega/batch/attribute_loader.rb
+- lib/serega/batch/attribute_loaders.rb
+- lib/serega/batch/auto_resolver.rb
+- lib/serega/batch/auto_resolver_factory.rb
+- lib/serega/batch/loader.rb
 - lib/serega/config.rb
 - lib/serega/errors.rb
 - lib/serega/helpers/serializer_class_helper.rb
@@ -41,24 +45,8 @@ 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/batch/batch.rb
-- lib/serega/plugins/batch/lib/batch_config.rb
-- lib/serega/plugins/batch/lib/loader.rb
-- lib/serega/plugins/batch/lib/loaders.rb
-- lib/serega/plugins/batch/lib/modules/attribute.rb
-- lib/serega/plugins/batch/lib/modules/attribute_normalizer.rb
-- lib/serega/plugins/batch/lib/modules/check_attribute_params.rb
-- lib/serega/plugins/batch/lib/modules/config.rb
-- lib/serega/plugins/batch/lib/modules/object_serializer.rb
-- lib/serega/plugins/batch/lib/modules/plan_point.rb
-- lib/serega/plugins/batch/lib/plugins_extensions/activerecord_preloads.rb
-- lib/serega/plugins/batch/lib/plugins_extensions/formatters.rb
-- lib/serega/plugins/batch/lib/plugins_extensions/if.rb
-- lib/serega/plugins/batch/lib/plugins_extensions/preloads.rb
-- lib/serega/plugins/batch/lib/validations/check_batch_opt_id_method.rb
-- lib/serega/plugins/batch/lib/validations/check_batch_opt_loader.rb
-- lib/serega/plugins/batch/lib/validations/check_opt_batch.rb
 - lib/serega/plugins/camel_case/camel_case.rb
 - lib/serega/plugins/context_metadata/context_metadata.rb
 - lib/serega/plugins/depth_limit/depth_limit.rb
@@ -79,42 +67,36 @@ files:
 - lib/serega/plugins/metadata/validations/check_opt_value.rb
 - lib/serega/plugins/metadata/validations/check_opts.rb
 - lib/serega/plugins/metadata/validations/check_path.rb
-- lib/serega/plugins/preloads/lib/format_user_preloads.rb
-- lib/serega/plugins/preloads/lib/modules/attribute.rb
-- lib/serega/plugins/preloads/lib/modules/attribute_normalizer.rb
-- lib/serega/plugins/preloads/lib/modules/check_attribute_params.rb
-- lib/serega/plugins/preloads/lib/modules/config.rb
-- lib/serega/plugins/preloads/lib/modules/plan_point.rb
-- lib/serega/plugins/preloads/lib/preload_paths.rb
-- lib/serega/plugins/preloads/lib/preloads_config.rb
-- lib/serega/plugins/preloads/lib/preloads_constructor.rb
-- lib/serega/plugins/preloads/preloads.rb
-- lib/serega/plugins/preloads/validations/check_opt_preload.rb
-- lib/serega/plugins/preloads/validations/check_opt_preload_path.rb
 - lib/serega/plugins/presenter/presenter.rb
 - lib/serega/plugins/root/root.rb
 - lib/serega/plugins/string_modifiers/parse_string_modifiers.rb
 - 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/params_count.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
 - lib/serega/validations/attribute/check_name.rb
+- lib/serega/validations/attribute/check_opt_batch.rb
 - lib/serega/validations/attribute/check_opt_const.rb
 - lib/serega/validations/attribute/check_opt_delegate.rb
 - lib/serega/validations/attribute/check_opt_hide.rb
 - 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
+- lib/serega/validations/check_batch_loader_params.rb
 - lib/serega/validations/check_initiate_params.rb
 - lib/serega/validations/check_serialize_params.rb
 - lib/serega/validations/initiate/check_modifiers.rb
 - lib/serega/validations/utils/check_allowed_keys.rb
-- lib/serega/validations/utils/check_extra_keyword_arg.rb
 - lib/serega/validations/utils/check_opt_is_bool.rb
 - lib/serega/validations/utils/check_opt_is_hash.rb
 - lib/serega/validations/utils/check_opt_is_string_or_symbol.rb
@@ -126,7 +108,6 @@ metadata:
   source_code_uri: https://github.com/aglushkov/serega
   documentation_uri: https://www.rubydoc.info/gems/serega
   changelog_uri: https://github.com/aglushkov/serega/blob/master/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -141,8 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
-signing_key:
+rubygems_version: 3.7.1
 specification_version: 4
 summary: JSON Serializer
 test_files: []