serega 0.40.0 → 0.41.0

data/lib/serega/validations/attribute/check_name.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `name` parameter validator
       #
+      # @private
       class CheckName
         # Regexp for valid attribute name
         FORMAT = /\A[\w~-]+\z/

data/lib/serega/validations/attribute/check_opt_base_serializer.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:base_serializer` option validator
       #
+      # @private
       class CheckOptBaseSerializer
         class << self
           #

data/lib/serega/validations/attribute/check_opt_batch.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:batch` option validator
       #
+      # @private
       class CheckOptBatch
         class << self
           #

data/lib/serega/validations/attribute/check_opt_const.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:const` option validator
       #
+      # @private
       class CheckOptConst
         class << self
           #

data/lib/serega/validations/attribute/check_opt_delegate.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:delegate` option validator
       #
+      # @private
       class CheckOptDelegate
         class << self
           #

data/lib/serega/validations/attribute/check_opt_hash_access.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:hash_access` option validator
       #
+      # @private
       class CheckOptHashAccess
         class << self
           #

data/lib/serega/validations/attribute/check_opt_hide.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:hide` option validator
       #
+      # @private
       class CheckOptHide
         #
         # Checks attribute :hide option

data/lib/serega/validations/attribute/check_opt_many.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:many` option validator
       #
+      # @private
       class CheckOptMany
         class << self
           #

data/lib/serega/validations/attribute/check_opt_method.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:method` option validator
       #
+      # @private
       class CheckOptMethod
         class << self
           #

data/lib/serega/validations/attribute/check_opt_preload.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Validator for attribute :preload option
       #
+      # @private
       class CheckOptPreload
         class << self
           #

data/lib/serega/validations/attribute/check_opt_serializer.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:serializer` option validator
       #
+      # @private
       class CheckOptSerializer
         class << self
           #

data/lib/serega/validations/attribute/check_opt_value.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:value` option validator
       #
+      # @private
       class CheckOptValue
         class << self
           #

data/lib/serega/validations/check_attribute_params.rb

@@ -4,14 +4,17 @@ class Serega
   #
   # Validations
   #
+  # @private
   module SeregaValidations
     #
     # Validations for attribute params
     #
+    # @private
     class CheckAttributeParams
       #
       # Validations for attribute params instance methods
       #
+      # @private
       module InstanceMethods
         # @return [Symbol] validated attribute name
         attr_reader :name

data/lib/serega/validations/check_batch_loader_params.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
     #
     # Batch loader parameters validators
     #
+    # @private
     class CheckBatchLoaderParams
       #
       # batch_loader parameters validation instance methods
       #
+      # @private
       module InstanceMethods
         # @return [Symbol] validated batch_loader name
         attr_reader :name

data/lib/serega/validations/check_initiate_params.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
     #
     # Validations of serializer initialization options
     #
+    # @private
     class CheckInitiateParams
       #
       # Validations of serializer initialization options instance methods
       #
+      # @private
       module InstanceMethods
         # @return [Hash] validated initialization options
         attr_reader :opts

data/lib/serega/validations/check_serialize_params.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
     #
     # Validations of serialization options
     #
+    # @private
     class CheckSerializeParams
       #
       # Validations of serialization options instance methods
       #
+      # @private
       module InstanceMethods
         attr_reader :opts
 

data/lib/serega/validations/initiate/check_modifiers.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
     #
     # Validations that take place when initializing serializer
     #
+    # @private
     module Initiate
       #
       # Modifiers validation
       #
+      # @private
       class CheckModifiers
         #
         # Validates provided fields names are existing attributes

data/lib/serega/validations/utils/check_allowed_keys.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
     #
     # Validations Utilities
     #
+    # @private
     module Utils
       #
       # Utility to check all hash keys are allowed
       #
+      # @private
       class CheckAllowedKeys
         # Checks hash keys are allowed
         #

data/lib/serega/validations/utils/check_opt_is_bool.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Utils
       #
       # Utility to check hash key value is boolean
       #
