serega 0.17.0 → 0.19.0

data/VERSION

@@ -1 +1 @@
-0.17.0
+0.19.0

data/lib/serega/attribute.rb

@@ -21,6 +21,10 @@ class Serega
       # @return [Boolean, nil] Attribute :many option
       attr_reader :many
 
+      # Attribute :default option
+      # @return [Object, nil] Attribute :default option
+      attr_reader :default
+
       # Attribute :hide option
       # @return [Boolean, nil] Attribute :hide option
       attr_reader :hide
@@ -108,9 +112,10 @@ class Serega
 
       def set_normalized_vars(normalizer)
         @name = normalizer.name
+        @many = normalizer.many
+        @default = normalizer.default
         @value_block = normalizer.value_block
         @hide = normalizer.hide
-        @many = normalizer.many
         @serializer = normalizer.serializer
       end
     end

data/lib/serega/attribute_normalizer.rb

@@ -86,6 +86,19 @@ class Serega
         @serializer = prepare_serializer
       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
+
       private
 
       def prepare_name
@@ -97,11 +110,14 @@ class Serega
       # - plugin :formatters (wraps resulted block in formatter block and formats :const values)
       #
       def prepare_value_block
-        prepare_init_block ||
+        value_block =
+          prepare_init_block ||
           prepare_value_option_block ||
           prepare_const_block ||
           prepare_delegate_block ||
           prepare_keyword_block
+
+        prepare_value_block_with_default(value_block)
       end
 
       #
@@ -158,6 +174,20 @@ class Serega
         end
       end
 
+      def prepare_value_block_with_default(callable)
+        default_value = default
+        return callable if default_value.nil?
+
+        proc { |obj, ctx|
+          res = callable.call(obj, ctx)
+          res.nil? ? default_value : res
+        }
+      end
+
+      def prepare_default
+        init_opts.fetch(:default) { many ? FROZEN_EMPTY_ARRAY : nil }
+      end
+
       def prepare_delegate_block
         delegate = init_opts[:delegate]
         return unless delegate

data/lib/serega/config.rb

