treaty 0.17.0 → 0.19.0

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

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        module Validators
+          # Validates that string attribute value matches a specific format.
+          #
+          # ## Supported Formats
+          #
+          # - `:uuid` - Universally unique identifier
+          # - `:email` - Email address (RFC 2822 compliant)
+          # - `:password` - Password (8-16 chars, must contain digit, lowercase, and uppercase)
+          # - `:duration` - ActiveSupport::Duration compatible string (e.g., "1 day", "2 hours")
+          # - `:date` - ISO 8601 date string (e.g., "2025-01-15")
+          # - `:datetime` - ISO 8601 datetime string (e.g., "2025-01-15T10:30:00Z")
+          # - `:time` - Time string (e.g., "10:30:00", "10:30 AM")
+          # - `:boolean` - Boolean string ("true", "false", "0", "1")
+          #
+          # ## Usage Examples
+          #
+          # Simple mode:
+          #   string :email, format: :email
+          #   string :started_on, format: :date
+          #
+          # Advanced mode:
+          #   string :email, format: { is: :email }
+          #   string :started_on, format: { is: :date, message: "Invalid date format" }
+          #   string :started_on, format: { is: :date, message: ->(attribute:, value:, **) { "#{attribute} has invalid date: #{value}" } } # rubocop:disable Layout/LineLength
+          #
+          # ## Validation Rules
+          #
+          # - Only works with `:string` type attributes
+          # - Raises Treaty::Exceptions::Validation if used with non-string types
+          # - Skips validation for nil values (handled by RequiredValidator)
+          # - Each format has a pattern and/or validator for flexible validation
+          #
+          # ## Extensibility
+          #
+          # To add new formats, extend DEFAULT_FORMATS hash with format definition:
+          #   DEFAULT_FORMATS[:custom_format] = {
+          #     pattern: /regex/,
+          #     validator: ->(value) { custom_validation_logic }
+          #   }
+          class FormatValidator < Treaty::Entity::Attribute::Option::Base # rubocop:disable Metrics/ClassLength
+            # UUID format regex (8-4-4-4-12 hexadecimal pattern)
+            UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+            # Password format regex (8-16 chars, at least one digit, lowercase, and uppercase)
+            PASSWORD_PATTERN = /\A(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z]).{8,16}\z/
+
+            # Boolean string format regex (accepts "true", "false", "0", "1" case-insensitive)
+            BOOLEAN_PATTERN = /\A(true|false|0|1)\z/i
+
+            # Default format definitions with patterns and validators
+            # Each format can have:
+            # - pattern: Regex for pattern matching
+            # - validator: Lambda for custom validation logic
+            DEFAULT_FORMATS = {
+              uuid: {
+                pattern: UUID_PATTERN,
+                validator: nil
+              },
+              email: {
+                pattern: URI::MailTo::EMAIL_REGEXP,
+                validator: nil
+              },
+              password: {
+                pattern: PASSWORD_PATTERN,
+                validator: nil
+              },
+              duration: {
+                pattern: nil,
+                validator: lambda do |value|
+                  ActiveSupport::Duration.parse(value)
+                  true
+                rescue StandardError
+                  false
+                end
+              },
+              date: {
+                pattern: nil,
+                validator: lambda do |value|
+                  Date.parse(value)
+                  true
+                rescue ArgumentError, TypeError
+                  false
+                end
+              },
+              datetime: {
+                pattern: nil,
+                validator: lambda do |value|
+                  DateTime.parse(value)
+                  true
+                rescue ArgumentError, TypeError
+                  false
+                end
+              },
+              time: {
+                pattern: nil,
+                validator: lambda do |value|
+                  Time.parse(value)
+                  true
+                rescue ArgumentError, TypeError
+                  false
+                end
+              },
+              boolean: {
+                pattern: BOOLEAN_PATTERN,
+                validator: nil
+              }
+            }.freeze
+
+            # Validates that format is only used with string type attributes
+            # and that the format name is valid
+            #
+            # @raise [Treaty::Exceptions::Validation] If format is used with non-string type
+            # @raise [Treaty::Exceptions::Validation] If format name is unknown
+            # @return [void]
+            def validate_schema! # rubocop:disable Metrics/MethodLength
+              # Format option only works with string types
+              unless @attribute_type == :string
+                raise Treaty::Exceptions::Validation,
+                      I18n.t(
+                        "treaty.attributes.validators.format.type_mismatch",
+                        attribute: @attribute_name,
+                        type: @attribute_type
+                      )
+              end
+
+              format_name = option_value
+
+              # Validate that format name exists
+              return if formats.key?(format_name)
+
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.validators.format.unknown_format",
+                      attribute: @attribute_name,
+                      format_name:,
+                      allowed: formats.keys.join(", ")
+                    )
+            end
+
+            # Validates that the value matches the specified format
+            # Skips validation for nil values (handled by RequiredValidator)
+            #
+            # @param value [String] The value to validate
+            # @raise [Treaty::Exceptions::Validation] If value doesn't match format
+            # @return [void]
+            def validate_value!(value) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+              return if value.nil? # Format validation doesn't check for nil, required does.
+
+              format_name = option_value
+              format_definition = formats[format_name]
+
+              # Allow blank values (empty strings should be caught by required validator)
+              return if value.to_s.strip.empty?
+
+              # Apply pattern matching if defined
+              if format_definition.fetch(:pattern)
+                return if value.match?(format_definition.fetch(:pattern))
+
+                # Pattern failed, and no validator - raise error
+                unless format_definition.fetch(:validator)
+                  attributes = {
+                    attribute: @attribute_name,
+                    value:,
+                    format_name:
+                  }
+
+                  message = resolve_custom_message(**attributes) || default_message(**attributes)
+
+                  raise Treaty::Exceptions::Validation, message
+                end
+              end
+
+              # Apply validator if defined
+              return unless format_definition.fetch(:validator)
+              return if format_definition.fetch(:validator).call(value)
+
+              attributes = {
+                attribute: @attribute_name,
+                value:,
+                format_name:
+              }
+
+              message = resolve_custom_message(**attributes) || default_message(**attributes)
+
+              raise Treaty::Exceptions::Validation, message
+            end
+
+            private
+
+            # Returns the available formats (allows for extension)
+            #
+            # @return [Hash] Hash of available formats with their definitions
+            def formats
+              DEFAULT_FORMATS
+            end
+
+            # Generates default error message for format validation failure using I18n
+            #
+            # @param attribute [Symbol] The attribute name
+            # @param value [Object] The actual value that failed validation
+            # @param format_name [Symbol] The format name
+            # @return [String] Default error message
+            def default_message(attribute:, value:, format_name:)
+              I18n.t(
+                "treaty.attributes.validators.format.mismatch",
+                attribute:,
+                value:,
+                format_name:
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    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::Entity::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)
+
+              attributes = {
+                attribute: @attribute_name,
+                value:,
+                allowed_values:
+              }
+
+              message = resolve_custom_message(**attributes) || default_message(**attributes)
+
+              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 attribute [Symbol] The attribute name
+            # @param value [Object] The actual value that failed validation
+            # @param allowed_values [Array] Array of allowed values
+            # @return [String] Default error message
+            def default_message(attribute:, value:, allowed_values:)
+              I18n.t(
+                "treaty.attributes.validators.inclusion.not_included",
+                attribute:,
+                allowed: allowed_values.join(", "),
+                value:
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    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::Entity::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 = resolve_custom_message(
+                attribute: @attribute_name,
+                value:
+              ) || 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
+end

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