+      # @private
       class CheckOptIsBool
         # Checks hash key has boolean value
         #

data/lib/serega/validations/utils/check_opt_is_hash.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Utils
       #
       # Utility to check hash key value is Hash
       #
+      # @private
       class CheckOptIsHash
         # Checks hash key value is Hash
         #

data/lib/serega/validations/utils/check_opt_is_string_or_symbol.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Utils
       #
       # Utility to check hash key value is String or Symbol
       #
+      # @private
       class CheckOptIsStringOrSymbol
         # Checks hash key has String or Symbol value
         #

data/lib/serega.rb

@@ -6,10 +6,12 @@ require_relative "serega/version"
 class Serega
   # Frozen hash
   # @return [Hash] frozen hash
+  # @private
   FROZEN_EMPTY_HASH = {}.freeze
 
   # Frozen array
   # @return [Array] frozen array
+  # @private
   FROZEN_EMPTY_ARRAY = [].freeze
 
   # Empty modifiers/serialization options (used when serializing with no opts provided)
@@ -136,6 +138,7 @@ class Serega
     #
     # @return [Boolean] Is plugin used
     #
+    # @private
     def plugin_used?(name)
       plugin_name =
         case name
@@ -151,6 +154,7 @@ class Serega
     #
     # @return [Hash] attributes list
     #
+    # @private
     def attributes
       @attributes ||= {}
     end
@@ -160,6 +164,7 @@ class Serega
     #
     # @return [Hash] batch loaders list
     #
+    # @private
     def batch_loaders
       @batch_loaders ||= {}
     end
@@ -260,6 +265,63 @@ class Serega
       @preload_with = handler
     end
 
+    #
+    # Registers (or returns) the handler that replaces the serialized objects
+    # before serialization starts.
+    #
+    # The handler is called once per serialization with the objects provided to
+    # `.call`/`.to_h`/`.to_data` and the serialization context. Its result is
+    # serialized instead of the provided objects, which allows to accept ids or
+    # other references and load the records in one place.
+    #
+    # The handler runs before the `:many` option is detected, so it may turn a
+    # single object into a collection and back. A provided `:many` serialization
+    # option is still used as is.
+    #
+    # The handler runs only for the serialized objects, and not for objects of
+    # nested serializers.
+    #
+    # @example with a block
+    #   prepare_initial_objects { |user_ids| User.where(id: user_ids) }
+    #
+    # @example with a context
+    #   prepare_initial_objects { |user_ids, ctx| User.where(id: user_ids, account: ctx[:account]) }
+    #
+    # @example with a keyword context
+    #   prepare_initial_objects { |user_ids, ctx:| User.where(id: user_ids, account: ctx[:account]) }
+    #
+    # @example with a callable value
+    #   prepare_initial_objects UsersLoader
+    #
+    # @param value [#call, nil] Handler accepting (objects), (objects, context) or (objects, ctx:)
+    # @param block [Proc] Handler accepting (objects), (objects, context) or (objects, ctx:)
+    #
+    # @return [#call, nil] The registered handler
+    #
+    def prepare_initial_objects(value = nil, &block)
+      return @prepare_initial_objects if value.nil? && block.nil?
+      raise SeregaError, "prepare_initial_objects accepts a single callable or a block, not both" if value && block
+
+      handler = value || block
+      raise SeregaError, "prepare_initial_objects value must be a Proc or respond to #call" if !handler.is_a?(Proc) && !handler.respond_to?(:call)
+
+      signature = SeregaUtils::MethodSignature.call(handler, pos_limit: 2, keyword_args: [:ctx])
+      raise SeregaError, prepare_initial_objects_signature_error unless %w[1 2 1_ctx].include?(signature)
+
+      @prepare_initial_objects_signature = signature
+      @prepare_initial_objects = handler
+    end
+
+    #
+    # Signature of the registered prepare_initial_objects handler
+    #
+    # @return [String, nil] Handler signature
+    #
+    # @private
+    def prepare_initial_objects_signature
+      @prepare_initial_objects_signature
+    end
+
     #
     # Serializes provided object to Hash
     #
