serega 0.6.1 → 0.7.0

data/lib/serega/plugins/context_metadata/context_metadata.rb

@@ -2,23 +2,66 @@
 
 class Serega
   module SeregaPlugins
+    #
+    # Plugin :context_metadata
+    #
+    # Depends on: `:root` plugin, that must be loaded first
+    #
+    # Allows to specify metadata to be added to serialized response.
+    #
+    # @example
+    #   class UserSerializer < Serega
+    #     plugin :root, root: :data
+    #     plugin :context_metadata, context_metadata_key: :meta
+    #   end
+    #
+    #   UserSerializer.to_h(nil, meta: { version: '1.0.1' })
+    #   # => {:data=>nil, :version=>"1.0.1"}
+    #
     module ContextMetadata
+      # Default context metadata option name
       DEFAULT_CONTEXT_METADATA_KEY = :meta
 
+      # @return [Symbol] Plugin name
       def self.plugin_name
         :context_metadata
       end
 
+      # Checks requirements and loads additional plugins
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
       def self.before_load_plugin(serializer_class, **opts)
-        serializer_class.plugin(:root, **opts) unless serializer_class.plugin_used?(:root)
+        unless serializer_class.plugin_used?(:root)
+          raise SeregaError, "Please load :root plugin first so we can wrap serialization response into top-level hash to add metadata there"
+        end
       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)
+        serializer_class.include(InstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
-        serializer_class::SeregaSerializer.include(SeregaSerializerInstanceMethods)
         serializer_class::CheckSerializeParams.include(CheckSerializeParamsInstanceMethods)
       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
         meta_key = opts[:context_metadata_key] || DEFAULT_CONTEXT_METADATA_KEY
@@ -26,29 +69,58 @@ class Serega
         config.serialize_keys << meta_key
       end
 
+      #
+      # Config for `context_metadata` plugin
+      #
       class ContextMetadataConfig
+        # @return [Hash] context_metadata options
         attr_reader :opts
 
+        #
+        # Initializes context_metadata config object
+        #
+        # @param opts [Hash] options
+        #
+        # @return [Serega::SeregaPlugins::ContextMetadata::ContextMetadataConfig]
         def initialize(opts)
           @opts = opts
         end
 
+        # Key that should be used to define metadata
         def key
           opts.fetch(:key)
         end
 
-        def key=(value)
-          opts[:key] = value
+        # Sets key that should be used to define metadata
+        #
+        # @param new_key [Symbol] New key
+        #
+        # @return [Symbol] New key
+        def key=(new_key)
+          opts[:key] = new_key
         end
       end
 
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
       module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::ContextMetadata::ContextMetadataConfig] context_metadata config
         def context_metadata
           @context_metadata ||= ContextMetadataConfig.new(opts.fetch(:context_metadata))
         end
       end
 
+      #
+      # CheckSerializeParams class additional/patched instance methods
+      #
+      # @see Serega::SeregaValidations::CheckSerializeParams
+      #
       module CheckSerializeParamsInstanceMethods
+        private
+
         def check_opts
           super
 
@@ -57,17 +129,27 @@ class Serega
         end
       end
 
-      module SeregaSerializerInstanceMethods
-        def serialize(object)
-          super.tap do |hash|
-            add_context_metadata(hash)
-          end
-        end
-
+      #
+      # Serega additional/patched instance methods
+      #
+      # @see Serega
+      #
+      module InstanceMethods
         private
 
-        def add_context_metadata(hash)
-          context_metadata_key = self.class.serializer_class.config.context_metadata.key
+        def serialize(object, opts)
+          result = super
+          return result unless result.is_a?(Hash) # return earlier if not a hash, so no root was added
+
+          root = build_root(object, opts)
+          return result unless root # return earlier when no root
+
+          add_context_metadata(result, opts)
+          result
+        end
+
+        def add_context_metadata(hash, opts)
+          context_metadata_key = self.class.config.context_metadata.key
           return unless context_metadata_key
 
           metadata = opts[context_metadata_key]

data/lib/serega/plugins/formatters/formatters.rb

@@ -2,22 +2,82 @@
 
 class Serega
   module SeregaPlugins
