serega 0.8.3 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 116b00d5c709f65a90899a9eda49f6e2c95cc9a47781a1cddf2499057553f427
-  data.tar.gz: 5f8fe19470218be68c09704964228be0381e677f5bd3cbcf9688f92974e9392d
+  metadata.gz: 6a94d74dd45c74e499cd1a3abec082d8776019538b67bf24fc840512271adb6b
+  data.tar.gz: a22bc547e6ac94b0988e2cfef2af31ad659beb53058a90159e7f46f6470c3390
 SHA512:
-  metadata.gz: 047de5335017cf65ee0f887124f81a755b94e19eea0e53a56ae24cb81698e7bdcc7e8eb6eba9256b5160a24bb011a5c0a1c1628cca77c7e7951b8883629ad96f
-  data.tar.gz: 5836df28c6e1cf2238d8c8471280dc806dd41a0cbbe474a101118d801e460830cda97dcb419e0885f9106d1e4e5ae795776ff5cc475555bdab6cb4c5408c1c94
+  metadata.gz: d89c6180d4af0273eee6dd6179a0ac6f0157409f07ae6c18985941ecd8971bd17eb8b547a764d97afd12cdc08e565cb8749e9d9e0a70d8ab8add5dbad3e349db
+  data.tar.gz: 4cd808491f38a469ac705f6884007a3d71cead7f12d8e9730ec8c15ee1da97cb2d0d7503aafc0925a5bf41c7b660f7aa71a62da6fda295e713b62114ee83842a

data/README.md

@@ -20,6 +20,7 @@ It has some great features:
 - Built-in object presenter ([presenter][presenter] plugin)
 - Adding custom metadata (via [metadata][metadata] or [context_metadata][context_metadata] plugins)
 - Attributes formatters ([formatters][formatters] plugin)
+- Conditional attributes ([if][if] plugin)
 
 ## Installation
 
@@ -94,9 +95,11 @@ class UserSerializer < Serega
   # It allows to specify associations to preload to attribute value
   attribute :email, preload: :emails, value: proc { |user| user.emails.find(&:verified?) }
 
-  # Option `:hide_nil` can be specified when enabled `:hide_nil` plugin
-  # It is literally hides attribute if its value is nil
-  attribute :email, hide_nil: true
+  # Options `:if`, `:unless`, `:if_value`, `:unless_value` can be specified when enabled `:if` plugin
+  # They hide attribute key and value from response when conditions satisfied
+  # See more usage examples in :if plugin section.
+  attribute :email, if: proc { |user, ctx| user == ctx[:current_user] }
+  attribute :email, if_value: :present?
 
   # Option `:format` can be specified when enabled `:formatters` plugin
   # It changes attribute value
@@ -108,6 +111,23 @@ class UserSerializer < Serega
 end
 ```
 
+---
+
+⚠️ Attribute names are checked to include only "a-z", "A-Z", "0-9", "_", "-", "~" characters.
+We have this check as:
+- Attributes names can be used in URL without encoding.
+- Plugin [string_modifiers][string_modifiers] already uses "," and "()" as attribute names delimeters.
+- We are protected from errors when added some non-english character looking as english.
+
+This names check can be disabled globally or per-serializer via:
+```ruby
+Serega.config.check_attribute_name = false
+
+class SomeSerializer < Serega
+  config.check_attribute_name = false
+end
+```
+
 ### Serializing
 
 We can serialize objects using class methods `.to_h`, `.to_json`, `.as_json` and same instance methods `#to_h`, `#to_json`, `#as_json`.
@@ -600,16 +620,45 @@ PostSerializer.new(with: "user(email)").to_h(post)
 PostSerializer.new(with: {user: %i[email, username]}).to_h(post)
 ```
 
-### Plugin :hide_nil
+### Plugin :if
 
-Allows to hide attributes with `nil` values
+Plugin adds `:if`, `:unless`, `:if_value`, `:unless_value` options to
+attributes so we can remove attributes from response in various ways.
 
-```ruby
-class UserSerializer < Serega
-  plugin :hide_nil
+Use `:if` and `:unless` when you want to hide attributes before finding attribute value,
+and use `:if_value` and `:unless_value` to hide attributes after we find final value.
 
