serega 0.42.0 → 0.50.0

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

@@ -2,162 +2,93 @@
 
 class Serega
   module SeregaPlugins
+    # `plugin :context_metadata` adds metadata given per serialization with
+    # the `:meta` option. Load `plugin :root` first.
     #
-    # Plugin :context_metadata
+    # ```ruby
+    # plugin :root
+    # plugin :context_metadata
     #
-    # Depends on: `:root` plugin, that must be loaded first
-    #
-    # Adds metadata supplied per serialization call (as opposed to `:metadata`,
-    # which is defined statically on the serializer).
-    #
-    # @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"}
+    # UserSerializer.to_h(user, meta: {version: "1.0.1"})
+    # # => {data: {username: "batman"}, version: "1.0.1"}
+    # ```
     #
+    # See [Metadata per serialization](https://github.com/andreyruby/serega/blob/master/docs/root-and-metadata.md#metadata-per-serialization).
     module ContextMetadata
       # Default context metadata option name
-      DEFAULT_CONTEXT_METADATA_KEY = :meta
+      DEFAULT_CONTEXT_METADATA_KEY = :meta # :nodoc:
 
-      # @return [Symbol] Plugin name
-      # @private
-      def self.plugin_name
-        :context_metadata
-      end
-
-      # Checks requirements and loads additional plugins
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param opts [Hash] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.before_load_plugin(serializer_class, **opts)
-        allowed_keys = %i[context_metadata_key]
-        opts.each_key do |key|
-          next if allowed_keys.include?(key)
-
-          raise SeregaError,
-            "Plugin #{plugin_name.inspect} does not accept the #{key.inspect} option. Allowed options:\n" \
-            "  - :context_metadata_key [Symbol] - The key name that must be used to add metadata. Default is :meta."
-        end
+      # Adds the plugin to the serializer
+      def self.apply(serializer_class, **opts) # :nodoc:
+        SeregaValidations::Utils::CheckAllowedKeys.call(opts, %i[context_metadata_key], "plugin :context_metadata")
 
         unless serializer_class.plugin_used?(:root)
-          raise SeregaError, "Plugin #{plugin_name.inspect} must be loaded after the :root plugin. Please load the :root plugin first"
+          raise SeregaError, "Plugin :context_metadata must be loaded after the :root plugin. Please load the :root plugin first"
         end
-      end
 
-      #
-      # Applies plugin code to specific serializer
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param _opts [Hash] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.load_plugin(serializer_class, **_opts)
         serializer_class.include(InstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
-        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] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.after_load_plugin(serializer_class, **opts)
         config = serializer_class.config
         meta_key = opts[:context_metadata_key] || DEFAULT_CONTEXT_METADATA_KEY
         config.opts[:context_metadata] = {key: meta_key}
         config.serialize_keys << meta_key
       end
 
-      #
-      # Config for `context_metadata` plugin
-      #
+      # Config of the `:context_metadata` plugin, `config.context_metadata`
       class ContextMetadataConfig
-        # @return [Hash] context_metadata options
-        attr_reader :opts
+        # context_metadata options
+        attr_reader :opts # :nodoc:
 
-        #
         # Initializes context_metadata config object
-        #
-        # @param opts [Hash] options
-        #
-        # @return [Serega::SeregaPlugins::ContextMetadata::ContextMetadataConfig]
-        def initialize(opts)
+        def initialize(opts, serialize_keys) # :nodoc:
           @opts = opts
+          @serialize_keys = serialize_keys
         end
 
-        # Key that should be used to define metadata
+        # Name of the serialization option with metadata, `:meta` by default
         def key
           opts.fetch(:key)
         end
 
-        # Sets key that should be used to define metadata
-        #
-        # @param new_key [Symbol] New key
-        #
-        # @return [Symbol] New key
+        # Sets #key. The previous name raises Serega::SeregaError.
         def key=(new_key)
+          previous_key = key
           opts[:key] = new_key
+          @serialize_keys.delete(previous_key)
+          @serialize_keys << new_key if new_key
         end
       end
 
-      #
-      # Config class additional/patched instance methods
-      #
-      # @see Serega::SeregaConfig
-      #
+      # Config methods the plugin adds to Serega::SeregaConfig
       module ConfigInstanceMethods
-        # @return [Serega::SeregaPlugins::ContextMetadata::ContextMetadataConfig] context_metadata config
+        # Config of the plugin
         def context_metadata
