serega 0.42.0 → 0.50.0

data/sig/serega/plugins.rbs

@@ -0,0 +1,49 @@
+# Plugins add these modules when they are loaded, thus a type checker does
+# not see them on serializers and configs.
+class Serega
+  module SeregaPlugins
+    module ActiverecordPreloads
+    end
+
+    module ContextMetadata
+      module ConfigInstanceMethods
+        def context_metadata: () -> ContextMetadataConfig
+      end
+
+      class ContextMetadataConfig
+        def initialize: (Hash[Symbol, untyped] opts, Array[Symbol] serialize_keys) -> void
+
+        def key: () -> Symbol?
+        def key=: (Symbol? new_key) -> Symbol?
+      end
+    end
+
+    module Metadata
+      module ClassMethods
+        def meta_attribute: (*Symbol | String path, **untyped opts) ?{ (untyped objects, context context) -> untyped } -> void
+      end
+    end
+
+    module Root
+      type key = Symbol | String | nil
+
+      module ClassMethods
+        def root: (?key root, ?one: key, ?many: key) -> void
+      end
+
+      class RootConfig
+        def initialize: (Hash[Symbol, untyped] opts) -> void
+
+        def one: () -> key
+        def one=: (key value) -> key
+        def many: () -> key
+        def many=: (key value) -> key
+      end
+
+      module ConfigInstanceMethods
+        def root: () -> RootConfig
+        def root=: ({ one: key, many: key } value) -> void
+      end
+    end
+  end
+end

data/sig/serega.rbs