+    #
+    # Plugin :formatters
+    #
+    # Allows to define value formatters one time and apply them on any attributes.
+    #
+    # Config option `config.formatters.add()` can be used to add formatters.
+    #
+    # Attribute option `:format` now can be used with name of formatter or with callable instance.
+    #
+    # @example
+    #   class AppSerializer < Serega
+    #     plugin :formatters, formatters: {
+    #       iso8601: ->(value) { time.iso8601.round(6) },
+    #       on_off: ->(value) { value ? 'ON' : 'OFF' },
+    #       money: ->(value) { value.round(2) }
+    #     }
+    #   end
+    #
+    #   class UserSerializer < Serega
+    #     # Additionally we can add formatters via config in subclasses
+    #     config.formatters.add(
+    #       iso8601: ->(value) { time.iso8601.round(6) },
+    #       on_off: ->(value) { value ? 'ON' : 'OFF' },
+    #       money: ->(value) { value.round(2) }
+    #     )
+    #
+    #     # Using predefined formatter
+    #     attribute :commission, format: :money
+    #     attribute :is_logined, format: :on_off
+    #     attribute :created_at, format: :iso8601
+    #     attribute :updated_at, format: :iso8601
+    #
+    #     # Using `callable` formatter
+    #     attribute :score_percent, format: proc { |percent| "#{percent.round(2)}%" }
+    #   end
+    #
     module Formatters
+      # @return [Symbol] Plugin name
       def self.plugin_name
         :formatters
       end
 
+      # Checks requirements and loads additional plugins
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
       def self.before_load_plugin(serializer_class, **opts)
         if serializer_class.plugin_used?(:batch)
           raise SeregaError, "Plugin `formatters` must be loaded before `batch`"
         end
       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)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
         serializer_class::SeregaAttribute.include(AttributeInstanceMethods)
       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.opts[:formatters] = {}
@@ -25,13 +85,26 @@ class Serega
         config.attribute_keys << :format
       end
 
+      # Formatters plugin config
       class FormattersConfig
         attr_reader :opts
 
+        #
+        # Initializes formatters config object
+        #
+        # @param opts [Hash] options
+        #
+        # @return FormattersConfig
         def initialize(opts)
           @opts = opts
         end
 
+        # Adds new formatters
+        #
+        # @param formatters [Hash<Symbol, #call>] hash key is a formatter name and
+        #   hash value is a callable instance to format value
+        #
+        # @return [void]
         def add(formatters)
           formatters.each_pair do |key, value|
             opts[key] = value
@@ -39,27 +112,32 @@ class Serega
         end
       end
 
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
       module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::Formatters::FormattersConfig] current formatters config
         def formatters
           @formatters ||= FormattersConfig.new(opts.fetch(:formatters))
         end
       end
 
+      #
+      # Attribute class additional/patched instance methods
+      #
+      # @see Serega::SeregaAttribute
+      #
       module AttributeInstanceMethods
+        # @return [#call] callable formatter
         def formatter
           return @formatter if instance_variable_defined?(:@formatter)
 
           @formatter = formatter_resolved
         end
 
-        def formatter_resolved
-          formatter = opts[:format]
-          return unless formatter
-
-          formatter = self.class.serializer_class.config.formatters.opts.fetch(formatter) if formatter.is_a?(Symbol)
-          formatter
-        end
-
+        # @return [#call] callable, that should be used to fetch attribute value
         def value_block
           return @value_block if instance_variable_defined?(:@value_block)
           return @value_block = super unless formatter
@@ -77,6 +155,14 @@ class Serega
 
         private
 
+        def formatter_resolved
+          formatter = opts[:format]
+          return unless formatter
+
+          formatter = self.class.serializer_class.config.formatters.opts.fetch(formatter) if formatter.is_a?(Symbol)
+          formatter
+        end
+
         def formatted_block(formatter, original_block)
           proc do |object, context|
             value = original_block.call(object, context)

data/lib/serega/plugins/hide_nil/hide_nil.rb

@@ -7,36 +7,54 @@ class Serega
     # if value is nil
     #
     module HideNil
-      # @return [Symbol] plugin name
+      # @return [Symbol] Plugin name
       def self.plugin_name
         :hide_nil
       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::SeregaAttribute.include(AttributeMethods)
+        serializer_class::SeregaAttribute.include(AttributeInstanceMethods)
         serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
         serializer_class::SeregaObjectSerializer.include(SeregaObjectSerializerInstanceMethods)
       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)
         serializer_class.config.attribute_keys << :hide_nil
       end
 
-      # Adds #hide_nil? Attribute instance method
-      module AttributeMethods
+      #
+      # Serega::SeregaAttribute additional/patched instance methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
+      module AttributeInstanceMethods
+        # Check hide_nil is specified
         def hide_nil?
           !!opts[:hide_nil]
         end
       end
 
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
       module CheckAttributeParamsInstanceMethods
         private
 
