serega 0.6.1 → 0.7.0

data/lib/serega/plugins/preloads/lib/enum_deep_freeze.rb

@@ -3,9 +3,18 @@
 class Serega
   module SeregaPlugins
     module Preloads
-      # Freezes nested enumerable data
+      #
+      # Utility to freeze nested hashes and arrays
+      #
       class EnumDeepFreeze
         class << self
+          #
+          # Freezes nested enumerable data
+          #
+          # @param data[Hash, Array] data to freeze
+          #
+          # @return [Hash, Array] same deeply frozen data
+          #
           def call(data)
             data.each_entry { |entry| call(entry) } if data.is_a?(Enumerable)
             data.freeze

data/lib/serega/plugins/preloads/lib/format_user_preloads.rb

@@ -3,7 +3,9 @@
 class Serega
   module SeregaPlugins
     module Preloads
-      # Transforms user provided preloads to hash
+      #
+      # Utility that helps to transform user provided preloads to hash
+      #
       class FormatUserPreloads
         METHODS = {
           Array => :array_to_hash,
@@ -14,7 +16,16 @@ class Serega
           Symbol => :symbol_to_hash
         }.freeze
 
-        module ClassMethods
+        private_constant :METHODS
+
+        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)
             send(METHODS.fetch(value.class), value)
           end
@@ -45,8 +56,6 @@ class Serega
             {value => {}}
           end
         end
-
-        extend ClassMethods
       end
     end
   end

data/lib/serega/plugins/preloads/lib/main_preload_path.rb

@@ -3,9 +3,24 @@
 class Serega
   module SeregaPlugins
     module Preloads
+      #
+      # Class that constructs main preloads path.
+      #
+      # When we have nested preloads we will use this path to dig to `main` element and
+      # assign nested preloads to it.
+      #
+      # By default its a path to latest provided preload
+      #
+      # @example
+      #  MainPreloadPath.(a: { b: { c: {} }, d: {} }) # => [:a, :d]
+      #
       class MainPreloadPath
-        module ClassMethods
+        class << self
+          # Finds default preload path
+          #
           # @param preloads [Hash] Formatted user provided preloads hash
+          #
+          # @return [Array<Symbol>] Preloads path to `main` element
           def call(preloads)
             return FROZEN_EMPTY_ARRAY if preloads.empty?
 
@@ -32,8 +47,6 @@ class Serega
             path
           end
         end
-
-        extend ClassMethods
       end
     end
   end

data/lib/serega/plugins/preloads/lib/preloads_constructor.rb

@@ -4,14 +4,14 @@ class Serega
   module SeregaPlugins
     module Preloads
       #
-      # Finds relations to preload for provided serializer
+      # Finds preloads for provided attributes map
       #
       class PreloadsConstructor
-        module ClassMethods
+        class << self
           #
-          # Constructs preloads hash for given serializer
+          # Constructs preloads hash for given attributes map
           #
-          # @param serializer [Serega] Instance of Serega serializer
+          # @param map [Array<Serega::MapPoint>] Serialization map
           #
           # @return [Hash]
           #
@@ -54,8 +54,6 @@ class Serega
             (!path || path.empty?) ? preloads : preloads.dig(*path)
           end
         end
-
-        extend ClassMethods
       end
     end
   end

data/lib/serega/plugins/preloads/preloads.rb

@@ -3,8 +3,59 @@
 class Serega
   module SeregaPlugins
     #
-    # Plugin adds `.preloads` method to find relations that must be preloaded
+    # Plugin `:preloads`
     #
