serega 0.6.1 → 0.7.0

data/lib/serega/plugins/root/root.rb

@@ -2,36 +2,109 @@
 
 class Serega
   module SeregaPlugins
+    #
+    # Plugin :root
+    #
+    # Allows to add root key to your serialized data
+    #
+    # Accepts options:
+    #  - :root - specifies root for all responses
+    #  - :root_one - specifies root for single object serialization only
+    #  - :root_many - specifies root for multiple objects serialization only
+    #
+    # Adds additional config options:
+    #   - config.root.one
+    #   - config.root.many
+    #   - config.root.one=
+    #   - config.root_many=
+    #
+    # Default root is `:data`.
+    #
+    # Root also can be changed per serialization.
+    #
+    # Also root can be removed for all responses by providing `root: nil`. In this case no root will be added to response, but
+    # you still can to add it per serialization
+    #
+    # @example Define plugin
+    #   class UserSerializer < Serega
+    #     plugin :root # default root is :data
+    #   end
+    #
+    #   class UserSerializer < Serega
+    #     plugin :root, root: :users
+    #   end
+    #
+    #   class UserSerializer < Serega
+    #     plugin :root, root_one: :user, root_many: :people
+    #   end
+    #
+    #   class UserSerializer < Serega
+    #     plugin :root, root: nil # no root by default
+    #   end
+    #
+    # @example Change root per serialization:
+    #   class UserSerializer < Serega
+    #     plugin :root
+    #   end
+    #
+    #   UserSerializer.to_h(nil)              # => {:data=>nil}
+    #   UserSerializer.to_h(nil, root: :user) # => {:user=>nil}
+    #   UserSerializer.to_h(nil, root: nil)   # => nil
+    #
     module Root
       # @return [Symbol] Default response root key
       ROOT_DEFAULT = :data
 
+      # @return [Symbol] Plugin name
       def self.plugin_name
         :root
       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)
         serializer_class.extend(ClassMethods)
+        serializer_class.include(InstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
-        serializer_class::SeregaSerializer.include(SerializerInstanceMethods)
       end
 
+      #
+      # Adds config options and runs other callbacks after plugin was loaded
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
       def self.after_load_plugin(serializer_class, **opts)
         config = serializer_class.config
-        default = opts[:root] || ROOT_DEFAULT
-        one = (opts[:root_one] || default).to_sym
-        many = (opts[:root_many] || default).to_sym
-        config.opts[:root] = {one: one, many: many}
+        default = opts.fetch(:root, ROOT_DEFAULT)
+        one = opts.fetch(:root_one, default)
+        many = opts.fetch(:root_many, default)
+        config.opts[:root] = {}
+        config.root = {one: one, many: many}
+
         config.serialize_keys << :root
       end
 
+      #
+      # Serega additional/patched class methods
+      #
+      # @see Serega
+      #
       module ClassMethods
         #
         # Configures response root key
         #
-        # @param root [String, Symbol] Specifies common root when serializing one or multiple objects
-        # @param root_one [String, Symbol] Specifies root when serializing one object
-        # @param root_many [String, Symbol] Specifies root when serializing multiple objects
+        # @param root [String, Symbol, nil] Specifies common root when serializing one or multiple objects
+        # @param one [String, Symbol, nil] Specifies root when serializing one object
+        # @param many [String, Symbol, nil] Specifies root when serializing multiple objects
         #
         # @return [Hash] Configured root names
         #
@@ -39,63 +112,102 @@ class Serega
           one ||= root
           many ||= root
 
-          one = one.to_sym if one
-          many = many.to_sym if many
-
           config.root = {one: one, many: many}
         end
       end
 
+      # Root config object
       class RootConfig
         attr_reader :opts
 
+        #
+        # Initializes RootConfig object
+        #
+        # @param opts [Hash] root options
+        # @option opts [Symbol, String, nil] :one root for single-object serialization
+        # @option opts [Symbol, String, nil] :many root for many-objects serialization
+        #
+        # @return [Serega::SeregaPlugins::Root::RootConfig] RootConfig object
+        #
         def initialize(opts)
           @opts = opts
         end
 
+        # @return [Symbol, String, nil] defined root for single-object serialization
         def one
           opts.fetch(:one)
         end
 
+        # @return [Symbol, String, nil] defined root for many-objects serialization
         def many
           opts.fetch(:many)
         end
 
+        #
+        # Set root for single-object serialization
+        #
+        # @param value [Symbol, String, nil] root key
+        #
+        # @return [Symbol, String, nil] root key for single-object serialization
         def one=(value)
           opts[:one] = value
         end
 
+        #
+        # Set root for multiple-object serialization
+        #
+        # @param value [Symbol, String, nil] root key
+        #
+        # @return [Symbol, String, nil] root key for multiple-object serialization
         def many=(value)
           opts[:many] = value
         end
       end
 
+      #
+      # Serega::SeregaConfig additional/patched class methods
+      #
+      # @see Serega::SeregaConfig
+      #
       module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::Root::RootConfig] current root config
         def root
           @root ||= RootConfig.new(opts.fetch(:root))
         end
 