@@ -46,6 +64,9 @@ class Serega
         end
       end
 
+      #
+      # Validator class for :hide_nil attribute option
+      #
       class CheckOptHideNil
         #
         # Checks attribute :hide_nil option
@@ -66,6 +87,11 @@ class Serega
         end
       end
 
+      #
+      # SeregaObjectSerializer additional/patched class methods
+      #
+      # @see Serega::SeregaObjectSerializer
+      #
       module SeregaObjectSerializerInstanceMethods
         private
 

data/lib/serega/plugins/metadata/metadata.rb

@@ -2,25 +2,65 @@
 
 class Serega
   module SeregaPlugins
+    #
+    # Plugin `:metadata`
+    #
+    # Depends on: `:root` plugin, that must be loaded first
+    #
+    # Adds ability to describe metadata that must be added to serialized response
+    #
+    # Added class-level method `:meta_attribute`, to define metadata, it accepts:
+    # - *path [Array<Symbol>] - nested hash keys beginning from the root object.
+    # - **options [Hash] - defaults are `hide_nil: false, hide_empty: false`
+    # - &block [Proc] - describes value for current meta attribute
+    #
+    # @example
+    #  class AppSerializer < Serega
+    #    plugin :root
+    #    plugin :metadata
+    #
+    #    meta_attribute(:version) { '1.2.3' }
+    #    meta_attribute(:ab_tests, :names) { %i[foo bar] }
+    #    meta_attribute(:meta, :paging, hide_nil: true) do |records, ctx|
+    #      next unless records.respond_to?(:total_count)
+    #
+    #      { page: records.page, per_page: records.per_page, total_count: records.total_count }
+    #    end
+    #  end
+    #
+    #  AppSerializer.to_h(nil) # => {:data=>nil, :version=>"1.2.3", :ab_tests=>{:names=>[:foo, :bar]}}
+    #
     module Metadata
+      # @return [Symbol] Plugin name
       def self.plugin_name
         :metadata
       end
 
-      def self.before_load_plugin(serializer_class, **opts)
-        if serializer_class.plugin_used?(:root)
-          root = serializer_class.config.root
-          root.one = opts[:root_one] if opts.key?(:root_one)
-          root.many = opts[:root_many] if opts.key?(:root_many)
-        else
-          serializer_class.plugin(:root, **opts)
+      # Checks requirements and loads additional plugins
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param _opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
+      def self.before_load_plugin(serializer_class, **_opts)
+        unless serializer_class.plugin_used?(:root)
+          raise SeregaError, "Please load :root plugin first so we can wrap serialization response into top-level hash to add metadata there"
         end
       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)
         serializer_class.extend(ClassMethods)
+        serializer_class.include(InstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
-        serializer_class::SeregaSerializer.include(SeregaSerializerInstanceMethods)
 
         require_relative "./meta_attribute"
         require_relative "./validations/check_block"
@@ -34,28 +74,61 @@ class Serega
         serializer_class.const_set(:MetaAttribute, meta_attribute_class)
       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)
         serializer_class.config.opts[:metadata] = {attribute_keys: %i[path hide_nil hide_empty]}
       end
 
+      #
+      # Config for `metadata` plugin
+      #
       class MetadataConfig
+        # @return [Hash] metadata options
         attr_reader :opts
 
+        #
+        # Initializes context_metadata config object
+        #
+        # @param opts [Hash] options
+        #
+        # @return [Serega::SeregaPlugins::Metadata::MetadataConfig]
+        #
         def initialize(opts)
           @opts = opts
         end
 
+        #
+        # Returns allowed metadata attribute keys
+        #
         def attribute_keys
           opts.fetch(:attribute_keys)
         end
       end
 
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
       module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::Metadata::MetadataConfig] metadata config
         def metadata
           @metadata ||= MetadataConfig.new(opts.fetch(:metadata))
         end
       end
 
+      #
+      # Serega class additional/patched class methods
+      #
+      # @see Serega::SeregaConfig
+      #
       module ClassMethods
         private def inherited(subclass)
           super
@@ -73,30 +146,20 @@ class Serega
         #
         # List of added metadata attributes
         #
-        # @return [Array] Added metadata attributes
+        # @return [Hash<Symbol => Serega::SeregaPlugins::Metadata::MetaAttribute>] Added metadata attributes
         #
         def meta_attributes
           @meta_attributes ||= {}
         end
 
         #
-        # Adds metadata to response
-        #
-        # @example
-        #   class AppSerializer < Serega
-        #
-        #     meta_attribute(:version) { '1.2.3' }
+        # Define metadata attribute
         #
