treaty 0.18.0 → 0.20.0

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

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    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
+          # @param _root_data [Hash] Full raw data from root level (used by computed modifier)
+          # @return [Object] Transformed value
+          def transform_value(value, _root_data = {})
+            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, Proc, nil] Custom error message, lambda, or nil for default message
+          def custom_message
+            return nil unless @option_schema.is_a?(Hash)
+
+            @option_schema.fetch(:message, nil)
+          end
+
+          # Resolves custom message with lambda support
+          # If message is a lambda, calls it with provided named arguments
+          # Catches all exceptions from lambda execution and re-raises as Validation errors
+          #
+          # @param attributes [Hash] Named arguments to pass to lambda
+          # @return [String, nil] Resolved message string or nil
+          # @raise [Treaty::Exceptions::Validation] If custom message lambda raises an exception
+          def resolve_custom_message(**attributes) # rubocop:disable Metrics/MethodLength
+            message = custom_message
+            return nil if message.nil?
+
+            if message.respond_to?(:call)
+              message.call(**attributes)
+            else
+              message
+            end
+          rescue StandardError => e
+            # Catch all exceptions from custom message lambda execution
+            error_message = I18n.t(
+              "treaty.attributes.options.message_evaluation_error",
+              attribute: @attribute_name,
+              error: e.message
+            )
+
+            raise Treaty::Exceptions::Validation, error_message
+          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
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        module Conditionals
+          # Base class for conditional option processors.
+          #
+          # ## Purpose
+          #
+          # Conditionals control whether an attribute should be processed at all.
+          # Unlike validators (which check data) and modifiers (which transform data),
+          # conditionals determine attribute visibility based on runtime conditions.
+          #
+          # ## Key Difference from Validators/Modifiers
+          #
+          # - **Validators**: Check if data is valid
+          # - **Modifiers**: Transform data values
+          # - **Conditionals**: Decide if attribute exists in output
+          #
+          # ## Processing
+          #
+          # Conditionals are evaluated BEFORE validators and modifiers:
+          # 1. If condition evaluates to `false` → attribute is skipped entirely
+          # 2. If condition evaluates to `true` → attribute is processed normally
+          #
+          # ## Mode Support
+          #
+          # Conditionals do NOT support simple/advanced modes.
+          # They only accept lambda/proc directly:
+          #
+          # ```ruby
+          # # Correct
+          # integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          # array :tags, if: ->(post:) { post[:published_at].present? }
+          #
+          # # Incorrect - no simple/advanced mode
+          # integer :rating, if: true  # Not supported
+          # integer :rating, if: { is: ..., message: ... }  # Not supported
+          # ```
+          #
+          # ## Implementation
+          #
+          # Subclasses must implement:
+          # - `validate_schema!` - Validate the conditional schema at definition time
+          # - `evaluate_condition(data)` - Evaluate condition with runtime data
+          class Base < Treaty::Entity::Attribute::Option::Base
+            # Phase 1: Validates conditional schema
+            # Must be overridden in subclasses
+            #
+            # @raise [Treaty::Exceptions::Validation] If schema is invalid
+            # @return [void]
+            def validate_schema!
+              raise Treaty::Exceptions::NotImplemented,
+                    "#{self.class} must implement #validate_schema!"
+            end
+
+            # Evaluates the conditional with runtime data
+            # Must be overridden in subclasses
+            #
+            # @param _data [Hash] Raw data to evaluate condition against
+            # @raise [Treaty::Exceptions::Validation] If evaluation fails
+            # @return [Boolean] True if attribute should be processed, false otherwise
+            def evaluate_condition(_data)
+              raise Treaty::Exceptions::NotImplemented,
+                    "#{self.class} must implement #evaluate_condition"
+            end
+
+            # Conditionals do not validate values
+            # This is a no-op for conditionals
+            #
+            # @param _value [Object] The value (unused)
+            # @return [void]
+            def validate_value!(_value)
+              # No-op: conditionals don't validate values
+            end
+
+            # Conditionals do not transform values
+            # This is a no-op for conditionals
+            #
+            # @param value [Object] The value to pass through
+            # @return [Object] The unchanged value
+            def transform_value(value)
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/option/conditionals/if_conditional.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        module Conditionals
+          # Conditionally includes attributes based on runtime data evaluation.
+          #
+          # ## Usage Examples
+          #
+          # Basic usage with keyword arguments splat:
+          #   array :tags, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #   integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #
+          # Named argument pattern:
+          #   array :tags, if: ->(post:) { post[:published_at].present? }
+          #   integer :views, if: ->(post:) { post[:published_at].present? }
+          #
+          # Complex conditions:
+          #   string :admin_note, if: (lambda do |**attributes|
+          #     attributes.dig(:user, :role) == "admin" && attributes.dig(:post, :flagged)
+          #   end)
+          #
+          # ## Use Cases
+          #
+          # 1. **Show fields only when published**:
+          #    ```ruby
+          #    response 200 do
+          #      object :post do
+          #        string :id
+          #        string :title
+          #        datetime :published_at, :optional
+          #        integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #      end
+          #    end
+          #    # If published_at is nil → rating is excluded from response
+          #    # If published_at exists → rating is included
+          #    ```
+          #
+          # 2. **Role-based field visibility**:
+          #    ```ruby
+          #    response 200 do
+          #      object :user do
+          #        string :name
+          #        string :email, if: ->(user:) { user[:role] == "admin" }
+          #      end
+          #    end
+          #    ```
+          #
+          # 3. **Nested attribute conditionals**:
+          #    ```ruby
+          #    object :post do
+          #      string :title
+          #      array :tags, if: ->(post:) { post[:published_at].present? } do
+          #        string :_self
+          #      end
+          #    end
+          #    ```
+          #
+          # ## Important Notes
+          #
+          # - Lambda receives raw data as named arguments
+          # - Lambda MUST return truthy/falsy value
+          # - If condition is false → attribute is completely omitted
+          # - If condition is true → attribute is validated and transformed normally
+          # - All exceptions in lambda are caught and wrapped in Treaty::Exceptions::Validation
+          # - Does NOT support simple mode (if: true) or advanced mode (if: { is: ..., message: ... })
+          #
+          # ## Error Handling
+          #
+          # If the lambda raises any exception, it's caught and converted to a
+          # Treaty::Exceptions::Validation with detailed error message including:
+          # - Attribute name
+          # - Original exception message
+          #
+          # ## Data Access Pattern
+          #
+          # The lambda receives the same data structure that the orchestrator processes.
+          # For nested attributes, you can access parent data using dig:
+          #
+          # ```ruby
+          # # For response with { post: { title: "...", published_at: "..." } }
+          # integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #
+          # # Alternative: named argument pattern
+          # integer :rating, if: ->(post:) { post[:published_at].present? }
+          # ```
+          class IfConditional < Treaty::Entity::Attribute::Option::Conditionals::Base
+            # Validates that if option is a callable (Proc/Lambda)
+            #
+            # @raise [Treaty::Exceptions::Validation] If if is not a Proc/lambda
+            # @return [void]
+            def validate_schema!
+              conditional_lambda = @option_schema
+
+              return if conditional_lambda.respond_to?(:call)
+
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.if.invalid_type",
+                      attribute: @attribute_name,
+                      type: conditional_lambda.class
+                    )
+            end
+
+            # Evaluates the conditional lambda with runtime data
+            # Returns boolean indicating if attribute should be processed
+            #
+            # @param data [Hash] Raw data from request/response/entity
+            # @raise [Treaty::Exceptions::Validation] If lambda execution fails
+            # @return [Boolean] True if attribute should be processed, false to skip it
+            def evaluate_condition(data)
+              conditional_lambda = @option_schema
+
+              # Call lambda with raw data as named arguments
+              # The lambda can use **attributes or specific named args like post:
+              result = conditional_lambda.call(**data)
+
+              # Convert result to boolean
+              !!result
+            rescue StandardError => e
+              # Catch all exceptions from lambda execution
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.if.evaluation_error",
+                      attribute: @attribute_name,
+                      error: e.message
+                    )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/option/conditionals/unless_conditional.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        module Conditionals
+          # Conditionally excludes attributes based on runtime data evaluation.
+          #
+          # ## Usage Examples
+          #
+          # Basic usage with keyword arguments splat:
+          #   array :tags, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #   integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #
+          # Named argument pattern:
+          #   array :draft_notes, unless: ->(post:) { post[:published_at].present? }
+          #   integer :edit_count, unless: ->(post:) { post[:published_at].present? }
+          #
+          # Complex conditions:
+          #   string :internal_note, unless: (lambda do |**attributes|
+          #     attributes.dig(:user, :role) == "admin" && attributes.dig(:post, :flagged)
+          #   end)
+          #
+          # ## Use Cases
+          #
+          # 1. **Hide fields when published**:
+          #    ```ruby
+          #    response 200 do
+          #      object :post do
+          #        string :id
+          #        string :title
+          #        datetime :published_at, :optional
+          #        integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #      end
+          #    end
+          #    # If published_at is nil → draft_views is included in response
+          #    # If published_at exists → draft_views is excluded
+          #    ```
+          #
+          # 2. **Role-based field exclusion**:
+          #    ```ruby
+          #    response 200 do
+          #      object :user do
+          #        string :name
+          #        string :internal_id, unless: ->(user:) { user[:role] == "public" }
+          #      end
+          #    end
+          #    ```
+          #
+          # 3. **Nested attribute conditionals**:
+          #    ```ruby
+          #    object :post do
+          #      string :title
+          #      array :draft_notes, unless: ->(post:) { post[:published_at].present? } do
+          #        string :_self
+          #      end
+          #    end
+          #    ```
+          #
+          # ## Important Notes
+          #
+          # - Lambda receives raw data as named arguments
+          # - Lambda MUST return truthy/falsy value
+          # - If condition is true → attribute is completely omitted (OPPOSITE of `if`)
+          # - If condition is false → attribute is validated and transformed normally
+          # - All exceptions in lambda are caught and wrapped in Treaty::Exceptions::Validation
+          # - Does NOT support simple mode (unless: true) or advanced mode (unless: { is: ..., message: ... })
+          #
+          # ## Difference from `if` Option
+          #
+          # `unless` is the logical opposite of `if`:
+          # - `if` includes attribute when condition is TRUE
+          # - `unless` includes attribute when condition is FALSE
+          #
+          # ```ruby
+          # # These are equivalent:
+          # integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          # integer :rating, unless: ->(**attributes) { attributes.dig(:post, :published_at).blank? }
+          #
+          # # These are also equivalent:
+          # integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          # integer :draft_views, if: ->(**attributes) { attributes.dig(:post, :published_at).blank? }
+          # ```
+          #
+          # ## Error Handling
+          #
+          # If the lambda raises any exception, it's caught and converted to a
+          # Treaty::Exceptions::Validation with detailed error message including:
+          # - Attribute name
+          # - Original exception message
+          #
+          # ## Data Access Pattern
+          #
+          # The lambda receives the same data structure that the orchestrator processes.
+          # For nested attributes, you can access parent data using dig:
+          #
+          # ```ruby
+          # # For response with { post: { title: "...", published_at: "..." } }
+          # integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #
+          # # Alternative: named argument pattern
+          # integer :draft_views, unless: ->(post:) { post[:published_at].present? }
+          # ```
+          class UnlessConditional < Treaty::Entity::Attribute::Option::Conditionals::Base
+            # Validates that unless option is a callable (Proc/Lambda)
+            #
+            # @raise [Treaty::Exceptions::Validation] If unless is not a Proc/lambda
+            # @return [void]
+            def validate_schema!
+              conditional_lambda = @option_schema
+
+              return if conditional_lambda.respond_to?(:call)
+
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.unless.invalid_type",
+                      attribute: @attribute_name,
+                      type: conditional_lambda.class
+                    )
+            end
+
+            # Evaluates the conditional lambda with runtime data
+            # Returns boolean indicating if attribute should be processed
+            #
+            # @param data [Hash] Raw data from request/response/entity
+            # @raise [Treaty::Exceptions::Validation] If lambda execution fails
+            # @return [Boolean] True if attribute should be processed (when condition is FALSE), false to skip it
+            def evaluate_condition(data)
+              conditional_lambda = @option_schema
+
+              # Call lambda with raw data as named arguments
+              # The lambda can use **attributes or specific named args like post:
+              result = conditional_lambda.call(**data)
+
+              # Convert result to boolean and NEGATE it (opposite of if)
+              # unless includes attribute when condition is FALSE
+              !result
+            rescue StandardError => e
+              # Catch all exceptions from lambda execution
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.unless.evaluation_error",
+                      attribute: @attribute_name,
+                      error: e.message
+                    )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    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::Entity::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
+            # @param _root_data [Hash] Unused root data parameter
+            # @return [Object] Unchanged value
+            def transform_value(value, _root_data = {})
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end