treaty 0.0.1 → 0.1.0

data/lib/treaty/attribute/option/modifiers/as_modifier.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Modifiers
+        # Transforms attribute names during data processing.
+        #
+        # ## Usage Examples
+        #
+        # Simple mode:
+        #   # Request: expects "handle", outputs as "value"
+        #   string :handle, as: :value
+        #
+        # Advanced mode:
+        #   string :handle, as: { is: :value, message: nil }
+        #
+        # ## Use Cases
+        #
+        # 1. **Request to Service mapping**:
+        #    ```ruby
+        #    request do
+        #      string :user_id, as: :id
+        #    end
+        #    # Input: { user_id: "123" }
+        #    # Service receives: { id: "123" }
+        #    ```
+        #
+        # 2. **Service to Response mapping**:
+        #    ```ruby
+        #    response 200 do
+        #      string :id, as: :user_id
+        #    end
+        #    # Service returns: { id: "123" }
+        #    # Output: { user_id: "123" }
+        #    ```
+        #
+        # ## How It Works
+        #
+        # AsModifier doesn't transform values - it transforms attribute names.
+        # The orchestrator uses `target_name` to map source name to target name.
+        #
+        # ## Advanced Mode
+        #
+        # Schema format: `{ is: :symbol, message: nil }`
+        class AsModifier < Treaty::Attribute::Option::Base
+          # Validates that target name is a Symbol
+          #
+          # @raise [Treaty::Exceptions::Validation] If target is not a Symbol
+          # @return [void]
+          def validate_schema!
+            target = option_value
+
+            return if target.is_a?(Symbol)
+
+            # TODO: It is necessary to implement a translation system (I18n).
+            raise Treaty::Exceptions::Validation,
+                  "Option 'as' for attribute '#{@attribute_name}' must be a Symbol. Got: #{target.class}"
+          end
+
+          # Indicates that AsModifier transforms attribute names
+          #
+          # @return [Boolean] Always returns true
+          def transforms_name?
+            true
+          end
+
+          # Returns the target name for the attribute
+          #
+          # @return [Symbol] The target attribute name
+          def target_name
+            option_value
+          end
+
+          # AsModifier doesn't modify the value itself, only the name
+          # The renaming is handled by the orchestrator using target_name
+          #
+          # @param value [Object] The value to transform
+          # @return [Object] Unchanged value
+          def transform_value(value)
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/option/modifiers/default_modifier.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Modifiers
+        # Sets default values for attributes when value is nil.
+        #
+        # ## Usage Examples
+        #
+        # Simple mode with static value:
+        #   integer :limit, default: 12
+        #   string :status, default: "pending"
+        #   boolean :active, default: false
+        #
+        # Simple mode with dynamic value (Proc):
+        #   datetime :created_at, default: -> { Time.current }
+        #   string :uuid, default: -> { SecureRandom.uuid }
+        #
+        # Advanced mode:
+        #   integer :limit, default: { is: 12, message: nil }
+        #
+        # ## Use Cases
+        #
+        # 1. **Response defaults** (most common):
+        #    ```ruby
+        #    response 200 do
+        #      scope :meta do
+        #        integer :limit, default: 12
+        #        integer :page, default: 1
+        #      end
+        #    end
+        #    # Service returns: { meta: { page: 1 } }
+        #    # Output: { meta: { page: 1, limit: 12 } }
+        #    ```
+        #
+        # 2. **Request defaults**:
+        #    ```ruby
+        #    request do
+        #      string :format, default: "json"
+        #    end
+        #    # Input: {}
+        #    # Service receives: { format: "json" }
+        #    ```
+        #
+        # ## Important Notes
+        #
+        # - Default is applied ONLY when value is nil
+        # - Empty strings, empty arrays, false are NOT replaced
+        # - Proc defaults are called at transformation time
+        # - Procs receive no arguments
+        #
+        # ## Array and Object Types
+        #
+        # NOTE: DO NOT use `default: []` or `default: {}` for array/object types!
+        # Array and object types automatically represent empty collections.
+        #
+        # Incorrect:
+        #   array :tags, default: []      # Wrong! Redundant
+        #   object :meta, default: {}     # Wrong! Redundant
+        #
+        # Correct:
+        #   array :tags                   # Automatically handles empty array
+        #   object :meta                  # Automatically handles empty object
+        #
+        # ## Advanced Mode
+        #
+        # Schema format: `{ is: value_or_proc, message: nil }`
+        class DefaultModifier < Treaty::Attribute::Option::Base
+          # Validates schema (no validation needed)
+          # Default value can be any type
+          #
+          # @return [void]
+          def validate_schema!
+            # Schema structure is already normalized by OptionNormalizer.
+            # Default value can be any type, so nothing specific to validate here.
+          end
+
+          # Applies default value if current value is nil
+          # Empty strings, empty arrays, and false are NOT replaced
+          #
+          # @param value [Object] The current value
+          # @param _context [Hash] Unused context parameter
+          # @return [Object] Default value if original is nil, otherwise original value
+          def transform_value(value, _context = {})
+            # Only apply default if value is nil
+            # Empty strings, empty arrays, false are NOT replaced
+            return value unless value.nil?
+
+            default_value = option_value
+
+            # If default value is a Proc, call it to get the value
+            if default_value.is_a?(Proc)
+              default_value.call
+            else
+              default_value
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      # Central registry for all option processors (validators and modifiers).
+      #
+      # ## 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)
+      # 4. **Validation** - Checks if options are registered
+      #
+      # ## Registered Options
+      #
+      # ### Validators
+      # - `:required` → RequiredValidator
+      # - `:type` → TypeValidator
+      # - `:inclusion` → InclusionValidator
+      #
+      # ### Modifiers
+      # - `:as` → AsModifier
+      # - `:default` → DefaultModifier
+      #
+      # ## Usage
+      #
+      # Registration (done in RegistryInitializer):
+      #   Registry.register(:required, RequiredValidator, category: :validator)
+      #
+      # 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 or :modifier)
+          def register(option_name, processor_class, category:)
+            registry[option_name] = {
+              processor_class:,
+              category:
+            }
+          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
+
+          # 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[:category] == :validator }
+                    .transform_values { |info| info[:processor_class] }
+          end
+
+          # Get all modifiers
+          #
+          # @return [Hash] Hash of option_name => processor_class for modifiers
+          def modifiers
+            registry.select { |_, info| info[:category] == :modifier }
+                    .transform_values { |info| info[:processor_class] }
+          end
+
+          # Reset registry (mainly for testing)
+          def reset!
+            @registry = nil
+          end
+
+          private
+
+          def registry
+            @registry ||= {}
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      # Initializes and registers all built-in option processors with the Registry.
+      #
+      # ## Purpose
+      #
+      # Centralized registration point for all option processors (validators and modifiers).
+      # 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. **Auto-Loading** - Executes automatically when file is loaded
+      #
+      # ## Built-in Validators
+      #
+      # - `:required` → RequiredValidator - Validates required/optional attributes
+      # - `:type` → TypeValidator - Validates value types
+      # - `:inclusion` → InclusionValidator - Validates value is in allowed set
+      #
+      # ## Built-in Modifiers
+      #
+      # - `:as` → AsModifier - Renames attributes
+      # - `:default` → DefaultModifier - Provides default values
+      #
+      # ## 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!
+          end
+
+          private
+
+          # Registers all built-in validators
+          #
+          # @return [void]
+          def register_validators!
+            Registry.register(:required, Validators::RequiredValidator, category: :validator)
+            Registry.register(:type, Validators::TypeValidator, category: :validator)
+            Registry.register(:inclusion, Validators::InclusionValidator, category: :validator)
+          end
+
+          # Registers all built-in modifiers
+          #
+          # @return [void]
+          def register_modifiers!
+            Registry.register(:as, Modifiers::AsModifier, category: :modifier)
+            Registry.register(:default, Modifiers::DefaultModifier, category: :modifier)
+          end
+        end
+      end
+    end
+  end
+end
+
+# Auto-register all options when this file is loaded
+Treaty::Attribute::Option::RegistryInitializer.register_all!

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?
+
+            # TODO: It is necessary to implement a translation system (I18n).
+            raise Treaty::Exceptions::Validation,
+                  "Option 'inclusion' for attribute '#{@attribute_name}' must have a non-empty array of allowed values"
+          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)
+
+            # TODO: It is necessary to implement a translation system (I18n).
+            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
+          #
+          # @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)
+            # TODO: It is necessary to implement a translation system (I18n).
+            "Attribute '#{@attribute_name}' must be one of: #{allowed_values.join(', ')}. Got: '#{value}'"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# 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
+
+            # TODO: It is necessary to implement a translation system (I18n).
+            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
+          #
+          # @return [String] Default error message
+          def default_message
+            # TODO: It is necessary to implement a translation system (I18n).
+            "Attribute '#{@attribute_name}' is required but was not provided or is empty"
+          end
+        end
+      end
+    end
+  end
+end