@@ -0,0 +1,142 @@
+class Serega
+  VERSION: String
+
+  # Fields of the `only:`, `except:` and `with:` options
+  type fields = Symbol | String | Array[fields] | Hash[Symbol | String, fields]
+
+  # Serialization context
+  type context = Hash[untyped, untyped]
+
+  extend ClassMethods
+  include InstanceMethods
+
+  module ClassMethods
+    attr_reader config: SeregaConfig
+
+    def plugin: (Symbol name, **untyped opts) -> Module
+
+    def attributes: () -> Hash[Symbol, SeregaAttribute]
+
+    def attribute: (Symbol | String name, **untyped opts) ?{ () [self: singleton(Serega)] -> void } -> SeregaAttribute
+
+    def batch: (Symbol | String name, untyped loader) -> void
+             | (Symbol | String name) { (untyped objects) -> untyped } -> void
+             | (Symbol | String name) { (untyped objects, context context) -> untyped } -> void
+             | (Symbol | String name) { (untyped objects, ctx: context) -> untyped } -> void
+
+    def formatter: (Symbol name, untyped formatter, ?allow_nil: bool) -> void
+                 | (Symbol name, ?allow_nil: bool) { (untyped value) -> untyped } -> void
+                 | (Symbol name, ?allow_nil: bool) { (untyped value, context context) -> untyped } -> void
+                 | (Symbol name, ?allow_nil: bool) { (untyped value, ctx: context) -> untyped } -> void
+
+    def presenter: () -> singleton(SeregaPresenter)?
+                 | () { () [self: singleton(SeregaPresenter)] -> void } -> singleton(SeregaPresenter)
+
+    def preload_with: () -> untyped
+                    | (untyped handler) -> untyped
+                    | () { (untyped objects, untyped preloads) -> void } -> untyped
+
+    def prepare_initial_objects: () -> untyped
+                               | (untyped handler) -> untyped
+                               | () { (untyped objects) -> untyped } -> untyped
+                               | () { (untyped objects, context context) -> untyped } -> untyped
+                               | () { (untyped objects, ctx: context) -> untyped } -> untyped
+
+    # Results are `untyped`: plugins change their shape. Options that plugins
+    # add at load time, such as `root:`, are not in these signatures.
+    def call: (untyped object, ?only: fields?, ?with: fields?, ?except: fields?, ?check_initiate_params: bool?, ?context: context?, ?many: bool?) -> untyped
+    alias to_h call
+    def to_data: (untyped object, ?only: fields?, ?with: fields?, ?except: fields?, ?check_initiate_params: bool?, ?context: context?, ?many: bool?) -> untyped
+    def to_struct: (untyped object, ?only: fields?, ?with: fields?, ?except: fields?, ?check_initiate_params: bool?, ?context: context?, ?many: bool?) -> untyped
+    def to_json: (untyped object, ?only: fields?, ?with: fields?, ?except: fields?, ?check_initiate_params: bool?, ?context: context?, ?many: bool?) -> String
+
+    def make_shareable!: () -> self
+  end
+
+  module InstanceMethods
+    def initialize: (?only: fields?, ?with: fields?, ?except: fields?, ?check_initiate_params: bool?) -> void
+
+    def call: (untyped object, ?context: context?, ?many: bool?) -> untyped
+    alias to_h call
+    def to_data: (untyped object, ?context: context?, ?many: bool?) -> untyped
+    def to_struct: (untyped object, ?context: context?, ?many: bool?) -> untyped
+    def to_json: (untyped object, ?context: context?, ?many: bool?) -> String
+  end
+
+  # Attribute of a serializer. Its methods are internal.
+  class SeregaAttribute
+    def initialize: (singleton(Serega) serializer_class, name: Symbol | String, ?opts: Hash[Symbol, untyped], ?block: Proc?, ?location: String?) -> void
+  end
+
+  # Parent class of presenters. Its methods are internal.
+  class SeregaPresenter
+    def initialize: (untyped object, ?context? ctx) -> void
+  end
+
+  class SeregaError < StandardError
+  end
+
+  class AttributeNotExist < SeregaError
+    def initialize: (?String? message, ?singleton(Serega)? serializer, ?Array[String]? attributes) -> void
+
+    attr_reader serializer: singleton(Serega)?
+    attr_reader attributes: Array[String]?
+  end
+
+  class DepthLimitError < SeregaError
+    def initialize: (?String? message, ?String? details) -> void
+
+    attr_reader details: String?
+  end
+
+  class SeregaConfig
+    include SeregaConfigInstanceMethods
+
+    module SeregaConfigInstanceMethods
+      def check_initiate_params: () -> bool
+      def check_initiate_params=: (bool value) -> bool
+
+      def check_attribute_name: () -> bool
+      def check_attribute_name=: (bool value) -> bool
+
+      def require_many: () -> bool
+      def require_many=: (bool value) -> bool
+
+      def delegate_default_allow_nil: () -> bool
+      def delegate_default_allow_nil=: (bool value) -> bool
+
+      def hide_by_default: () -> (bool | :auto)
+      def hide_by_default=: (bool | :auto value) -> (bool | :auto)
+
+      def base_serializer: () -> singleton(Serega)?
+      def base_serializer=: (singleton(Serega) value) -> singleton(Serega)
+
+      def depth_limit: () -> Integer?
+      def depth_limit=: (Integer? value) -> Integer?
+
+      def max_cached_plans_per_serializer_count: () -> Integer
+      def max_cached_plans_per_serializer_count=: (Integer value) -> Integer
+
+      def batch_id_option: () -> Symbol
+      def batch_id_option=: (Symbol value) -> Symbol
+
+      def auto_preload: () -> { has_delegate_option: bool, has_serializer_option: bool }
+      def auto_preload=: (bool | { ?has_delegate_option: bool, ?has_serializer_option: bool } value) -> { has_delegate_option: bool, has_serializer_option: bool }
+
+      def auto_preload_excluded_methods: () -> Array[Symbol]
+      def auto_preload_excluded_methods=: (Array[Symbol] value) -> Array[Symbol]
+
+      def hash_access: () -> HashAccessConfig
+    end
+
+    class HashAccessConfig
+      def initialize: (Hash[Symbol, untyped] opts) -> void
+
+      def default_mode: () -> (:symbol | :string)
+      def default_mode=: (:symbol | :string value) -> (:symbol | :string)
+
+      def default_allow_missing_key: () -> bool
+      def default_allow_missing_key=: (bool value) -> bool
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.42.0
+  version: 0.50.0
 platform: ruby
 authors:
 - Andrey
@@ -11,14 +11,13 @@ date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Serializes Ruby objects into Hashes, ready for further conversion to
   JSON or other formats, with a simple DSL for selecting fields and solving N+1 queries
-  through batch loading. Extendable through a Roda/Shrine-style plugin system, with
-  built-in plugins for presenters, formatters, camel_case keys, depth limiting, and
-  more. No runtime dependencies.
+  through batch loading. No runtime dependencies.
 email:
 - andreyruby@yandex.ru
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
 - LICENSE.txt
 - README.md