-  attribute :email, hide_nil: true
-end
+Options `:if` and `:unless` accept currently serialized object and context as parameters.
+Options `:if_value` and `:unless_value` accept already found serialized value and context as parameters.
+
+Options `:if_value` and `:unless_value` cannot be used with :serializer option, as
+serialized objects have no "serialized value". Use `:if` and `:unless` in this case.
+
+See also a `:hide` option that is available without any plugins to hide
+attribute without conditions. Look at [select serialized fields](#selecting-fields) for `:hide` usage examples.
+
+```ruby
+ class UserSerializer < Serega
+   attribute :email, if: :active? # if user.active?
+   attribute :email, if: proc {|user| user.active?} # same
+   attribute :email, if: proc {|user, ctx| user == ctx[:current_user]} # using context
+   attribute :email, if: CustomPolicy.method(:view_email?) # You can provide own callable object
+
+   attribute :email, unless: :hidden? # unless user.hidden?
+   attribute :email, unless: proc {|user| user.hidden?} # same
+   attribute :email, unless: proc {|user, context| context[:show_emails]} # using context
+   attribute :email, unless: CustomPolicy.method(:hide_email?) # You can provide own callable object
+
+   attribute :email, if_value: :present? # if email.present?
+   attribute :email, if_value: proc {|email| email.present?} # same
+   attribute :email, if_value: proc {|email, ctx| ctx[:show_emails]} # using context
+   attribute :email, if_value: CustomPolicy.method(:view_email?) # You can provide own callable object
+
+   attribute :email, unless_value: :blank? # unless email.blank?
+   attribute :email, unless_value: proc {|email| email.blank?} # same
+   attribute :email, unless_value: proc {|email, context| context[:show_emails]} # using context
+   attribute :email, unless_value: CustomPolicy.method(:hide_email?) # You can provide own callable object
+ end
 ```
 
 ## Errors
@@ -648,3 +697,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 [presenter]: #plugin-presenter
 [root]: #plugin-root
 [string_modifiers]: #plugin-string_modifiers
+[if]: #plugin-if

data/VERSION

@@ -1 +1 @@
-0.8.3
+0.10.0

data/lib/serega/attribute.rb

@@ -51,6 +51,10 @@ class Serega
       end
 
       # Shows current opts[:hide] option
+      #
+      # Patched in:
+      # - plugin :preloads (returns true by default if config option auto_hide_attribute_with_preloads is enabled)
+      #
       # @return [Boolean, nil] Attribute :hide option value
       def hide
         opts[:hide]
@@ -82,7 +86,11 @@ class Serega
           end
       end
 
-      # Returns final block that will be used to find attribute value
+      # Returns final block used to find attribute value
+      #
+      # Patched in:
+      # - plugin :formatters (wraps resulted block in formatter block and formats :const values)
+      #
       # @return [Proc] Proc to find attribute value
       def value_block
         return @value_block if instance_variable_defined?(:@value_block)

data/lib/serega/config.rb

@@ -17,6 +17,7 @@ class Serega
       initiate_keys: %i[only with except check_initiate_params].freeze,
       attribute_keys: %i[key value serializer many hide const delegate].freeze,
       serialize_keys: %i[context many].freeze,
+      check_attribute_name: true,
       check_initiate_params: true,
       max_cached_map_per_serializer_count: 0,
       to_json: (SeregaJSON.adapter == :oj) ? SeregaJSON::OjDump : SeregaJSON::JSONDump,
@@ -102,6 +103,21 @@ class Serega
         opts[:max_cached_map_per_serializer_count] = value
       end
 
+      # Returns whether attributes names check is disabled
+      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
+      def check_attribute_name=(value)
+        raise SeregaError, "Must have boolean value, #{value.inspect} provided" if (value != true) && (value != false)
+        opts[:check_attribute_name] = value
+      end
+
       # Returns current `to_json` adapter
       # @return [#call] Callable that used to construct JSON
       def to_json

data/lib/serega/object_serializer.rb

@@ -41,18 +41,30 @@ class Serega
         object.map { |obj| serialize_object(obj) }
       end
 
+      # Patched in:
+      # - plugin :presenter (makes presenter_object and serializes it)
       def serialize_object(object)
         points.each_with_object({}) do |point, container|
-          attach_value(object, point, container)
+          serialize_point(object, point, container)
         end
       end
 
+      # Patched in:
+      # - plugin :if (conditionally skips serializing this point)
+      def serialize_point(object, point, container)
+        attach_value(object, point, container)
+      end
+
+      # Patched in:
+      # - plugin :batch (remembers key for batch loading values instead of attaching)
       def attach_value(object, point, container)
         value = point.value(object, context)
         final_value = final_value(value, point)
         attach_final_value(final_value, point, container)
       end
 
+      # Patched in:
+      # - plugin :if (conditionally skips attaching)
       def attach_final_value(final_value, point, container)
         container[point.name] = final_value
       end

data/lib/serega/plugins/batch/batch.rb

@@ -262,14 +262,15 @@ class Serega
 
         def attach_value(object, point, container)
           batch = point.batch
+          return super unless batch
 
-          if batch
-            key = batch.key.call(object, context)
-            opts[:batch_loaders].get(point, self).remember(key, container)
-            container[point.name] = nil # Reserve attribute place in resulted hash. We will set correct value later
-          else
-            super
-          end
+          remember_key_for_batch_loading(batch, object, point, container)
+        end
+
+        def remember_key_for_batch_loading(batch, object, point, container)
+          key = batch.key.call(object, context)
+          opts[:batch_loaders].get(point, self).remember(key, container)
+          container[point.name] = nil # Reserve attribute place in resulted hash. We will set correct value later
         end
       end
     end

data/lib/serega/plugins/batch/lib/loader.rb

@@ -68,6 +68,9 @@ class Serega
             end
           end
 
+          # Patched in:
+          # - plugin batch (extension :activerecord_preloads - preloads data to found values)
+          # - plugin batch (extension :formatters - formats values)
           def keys_values
             ids = keys.keys
 

data/lib/serega/plugins/if/if.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    #
+    # Plugin adds `:if`, `:unless`, `:if_value`, `:unless_value` options to
+    # attributes so we can remove attributes from response in various ways.
+    #
+    # Use `:if` and `:unless` when you want to hide attributes before finding attribute value,
+    # and use `:if_value` and `:unless_value` to hide attributes after we find final value.
+    #
+    # Options `:if` and `:unless` accept currently serialized object and context as parameters.
+    # Options `:if_value` and `:unless_value` accept already found serialized value and context as parameters.
+    #
+    # Options `:if_value` and `:unless_value` cannot be used with :serializer option, as
+    # serialized objects have no "serialized value". Use `:if` and `:unless` in this case.
+    #
+    # See also a `:hide` option that is available without any plugins to hide
+    # attribute without conditions. Look at README.md#selecting-fields for `:hide` usage examples.
+    #
+    # Examples:
+    #  class UserSerializer < Serega
+    #    attribute :email, if: :active? # if user.active?
+    #    attribute :email, if: proc {|user| user.active?} # same
+    #    attribute :email, if: proc {|user, ctx| user == ctx[:current_user]} # using context
+    #    attribute :email, if: CustomPolicy.method(:view_email?) # You can provide own callable object
+    #
+    #    attribute :email, unless: :hidden? # unless user.hidden?
+    #    attribute :email, unless: proc {|user| user.hidden?} # same
+    #    attribute :email, unless: proc {|user, context| context[:show_emails]} # using context
+    #    attribute :email, unless: CustomPolicy.method(:hide_email?) # You can provide own callable object
+    #
+    #    attribute :email, if_value: :present? # if email.present?
+    #    attribute :email, if_value: proc {|email| email.present?} # same
+    #    attribute :email, if_value: proc {|email, ctx| ctx[:show_emails]} # using context
+    #    attribute :email, if_value: CustomPolicy.method(:view_email?) # You can provide own callable object
+    #
+    #    attribute :email, unless_value: :blank? # unless email.blank?
+    #    attribute :email, unless_value: proc {|email| email.blank?} # same
+    #    attribute :email, unless_value: proc {|email, context| context[:show_emails]} # using context
+    #    attribute :email, unless_value: CustomPolicy.method(:hide_email?) # You can provide own callable object
+    #  end
+    #
+    module If
+      # @return [Symbol] Plugin name
+      def self.plugin_name
+        :if
+      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)
+        require_relative "./validations/check_opt_if"
+        require_relative "./validations/check_opt_if_value"
+        require_relative "./validations/check_opt_unless"
+        require_relative "./validations/check_opt_unless_value"
+
+        serializer_class::SeregaMapPoint.include(MapPointInstanceMethods)
+        serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
+        serializer_class::SeregaObjectSerializer.include(SeregaObjectSerializerInstanceMethods)
+      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)
+        serializer_class.config.attribute_keys << :if << :if_value << :unless << :unless_value
+      end
+
+      #
+      # Serega::SeregaMapPoint additional/patched instance methods
+      #
+      # @see Serega::SeregaMapPoint::InstanceMethods
+      #
+      module MapPointInstanceMethods
+        #
+        # @return [Boolean] Should we show attribute or not
+        #   Conditions for this checks are specified by :if and :unless attribute options.
+        #
+        def satisfy_if_conditions?(obj, ctx)
+          check_if_unless(obj, ctx, :if, :unless)
+        end
+
+        #
+        # @return [Boolean] Should we show attribute with specific value or not.
+        #   Conditions for this checks are specified by :if_value and :unless_value attribute options.
+        #
+        def satisfy_if_value_conditions?(value, ctx)
+          check_if_unless(value, ctx, :if_value, :unless_value)
+        end
+
+        private
+
+        def check_if_unless(obj, ctx, opt_if_name, opt_unless_name)
+          opt_if = attribute.opts[opt_if_name]
+          opt_unless = attribute.opts[opt_unless_name]
+          return true if opt_if.nil? && opt_unless.nil?
+
+          res_if =
+            case opt_if
+            when NilClass then true
+            when Symbol then obj.public_send(opt_if)
+            else opt_if.call(obj, ctx)
+            end
+
+          res_unless =
+            case opt_unless
+            when NilClass then true
+            when Symbol then !obj.public_send(opt_unless)
+            else !opt_unless.call(obj, ctx)
+            end
+
+          res_if && res_unless
+        end
+      end
+
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
+      module CheckAttributeParamsInstanceMethods
+        private
+
+        def check_opts
+          super
+
+          CheckOptIf.call(opts)
+          CheckOptUnless.call(opts)
+          CheckOptIfValue.call(opts)
+          CheckOptUnlessValue.call(opts)
+        end
+      end
+
+      #
+      # SeregaObjectSerializer additional/patched class methods
+      #
+      # @see Serega::SeregaObjectSerializer
+      #
+      module SeregaObjectSerializerInstanceMethods
+        private
+
+        def serialize_point(object, point, _container)
+          return unless point.satisfy_if_conditions?(object, context)
+          super
+        end
+
+        def attach_final_value(value, point, _container)
+          return unless point.satisfy_if_value_conditions?(value, context)
+          super
+        end
+      end
+    end
+
+    register_plugin(If.plugin_name, If)
+  end
+end