-          @context_metadata ||= ContextMetadataConfig.new(opts.fetch(:context_metadata))
+          @plugin_configs[:context_metadata] ||= ContextMetadataConfig.new(opts.fetch(:context_metadata), serialize_keys)
         end
-      end
 
-      #
-      # CheckSerializeParams class additional/patched instance methods
-      #
-      # @see Serega::SeregaValidations::CheckSerializeParams
-      #
-      # @private
-      module CheckSerializeParamsInstanceMethods
-        private
-
-        def check_opts
+        # Builds the context_metadata config before freezing
+        def freeze # :nodoc:
+          context_metadata
           super
-
-          meta_key = self.class.serializer_class.config.context_metadata.key
-          SeregaValidations::Utils::CheckOptIsHash.call(opts, meta_key)
         end
       end
 
-      #
       # Serega additional/patched instance methods
-      #
-      # @see Serega
-      #
-      # @private
-      module InstanceMethods
+      module InstanceMethods # :nodoc:
         private
 
-        def serialize(object, opts)
+        def checked_opts(opts)
+          checked_opts = super
+          SeregaValidations::Utils::CheckOptIsHash.call(checked_opts, self.class.config.context_metadata.key)
+          checked_opts
+        end
+
+        def serialize(object, opts, context, many, mode)
           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)
+          root = build_root(opts, many)
           return result unless root # return earlier when no root
 
           add_context_metadata(result, opts)
@@ -166,26 +97,12 @@ class Serega
 
         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]
           return unless metadata
 
-          deep_merge_context_metadata(hash, metadata)
-        end
-
-        def deep_merge_context_metadata(hash, metadata)
-          hash.merge!(metadata) do |_key, this_val, other_val|
-            if this_val.is_a?(Hash) && other_val.is_a?(Hash)
-              deep_merge_context_metadata(this_val, other_val)
-            else
-              other_val
-            end
-          end
+          SeregaUtils::DeepMerge.call(hash, metadata)
         end
       end
     end
-
-    register_plugin(ContextMetadata.plugin_name, ContextMetadata)
   end
 end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Metadata
+      class MetaAttribute
+        #
+        # Validator of the path, the options and the block of a meta attribute
+        #
+        class CheckParams # :nodoc:
+          # Options of `meta_attribute`
+          KEYS = %i[const value hide_nil hide_empty].freeze
+
+          # Characters allowed in each key of the path
+          PATH_FORMAT = /\A[\w~-]+\z/
+
+          # Signatures of a value or a block: up to two parameters, the objects
+          # and the context
+          VALID_SIGNATURES = %w[0 1 2].freeze
+
+          class << self
+            # Checks the meta attribute params. `check_path` is
+            # `config.check_attribute_name`.
+            def call(path, opts, block, check_path)
+              path.each { |key| check_path_key(key) } if check_path
+              SeregaValidations::Utils::CheckAllowedKeys.call(opts, KEYS, :meta_attribute)
+              check_true(opts, :hide_empty)
+              check_true(opts, :hide_nil)
+              check_value_source(opts, block)
+              check_value(opts[:value]) if opts.key?(:value)
+              check_block(block) if block
+            end
+
+            private
+
+            def check_path_key(key)
+              key = key.to_s
+              return if PATH_FORMAT.match?(key)
+
+              raise SeregaError,
+                "Invalid metadata path #{key.inspect}. Allowed characters: \"a-z\", \"A-Z\", \"0-9\", \"_\", \"-\", \"~\""
+            end
+
+            def check_true(opts, key)
+              return unless opts.key?(key)
+
+              value = opts[key]
+              raise SeregaError, "Invalid option #{key.inspect} => #{value.inspect}. Must be true" unless value == true
+            end
+
+            # Exactly one of :value, :const and the block gives the value
+            def check_value_source(opts, block)
+              value = opts.key?(:value)
+              const = opts.key?(:const)
+
+              raise SeregaError, "Option :value can not be used together with option :const" if value && const
+              raise SeregaError, "Option :value can not be used together with block" if value && block
+              raise SeregaError, "Option :const can not be used together with block" if const && block
+              raise SeregaError, "Please provide block argument or add :value or :const option" unless value || const || block
+            end
+
+            def check_value(value)
+              raise SeregaError, "Option :value value must be a Proc or respond to #call" unless value.respond_to?(:call)
+
+              signature = SeregaUtils::MethodSignature.call(value, pos_limit: 2, keyword_args: [])
+              return if VALID_SIGNATURES.include?(signature)
+
+              raise SeregaError, "Option :value value can have maximum 2 parameters (object(s), context)"
+            end
+
+            def check_block(block)
+              signature = SeregaUtils::MethodSignature.call(block, pos_limit: 2, keyword_args: [])
+              raise SeregaError, "Block can have maximum two parameters (object(s), context)" unless VALID_SIGNATURES.include?(signature)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -6,93 +6,54 @@ class Serega
       #
       # Stores Attribute data
       #
