serega 0.11.2 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b4a68e91572d22cf24e20a79cc788f647eb63e16582f0e33497eec459692de1
-  data.tar.gz: 8d3a55c8fd783b00c55cb08ed8f62c0f47cb79573ccbdc9f65c6710489d0dd0f
+  metadata.gz: f11821b5953500ef9f895ad8c96e97951734615363f3147c623b70519b6199a5
+  data.tar.gz: 8b03241a9def2e5a8777a75e61062f8b81544e497a1a1e490e085d52f14a326c
 SHA512:
-  metadata.gz: 67cb15aafd0dd90dd301a2ae79643c93204c52c26752649f96e904d2e1fe75d37709c91474c891eb73d1ee913002c214fc2c0288a613f82ad082ee385b149338
-  data.tar.gz: c421133bba5f4be2227a266bf6eb6fa6013f0320741f4e842575823d3a6d9e93bf37e8029b9fa801b2bcede964679c19fe794a1f7f0dceb10909c98251db588b
+  metadata.gz: eb5cb48e74c0e9c8307c6ceb6c47b918eb46ef3c160de90d0eb976239bbc036f1d3fb78219abd5567977f348e3e03d7e492e29140e6d85223fcf14289d794d89
+  data.tar.gz: acb7623ea317aab640aae70d0a5dfa0c436b706529741b36b15d938ab6af7523576f72ab4633b591b61dcdc38df768818eab3811005c248c3a00d2872cdccc46

data/README.md

