treaty 0.18.0 → 0.19.0

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    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
+          #      object :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::Entity::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 _root_data [Hash] Unused root data parameter
+            # @return [Object] Default value if original is nil, otherwise original value
+            def transform_value(value, _root_data = {})
+              # 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
+end

data/lib/treaty/entity/attribute/option/modifiers/transform_modifier.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        module Modifiers
+          # Transforms attribute values using custom lambda functions.
+          #
+          # ## Usage Examples
+          #
+          # Simple mode:
+          #   integer :amount, transform: ->(value:) { value * 100 }
+          #   string :title, transform: ->(value:) { value.strip.upcase }
+          #
+          # Advanced mode with custom error message:
+          #   integer :amount, transform: {
+          #     is: ->(value:) { value * 100 },
+          #     message: "Failed to transform amount"
+          #   }
+          #
+          # ## Use Cases
+          #
+          # 1. **Request transformation**:
+          #    ```ruby
+          #    request do
+          #      integer :amount_cents, transform: ->(value:) { value * 100 }
+          #    end
+          #    # Input: { amount_cents: 10 }
+          #    # Service receives: { amount_cents: 1000 }
+          #    ```
+          #
+          # 2. **Response transformation**:
+          #    ```ruby
+          #    response 200 do
+          #      string :title, transform: ->(value:) { value.titleize }
+          #    end
+          #    # Service returns: { title: "hello world" }
+          #    # Output: { title: "Hello World" }
+          #    ```
+          #
+          # 3. **Complex transformations**:
+          #    ```ruby
+          #    string :email, transform: ->(value:) { value.downcase.strip }
+          #    datetime :timestamp, transform: ->(value:) { value.iso8601 }
+          #    ```
+          #
+          # ## Important Notes
+          #
+          # - Lambda must accept named argument `value:`
+          # - All exceptions raised in lambda are caught and re-raised as Validation errors
+          # - Transformation is applied during Phase 3 (after validation)
+          # - Can be combined with other options (required, default, as, etc.)
+          #
+          # ## Error Handling
+          #
+          # If the lambda raises any exception, it's caught and converted to a
+          # Treaty::Exceptions::Validation with appropriate error message.
+          #
+          # ## Advanced Mode
+          #
+          # Schema format: `{ is: lambda, message: nil }`
+          class TransformModifier < Treaty::Entity::Attribute::Option::Base
+            # Validates that transform value is a lambda
+            #
+            # @raise [Treaty::Exceptions::Validation] If transform is not a Proc/lambda
+            # @return [void]
+            def validate_schema!
+              transform_lambda = option_value
+
+              return if transform_lambda.respond_to?(:call)
+
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.modifiers.transform.invalid_type",
+                      attribute: @attribute_name,
+                      type: transform_lambda.class
+                    )
+            end
+
+            # Applies transformation to the value using the provided lambda
+            # Catches all exceptions and re-raises as Validation errors
+            # Skips transformation for nil values (handled by RequiredValidator)
+            #
+            # @param value [Object] The current value
+            # @param _root_data [Hash] Unused root data parameter
+            # @return [Object] Transformed value
+            def transform_value(value, _root_data = {}) # rubocop:disable Metrics/MethodLength
+              return value if value.nil? # Transform doesn't modify nil, required validator handles it.
+
+              transform_lambda = option_value
+
+              # Call lambda with named argument
+              transform_lambda.call(value:)
+            rescue StandardError => e
+              attributes = {
+                attribute: @attribute_name,
+                error: e.message
+              }
+
+              # Catch all exceptions from lambda execution
+              error_message = resolve_custom_message(**attributes) || I18n.t(
+                "treaty.attributes.modifiers.transform.execution_error",
+                **attributes
+              )
+
+              raise Treaty::Exceptions::Validation, error_message
+            end
+          end
+        end
+      end
+    end
+  end
+end

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!