@@ -26,61 +25,57 @@ files:
 - lib/serega.rb
 - lib/serega/attribute.rb
 - lib/serega/attribute_normalizer.rb
+- lib/serega/attribute_normalizers/batch.rb
+- lib/serega/attribute_normalizers/block.rb
+- lib/serega/attribute_normalizers/delegate.rb
+- lib/serega/attribute_normalizers/hash_access.rb
+- lib/serega/attribute_normalizers/preloads.rb
 - lib/serega/attribute_value_resolvers/batch.rb
 - lib/serega/attribute_value_resolvers/const.rb
 - lib/serega/attribute_value_resolvers/delegate.rb
 - lib/serega/attribute_value_resolvers/hash_access.rb
 - lib/serega/attribute_value_resolvers/keyword.rb
+- lib/serega/attribute_values.rb
+- lib/serega/batch_loader.rb
+- lib/serega/conditions.rb
 - lib/serega/config.rb
-- lib/serega/data_builder.rb
-- lib/serega/engine/level.rb
-- lib/serega/engine/level_queue.rb
-- lib/serega/engine/loader.rb
+- lib/serega/engine/pulls.rb
+- lib/serega/engine/run.rb
 - lib/serega/errors.rb
-- lib/serega/helpers/serializer_class_helper.rb
-- lib/serega/object_serializer.rb
+- lib/serega/formatter.rb
 - lib/serega/plan.rb
+- lib/serega/plan/cache.rb
+- lib/serega/plan/per_ractor_cache.rb
 - lib/serega/plan_point.rb
 - lib/serega/plugins.rb
 - lib/serega/plugins/activerecord_preloads/activerecord_preloads.rb
 - lib/serega/plugins/activerecord_preloads/lib/preloader.rb
-- lib/serega/plugins/camel_case/camel_case.rb
 - lib/serega/plugins/context_metadata/context_metadata.rb
-- lib/serega/plugins/depth_limit/depth_limit.rb
-- lib/serega/plugins/explicit_many_option/explicit_many_option.rb
-- lib/serega/plugins/explicit_many_option/validations/check_opt_many.rb
-- lib/serega/plugins/formatters/formatters.rb
-- lib/serega/plugins/if/if.rb
-- lib/serega/plugins/if/validations/check_opt_if.rb
-- lib/serega/plugins/if/validations/check_opt_if_value.rb
-- lib/serega/plugins/if/validations/check_opt_unless.rb
-- lib/serega/plugins/if/validations/check_opt_unless_value.rb
+- lib/serega/plugins/metadata/check_params.rb
 - lib/serega/plugins/metadata/meta_attribute.rb
 - lib/serega/plugins/metadata/metadata.rb
-- lib/serega/plugins/metadata/validations/check_block.rb
-- lib/serega/plugins/metadata/validations/check_opt_const.rb
-- lib/serega/plugins/metadata/validations/check_opt_hide_empty.rb
-- lib/serega/plugins/metadata/validations/check_opt_hide_nil.rb
-- lib/serega/plugins/metadata/validations/check_opt_value.rb
-- lib/serega/plugins/metadata/validations/check_opts.rb
-- lib/serega/plugins/metadata/validations/check_path.rb
 - lib/serega/plugins/root/root.rb
-- lib/serega/plugins/string_modifiers/parse_string_modifiers.rb
-- lib/serega/plugins/string_modifiers/string_modifiers.rb
 - lib/serega/presenter.rb
+- lib/serega/result_builder.rb
+- lib/serega/result_code.rb
+- lib/serega/shareable.rb
+- lib/serega/source_group.rb
 - lib/serega/utils/collection_detector.rb
+- lib/serega/utils/deep_merge.rb
 - lib/serega/utils/enum_deep_dup.rb
 - lib/serega/utils/enum_deep_freeze.rb
 - lib/serega/utils/method_signature.rb
+- lib/serega/utils/parse_string_modifiers.rb
+- lib/serega/utils/ractor_local.rb
 - lib/serega/utils/serialized_attribute_error.rb
-- lib/serega/utils/symbol_name.rb
 - lib/serega/utils/to_hash.rb
 - lib/serega/validations/attribute/check_block.rb
 - lib/serega/validations/attribute/check_name.rb
 - lib/serega/validations/attribute/check_opt_base_serializer.rb
 - lib/serega/validations/attribute/check_opt_batch.rb