-        #     meta_attribute(:meta, :paging, hide_nil: true, hide_empty: true) do |scope, ctx|
-        #       { page: scope.page, per_page: scope.per_page, total_count: scope.total_count }
-        #     end
-        #   end
+        # @param path [String, Symbol] Metadata attribute path keys
+        # @param opts [Hash] Metadata attribute options
+        # @param block [Proc] Block to fetch metadata attribute value
         #
-        # @param *path [Array<String, Symbol>] Metadata attribute path keys
-        # @param **opts [Hash] Metadata attribute options
-        # @param &block [Proc] Metadata attribute value
-        #
-        # @return [MetadataAttribute] Added metadata attribute
+        # @return [Serega::SeregaPlugins::Metadata::MetaAttribute] Added metadata attribute
         #
         def meta_attribute(*path, **opts, &block)
           attribute = self::MetaAttribute.new(path: path, opts: opts, block: block)
@@ -104,25 +167,35 @@ class Serega
         end
       end
 
-      module SeregaSerializerInstanceMethods
-        def serialize(object)
-          super.tap do |hash|
-            add_metadata(object, hash)
-          end
-        end
-
+      #
+      # Serega additional/patched instance methods
+      #
+      # @see Serega
+      #
+      module InstanceMethods
         private
 
-        def add_metadata(object, hash)
-          self.class.serializer_class.meta_attributes.each_value do |meta_attribute|
-            metadata = meta_attribute_value(object, meta_attribute)
+        def serialize(object, opts)
+          result = super
+          return result unless result.is_a?(Hash) # return earlier if not a hash, so no root was added
+
+          root = build_root(object, opts)
+          return result unless root # return earlier when no root
+
+          add_metadata(object, opts[:context], result)
+          result
+        end
+
+        def add_metadata(object, context, hash)
+          self.class.meta_attributes.each_value do |meta_attribute|
+            metadata = meta_attribute_value(object, context, meta_attribute)
             next unless metadata
 
             deep_merge_metadata(hash, metadata)
           end
         end
 
-        def meta_attribute_value(object, meta_attribute)
+        def meta_attribute_value(object, context, meta_attribute)
           value = meta_attribute.value(object, context)
           return if meta_attribute.hide?(value)
 

data/lib/serega/plugins/metadata/validations/check_block.rb

@@ -4,6 +4,9 @@ class Serega
   module SeregaPlugins
     module Metadata
       class MetaAttribute
+        #
+        # Validator for meta_attribute block parameter
+        #
         class CheckBlock
           ALLOWED_PARAM_TYPES = %i[opt req]
           private_constant :ALLOWED_PARAM_TYPES

data/lib/serega/plugins/metadata/validations/check_opt_hide_empty.rb

@@ -4,10 +4,13 @@ class Serega
   module SeregaPlugins
     module Metadata
       class MetaAttribute
+        #
+        # Validator for meta_attribute :hide_empty option
+        #
         class CheckOptHideEmpty
           class << self
             #
-            # Checks attribute :after_hide_if option
+            # Checks attribute :hide_empty option
             #
             # @param opts [Hash] Attribute options
             #

data/lib/serega/plugins/metadata/validations/check_opt_hide_nil.rb

@@ -4,10 +4,13 @@ class Serega
   module SeregaPlugins
     module Metadata
       class MetaAttribute
+        #
+        # Validator for meta_attribute :hide_nil option
+        #
         class CheckOptHideNil
           class << self
             #
-            # Checks attribute :after_hide_if option
+            # Checks attribute :hide_nil option
             #
             # @param opts [Hash] Attribute options
             #

data/lib/serega/plugins/metadata/validations/check_opts.rb

@@ -4,6 +4,9 @@ class Serega
   module SeregaPlugins
     module Metadata
       class MetaAttribute
+        #
+        # Validator for meta_attribute options
+        #
         class CheckOpts
           class << self
             #

data/lib/serega/plugins/metadata/validations/check_path.rb

@@ -4,6 +4,9 @@ class Serega
   module SeregaPlugins
     module Metadata
       class MetaAttribute
+        #
+        # Validator for meta_attribute :path parameter
+        #
         class CheckPath
           FORMAT_ONE_CHAR = /\A[a-zA-Z0-9]\z/
           FORMAT_MANY_CHARS = /\A[a-zA-Z0-9][a-zA-Z0-9_-]*?[a-zA-Z0-9]\z/ # allow '-' and '_' in the middle