serega 0.6.1 → 0.7.0

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

@@ -3,8 +3,16 @@
 class Serega
   module SeregaPlugins
     module ActiverecordPreloads
+      # Handles preloads for different types of initial records
       class Preloader
-        module ClassMethods
+        class << self
+          # Preloads associations to records
+          #
+          # @param object [Object] record(s)
+          # @param preloads [Hash] associations names
+          #
+          # @return [Object] provided object with preloaded associations
+          #
           def preload(object, preloads)
             return object if object.nil? || (object.is_a?(Array) && object.empty?) || preloads.empty?
 
@@ -14,6 +22,7 @@ class Serega
             preload_handler.preload(object, preloads)
           end
 
+          # @return [Array] Registered preload adapters for different types of initial records
           def handlers
             @handlers ||= [
               ActiverecordRelation,
@@ -23,12 +32,19 @@ class Serega
             ].freeze
           end
         end
-
-        extend ClassMethods
       end
 
+      # Associations loader for prepared records
       class Loader
         # :nocov: We can check only one version of activerecord
+
+        # Preloads associations to records
+        #
+        # @param records [Array<ActiveRecord::Base>] records
+        # @param associations [Hash] associations names
+        #
+        # @return [void]
+        #
         def self.call(records, associations)
           if ActiveRecord::VERSION::MAJOR >= 7
             ActiveRecord::Associations::Preloader.new(records: records, associations: associations).call
@@ -39,75 +55,119 @@ class Serega
         # :nocov:
       end
 
+      # Preloader adapter for ActiveRecord object
       class ActiverecordObject
-        module ClassMethods
+        class << self
+          #
+          # Checks object is kind of ActiveRecord::Base
+          #
+          # @param object [Object] object
+          #
+          # @return [Boolean] whether object is kind of ActiveRecord::Base
           def fit?(object)
             object.is_a?(ActiveRecord::Base)
           end
 
-          def preload(object, preloads)
-            Loader.call([object], preloads)
-            object
+          #
+          # Preloads associations to ActiveRecord::Base record
+          #
+          # @param record [ActiveRecord::Base] record
+          #
+          # @return [Object] provided record with preloaded associations
+          def preload(record, preloads)
+            Loader.call([record], preloads)
+            record
           end
         end
-
-        extend ClassMethods
       end
 
+      # Preloader adapter for ActiveRecord::Relation
       class ActiverecordRelation
-        module ClassMethods
-          def fit?(objects)
-            objects.is_a?(ActiveRecord::Relation)
+        class << self
+          #
+          # Checks object is kind of ActiveRecord::Relation
+          #
+          # @param object [Object] object to check
+          #
+          # @return [Boolean] whether object is kind of ActiveRecord::Relation
+          def fit?(object)
+            object.is_a?(ActiveRecord::Relation)
           end
 
-          def preload(objects, preloads)
-            objects.load
-            Loader.call(objects.to_a, preloads)
-            objects
+          #
+          # Preloads associations to ActiveRecord::Relation
+          #
+          # @param scope [ActiveRecord::Relation] scope
+          #
+          # @return [ActiveRecord::Relation] provided scope with preloaded associations
+          def preload(scope, preloads)
+            scope.load
+            Loader.call(scope.to_a, preloads)
+            scope
           end
         end
-
-        extend ClassMethods
       end
 
+      # Preloader adapter for Array of ActiveRecord objects
       class ActiverecordArray
-        module ClassMethods
-          def fit?(objects)
-            objects.is_a?(Array) &&
-              ActiverecordObject.fit?(objects.first) &&
-              same_kind?(objects)
+        class << self
+          #
+          # Checks object is an array of ActiveRecord::Base objects
+          #
+          # @param object [Object] object
+          #
+          # @return [Boolean] whether object is an array with ActiveRecord objects (and all objects have same class)
+          def fit?(object)
+            object.is_a?(Array) &&
+              ActiverecordObject.fit?(object.first) &&
+              same_kind?(object)
           end
 
-          def preload(objects, preloads)
-            Loader.call(objects, preloads)
-            objects
+          #
+          # Preloads associations to array with ActiveRecord::Base objects
+          #
+          # @param records [Array<ActiveRecord::Base>] ActiveRecord records
+          #
+          # @return [Array<ActiveRecord::Base>] provided records with preloaded associations
+          def preload(records, preloads)
+            Loader.call(records, preloads)
+            records
           end
 
           private
 
