treaty 0.18.0 → 0.20.0

data/lib/treaty/entity/attribute/option/validators/type_validator.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        module Validators
+          # Validates that attribute value matches the declared type.
+          #
+          # ## Supported Types
+          #
+          # - `:integer` - Ruby Integer
+          # - `:string` - Ruby String
+          # - `:boolean` - Ruby TrueClass or FalseClass
+          # - `:object` - Ruby Hash (for nested objects)
+          # - `:array` - Ruby Array (for collections)
+          # - `:date` - Ruby Date
+          # - `:time` - Ruby Time
+          # - `:datetime` - Ruby DateTime
+          #
+          # ## Usage Examples
+          #
+          # Simple types:
+          #   integer :age
+          #   string :name
+          #   boolean :published
+          #   date :published_on
+          #   time :created_at
+          #   datetime :updated_at
+          #
+          # Nested structures:
+          #   object :author do
+          #     string :name
+          #   end
+          #
+          #   array :tags do
+          #     string :_self  # Simple array of strings
+          #   end
+          #
+          # ## Validation Rules
+          #
+          # - Validates only non-nil values (nil handling is done by RequiredValidator)
+          # - Type mismatch raises Treaty::Exceptions::Validation
+          # - Date accepts only Date objects (not DateTime or Time)
+          # - Time accepts only Time objects (not Date or DateTime)
+          # - DateTime accepts only DateTime objects (not Date or Time)
+          #
+          # ## Note
+          #
+          # TypeValidator doesn't use option_schema - it validates based on attribute_type.
+          # This validator is always active for all attributes.
+          class TypeValidator < Treaty::Entity::Attribute::Option::Base
+            ALLOWED_TYPES = %i[integer string boolean object array date time datetime].freeze
+
+            # Validates that the attribute type is one of the allowed types
+            #
+            # @raise [Treaty::Exceptions::Validation] If type is not allowed
+            # @return [void]
+            def validate_schema!
+              return if ALLOWED_TYPES.include?(@attribute_type)
+
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.validators.type.unknown_type",
+                      type: @attribute_type,
+                      attribute: @attribute_name,
+                      allowed: ALLOWED_TYPES.join(", ")
+                    )
+            end
+
+            # Validates that the value matches the declared type
+            # Skips validation for nil values (handled by RequiredValidator)
+            #
+            # @param value [Object] The value to validate
+            # @raise [Treaty::Exceptions::Validation] If value type doesn't match
+            # @return [void]
+            def validate_value!(value) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+              return if value.nil? # Type validation doesn't check for nil, required does.
+
+              case @attribute_type
+              when :integer
+                validate_integer!(value)
+              when :string
+                validate_string!(value)
+              when :boolean
+                validate_boolean!(value)
+              when :object
+                validate_object!(value)
+              when :array
+                validate_array!(value)
+              when :date
+                validate_date!(value)
+              when :time
+                validate_time!(value)
+              when :datetime
+                validate_datetime!(value)
+              end
+            end
+
+            private
+
+            # Common type validation logic
+            # Checks if value matches expected type and raises exception with appropriate message
+            #
+            # @param value [Object] The value to validate
+            # @param expected_type [Symbol] The expected type symbol
+            # @yield Block that returns true if value is valid
+            # @raise [Treaty::Exceptions::Validation] If type validation fails
+            # @return [void]
+            def validate_type!(value, expected_type)
+              return if yield(value)
+
+              actual_type = value.class
+
+              attributes = {
+                attribute: @attribute_name,
+                value:,
+                expected_type:,
+                actual_type:
+              }
+
+              message = resolve_custom_message(**attributes) || default_message(**attributes)
+
+              raise Treaty::Exceptions::Validation, message
+            end
+
+            # Generates default error message for type mismatch using I18n
+            #
+            # @param attribute [Symbol] The attribute name
+            # @param expected_type [Symbol] The expected type
+            # @param actual_type [Class] The actual class of the value
+            # @return [String] Default error message
+            def default_message(attribute:, expected_type:, actual_type:, **)
+              I18n.t(
+                "treaty.attributes.validators.type.mismatch.#{expected_type}",
+                attribute:,
+                actual: actual_type
+              )
+            end
+
+            # Validates that value is an Integer
+            #
+            # @param value [Object] The value to validate
+            # @raise [Treaty::Exceptions::Validation] If value is not an Integer
+            # @return [void]
+            def validate_integer!(value)
+              validate_type!(value, :integer) { |v| v.is_a?(Integer) }
+            end
+
+            # Validates that value is a String
+            #
+            # @param value [Object] The value to validate
+            # @raise [Treaty::Exceptions::Validation] If value is not a String
+            # @return [void]
+            def validate_string!(value)
+              validate_type!(value, :string) { |v| v.is_a?(String) }
+            end
+
+            # Validates that value is a Boolean (TrueClass or FalseClass)
+            #
+            # @param value [Object] The value to validate
+            # @raise [Treaty::Exceptions::Validation] If value is not a Boolean
+            # @return [void]
+            def validate_boolean!(value)
+              validate_type!(value, :boolean) { |v| v.is_a?(TrueClass) || v.is_a?(FalseClass) }
+            end
+
+            # Validates that value is a Hash (object type)
+            #
+            # @param value [Object] The value to validate
+            # @raise [Treaty::Exceptions::Validation] If value is not a Hash
+            # @return [void]
+            def validate_object!(value)
+              validate_type!(value, :object) { |v| v.is_a?(Hash) }
+            end
+
+            # Validates that value is an Array
+            #
+            # @param value [Object] The value to validate
+            # @raise [Treaty::Exceptions::Validation] If value is not an Array
+            # @return [void]
+            def validate_array!(value)
+              validate_type!(value, :array) { |v| v.is_a?(Array) }
+            end
+
+            # Validates that value is a Date (but not DateTime, since DateTime < Date)
+            #
+            # @param value [Object] The value to validate
+            # @raise [Treaty::Exceptions::Validation] If value is not a Date
+            # @return [void]
+            def validate_date!(value)
+              validate_type!(value, :date) { |v| v.is_a?(Date) && !v.is_a?(DateTime) }
+            end
+
+            # Validates that value is a Time or ActiveSupport::TimeWithZone
+            #
+            # @param value [Object] The value to validate
+            # @raise [Treaty::Exceptions::Validation] If value is not a Time
+            # @return [void]
+            def validate_time!(value)
+              validate_type!(value, :time) do |v|
+                v.is_a?(Time) || (defined?(ActiveSupport::TimeWithZone) && v.is_a?(ActiveSupport::TimeWithZone))
+              end
+            end
+
+            # Validates that value is a DateTime
+            #
+            # @param value [Object] The value to validate
+            # @raise [Treaty::Exceptions::Validation] If value is not a DateTime
+            # @return [void]
+            def validate_datetime!(value)
+              validate_type!(value, :datetime) { |v| v.is_a?(DateTime) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/option_normalizer.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      # Normalizes options from simple mode to advanced mode.
+      #
+      # ## Purpose
+      #
+      # All options are stored and processed internally in advanced mode.
+      # This normalizer converts simple mode to advanced mode automatically.
+      #
+      # ## Modes Explained
+      #
+      # ### Simple Mode (Concise syntax)
+      # ```ruby
+      # {
+      #   required: true,
+      #   as: :value,
+      #   in: %w[twitter linkedin github],
+      #   default: 12
+      # }
+      # ```
+      #
+      # ### Advanced Mode (With messages)
+      # ```ruby
+      # {
+      #   required: { is: true, message: nil },
+      #   as: { is: :value, message: nil },
+      #   inclusion: { in: %w[twitter linkedin github], message: nil },
+      #   default: { is: 12, message: nil }
+      # }
+      # ```
+      #
+      # ## Key Mappings
+      #
+      # Some simple mode keys are renamed in advanced mode:
+      # - `in:` → `inclusion:` (with value key `:in`)
+      #
+      # Others keep the same name:
+      # - `required:` → `required:` (with value key `:is`)
+      # - `as:` → `as:` (with value key `:is`)
+      # - `default:` → `default:` (with value key `:is`)
+      #
+      # ## Value Keys
+      #
+      # Each option has a value key in advanced mode:
+      # - Default: `:is` (most options)
+      # - Special: `:in` (inclusion validator)
+      #
+      # ## Message Field
+      #
+      # The `message` field in advanced mode allows custom error messages:
+      # - `nil` - Use default message (most common)
+      # - String - Custom error message for validation failures
+      #
+      # ## Usage in DSL
+      #
+      # Users can write in either mode:
+      #
+      # Simple mode:
+      #   string :provider, in: %w[twitter linkedin]
+      #
+      # Advanced mode:
+      #   string :provider, inclusion: { in: %w[twitter linkedin], message: "Invalid provider" }
+      #
+      # Both are normalized to advanced mode internally.
+      class OptionNormalizer
+        # Maps simple mode option keys to their advanced mode configuration.
+        # Format: simple_key => { advanced_key:, value_key: }
+        OPTION_KEY_MAPPING = {
+          in: { advanced_key: :inclusion, value_key: :in },
+          as: { advanced_key: :as, value_key: :is },
+          default: { advanced_key: :default, value_key: :is },
+          cast: { advanced_key: :cast, value_key: :to }
+        }.freeze
+        private_constant :OPTION_KEY_MAPPING
+
+        # Reverse mapping: advanced_key => value_key
+        # Used to determine value key when option is already in advanced mode.
+        ADVANCED_KEY_TO_VALUE_KEY = OPTION_KEY_MAPPING.each_with_object({}) do |(_, config), result|
+          result[config.fetch(:advanced_key)] = config.fetch(:value_key)
+        end.freeze
+        private_constant :ADVANCED_KEY_TO_VALUE_KEY
+
+        DEFAULT_VALUE_KEY = :is
+        private_constant :DEFAULT_VALUE_KEY
+
+        class << self
+          # Normalizes all options from simple mode to advanced mode
+          # and sorts them by position for consistent execution order.
+          #
+          # @param options [Hash] Options hash in simple or advanced mode
+          # @return [Hash] Normalized options in advanced mode, sorted by position
+          def normalize(options)
+            normalized = options.each_with_object({}) do |(key, value), result|
+              advanced_key, normalized_value = normalize_option(key, value)
+              result[advanced_key] = normalized_value
+            end
+
+            sort_by_position(normalized)
+          end
+
+          private
+
+          # Sorts options by their registered position.
+          # Options without position (like conditionals) sort first (position 0).
+          #
+          # @param options_hash [Hash] Normalized options hash
+          # @return [Hash] Options sorted by position
+          def sort_by_position(options_hash)
+            options_hash.sort_by do |option_name, _|
+              Option::Registry.position_for(option_name) || 0
+            end.to_h
+          end
+
+          # Normalizes a single option to advanced mode
+          #
+          # @param key [Symbol] Option key
+          # @param value [Object] Option value
+          # @return [Array<Symbol, Hash>] Tuple of [advanced_key, normalized_value]
+          def normalize_option(key, value) # rubocop:disable Metrics/MethodLength
+            mapping = OPTION_KEY_MAPPING.fetch(key, nil)
+
+            if mapping.present?
+              # Special handling for mapped options (e.g., in -> inclusion).
+              advanced_key = mapping.fetch(:advanced_key)
+              value_key = mapping.fetch(:value_key)
+              normalized_value = normalize_value(value, value_key)
+              [advanced_key, normalized_value]
+            else
+              # Check if this key is already an advanced mode key.
+              value_key = ADVANCED_KEY_TO_VALUE_KEY.fetch(key, nil) || DEFAULT_VALUE_KEY
+              normalized_value = normalize_value(value, value_key)
+              [key, normalized_value]
+            end
+          end
+
+          # Normalizes option value to advanced mode format
+          #
+          # @param value [Object] The option value (simple or advanced mode)
+          # @param value_key [Symbol] The key to use for the value (:is or :in)
+          # @return [Hash] Normalized hash with value_key and :message
+          def normalize_value(value, value_key)
+            if advanced_mode?(value, value_key)
+              # Already in advanced mode, ensure it has both keys.
+              # message: nil means use I18n default message from validators
+              { value_key => value.fetch(value_key), message: value.fetch(:message, nil) }
+            else
+              # Simple mode, convert to advanced.
+              # message: nil means use I18n default message from validators
+              { value_key => value, message: nil }
+            end
+          end
+
+          # Checks if value is already in advanced mode
+          #
+          # @param value [Object] The value to check
+          # @param value_key [Symbol] The expected value key
+          # @return [Boolean] True if value is a hash with the value key
+          def advanced_mode?(value, value_key)
+            value.is_a?(Hash) && value.key?(value_key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/option_orchestrator.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      # Orchestrates all option processors for a single attribute.
+      #
+      # ## Purpose
+      #
+      # Coordinates the execution of all option processors (validators and modifiers)
+      # for an attribute through three distinct processing phases.
+      #
+      # ## Responsibilities
+      #
+      # 1. **Processor Building** - Creates instances of all relevant option processors
+      # 2. **Schema Validation** - Validates DSL definition correctness (phase 1)
+      # 3. **Value Validation** - Validates runtime data values (phase 2)
+      # 4. **Value Transformation** - Transforms values through modifiers (phase 3)
+      # 5. **Name Transformation** - Provides target name if `as:` option is used
+      #
+      # ## Processing Phases
+      #
+      # ### Phase 1: Schema Validation
+      # Validates that the attribute definition in the DSL is correct.
+      # Called once during treaty definition loading.
+      #
+      # ```ruby
+      # orchestrator.validate_schema!
+      # ```
+      #
+      # ### Phase 2: Value Validation
+      # Validates that runtime data matches the constraints.
+      # Called for each request/response.
+      #
+      # ```ruby
+      # orchestrator.validate_value!(value)
+      # ```
+      #
+      # ### Phase 3: Value Transformation
+      # Transforms the value (applies defaults, renaming, etc.).
+      # Called for each request/response after validation.
+      #
+      # ```ruby
+      # transformed = orchestrator.transform_value(value)
+      # ```
+      #
+      # ## Usage
+      #
+      # Used by AttributeValidator to coordinate all option processing:
+      #
+      #   orchestrator = OptionOrchestrator.new(attribute)
+      #   orchestrator.validate_schema!
+      #   orchestrator.validate_value!(value)
+      #   transformed = orchestrator.transform_value(value)
+      #   target_name = orchestrator.target_name
+      #
+      # ## Processor Building
+      #
+      # Automatically:
+      # - Builds processor instances for all defined options
+      # - Always includes TypeValidator (even if not explicitly defined)
+      # - Validates that all options are registered in Registry
+      # - Raises error for unknown options
+      #
+      # ## Architecture
+      #
+      # Works with:
+      # - Option::Registry - Looks up processor classes
+      # - Option::Base - Base class for all processors
+      # - AttributeValidator - Uses orchestrator to coordinate processing
+      class OptionOrchestrator
+        # Creates a new orchestrator instance
+        #
+        # @param attribute [Attribute::Base] The attribute to orchestrate options for
+        def initialize(attribute)
+          @attribute = attribute
+          @processors = build_processors
+        end
+
+        # Phase 1: Validates all option schemas
+        # Ensures DSL definition is correct and all options are registered
+        #
+        # @raise [Treaty::Exceptions::Validation] If unknown options found
+        # @return [void]
+        def validate_schema!
+          validate_known_options!
+
+          @processors.each_value(&:validate_schema!)
+        end
+
+        # Phase 2: Validates value against all option validators
+        # Validates runtime data against all defined constraints
+        #
+        # @param value [Object] The value to validate
+        # @raise [Treaty::Exceptions::Validation] If validation fails
+        # @return [void]
+        def validate_value!(value)
+          @processors.each_value do |processor|
+            processor.validate_value!(value)
+          end
+        end
+
+        # Phase 3: Transforms value through all option modifiers
+        # Applies transformations like defaults, type coercion, etc.
+        #
+        # @param value [Object] The value to transform
+        # @param root_data [Hash] Full raw data from root level (used by computed modifier)
+        # @return [Object] Transformed value
+        def transform_value(value, root_data = {})
+          @processors.values.reduce(value) do |current_value, processor|
+            processor.transform_value(current_value, root_data)
+          end
+        end
+
+        # Checks if any processor transforms the attribute name
+        #
+        # @return [Boolean] True if any processor (like AsModifier) transforms names
+        def transforms_name?
+          @processors.values.any?(&:transforms_name?)
+        end
+
+        # Gets the target name from the processor that transforms names
+        # Returns original name if no transformation
+        #
+        # @return [Symbol] The target attribute name
+        def target_name
+          name_transformer = @processors.values.find(&:transforms_name?)
+          name_transformer ? name_transformer.target_name : @attribute.name
+        end
+
+        # Gets specific processor by option name
+        #
+        # @param option_name [Symbol] The option name (:required, :type, etc.)
+        # @return [Option::Base, nil] The processor instance or nil if not found
+        def processor_for(option_name)
+          @processors.fetch(option_name)
+        end
+
+        private
+
+        # Builds processor instances for all defined options
+        # Always includes TypeValidator even if not explicitly defined
+        #
+        # @return [Hash<Symbol, Option::Base>] Hash of option_name => processor
+        def build_processors # rubocop:disable Metrics/MethodLength
+          processors_hash = {}
+
+          @attribute.options.each do |option_name, option_schema|
+            processor_class = Option::Registry.processor_for(option_name)
+
+            next if processor_class.nil?
+
+            processors_hash[option_name] = processor_class.new(
+              attribute_name: @attribute.name,
+              attribute_type: @attribute.type,
+              option_schema:
+            )
+          end
+
+          # Always include type validator
+          unless processors_hash.key?(:type)
+            processors_hash[:type] = Option::Validators::TypeValidator.new(
+              attribute_name: @attribute.name,
+              attribute_type: @attribute.type,
+              option_schema: nil
+            )
+          end
+
+          processors_hash
+        end
+
+        # Validates that all options are registered in the Registry
+        #
+        # @raise [Treaty::Exceptions::Validation] If unknown options found
+        # @return [void]
+        def validate_known_options!
+          unknown_options = @attribute.options.keys - Option::Registry.all_options
+
+          return if unknown_options.empty?
+
+          raise Treaty::Exceptions::Validation,
+                I18n.t(
+                  "treaty.attributes.options.unknown",
+                  attribute: @attribute.name,
+                  unknown: unknown_options.join(", "),
+                  known: Option::Registry.all_options.join(", ")
+                )
+        end
+      end
+    end
+  end
+end