+        # Set root for one-object and many-objects serialization types
+        #
+        # @param value [Hash]
+        # @option value [Symbol, String, nil] :one Root for one-object serialization type
+        # @option value [Symbol, String, nil] :many Root for many-objects serialization type
+        #
+        # @return [void]
         def root=(value)
           root.one = value.fetch(:one)
           root.many = value.fetch(:many)
         end
       end
 
-      module SerializerInstanceMethods
-        def serialize(_object)
+      #
+      # Serega additional/patched instance methods
+      #
+      # @see Serega
+      #
+      module InstanceMethods
+        private
+
+        def serialize(object, opts)
           result = super
-          root = build_root(result, opts)
+          root = build_root(object, opts)
           result = {root => result} if root
           result
         end
 
-        private
-
-        def build_root(result, opts)
+        def build_root(object, opts)
           return opts[:root] if opts.key?(:root)
 
-          root = self.class.serializer_class.config.root
-          result.is_a?(Array) ? root.many : root.one
+          root = self.class.config.root
+          (opts.fetch(:many) { object.is_a?(Enumerable) }) ? root.many : root.one
         end
       end
     end

data/lib/serega/plugins/string_modifiers/parse_string_modifiers.rb

@@ -2,23 +2,53 @@
 
 class Serega
   module SeregaPlugins
+    #
+    # Plugin :string_modifiers
+    #
+    # Allows to specify modifiers as strings.
+    #
+    # Serialized attributes must be split with `,` and nested attributes can be defined inside brackets `(`, `)`.
+    #
+    # @example
+    #   PostSerializer.plugin :string_modifiers
+    #   PostSerializer.new(only: "id,user(id,username)").to_h(post)
+    #   PostSerializer.new(except: "user(username,email)").to_h(post)
+    #   PostSerializer.new(with: "user(email)").to_h(post)
+
+    #   # Modifiers can still be provided old way with nested hashes or arrays.
+    #   PostSerializer.new(with: {user: %i[email, username]}).to_h(post)
+    #
     module StringModifiers
+      #
+      # Modifiers parser
+      #
       class ParseStringModifiers
-        COMMA = ","
-        OPEN_BRACKET = "("
-        CLOSE_BRACKET = ")"
-
+        #
+        # Parses provided fields
+        #
+        # @param fields [String,Hash,Array,nil]
+        #
+        # @return [Hash] parsed modifiers in form of nested hash
+        #
         def self.call(fields)
           return fields unless fields.is_a?(String)
 
           new.parse(fields)
         end
 
-        # user => { user: {} }
-        # user(id) => { user: { id: {} } }
-        # user(id,name) => { user: { id: {}, name: {} } }
-        # user,comments => { user: {}, comments: {} }
-        # user(comments(text)) => { user: { comments: { text: {} } } }
+        #
+        # Parses string modifiers
+        #
+        # @param fields [String]
+        #
+        # @return [Hash] parsed modifiers in form of nested hash
+        #
+        # @example
+        #   parse("user") => { user: {} }
+        #   parse("user(id)") => { user: { id: {} } }
+        #   parse("user(id,name)") => { user: { id: {}, name: {} } }
+        #   parse("user,comments") => { user: {}, comments: {} }
+        #   parse("user(comments(text))") => { user: { comments: { text: {} } } }
         def parse(fields)
           res = {}
           attribute = +""
@@ -26,12 +56,12 @@ class Serega
 
           fields.each_char do |char|
             case char
-            when COMMA
+            when ","
               add_attribute(res, path_stack, attribute, FROZEN_EMPTY_HASH)
-            when CLOSE_BRACKET
+            when ")"
               add_attribute(res, path_stack, attribute, FROZEN_EMPTY_HASH)
               path_stack&.pop
