serega 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac327fb1d98a08b76fcdfdc68166265bea134f298892f0a2f9b1a25c7d1e6063
+  data.tar.gz: 9843b54690c3ab5e4c4ad0c651e5e7629915eb502a0913520cec9153e6ebfa9f
+SHA512:
+  metadata.gz: 7260b7ff2a939f93510565e50a19e6ad3c4fe6899c8ddb927938714bf422d0faedab7e62c638f18e98af13b6f9403cd30d4d72088dd6209f083ad4338f4d64da
+  data.tar.gz: b54726235c873c143fc3458837f1ecce05ffa26229d37e6b7420b304b8f1bff3bdde9e4a73fcd91c0e19664918cd2080d708e105398d4d30f15e6b440a7d737f

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/serega/attribute.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Stores Attribute data
+  #
+  class Attribute
+    #
+    # Stores Attribute instance methods
+    #
+    module AttributeInstanceMethods
+      # @return [Symbol] Attribute name
+      attr_reader :name
+
+      # @return [Hash] Attribute options
+      attr_reader :opts
+
+      # @return [Proc] Attribute originally added block
+      attr_reader :block
+
+      #
+      # Initializes new attribute
+      #
+      # @param name [Symbol, String] Name of attribute
+      #
+      # @param opts [Hash] Attribute options
+      # @option opts [Symbol] :key Object instance method name to get attribute value
+      # @option opts [Boolean] :exposed Configures if we should serialize this attribute by default.
+      #  (by default is true for regular attributes and false for relationships)
+      # @option opts [Boolean] :many Specifies has_many relationship. By default is detected via object.is_a?(Enumerable)
+      # @option opts [Serega, Proc] :serializer Relationship serializer class. Use `proc { MySerializer }` if serializers have cross references.
+      #
+      # @param block [Proc] Proc that receives object and context and finds attribute value
+      #
+      def initialize(name:, opts: {}, block: nil)
+        check(name, opts, block)
+
+        @name = name.to_sym
+        @opts = Utils::EnumDeepDup.call(opts)
+        @block = opts[:value] || block
+      end
+
+      # @return [Symbol] Object method name to will be used to get attribute value unless block provided
+      def key
+        @key ||= opts.key?(:key) ? opts[:key].to_sym : name
+      end
+
+      # @return [Boolean, nil] Attribute initial :hide option value
+      def hide
+        opts[:hide]
+      end
+
+      # @return [Boolean, nil] Attribute initialization :many option
+      def many
+        opts[:many]
+      end
+
+      # @return [Boolean] Checks if attribute is relationship (if :serializer option exists)
+      def relation?
+        !opts[:serializer].nil?
+      end
+
+      # @return [Serega, nil] Attribute serializer if exists
+      def serializer
+        return @serializer if instance_variable_defined?(:@serializer)
+
+        serializer = opts[:serializer]
+        @serializer =
+          case serializer
+          when String then Object.const_get(serializer, false)
+          when Proc then serializer.call
+          else serializer
+          end
+      end
+
+      # @return [Proc] Proc to find attribute value
+      def value_block
+        return @value_block if instance_variable_defined?(:@value_block)
+
+        @value_block = block || keyword_block
+      end
+
+      #
+      # Finds attribute value
+      #
+      # @param object [Object] Serialized object
+      # @param context [Hash, nil] Serialization context
+      #
+      # @return [Object] Serialized attribute value
+      #
+      def value(object, context)
+        value_block.call(object, context)
+      end
+
+      #
+      # Checks if attribute must be added to serialized response
+      #
+      # @param except [Hash] manually hidden attributes
+      # @param only [Hash] manually enforced exposed attributes, other attributes are enforced to be hidden
+      # @param with [Hash] manually enforced exposed attributes
+      #
+      # @return [Boolean]
+      #
+      def visible?(except:, only:, with:)
+        return false if except.member?(name) && except[name].empty?
+        return true if only.member?(name)
+        return true if with.member?(name)
+        return false unless only.empty?
+
+        !hide
+      end
+
+      private
+
+      def keyword_block
+        key_method_name = key
+        proc { |object| object.public_send(key_method_name) }
+      end
+
+      def check(name, opts, block)
+        CheckName.call(name)
+        CheckOpts.call(opts, self.class.serializer_class.config[:attribute_keys])
+        CheckBlock.call(opts, block)
+      end
+    end
+
+    extend Serega::Helpers::SerializerClassHelper
+    include AttributeInstanceMethods
+  end
+end

