treaty 0.0.1 → 0.2.0

data/lib/treaty/attribute/helper_mapper.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    # Maps DSL helper symbols to their simple mode option equivalents.
+    #
+    # ## Purpose
+    #
+    # Helpers provide the most concise syntax for common options.
+    # They are syntactic sugar that gets converted to simple mode options.
+    #
+    # ## Available Helpers
+    #
+    # - `:required` → `required: true`
+    # - `:optional` → `required: false`
+    #
+    # ## Usage Examples
+    #
+    # Helper mode (most concise):
+    #   string :title, :required
+    #   string :bio, :optional
+    #
+    # Equivalent to simple mode:
+    #   string :title, required: true
+    #   string :bio, required: false
+    #
+    # ## Processing Flow
+    #
+    # 1. Helper mode: `string :title, :required`
+    # 2. HelperMapper: `:required` → `required: true`
+    # 3. OptionNormalizer: `required: true` → `{ is: true, message: nil }`
+    # 4. Final: Advanced mode used internally
+    #
+    # ## Adding New Helpers
+    #
+    # To add a new helper:
+    # ```ruby
+    # HELPER_MAPPINGS = {
+    #   required: { required: true },
+    #   optional: { required: false },
+    #   my_helper: { my_option: :smth }  # New helper example
+    # }.freeze
+    # ```
+    class HelperMapper
+      HELPER_MAPPINGS = {
+        required: { required: true },
+        optional: { required: false }
+      }.freeze
+
+      class << self
+        # Maps helper symbols to their simple mode equivalents
+        #
+        # @param helpers [Array<Symbol>] Array of helper symbols
+        # @return [Hash] Simple mode options hash
+        def map(helpers)
+          helpers.each_with_object({}) do |helper, result|
+            mapping = HELPER_MAPPINGS.fetch(helper)
+            result.merge!(mapping) if mapping.present?
+          end
+        end
+
+        # Checks if a symbol is a registered helper
+        #
+        # @param symbol [Symbol] Symbol to check
+        # @return [Boolean] True if symbol is a helper
+        def helper?(symbol)
+          HELPER_MAPPINGS.key?(symbol)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      # Base class for all option processors (validators and modifiers).
+      #
+      # ## Option Modes
+      #
+      # Treaty supports two modes for defining options:
+      #
+      # 1. **Simple Mode** - Concise syntax for common cases:
+      #    - `required: true`
+      #    - `as: :value`
+      #    - `default: 12`
+      #    - `in: %w[twitter linkedin]`
+      #
+      # 2. **Advanced Mode** - Extended syntax with custom messages:
+      #    - `required: { is: true, message: "Custom error" }`
+      #    - `as: { is: :value, message: nil }`
+      #    - `inclusion: { in: %w[...], message: "Must be one of..." }`
+      #
+      # ## Helpers
+      #
+      # Helpers are shortcuts in DSL that map to simple mode options:
+      # - `:required` → `required: true`
+      # - `:optional` → `required: false`
+      #
+      # ## Advanced Mode Keys
+      #
+      # Each option in advanced mode has a value key:
+      # - Default key: `:is` (used by most options)
+      # - Special key: `:in` (used by inclusion validator)
+      #
+      # The value key is defined by overriding `value_key` method in subclasses.
+      #
+      # ## Processing Phases
+      #
+      # Each option processor can participate in three phases:
+      # - Phase 1: Schema validation (validate DSL definition correctness)
+      # - Phase 2: Value validation (validate runtime data values)
+      # - Phase 3: Value transformation (transform values: defaults, renaming, etc.)
+      class Base
+        # Creates a new option processor instance
+        #
+        # @param attribute_name [Symbol] The name of the attribute
+        # @param attribute_type [Symbol] The type of the attribute
+        # @param option_schema [Object] The option schema (simple or advanced mode)
+        def initialize(attribute_name:, attribute_type:, option_schema:)
+          @attribute_name = attribute_name
+          @attribute_type = attribute_type
+          @option_schema = option_schema
+        end
+
+        # Phase 1: Validates schema (DSL definition)
+        # Override in subclasses if validation is needed
+        #
+        # @raise [Treaty::Exceptions::Validation] If schema is invalid
+        # @return [void]
+        def validate_schema!
+          # No-op by default
+        end
+
+        # Phase 2: Validates value (runtime data)
+        # Override in subclasses if validation is needed
+        #
+        # @param value [Object] The value to validate
+        # @raise [Treaty::Exceptions::Validation] If value is invalid
+        # @return [void]
+        def validate_value!(value)
+          # No-op by default
+        end
+
+        # Phase 3: Transforms value
+        # Returns transformed value or original if no transformation needed
+        # Override in subclasses if transformation is needed
+        #
+        # @param value [Object] The value to transform
+        # @return [Object] Transformed value
+        def transform_value(value)
+          value
+        end
+
+        # Indicates if this option processor transforms attribute names
+        # Override in subclasses if needed (e.g., AsModifier)
+        #
+        # @return [Boolean] True if this processor transforms names
+        def transforms_name?
+          false
+        end
+
+        # Returns the target name for the attribute if this processor transforms names
+        # Override in subclasses if needed (e.g., AsModifier)
+        #
+        # @return [Symbol] The target attribute name
+        def target_name
+          @attribute_name
+        end
+
+        protected
+
+        # Returns the value key for this option in advanced mode
+        # Default is :is, but can be overridden (e.g., :in for inclusion)
+        #
+        # @return [Symbol] The key used to store the value in advanced mode
+        def value_key
+          :is
+        end
+
+        # Checks if option is enabled
+        # Handles both simple mode (boolean) and advanced mode (hash with value key)
+        #
+        # @return [Boolean] Whether the option is enabled
+        def option_enabled?
+          return false if @option_schema.nil?
+          return @option_schema if @option_schema.is_a?(TrueClass) || @option_schema.is_a?(FalseClass)
+
+          @option_schema.fetch(value_key, false)
+        end
+
+        # Extracts the actual value from normalized schema
+        # Works with both simple mode and advanced mode
+        #
+        # In simple mode: returns the value directly
+        # In advanced mode: extracts value using the appropriate key (is/in)
+        #
+        # @return [Object] The actual value from the option schema
+        def option_value
+          return @option_schema unless @option_schema.is_a?(Hash)
+
+          @option_schema.fetch(value_key, nil)
+        end
+
+        # Gets custom error message from advanced mode schema
+        # Returns nil if no custom message, which triggers I18n default message
+        #
+        # @return [String, nil] Custom error message or nil for default message
+        def custom_message
+          return nil unless @option_schema.is_a?(Hash)
+
+          @option_schema.fetch(:message, nil)
+        end
+
+        # Checks if schema is in advanced mode
+        #
+        # @return [Boolean] True if schema is in advanced mode (hash with value key)
+        def advanced_mode?
+          @option_schema.is_a?(Hash) && @option_schema.key?(value_key)
+        end
+
+        # Checks if schema is in simple mode
+        #
+        # @return [Boolean] True if schema is in simple mode (not a hash or no value key)
+        def simple_mode?
+          !advanced_mode?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# 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)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.modifiers.as.invalid_type",
+                         attribute: @attribute_name,
+                         type: 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!