-          def same_kind?(objects)
-            first_object_class = objects.first.class
-            objects.all? { |object| object.instance_of?(first_object_class) }
+          def same_kind?(records)
+            first_object_class = records.first.class
+            records.all? { |record| record.instance_of?(first_object_class) }
           end
         end
-
-        extend ClassMethods
       end
 
+      # Preloader adapter for Enumerator with ActiveRecord objects
       class ActiverecordEnumerator
-        module ClassMethods
-          def fit?(objects)
-            objects.is_a?(Enumerator) &&
-              ActiverecordArray.fit?(objects.to_a)
+        class << self
+          #
+          # Checks object is an Enumerator with each value is a ActiveRecord::Base object
+          #
+          # @param object [Object] object
+          #
+          # @return [Boolean] whether object is an Enumerator with each value is a ActiveRecord::Base object
+          def fit?(object)
+            object.is_a?(Enumerator) &&
+              ActiverecordArray.fit?(object.to_a)
           end
 
-          def preload(objects, preloads)
-            ActiverecordArray.preload(objects.to_a, preloads)
-            objects
+          #
+          # Preloads associations to Enumerator with ActiveRecord::Base objects
+          #
+          # @param enum [Enumerator<ActiveRecord::Base>] enum
+          #
+          # @return [Enumerator<ActiveRecord::Base>] provided enumerator with preloaded associations
+          def preload(enum, preloads)
+            ActiverecordArray.preload(enum.to_a, preloads)
+            enum
           end
         end
-
-        extend ClassMethods
       end
     end
   end

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

@@ -2,11 +2,52 @@
 
 class Serega
   module SeregaPlugins
+    #
+    # Plugin that can be used to load attributes values in batches.
+    #   Each batch loader accepts list of selected keys, context and current attribute point.
+    #   Each batch loader must return Hash with values grouped by provided keys.
+    #   There are specific `:default` option that can be used to add default value for missing key.
+    #
+    # @example
+    #   class PostSerializer < Serega
+    #     plugin :batch
+    #
+    #     # Define batch loader via callable class, it must accept three args (keys, context, map_point)
+    #     attribute :comments_count, batch: { key: :id, loader: PostCommentsCountBatchLoader, default: 0}
+    #
+    #     # Define batch loader via Symbol, later we should define this loader via config.batch_loaders.define(:posts_comments_counter) { ... }
+    #     attribute :comments_count, batch: { key: :id, loader: :posts_comments_counter, default: 0}
+    #
+    #     # Define batch loader with serializer
+    #     attribute :comments, serializer: CommentSerializer, batch: { key: :id, loader: :posts_comments, default: []}
+    #
+    #     # Resulted block must return hash like { key => value(s) }
+    #     config.batch_loaders.define(:posts_comments_counter) do |keys|
+    #       Comment.group(:post_id).where(post_id: keys).count
+    #     end
+    #
+    #     # We can return objects that will be automatically serialized if attribute defined with :serializer
+    #     # Parameter `context` can be used when loading batch
+    #     # Parameter `map_point` can be used to find nested attributes that will be serialized (`map_point.preloads`)
+    #     config.batch_loaders.define(:posts_comments) do |keys, context, map_point|
+    #       Comment.where(post_id: keys).where(is_spam: false).group_by(&:post_id)
+    #     end
+    #   end
+    #
     module Batch
+      # @return [Symbol] Plugin name
       def self.plugin_name
         :batch
       end
 
+      #
+      # Applies plugin code to specific serializer
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param _opts [Hash] Loaded plugins options
+      #
+      # @return [void]
+      #
       def self.load_plugin(serializer_class, **_opts)
         require_relative "./lib/loader"
         require_relative "./lib/loaders"
@@ -15,13 +56,21 @@ class Serega
         require_relative "./lib/validations/check_opt_batch"
 
         serializer_class.extend(ClassMethods)
+        serializer_class.include(InstanceMethods)
         serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
         serializer_class::SeregaAttribute.include(AttributeInstanceMethods)
         serializer_class::SeregaMapPoint.include(MapPointInstanceMethods)
-        serializer_class::SeregaSerializer.include(SeregaSerializerInstanceMethods)
         serializer_class::SeregaObjectSerializer.include(SeregaObjectSerializerInstanceMethods)
       end
 
+      #
+      # Runs callbacks after plugin was attached
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
       def self.after_load_plugin(serializer_class, **opts)
         config = serializer_class.config
         config.attribute_keys << :batch
@@ -47,6 +96,9 @@ class Serega
         end
       end
 
