serega 0.42.0 → 0.50.0

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

@@ -2,164 +2,55 @@
 
 class Serega
   module SeregaPlugins
+    # `plugin :metadata` adds metadata defined with
+    # Serega::SeregaPlugins::Metadata::ClassMethods#meta_attribute. Load
+    # `plugin :root` first.
     #
-    # Plugin :metadata
+    # ```ruby
+    # plugin :root
+    # plugin :metadata
     #
-    # Depends on: `:root` plugin, that must be loaded first
-    #
-    # Adds metadata to the serialized response via the class-level
-    # `meta_attribute` method, which accepts:
-    #
-    # - `*path` [Array<Symbol>] - nested hash keys
-    # - `**options` [Hash]
-    #   - `:const` - a constant metadata value
-    #   - `:value` - a `#callable` producing the metadata value
-    #   - `:hide_nil` - hide the key if the value is nil (`false` by default)
-    #   - `:hide_empty` - hide the key if the value is nil or empty (`false` by default)
-    # - `&block` - computes the value for this meta attribute
-    #
-    # @example
-    #  class AppSerializer < Serega
-    #    plugin :root
-    #    plugin :metadata
-    #
-    #    meta_attribute(:version, const: '1.2.3')
-    #    meta_attribute(:ab_tests, :names, value: ABTests.new.method(:names))
-    #    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=> ... }}
+    # meta_attribute :version, const: "1.2.3"
+    # ```
     #
+    # See [Metadata](https://github.com/andreyruby/serega/blob/master/docs/root-and-metadata.md#metadata).
     module Metadata
-      # @return [Symbol] Plugin name
-      # @private
-      def self.plugin_name
-        :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)
+      # Adds the plugin to the serializer
+      def self.apply(serializer_class, **_opts) # :nodoc:
         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 :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.extend(ClassMethods)
-        serializer_class.include(InstanceMethods)
-        serializer_class::SeregaConfig.include(ConfigInstanceMethods)
 
         require_relative "meta_attribute"
-        require_relative "validations/check_block"
-        require_relative "validations/check_opt_const"
-        require_relative "validations/check_opt_hide_nil"
-        require_relative "validations/check_opt_hide_empty"
-        require_relative "validations/check_opt_value"
-        require_relative "validations/check_opts"
-        require_relative "validations/check_path"
-
-        meta_attribute_class = Class.new(MetaAttribute)
-        meta_attribute_class.serializer_class = serializer_class
-        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] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.after_load_plugin(serializer_class, **_opts)
-        serializer_class.config.opts[:metadata] = {attribute_keys: %i[const hide_nil hide_empty value]}
-      end
+        require_relative "check_params"
 
-      #
-      # 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
+        serializer_class.extend(ClassMethods)
+        serializer_class.include(InstanceMethods)
+        serializer_class.instance_variable_set(:@meta_attributes, {})
       end
 
-      #
-      # Serega class additional/patched class methods
-      #
-      # @see Serega::SeregaConfig
-      #
+      # Class methods the plugin adds to serializers
       module ClassMethods
-        #
         # List of added metadata attributes
-        #
-        # @return [Hash<Symbol => Serega::SeregaPlugins::Metadata::MetaAttribute>] Added metadata attributes
-        #
-        def meta_attributes
-          @meta_attributes ||= {}
+        def meta_attributes # :nodoc:
+          @meta_attributes
         end
 
+        # Adds metadata under a path of keys. The value is `const:`, a `value:`
+        # callable or a block, which receive the serialized objects and the
+        # context. `hide_nil: true` skips `nil` values, `hide_empty: true` skips
+        # `nil` and empty values.
         #
-        # Define metadata attribute
-        #
-        # @param path [String, Symbol] Metadata attribute path keys
-        # @param opts [Hash] Metadata attribute options
-        # @param block [Proc] Block to fetch metadata attribute value
-        #
-        # @return [Serega::SeregaPlugins::Metadata::MetaAttribute] Added metadata attribute
+        # ```ruby
+        # meta_attribute :meta, :paging, hide_nil: true do |records, ctx|
+        #   next unless records.respond_to?(:total_count)
         #