-- lib/serega/validations/attribute/check_opt_const.rb
+- lib/serega/validations/attribute/check_opt_condition.rb
 - lib/serega/validations/attribute/check_opt_delegate.rb
+- lib/serega/validations/attribute/check_opt_format.rb
 - lib/serega/validations/attribute/check_opt_hash_access.rb
 - lib/serega/validations/attribute/check_opt_hide.rb
 - lib/serega/validations/attribute/check_opt_many.rb
@@ -90,36 +85,45 @@ files:
 - lib/serega/validations/attribute/check_opt_value.rb
 - lib/serega/validations/check_attribute_params.rb
 - lib/serega/validations/check_batch_loader_params.rb
-- lib/serega/validations/check_initiate_params.rb
-- lib/serega/validations/check_serialize_params.rb
+- lib/serega/validations/check_formatter.rb
+- lib/serega/validations/check_serialize_keywords.rb
 - lib/serega/validations/initiate/check_modifiers.rb
 - lib/serega/validations/utils/check_allowed_keys.rb
+- lib/serega/validations/utils/check_hash_access_value.rb
 - lib/serega/validations/utils/check_opt_is_bool.rb
 - lib/serega/validations/utils/check_opt_is_hash.rb
 - lib/serega/validations/utils/check_opt_is_string_or_symbol.rb
 - lib/serega/version.rb
+- sig/serega.rbs
+- sig/serega/plugins.rbs
 homepage: https://github.com/andreyruby/serega
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/andreyruby/serega
-  documentation_uri: https://www.rubydoc.info/gems/serega
+  documentation_uri: https://andreyruby.github.io/serega/
   changelog_uri: https://github.com/andreyruby/serega/blob/master/CHANGELOG.md
-rdoc_options: []
+rdoc_options:
+- "--markup"
+- markdown
+- "--main"
+- README.md
+- "--title"
+- Serega
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.13
+rubygems_version: 4.0.23
 specification_version: 4
 summary: Ruby Serializer
 test_files: []

data/lib/serega/data_builder.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  #
-  # Builds Data objects from serialized hashes.
-  # Used by `#to_data` / `.to_data`.
-  #
-  # @private
-  class SeregaDataBuilder
-    # SeregaDataBuilder class methods
-    # @private
-    module SeregaDataBuilderClassMethods
-      #
-      # Converts serialized Hash/Array result into a tree of Ruby Data objects
-      # following the serializer's plan structure.
-      #
-      # @param serializer [Serega] Serializer instance carrying the plan
-      # @param serialized [Hash, Array, nil] Serialized output from `#to_h`
-      #
-      # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
-      #
-      def call(serializer, serialized)
-        build(serialized, serializer.plan)
-      end
-
-      private
-
-      def build(serialized, plan)
-        case serialized
-        when Array then serialized.map { |item| hash_to_data(item, plan) }
-        when Hash then hash_to_data(serialized, plan)
-        else serialized
-        end
-      end
-
-      def hash_to_data(hash, plan)
-        hash_data = hash.to_h do |key, value|
-          child_plan = plan.points_hash.fetch(key).child_plan
-          value = build(value, child_plan) if child_plan
-          [key, value]
-        end
-
-        build_data_object(plan, hash_data)
-      end
-
-      def build_data_object(plan, hash_data)
-        plan.data_class.new(**hash_data)
-      end
-    end
-
-    extend SeregaHelpers::SerializerClassHelper
-    extend SeregaDataBuilderClassMethods
-  end
-end