+      #
+      # Batch loader config
+      #
       class BatchLoadersConfig
         attr_reader :opts
 
@@ -54,6 +106,15 @@ class Serega
           @opts = opts
         end
 
+        #
+        # 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, map_point
+        #   and returns hash where ids are keys and values are batch loaded objects/
+        #
+        # @return [void]
+        #
         def define(loader_name, &block)
           unless block
             raise SeregaError, "Block must be given to batch_loaders.define method"
@@ -67,20 +128,38 @@ class Serega
           opts[loader_name] = block
         end
 
+        #
+        # Finds previously defined batch loader by name
+        #
+        # @param loader_name [Symbol]
+        #
+        # @return [Proc] batch loader block
         def fetch(loader_name)
           opts[loader_name] || (raise SeregaError, "Batch loader with name `#{loader_name.inspect}` was not defined. Define example: config.batch_loaders.define(:#{loader_name}) { |keys, ctx, points| ... }")
         end
       end
 
+      #
+      # Stores batch config for specific attribute
+      #
       class BatchModel
         attr_reader :opts, :loaders, :many
 
+        #
+        # Initializes batch model
+        #
+        # @param opts [Hash] Attribute :batch option
+        # @param loaders [Array] Array of all loaders defined in serialize class
+        # @param many [Boolean] Option :many, defined on attribute
+        #
+        # @return [void]
         def initialize(opts, loaders, many)
           @opts = opts
           @loaders = loaders
           @many = many
         end
 
+        # @return [#call] batch loader
         def loader
           @batch_loader ||= begin
             loader = opts[:loader]
@@ -89,6 +168,7 @@ class Serega
           end
         end
 
+        # @return [Object] key (uid) of batch loaded object
         def key
           @batch_key ||= begin
             key = opts[:key]
@@ -96,6 +176,7 @@ class Serega
           end
         end
 
+        # @return [Object] default value for missing key
         def default_value
           if opts.key?(:default)
             opts[:default]
@@ -105,12 +186,25 @@ class Serega
         end
       end
 
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
       module ConfigInstanceMethods
+        #
+        # @return [Serega::SeregaPlugins::Batch::BatchLoadersConfig] configuration for batch loaders
+        #
         def batch_loaders
           @batch_loaders ||= BatchLoadersConfig.new(opts.fetch(:batch).fetch(:loaders))
         end
       end
 
+      #
+      # Serega class additional/patched class methods
+      #
+      # @see Serega::SeregaConfig
+      #
       module ClassMethods
         private
 
@@ -127,7 +221,14 @@ class Serega
         end
       end
 
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
       module CheckAttributeParamsInstanceMethods
+        private
+
         def check_opts
           super
 
@@ -135,13 +236,29 @@ class Serega
         end
       end
 
+      #
+      # Serega::SeregaAttribute additional/patched class methods
+      #
+      # @see Serega::SeregaAttribute
+      #
       module AttributeInstanceMethods
+        #
+        # @return [nil, Hash] :batch option
+        #
         def batch
           opts[:batch]
         end
       end
 
+      #
+      # Serega::SeregaMapPoint additional/patched class methods
+      #
+      # @see Serega::SeregaAttribute
+      #
       module MapPointInstanceMethods
+        #
+        # @return [Serega::Batch::BatchModel] batch model that encapsulates everything needed to load current batch
+        #
         def batch
           return @batch if instance_variable_defined?(:@batch)
 
@@ -152,21 +269,30 @@ class Serega
         end
       end
 
-      module SeregaSerializerInstanceMethods
-        def initialize(**_args)
-          super
-          opts[:batch_loaders] = self.class.serializer_class::SeregaBatchLoaders.new
-        end
+      #
+      # Serega additional/patched instance methods
+      #
+      # @see Serega
+      #
+      module InstanceMethods
+        private
 
-        def serialize(*)
+        #
+        # Loads batch loaded attributes after serialization
+        #
+        def serialize(object, opts)
+          batch_loaders = opts[:batch_loaders] = self.class::SeregaBatchLoaders.new
           result = super
-
-          opts[:batch_loaders].load_all
-
+          batch_loaders.load_all
           result
         end
       end
 
+      #
+      # SeregaObjectSerializer additional/patched class methods
+      #
+      # @see Serega::SeregaObjectSerializer
+      #
       module SeregaObjectSerializerInstanceMethods
         private
 

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

@@ -3,19 +3,51 @@
 class Serega
   module SeregaPlugins
     module Batch