-      # @private
-      class MetaAttribute
-        #
-        # Stores Attribute instance methods
-        #
-        # @private
-        module InstanceMethods
-          # @return [Symbol] Meta attribute name
-          attr_reader :name
-
-          # @return [Symbol] Meta attribute full path
-          attr_reader :path
-
-          # @return [Proc] Meta attribute options
-          attr_reader :opts
-
-          # @return [Proc,nil] Meta attribute originally added block
-          attr_reader :block
-
-          #
-          # Initializes new meta attribute
-          #
-          # @param path [Array<Symbol, String>] Path for metadata of attribute
-          #
-          # @param opts [Hash] metadata attribute options
-          #
-          # @param block [Proc] Proc that receives object(s) and context and finds value
-          #
-          def initialize(path:, opts:, block:)
-            check(path, opts, block)
-
-            @name = path.join(".").to_sym
-            @path = SeregaUtils::EnumDeepDup.call(path)
-            @opts = SeregaUtils::EnumDeepDup.call(opts)
-            @block = block
-            @normalized_block = normalize_block(opts[:value], opts[:const], block)
-            @normalized_block_signature =
-              SeregaUtils::MethodSignature.call(@normalized_block, pos_limit: 2, keyword_args: [])
-          end
-
-          #
-          # Finds attribute value
-          #
-          # @param object [Object] Serialized object(s)
-          # @param context [Hash, nil] Serialization context
-          #
-          # @return [Object] Serialized meta attribute value
-          #
-          def value(object, context)
-            case normalized_block_signature
-            when "0" then normalized_block.call
-            when "1" then normalized_block.call(object)
-            else normalized_block.call(object, context)
-            end
-          end
+      class MetaAttribute # :nodoc:
+        # Meta attribute name
+        attr_reader :name
+
+        # Meta attribute full path
+        attr_reader :path
+
+        # Meta attribute options
+        attr_reader :opts
+
+        # Meta attribute originally added block
+        attr_reader :block
+
+        # Initializes new meta attribute
+        def initialize(serializer_class, path:, opts:, block:)
+          CheckParams.call(path, opts, block, serializer_class.config.check_attribute_name)
+
+          @name = path.join(".").to_sym
+          @path = SeregaUtils::EnumDeepDup.call(path)
+          @opts = SeregaUtils::EnumDeepDup.call(opts)
+          @block = block
+          @normalized_block = normalize_block(opts[:value], opts[:const], block)
+          @normalized_block_signature =
+            SeregaUtils::MethodSignature.call(@normalized_block, pos_limit: 2, keyword_args: [])
+        end
 
-          def hide?(value)
-            (!!opts[:hide_nil] && value.nil?) || (!!opts[:hide_empty] && (value.nil? || (value.respond_to?(:empty?) && value.empty?)))
+        # Finds attribute value
+        def value(object, context)
+          case normalized_block_signature
+          when "0" then normalized_block.call
+          when "1" then normalized_block.call(object)
+          else normalized_block.call(object, context)
           end
+        end
 
-          private
+        def hide?(value)
+          (!!opts[:hide_nil] && value.nil?) || (!!opts[:hide_empty] && (value.nil? || (value.respond_to?(:empty?) && value.empty?)))
+        end
 
-          attr_reader :normalized_block, :normalized_block_signature
+        private
 
-          def normalize_block(value, const, block)
-            return proc { const } if const
+        attr_reader :normalized_block, :normalized_block_signature
 
-            value || block
-          end
-
-          def check(path, opts, block)
-            CheckPath.call(path) if check_attribute_name
-            CheckOpts.call(opts, block, attribute_keys)
-            CheckBlock.call(block) if block
-          end
+        def normalize_block(value, const, block)
+          return proc { const } if const
 
-          def attribute_keys
-            self.class.serializer_class.config.metadata.attribute_keys
-          end
-
-          def check_attribute_name
-            self.class.serializer_class.config.check_attribute_name
-          end
+          value || block
         end
-
-        extend Serega::SeregaHelpers::SerializerClassHelper
-        include InstanceMethods
       end
     end
   end