+        #   {page: records.current_page, total_count: records.total_count}
+        # end
+        # ```
         def meta_attribute(*path, **opts, &block)
-          attribute = self::MetaAttribute.new(path: path, opts: opts, block: block)
+          check_unlocked
+          attribute = MetaAttribute.new(self, path: path, opts: opts, block: block)
           meta_attributes[attribute.name] = attribute
         end
 
@@ -168,9 +59,7 @@ class Serega
         def inherited(subclass)
           super
 
-          meta_attribute_class = Class.new(self::MetaAttribute)
-          meta_attribute_class.serializer_class = subclass
-          subclass.const_set(:MetaAttribute, meta_attribute_class)
+          subclass.instance_variable_set(:@meta_attributes, {})
 
           # Assign same metadata attributes
           meta_attributes.each_value do |attr|
@@ -179,23 +68,18 @@ class Serega
         end
       end
 
-      #
       # Serega additional/patched instance methods
-      #
-      # @see Serega
-      #
-      # @private
-      module InstanceMethods
+      module InstanceMethods # :nodoc:
         private
 
-        def serialize(object, opts)
+        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_metadata(object, opts[:context], result)
+          add_metadata(object, context, result)
           result
         end
 
@@ -204,7 +88,7 @@ class Serega
             metadata = meta_attribute_value(object, context, meta_attribute)
             next unless metadata
 
-            deep_merge_metadata(hash, metadata)
+            SeregaUtils::DeepMerge.call(hash, metadata)
           rescue => error
             raise error.exception(<<~MESSAGE.strip)
               #{error.message}
@@ -217,23 +101,11 @@ class Serega
           value = meta_attribute.value(object, context)
           return if meta_attribute.hide?(value)
 
-          # Example:
-          #  [:foo, :bar].reverse_each.inject(:bazz) { |val, key| { key => val } } # => { foo: { bar: :bazz } }
-          meta_attribute.path.reverse_each.inject(value) { |val, key| {key => val} }
-        end
-
-        def deep_merge_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_metadata(this_val, other_val)
-            else
-              other_val
-            end
-          end
+          # Example: path [:foo, :bar] and value :bazz give { foo: { bar: :bazz } }
+          meta_attribute.path.reverse_each { |key| value = {key => value} }
+          value
         end
       end
     end
-
-    register_plugin(Metadata.plugin_name, Metadata)
   end
 end

data/lib/serega/plugins/root/root.rb

@@ -2,110 +2,30 @@
 
 class Serega
   module SeregaPlugins
+    # `plugin :root` wraps results in a root key, `:data` by default
     #
-    # Plugin :root
+    # ```ruby
+    # plugin :root                                     # {data: ...}
+    # plugin :root, root: :users                       # one key for objects and lists
+    # plugin :root, root_one: :user, root_many: :users # separate keys
     #
-    # Adds a root key to serialized data.
-    #
-    # Accepts options:
-    #  - :root - specifies root for all responses
-    #  - :root_one - specifies root for single object serialization only
-    #  - :root_many - specifies root for multiple objects serialization only
-    #
-    # Adds additional config options:
-    #   - config.root.one
-    #   - config.root.many
-    #   - config.root.one=
-    #   - config.root.many=
-    #
-    # Default root is `:data`.
-    #
-    # Root can also be changed per serialization, or removed entirely by
-    # providing `root: nil` (per serialization it can still be added back).
-    #
-    # @example Define plugin
-    #   class UserSerializer < Serega
-    #     plugin :root # default root is :data
-    #   end
-    #
-    #   class UserSerializer < Serega
-    #     plugin :root, root: :users
-    #   end
-    #
-    #   class UserSerializer < Serega
-    #     plugin :root, root_one: :user, root_many: :people
-    #   end
-    #
-    #   class UserSerializer < Serega
-    #     plugin :root, root: nil # no root by default
-    #   end
-    #
-    # @example Change root per serialization:
-    #   class UserSerializer < Serega
-    #     plugin :root
-    #   end
-    #
-    #   UserSerializer.to_h(nil)              # => {:data=>nil}
-    #   UserSerializer.to_h(nil, root: :user) # => {:user=>nil}
-    #   UserSerializer.to_h(nil, root: nil)   # => nil
+    # UserSerializer.to_h(user, root: :user) # => {user: {username: "batman"}}
+    # UserSerializer.to_h(user, root: nil)   # => {username: "batman"}
+    # ```
     #
