treaty 0.0.1 → 0.2.0

data/lib/treaty/attribute/option/validators/inclusion_validator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Validators
+        # Validates that attribute value is included in allowed set.
+        #
+        # ## Usage Examples
+        #
+        # Simple mode:
+        #   string :provider, in: %w[twitter linkedin github]
+        #
+        # Advanced mode:
+        #   string :provider, inclusion: { in: %w[twitter linkedin github], message: "Invalid provider" }
+        #
+        # ## Advanced Mode
+        #
+        # Uses `:in` as the value key (instead of default `:is`).
+        # Schema format: `{ in: [...], message: nil }`
+        class InclusionValidator < Treaty::Attribute::Option::Base
+          # Validates that allowed values are provided as non-empty array
+          #
+          # @raise [Treaty::Exceptions::Validation] If allowed values are not valid
+          # @return [void]
+          def validate_schema!
+            allowed_values = option_value
+
+            return if allowed_values.is_a?(Array) && !allowed_values.empty?
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.validators.inclusion.invalid_schema", attribute: @attribute_name)
+          end
+
+          # Validates that value is included in allowed set
+          # Skips validation for nil values (handled by RequiredValidator)
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If value is not in allowed set
+          # @return [void]
+          def validate_value!(value)
+            return if value.nil? # Inclusion validation doesn't check for nil, required does.
+
+            allowed_values = option_value
+
+            return if allowed_values.include?(value)
+
+            message = custom_message || default_message(allowed_values, value)
+
+            raise Treaty::Exceptions::Validation, message
+          end
+
+          protected
+
+          # Returns the value key for inclusion validator
+          # Uses :in instead of default :is
+          #
+          # @return [Symbol] The value key (:in)
+          def value_key
+            :in
+          end
+
+          private
+
+          # Generates default error message with allowed values using I18n
+          #
+          # @param allowed_values [Array] Array of allowed values
+          # @param value [Object] The actual value that failed validation
+          # @return [String] Default error message
+          def default_message(allowed_values, value)
+            I18n.t("treaty.attributes.validators.inclusion.not_included",
+                   attribute: @attribute_name,
+                   allowed: allowed_values.join(", "),
+                   value:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/option/validators/required_validator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Validators
+        # Validates that attribute value is present (not nil and not empty).
+        #
+        # ## Usage Examples
+        #
+        # Helper mode:
+        #   string :title, :required  # Maps to required: true
+        #   string :bio, :optional    # Maps to required: false
+        #
+        # Simple mode:
+        #   string :title, required: true
+        #   string :bio, required: false
+        #
+        # Advanced mode:
+        #   string :title, required: { is: true, message: "Title is mandatory" }
+        #
+        # ## Default Behavior
+        #
+        # - Request attributes: required by default (required: true)
+        # - Response attributes: optional by default (required: false)
+        #
+        # ## Validation Rules
+        #
+        # A value is considered present if:
+        # - It is not nil
+        # - It is not empty (for String, Array, Hash)
+        #
+        # ## Advanced Mode
+        #
+        # Schema format: `{ is: true/false, message: nil }`
+        class RequiredValidator < Treaty::Attribute::Option::Base
+          # Validates schema (no validation needed, already normalized)
+          #
+          # @return [void]
+          def validate_schema!
+            # Schema structure is already normalized by OptionNormalizer.
+            # Nothing to validate here.
+          end
+
+          # Validates that required attribute has a present value
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If required but value is missing/empty
+          # @return [void]
+          def validate_value!(value)
+            return unless required?
+            return if present?(value)
+
+            message = custom_message || default_message
+
+            raise Treaty::Exceptions::Validation, message
+          end
+
+          private
+
+          # Checks if attribute is required
+          #
+          # @return [Boolean] True if attribute is required
+          def required?
+            return false if @option_schema.nil?
+
+            # Use option_value helper which correctly extracts value based on mode
+            option_value == true
+          end
+
+          # Checks if value is present (not nil and not empty)
+          #
+          # @param value [Object] The value to check
+          # @return [Boolean] True if value is present
+          def present?(value)
+            return false if value.nil?
+            return false if value.respond_to?(:empty?) && value.empty?
+
+            true
+          end
+
+          # Generates default error message using I18n
+          #
+          # @return [String] Default error message
+          def default_message
+            I18n.t("treaty.attributes.validators.required.blank", attribute: @attribute_name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Validators
+        # Validates that attribute value matches the declared type.
+        #
+        # ## Supported Types
+        #
+        # - `:integer` - Ruby Integer
+        # - `:string` - Ruby String
+        # - `:object` - Ruby Hash (for nested objects)
+        # - `:array` - Ruby Array (for collections)
+        # - `:datetime` - Ruby DateTime, Time, or Date
+        #
+        # ## Usage Examples
+        #
+        # Simple types:
+        #   integer :age
+        #   string :name
+        #   datetime :created_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
+        # - Datetime accepts DateTime, Time, or Date objects
+        #
+        # ## Note
+        #
+        # TypeValidator doesn't use option_schema - it validates based on attribute_type.
+        # This validator is always active for all attributes.
+        class TypeValidator < Treaty::Attribute::Option::Base
+          ALLOWED_TYPES = %i[integer string object array 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
+            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 :object
+              validate_object!(value)
+            when :array
+              validate_array!(value)
+            when :datetime
+              validate_datetime!(value)
+            end
+          end
+
+          private
+
+          # 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)
+            return if value.is_a?(Integer)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.validators.type.mismatch.integer",
+                         attribute: @attribute_name,
+                         actual: value.class)
+          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)
+            return if value.is_a?(String)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.validators.type.mismatch.string",
+                         attribute: @attribute_name,
+                         actual: value.class)
+          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)
+            return if value.is_a?(Hash)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.validators.type.mismatch.object",
+                         attribute: @attribute_name,
+                         actual: value.class)
+          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)
+            return if value.is_a?(Array)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.validators.type.mismatch.array",
+                         attribute: @attribute_name,
+                         actual: value.class)
+          end
+
+          # Validates that value is a DateTime, Time, or Date
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If value is not a datetime type
+          # @return [void]
+          def validate_datetime!(value)
+            # TODO: It is better to divide it into different methods for each class.
+            return if value.is_a?(DateTime) || value.is_a?(Time) || value.is_a?(Date)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.validators.type.mismatch.datetime",
+                         attribute: @attribute_name,
+                         actual: value.class)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/option_normalizer.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Treaty
+  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 }
+      }.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
+        #
+        # @param options [Hash] Options hash in simple or advanced mode
+        # @return [Hash] Normalized options in advanced mode
+        def normalize(options)
+          options.each_with_object({}) do |(key, value), result|
+            advanced_key, normalized_value = normalize_option(key, value)
+            result[advanced_key] = normalized_value
+          end
+        end
+
+        private
+
+        # 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

data/lib/treaty/attribute/option_orchestrator.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Treaty
+  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
+      # @return [Object] Transformed value
+      def transform_value(value)
+        @processors.values.reduce(value) do |current_value, processor|
+          processor.transform_value(current_value)
+        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[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 unless processor_class
+
+          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