serega 0.42.0 → 0.50.0

data/lib/serega/plugins/formatters/formatters.rb

@@ -1,322 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaPlugins
-    #
-    # Plugin :formatters
-    #
-    # Defines named value formatters once and applies them to any attribute.
-    #
-    # Use `config.formatters.add()` to register formatters. The `:format`
-    # attribute option then accepts a formatter name or a callable directly.
-    #
-    # Formatters receive up to 2 parameters: the value and the context.
-    #
-    # @example
-    #   class AppSerializer < Serega
-    #     plugin :formatters, formatters: {
-    #       iso8601: ->(value) { value.iso8601 },
-    #       on_off: ->(value) { value ? 'ON' : 'OFF' },
-    #       money: ->(value) { value.round(2) },
-    #       date: DateTypeFormatter # callable
-    #     }
-    #   end
-    #
-    #   class UserSerializer < Serega
-    #     # Additionally we can add formatters via config in subclasses
-    #     config.formatters.add(
-    #       iso8601: ->(value) { value.iso8601 },
-    #       on_off: ->(value) { value ? 'ON' : 'OFF' },
-    #       money: ->(value) { value.round(2) }
-    #     )
-    #
-    #     # Using predefined formatter
-    #     attribute :commission, format: :money
-    #     attribute :is_logged_in, format: :on_off
-    #     attribute :created_at, format: :iso8601
-    #     attribute :updated_at, format: :iso8601
-    #
-    #     # Using `callable` formatter
-    #     attribute :score_percent, format: PercentFormatter # callable class
-    #     attribute :score_percent, format: proc { |percent| "#{percent.round(2)}%" }
-    #   end
-    #
-    module Formatters
-      # @return [Symbol] Plugin name
-      # @private
-      def self.plugin_name
-        :formatters
-      end
-
-      # Checks requirements and loads additional plugins
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param opts [Hash] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.before_load_plugin(serializer_class, **opts)
-        allowed_keys = %i[formatters]
-        opts.each_key do |key|
-          next if allowed_keys.include?(key)
-
-          raise SeregaError,
-            "Plugin #{plugin_name.inspect} does not accept the #{key.inspect} option. Allowed options:\n" \
-            "  - :formatters [Hash<Symbol, #call>] - Formatters (names and according callable values)"
-        end
-      end
-
-      #
-      # Applies plugin code to specific serializer
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param _opts [Hash] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.load_plugin(serializer_class, **_opts)
-        serializer_class::SeregaConfig.include(ConfigInstanceMethods)
-        serializer_class::SeregaAttributeNormalizer.include(AttributeNormalizerInstanceMethods)
-        serializer_class::SeregaAttribute.include(AttributeInstanceMethods)
-        serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
-      end
-
-      #
-      # Adds config options and runs other callbacks after plugin was loaded
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param opts [Hash] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.after_load_plugin(serializer_class, **opts)
-        config = serializer_class.config
-        config.opts[:formatters] = {}
-        config.formatters.add(opts[:formatters] || {})
-        config.attribute_keys << :format
-      end
-
-      # Formatters plugin config
-      class FormattersConfig
-        attr_reader :opts
-
-        #
-        # Initializes formatters config object
-        #
-        # @param opts [Hash] options
-        #
-        # @return FormattersConfig
-        def initialize(opts)
-          @opts = opts
-        end
-
-        # Adds new formatters
-        #
-        # @param formatters [Hash<Symbol, #call>] hash key is a formatter name and
-        #   hash value is a callable instance to format value
-        #
-        # @return [void]
-        def add(formatters)
-          formatters.each_pair do |key, value|
-            CheckFormatter.call(key, value)
-            opts[key] = value
-          end
-        end
-      end
-
-      #
-      # Config class additional/patched instance methods
-      #
-      # @see SeregaConfig
-      #
-      module ConfigInstanceMethods
-        # @return [SeregaPlugins::Formatters::FormattersConfig] current formatters config
-        def formatters
-          @formatters ||= FormattersConfig.new(opts.fetch(:formatters))
-        end
-      end
-
-      #
-      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
-      #
-      # @see Serega::SeregaValidations::CheckAttributeParams
-      #
-      # @private
-      module CheckAttributeParamsInstanceMethods
-        private
-
-        def check_opts
-          super
-
-          CheckOptFormat.call(opts, self.class.serializer_class)
-        end
-      end
-
-      #
-      # AttributeNormalizer class additional/patched instance methods
-      #
-      # @see SeregaAttributeNormalizer
-      #
-      # @private
-      module AttributeNormalizerInstanceMethods
-        # Block or callable instance that will format attribute values
-        # @return [Proc, #call, nil] Block or callable instance that will format attribute values
-        def formatter
-          @formatter ||= prepare_formatter
-        end
-
-        #
-        # Returns formatter method signature for optimized calling
-        #
-        # @return [String, nil] Formatter signature ("1", "2", "1_ctx") or nil if no formatter
-        #
-        def formatter_signature
-          @formatter_signature ||= prepare_formatter_signature
-        end
-
-        private
-
-        def prepare_formatter
-          formatter = init_opts[:format]
-          return unless formatter
-
-          formatter = self.class.serializer_class.config.formatters.opts.fetch(formatter) if formatter.is_a?(Symbol)
-          formatter
-        end
-
-        def prepare_formatter_signature
-          return unless formatter
-
-          SeregaUtils::MethodSignature.call(formatter, pos_limit: 2, keyword_args: [:ctx])
-        end
-      end
-
-      #
-      # Attribute class additional/patched instance methods
-      #
-      # @see SeregaAttribute
-      #
-      # @private
-      module AttributeInstanceMethods
-        #
-        # Returns formatted attribute value
-        #
-        # @param object [Object] Serialized object
-        # @param context [Hash] Serialization context
-        #
-        # @return [Object] Formatted attribute value
-        #
-        def value(object, context, batches: nil)
-          result = super # `:batches` parameter is needed to find unformatted result
-          return result unless formatter
-
-          case formatter_signature
-          when "1" then formatter.call(result)
-          when "1_ctx" then formatter.call(result, ctx: context)
-          else # "2"
-            formatter.call(result, context)
-          end
-        end
-
-        private
-
-        attr_reader :formatter, :formatter_signature
-
-        def set_normalized_vars(normalizer)
-          super
-          @formatter = normalizer.formatter
-          @formatter_signature = normalizer.formatter_signature
-        end
-      end
-
-      #
-      # Validator for attribute :format option
-      #
-      # @private
-      class CheckOptFormat
-        class << self
-          #
-          # Checks attribute :format option must be registered or valid callable with maximum 2 args
-          #
-          # @param opts [value] Attribute options
-          #
-          # @raise [SeregaError] Attribute validation error
-          #
-          # @return [void]
-          #
-          def call(opts, serializer_class)
-            return unless opts.key?(:format)
-
-            formatter = opts[:format]
-
-            if formatter.is_a?(Symbol)
-              check_formatter_defined(serializer_class, formatter)
-            else
-              CheckFormatter.call(:format, formatter)
-            end
-          end
-
-          private
-
-          def check_formatter_defined(serializer_class, formatter)
-            return if serializer_class.config.formatters.opts.key?(formatter)
-
-            raise Serega::SeregaError, "Formatter `#{formatter.inspect}` was not defined"
-          end
-        end
-      end
-
-      #
-      # Validator for formatters defined as config options or directly as attribute :format option
-      #
-      # @private
-      class CheckFormatter
-        class << self
-          #
-          # Check formatter type and parameters
-          #
-          # @param formatter_name [Symbol] Name of formatter
-          # @param formatter [#call] Formatter callable object
-          #
-          # @return [void]
-          #
-          def call(formatter_name, formatter)
-            raise Serega::SeregaError, "Option #{formatter_name.inspect} must have callable value" unless formatter.respond_to?(:call)
-
-            signature = SeregaUtils::MethodSignature.call(formatter, pos_limit: 2, keyword_args: [:ctx])
-            raise SeregaError, signature_error unless valid_signature?(signature)
-          end
-
-          private
-
-          def valid_signature?(signature)
-            case signature
-            when "1"      # (object)
-              true
-            when "2"      # (object, context)
-              true
-            when "1_ctx"  # (object, :ctx)
-              true
-            else
-              false
-            end
-          end
-
-          def signature_error
-            <<~ERROR.strip
-              Invalid formatter parameters, valid parameters signatures:
-              - (object)          # one positional parameter
-              - (object, context) # two positional parameters
-              - (object, :ctx)    # one positional parameter and :ctx keyword
-            ERROR
-          end
-        end
-      end
-    end
-
-    register_plugin(Formatters.plugin_name, Formatters)
-  end
-end

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

