serega 0.42.0 → 0.50.0

data/lib/serega/object_serializer.rb

@@ -1,125 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  #
-  # Low-level class used by the serializer to construct the serialized response.
-  #
-  # Serialization is level-by-level. `#serialize` builds the result container(s)
-  # and enqueues this level; the batch queue later calls `#process` for each level,
-  # which resolves every attribute for every object and enqueues child levels for
-  # relations.
-  #
-  # @private
-  class SeregaObjectSerializer
-    #
-    # SeregaObjectSerializer instance methods
-    #
-    # @private
-    module InstanceMethods
-      attr_reader :context, :plan, :many, :opts, :level_queue, :presenter
-
-      # @param plan [SeregaPlan] Serialization plan
-      # @param context [Hash] Serialization context
-      # @param many [Boolean] is object is enumerable
-      # @param opts [Hash] Any custom options
-      #
-      # @return [SeregaObjectSerializer] New SeregaObjectSerializer
-      def initialize(context:, plan:, many: nil, **opts)
-        @context = context
-        @plan = plan
-        @many = many
-        @opts = opts
-        @level_queue = opts[:level_queue]
-        # Looked up once here and reused for every enqueued chunk of the level.
-        @presenter = self.class.serializer_class.presenter
-      end
-
-      # Enqueues this level and returns its result container(s). The containers are
-      # returned immediately but filled in place once the queue is processed.
-      #
-      # @param object [Object] Serialized object(s)
-      #
-      # @return [Hash, Array<Hash>, nil] Serialized object(s)
-      def serialize(object)
-        return if object.nil?
-
-        case serialize_mode(object)
-        when :many then enqueue(object.to_a)
-        when :many_for_one then enqueue([object]) # `many` on, but a sole object was given — wrap it, don't raise
-        else enqueue([object])[0] # :one
-        end
-      end
-
-      # Resolves every attribute of one level onto its containers. For each point,
-      # preloads and batch loaders run once over all of the level's objects; the
-      # value is then resolved and assigned per object, in attribute order.
-      #
-      # @param level [SeregaEngine::Level] level to resolve
-      # @return [void]
-      def process(level)
-        objects = level.objects
-
-        plan.points.each do |point|
-          point.run_preloads(objects)
-          batches = point.load_batches(level)
-          # One child serializer per relation point per level (reused for every object),
-          # instead of one per object — child objects are grouped into one child level anyway.
-          child_serializer = point.child_serializer(context: context, **opts)
-
-          objects.each_with_index do |object, index|
-            resolve_point(object, point, level.containers[index], batches, child_serializer)
-          rescue => error
-            SeregaUtils::SerializedAttributeError.call(error, point)
-          end
-        end
-      end
-
-      private
-
-      # Enqueues this chunk of objects onto the queue and returns their result
-      # containers. This is where objects enter their level, so every object a
-      # point resolves against and a batch loader receives has the same shape.
-      #
-      # Each object is wrapped in the serializer's presenter before it is enqueued,
-      # so the whole level — value resolution and batch loaders alike — sees
-      # presenters. Serializers without a presenter enqueue the objects as they
-      # are — wrapping would only add overhead and break class checks
-      # (object.is_a?, Hash === object) without changing anything.
-      def enqueue(objects)
-        objects = objects.map { |object| presenter.new(object, context) } if presenter
-
-        level_queue.enqueue(self, objects)
-      end
-
-      # Patched in:
-      # - plugin :if (skips the point for objects failing an :if/:unless condition)
-      def resolve_point(object, point, container, batches, child_serializer)
-        value = point.value(object, context, batches: batches)
-        final_value = child_serializer ? child_serializer.serialize(value) : value
-        write_value(final_value, point, container)
-      end
-
-      # Patched in:
-      # - plugin :if (skips assigning when an :if_value/:unless_value condition fails)
-      def write_value(final_value, point, container)
-        container[point.name] = final_value
-      end
-
-      # How to serialize `object`, deciding whether the result is a collection or a
-      # single object and checking the object type only once:
-      # - :many         — `many` is on and the object is a collection
-      # - :many_for_one — `many` is on but a sole object was given (wrap it, don't raise)
-      # - :one          — serialize the object on its own
-      def serialize_mode(object)
-        case many
-        when NilClass then SeregaUtils::CollectionDetector.call(object) ? :many : :one
-        when TrueClass then SeregaUtils::CollectionDetector.call(object) ? :many : :many_for_one
-        else :one # many == false
-        end
-      end
-    end
-
-    extend Serega::SeregaHelpers::SerializerClassHelper
-    include InstanceMethods
-  end
-end

