serega 0.1.0

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Metadata
+      #
+      # Stores Attribute data
+      #
+      class MetaAttribute
+        #
+        # Stores Attribute instance methods
+        #
+        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] 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 = Utils::EnumDeepDup.call(path)
+            @opts = Utils::EnumDeepDup.call(opts)
+            @block = block
+          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)
+            block.call(object, context)
+          end
+
+          def hide?(value)
+            (opts[:hide_nil] && value.nil?) || (opts[:hide_empty] && value.empty?)
+          end
+
+          private
+
+          def check(path, opts, block)
+            CheckPath.call(path)
+            CheckOpts.call(opts, self.class.serializer_class.config[:metadata][:attribute_keys])
+            CheckBlock.call(block)
+          end
+        end
+
+        extend Serega::Helpers::SerializerClassHelper
+        include InstanceMethods
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Metadata
+      def self.plugin_name
+        :metadata
+      end
+
+      def self.before_load_plugin(serializer_class, **opts)
+        serializer_class.plugin(:root, **opts) unless serializer_class.plugin_used?(:root)
+      end
+
+      def self.load_plugin(serializer_class, **_opts)
+        serializer_class.extend(ClassMethods)
+        serializer_class::Convert.include(ConvertInstanceMethods)
+
+        require_relative "./meta_attribute"
+        require_relative "./validations/check_block"
+        require_relative "./validations/check_opt_hide_nil"
+        require_relative "./validations/check_opt_hide_empty"
+        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
+
+      def self.after_load_plugin(serializer_class, **_opts)
+        serializer_class.config[plugin_name] = {attribute_keys: %i[path hide_nil hide_empty]}
+      end
+
+      module ClassMethods
+        private def inherited(subclass)
+          super
+
+          meta_attribute_class = Class.new(self::MetaAttribute)
+          meta_attribute_class.serializer_class = subclass
+          subclass.const_set(:MetaAttribute, meta_attribute_class)
+
+          # Assign same metadata attributes
+          meta_attributes.each_value do |attr|
+            subclass.meta_attribute(*attr.path, **attr.opts, &attr.block)
+          end
+        end
+
+        #
+        # List of added metadata attributes
+        #
+        # @return [Array] Added metadata attributes
+        #
+        def meta_attributes
+          @meta_attributes ||= {}
+        end
+
+        #
+        # Adds metadata to response
+        #
+        # @example
+        #   class AppSerializer < Serega
+        #
+        #     meta_attribute(:version) { '1.2.3' }
+        #
+        #     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 [Array<String, Symbol>] Metadata attribute path keys
+        # @param **opts [Hash] Metadata attribute options
+        # @param &block [Proc] Metadata attribute value
+        #
+        # @return [MetadataAttribute] Added metadata attribute
+        #
+        def meta_attribute(*path, **opts, &block)
+          attribute = self::MetaAttribute.new(path: path, opts: opts, block: block)
+          meta_attributes[attribute.name] = attribute
+        end
+      end
+
+      module ConvertInstanceMethods
+        def to_h
+          hash = super
+          add_metadata(hash)
+          hash
+        end
+
+        private
+
+        def add_metadata(hash)
+          self.class.serializer_class.meta_attributes.each_value do |meta_attribute|
+            metadata = meta_attribute_value(meta_attribute)
+            next unless metadata
+
+            deep_merge_metadata(hash, metadata)
+          end
+        end
+
+        def meta_attribute_value(meta_attribute)
+          value = meta_attribute.value(object, opts[: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
+        end
+      end
+    end
+
+    register_plugin(Metadata.plugin_name, Metadata)
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Metadata
+      class MetaAttribute
+        class CheckBlock
+          ALLOWED_PARAM_TYPES = %i[opt req]
+          private_constant :ALLOWED_PARAM_TYPES
+
+          class << self
+            #
+            # Checks block provided with attribute
+            # Block must have up to two arguments - object and context.
+            # It should not have any *rest or **key arguments
+            #
+            # @example without arguments
+            #   metadata(:version) { CONSTANT_VERSION }
+            #
+            # @example with one argument
+            #   metadata(:paging) { |scope| { { page: scope.page, per_page: scope.per_page, total_count: scope.total_count } }
+            #
+            # @example with two arguments
+            #   metadata(:paging) { |scope, context| { { ... } if context[:with_paging] }
+            #
+            # @param block [Proc] Block that returns serialized meta attribute value
+            #
+            # @raise [Error] Error that block has invalid arguments
+            #
+            # @return [void]
+            #
+            def call(block)
+              raise Error, "Block must be provided when defining meta attribute" unless block
+
+              params = block.parameters
+              return if (params.count <= 2) && params.all? { |par| ALLOWED_PARAM_TYPES.include?(par[0]) }
+
+              raise Error, "Block can have maximum 2 regular parameters (no **keyword or *array args)"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Metadata
+      class MetaAttribute
+        class CheckOptHideEmpty
+          class << self
+            #
+            # Checks attribute :after_hide_if option
+            #
+            # @param opts [Hash] Attribute options
+            #
+            # @raise [Error] Error that option has invalid value
+            #
+            # @return [void]
+            #
+            def call(opts)
+              return unless opts.key?(:hide_empty)
+
+              value = opts[:hide_empty]
+              return if value == true
+
+              raise Error, "Invalid option :hide_empty => #{value.inspect}. Must be true"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Metadata
+      class MetaAttribute
+        class CheckOptHideNil
+          class << self
+            #
+            # Checks attribute :after_hide_if option
+            #
+            # @param opts [Hash] Attribute options
+            #
+            # @raise [Error] Error that option has invalid value
+            #
+            # @return [void]
+            #
+            def call(opts)
+              return unless opts.key?(:hide_nil)
+
+              value = opts[:hide_nil]
+              return if value == true
+
+              raise Error, "Invalid option :hide_nil => #{value.inspect}. Must be true"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Metadata
+      class MetaAttribute
+        class CheckOpts
+          class << self
+            #
+            # Validates attribute options
+            # Checks used options are allowed and then checks options values.
+            #
+            # @param opts [Hash] Attribute options
+            # @param attribute_keys [Array<Symbol>] Allowed options keys
+            #
+            # @raise [Error] when attribute has invalid options
+            #
+            # @return [void]
+            #
+            def call(opts, attribute_keys)
+              opts.each_key do |key|
+                next if attribute_keys.include?(key.to_sym)
+
+                raise Error, "Invalid option #{key.inspect}. Allowed options are: #{attribute_keys.map(&:inspect).join(", ")}"
+              end
+
+              check_each_opt(opts)
+            end
+
+            private
+
+            def check_each_opt(opts)
+              CheckOptHideEmpty.call(opts)
+              CheckOptHideNil.call(opts)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Metadata
+      class MetaAttribute
+        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
+
+          private_constant :FORMAT_ONE_CHAR, :FORMAT_MANY_CHARS
+
+          class << self
+            #
+            # Checks allowed characters in specified metadata path parts.
+            # Globally allowed characters: "a-z", "A-Z", "0-9".
+            # Minus and low line "-", "_" also allowed except as the first or last character.
+            #
+            # @param path [Array<String, Symbol>] Metadata attribute path names
+            #
+            # @raise [Error] when metadata attribute name has invalid format
+            # @return [void]
+            #
+            def call(path)
+              path.each { |attr_name| check_name(attr_name) }
+            end
+
+            private
+
+            def check_name(name)
+              name = name.to_s
+
+              valid =
+                case name.size
+                when 0 then false
+                when 1 then name.match?(FORMAT_ONE_CHAR)
+                else name.match?(FORMAT_MANY_CHARS)
+                end
+
+              return if valid
+
+              raise Error, message(name)
+            end
+
+            def message(name)
+              %(Invalid metadata path #{name.inspect}, globally allowed characters: "a-z", "A-Z", "0-9". Minus and low line "-", "_" also allowed except as the first or last character)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Preloads
+      # Freezes nested enumerable data
+      class EnumDeepFreeze
+        class << self
+          def call(data)
+            data.each_entry { |entry| call(entry) } if data.is_a?(Enumerable)
+            data.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Preloads
+      # Transforms user provided preloads to hash
+      class FormatUserPreloads
+        METHODS = {
+          Array => :array_to_hash,
+          FalseClass => :nil_to_hash,
+          Hash => :hash_to_hash,
+          NilClass => :nil_to_hash,
+          String => :string_to_hash,
+          Symbol => :symbol_to_hash
+        }.freeze
+
+        module ClassMethods
+          def call(value)
+            send(METHODS.fetch(value.class), value)
+          end
+
+          private
+
+          def array_to_hash(values)
+            values.each_with_object({}) do |value, obj|
+              obj.merge!(call(value))
+            end
+          end
+
+          def hash_to_hash(values)
+            values.each_with_object({}) do |(key, value), obj|
+              obj[key.to_sym] = call(value)
+            end
+          end
+
+          def nil_to_hash(_value)
+            {}
+          end
+
+          def string_to_hash(value)
+            symbol_to_hash(value.to_sym)
+          end
+
+          def symbol_to_hash(value)
+            {value => {}}
+          end
+        end
+
+        extend ClassMethods
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Preloads
+      class MainPreloadPath
+        module ClassMethods
+          # @param preloads [Hash] Formatted user provided preloads hash
+          def call(preloads)
+            return FROZEN_EMPTY_ARRAY if preloads.empty?
+
+            main_path(preloads)
+          end
+
+          private
+
+          # Generates path (Array) to the last included resource.
+          # We need to know this path to include nested associations.
+          #
+          #  main_path(a: { b: { c: {} }, d: {} }) # => [:a, :d]
+          #
+          def main_path(hash, path = [])
+            current_level = path.size
+
+            hash.each do |key, data|
+              path.pop(path.size - current_level)
+              path << key
+
+              main_path(data, path)
+            end
+
+            path
+          end
+        end
+
+        extend ClassMethods
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Preloads
+      #
+      # Finds relations to preload for provided serializer
+      #
+      class PreloadsConstructor
+        module ClassMethods
+          #
+          # Constructs preloads hash for given serializer
+          #
+          # @param serializer [Serega] Instance of Serega serializer
+          #
+          # @return [Hash]
+          #
+          def call(map)
+            preloads = {}
+            append_many(preloads, map)
+            preloads
+          end
+
+          private
+
+          def append_many(preloads, map)
+            map.each do |attribute, nested_map|
+              current_preloads = attribute.preloads
+              next unless current_preloads
+
+              has_nested = nested_map.any?
+              current_preloads = Utils::EnumDeepDup.call(current_preloads) if has_nested
+              append_current(preloads, current_preloads)
+              next unless has_nested
+
+              nested_preloads = nested(preloads, attribute.preloads_path)
+              append_many(nested_preloads, nested_map)
+            end
+          end
+
+          def append_current(preloads, current_preloads)
+            merge(preloads, current_preloads) unless current_preloads.empty?
+          end
+
+          def merge(preloads, current_preloads)
+            preloads.merge!(current_preloads) do |_key, value_one, value_two|
+              merge(value_one, value_two)
+            end
+          end
+
+          def nested(preloads, path)
+            !path || path.empty? ? preloads : preloads.dig(*path)
+          end
+        end
+
+        extend ClassMethods
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    #
+    # Plugin adds `.preloads` method to find relations that must be preloaded
+    #
+    module Preloads
+      # @return [Symbol] plugin name
+      def self.plugin_name
+        :preloads
+      end
+
+      #
+      # Includes plugin modules to current serializer
+      #
+      # @param serializer_class [Class] current serializer class
+      # @param _opts [Hash] plugin opts
+      #
+      # @return [void]
+      #
+      def self.load_plugin(serializer_class, **_opts)
+        serializer_class.include(InstanceMethods)
+        serializer_class::Attribute.include(AttributeMethods)
+
+        serializer_class::Attribute::CheckOpts.extend(CheckOptsClassMethods)
+
+        require_relative "./lib/enum_deep_freeze"
+        require_relative "./lib/format_user_preloads"
+        require_relative "./lib/main_preload_path"
+        require_relative "./lib/preloads_constructor"
+        require_relative "./validations/check_opt_preload_path"
+      end
+
+      def self.after_load_plugin(serializer_class, **opts)
+        config = serializer_class.config
+        config[:attribute_keys] += [:preload, :preload_path]
+        config[:preloads] = {auto_preload_relations: opts.fetch(:auto_preload_relations, true)}
+      end
+
+      # Adds #preloads instance method
+      module InstanceMethods
+        # @return [Hash] relations that can be preloaded to omit N+1
+        def preloads
+          @preloads ||= PreloadsConstructor.call(map)
+        end
+      end
+
+      # Adds #preloads and #preloads_path Attribute instance method
+      module AttributeMethods
+        def preloads
+          return @preloads if defined?(@preloads)
+
+          @preloads = get_preloads
+        end
+
+        def preloads_path
+          return @preloads_path if defined?(@preloads_path)
+
+          @preloads_path = get_preloads_path
+        end
+
+        private
+
+        def get_preloads
+          preloads_provided = opts.key?(:preload)
+          preloads =
+            if preloads_provided
+              opts[:preload]
+            elsif relation? && self.class.serializer_class.config[:preloads][:auto_preload_relations]
+              key
+            end
+
+          # Nil and empty hash differs as we can preload nested results to
+          # empty hash, but we will skip nested preloading if nil or false provided
+          return if preloads_provided && !preloads
+
+          FormatUserPreloads.call(preloads)
+        end
+
+        def get_preloads_path
+          path = Array(opts[:preload_path]).map!(&:to_sym)
+          path = MainPreloadPath.call(preloads) if path.empty?
+          EnumDeepFreeze.call(path)
+        end
+      end
+
+      module CheckOptsClassMethods
+        private
+
+        def check_each_opt(opts)
+          super
+          CheckOptPreloadPath.call(opts)
+        end
+      end
+    end
+
+    register_plugin(Preloads.plugin_name, Preloads)
+  end
+end