serega 0.42.0 → 0.50.0

data/lib/serega/batch_loader.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Named batch loader. Loads values of many objects in one call.
+  #
+  class SeregaBatchLoader # :nodoc:
+    # Batch loader name
+    attr_reader :name
+
+    # Batch loader block
+    attr_reader :block
+
+    # Initializes new batch loader
+    def initialize(name:, block:)
+      SeregaValidations::CheckBatchLoaderParams.new(name, block).validate
+
+      @name = name.to_sym
+      @block = block
+      @signature = SeregaUtils::MethodSignature.call(block, pos_limit: 2, keyword_args: [:ctx])
+    end
+
+    # Loads values for objects
+    def load(objects, context)
+      case signature
+      when "1" then block.call(objects)
+      when "2" then block.call(objects, context)
+      else block.call(objects, ctx: context) # "1_ctx"
+      end
+    end
+
+    private
+
+    # Batch loader block signature
+    attr_reader :signature
+  end
+end

data/lib/serega/conditions.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # The :if, :unless, :if_value and :unless_value conditions of one attribute.
+  # Each object defines `#satisfy?(object, context)`, which checks :if and
+  # :unless, and `#satisfy_value?(value, context)`, which checks :if_value
+  # and :unless_value. Each method is one line of code at the file and line
+  # of the attribute, and calls the conditions directly, for example:
+  #
+  #   def satisfy?(object, context) = (begin; object.active; rescue => error; ...; end)
+  #
+  class SeregaConditions # :nodoc:
+    def initialize(attribute, conditions)
+      @attribute = attribute
+      @conditions = conditions
+      satisfy_code = "def satisfy?(object, context) = #{check_code(:if, :unless)}"
+      satisfy_value_code = "def satisfy_value?(object, context) = #{check_code(:if_value, :unless_value)}"
+      attribute.define_methods(singleton_class, "#{satisfy_code}; #{satisfy_value_code}")
+    end
+
+    private
+
+    # Code that is true when the object passes the :if and does not match the
+    # :unless condition
+    def check_code(if_name, unless_name)
+      checks = []
+      checks << rescued_call_code(if_name) if @conditions.key?(if_name)
+      checks << "!#{rescued_call_code(unless_name)}" if @conditions.key?(unless_name)
+      checks.empty? ? "true" : checks.join(" && ")
+    end
+
+    # Code that calls the condition. An error raised there gets the condition
+    # name.
+    def rescued_call_code(name)
+      "(begin; #{call_code(name)}; rescue => error; " \
+        "Serega::SeregaUtils::SerializedAttributeError.condition(error, @attribute, #{name.inspect}); end)"
+    end
+
+    # Code that calls the condition with the parameters of its signature
+    def call_code(name)
+      condition = @conditions[name]
+      keyword_code = condition.code("object") if condition.is_a?(AttributeValueResolvers::Keyword)
+      return keyword_code if keyword_code
+
+      callable = "@conditions[#{name.inspect}]"
+      case SeregaUtils::MethodSignature.call(condition, pos_limit: 2, keyword_args: [:ctx])
+      when "1" then "#{callable}.call(object)"
+      when "2" then "#{callable}.call(object, context)"
+      when "1_ctx" then "#{callable}.call(object, ctx: context)"
+      when "2_ctx" then "#{callable}.call(object, context, ctx: context)"
+      else "#{callable}.call" # "0"
+      end
+    end
+  end
+end

data/lib/serega/config.rb

@@ -1,37 +1,32 @@
 # frozen_string_literal: true
 
 class Serega
+  # Config of a serializer, `config` in a serializer class. Subclasses copy
+  # the config of their parent and can change it.
   #
-  # Stores serialization config
+  # ```ruby
+  # class AppSerializer < Serega
+  #   config.auto_preload = true
+  #   config.hide_by_default = :auto
+  # end
+  # ```
   #