data/lib/serega/engine/level.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  #
-  # Batch feature main module
-  #
-  # @private
-  module SeregaEngine
-    #
-    # One serialization level: all objects serialized under a single plan and the
-    # result containers they fill. Objects from different parents that share a plan
-    # (e.g. every user's posts) accumulate into one level, so a named batch loader
-    # or preload runs once over the whole set. A deeper level (its own plan) loads
-    # separately.
-    #
-    # @private
-    class Level
-      # @param serializer [SeregaObjectSerializer] serializer that resolves this level
-      def initialize(serializer)
-        @serializer = serializer
-        @objects = []
-        @containers = []
-        @results = {}.compare_by_identity
-      end
-
-      # @return [Array] Objects serialized at this level
-      attr_reader :objects
-
-      # @return [Array<Hash>] Result container per object (filled in place)
-      attr_reader :containers
-
-      # Accumulates a chunk of objects into this level, creating one empty result
-      # container per object. The containers are returned so the caller can hand
-      # them to its parent; they are filled in place later during #process.
-      #
-      # @param objects [Array] objects serialized at this level
-      # @return [Array<Hash>] the created containers, aligned with objects
-      def add(objects)
-        containers = Array.new(objects.size) { {} }
-        @objects.concat(objects)
-        @containers.concat(containers)
-        containers
-      end
-
-      # Resolves every attribute of this level onto the containers.
-      # @return [void]
-      def process
-        @serializer.process(self)
-      end
-
-      # Loads a named batch loader once for this level's objects.
-      # @param loader [SeregaEngine::Loader] Named batch loader
-      # @return [Object] Loaded values
-      def fetch(loader)
-        @results[loader] ||= loader.load(@objects, @serializer.context)
-      end
-    end
-  end
-end

data/lib/serega/engine/level_queue.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  #
-  # Batch feature main module
-  #
-  # @private
-  module SeregaEngine
-    #
-    # Level-order queue of serialization levels for one serialization run.
-    #
-    # `#serialize` on the object serializer enqueues a level (objects + their result
-    # containers) instead of resolving values inline. `#run` then processes the
-    # queue: each level resolves its attributes and, for relations, enqueues child
-    # levels — which the loop picks up because it re-reads the size each iteration.
-    # Processing level-by-level lets a named batch loader and preloads run once per
-    # level over all of its objects.
-    #
-    # @private
-    class LevelQueue
-      def initialize
-        @levels = []
-        @levels_by_plan = {}.compare_by_identity
-      end
-
-      # Adds objects to the level for their plan (creating it on first use), so
-      # objects serialized under the same plan — even from different parents —
-      # share one level and load once. The level creates a result container per
-      # object and returns them for the caller to embed in its parent.
-      #
-      # @param serializer [SeregaObjectSerializer] serializer that resolves the level
-      # @param objects [Array] objects serialized at this level
-      #
-      # @return [Array<Hash>] the created result containers, aligned with objects
-      def enqueue(serializer, objects)
-        level = @levels_by_plan[serializer.plan]
-        unless level
-          level = Level.new(serializer)
-          @levels_by_plan[serializer.plan] = level
-          @levels << level
-        end
-        level.add(objects)
-      end
-
-      # Processes every level, including child levels enqueued while processing.
-      # @return [void]
-      def run
-        i = 0
-        while i < @levels.size
-          @levels[i].process
-          i += 1
-        end
-      end
-    end
-  end
-end

data/lib/serega/engine/loader.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  #
-  # Batch feature main module
-  #
-  # @private
-  module SeregaEngine
-    #
-    #  Batch loader
-    #
-    # @private
-    class Loader
-      #
-      # BatchLoader instance methods
-      #
-      # @private
-      module InstanceMethods
-        # BatchLoader initial params
-        # @return [Hash] BatchLoader initial params
-        attr_reader :initials
-
-        # BatchLoader name
-        # @return [Symbol] BatchLoader name
-        attr_reader :name
-
-        # BatchLoader block
-        # @return [#call] BatchLoader block
-        attr_reader :block
-
-        #
-        # Initializes new batch loader
-        #
-        # @param name [Symbol, String] Name of attribute
-        # @param block [#call] BatchLoader block
-        #
-        def initialize(name:, block:)
-          serializer_class = self.class.serializer_class
-          serializer_class::CheckBatchLoaderParams.new(name, block).validate
-
-          @initials = SeregaUtils::EnumDeepFreeze.call(name: name, block: block)
-          @name = name.to_sym
-          @block = block
-          @signature = SeregaUtils::MethodSignature.call(block, pos_limit: 2, keyword_args: [:ctx])
-        end
-
-        # Serializes values for objects
-        # @param objects [Array] Serialized objects
-        # @param context [Hash] Serialization context
-        # @return [void]
-        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
-
-        # BatchLoader block signature
-        # @return [String] BatchLoader block signature
-        attr_reader :signature
-      end
-
-      extend SeregaHelpers::SerializerClassHelper
-      include InstanceMethods
-    end
-  end
-end

data/lib/serega/helpers/serializer_class_helper.rb

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