-            when OPEN_BRACKET
+            when "("
               name = add_attribute(res, path_stack, attribute, {})
               (path_stack ||= []).push(name) if name
             else

data/lib/serega/plugins/string_modifiers/string_modifiers.rb

@@ -3,15 +3,29 @@
 class Serega
   module SeregaPlugins
     module StringModifiers
+      # @return [Symbol] Plugin name
       def self.plugin_name
         :string_modifiers
       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)
         serializer_class.include(InstanceMethods)
         require_relative "./parse_string_modifiers"
       end
 
+      #
+      # Serega additional/patched instance methods
+      #
+      # @see Serega
+      #
       module InstanceMethods
         private
 

data/lib/serega/plugins.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class Serega
-  # Module in which all Serega plugins should be stored
+  # Plugins are stored here
   module SeregaPlugins
     @plugins = {}
 
@@ -9,8 +9,14 @@ class Serega
       #
       # Registers given plugin to be able to load it using symbol name.
       #
+      # @param name [Symbol] Plugin name
+      # @param mod [Module] Plugin module
+      #
       # @example Register plugin
       #   Serega::SeregaPlugins.register_plugin(:plugin_name, PluginModule)
+      #
+      # @return [void]
+      #
       def register_plugin(name, mod)
         @plugins[name] = mod
       end

data/lib/serega/utils/enum_deep_dup.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
 class Serega
+  #
+  # Utilities
+  #
   module SeregaUtils
+    #
     # Duplicates nested hashes and arrays
+    #
     class EnumDeepDup
       DUP = {
         Hash => ->(data) { dup_hash_values(data) },

data/lib/serega/utils/to_hash.rb

@@ -2,8 +2,28 @@
 
 class Serega
   module SeregaUtils
+    #
+    # Utility to transform almost anything to Hash
+    #
     class ToHash
-      module ClassMethods
+      class << self
+        #
+        # Constructs deep hashes from provided data
+        #
+        # @param value [Array, Hash, String, Symbol, NilClass, FalseClass] Value to transform
+        #
+        # @example
+        #   Serega::SeregaUtils::ToHash.(nil) # => {}
+        #   Serega::SeregaUtils::ToHash.(false) # => {}
+        #   Serega::SeregaUtils::ToHash.(:foo) # => {:foo=>{}}
+        #   Serega::SeregaUtils::ToHash.("foo") # => {:foo=>{}}
+        #   Serega::SeregaUtils::ToHash.(%w[foo bar]) # => {:foo=>{}, :bar=>{}}
+        #   Serega::SeregaUtils::ToHash.({ foo: nil, bar: false }) # => {:foo=>{}, :bar=>{}}
+        #   Serega::SeregaUtils::ToHash.({ foo: :bar }) # => {:foo=>{:bar=>{}}}
+        #   Serega::SeregaUtils::ToHash.({ foo: [:bar] }) # => {:foo=>{:bar=>{}}}
+        #
+        # @return [Hash] Transformed data
+        #
         def call(value)
           case value
           when Array then array_to_hash(value)
@@ -45,8 +65,6 @@ class Serega
           {value => Serega::FROZEN_EMPTY_HASH}
         end
       end
-
-      extend ClassMethods
     end
   end
 end

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

@@ -2,11 +2,17 @@
 
 class Serega
   module SeregaValidations
+    #
+    # Attribute parameters validators
+    #
     module Attribute
+      #
+      # Attribute `block` parameter validator
+      #
       class CheckBlock
         class << self
           #
-          # Checks :value option or a block provided with attribute
+          # Checks block parameter provided with attribute.
           # Must have up to two arguments - object and context.
           # It should not have any *rest or **key arguments
           #
@@ -19,7 +25,6 @@ class Serega
           # @example with two arguments
           #   attribute(:email) { |obj, context| context['is_current'] ? obj.email : nil }
           #
-          # @param opts [Proc] Attribute opts, we will check :value option
           # @param block [Proc] Block that returns serialized attribute value
           #
           # @raise [SeregaError] SeregaError that block has invalid arguments

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

@@ -3,8 +3,14 @@
 class Serega
   module SeregaValidations
     module Attribute
+      #
+      # Attribute `name` parameter validator
+      #
       class CheckName
+        # Regexp for valid one-char attribute name
         FORMAT_ONE_CHAR = /\A[a-zA-Z0-9]\z/
+
+        # Regexp for valid multi-chars attribute name
         FORMAT_MANY_CHARS = /\A[a-zA-Z0-9][a-zA-Z0-9_-]*?[a-zA-Z0-9]\z/ # allow '-' and '_' in the middle
 
         private_constant :FORMAT_ONE_CHAR, :FORMAT_MANY_CHARS

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

@@ -3,17 +3,20 @@
 class Serega
   module SeregaValidations
     module Attribute
+      #
+      # Attribute `:const` option validator
+      #
       class CheckOptConst
-        #
-        # Checks attribute :const option
-        #
-        # @param opts [Hash] Attribute options
-        #
-        # @raise [SeregaError] Attribute validation error
-        #
-        # @return [void]
-        #
         class << self
+          #
+          # Checks attribute :const option
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
           def call(opts, block = nil)
             return unless opts.key?(:const)
 

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

@@ -3,18 +3,21 @@
 class Serega
   module SeregaValidations
     module Attribute
+      #
+      # Attribute `:delegate` option validator
+      #
       class CheckOptDelegate
-        #
-        # Checks attribute :delegate option
-        # It must have :to option and can have :optional allow_nil option
-        #
-        # @param opts [Hash] Attribute options
-        #
-        # @raise [SeregaError] Attribute validation error
-        #
-        # @return [void]
-        #
         class << self
+          #
+          # Checks attribute :delegate option
+          # It must have :to option and can have :optional allow_nil option
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
           def call(opts, block = nil)
             return unless opts.key?(:delegate)
 

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

@@ -3,6 +3,9 @@
 class Serega
   module SeregaValidations
     module Attribute
+      #
+      # Attribute `:hide` option validator
+      #
       class CheckOptHide
         #
         # Checks attribute :hide option

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

@@ -3,17 +3,20 @@
 class Serega
   module SeregaValidations
     module Attribute
+      #
+      # Attribute `:key` option validator
+      #
       class CheckOptKey
-        #
-        # Checks attribute :key option
-        #
-        # @param opts [Hash] Attribute options
-        #
-        # @raise [SeregaError] SeregaError that option has invalid value
-        #
-        # @return [void]
-        #
         class << self
+          #
+          # Checks attribute :key option
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] SeregaError that option has invalid value
+          #
+          # @return [void]
+          #
           def call(opts, block = nil)
             return unless opts.key?(:key)
 

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