@@ -1,287 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaPlugins
-    #
-    # Plugin :if
-    #
-    # Adds `:if`, `:unless`, `:if_value`, `:unless_value` attribute options to
-    # conditionally remove attributes from the response.
-    #
-    # `:if`/`:unless` receive the serialized object and context, and are
-    # checked before the attribute value is found. `:if_value`/`:unless_value`
-    # receive the already-found value and context, checked after. The latter
-    # two cannot be used with the `:serializer` option, since a relationship
-    # has no "serialized value" of its own — use `:if`/`:unless` instead.
-    #
-    # See also the plugin-free `:hide` option (README.md#selecting-fields),
-    # which hides an attribute unconditionally.
-    #
-    # @example
-    #   class UserSerializer < Serega
-    #     attribute :email, if: :active? # if user.active?
-    #     attribute :email, if: proc { |user, ctx| user == ctx[:current_user] } # using context
-    #     attribute :email, if: CustomPolicy.method(:view_email?) # any callable
-    #
-    #     attribute :email, unless: :hidden? # unless user.hidden?
-    #     attribute :email, if_value: :present? # if email.present?
-    #     attribute :email, unless_value: :blank? # unless email.blank?
-    #   end
-    #
-    module If
-      # @return [Symbol] Plugin name
-      # @private
-      def self.plugin_name
-        :if
-      end
-
-      #
-      # Applies plugin code to specific serializer
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param _opts [Hash] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      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::SeregaAttribute.include(AttributeInstanceMethods)
-        serializer_class::SeregaAttributeNormalizer.include(AttributeNormalizerInstanceMethods)
-        serializer_class::SeregaPlanPoint.include(PlanPointInstanceMethods)
-        serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
-        serializer_class::SeregaObjectSerializer.include(ObjectSerializerInstanceMethods)
-        serializer_class::SeregaDataBuilder.extend(DataBuilderClassMethods)
-      end
-
-      #
-      # Adds config options and runs other callbacks after plugin was loaded
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param opts [Hash] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.after_load_plugin(serializer_class, **opts)
-        serializer_class.config.attribute_keys << :if << :if_value << :unless << :unless_value
-      end
-
-      #
-      # SeregaAttributeNormalizer additional/patched instance methods
-      #
-      # @see SeregaAttributeNormalizer::AttributeInstanceMethods
-      #
-      # @private
-      module AttributeNormalizerInstanceMethods
-        #
-        # Returns prepared attribute :if_options.
-        #
-        # @return [Hash] prepared options for :if plugin
-        #
-        def if_options
-          @if_options ||= {
-            if: prepare_if_option(init_opts[:if]),
-            unless: prepare_if_option(init_opts[:unless]),
-            if_value: prepare_if_option(init_opts[:if_value]),
-            unless_value: prepare_if_option(init_opts[:unless_value])
-          }.freeze
-        end
-
-        #
-        # Returns method signatures for all if options for optimized calling
-        #
-        # @return [Hash] Hash with signatures for each if option type
-        #
-        def if_options_signatures
-          @if_options_signatures ||= {
-            if: if_option_signature(:if),
-            unless: if_option_signature(:unless),
-            if_value: if_option_signature(:if_value),
-            unless_value: if_option_signature(:unless_value)
-          }.freeze
-        end
-
-        private
-
-        def if_option_signature(option_name)
-          callable = if_options[option_name]
-          return unless callable
-
-          SeregaUtils::MethodSignature.call(callable, pos_limit: 2, keyword_args: [:ctx])
-        end
-
-        def prepare_if_option(if_option)
-          return unless if_option
-          return KeywordConditionResolver.new(if_option) if if_option.is_a?(Symbol)
-
-          if_option
-        end
-      end
-
-      #
-      # Resolves keyword-based conditions for if/unless options
-      #
-      # @private
-      class KeywordConditionResolver
-        def initialize(keyword)
-          @keyword = keyword
-        end
-
-        #
-        # Calls the keyword method on the object
-        #
-        # @param object [Object] the object to call method on
-        # @return [Object] result of method call
-        #
-        def call(object)
-          object.public_send(@keyword)
-        end
-      end
-
-      #
-      # SeregaAttribute additional/patched instance methods
-      #
-      # @see Serega::SeregaAttribute
-      #
-      # @private
-      module AttributeInstanceMethods
-        # @return [Hash] provided :if options
-        attr_reader :opt_if
-
-        # @return [Hash] signatures for provided :if options
-        attr_reader :opt_if_signatures
-
-        private
-
-        def set_normalized_vars(normalizer)
-          super
-          @opt_if = normalizer.if_options
-          @opt_if_signatures = normalizer.if_options_signatures
-        end
-      end
-
-      #
-      # Serega::SeregaPlanPoint additional/patched instance methods
-      #
-      # @see Serega::SeregaPlanPoint::InstanceMethods
-      #
-      # @private
-      module PlanPointInstanceMethods
-        #
-        # @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.opt_if[opt_if_name]
-          opt_unless = attribute.opt_if[opt_unless_name]
-          return true if opt_if.nil? && opt_unless.nil?
-
-          res_if = opt_if ? check_condition(opt_if, opt_if_name, obj, ctx) : true
-          res_unless = opt_unless ? !check_condition(opt_unless, opt_unless_name, obj, ctx) : true
-          res_if && res_unless
-        end
-
-        def check_condition(condition, condition_name, object, context)
-          signature = attribute.opt_if_signatures[condition_name]
-
-          case signature
-          when "1" then condition.call(object)
-          when "2" then condition.call(object, context)
-          when "1_ctx" then condition.call(object, ctx: context)
-          when "2_ctx" then condition.call(object, context, ctx: context)
-          else # "0"
-            condition.call
-          end
-        end
-      end
-
-      #
-      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
-      #
-      # @see Serega::SeregaValidations::CheckAttributeParams
-      #
-      # @private
-      module CheckAttributeParamsInstanceMethods
-        private
-
-        def check_opts
-          super
-
-          CheckOptIf.call(opts)
-          CheckOptUnless.call(opts)
-          CheckOptIfValue.call(opts)
-          CheckOptUnlessValue.call(opts)
-        end
-      end
-
-      #
-      # SeregaDataBuilder additional/patched class methods
-      #
-      # Overrides `build_data_object` to handle plans where some keys were skipped
-      # by `:if`/`:unless`/`:if_value`/`:unless_value` conditions, so the Data class
-      # is built from the actually-present keys rather than the full plan.
-      #
-      # @see Serega::SeregaDataBuilder
-      #
-      # @private
-      module DataBuilderClassMethods
-        private
-
-        def build_data_object(plan, hash_data)
-          if hash_data.size < plan.points.size
-            plan.class.data_class_for(hash_data.keys).new(**hash_data)
-          else
-            super
-          end
-        end
-      end
-
-      #
-      # SeregaObjectSerializer additional/patched class methods
-      #
-      # @see Serega::SeregaObjectSerializer
-      #
-      # @private
-      module ObjectSerializerInstanceMethods
-        private
-
-        # Skip the whole point for this object (its value is never resolved).
-        def resolve_point(object, point, _container, _batches, _child_plan)
-          return unless point.satisfy_if_conditions?(object, context)
-
-          super
-        end
-
-        # Skip only the assignment based on the resolved value. Levels resolve
-        # points in attribute order, so simply not assigning keeps the remaining
-        # keys in declared order — no slot to reserve or delete.
-        def write_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

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaPlugins
-    module If
-      #
-      # Validator for attribute :if option
-      #
-      # @private
-      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)
-
-            signature = SeregaUtils::MethodSignature.call(value, pos_limit: 2, keyword_args: [:ctx])
-            raise SeregaError, signature_error unless valid_signature?(signature)
-          end
-
-          def must_be_callable
-            "Invalid attribute option :if. It must be a Symbol, a Proc or respond to :call"
-          end
-
-          def valid_signature?(signature)
-            case signature
-            when "0"      # no parameters
-              true
-            when "1"      # (object)
-              true
-            when "2"      # (object, context)
-              true
-            when "1_ctx"  # (object, :ctx)
-              true
-            when "2_ctx"  # (object, context, :ctx)
-              true
-            else
-              false
-            end
-          end
-
-          def signature_error
-            <<~ERROR.strip
-              Invalid attribute option :if parameters, valid parameters signatures:
-              - ()                     # no parameters
-              - (object)               # one positional parameter
-              - (object, context)      # two positional parameters
-              - (object, :ctx)         # one positional parameter and :ctx keyword
-              - (object, context, :ctx) # two positional parameters and :ctx keyword
-            ERROR
-          end
-        end
-      end
-    end
-  end
-end