+    # See [Root key](https://github.com/andreyruby/serega/blob/master/docs/root-and-metadata.md#root-key).
     module Root
-      # @return [Symbol] Default response root key
-      ROOT_DEFAULT = :data
+      # Default response root key
+      ROOT_DEFAULT = :data # :nodoc:
 
-      # @return [Symbol] Plugin name
-      # @private
-      def self.plugin_name
-        :root
-      end
+      # Adds the plugin to the serializer
+      def self.apply(serializer_class, **opts) # :nodoc:
+        SeregaValidations::Utils::CheckAllowedKeys.call(opts, %i[root root_one root_many], "plugin :root")
 
-      # Checks requirements to load plugin
-      #
-      # @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[root root_one root_many]
-        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" \
-            "  - :root [String, Symbol, nil] Specifies common root keyword used when serializing one or multiple objects\n" \
-            "  - :root_one [String, Symbol, nil] Specifies root keyword used when serializing one object\n" \
-            "  - :root_many [String, Symbol, nil] Specifies root keyword used when serializing multiple objects" \
-        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.extend(ClassMethods)
         serializer_class.include(InstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
-        serializer_class::SeregaDataBuilder.extend(DataBuilderClassMethods)
-      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
         default = opts.fetch(:root, ROOT_DEFAULT)
         one = opts.fetch(:root_one, default)
@@ -116,21 +36,37 @@ class Serega
         config.serialize_keys << :root
       end
 
-      #
-      # Serega additional/patched class methods
-      #
-      # @see Serega
-      #
+      # Class methods the plugin adds to serializers
       module ClassMethods
+        def call(object, only: nil, with: nil, except: nil, check_initiate_params: nil, context: nil, many: nil, **opts) # :nodoc:
+          new(only: only, with: with, except: except, check_initiate_params: check_initiate_params)
+            .to_h(object, context: context, many: many, **opts)
+        end
+
+        def to_data(object, only: nil, with: nil, except: nil, check_initiate_params: nil, context: nil, many: nil, **opts) # :nodoc:
+          new(only: only, with: with, except: except, check_initiate_params: check_initiate_params)
+            .to_data(object, context: context, many: many, **opts)
+        end
+
+        def to_struct(object, only: nil, with: nil, except: nil, check_initiate_params: nil, context: nil, many: nil, **opts) # :nodoc:
+          new(only: only, with: with, except: except, check_initiate_params: check_initiate_params)
+            .to_struct(object, context: context, many: many, **opts)
+        end
+
+        def to_json(object, only: nil, with: nil, except: nil, check_initiate_params: nil, context: nil, many: nil, **opts) # :nodoc:
+          new(only: only, with: with, except: except, check_initiate_params: check_initiate_params)
+            .to_json(object, context: context, many: many, **opts)
+        end
+
+        alias_method :to_h, :call # :nodoc:
+
+        # Sets the root keys: one key for objects and lists, or separate `one:`
+        # and `many:` keys
         #
-        # Configures response root key
-        #
-        # @param root [String, Symbol, nil] Specifies common root keyword used when serializing one or multiple objects
-        # @param one [String, Symbol, nil] Specifies root keyword used when serializing one object
-        # @param many [String, Symbol, nil] Specifies root keyword used when serializing multiple objects
-        #
-        # @return [Hash] Configured root names
-        #
+        # ```ruby
+        # root :users
+        # root one: :user, many: :users
+        # ```
         def root(root = nil, one: nil, many: nil)
           one ||= root
           many ||= root
@@ -139,185 +75,105 @@ class Serega
         end
       end
 
-      # Root config object
+      # Root keys, `config.root`
       class RootConfig
-        attr_reader :opts
+        attr_reader :opts # :nodoc:
 
-        #
         # Initializes RootConfig object
-        #
-        # @param opts [Hash] root options
-        # @option opts [Symbol, String, nil] :one root for single-object serialization
-        # @option opts [Symbol, String, nil] :many root for many-objects serialization
-        #
-        # @return [SeregaPlugins::Root::RootConfig] RootConfig object
-        #
-        def initialize(opts)
+        def initialize(opts) # :nodoc:
           @opts = opts
         end
 
-        # @return [Symbol, String, nil] defined root for single-object serialization
+        # Root key of one object
         def one
           opts.fetch(:one)
         end
 
-        # @return [Symbol, String, nil] defined root for many-objects serialization
+        # Root key of a list
         def many
           opts.fetch(:many)
         end
 
-        #
-        # Set root for single-object serialization
-        #
-        # @param value [Symbol, String, nil] root key
-        #
-        # @return [Symbol, String, nil] root key for single-object serialization
+        # Sets #one
         def one=(value)
           opts[:one] = value
         end
 
-        #
-        # Set root for multiple-object serialization
-        #
-        # @param value [Symbol, String, nil] root key
-        #
-        # @return [Symbol, String, nil] root key for multiple-object serialization
+        # Sets #many
         def many=(value)
           opts[:many] = value
         end
       end
 
-      #
-      # Serega::SeregaConfig additional/patched class methods
-      #
-      # @see Serega::SeregaConfig
-      #
+      # Config methods the plugin adds to Serega::SeregaConfig
       module ConfigInstanceMethods
-        # @return [Serega::SeregaPlugins::Root::RootConfig] current root config
+        # Root keys
         def root
-          @root ||= RootConfig.new(opts.fetch(:root))
+          @plugin_configs[:root] ||= RootConfig.new(opts.fetch(:root))
         end
 
-        # Set root for one-object and many-objects serialization types
-        #
-        # @param value [Hash]
-        # @option value [Symbol, String, nil] :one Root for one-object serialization type
-        # @option value [Symbol, String, nil] :many Root for many-objects serialization type
-        #
-        # @return [void]
+        # Builds the root config before freezing
+        def freeze # :nodoc:
+          root
+          super
+        end
+
+        # Sets the root keys from a Hash with `:one` and `:many`
         def root=(value)
           root.one = value.fetch(:one)
           root.many = value.fetch(:many)
         end
       end
 
-      #
       # Serega additional/patched instance methods
       #
-      # @see Serega
-      #
-      # @private
-      module InstanceMethods
-        #
-        # Serializes provided object to a tree of Ruby Data objects.
-        # When a root key is configured, the result is wrapped in an outer Data object
-        # whose members include the root key plus any metadata keys.
-        #
-        # @param object [Object] Serialized object
-        # @param opts [Hash, nil] Serializing options (`:root`, `:many`, `:context`, etc.)
-        #
-        # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
-        #
-        def to_data(object, opts = nil)
-          opts = normalize_serialization_opts(opts)
-          object = prepare_objects(object, opts[:context])
-          opts = prepare_initial_serialization_opts(object, opts)
-          serialized_data = serialize(object, opts)
-          self.class::SeregaDataBuilder.call(self, serialized_data, opts)
+      # The serialization methods take `**opts`, see ClassMethods. The
+      # options reach `#serialize` as its `opts`, after #checked_opts
+      # validates them.
+      module InstanceMethods # :nodoc:
+        def call(object, context: nil, many: nil, **opts)
+          serialize_to(:hash, object, context, many, checked_opts(opts))
         end
 
-        private
-
-        def serialize(object, opts)
-          result = super
-          root = build_root(object, opts)
-          result = {root => result} if root
-          result
+        def to_data(object, context: nil, many: nil, **opts)
+          serialize_to(:data, object, context, many, checked_opts(opts))
         end
 
-        def build_root(object, opts)
-          return opts[:root] if opts.key?(:root)
-
-          root = self.class.config.root
-          (opts.fetch(:many) { SeregaUtils::CollectionDetector.call(object) }) ? root.many : root.one
+        def to_struct(object, context: nil, many: nil, **opts)
+          serialize_to(:struct, object, context, many, checked_opts(opts))
         end
-      end
 
-      #
-      # SeregaDataBuilder additional/patched class methods
-      #
-      # Overrides `call` to handle the root key: the serialized result is
-      # unwrapped from the root key, converted to a Data tree by the base
-      # implementation, and then re-wrapped together with any metadata keys
-      # in an outer Data object. Metadata values (arbitrary hashes/arrays)
-      # are recursively converted to Data objects via `deep_hash_to_data`.
-      #
-      # When the root key is `nil` (disabled), delegates directly to the base.
-      #
-      # @see Serega::SeregaDataBuilder
-      #
-      # @private
-      module DataBuilderClassMethods
-        #
-        # @param serializer [Serega] Serializer instance carrying the plan
-        # @param serialized_result [Hash, Array, nil] Full serialized output (possibly wrapped under root key)
-        # @param serialization_opts [Hash] Serialization options used to determine the root key
-        #
-        # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
-        #
-        def call(serializer, serialized_result, serialization_opts)
-          root_key = resolve_root_key(serializer, serialization_opts)
-          return super(serializer, serialized_result) unless root_key
-
-          root_data = super(serializer, serialized_result.fetch(root_key))
-          build_data_objects(serialized_result, root_key, root_data)
+        def to_json(object, context: nil, many: nil, **opts)
+          JSON.generate(call(object, context: context, many: many, **opts))
         end
 
+        alias_method :to_h, :call
+
         private
 
-        def resolve_root_key(serializer, serialization_opts)
-          if serialization_opts.key?(:root)
-            serialization_opts[:root]
-          else
-            config_root = serializer.class.config.root
-            serialization_opts[:many] ? config_root.many : config_root.one
-          end
-        end
+        # Patched in:
+        # - plugin :context_metadata (checks the context metadata is a Hash)
+        def checked_opts(opts)
+          return FROZEN_EMPTY_HASH if opts.empty?
 
-        def build_data_objects(serialized_result, root_key, root_data)
-          converted_hash =
-            serialized_result.to_h do |key, val|
-              value = (key == root_key) ? root_data : deep_hash_to_data(val)
-              [key, value]
-            end
+          SeregaValidations::Utils::CheckAllowedKeys.call(opts, self.class.config.serialize_keys, :serialize)
+          opts
+        end
 
-          Data.define(*converted_hash.keys).new(**converted_hash)
+        def serialize(object, opts, context, many, mode)
+          result = super
+          root = build_root(opts, many)
+          result = {root => result} if root
+          result
         end
 
-        def deep_hash_to_data(value)
-          case value
-          when Hash
-            converted = value.transform_values { |nested| deep_hash_to_data(nested) }
-            Data.define(*value.keys).new(**converted)
-          when Array
-            value.map { |item| deep_hash_to_data(item) }
-          else
-            value
-          end
+        def build_root(opts, many)
+          return opts[:root] if opts.key?(:root)
+
+          root = self.class.config.root
+          many ? root.many : root.one
         end
       end
     end
-
-    register_plugin(Root.plugin_name, Root)
   end
 end