serega 0.11.2 → 0.14.0

data/lib/serega/plugins/openapi/lib/modules/config.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module OpenAPI
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
+      module ConfigInstanceMethods
+        #
+        # Returns openapi plugin config
+        #
+        # @return [Serega::SeregaPlugins::OpenAPI::OpenAPIConfig] configuration for openapi plugin
+        #
+        def openapi
+          @openapi ||= OpenAPIConfig.new(self.class.serializer_class, opts.fetch(:openapi))
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/openapi/lib/openapi_config.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module OpenAPI
+      #
+      # OpenAPI plugin config
+      #
+      class OpenAPIConfig
+        attr_reader :serializer_class, :opts
+
+        def initialize(serializer_class, opts)
+          @serializer_class = serializer_class
+          @opts = opts
+        end
+
+        #
+        # Saves new properties
+        #
+        # @param new_properties [Hash] new properties
+        #
+        # @return [Hash] OpenAPI properties
+        #
+        def properties(new_properties = FROZEN_EMPTY_HASH)
+          properties = opts[:properties]
+          return properties if new_properties.empty?
+
+          new_properties = SeregaUtils::EnumDeepDup.call(new_properties)
+          symbolize_keys!(new_properties)
+
+          new_properties.each do |attribute_name, new_attribute_properties|
+            check_attribute_exists(attribute_name)
+            check_properties_is_a_hash(attribute_name, new_attribute_properties)
+
+            properties[attribute_name] = symbolize_keys!(new_attribute_properties)
+          end
+        end
+
+        #
+        # @return [#call] builder of `$ref` attribute
+        #
+        def ref_builder
+          opts[:ref_builder]
+        end
+
+        #
+        # Sets new $ref option builder
+        #
+        # @param builder [#call] Callable object that accepts serializer_class and constructs $ref option string
+        #
+        # @return Specified new builder
+        #
+        def ref_builder=(builder)
+          raise SeregaError, "ref_builder must respond to #call" unless builder.respond_to?(:call)
+          opts[:ref_builder] = builder
+        end
+
+        #
+        # @return [#call] builder of schema name
+        #
+        def schema_name_builder
+          opts[:schema_name_builder]
+        end
+
+        #
+        # Sets new schema_name_builder
+        #
+        # @param builder [#call] Callable object that accepts serializer_class and
+        #   constructs schema name to use in schemas list and in $ref option
+        #
+        # @return Specified new builder
+        #
+        def schema_name_builder=(builder)
+          raise SeregaError, "schema_name_builder must respond to #call" unless builder.respond_to?(:call)
+          opts[:schema_name_builder] = builder
+        end
+
+        private
+
+        def check_attribute_exists(attribute_name)
+          return if serializer_class.attributes.key?(attribute_name)
+
+          raise SeregaError, "No attribute with name :#{attribute_name}"
+        end
+
+        def check_properties_is_a_hash(attribute_name, new_attribute_properties)
+          return if new_attribute_properties.is_a?(Hash)
+
+          raise SeregaError, "Property #{attribute_name} value must be a Hash," \
+            " but #{new_attribute_properties.inspect} was provided"
+        end
+
+        def symbolize_keys!(opts)
+          opts.transform_keys! do |key|
+            key.to_sym
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/openapi/openapi.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Utility class to build OpenAPI schemas
+  #
+  class OpenAPI
+    #
+    # Constructs OpenAPI schemas for multiple serializers
+    #
+    # @params serializers [Class<Serega>] Serializers tobuild schemas,
+    #   by default it is all serializers with :openapi plugin enabled
+    #
+    # @return [Hash] Schemas hash
+    #
+    def self.schemas(serializers = self.serializers)
+      serializers.each_with_object({}) do |serializer_class, schemas|
+        schema = serializer_class.openapi_schema
+        schema_name = serializer_class.openapi_schema_name
+        schemas[schema_name] = schema
+      end
+    end
+
+    #
+    # Returns list of serializers with :openapi plugin
+    #
+    def self.serializers
+      @serializers ||= []
+    end
+  end
+
+  module SeregaPlugins
+    #
+    # Plugin :openapi
+    #
+    # Helps to build OpenAPI schemas
+    #
+    # This schemas can be easielty used with "rswag" gem by adding them to "config.swagger_docs"
+    #   https://github.com/rswag/rswag#referenced-parameters-and-schema-definitions
+    #
+    # This plugin only adds type "object" or "array" for relationships and marks
+    # attributes as **required** if they have no :hide option set.
+    #
+    # OpenAPI properties will have no any "type" or other options specified by default,
+    # you should provide them in 'YourSerializer.openapi_properties' method.
+    # `openapi_properties` can be specified multiple time, in this case they wil be merged.
+    #
+    # After enabling this plugin attributes with :serializer option will have
+    # to have :many option set to construct "object" or "array" openapi type for relationships.
+    #
+    # OpenAPI `$ref` property will be added automatically for all relationships.
+    #
+    # Example constructing all serializers schemas:
+    #   `Serega::OpenAPI.schemas`
+    #
+    # Example constructing specific serializers schemas:
+    #   `Serega::OpenAPI.schemas(Serega::OpenAPI.serializers - [MyBaseSerializer])`
+    #
+    # Example constructing one serializer schema:
+    #   `SomeSerializer.openapi_schema`
+    #
+    # @example
+    #   class BaseSerializer < Serega
+    #     plugin :openapi
+    #   end
+    #
+    #   class UserSerializer < BaseSerializer
+    #     attribute :name
+    #
+    #     openapi_properties(
+    #       name: { type: :string }
+    #     )
+    #   end
+    #
+    #   class PostSerializer < BaseSerializer
+    #     attribute :text
+    #     attribute :user, serializer: UserSerializer, many: false
+    #     attribute :comments, serializer: PostSerializer, many: true, hide: true
+    #
+    #     openapi_properties(
+    #       text: { type: :string },
+    #       user: { type: 'object' }, # `$ref` option will be added automatically when constructing schema
+    #       comments: { type: 'array' } # `items` option with `$ref` will be added automatically when constructing schema
+    #     )
+    #   end
+    #
+    #   puts Serega::OpenAPI.schemas
+    #   =>
+    #   {
+    #     "PostSerializer" => {
+    #       type: "object",
+    #       properties: {
+    #         text: {type: "string"},
+    #         user: {:$ref => "#/components/schemas/UserSerializer"},
+    #         comments: {type: "array", items: {:$ref => "#/components/schemas/PostSerializer"}}
+    #       },
+    #       required: [:text, :comments],
+    #       additionalProperties: false
+    #     },
+    #     "UserSerializer" => {
+    #       type: "object",
+    #       properties: {
+    #         name: {type: "string"}
+    #       },
+    #       required: [:name],
+    #       additionalProperties: false
+    #     }
+    #   }
+    #
+    module OpenAPI
+      # Builder for schema name (used is schemas list). Returns serializer class name
+      DEFAULT_SCHEMA_NAME_BUILDER = ->(serializer_class) { serializer_class.name }
+
+      # Builder for $ref openapi property
+      DEFAULT_REF_BUILDER = ->(serializer_class) { "#/components/schemas/#{serializer_class.openapi_schema_name}" }
+
+      # @return [Symbol] Plugin name
+      def self.plugin_name
+        :openapi
+      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)
+        unless serializer_class.plugin_used?(:explicit_many_option)
+          serializer_class.plugin :explicit_many_option
+        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)
+        require_relative "./lib/modules/config"
+        require_relative "./lib/openapi_config"
+
+        serializer_class.extend(ClassMethods)
+        serializer_class::SeregaConfig.include(ConfigInstanceMethods)
+
+        config = serializer_class.config
+        config.opts[:openapi] = {properties: {}}
+        openapi_config = serializer_class.config.openapi
+        openapi_config.schema_name_builder = opts[:schema_name_builder] || DEFAULT_SCHEMA_NAME_BUILDER
+        openapi_config.ref_builder = opts[:ref_builder] || DEFAULT_REF_BUILDER
+      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)
+        Serega::OpenAPI.serializers << serializer_class unless serializer_class.equal?(Serega)
+      end
+
+      #
+      # Serega additional/patched class methods
+      #
+      # @see Serega
+      #
+      module ClassMethods
+        #
+        # OpenAPI schema for current serializer
+        #
+        def openapi_schema
+          properties = SeregaUtils::EnumDeepDup.call(openapi_properties)
+          required_properties = []
+
+          attributes.each do |attribute_name, attribute|
+            add_openapi_property(properties, attribute_name, attribute)
+            add_openapi_required_property(required_properties, attribute_name, attribute)
+          end
+
+          {
+            type: "object",
+            properties: properties,
+            required: required_properties,
+            additionalProperties: false
+          }
+        end
+
+        #
+        # Adds new OpenAPI properties and returns all properties
+        #
+        # @param props [Hash] Specifies new properties
+        #
+        # @return [Hash] Specified OpenAPI properties
+        #
+        def openapi_properties(props = FROZEN_EMPTY_HASH)
+          config.openapi.properties(props)
+        end
+
+        #
+        # Builds OpenAPI schema name using configured builder
+        #
+        # @return [String] OpenAPI schema name
+        #
+        def openapi_schema_name
+          config.openapi.schema_name_builder.call(self)
+        end
+
+        private
+
+        def inherited(subclass)
+          super
+          Serega::OpenAPI.serializers << subclass
+        end
+
+        def add_openapi_property(properties, attribute_name, attribute)
+          property = properties[attribute_name] ||= {}
+          return unless attribute.relation?
+
+          ref = attribute.serializer.config.openapi.ref_builder.call(attribute.serializer)
+
+          if attribute.many
+            property[:type] = "array"
+            property[:items] ||= {}
+            property[:items][:$ref] ||= ref
+          else
+            property[:$ref] ||= ref
+          end
+        end
+
+        def add_openapi_required_property(required_properties, attribute_name, attribute)
+          required_properties << attribute_name unless attribute.hide
+        end
+      end
+    end
+
+    register_plugin(OpenAPI.plugin_name, OpenAPI)
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaAttribute additional/patched instance methods
+      #
+      # @see Serega::SeregaAttribute::AttributeInstanceMethods
+      #
+      module AttributeInstanceMethods
+        # @return [Hash, nil] normalized preloads of current attribute
+        attr_reader :preloads
+
+        # @return [Array] normalized preloads_path of current attribute
+        attr_reader :preloads_path
+
+        private
+
+        def set_normalized_vars(normalizer)
+          super
+          @preloads = normalizer.preloads
+          @preloads_path = normalizer.preloads_path
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaAttributeNormalizer additional/patched instance methods
+      #
+      # @see SeregaAttributeNormalizer::AttributeNormalizerInstanceMethods
+      #
+      module AttributeNormalizerInstanceMethods
+        # @return [Hash,nil] normalized attribute preloads
+        def preloads
+          return @preloads if instance_variable_defined?(:@preloads)
+
+          @preloads = prepare_preloads
+        end
+
+        # @return [Array, nil] normalized attribute preloads path
+        def preloads_path
+          return @preloads_path if instance_variable_defined?(:@preloads_path)
+
+          @preloads_path = prepare_preloads_path
+        end
+
+        private
+
+        #
+        # Patched in:
+        # - plugin :batch (extension :preloads - skips auto preloads when batch option provided)
+        #
+        def prepare_preloads
+          opts = init_opts
+          preloads_provided = opts.key?(:preload)
+          preloads =
+            if preloads_provided
+              opts[:preload]
+            elsif opts.key?(:serializer) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_serializer
+              key
+            elsif opts.key?(:delegate) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_delegate
+              opts[:delegate].fetch(:to)
+            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 prepare_preloads_path
+          path = init_opts.fetch(:preload_path) { default_preload_path(preloads) }
+
+          if path && path[0].is_a?(Array)
+            prepare_many_preload_paths(path)
+          else
+            prepare_one_preload_path(path)
+          end
+        end
+
+        def prepare_one_preload_path(path)
+          return unless path
+
+          case path
+          when Array
+            path.map(&:to_sym).freeze
+          else
+            [path.to_sym].freeze
+          end
+        end
+
+        def prepare_many_preload_paths(paths)
+          paths.map { |path| prepare_one_preload_path(path) }.freeze
+        end
+
+        def default_preload_path(preloads)
+          return FROZEN_EMPTY_ARRAY if !preloads || preloads.empty?
+
+          [preloads.keys.first]
+        end
+
+        #
+        # Patch for original `prepare_hide` method
+        # @see
+        #
+        # Marks attribute hidden if auto_hide_attribute_with_preloads option was set and attribute has preloads
+        #
+        def prepare_hide
+          res = super
+          return res unless res.nil?
+
+          if preloads && !preloads.empty?
+            self.class.serializer_class.config.preloads.auto_hide_attributes_with_preload || nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
+      module CheckAttributeParamsInstanceMethods
+        private
+
+        def check_opts
+          super
+          CheckOptPreload.call(opts)
+          CheckOptPreloadPath.call(opts)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
+      module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::Preloads::PreloadsConfig] `preloads` plugin config
+        def preloads
+          @preloads ||= PreloadsConfig.new(opts.fetch(:preloads))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaPlanPoint additional/patched instance methods
+      #
+      # @see Serega::SeregaPlanPoint::InstanceMethods
+      #
+      module PlanPointInstanceMethods
+        #
+        # @return [Hash] preloads for nested attributes
+        #
+        attr_reader :preloads
+
+        #
+        # @return [Array<Symbol>] preloads path for current attribute
+        #
+        attr_reader :preloads_path
+
+        private
+
+        def set_normalized_vars
+          super
+
+          @preloads = prepare_preloads
+          @preloads_path = prepare_preloads_path
+        end
+
+        def prepare_preloads
+          PreloadsConstructor.call(child_plan)
+        end
+
+        def prepare_preloads_path
+          attribute.preloads_path
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Utility that helps to transform preloads to array of paths
+      #
+      # Example:
+      #
+      #   call({ a: { b: { c: {}, d: {} } }, e: {} })
+      #
+      #   => [
+      #        [:a],
+      #        [:a, :b],
+      #        [:a, :b, :c],
+      #        [:a, :b, :d],
+      #        [:e]
+      #      ]
+      class PreloadPaths
+        class << self
+          #
+          # Transforms user provided preloads to array of paths
+          #
+          # @param value [Array,Hash,String,Symbol,nil,false] preloads
+          #
+          # @return [Hash] preloads transformed to hash
+          #
+          def call(preloads, path = [], result = [])
+            preloads = FormatUserPreloads.call(preloads)
+
+            preloads.each do |key, nested_preloads|
+              path << key
+              result << path.dup
+
+              call(nested_preloads, path, result)
+              path.pop
+            end
+
+            result
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Config for `preloads` plugin
+      #
+      class PreloadsConfig
+        # @return [Hash] preloads plugin options
+        attr_reader :opts
+
+        #
+        # Initializes PreloadsConfig object
+        #
+        # @param opts [Hash] options
+        #
+        # @return [Serega::SeregaPlugins::Preloads::PreloadsConfig]
+        #
+        def initialize(opts)
+          @opts = opts
+        end
+
+        # @!method auto_preload_attributes_with_delegate
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_preload_attributes_with_delegate=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
+        # @!method auto_preload_attributes_with_serializer
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_preload_attributes_with_serializer=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
+        # @!method auto_hide_attributes_with_preload
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_hide_attributes_with_preload=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
+        %i[
+          auto_preload_attributes_with_delegate
+          auto_preload_attributes_with_serializer
+          auto_hide_attributes_with_preload
+        ].each do |method_name|
+          define_method(method_name) do
+            opts.fetch(method_name)
+          end
+
+          define_method("#{method_name}=") do |value|
+            raise SeregaError, "Must have boolean value, #{value.inspect} provided" if (value != true) && (value != false)
+            opts[method_name] = value
+          end
+        end
+      end
+    end
+  end
+end