@@ -381,8 +443,20 @@ class Serega
       # Assign same preload handler
       subclass.preload_with(preload_with) if preload_with
 
+      # Assign same initial objects handler
+      subclass.prepare_initial_objects(prepare_initial_objects) if prepare_initial_objects
+
       super
     end
+
+    def prepare_initial_objects_signature_error
+      <<~ERR.strip
+        prepare_initial_objects handler arguments should have one of this signatures:
+        - (objects)        # one argument
+        - (objects, ctx)   # two arguments
+        - (objects, ctx:)  # one argument and one :ctx keyword argument
+      ERR
+    end
   end
 
   #
@@ -417,6 +491,7 @@ class Serega
     # This plan can be traversed to find serialized attributes and nested attributes.
     #
     # @return [Serega::SeregaPlan] Serialization plan
+    # @private
     attr_reader :plan
 
     #
@@ -430,6 +505,8 @@ class Serega
     # @return [Hash] Serialization result
     #
     def call(object, opts = nil)
+      opts = normalize_serialization_opts(opts)
+      object = prepare_objects(object, opts[:context])
       opts = prepare_initial_serialization_opts(object, opts)
       serialize(object, opts)
     end
@@ -452,6 +529,8 @@ class Serega
     # @return [Data] Serialization result
     #
     def to_data(object, opts = nil)
+      opts = normalize_serialization_opts(opts)
+      object = prepare_objects(object, opts[:context])
       opts = prepare_initial_serialization_opts(object, opts)
       serialized_data = serialize(object, opts)
       self.class::SeregaDataBuilder.call(self, serialized_data)
@@ -482,11 +561,26 @@ class Serega
       SeregaUtils::ToHash.call(value)
     end
 
-    def prepare_initial_serialization_opts(object, opts)
+    def normalize_serialization_opts(opts)
       opts = opts ? opts.transform_keys(&:to_sym) : {}
       self.class::CheckSerializeParams.new(opts).validate unless opts.empty?
 
       opts[:context] ||= {}
+      opts
+    end
+
+    def prepare_objects(objects, context)
+      handler = self.class.prepare_initial_objects
+      return objects unless handler
+
+      case self.class.prepare_initial_objects_signature
+      when "1" then handler.call(objects)
+      when "2" then handler.call(objects, context)
+      else handler.call(objects, ctx: context) # "1_ctx"
+      end
+    end
+
+    def prepare_initial_serialization_opts(object, opts)
       opts[:level_queue] = SeregaEngine::LevelQueue.new
       opts[:many] = SeregaUtils::CollectionDetector.call(object) unless opts.key?(:many)
       opts[:plan] = plan

metadata

@@ -1,29 +1,26 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.40.0
+  version: 0.41.0
 platform: ruby
 authors:
-- Andrey Glushkov
+- Andrey
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: |
-  JSON Serializer
-
-  - Simple and clear DSL
-  - Ability to manually select serialized fields
-  - Multiple ways to solve N+1 problems
-  - Built-in presenter
-  - No dependencies
-  - Plugin system as in Roda or Shrine
+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.
 email:
-- aglushkov@shakuro.com
+- andreyruby@yandex.ru
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE.txt
 - README.md
 - VERSION
 - lib/serega.rb
@@ -101,13 +98,13 @@ files:
 - lib/serega/validations/utils/check_opt_is_hash.rb
 - lib/serega/validations/utils/check_opt_is_string_or_symbol.rb
 - lib/serega/version.rb
-homepage: https://github.com/aglushkov/serega
+homepage: https://github.com/andreyruby/serega
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/aglushkov/serega
+  source_code_uri: https://github.com/andreyruby/serega
   documentation_uri: https://www.rubydoc.info/gems/serega
-  changelog_uri: https://github.com/aglushkov/serega/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/andreyruby/serega/blob/master/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -124,5 +121,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.13
 specification_version: 4
-summary: JSON Serializer
+summary: Ruby Serializer
 test_files: []