+      #
+      # Encapsulates point and according object_serializer
+      #   so we can put batch loaded values to this serializer response
+      #
       class SeregaBatchLoader
+        #
+        # Batch Loader instance methods
+        #
         module InstanceMethods
-          attr_reader :object_serializer, :point
+          # @return [Serega::SeregaMapPoint]
+          attr_reader :point
 
+          # @return [Serega::SeregaObjectSerializer]
+          attr_reader :object_serializer
+
+          #
+          # Initializes new SeregaBatchLoader
+          #
+          # @param object_serializer [Serega::SeregaObjectSerializer]
+          # @param point [Serega::SeregaMapPoint]
+          #
+          # @return [Serega::SeregaPlugins::Batch::SeregaBatchLoader]
+          #
           def initialize(object_serializer, point)
             @object_serializer = object_serializer
             @point = point
           end
 
+          #
+          # Remembers key and hash container where value for this key must be inserted
+          #
+          # @param key [Object] key that identifies batch loaded objects
+          # @param container [Hash] container where batch loaded objects must be attached
+          #
+          # @return [void]
+          #
           def remember(key, container)
             (keys[key] ||= []) << container
           end
 
+          #
+          # Loads this batch and assigns values to remembered containers
+          #
+          # @return [void]
+          #
           def load
             keys_values = keys_values()
 

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

@@ -3,12 +3,25 @@
 class Serega
   module SeregaPlugins
     module Batch
+      # Lists batch loaders registered during serialization
       class SeregaBatchLoaders
+        # BatchLoaders instance methods
         module InstanceMethods
-          def get(point, object_serializer)
-            batch_loaders[point] ||= self.class.serializer_class::SeregaBatchLoader.new(object_serializer, point)
+          #
+          # Initializes or fetches already initialized batch loader
+          #
+          # @param map_point [Serega::SeregaMapPoint] current map point
+          # @param object_serializer[Serega::SeregaObjectSerializer] current object serializer
+          #
+          # @return [Serega::SeregaPlugins::Batch::SeregaBatchLoader] Batch Loader
+          #
+          def get(map_point, object_serializer)
+            batch_loaders[map_point] ||= self.class.serializer_class::SeregaBatchLoader.new(object_serializer, map_point)
           end
 
+          #
+          # Loads all registered batches and removes them from registered list
+          #
           def load_all
             return unless defined?(@batch_loaders)
 

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

@@ -3,9 +3,21 @@
 class Serega
   module SeregaPlugins
     module Batch
+      # Extensions (mini-plugins) that are enabled when Batch plugin used with other plugins
       module PluginsExtensions
+        #
+        # Extension that is used when batch plugin used with :active_record_preloads plugin
+        #
         module ActiveRecordPreloads
+          #
+          # BatchLoader additional/patched instance methods
+          #
+          # @see Serega::SeregaPlugins::Batch::SeregaBatchLoader
+          #
           module BatchLoaderInstanceMethods
+            private
+
+            # Preloads required associations to batch-loaded records
             def keys_values(*)
               data = super
 
@@ -21,13 +33,23 @@ class Serega
           end
         end
 
+        #
+        # Extension that is used when batch plugin used with :formatters plugin
+        #
         module Formatters
+          #
+          # BatchLoader additional/patched instance methods
+          #
+          # @see Serega::SeregaPlugins::Batch::SeregaBatchLoader
+          #
           module BatchLoaderInstanceMethods
+            private
+
             # Format values after they are prepared
             def keys_values(*)
               data = super
 
-              formatter = point.attribute.formatter_resolved
+              formatter = point.attribute.formatter
               data.transform_values! { |value| formatter.call(value) } if formatter
 
               data

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

@@ -3,8 +3,20 @@
 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)
 

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

@@ -3,8 +3,20 @@
 class Serega
   module SeregaPlugins
     module Batch
+      #
+      # Validator for option :loader in attribute :batch option
+      #
       class CheckBatchOptLoader
         class << self
+          #
+          # Checks option :loader of attribute :batch option
+          #
+          # @param loader [nil, #call] Attribute :batch option :loader
+          #
+          # @raise [SeregaError] validation error
+          #
+          # @return [void]
+          #
           def call(loader)
             return if loader.is_a?(Symbol)
 

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

@@ -3,8 +3,20 @@
 class Serega
   module SeregaPlugins
     module Batch
+      #
+      # Attribute `:batch` option validator
+      #
       class CheckOptBatch
         class << self
+          #
+          # Checks attribute :batch  option
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
           def call(opts, block)
             return unless opts.key?(:batch)