data/lib/serega/plugins/if/validations/check_opt_if.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module If
+      #
+      # Validator for attribute :if option
+      #
+      class CheckOptIf
+        class << self
+          #
+          # Checks attribute :if option that must be [nil, Symbol, Proc, #call]
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
+          def call(opts)
+            return unless opts.key?(:if)
+
+            check_type(opts[:if])
+          end
+
+          private
+
+          def check_type(value)
+            return if value.is_a?(Symbol)
+
+            raise SeregaError, must_be_callable unless value.respond_to?(:call)
+
+            if value.is_a?(Proc)
+              check_block(value)
+            else
+              check_callable(value)
+            end
+          end
+
+          def check_block(block)
+            return if valid_parameters?(block, accepted_count: 0..2)
+
+            raise SeregaError, block_parameters_error
+          end
+
+          def check_callable(callable)
+            return if valid_parameters?(callable.method(:call), accepted_count: 2..2)
+
+            raise SeregaError, callable_parameters_error
+          end
+
+          def valid_parameters?(data, accepted_count:)
+            params = data.parameters
+            accepted_count.include?(params.count) && valid_parameters_types?(params)
+          end
+
+          def valid_parameters_types?(params)
+            params.all? do |param|
+              type = param[0]
+              (type == :req) || (type == :opt)
+            end
+          end
+
+          def block_parameters_error
+            "Invalid attribute option :if. When it is a Proc it can have maximum two regular parameters (object, context)"
+          end
+
+          def callable_parameters_error
+            "Invalid attribute option :if. When it is a callable object it must have two regular parameters (object, context)"
+          end
+
+          def must_be_callable
+            "Invalid attribute option :if. It must be a Symbol, a Proc or respond to :call"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/if/validations/check_opt_if_value.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module If
+      #
+      # Validator for attribute :if_value option
+      #
+      class CheckOptIfValue
+        class << self
+          #
+          # Checks attribute :if_value option that must be [nil, Symbol, Proc, #call]
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
+          def call(opts)
+            return unless opts.key?(:if_value)
+
+            check_usage_with_other_params(opts)
+            check_type(opts[:if_value])
+          end
+
+          private
+
+          def check_type(value)
+            return if value.is_a?(Symbol)
+
+            raise SeregaError, must_be_callable unless value.respond_to?(:call)
+
+            if value.is_a?(Proc)
+              check_block(value)
+            else
+              check_callable(value)
+            end
+          end
+
+          def check_usage_with_other_params(opts)
+            raise SeregaError, "Option :if_value can not be used together with option :serializer" if opts.key?(:serializer)
+          end
+
+          def check_block(block)
+            return if valid_parameters?(block, accepted_count: 0..2)
+
+            raise SeregaError, block_parameters_error
+          end
+
+          def check_callable(callable)
+            return if valid_parameters?(callable.method(:call), accepted_count: 2..2)
+
+            raise SeregaError, callable_parameters_error
+          end
+
+          def valid_parameters?(data, accepted_count:)
+            params = data.parameters
+            accepted_count.include?(params.count) && valid_parameters_types?(params)
+          end
+
+          def valid_parameters_types?(params)
+            params.all? do |param|
+              type = param[0]
+              (type == :req) || (type == :opt)
+            end
+          end
+
+          def block_parameters_error
+            "Invalid attribute option :if_value. When it is a Proc it can have maximum two regular parameters (object, context)"
+          end
+
+          def callable_parameters_error
+            "Invalid attribute option :if_value. When it is a callable object it must have two regular parameters (object, context)"
+          end
+
+          def must_be_callable
+            "Invalid attribute option :if_value. It must be a Symbol, a Proc or respond to :call"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/if/validations/check_opt_unless.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module If
+      #
+      # Validator for attribute :unless option
+      #
+      class CheckOptUnless
+        class << self
+          #
+          # Checks attribute :unless option that must be [nil, Symbol, Proc, #call]
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
+          def call(opts)
+            return unless opts.key?(:unless)
+
+            check_type(opts[:unless])
+          end
+
+          private
+
+          #
+          # Checks attribute :unless option
+          #
+          # @param value [nil, Symbol, Proc, #call] Attribute :unless option
+          #
+          # @raise [SeregaError] validation error
+          #
+          # @return [void]
+          #
+          def check_type(value)
+            return if value.is_a?(Symbol)
+
+            raise SeregaError, must_be_callable unless value.respond_to?(:call)
+
+            if value.is_a?(Proc)
+              check_block(value)
+            else
+              check_callable(value)
+            end
+          end
+
+          def check_block(block)
+            return if valid_parameters?(block, accepted_count: 0..2)
+
+            raise SeregaError, block_parameters_error
+          end
+
+          def check_callable(callable)
+            return if valid_parameters?(callable.method(:call), accepted_count: 2..2)
+
+            raise SeregaError, callable_parameters_error
+          end
+
+          def valid_parameters?(data, accepted_count:)
+            params = data.parameters
+            accepted_count.include?(params.count) && valid_parameters_types?(params)
+          end
+
+          def valid_parameters_types?(params)
+            params.all? do |param|
+              type = param[0]
+              (type == :req) || (type == :opt)
+            end
+          end
+
+          def block_parameters_error
+            "Invalid attribute option :unless. When it is a Proc it can have maximum two regular parameters (object, context)"
+          end
+
+          def callable_parameters_error
+            "Invalid attribute option :unless. When it is a callable object it must have two regular parameters (object, context)"
+          end
+
+          def must_be_callable
+            "Invalid attribute option :unless. It must be a Symbol, a Proc or respond to :call"
+          end
+        end
+      end
+    end
+  end
+end