data/lib/serega/config.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+class Serega
+  #
+  # Core class that stores serializer configuration
+  #
+  class Config
+    module ConfigInstanceMethods
+      extend Forwardable
+
+      # @return [Hash] Current config data
+      attr_reader :opts
+
+      #
+      # Initializes new config instance and deeply duplicates all provided options to
+      # remove possibility of accidental overwriting of parent/nested configs.
+      #
+      # @param opts [Hash] Initial config options
+      #
+      def initialize(opts = {})
+        @opts = Utils::EnumDeepDup.call(opts)
+      end
+
+      #
+      # @!method [](name)
+      #   Get config option, delegates to opts#[]
+      #   @param name [Symbol] option name
+      #   @return [Object]
+      #
+      # @!method []=(name)
+      #   Set config option, delegates to opts#[]=
+      #   @param name [Symbol] option name
+      #   @return [Object]
+      #
+      # @!method fetch(name)
+      #   Fetch config option, delegates to opts#fetch
+      #   @param name [Symbol] option name
+      #   @return [Object]
+      #
+      def_delegators :opts, :[], :[]=, :fetch, :keys, :has_key?
+    end
+
+    include ConfigInstanceMethods
+    extend Serega::Helpers::SerializerClassHelper
+  end
+end

data/lib/serega/convert.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class Serega
+  class Convert
+    module ConvertClassMethods
+      def call(object, **opts)
+        new(object, **opts).to_h
+      end
+    end
+
+    module ConvertInstanceMethods
+      attr_reader :object, :opts
+
+      def initialize(object, **opts)
+        @object = object
+        @opts = opts
+      end
+
+      def to_h
+        many? ? many(object) : one(object) || {}
+      end
+
+      private
+
+      def many(objects)
+        objects.map { |obj| one(obj) }
+      end
+
+      def one(object)
+        self.class.serializer_class::ConvertItem.call(object, opts[:context], opts[:map])
+      end
+
+      def many?
+        many = opts[:many]
+        return many unless many.nil?
+
+        object.is_a?(Enumerable)
+      end
+    end
+
+    extend Serega::Helpers::SerializerClassHelper
+    extend ConvertClassMethods
+    include ConvertInstanceMethods
+  end
+end

data/lib/serega/convert_item.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class Serega
+  class ConvertItem
+    module ConvertItemClassMethods
+      def call(object, context, map)
+        return unless object
+
+        map.each_with_object({}) do |(attribute, nested_attributes), hash|
+          value = attribute.value(object, context)
+          attach_value(value, hash, attribute, nested_attributes, context)
+        end
+      end
+
+      private
+
+      def attach_value(value, hash, attribute, nested_attributes, context)
+        hash[attribute.name] =
+          if nested_attributes.empty?
+            attribute.relation? ? FROZEN_EMPTY_HASH : value
+          elsif many?(attribute, value)
+            value.map { |val| call(val, context, nested_attributes) }
+          else
+            call(value, context, nested_attributes)
+          end
+      end
+
+      def many?(attribute, object)
+        is_many = attribute.many
+        is_many.nil? ? object.is_a?(Enumerable) : is_many
+      end
+    end
+
+    extend Serega::Helpers::SerializerClassHelper
+    extend ConvertItemClassMethods
+  end
+end

data/lib/serega/helpers/serializer_class_helper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class Serega
+  module Helpers
+    # Stores link to current serializer class
+    module SerializerClassHelper
+      # @return [Class<Serega>] Serializer class that current class is namespaced under.
+      attr_accessor :serializer_class
+    end
+  end
+end