+  # See [Configuration](https://github.com/andreyruby/serega/blob/master/docs/configuration.md).
   class SeregaConfig
     # :nocov: We can't use both :oj and :json adapters together
 
     #
     # Default config options
     #
-    DEFAULTS = {
+    DEFAULTS = { # :nodoc:
       plugins: [],
-      initiate_keys: %i[only with except check_initiate_params].freeze,
-      attribute_keys: %i[
-        method
-        value
-        serializer
-        many
-        hide
-        const
-        delegate
-        default
-        preload
-        batch
-        base_serializer
-        hash_access
-      ].freeze,
       serialize_keys: %i[context many].freeze,
       check_attribute_name: true,
+      require_many: false,
       check_initiate_params: true,
       delegate_default_allow_nil: false,
-      max_cached_plans_per_serializer_count: 0,
+      max_cached_plans_per_serializer_count: 20,
+      depth_limit: nil,
       auto_preload: {has_delegate_option: false, has_serializer_option: false},
       auto_preload_excluded_methods: %i[itself __getobj__].freeze,
       hide_by_default: false,
@@ -41,99 +36,58 @@ class Serega
     }.freeze
     # :nocov:
 
-    # SeregaConfig Instance methods
+    # Config options
     module SeregaConfigInstanceMethods
-      #
       # Shows current config as Hash
-      #
-      # @return [Hash] config options
-      #
-      attr_reader :opts
+      attr_reader :opts # :nodoc:
 
-      #
       # Initializes new config instance.
-      #
-      # @param opts [Hash] Initial config options
-      #
-      def initialize(opts = nil)
+      def initialize(opts = nil) # :nodoc:
         opts ||= DEFAULTS
         @opts = SeregaUtils::EnumDeepDup.call(opts)
+        @hash_access = nil
+        @plugin_configs = {}
       end
 
-      #
       # Shows used plugins
-      #
-      # @return [Array] Used plugins
-      #
-      def plugins
+      def plugins # :nodoc:
         opts.fetch(:plugins)
       end
 
-      # Returns options names allowed in `Serega#new` method
-      # @return [Array<Symbol>] allowed options keys
-      def initiate_keys
-        opts.fetch(:initiate_keys)
-      end
-
-      # Returns options names allowed in `Serega.attribute` method
-      # @return [Array<Symbol>] Allowed options keys for attribute initialization
-      def attribute_keys
-        opts.fetch(:attribute_keys)
-      end
-
       # Returns options names allowed in `call, to_h` methods
-      # @return [Array<Symbol>] Allowed options keys for serialization
-      def serialize_keys
+      def serialize_keys # :nodoc:
         opts.fetch(:serialize_keys)
       end
 
-      # Returns :check_initiate_params config option
-      # @return [Boolean] Current :check_initiate_params config option
+      # Whether unknown fields of `only:`, `except:` and `with:` raise
+      # `Serega::AttributeNotExist`. `true` by default.
       def check_initiate_params
         opts.fetch(:check_initiate_params)
       end
 
-      # Sets :check_initiate_params config option
-      #
-      # @param value [Boolean] Set :check_initiate_params config option
-      #
-      # @return [Boolean] :check_initiate_params config option
+      # Sets #check_initiate_params
       def check_initiate_params=(value)
-        raise SeregaError, "Must have boolean value, #{value.inspect} provided" if (value != true) && (value != false)
-        opts[:check_initiate_params] = value
+        opts[:check_initiate_params] = checked_boolean(value)
       end
 
-      # Returns :delegate_default_allow_nil config option
-      # @return [Boolean] Current :delegate_default_allow_nil config option
+      # Default `allow_nil:` of the `:delegate` attribute option. `false` by
+      # default.
       def delegate_default_allow_nil
         opts.fetch(:delegate_default_allow_nil)
       end
 
-      # Sets :delegate_default_allow_nil config option
-      #
-      # @param value [Boolean] Set :delegate_default_allow_nil config option
-      #
-      # @return [Boolean] :delegate_default_allow_nil config option
+      # Sets #delegate_default_allow_nil
       def delegate_default_allow_nil=(value)
-        raise SeregaError, "Must have boolean value, #{value.inspect} provided" if (value != true) && (value != false)
-        opts[:delegate_default_allow_nil] = value
+        opts[:delegate_default_allow_nil] = checked_boolean(value)
       end
 
-      # Returns :auto_preload_excluded_methods config option — methods that are
-      # never auto-preloaded, as they return the serialized object itself and
-      # not an association
-      # @return [Array<Symbol>] Current :auto_preload_excluded_methods config option
+      # Methods that #auto_preload never preloads, as they return the object
+      # itself. `[:itself, :__getobj__]` by default.
       def auto_preload_excluded_methods
         opts.fetch(:auto_preload_excluded_methods)
       end
 
-      # Sets :auto_preload_excluded_methods config option — methods that are
-      # never auto-preloaded. Applies to the `:method` option of attributes
-      # with a serializer and to the `delegate: {to: ...}` option.
-      #
-      # @param value [Array<Symbol>] Method names to skip in auto-preload
-      #
-      # @return [Array<Symbol>] New :auto_preload_excluded_methods config option
+      # Sets #auto_preload_excluded_methods
       def auto_preload_excluded_methods=(value)
         unless value.is_a?(Array) && value.all?(Symbol)
           raise SeregaError, "Must be an Array of Symbols, #{value.inspect} provided"
@@ -142,41 +96,31 @@ class Serega
         opts[:auto_preload_excluded_methods] = value
       end
 
-      # Returns :base_serializer config option — the parent class for nested
-      # serializers defined with attribute blocks
-      # @return [Class, nil] Current :base_serializer config option
+      # Parent class of nested serializers defined with an attribute block.
+      # `nil` by default.
       def base_serializer
         opts.fetch(:base_serializer)
       end
 
-      # Sets :base_serializer config option — the parent class for nested
-      # serializers defined with attribute blocks. Usually a settings-only
-      # serializer, e.g. `config.base_serializer = self` in an application
-      # base serializer class.
-      #
-      # @param value [Class] Serega or its subclass
+      # Sets #base_serializer, a Serega subclass
       #
-      # @return [Class] New :base_serializer config option
+      # ```ruby
+      # config.base_serializer = self
+      # ```
       def base_serializer=(value)
         raise SeregaError, "Must be a Serega subclass, #{value.inspect} provided" if !value.is_a?(Class) || !(value <= Serega)
 
         opts[:base_serializer] = value
       end
 
-      # Returns :hide_by_default config option
-      # @return [Boolean, Symbol] Current :hide_by_default config option
+      # Which attributes are hidden without the `:hide` option: `false` for none
+      # (the default), `true` for all, `:auto` for attributes with preloads or
+      # batch loaders.
       def hide_by_default
         opts.fetch(:hide_by_default)
       end
 
-      # Sets :hide_by_default config option
-      #
-      # @param value [Boolean, Symbol] Accepted values:
-      #   - false (default) — nothing is hidden by default
-      #   - true — all attributes are hidden by default
-      #   - :auto — hides attributes that declare :preload or :batch
-      #
-      # @return [Boolean, Symbol] New :hide_by_default config option
+      # Sets #hide_by_default
       def hide_by_default=(value)
         opts[:hide_by_default] =
           case value
@@ -187,13 +131,15 @@ class Serega
           end
       end
 
-      # @return [Hash] auto_preload option
+      # Attributes that get preloads automatically: `:delegate` attributes with
+      # `has_delegate_option` and `:serializer` attributes with
+      # `has_serializer_option`. Both are `false` by default.
       def auto_preload
         opts.fetch(:auto_preload)
       end
 
-      # Validates and sets auto_preload option
-      # @return [Hash] New auto_preload option with attributes that trigger auto preload
+      # Sets #auto_preload: `true` or `false` for both kinds of attributes, or a
+      # Hash with `has_delegate_option` and `has_serializer_option`
       def auto_preload=(value)
         opts[:auto_preload] =
           case value
@@ -207,85 +153,102 @@ class Serega
           end
       end
 
-      # Returns the hash_access config object
-      # @return [Serega::SeregaConfig::HashAccessConfig] hash_access config object
+      # Builds lazy config objects before freezing, thus a frozen config
+      # returns them
+      def freeze # :nodoc:
+        hash_access
+        super
+      end
+
+      # Defaults of the `hash_access:` attribute option
       def hash_access
         @hash_access ||= HashAccessConfig.new(opts.fetch(:hash_access))
       end
 
-      # Returns :max_cached_plans_per_serializer_count config option
-      # @return [Boolean] Current :max_cached_plans_per_serializer_count config option
+      # How many serialization plans with field selection the serializer
+      # caches, `20` by default. `0` disables the cache.
       def max_cached_plans_per_serializer_count
         opts.fetch(:max_cached_plans_per_serializer_count)
       end
 
-      # Sets :max_cached_plans_per_serializer_count config option
-      #
-      # @param value [Boolean] Set :check_initiate_params config option
-      #
-      # @return [Boolean] New :max_cached_plans_per_serializer_count config option
+      # Sets #max_cached_plans_per_serializer_count
       def max_cached_plans_per_serializer_count=(value)
         raise SeregaError, "Must have Integer value, #{value.inspect} provided" unless value.is_a?(Integer)
         opts[:max_cached_plans_per_serializer_count] = value
       end
 
-      # Returns whether attributes names check is disabled
+      # Deepest nesting of serialized fields, `nil` for no limit (the default).
+      # The limit of the serializer that starts the serialization applies.
+      def depth_limit
+        opts.fetch(:depth_limit)
+      end
+
+      # Sets #depth_limit: a positive Integer or `nil`
+      def depth_limit=(value)
+        valid = value.nil? || (value.is_a?(Integer) && value.positive?)
+        raise SeregaError, "Must have positive Integer or nil value, #{value.inspect} provided" unless valid
+        opts[:depth_limit] = value
+      end
+
+      # Whether attribute names may contain only `a-z`, `A-Z`, `0-9`, `_`, `-`
+      # and `~`. `true` by default.
       def check_attribute_name
         opts.fetch(:check_attribute_name)
       end
 
-      # Sets :check_attribute_name config option
-      #
-      # @param value [Boolean] Set :check_attribute_name config option
-      #
-      # @return [Boolean] New :check_attribute_name config option
+      # Sets #check_attribute_name
       def check_attribute_name=(value)
-        raise SeregaError, "Must have boolean value, #{value.inspect} provided" if (value != true) && (value != false)
-        opts[:check_attribute_name] = value
+        opts[:check_attribute_name] = checked_boolean(value)
+      end
+
+      # Whether every relation, an attribute with `:serializer` or a block,
+      # must have the `:many` option. `false` by default.
+      def require_many
+        opts.fetch(:require_many)
+      end
+
+      # Sets #require_many
+      def require_many=(value)
+        opts[:require_many] = checked_boolean(value)
       end
 
-      # Returns current batch_id_option
+      # Method that returns the id of an object for batch loaders, `:id` by
+      # default
       def batch_id_option
         opts.fetch(:batch_id_option)
       end
 
-      # Sets :batch_id_option config option
-      #
-      # @param value [Symbol] Set :batch_id_option config option
-      #
-      # @return [Symbol] New :check_attribute_name config option
+      # Sets #batch_id_option
       def batch_id_option=(value)
         raise SeregaError, "Must have Symbol value, #{value.inspect} provided" unless value.is_a?(Symbol)
         opts[:batch_id_option] = value
       end
+
+      private
+
+      def checked_boolean(value)
+        raise SeregaError, "Must have boolean value, #{value.inspect} provided" unless value == true || value == false
+
+        value
+      end
     end
 
-    #
-    # Config for the `hash_access:` attribute option
-    #
+    # Defaults of the `hash_access:` attribute option, `config.hash_access`
     class HashAccessConfig
-      # @return [Hash] hash_access config options
-      attr_reader :opts
+      # hash_access config options
+      attr_reader :opts # :nodoc:
 
-      #
       # Initializes HashAccessConfig object
-      #
-      # @param opts [Hash] hash_access config options
-      #
-      # @return [Serega::SeregaConfig::HashAccessConfig]
-      #
-      def initialize(opts)
+      def initialize(opts) # :nodoc:
         @opts = opts
       end
 
-      # @return [Symbol] mode used by `hash_access: true` (default :symbol)
+      # Mode of `hash_access: true`: `:symbol` (the default) or `:string` keys
       def default_mode
         opts.fetch(:default_mode)
       end
 
-      # Sets the mode used by `hash_access: true`
-      # @param value [Symbol] one of :symbol, :string
-      # @return [Symbol] new default mode
+      # Sets #default_mode
       def default_mode=(value)
         unless AttributeValueResolvers::HashAccessResolver::MODES.include?(value)
           raise SeregaError, "Invalid hash_access default_mode #{value.inspect}. Allowed modes: :symbol, :string"
@@ -294,14 +257,13 @@ class Serega
         opts[:default_mode] = value
       end
 
-      # @return [Boolean] allow_missing_key used when an attribute omits it
+      # Whether a missing Hash key gives `nil` instead of raising `KeyError`.
+      # `false` by default.
       def default_allow_missing_key
         opts.fetch(:default_allow_missing_key)
       end
 
-      # Sets the allow_missing_key used when an attribute omits it
-      # @param value [Boolean]
-      # @return [Boolean] new default allow_missing_key
+      # Sets #default_allow_missing_key
       def default_allow_missing_key=(value)
         unless value == true || value == false
           raise SeregaError, "Invalid hash_access default_allow_missing_key #{value.inspect}. Must be a Boolean"
@@ -312,6 +274,5 @@ class Serega
     end
 
     include SeregaConfigInstanceMethods
-    extend Serega::SeregaHelpers::SerializerClassHelper
   end
 end

data/lib/serega/engine/pulls.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaEngine # :nodoc:
+    #
+    # Pulls of relation sources. A pull says what to take for one relation
+    # source from the serialized objects of its child group:
+    # - the count of a collection: an Array of this count of serialized objects
+    # - SINGLE_SOURCE for one source: one serialized object
+    # - nil for nil: nothing, the relation value is nil
+    # - SKIP for a relation skipped by its condition: nothing, the relation
+    #   value is SKIP
+    #
+    module Pulls # :nodoc:
+      # Pull of one source that is not in a collection. Its relation value is
+      # one serialized object, and not an Array.
+      SINGLE_SOURCE = Object.new.freeze
+
+      module_function
+
+      # Appends the sources of the relation sources to sources, and returns
+      # the pull of each relation source
+      def collect(sources, relation_sources, many, known_classes)
+        relation_sources.map { |relation_source| append(sources, relation_source, many, known_classes) }
+      end
+
+      # Collects like `.collect`, and keeps SKIP of a skipped relation source
+      # as its pull
+      def collect_conditional(sources, relation_sources, many, known_classes)
+        relation_sources.map do |relation_source|
+          SKIP.equal?(relation_source) ? relation_source : append(sources, relation_source, many, known_classes)
+        end
+      end
+
+      # Appends the source(s) of one relation source to sources, and returns
+      # its pull
+      def append(sources, relation_source, many, known_classes)
+        return if relation_source.nil?
+
+        if many != false && SeregaUtils::CollectionDetector.call(relation_source, known_classes)
+          collection = relation_source.to_a
+          sources.concat(collection)
+          collection.size
+        else
+          sources << relation_source
+          many ? 1 : SINGLE_SOURCE # `many` on, but a sole source was given — wrap it, don't raise
+        end
+      end
+
+      # Takes the relation value of each pull from the front of the
+      # serialized objects. The serialized objects follow the order of the
+      # pulls. Empties the serialized objects.
+      def take!(serialized, pulls)
+        pulls.map do |pull|
+          case pull
+          when Integer then serialized.shift(pull)
+          when SINGLE_SOURCE then serialized.shift
+          else pull # nil or SKIP
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/engine/run.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Serialization engine
+  #
+  module SeregaEngine # :nodoc:
+    # Value of an attribute skipped by its conditions. It is also the pull of
+    # a skipped relation.
+    SKIP = Object.new.freeze
+
+    #
+    # One serialization run. Serializes the source(s) with a plan, and all
+    # their relation sources. A source is an object to serialize.
+    #
+    # The run makes source groups. A group holds all sources of one plan, for
+    # example the posts of all users, thus batch loaders and preloads run once
+    # per group. The run serializes the groups in two passes:
+    # - Discover pass, from the root group down. Each group runs its preloads
+    #   and makes one child group per relation.
+    # - Build pass, from the last group up. Each group builds its serialized
+    #   objects. The serialized related objects are ready at this time.
+    #
+    class Run # :nodoc:
+      class << self
+        # Serializes the object(s) with the plan in a new run. A flat plan
+        # builds its serialized object(s) with its result builder, without a
+        # run, and one source without the sources Array.
+        def call(plan, object, many, mode, context)
+          return new(mode, context).call(plan, object, many: many) unless plan.flat?
+          return if object.nil?
+
+          builder = plan.result_builder(mode)
+          return builder.call_one(object, context) if many == false
+
+          sources = []
+          pull = Pulls.append(sources, object, many, plan.collection_classes)
+          Pulls::SINGLE_SOURCE.equal?(pull) ? builder.call_one(object, context) : builder.call(sources, context, nil, nil)
+        end
+      end
+
+      # Serialization mode
+      attr_reader :mode
+
+      # Serialization context
+      attr_reader :context
+
+      def initialize(mode, context)
+        @mode = mode
+        @context = context
+      end
+
+      # Serializes the object(s) with the plan.
+      def call(plan, object, many:)
+        return if object.nil?
+
+        root_group = root_source_group(plan, object, many)
+        source_groups = discover(root_group)
+        build(source_groups)
+        root_value(root_group)
+      end
+
+      # Makes a source group of the plan.
+      def new_source_group(plan, sources, pulls)
+        SeregaSourceGroup.new(self, plan, sources, pulls)
+      end
+
+      private
+
+      # Makes the root group: the root source(s) with one pull
+      def root_source_group(plan, object, many)
+        sources = []
+        pull = Pulls.append(sources, object, many, plan.collection_classes)
+        new_source_group(plan, sources, [pull])
+      end
+
+      # Discovers the root group and its child groups, from the root down.
+      # Returns all groups in discover order: a child group comes after its
+      # parent group.
+      def discover(root_group)
+        source_groups = [root_group]
+        index = 0
+
+        while index < source_groups.size
+          source_groups.concat(source_groups[index].discover)
+          index += 1
+        end
+
+        source_groups
+      end
+
+      # Builds the groups from the last one up, thus a child group is built
+      # before its parent group
+      def build(source_groups)
+        source_groups.reverse_each(&:build)
+      end
+
+      # Returns the serialized root: one serialized object for SINGLE_SOURCE,
+      # or all serialized objects of the root group
+      def root_value(root_group)
+        serialized = root_group.serialized
+        Pulls::SINGLE_SOURCE.equal?(root_group.pulls[0]) ? serialized[0] : serialized
+      end
+    end
+  end
+end