@@ -3,6 +3,9 @@
 class Serega
   module SeregaValidations
     module Attribute
+      #
+      # Attribute `:many` option validator
+      #
       class CheckOptMany
         #
         # Checks attribute :many option

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

@@ -3,6 +3,9 @@
 class Serega
   module SeregaValidations
     module Attribute
+      #
+      # Attribute `:serializer` option validator
+      #
       class CheckOptSerializer
         class << self
           #

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

@@ -3,17 +3,20 @@
 class Serega
   module SeregaValidations
     module Attribute
+      #
+      # Attribute `:value` option validator
+      #
       class CheckOptValue
-        #
-        # Checks attribute :value option
-        #
-        # @param opts [Hash] Attribute options
-        #
-        # @raise [SeregaError] SeregaError that option has invalid value
-        #
-        # @return [void]
-        #
         class << self
+          #
+          # Checks attribute :value option
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] SeregaError that option has invalid value
+          #
+          # @return [void]
+          #
           def call(opts, block = nil)
             return unless opts.key?(:value)
 

data/lib/serega/validations/check_attribute_params.rb

@@ -1,17 +1,45 @@
 # frozen_string_literal: true
 
 class Serega
+  #
+  # Validations
+  #
   module SeregaValidations
+    #
+    # Validations for attribute params
+    #
     class CheckAttributeParams
+      #
+      # Validations for attribute params instance methods
+      #
       module InstanceMethods
-        attr_reader :name, :opts, :block
+        # @return [Symbol] validated attribute name
+        attr_reader :name
 
+        # @return [Hash] validated attribute options
+        attr_reader :opts
+
+        # @return [nil, Proc] validated attribute block
+        attr_reader :block
+
+        #
+        # Initializes attribute params validator
+        #
+        # @param name [Symbol] attribute name
+        # @param opts [Hash] attribute options
+        # @param block [nil, Proc] block provided to attribute
+        #
+        # @return [void]
+        #
         def initialize(name, opts, block)
           @name = name
           @opts = opts
           @block = block
         end
 
+        #
+        # Validates attribute params
+        #
         def validate
           check_name
           check_opts