data/lib/serega/map.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class Serega
+  class Map
+    module ClassMethods
+      def call(opts)
+        @cache ||= {}
+        cache_key = opts.to_s
+
+        @cache[cache_key] ||= begin
+          modifiers = {
+            only: opts&.[](:only) || FROZEN_EMPTY_HASH,
+            except: opts&.[](:except) || FROZEN_EMPTY_HASH,
+            with: opts&.[](:with) || FROZEN_EMPTY_HASH
+          }
+
+          construct_map(serializer_class, **modifiers).tap do
+            @cache.shift if @cache.length >= serializer_class.config[:max_cached_map_per_serializer_count]
+          end
+        end
+      end
+
+      private
+
+      def construct_map(serializer_class, only:, except:, with:)
+        serializer_class.attributes.each_with_object([]) do |(name, attribute), map|
+          next unless attribute.visible?(only: only, except: except, with: with)
+
+          nested_map =
+            if attribute.relation?
+              construct_map(
+                attribute.serializer,
+                only: only[name] || FROZEN_EMPTY_HASH,
+                with: with[name] || FROZEN_EMPTY_HASH,
+                except: except[name] || FROZEN_EMPTY_HASH
+              )
+            else
+              FROZEN_EMPTY_ARRAY
+            end
+
+          map << [attribute, nested_map]
+        end
+      end
+    end
+
+    extend ClassMethods
+    extend Serega::Helpers::SerializerClassHelper
+  end
+end

data/lib/serega/plugins/activerecord_preloads/activerecord_preloads.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    #
+    # Plugin that checks used plugins and loads correct Preloader for selected response type
+    # @see Serega::Plugins::JsonApiActiverecordPreloader
+    # @see Serega::Plugins::SimpleApiActiverecordPreloader
+    #
+    module ActiverecordPreloads
+      # @return [Symbol] plugin name
+      def self.plugin_name
+        :activerecord_preloads
+      end
+
+      def self.before_load_plugin(serializer_class, **opts)
+        serializer_class.plugin(:preloads, **opts) unless serializer_class.plugin_used?(:preloads)
+      end
+
+      #
+      # Loads plugin code and additional plugins
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
+      def self.load_plugin(serializer_class, **opts)
+        require_relative "./lib/preloader"
+
+        serializer_class.include(InstanceMethods)
+      end
+
+      # Overrides Serega classes instance methods
+      module InstanceMethods
+        #
+        # Override original #to_h method
+        # @see Serega#to_h
+        #
+        def to_h(object, **opts)
+          object = add_preloads(object)
+          super
+        end
+
+        private
+
+        def add_preloads(obj)
+          return obj if obj.nil? || (obj.is_a?(Array) && obj.empty?)
+
+          # preloads() method comes from :preloads plugin
+          preloads = preloads()
+          return obj if preloads.empty?
+
+          Preloader.preload(obj, preloads)
+        end
+      end
+    end
+
+    register_plugin(ActiverecordPreloads.plugin_name, ActiverecordPreloads)
+  end
+end