+    # Allows to define `:preloads` to attributes and then allows to merge preloads
+    # from serialized attributes and return single associations hash.
+    #
+    # Plugin accepts options:
+    # - `auto_preload_attributes_with_delegate` - default false
+    # - `auto_preload_attributes_with_serializer` - default false
+    # - `auto_hide_attributes_with_preload` - default false
+    #
+    # This options are very handy if you want to forget about finding preloads manually.
+    #
+    # Preloads can be disabled with `preload: false` attribute option option.
+    # Also automatically added preloads can be overwritten with manually specified `preload: :another_value`.
+    #
+    # Some examples, **please read comments in the code below**
+    #
+    # @example
+    #   class AppSerializer < Serega
+    #     plugin :preloads,
+    #       auto_preload_attributes_with_delegate: true,
+    #       auto_preload_attributes_with_serializer: true,
+    #       auto_hide_attributes_with_preload: true
+    #   end
+    #
+    #   class UserSerializer < AppSerializer
+    #     # No preloads
+    #     attribute :username
+    #
+    #     # Specify `preload: :user_stats` manually
+    #     attribute :followers_count, preload: :user_stats, value: proc { |user| user.user_stats.followers_count }
+    #
+    #     # Automatically `preloads: :user_stats` as `auto_preload_attributes_with_delegate` option is true
+    #     attribute :comments_count, delegate: { to: :user_stats }
+    #
+    #     # Automatically `preloads: :albums` as `auto_preload_attributes_with_serializer` option is true
+    #     attribute :albums, serializer: 'AlbumSerializer'
+    #   end
+    #
+    #   class AlbumSerializer < AppSerializer
+    #     attribute :images_count, delegate: { to: :album_stats }
+    #   end
+    #
+    #   # By default preloads are empty, as we specify `auto_hide_attributes_with_preload = true`,
+    #   # and attributes with preloads will be not serialized
+    #   UserSerializer.new.preloads # => {}
+    #   UserSerializer.new.to_h(OpenStruct.new(username: 'foo')) # => {:username=>"foo"}
+    #
+    #   UserSerializer.new(with: :followers_count).preloads # => {:user_stats=>{}}
+    #   UserSerializer.new(with: %i[followers_count comments_count]).preloads # => {:user_stats=>{}}
+    #   UserSerializer.new(with: [:followers_count, :comments_count, { albums: :images_count }]).preloads # => {:user_stats=>{}, :albums=>{:album_stats=>{}}}
+    #
+
     module Preloads
       DEFAULT_CONFIG = {
         auto_preload_attributes_with_delegate: false,
@@ -12,24 +63,26 @@ class Serega
         auto_hide_attributes_with_preload: false
       }.freeze
 
-      # @return [Symbol] plugin name
+      private_constant :DEFAULT_CONFIG
+
+      # @return [Symbol] Plugin name
       def self.plugin_name
         :preloads
       end
 
       #
-      # Includes plugin modules to current serializer
+      # Applies plugin code to specific serializer
       #
-      # @param serializer_class [Class] current serializer class
-      # @param _opts [Hash] plugin opts
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param _opts [Hash] Loaded plugins options
       #
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
         serializer_class.include(InstanceMethods)
-        serializer_class::SeregaAttribute.include(AttributeMethods)
+        serializer_class::SeregaAttribute.include(AttributeInstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
-        serializer_class::SeregaMapPoint.include(MapPointMethods)
+        serializer_class::SeregaMapPoint.include(MapPointInstanceMethods)
 
         serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
 
@@ -41,6 +94,14 @@ class Serega
         require_relative "./validations/check_opt_preload_path"
       end
 
+      #
+      # Adds config options and runs other callbacks after plugin was loaded
+      #
+      # @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 << :preload << :preload_path
@@ -53,21 +114,57 @@ class Serega
         preloads_config.auto_hide_attributes_with_preload = preloads_opts[:auto_hide_attributes_with_preload]
       end
 
-      # Adds #preloads instance method
+      #
+      # Serega additional/patched instance methods
+      #
+      # @see Serega
+      #
       module InstanceMethods
-        # @return [Hash] relations that can be preloaded to omit N+1
+        # @return [Hash] merged preloads of all serialized attributes
         def preloads
           @preloads ||= PreloadsConstructor.call(map)
         end
       end
 
+      #
+      # Config for `preloads` plugin
+      #
       class PreloadsConfig
+        # @return [Hash] preloads plugin options
         attr_reader :opts
 
+        #
+        # Initializes context_metadata config object
+        #
+        # @param opts [Hash] options
+        #
+        # @return [Serega::SeregaPlugins::Metadata::MetadataConfig]
+        #
         def initialize(opts)
           @opts = opts
         end
 
+        # @!method auto_preload_attributes_with_delegate
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_preload_attributes_with_delegate=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
+        # @!method auto_preload_attributes_with_serializer
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_preload_attributes_with_serializer=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
+        # @!method auto_hide_attributes_with_preload
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_hide_attributes_with_preload=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
         %i[
           auto_preload_attributes_with_delegate
           auto_preload_attributes_with_serializer
@@ -84,26 +181,46 @@ class Serega
         end
       end
 
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
       module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::Preloads::PreloadsConfig] `preloads` plugin config
         def preloads
           @preloads ||= PreloadsConfig.new(opts.fetch(:preloads))
         end
       end
 
-      # Adds #preloads and #preloads_path Attribute instance method
-      module AttributeMethods
+      #
+      # Serega::SeregaAttribute additional/patched instance methods
+      #
+      # @see Serega::SeregaAttribute::AttributeInstanceMethods
+      #
+      module AttributeInstanceMethods
+        # @return [Hash,nil] formatted preloads of current attribute
         def preloads
           return @preloads if defined?(@preloads)
 
           @preloads = get_preloads
         end
 
+        # @return [Array] formatted preloads_path of current attribute
         def preloads_path
           return @preloads_path if defined?(@preloads_path)
 
           @preloads_path = get_preloads_path
         end
 
+        # Patch for original `hide` method
+        #
+        # Marks attribute hidden if auto_hide_attribute_with_preloads option was set and attribute has preloads
+        #
+        # @return [Boolean, nil] if attribute is hidden
+        #
+        # @see Serega::SeregaAttribute::AttributeInstanceMethods#hide
+        #
         def hide
           res = super
           return res unless res.nil?
@@ -143,16 +260,32 @@ class Serega
         end
       end
 
-      module MapPointMethods
+      #
+      # Serega::SeregaMapPoint additional/patched instance methods
+      #
+      # @see Serega::SeregaMapPoint::InstanceMethods
+      #
+      module MapPointInstanceMethods
+        #
+        # @return [Hash] preloads for nested attributes
+        #
         def preloads
           @preloads ||= PreloadsConstructor.call(nested_points)
         end
 
+        #
+        # @return [Array<Symbol>] preloads path for current attribute
+        #
         def preloads_path
           attribute.preloads_path
         end
       end
 
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
       module CheckAttributeParamsInstanceMethods
         private
 

data/lib/serega/plugins/preloads/validations/check_opt_preload.rb

@@ -3,8 +3,19 @@
 class Serega
   module SeregaPlugins
     module Preloads
+      #
+      # Validator for attribute :preload option
+      #
       class CheckOptPreload
         class << self
+          #
+          # Checks :preload option
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] validation error
+          #
+          # @return [void]
           def call(opts)
             return unless opts.key?(:preload)
 

