treaty 0.18.0 → 0.19.0

data/lib/treaty/attribute/helper_mapper.rb

@@ -1,72 +0,0 @@
-# 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

@@ -1,188 +0,0 @@
-# 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
-        # @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

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

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  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::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

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

@@ -1,134 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  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::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

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

@@ -1,151 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  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::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