data/lib/serega/plugins/activerecord_preloads/lib/preloader.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module ActiverecordPreloads
+      class Preloader
+        module ClassMethods
+          def preload(object, preloads)
+            preload_handler = handlers.find { |handler| handler.fit?(object) }
+            raise Error, "Can't preload #{preloads.inspect} to #{object.inspect}" unless preload_handler
+
+            preload_handler.preload(object, preloads)
+          end
+
+          def handlers
+            @handlers ||= [ActiverecordRelation, ActiverecordObject, ActiverecordArray].freeze
+          end
+        end
+
+        extend ClassMethods
+      end
+
+      class Loader
+        # :nocov: We can check only one version of activerecord
+        def self.call(records, associations)
+          if ActiveRecord::VERSION::MAJOR >= 7
+            ActiveRecord::Associations::Preloader.new(records: records, associations: associations).call
+          else
+            ActiveRecord::Associations::Preloader.new.preload(records, associations)
+          end
+        end
+        # :nocov:
+      end
+
+      class ActiverecordObject
+        module ClassMethods
+          def fit?(object)
+            object.is_a?(ActiveRecord::Base)
+          end
+
+          def preload(object, preloads)
+            Loader.call([object], preloads)
+            object
+          end
+        end
+
+        extend ClassMethods
+      end
+
+      class ActiverecordRelation
+        module ClassMethods
+          def fit?(objects)
+            objects.is_a?(ActiveRecord::Relation)
+          end
+
+          def preload(objects, preloads)
+            if objects.loaded?
+              array_objects = objects.to_a
+              Loader.call(array_objects, preloads)
+              objects
+            else
+              objects.preload(preloads).load
+            end
+          end
+        end
+
+        extend ClassMethods
+      end
+
+      class ActiverecordArray
+        module ClassMethods
+          def fit?(objects)
+            objects.is_a?(Array) &&
+              ActiverecordObject.fit?(objects.first) &&
+              same_kind?(objects)
+          end
+
+          def preload(objects, preloads)
+            Loader.call(objects, preloads)
+            objects
+          end
+
+          private
+
+          def same_kind?(objects)
+            first_object_class = objects.first.class
+            objects.all? { |object| object.instance_of?(first_object_class) }
+          end
+        end
+
+        extend ClassMethods
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module ContextMetadata
+      DEFAULT_CONTEXT_METADATA_KEY = :meta
+
+      def self.plugin_name
+        :context_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.include(InstanceMethods)
+        serializer_class::Convert.include(ConvertInstanceMethods)
+      end
+
+      def self.after_load_plugin(serializer_class, **opts)
+        config = serializer_class.config
+        meta_key = opts[:context_metadata_key] || DEFAULT_CONTEXT_METADATA_KEY
+        config[plugin_name] = {key: meta_key}
+        config[:serialize_keys] << meta_key
+      end
+
+      module InstanceMethods
+        def to_h(object, **opts)
+          meta_key = self.class.config[:context_metadata][:key]
+          meta = opts[meta_key]
+
+          if meta && !meta.is_a?(Hash)
+            raise Serega::Error, "Option :#{meta_key} must be a Hash, but #{meta.class} was given"
+          end
+
+          super
+        end
+      end
+
+      module ConvertInstanceMethods
+        def to_h
+          super.tap do |hash|
+            add_context_metadata(hash)
+          end
+        end
+
+        private
+
+        def add_context_metadata(hash)
+          context_metadata_key = self.class.serializer_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
+        end
+      end
+    end
+
+    register_plugin(ContextMetadata.plugin_name, ContextMetadata)
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    module Formatters
+      def self.plugin_name
+        :formatters
+      end
+
+      def self.load_plugin(serializer_class, **_opts)
+        serializer_class::Attribute.include(AttributeInstanceMethods)
+      end
+
+      def self.after_load_plugin(serializer_class, **_opts)
+        config = serializer_class.config
+        config[plugin_name] = {}
+        config[:attribute_keys] << :format
+      end
+
+      module AttributeInstanceMethods
+        def value_block
+          return @value_block if instance_variable_defined?(:@value_block)
+
+          original_block = super
+          formatter = opts[:format]
+          return original_block unless formatter
+
+          @value_block = formatted_block(formatter, original_block)
+        end
+
+        private
+
+        def formatted_block(formatter, original_block)
+          proc do |object, context|
+            value = original_block.call(object, context)
+
+            if formatter.is_a?(Symbol)
+              self.class.serializer_class.config.fetch(:formatters).fetch(formatter).call(value)
+            else
+              formatter.call(value)
+            end
+          end
+        end
+      end
+    end
+
+    register_plugin(Formatters.plugin_name, Formatters)
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+class Serega
+  module Plugins
+    #
+    # Plugin adds `:hide_nil` option to attributes to delete them from final result
+    # if value is nil
+    #
+    module HideNil
+      # @return [Symbol] plugin name
+      def self.plugin_name
+        :hide_nil
+      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::Attribute.include(AttributeMethods)
+        serializer_class::Attribute::CheckOpts.extend(CheckOptsClassMethods)
+        serializer_class::ConvertItem.extend(ConvertItemClassMethods)
+      end
+
+      def self.after_load_plugin(serializer_class, **opts)
+        serializer_class.config[:attribute_keys] << :hide_nil
+      end
+
+      # Adds #hide_nil? Attribute instance method
+      module AttributeMethods
+        def hide_nil?
+          !!opts[:hide_nil]
+        end
+      end
+
+      module CheckOptsClassMethods
+        private
+
+        def check_each_opt(opts)
+          super
+          CheckOptHideNil.call(opts)
+        end
+      end
+
+      class CheckOptHideNil
+        #
+        # Checks attribute :hide_nil option
+        #
+        # @param opts [Hash] Attribute options
+        #
+        # @raise [Serega::Error] Error that option has invalid value
+        #
+        # @return [void]
+        #
+        def self.call(opts)
+          return unless opts.key?(:hide_nil)
+
+          value = opts[:hide_nil]
+          return if (value == true) || (value == false)
+
+          raise Error, "Invalid option :hide_nil => #{value.inspect}. Must have a boolean value"
+        end
+      end
+
+      module ConvertItemClassMethods
+        private
+
+        def attach_value(value, *args)
+          super unless value.nil?
+        end
+      end
+    end
+
+    register_plugin(HideNil.plugin_name, HideNil)
+  end
+end