data/lib/serega/plugins/preloads/validations/check_opt_preload_path.rb

@@ -3,8 +3,20 @@
 class Serega
   module SeregaPlugins
     module Preloads
+      #
+      # 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 unless opts.key?(:preload_path)
 

data/lib/serega/plugins/presenter/presenter.rb

@@ -20,13 +20,13 @@ class Serega
     #     end
     #   end
     module Presenter
-      # @return [Symbol] plugin name
+      # @return [Symbol] Plugin name
       def self.plugin_name
         :presenter
       end
 
       #
-      # Loads plugin
+      # Applies plugin code to specific serializer
       #
       # @param serializer_class [Class<Serega>] Current serializer class
       # @param _opts [Hash] Loaded plugins options
@@ -35,14 +35,14 @@ class Serega
       #
       def self.load_plugin(serializer_class, **_opts)
         serializer_class.extend(ClassMethods)
-        serializer_class::SeregaSerializer.include(SeregaSerializerInstanceMethods)
+        serializer_class::SeregaObjectSerializer.include(SeregaObjectSerializerInstanceMethods)
       end
 
       #
-      # Adds Presenter to current serializer
+      # Runs callbacks after plugin was attached
       #
       # @param serializer_class [Class<Serega>] Current serializer class
-      # @param _opts [Hash] Loaded plugins options
+      # @param _opts [Hash] loaded plugins opts
       #
       # @return [void]
       #
@@ -74,7 +74,11 @@ class Serega
         include InstanceMethods
       end
 
-      # Overrides class methods of included class
+      #
+      # Serega additional/patched class methods
+      #
+      # @see Serega
+      #
       module ClassMethods
         private def inherited(subclass)
           super
@@ -94,14 +98,19 @@ class Serega
         end
       end
 
-      # Includes methods to override SeregaSerializer class
-      module SeregaSerializerInstanceMethods
+      #
+      # SeregaObjectSerializer additional/patched class methods
+      #
+      # @see Serega::SeregaObjectSerializer
+      #
+      module SeregaObjectSerializerInstanceMethods
+        private
+
         #
         # Replaces serialized object with Presenter.new(object)
         #
-        def serialize(object)
-          presenter_class = points.first.class.serializer_class::Presenter
-          object = presenter_class.new(object)
+        def serialize_object(object)
+          object = self.class.serializer_class::Presenter.new(object)
           super
         end
       end