@@ -15,7 +15,7 @@ class Serega
     DEFAULTS = {
       plugins: [],
       initiate_keys: %i[only with except check_initiate_params].freeze,
-      attribute_keys: %i[method value serializer many hide const delegate].freeze,
+      attribute_keys: %i[method value serializer many hide const delegate default].freeze,
       serialize_keys: %i[context many].freeze,
       check_attribute_name: true,
       check_initiate_params: true,

data/lib/serega/object_serializer.rb

@@ -29,7 +29,7 @@ class Serega
       #
       # @param object [Object] Serialized object
       #
-      # @return [Hash, Array<Hash>] Serialized object(s)
+      # @return [Hash, Array<Hash>, nil] Serialized object(s)
       def serialize(object)
         return if object.nil?
 

data/lib/serega/plugins/batch/batch.rb

@@ -5,62 +5,17 @@ class Serega
     #
     # Plugin `:batch`
     #
-    # Adds ability to load nested attributes values in batches.
+    # Must be used to omit N+1 when loading attributes values.
     #
-    # It can be used to find value for attributes in optimal way:
-    # - load associations for multiple objects
-    # - load counters for multiple objects
-    # - make any heavy calculations for multiple objects only once
+    # @example Quick example
     #
-    # After including plugin, attributes gain new `:batch` option.
-    #
-    # `:batch` option must be a hash with this keys:
-    # - `key` (required) [Symbol, Proc, callable] - Defines current object identifier.
-    #   Later `loader` will accept array of `keys` to find `values`.
-    # - `loader` (required) [Symbol, Proc, callable] - Defines how to fetch values for
-    #   batch of keys. Receives 3 parameters: keys, context, plan_point.
-    # - `default` (optional) - Default value for attribute.
-    #   By default it is `nil` or `[]` when attribute has option `many: true`
-    #
-    # If `:loader` was defined using name (as Symbol) then batch loader must be
-    # defined in serializer config: `config.batch.define(:loader_name) { ... }` method.
-    #
-    # *Result of this `:loader` callable must be a **Hash** where*:
-    # - keys - provided keys
-    # - values - values for according keys
-    #
-    # `Batch` plugin can be defined with two specific attributes:
-    # - `auto_hide: true` - Marks attributes with defined :batch as hidden, so it
-    #   will not be serialized by default
-    # - `default_key: :id` - Set default object key (in this case :id) that will be used for all attributes with :batch option specified.
-    #
-    # This options (`auto_hide`, `default_key`) also can be set as config options in
-    # any nested serializer.
-    #
-    # @example
-    #   class PostSerializer < Serega
-    #     plugin :batch, auto_hide: true, default_key: :id
-    #
-    #     # Define batch loader via callable class, it must accept three args (keys, context, plan_point)
-    #     attribute :comments_count, batch: { loader: PostCommentsCountBatchLoader, default: 0}
-    #
-    #     # Define batch loader via Symbol, later we should define this loader via config.batch.define(:posts_comments_counter) { ... }
-    #     attribute :comments_count, batch: { loader: :posts_comments_counter, default: 0}
-    #
-    #     # Define batch loader with serializer
-    #     attribute :comments, serializer: CommentSerializer, batch: { loader: :posts_comments, default: []}
-    #
-    #     # Resulted block must return hash like { key => value(s) }
-    #     config.batch.define(:posts_comments_counter) do |keys|
-    #       Comment.group(:post_id).where(post_id: keys).count
-    #     end
+    #   class AppSerializer
+    #     plugin :batch, id_method: :id
+    #   end
     #
-    #     # We can return objects that will be automatically serialized if attribute defined with :serializer
-    #     # Parameter `context` can be used when loading batch
-    #     # Parameter `plan_point` can be used to find nested attributes that will be serialized (`plan_point.preloads`)
-    #     config.batch.define(:posts_comments) do |keys, context, plan_point|
-    #       Comment.where(post_id: keys).where(is_spam: false).group_by(&:post_id)
-    #     end
+    #   class UserSerializer < AppSerializer
+    #     attribute :comments_count, batch: { loader: CommentsCountBatchLoader }, default: 0
+    #     attribute :company, serializer: CompanySerializer, batch: { loader: UserCompanyBatchLoader }
     #   end
     #
     module Batch
@@ -88,7 +43,7 @@ class Serega
         require_relative "lib/modules/config"
         require_relative "lib/modules/object_serializer"
         require_relative "lib/modules/plan_point"
-        require_relative "lib/validations/check_batch_opt_key"
+        require_relative "lib/validations/check_batch_opt_id_method"
         require_relative "lib/validations/check_batch_opt_loader"
         require_relative "lib/validations/check_opt_batch"
 
@@ -138,9 +93,9 @@ class Serega
 
         config = serializer_class.config
         config.attribute_keys << :batch
-        config.opts[:batch] = {loaders: {}, default_key: nil, auto_hide: false}
+        config.opts[:batch] = {loaders: {}, id_method: nil, auto_hide: false}
         config.batch.auto_hide = opts[:auto_hide] if opts.key?(:auto_hide)
-        config.batch.default_key = opts[:default_key] if opts.key?(:default_key)
+        config.batch.id_method = opts[:id_method] if opts.key?(:id_method)
       end
 
       #

data/lib/serega/plugins/batch/lib/batch_config.rb

@@ -17,8 +17,8 @@ class Serega
         # Defines batch loader
         #
         # @param loader_name [Symbol] Batch loader name, that is used when defining attribute with batch loader.
-        # @param block [Proc] Block that can accept 3 parameters - keys, context, plan_point
-        #   and returns hash where ids are keys and values are batch loaded objects/
+        # @param block [Proc] Block that can accept 3 parameters - ids, context, plan_point
+        #   and returns hash with ids as keys and values are batch loaded objects
         #
         # @return [void]
         #
@@ -32,7 +32,7 @@ class Serega
           params_count = SeregaUtils::ParamsCount.call(callable, max_count: 3)
 
           if params_count > 3
-            raise SeregaError, "Batch loader can have maximum 3 parameters (keys, context, plan)"
+            raise SeregaError, "Batch loader can have maximum 3 parameters (ids, context, plan)"
           end
 
           loaders[loader_name] = callable
@@ -44,16 +44,6 @@ class Serega
           opts[:loaders]
         end
 
-        #
-        # Finds previously defined batch loader by name
-        #
-        # @param loader_name [Symbol]
-        #
-        # @return [Proc] batch loader block
-        def fetch_loader(loader_name)
-          loaders[loader_name] || (raise SeregaError, "Batch loader with name `#{loader_name.inspect}` was not defined. Define example: config.batch.define(:#{loader_name}) { |keys| ... }")
-        end
-
         # Shows option to auto hide attributes with :batch specified
         # @return [Boolean, nil] option value
         def auto_hide
@@ -67,17 +57,19 @@ class Serega
           opts[:auto_hide] = value
         end
 
-        # Shows default key for :batch option
-        # @return [Symbol, nil] default key for :batch option
-        def default_key
-          opts[:default_key]
+        # Shows method name or callable object needed to get object identifier for batch load
+        # @return [Symbol, #call, nil] Default method name or callable object to get identifier
+        def id_method
+          opts[:id_method]
         end
 
-        # @param value [Symbol] New :default_key option value
+        # Sets new identifier method name or callable value needed for batch loading
+        #
+        # @param value [Symbol, #call] New :id_method value
         # @return [Boolean] New option value
-        def default_key=(value)
-          raise SeregaError, "Must be a Symbol, #{value.inspect} provided" unless value.is_a?(Symbol)
-          opts[:default_key] = value
+        def id_method=(value)
+          CheckBatchOptIdMethod.call(value)
+          opts[:id_method] = value
         end
       end
     end

data/lib/serega/plugins/batch/lib/modules/attribute_normalizer.rb

@@ -44,27 +44,25 @@ class Serega
 
           loader = prepare_batch_loader(batch[:loader])
 
-          key = batch[:key] || self.class.serializer_class.config.batch.default_key
-          key = prepare_batch_key(key)
+          id_method = batch[:id_method] || self.class.serializer_class.config.batch.id_method
+          id_method = prepare_batch_id_method(id_method)
 
-          default = batch.fetch(:default) { many ? FROZEN_EMPTY_ARRAY : nil }
-
-          {loader: loader, key: key, default: default}
+          {loader: loader, id_method: id_method, default: default}
         end
 
-        def prepare_batch_key(key)
-          return proc { |object| object.public_send(key) } if key.is_a?(Symbol)
+        def prepare_batch_id_method(id_method)
+          return proc { |object| object.public_send(id_method) } if id_method.is_a?(Symbol)
 
-          params_count = SeregaUtils::ParamsCount.call(key, max_count: 2)
+          params_count = SeregaUtils::ParamsCount.call(id_method, max_count: 2)
           case params_count
-          when 0 then proc { key.call }
-          when 1 then proc { |object| key.call(object) }
-          else key
+          when 0 then proc { id_method.call }
+          when 1 then proc { |object| id_method.call(object) }
+          else id_method
           end
         end
 
         def prepare_batch_loader(loader)
-          return loader if loader.is_a?(Symbol)
+          loader = self.class.serializer_class.config.batch.loaders.fetch(loader) if loader.is_a?(Symbol)
 
           params_count = SeregaUtils::ParamsCount.call(loader, max_count: 3)
           case params_count

data/lib/serega/plugins/batch/lib/modules/object_serializer.rb

@@ -19,8 +19,8 @@ class Serega
         end
 
         def remember_key_for_batch_loading(batch, object, point, container)
-          key = batch[:key].call(object, context)
-          batch_loader(point).remember(key, container)
+          id = batch[:id_method].call(object, context)
+          batch_loader(point).remember(id, container)
           container[point.name] = nil # Reserve attribute place in resulted hash. We will set correct value later
         end
 

data/lib/serega/plugins/batch/lib/modules/plan_point.rb

@@ -13,25 +13,8 @@ class Serega
         # Returns attribute :batch option with prepared loader
         # @return [Hash] attribute :batch option
         #
-        attr_reader :batch
-
-        private
-
-        def set_normalized_vars
-          super
-          @batch = prepare_batch
-        end
-
-        def prepare_batch
-          batch = attribute.batch
-          if batch
-            loader = batch[:loader]
-            if loader.is_a?(Symbol)
-              batch_config = attribute.class.serializer_class.config.batch
-              batch[:loader] = batch_config.fetch_loader(loader)
-            end
-          end
-          batch
+        def batch
+          attribute.batch
         end
       end
     end

data/lib/serega/plugins/batch/lib/validations/check_batch_opt_id_method.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Batch
+      #
+      # Validator for option :id_method in attribute :batch option
+      #
+      class CheckBatchOptIdMethod
+        class << self
+          #
+          # Checks option :id_method of attribute :batch option
+          #
+          # @param id [nil, #call] Attribute :batch option :id_method
+          #
+          # @raise [SeregaError] validation error
+          #
+          # @return [void]
+          #
+          def call(id)
+            return if id.is_a?(Symbol)
+
+            raise SeregaError, must_be_callable unless id.respond_to?(:call)
+
+            SeregaValidations::Utils::CheckExtraKeywordArg.call(id, "batch option :id_method")
+            params_count = SeregaUtils::ParamsCount.call(id, max_count: 2)
+            raise SeregaError, params_count_error if params_count > 2
+          end
+
+          private
+
+          def params_count_error
+            "Invalid :batch option :id_method. It can accept maximum 2 parameters (object, context)"
+          end
+
+          def must_be_callable
+            "Invalid :batch option :id_method. It must be a Symbol, a Proc or respond to #call"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/batch/lib/validations/check_batch_opt_loader.rb

@@ -17,9 +17,27 @@ class Serega
           #
           # @return [void]
           #
-          def call(loader)
-            return if loader.is_a?(Symbol)
+          def call(loader, serializer_class)
+            if loader.is_a?(Symbol)
+              check_symbol(loader, serializer_class)
+            else
+              check_callable(loader)
+            end
+          end
+
+          private
+
+          def check_symbol(loader_name, serializer_class)
+            defined_loaders = serializer_class.config.batch.loaders
+            return if defined_loaders[loader_name]
 
+            raise SeregaError, <<~ERR.strip
+              Please define loader before adding it to attribute.
+                Example: `config.batch.define(:#{loader_name}) { |ids| ... }`
+            ERR
+          end
+
+          def check_callable(loader)
             raise SeregaError, must_be_callable unless loader.respond_to?(:call)
 
             SeregaValidations::Utils::CheckExtraKeywordArg.call(loader, ":batch option :loader")
@@ -27,10 +45,8 @@ class Serega
             raise SeregaError, params_count_error if params_count > 3
           end
 
-          private
-
           def params_count_error
-            "Invalid :batch option :loader. It can accept maximum 3 parameters (keys, context, plan)"
+            "Invalid :batch option :loader. It can accept maximum 3 parameters (ids, context, plan)"
           end
 
           def must_be_callable

data/lib/serega/plugins/batch/lib/validations/check_opt_batch.rb

@@ -23,30 +23,29 @@ class Serega
             SeregaValidations::Utils::CheckOptIsHash.call(opts, :batch)
 
             batch = opts[:batch]
-            SeregaValidations::Utils::CheckAllowedKeys.call(batch, %i[key loader default], :batch)
-
-            check_batch_opt_key(batch, serializer_class)
-            check_batch_opt_loader(batch)
+            SeregaValidations::Utils::CheckAllowedKeys.call(batch, %i[id_method loader], :batch)
 
+            check_batch_opt_id_method(batch, serializer_class)
+            check_batch_opt_loader(batch, serializer_class)
             check_usage_with_other_params(opts, block)
           end
 
           private
 
-          def check_batch_opt_key(batch, serializer_class)
-            return if !batch.key?(:key) && serializer_class.config.batch.default_key
+          def check_batch_opt_id_method(batch, serializer_class)
+            return if !batch.key?(:id_method) && serializer_class.config.batch.id_method
 
-            key = batch[:key]
-            raise SeregaError, "Option :key must present inside :batch option" unless key
+            id_method = batch[:id_method]
+            raise SeregaError, "Option :id_method must present inside :batch option" unless id_method
 
-            CheckBatchOptKey.call(key)
+            CheckBatchOptIdMethod.call(id_method)
           end
 
-          def check_batch_opt_loader(batch)
+          def check_batch_opt_loader(batch, serializer_class)
             loader = batch[:loader]
             raise SeregaError, "Option :loader must present inside :batch option" unless loader
 
-            CheckBatchOptLoader.call(loader)
+            CheckBatchOptLoader.call(loader, serializer_class)
           end
 
           def check_usage_with_other_params(opts, block)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Andrey Glushkov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-03 00:00:00.000000000 Z
+date: 2023-12-17 00:00:00.000000000 Z
 dependencies: []
 description: |
   JSON Serializer
@@ -55,7 +55,7 @@ files:
 - 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/preloads.rb
-- lib/serega/plugins/batch/lib/validations/check_batch_opt_key.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
@@ -140,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.21
+rubygems_version: 3.4.22
 signing_key:
 specification_version: 4
 summary: JSON Serializer

data/lib/serega/plugins/batch/lib/validations/check_batch_opt_key.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaPlugins
-    module Batch
-      #
-      # Validator for option :key in attribute :batch option
-      #
-      class CheckBatchOptKey
-        class << self
-          #
-          # Checks option :key of attribute :batch option
-          #
-          # @param key [nil, #call] Attribute :batch option :key
-          #
-          # @raise [SeregaError] validation error
-          #
-          # @return [void]
-          #
-          def call(key)
-            return if key.is_a?(Symbol)
-
-            raise SeregaError, must_be_callable unless key.respond_to?(:call)
-
-            SeregaValidations::Utils::CheckExtraKeywordArg.call(key, "batch option :key")
-            params_count = SeregaUtils::ParamsCount.call(key, max_count: 2)
-            raise SeregaError, params_count_error if params_count > 2
-          end
-
-          private
-
-          def params_count_error
-            "Invalid :batch option :key. It can accept maximum 2 parameters (object, context)"
-          end
-
-          def must_be_callable
-            "Invalid :batch option :key. It must be a Symbol, a Proc or respond to :call"
-          end
-        end
-      end
-    end
-  end
-end