treaty 0.18.0 → 0.20.0

data/lib/treaty/entity/attribute/option/registry.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        # Central registry for all option processors (validators, modifiers, and conditionals).
+        #
+        # ## Purpose
+        #
+        # Provides a centralized registry pattern for managing all option processors.
+        # Enables dynamic discovery and extensibility of the option system.
+        #
+        # ## Responsibilities
+        #
+        # 1. **Registration** - Stores option processor classes
+        # 2. **Retrieval** - Provides access to registered processors
+        # 3. **Categorization** - Organizes processors by category (validator/modifier/conditional)
+        # 4. **Validation** - Checks if options are registered
+        #
+        # ## Registered Options
+        #
+        # ### Validators (sorted by position)
+        # - `:type` → TypeValidator (position: 100)
+        # - `:required` → RequiredValidator (position: 200)
+        # - `:inclusion` → InclusionValidator (position: 300)
+        # - `:format` → FormatValidator (position: 400)
+        #
+        # ### Modifiers (sorted by position)
+        # - `:transform` → TransformModifier (position: 500)
+        # - `:cast` → CastModifier (position: 600)
+        # - `:computed` → ComputedModifier (position: 700)
+        # - `:default` → DefaultModifier (position: 800)
+        # - `:as` → AsModifier (position: 900)
+        #
+        # ### Conditionals (no position - handled separately)
+        # - `:if` → IfConditional
+        # - `:unless` → UnlessConditional
+        #
+        # ## Usage
+        #
+        # Registration (done in RegistryInitializer):
+        #   Registry.register(:required, RequiredValidator, category: :validator, position: 200)
+        #   Registry.register(:if, IfConditional, category: :conditional)
+        #
+        # Retrieval (done in OptionOrchestrator):
+        #   processor_class = Registry.processor_for(:required)
+        #   processor = processor_class.new(...)
+        #
+        # ## Extensibility
+        #
+        # To add a new option:
+        # 1. Create processor class inheriting from Option::Base
+        # 2. Register it: `Registry.register(:my_option, MyProcessor, category: :validator)`
+        # 3. Option becomes available in DSL immediately
+        #
+        # ## Architecture
+        #
+        # Works with:
+        # - RegistryInitializer - Populates registry with built-in options
+        # - OptionOrchestrator - Uses registry to build processors
+        # - Option::Base - Base class for all registered processors
+        class Registry
+          class << self
+            # Register an option processor
+            #
+            # @param option_name [Symbol] The name of the option (e.g., :required, :as, :default)
+            # @param processor_class [Class] The processor class
+            # @param category [Symbol] The category (:validator, :modifier, or :conditional)
+            # @param position [Integer, nil] Execution order position (nil for conditionals)
+            def register(option_name, processor_class, category:, position: nil)
+              registry[option_name] = {
+                processor_class:,
+                category:,
+                position:
+              }
+            end
+
+            # Get processor class for an option
+            #
+            # @param option_name [Symbol] The name of the option
+            # @return [Class, nil] The processor class or nil if not found
+            def processor_for(option_name)
+              registry.dig(option_name, :processor_class)
+            end
+
+            # Get category for an option
+            #
+            # @param option_name [Symbol] The name of the option
+            # @return [Symbol, nil] The category (:validator or :modifier) or nil if not found
+            def category_for(option_name)
+              registry.dig(option_name, :category)
+            end
+
+            # Get position for an option
+            #
+            # @param option_name [Symbol] The name of the option
+            # @return [Integer, nil] The execution order position or nil if not set
+            def position_for(option_name)
+              registry.dig(option_name, :position)
+            end
+
+            # Check if an option is registered
+            #
+            # @param option_name [Symbol] The name of the option
+            # @return [Boolean]
+            def registered?(option_name)
+              registry.key?(option_name)
+            end
+
+            # Get all registered option names
+            #
+            # @return [Array<Symbol>]
+            def all_options
+              registry.keys
+            end
+
+            # Get all validators
+            #
+            # @return [Hash] Hash of option_name => processor_class for validators
+            def validators
+              registry.select { |_, info| info.fetch(:category) == :validator }
+                      .transform_values { |info| info.fetch(:processor_class) }
+            end
+
+            # Get all modifiers
+            #
+            # @return [Hash] Hash of option_name => processor_class for modifiers
+            def modifiers
+              registry.select { |_, info| info.fetch(:category) == :modifier }
+                      .transform_values { |info| info.fetch(:processor_class) }
+            end
+
+            # Get all conditionals
+            #
+            # @return [Hash] Hash of option_name => processor_class for conditionals
+            def conditionals
+              registry.select { |_, info| info.fetch(:category) == :conditional }
+                      .transform_values { |info| info.fetch(:processor_class) }
+            end
+
+            # Reset registry (mainly for testing)
+            def reset!
+              @registry = nil
+            end
+
+            private
+
+            def registry
+              @registry ||= {}
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/option/registry_initializer.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        # Initializes and registers all built-in option processors with the Registry.
+        #
+        # ## Purpose
+        #
+        # Centralized registration point for all option processors (validators, modifiers, and conditionals).
+        # Automatically registers all built-in options when loaded.
+        #
+        # ## Responsibilities
+        #
+        # 1. **Validator Registration** - Registers all built-in validators
+        # 2. **Modifier Registration** - Registers all built-in modifiers
+        # 3. **Conditional Registration** - Registers all built-in conditionals
+        # 4. **Auto-Loading** - Executes automatically when file is loaded
+        #
+        # ## Built-in Validators (sorted by position)
+        #
+        # - `:type` → TypeValidator (position: 100) - Validates value types
+        # - `:required` → RequiredValidator (position: 200) - Validates required/optional attributes
+        # - `:inclusion` → InclusionValidator (position: 300) - Validates value is in allowed set
+        # - `:format` → FormatValidator (position: 400) - Validates string values match specific formats
+        #
+        # ## Built-in Modifiers (sorted by position)
+        #
+        # - `:transform` → TransformModifier (position: 500) - Transforms values using custom lambdas
+        # - `:cast` → CastModifier (position: 600) - Converts values between types automatically
+        # - `:computed` → ComputedModifier (position: 700) - Computes values from all raw data
+        # - `:default` → DefaultModifier (position: 800) - Provides default values
+        # - `:as` → AsModifier (position: 900) - Renames attributes
+        #
+        # ## Built-in Conditionals (no position - handled separately)
+        #
+        # - `:if` → IfConditional - Conditionally includes attributes based on runtime data
+        # - `:unless` → UnlessConditional - Conditionally excludes attributes based on runtime data
+        #
+        # ## Auto-Registration
+        #
+        # This file calls `register_all!` when loaded, ensuring all processors
+        # are available immediately.
+        #
+        # ## Adding New Options
+        #
+        # To add a new option processor:
+        #
+        # 1. Create the processor class (inherit from Option::Base)
+        # 2. Add registration call here:
+        # ```ruby
+        # def register_validators!
+        #   Registry.register(:required, Validators::RequiredValidator, category: :validator)
+        #   Registry.register(:my_option, Validators::MyValidator, category: :validator)
+        # end
+        # ```
+        #
+        # ## Architecture
+        #
+        # Works with:
+        # - Registry - Stores processor registrations
+        # - Option::Base - Base class for all processors
+        # - OptionOrchestrator - Uses registered processors
+        module RegistryInitializer
+          class << self
+            # Registers all built-in option processors
+            # Called automatically when this file is loaded
+            #
+            # @return [void]
+            def register_all!
+              register_validators!
+              register_modifiers!
+              register_conditionals!
+            end
+
+            private
+
+            # Registers all built-in validators
+            # Position determines execution order (lower = earlier)
+            #
+            # @return [void]
+            def register_validators!
+              Registry.register(:type, Validators::TypeValidator, category: :validator, position: 100)
+              Registry.register(:required, Validators::RequiredValidator, category: :validator, position: 200)
+              Registry.register(:inclusion, Validators::InclusionValidator, category: :validator, position: 300)
+              Registry.register(:format, Validators::FormatValidator, category: :validator, position: 400)
+            end
+
+            # Registers all built-in modifiers
+            # Position determines execution order (lower = earlier)
+            #
+            # @return [void]
+            def register_modifiers!
+              Registry.register(:transform, Modifiers::TransformModifier, category: :modifier, position: 500)
+              Registry.register(:cast, Modifiers::CastModifier, category: :modifier, position: 600)
+              Registry.register(:computed, Modifiers::ComputedModifier, category: :modifier, position: 700)
+              Registry.register(:default, Modifiers::DefaultModifier, category: :modifier, position: 800)
+              Registry.register(:as, Modifiers::AsModifier, category: :modifier, position: 900)
+            end
+
+            # Registers all built-in conditionals
+            #
+            # @return [void]
+            def register_conditionals!
+              Registry.register(:if, Conditionals::IfConditional, category: :conditional)
+              Registry.register(:unless, Conditionals::UnlessConditional, category: :conditional)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+# Auto-register all options when this file is loaded
+Treaty::Entity::Attribute::Option::RegistryInitializer.register_all!

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