data/lib/serega/plugins/camel_case/camel_case.rb

@@ -1,213 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaPlugins
-    #
-    # Plugin :camel_case
-    #
-    # CamelCases every attribute name automatically, replacing `_x` with `X`
-    # throughout the string. Runs once, when the attribute is defined, not on
-    # every serialization.
-    #
-    # Provide a custom transformation with
-    # `plugin :camel_case, transform: ->(name) { name.camelize }`.
-    #
-    # Skip camelCase for a single attribute with `camel_case: false`.
-    #
-    # @example Define plugin
-    #  class AppSerializer < Serega
-    #    plugin :camel_case
-    #  end
-    #
-    #  class UserSerializer < AppSerializer
-    #    attribute :first_name
-    #    attribute :last_name
-    #    attribute :full_name, camel_case: false, value: proc { |user| [user.first_name, user.last_name].compact.join(" ") }
-    #  end
-    #
-    #  require "ostruct"
-    #  user = OpenStruct.new(first_name: "Bruce", last_name: "Wayne")
-    #  UserSerializer.to_h(user) # {firstName: "Bruce", lastName: "Wayne", full_name: "Bruce Wayne"}
-    #
-    module CamelCase
-      # Default camel-case transformation
-      TRANSFORM_DEFAULT = proc { |attribute_name|
-        attribute_name.gsub!(/_[a-z]/) { |m| m[-1].upcase! }
-        attribute_name
-      }
-
-      # @return [Symbol] Plugin name
-      # @private
-      def self.plugin_name
-        :camel_case
-      end
-
-      # 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[transform]
-        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" \
-            "  - :transform [#call] - Custom transformation"
-        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::SeregaConfig.include(ConfigInstanceMethods)
-        serializer_class::SeregaAttributeNormalizer.include(AttributeNormalizerInstanceMethods)
-        serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
-      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
-        config.opts[:camel_case] = {}
-        config.camel_case.transform = opts[:transform] || TRANSFORM_DEFAULT
-
-        config.attribute_keys << :camel_case
-      end
-
-      #
-      # Config class additional/patched instance methods
-      #
-      # @see Serega::SeregaConfig
-      #
-      module ConfigInstanceMethods
-        # @return [Serega::SeregaPlugins::CamelCase::CamelCaseConfig] `camel_case` plugin config
-        def camel_case
-          @camel_case ||= CamelCaseConfig.new(opts.fetch(:camel_case))
-        end
-      end
-
-      #
-      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
-      #
-      # @see Serega::SeregaValidations::CheckAttributeParams
-      #
-      # @private
-      module CheckAttributeParamsInstanceMethods
-        private
-
-        def check_opts
-          super
-          CheckOptCamelCase.call(opts)
-        end
-      end
-
-      #
-      # Validator for attribute :camel_case option
-      #
-      # @private
-      class CheckOptCamelCase
-        class << self
-          #
-          # Checks attribute :camel_case option must be boolean
-          #
-          # @param opts [Hash] Attribute options
-          #
-          # @raise [SeregaError] Attribute validation error
-          #
-          # @return [void]
-          #
-          def call(opts)
-            camel_case_option_exists = opts.key?(:camel_case)
-            return unless camel_case_option_exists
-
-            value = opts[:camel_case]
-            return if value.equal?(true) || value.equal?(false)
-
-            raise SeregaError, "Attribute option :camel_case must have a boolean value, but #{value.class} was provided"
-          end
-        end
-      end
-
-      # CamelCase config object
-      class CamelCaseConfig
-        attr_reader :opts
-
-        #
-        # Initializes CamelCaseConfig object
-        #
-        # @param opts [Hash] camel_case plugin options
-        # @option opts [#call] :transform Callable object that transforms original attribute name
-        #
-        # @return [Serega::SeregaPlugins::CamelCase::CamelCaseConfig] CamelCaseConfig object
-        #
-        def initialize(opts)
-          @opts = opts
-        end
-
-        # @return [#call] defined object that transforms name
-        def transform
-          opts.fetch(:transform)
-        end
-
-        # Sets transformation callable object
-        #
-        # @param value [#call] transformation
-        #
-        # @return [#call] camel_case plugin transformation callable object
-        def transform=(value)
-          raise SeregaError, "Transform value must respond to #call" unless value.respond_to?(:call)
-
-          params = value.is_a?(Proc) ? value.parameters : value.method(:call).parameters
-          if params.count != 1 || !params.all? { |param| (param[0] == :req) || (param[0] == :opt) }
-            raise SeregaError, "Transform value must respond to #call and accept 1 regular parameter"
-          end
-
-          opts[:transform] = value
-        end
-      end
-
-      #
-      # SeregaAttributeNormalizer additional/patched instance methods
-      #
-      # @see SeregaAttributeNormalizer::AttributeInstanceMethods
-      #
-      # @private
-      module AttributeNormalizerInstanceMethods
-        private
-
-        #
-        # Patch for original `prepare_name` method
-        #
-        # Makes camelCased name
-        #
-        def prepare_name
-          res = super
-          return res if init_opts[:camel_case] == false
-
-          self.class.serializer_class.config.camel_case.transform.call(+res.to_s).to_sym
-        end
-      end
-    end
-
-    register_plugin(CamelCase.plugin_name, CamelCase)
-  end
-end

data/lib/serega/plugins/depth_limit/depth_limit.rb

@@ -1,206 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaPlugins
-    #
-    # Plugin :depth_limit
-    #
-    # Guards against malicious queries that serialize too much, or against
-    # accidentally serializing objects with cyclic relations.
-    #
-    # Depth limit is checked when a serialization plan is built, i.e. when
-    # `#new` is called (`SomeSerializer.new(with: params[:with])`) — including
-    # internally by every class-level serialization method. Instantiating the
-    # serializer early surfaces depth errors sooner.
-    #
-    # When the limit is exceeded, `Serega::DepthLimitError` is raised;
-    # details are available via `Serega::DepthLimitError#details`.
-    #
-    # Limit can be checked or changed with config options:
-    #
-    #   - config.depth_limit.limit
-    #   - config.depth_limit.limit=
-    #
-    # There is no default limit — it must be set when enabling the plugin.
-    #
-    # @example
-    #
-    #   class AppSerializer < Serega
-    #     plugin :depth_limit, limit: 10 # set limit for all child classes
-    #   end
-    #
-    #   class UserSerializer < AppSerializer
-    #     config.depth_limit.limit = 5 # overrides limit for UserSerializer
-    #   end
-    #
-    module DepthLimit
-      # @return [Symbol] Plugin name
-      # @private
-      def self.plugin_name
-        :depth_limit
-      end
-
-      # Checks requirements
-      #
-      # @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[limit]
-        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" \
-            "  - :limit [Integer] - Maximum serialization depth."
-        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::SeregaPlan.include(PlanInstanceMethods)
-        serializer_class::SeregaConfig.include(ConfigInstanceMethods)
-      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
-        limit = opts.fetch(:limit) { raise SeregaError, "Please provide :limit option. Example: `plugin :depth_limit, limit: 10`" }
-        config.opts[:depth_limit] = {}
-        config.depth_limit.limit = limit
-      end
-
-      # DepthLimit config object
-      class DepthLimitConfig
-        attr_reader :opts
-
-        #
-        # Initializes DepthLimitConfig object
-        #
-        # @param opts [Hash] depth_limit plugin options
-        #
-        # @return [SeregaPlugins::DepthLimit::DepthLimitConfig] DepthLimitConfig object
-        #
-        def initialize(opts)
-          @opts = opts
-        end
-
-        # @return [Integer] defined depth limit
-        def limit
-          opts.fetch(:limit)
-        end
-
-        #
-        # Set depth limit
-        #
-        # @param value [Integer] depth limit
-        #
-        # @return [Integer] depth limit
-        def limit=(value)
-          raise SeregaError, "Depth limit must be an Integer" unless value.is_a?(Integer)
-
-          opts[:limit] = value
-        end
-      end
-
-      #
-      # Serega::SeregaConfig additional/patched class methods
-      #
-      # @see Serega::SeregaConfig
-      #
-      module ConfigInstanceMethods
-        # @return [Serega::SeregaPlugins::DepthLimit::DepthLimitConfig] current depth_limit config
-        def depth_limit
-          @depth_limit ||= DepthLimitConfig.new(opts.fetch(:depth_limit))
-        end
-      end
-
-      #
-      # SeregaPlan additional/patched instance methods
-      #
-      # @see SeregaPlan
-      #
-      # @private
-      module PlanInstanceMethods
-        #
-        # Initializes serialization plan
-        # Overrides original method (adds depth_limit validation)
-        #
-        def initialize(parent_plan_point, *)
-          check_depth_limit_exceeded(parent_plan_point)
-          super
-        end
-
-        private
-
-        def check_depth_limit_exceeded(current_point)
-          plan = self
-          depth_level = 1
-          point = current_point
-
-          while point
-            depth_level += 1
-            plan = point.plan
-            point = plan.parent_plan_point
-          end
-
-          root_serializer = plan.class.serializer_class
-          root_depth_limit = root_serializer.config.depth_limit.limit
-
-          if depth_level > root_depth_limit
-            fields_chain = [current_point.name]
-            fields_chain << current_point.name while (current_point = current_point.plan.parent_plan_point)
-            details = "#{root_serializer} (depth limit: #{root_depth_limit}) -> #{fields_chain.reverse!.join(" -> ")}"
-            raise DepthLimitError.new("Depth limit was exceeded", details)
-          end
-        end
-      end
-    end
-
-    register_plugin(DepthLimit.plugin_name, DepthLimit)
-  end
-
-  #
-  # Special error for depth_limit plugin
-  #
-  class DepthLimitError < SeregaError
-    #
-    # Details of why depth limit error happens.
-    #
-    # @return [String] error details
-    #
-    attr_reader :details
-
-    #
-    # Initializes new error
-    #
-    # @param message [String] Error message
-    # @param details [String] Error additional details
-    #
-    # @return [DepthLimitError] error instance
-    #
-    def initialize(message, details = nil)
-      super(message)
-      @details = details
-    end
-  end
-end

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

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaPlugins
-    #
-    # Plugin :explicit_many_option
-    #
-    # Requires the `:many` option on every relationship attribute (an
-    # attribute with the `:serializer` option or a block defining a nested
-    # serializer), so it's always explicit whether it returns one object or many.
-    #
-    # @example
-    #   class BaseSerializer < Serega
-    #     plugin :explicit_many_option
-    #     config.base_serializer = self
-    #   end
-    #
-    #   class PostSerializer < BaseSerializer
-    #     attribute :text
-    #
-    #     attribute :user, many: false do
-    #       attribute :name
-    #     end
-    #
-    #     attribute :comments, serializer: PostSerializer, many: true
-    #   end
-    #
-    module ExplicitManyOption
-      # @return [Symbol] Plugin name
-      # @private
-      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] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      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
-      #
-      # @private
-      module CheckAttributeParamsInstanceMethods
-        private
-
-        def check_opts
-          super
-
-          CheckOptMany.call(opts, block)
-        end
-      end
-    end
-
-    register_plugin(ExplicitManyOption.plugin_name, ExplicitManyOption)
-  end
-end

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

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaPlugins
-    module ExplicitManyOption
-      #
-      # Validator for attribute :many option
-      #
-      # @private
-      class CheckOptMany
-        class << self
-          #
-          # Checks attribute :many option must be provided with relations
-          # (attributes with the :serializer option or a block defining
-          # a nested serializer)
-          #
-          # @param opts [Hash] Attribute options
-          # @param block [nil, Proc] Attribute block
-          #
-          # @raise [SeregaError] Attribute validation error
-          #
-          # @return [void]
-          #
-          def call(opts, block = nil)
-            return if !opts[:serializer] && !block
-
-            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 or a block"
-          end
-        end
-      end
-    end
-  end
-end