@@ -415,30 +415,79 @@ UserSerializer.new(
 ```
 
 ---
-One tricky case, that you will probably never see in real life:
 
-Manually you can preload multiple associations, like this:
+#### SPECIFIC CASE #1: Serializing same object as association
+
+For example you decided to show your current user as "user" and "user_stats".
+Where stats rely on user fields and some other associations.
+You should specify `preload: nil` to preload nested associations, if any, to "user".
 
 ```ruby
-attribute :image,
-  serializer: ImageSerializer,
-  preload: { attachment: :blob },
-  value: proc { |record| record.attachment }
+class AppSerializer < Serega
+  plugin :preloads,
+    auto_preload_attributes_with_delegate: true,
+    auto_preload_attributes_with_serializer: true,
+    auto_hide_attributes_with_preload: true
+end
+
+class UserSerializer < AppSerializer
+  attribute :username
+  attribute :user_stats,
+    serializer: 'UserStatSerializer'
+    value: proc { |user| user },
+    preload: nil
+end
+```
+
+#### SPECIFIC CASE #2: Serializing multiple associations as single relation
+
+For example "user" has two relations - "new_profile", "old_profile", and also
+profiles have "avatar" association. And you decided to serialize profiles in one
+array. You can specify `preload_path: [[:new_profile], [:old_profile]]` to
+achieve this:
+
+```ruby
+class AppSerializer < Serega
+  plugin :preloads,
+    auto_preload_attributes_with_delegate: true,
+    auto_preload_attributes_with_serializer: true
+end
+
+class UserSerializer < AppSerializer
+  attribute :username
+  attribute :profiles,
+    serializer: 'ProfileSerializer',
+    value: proc { |user| [user.new_profile, user.old_profile] },
+    preload: [:new_profile, :old_profile],
+    preload_path: [[:new_profile], [:old_profile]] # <--- like here
+end
+
+class ProfileSerializer < AppSerializer
+  attribute :avatar, serializer: 'AvatarSerializer'
+end
+
+class AvatarSerializer < AppSerializer
+end
+
+UserSerializer.new.preloads
+# => {:new_profile=>{:avatar=>{}}, :old_profile=>{:avatar=>{}}}
 ```
 
-In this case we mark last element (in this case it will be `blob`) as main,
-so nested associations, if any, will be preloaded to this `blob`.
-If you need to preload them to `attachment`,
-please specify additionally `:preload_path` option like this:
+#### SPECIFIC CASE #3: Preload association through another association
 
 ```ruby
 attribute :image,
+  preload: { attachment: :blob }, # <--------- like this one
+  value: proc { |record| record.attachment },
   serializer: ImageSerializer,
-  preload: { attachment: :blob },
-  preload_path: %i[attachment],
-  value: proc { |record| record.attachment }
+  preload_path: [:attachment] # or preload_path: [:attachment, :blob]
 ```
 
+In this case we don't know if preloads defined in ImageSerializer, should be
+preloaded to `attachment` or `blob`, so please specify `preload_path` manually.
+You can specify `preload_path: nil` if you are sure that there are no preloads
+inside ImageSerializer.
+
 ---
 
 📌 Plugin `:preloads` only allows to group preloads together in single Hash, but
@@ -839,6 +888,107 @@ Look at [select serialized fields](#selecting-fields) for `:hide` usage examples
  end
 ```
 
+### Plugin :openapi
+
+Helps to build OpenAPI schemas
+
+This schemas can be easily used with [rswag](https://github.com/rswag/rswag#referenced-parameters-and-schema-definitions)"
+gem by adding them to "config.swagger_docs"
+
+Schemas properties will have no any "type" or other limits specified by default,
+you should provide them as new attribute `:openapi` option.
+
+This plugin adds type "object" or "array" only for relationships and marks
+attributes as **required** if they have no `:hide` option set
+(manually or automatically).
+
+After enabling this plugin attributes with :serializer option will have
+to have `:many` option set to construct "object" or "array" openapi
+property type.
+
+- constructing all serializers schemas:
+  `Serega::OpenAPI.schemas`
+- constructing specific serializers schemas:
+  `Serega::OpenAPI.schemas(Serega::OpenAPI.serializers - [MyBaseSerializer])`
+- constructing one serializer schema:
+  `SomeSerializer.openapi_schema`
+
+```ruby
+  class BaseSerializer < Serega
+    plugin :openapi
+  end
+
+  class UserSerializer < BaseSerializer
+    attribute :name, openapi: { type: "string" }
+
+    openapi_properties(
+      name: { type: :string }
+    )
+  end
+
+  class PostSerializer < BaseSerializer
+    attribute :text, openapi: { type: "string" }
+    attribute :user, serializer: UserSerializer, many: false
+    attribute :comments, serializer: PostSerializer, many: true, hide: true
+
+    openapi_properties(
+      text: { type: :string },
+      user: { type: 'object' }, # `$ref` added automatically
+      comments: { type: 'array' } # `items` option with `$ref` added automatically
+    )
+  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
+  #   }
+  # }
+```
+
+### Plugin :explicit_many_option
+
+Plugin requires to add :many option when adding relationships
+(relationships are attributes with :serializer option specified)
+
+Adding this plugin makes clearer to find if relationship returns array or single
+object
+
+Also plugin `:openapi` load this plugin automatically as it need to know if
+relationship is array
+
+```ruby
+  class BaseSerializer < Serega
+    plugin :explicit_many_option
+  end
+
+  class UserSerializer < BaseSerializer
+    attribute :name
+  end
+
+  class PostSerializer < BaseSerializer
+    attribute :text
+    attribute :user, serializer: UserSerializer, many: false
+    attribute :comments, serializer: PostSerializer, many: true
+  end
+```
+
 ## Errors
 
 - `Serega::SeregaError` is a base error raised by this gem.

data/VERSION

@@ -1 +1 @@
-0.11.2
+0.14.0

data/lib/serega/attribute.rb

@@ -82,13 +82,18 @@ class Serega
       #
       # 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
+      # @param modifiers [Hash] Serialization modifiers
+      # @option modifiers [Hash] :only The only attributes to serialize
+      # @option modifiers [Hash] :except Attributes to hide
+      # @option modifiers [Hash] :with Hidden attributes to serialize additionally
       #
       # @return [Boolean]
       #
-      def visible?(except:, only:, with:)
+      def visible?(modifiers)
+        except = modifiers[:except] || FROZEN_EMPTY_HASH
+        only = modifiers[:only] || FROZEN_EMPTY_HASH
+        with = modifiers[:with] || FROZEN_EMPTY_HASH
+
         return false if except.member?(name) && except[name].empty?
         return true if only.member?(name)
         return true if with.member?(name)

data/lib/serega/attribute_normalizer.rb

@@ -107,6 +107,7 @@ class Serega
       #
       # Patched in:
       # - plugin :preloads (returns true by default if config option auto_hide_attribute_with_preloads is enabled)
+      # - plugin :batch (returns true by default if auto_hide option was set and attribute has batch loader)
       #
       def prepare_hide
         init_opts[:hide]
@@ -135,7 +136,7 @@ class Serega
       def prepare_keyword_block
         key_method_name = key
         proc do |object|
-          handle_no_method_error { object.public_send(key_method_name) }
+          object.public_send(key_method_name)
         end
       end
 
@@ -150,24 +151,14 @@ class Serega
 
         if allow_nil
           proc do |object|
-            handle_no_method_error do
-              object.public_send(delegate_to)&.public_send(key_method_name)
-            end
+            object.public_send(delegate_to)&.public_send(key_method_name)
           end
         else
           proc do |object|
-            handle_no_method_error do
-              object.public_send(delegate_to).public_send(key_method_name)
-            end
+            object.public_send(delegate_to).public_send(key_method_name)
           end
         end
       end
-
-      def handle_no_method_error
-        yield
-      rescue NoMethodError => error
-        raise error, "NoMethodError when serializing '#{name}' attribute in #{self.class.serializer_class}\n\n#{error.message}", error.backtrace
-      end
     end
 
     extend Serega::SeregaHelpers::SerializerClassHelper

data/lib/serega/object_serializer.rb

@@ -47,6 +47,10 @@ class Serega
       def serialize_object(object)
         plan.points.each_with_object({}) do |point, container|
           serialize_point(object, point, container)
+        rescue SeregaError
+          raise
+        rescue => error
+          reraise_with_serialized_attribute_details(error, point)
         end
       end
 
@@ -85,6 +89,13 @@ class Serega
       def array?(object, many)
         many.nil? ? object.is_a?(Enumerable) : many
       end
+
+      def reraise_with_serialized_attribute_details(error, point)
+        raise error.exception(<<~MESSAGE.strip)
+          #{error.message}
+          (when serializing '#{point.name}' attribute in #{self.class.serializer_class})
+        MESSAGE
+      end
     end
 
     extend Serega::SeregaHelpers::SerializerClassHelper

data/lib/serega/plan.rb

@@ -22,34 +22,22 @@ class Serega
       #
       def call(opts)
         max_cache_size = serializer_class.config.max_cached_plans_per_serializer_count
-        return plan_for(opts) if max_cache_size.zero?
+        return new(opts) if max_cache_size.zero?
 
         cached_plan_for(opts, max_cache_size)
       end
 
       private
 
-      def plan_for(opts)
-        new(**modifiers(opts))
-      end
-
       def cached_plan_for(opts, max_cache_size)
         @cache ||= {}
         cache_key = construct_cache_key(opts)
 
-        plan = @cache[cache_key] ||= plan_for(opts)
+        plan = @cache[cache_key] ||= new(opts)
         @cache.shift if @cache.length > max_cache_size
         plan
       end
 
-      def modifiers(opts)
-        {
-          only: opts[:only] || FROZEN_EMPTY_HASH,
-          except: opts[:except] || FROZEN_EMPTY_HASH,
-          with: opts[:with] || FROZEN_EMPTY_HASH
-        }
-      end
-
       def construct_cache_key(opts, cache_key = nil)
         return nil if opts.empty?
 
@@ -69,10 +57,14 @@ class Serega
     # SeregaPlan instance methods
     #
     module InstanceMethods
-      # Parent plan point, if exists
+      # Parent plan point
       # @return [SeregaPlanPoint, nil]
       attr_reader :parent_plan_point
 
+      # Sets new parent plan point
+      # @return [SeregaPlanPoint] new parent plan point
+      attr_writer :parent_plan_point
+
       # Serialization points
       # @return [Array<SeregaPlanPoint>] points to serialize
       attr_reader :points
@@ -80,17 +72,15 @@ class Serega
       #
       # Instantiate new serialization plan.
       #
-      # @param opts Serialization parameters
-      # @option opts [Hash] :only The only attributes to serialize
-      # @option opts [Hash] :except Attributes to hide
-      # @option opts [Hash] :with Attributes (usually marked hide: true`) to serialize additionally
-      # @option opts [Hash] :with Attributes (usually marked hide: true`) to serialize additionally
+      # @param modifiers Serialization parameters
+      # @option modifiers [Hash] :only The only attributes to serialize
+      # @option modifiers [Hash] :except Attributes to hide
+      # @option modifiers [Hash] :with Hidden attributes to serialize additionally
       #
       # @return [SeregaPlan] Serialization plan
       #
-      def initialize(only:, except:, with:, parent_plan_point: nil)
-        @parent_plan_point = parent_plan_point
-        @points = attributes_points(only: only, except: except, with: with)
+      def initialize(modifiers)
+        @points = attributes_points(modifiers)
       end
 
       #
@@ -102,7 +92,10 @@ class Serega
 
       private
 
-      def attributes_points(only:, except:, with:)
+      def attributes_points(modifiers)
+        only = modifiers[:only] || FROZEN_EMPTY_HASH
+        except = modifiers[:except] || FROZEN_EMPTY_HASH
+        with = modifiers[:with] || FROZEN_EMPTY_HASH
         points = []
 
         serializer_class.attributes.each_value do |attribute|
@@ -114,7 +107,9 @@ class Serega
               {only: only[name], with: with[name], except: except[name]}
             end
 
-          points << serializer_class::SeregaPlanPoint.new(attribute, self, child_fields)
+          point = serializer_class::SeregaPlanPoint.new(attribute, child_fields)
+          point.plan = self
+          points << point.freeze
         end
 
         points.freeze

data/lib/serega/plan_point.rb

@@ -13,7 +13,7 @@ class Serega
 
       # Link to current plan this point belongs to
       # @return [SeregaAttribute] Current plan
-      attr_reader :plan
+      attr_accessor :plan
 
       # Shows current attribute
       # @return [SeregaAttribute] Current attribute
@@ -24,8 +24,8 @@ class Serega
       attr_reader :child_plan
 
       # Child fields to serialize
-      # @return [SeregaPlan, nil] Attribute serialization plan
-      attr_reader :child_fields
+      # @return [Hash] Attributes to serialize
+      attr_reader :modifiers
 
       # @!method name
       #   Attribute `name`
@@ -44,18 +44,18 @@ class Serega
       #
       # Initializes plan point
       #
-      # @param plan [SeregaPlan] Plan where this point belongs to.
       # @param attribute [SeregaAttribute] Attribute to construct plan point
-      # @param child_fields [Hash, nil] Child fields (:only, :with, :except)
+      # @param modifiers Serialization parameters
+      # @option modifiers [Hash] :only The only attributes to serialize
+      # @option modifiers [Hash] :except Attributes to hide
+      # @option modifiers [Hash] :with Hidden attributes to serialize additionally
       #
       # @return [SeregaPlanPoint] New plan point
       #
-      def initialize(attribute, plan = nil, child_fields = nil)
-        @plan = plan
+      def initialize(attribute, modifiers = nil)
         @attribute = attribute
-        @child_fields = child_fields
+        @modifiers = modifiers
         set_normalized_vars
-        freeze
       end
 
       #
@@ -77,14 +77,11 @@ class Serega
       def prepare_child_plan
         return unless serializer
 
-        fields = child_fields || FROZEN_EMPTY_HASH
+        fields = modifiers || FROZEN_EMPTY_HASH
 
-        serializer::SeregaPlan.new(
-          parent_plan_point: self,
-          only: fields[:only] || FROZEN_EMPTY_HASH,
-          with: fields[:with] || FROZEN_EMPTY_HASH,
-          except: fields[:except] || FROZEN_EMPTY_HASH
-        )
+        plan = serializer::SeregaPlan.new(fields)
+        plan.parent_plan_point = self
+        plan
       end
     end
 

data/lib/serega/plugins/batch/lib/loader.rb

@@ -60,6 +60,10 @@ class Serega
 
           private
 
+          def keys
+            @keys ||= {}
+          end
+
           def each_key
             keys.each do |key, containers|
               containers.each do |container|
@@ -74,16 +78,30 @@ class Serega
           def keys_values
             ids = keys.keys
 
-            point.batch[:loader].call(ids, object_serializer.context, point).tap do |vals|
-              next if vals.is_a?(Hash)
+            keys_values = load_keys_values(ids)
+            validate(keys_values)
 
-              attribute_name = "#{point.class.serializer_class}.#{point.name}"
-              raise SeregaError, "Batch loader for `#{attribute_name}` must return Hash, but #{vals.inspect} was returned"
-            end
+            keys_values
           end
 
-          def keys
-            @keys ||= {}
+          def load_keys_values(ids)
+            point.batch[:loader].call(ids, object_serializer.context, point)
+          rescue => error
+            raise reraise_with_serialized_attribute_details(error, point)
+          end
+
+          def validate(keys_values)
+            return if keys_values.is_a?(Hash)
+
+            attribute_name = "#{point.class.serializer_class}.#{point.name}"
+            raise SeregaError, "Batch loader for `#{attribute_name}` must return Hash, but #{keys_values.inspect} was returned"
+          end
+
+          def reraise_with_serialized_attribute_details(error, point)
+            raise error.exception(<<~MESSAGE.strip)
+              #{error.message}
+              (when serializing '#{point.name}' attribute in #{self.class.serializer_class})
+            MESSAGE
           end
         end
 

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

@@ -49,9 +49,7 @@ class Serega
           key = batch[:key] || self.class.serializer_class.config.batch.default_key
           proc_key =
             if key.is_a?(Symbol)
-              proc do |object|
-                handle_no_method_error { object.public_send(key) }
-              end
+              proc { |object| object.public_send(key) }
             else
               key
             end
@@ -61,12 +59,6 @@ class Serega
 
           {loader: loader, key: proc_key, default: default}
         end
-
-        def handle_no_method_error
-          yield
-        rescue NoMethodError => error
-          raise error, "NoMethodError when serializing '#{name}' attribute in #{self.class.serializer_class}\n\n#{error.message}", error.backtrace
-        end
       end
     end
   end

data/lib/serega/plugins/explicit_many_option/explicit_many_option.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    #
+    # Plugin :explicit_many_option
+    #
+    # Plugin requires to add :many option when adding relationships
+    # (relationships are attributes with :serializer option specified)
+    #
+    # Adding this plugin makes clearer to find if relationship returns array or single object
+    #
+    # Also some plugins like :openapi load this plugin automatically as they need to know if
+    # relationship is array
+    #
+    # @example
+    #   class BaseSerializer < Serega
+    #     plugin :explicit_many_option
+    #   end
+    #
+    #   class UserSerializer < BaseSerializer
+    #     attribute :name
+    #   end
+    #
+    #   class PostSerializer < BaseSerializer
+    #     attribute :text
+    #     attribute :user, serializer: UserSerializer, many: false
+    #     attribute :comments, serializer: PostSerializer, many: true
+    #   end
+    #
+    module ExplicitManyOption
+      # @return [Symbol] Plugin name
+      def self.plugin_name
+        :explicit_many_option
+      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 "./validations/check_opt_many"
+
+        serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
+      end
+
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
+      module CheckAttributeParamsInstanceMethods
+        private
+
+        def check_opts
+          super
+
+          CheckOptMany.call(opts)
+        end
+      end
+    end
+
+    register_plugin(ExplicitManyOption.plugin_name, ExplicitManyOption)
+  end
+end

data/lib/serega/plugins/explicit_many_option/validations/check_opt_many.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module ExplicitManyOption
+      #
+      # Validator for attribute :many option
+      #
+      class CheckOptMany
+        class << self
+          #
+          # Checks attribute :many option must be provided with relations
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
+          def call(opts)
+            serializer = opts[:serializer]
+            return unless serializer
+
+            many_option_exists = opts.key?(:many)
+            return if many_option_exists
+
+            raise SeregaError,
+              "Attribute option :many [Boolean] must be provided" \
+              " for attributes with :serializer option"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -194,6 +194,11 @@ class Serega
             next unless metadata
 
             deep_merge_metadata(hash, metadata)
+          rescue => error
+            raise error.exception(<<~MESSAGE.strip)
+              #{error.message}
+              (when serializing meta_attribute #{meta_attribute.path.inspect} in #{self.class})
+            MESSAGE
           end
         end