treaty 0.18.0 → 0.20.0

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      # Base class for all attribute definitions in Treaty DSL.
+      #
+      # ## Purpose
+      #
+      # Represents a single attribute defined in request/response definitions.
+      # Handles:
+      # - Attribute metadata (name, type, nesting level)
+      # - Helper mode to simple mode conversion
+      # - Simple mode to advanced mode normalization
+      # - Nested attributes (for object and array types)
+      #
+      # ## Usage
+      #
+      # Attributes are created through DSL methods:
+      #   string :title, :required
+      #   integer :age, default: 18
+      #   object :author do
+      #     string :name
+      #   end
+      #
+      # ## Processing Flow
+      #
+      # 1. Extract helpers from arguments (`:required`, `:optional`)
+      # 2. Convert helpers to simple mode options
+      # 3. Merge with explicit options
+      # 4. Normalize all options to advanced mode
+      # 5. Apply defaults (required: true for request, false for response)
+      # 6. Process nested attributes if block given
+      #
+      # ## Nested Attributes
+      #
+      # Object and array types can have nested attributes:
+      # - `object` - nested attributes as direct children
+      # - `array` - nested attributes define array element structure
+      #
+      # Special attribute name `:_self` is used for simple arrays:
+      #   array :tags do
+      #     string :_self  # Array of strings
+      #   end
+      class Base
+        attr_reader :name,
+                    :type,
+                    :options,
+                    :nesting_level
+
+        # Creates a new attribute instance
+        #
+        # @param name [Symbol] The attribute name
+        # @param type [Symbol] The attribute type (:string, :integer, :object, :array, etc.)
+        # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
+        # @param nesting_level [Integer] Current nesting depth (default: 0)
+        # @param options [Hash] Attribute options (required, default, as, etc.)
+        # @param block [Proc] Block for defining nested attributes (for object/array types)
+        def initialize(name, type, *helpers, nesting_level: 0, **options, &block)
+          @name = name
+          @type = type
+          @nesting_level = nesting_level
+
+          validate_nesting_level!
+
+          # Separate helpers from non-helper symbols.
+          @helpers = extract_helpers(helpers)
+
+          # Merge helper options with explicit options.
+          merged_options = merge_options(@helpers, options)
+
+          # Normalize all options to advanced mode.
+          @options = OptionNormalizer.normalize(merged_options)
+
+          apply_defaults!
+
+          # Process nested attributes for object and array types.
+          process_nested_attributes(&block) if block_given?
+        end
+
+        # Returns collection of nested attributes for this attribute
+        #
+        # @return [Treaty::Entity::Attribute::Collection] Collection of nested attributes
+        def collection_of_attributes
+          @collection_of_attributes ||= Collection.new
+        end
+
+        # Checks if this attribute has nested attributes
+        #
+        # @return [Boolean] True if attribute is object/array with nested attributes
+        def nested?
+          object_or_array? && collection_of_attributes.exists?
+        end
+
+        # Checks if this attribute is an object or array type
+        #
+        # @return [Boolean] True if type is :object or :array
+        def object_or_array?
+          object? || array?
+        end
+
+        # Checks if this attribute is an object type
+        #
+        # @return [Boolean] True if type is :object
+        def object?
+          @type == :object
+        end
+
+        # Checks if this attribute is an array type
+        #
+        # @return [Boolean] True if type is :array
+        def array?
+          @type == :array
+        end
+
+        private
+
+        # Validates that nesting level doesn't exceed maximum allowed depth
+        #
+        # @raise [Treaty::Exceptions::NestedAttributes] If nesting exceeds limit
+        # @return [void]
+        def validate_nesting_level!
+          return unless @nesting_level > Treaty::Engine.config.treaty.attribute_nesting_level
+
+          raise Treaty::Exceptions::NestedAttributes,
+                I18n.t(
+                  "treaty.attributes.errors.nesting_level_exceeded",
+                  level: @nesting_level,
+                  max_level: Treaty::Engine.config.treaty.attribute_nesting_level
+                )
+        end
+
+        # Extracts helper symbols from arguments
+        #
+        # @param helpers [Array] Mixed array that may contain helper symbols
+        # @return [Array<Symbol>] Filtered array of valid helper symbols
+        def extract_helpers(helpers)
+          helpers.select do |helper|
+            helper.is_a?(Symbol) && HelperMapper.helper?(helper)
+          end
+        end
+
+        # Merges helper-derived options with explicit options
+        #
+        # @param helpers [Array<Symbol>] Helper symbols to convert
+        # @param explicit_options [Hash] Explicitly provided options
+        # @return [Hash] Merged options hash
+        def merge_options(helpers, explicit_options)
+          helper_options = HelperMapper.map(helpers)
+          helper_options.merge(explicit_options)
+        end
+
+        # Applies default values for options based on context (request/response)
+        # Must be implemented in subclasses
+        #
+        # @raise [Treaty::Exceptions::NotImplemented] If subclass doesn't implement
+        # @return [void]
+        def apply_defaults!
+          # Must be implemented in subclasses
+          raise Treaty::Exceptions::NotImplemented,
+                I18n.t(
+                  "treaty.attributes.errors.apply_defaults_not_implemented",
+                  class: self.class
+                )
+        end
+
+        # Processes nested attributes block for object/array types
+        # Must be implemented in subclasses
+        #
+        # @param block [Proc] Block containing nested attribute definitions
+        # @raise [Treaty::Exceptions::NotImplemented] If subclass doesn't implement
+        # @return [void]
+        def process_nested_attributes
+          # Must be implemented in subclasses
+          raise Treaty::Exceptions::NotImplemented,
+                I18n.t(
+                  "treaty.attributes.errors.process_nested_not_implemented",
+                  class: self.class
+                )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Builder
+        # Base DSL builder for defining attributes in request/response definitions.
+        #
+        # ## Purpose
+        #
+        # Provides the DSL interface for defining attributes within objects.
+        # Handles method_missing magic to support type-based method calls.
+        #
+        # ## Responsibilities
+        #
+        # 1. **DSL Interface** - Provides clean syntax for attribute definitions
+        # 2. **Method Dispatch** - Routes type methods (string, integer, etc.) to attribute creation
+        # 3. **Helper Support** - Handles helper symbols in various positions
+        # 4. **Nesting Tracking** - Tracks nesting level for nested attributes
+        # 5. **Entity Reuse** - Supports use_entity for copying attributes from Entity classes
+        #
+        # ## DSL Usage
+        #
+        # The builder enables this clean DSL syntax:
+        #
+        # ```ruby
+        # request do
+        #   object :user do
+        #     string :name
+        #     integer :age, default: 18
+        #     object :profile do
+        #       string :bio
+        #     end
+        #   end
+        # end
+        # ```
+        #
+        # ## Entity Reuse
+        #
+        # You can use `use_entity` to copy attributes from an Entity class:
+        #
+        # ```ruby
+        # object :author do
+        #   use_entity(AuthorEntity)
+        # end
+        # ```
+        #
+        # Note: `use_entity` must be the only statement in the block.
+        #
+        # ## Method Dispatch
+        #
+        # ### Type-based Methods
+        # When you call `string :name`, it routes through `method_missing`:
+        # 1. `string` becomes the type
+        # 2. `:name` becomes the attribute name
+        # 3. Calls `attribute(:name, :string, ...)`
+        #
+        # ### Helper Position Handling
+        # Handles helpers in different positions:
+        #
+        # ```ruby
+        # string :required, :name    # Helper first, then name
+        # string :name, :required    # Name first, then helper
+        # ```
+        #
+        # Both resolve to the same attribute definition.
+        #
+        # ## Nesting
+        #
+        # Tracks nesting level for:
+        # - Validation (enforcing maximum nesting depth)
+        # - Error messages (showing context)
+        #
+        # Maximum nesting level is configured in Treaty::Engine.config.
+        #
+        # ## Subclass Requirements
+        #
+        # Subclasses must implement:
+        # - `create_attribute` - Creates the appropriate attribute type (Request/Response)
+        # - `deep_copy_attribute` - Deep copies an attribute with adjusted nesting level
+        #
+        # ## Architecture
+        #
+        # Used by:
+        # - Request::Builder - For request attribute definitions
+        # - Response::Builder - For response attribute definitions
+        # - Entity::Builder - For entity attribute definitions
+        class Base
+          attr_reader :nesting_level,
+                      :collection_of_attributes
+
+          # Creates a new builder instance
+          #
+          # @param collection_of_attributes [Treaty::Entity::Attribute::Collection] Collection to add attributes to
+          # @param nesting_level [Integer] Current nesting depth
+          def initialize(collection_of_attributes, nesting_level)
+            @collection_of_attributes = collection_of_attributes
+            @nesting_level = nesting_level
+            @use_entity_called = false
+            @attributes_defined = false
+          end
+
+          # Uses an Entity class to copy its attributes into this builder's collection.
+          # Must be the ONLY statement in the block - no other attributes allowed.
+          #
+          # @param entity_class [Class] Entity class (must be Treaty::Entity::Base subclass)
+          # @raise [Treaty::Exceptions::Validation] if entity_class is invalid
+          # @raise [Treaty::Exceptions::Validation] if mixed with other attributes
+          # @return [void]
+          #
+          # @example Using an Entity in a nested object
+          #   object :author do
+          #     use_entity(AuthorEntity)
+          #   end
+          #
+          # @example Using an Entity in a nested array
+          #   array :items, :optional do
+          #     use_entity(ItemEntity)
+          #   end
+          def use_entity(entity_class)
+            validate_use_entity_preconditions!
+            validate_entity_class!(entity_class)
+
+            @use_entity_called = true
+
+            copy_attributes_from_entity(entity_class)
+          end
+
+          # Defines an attribute with explicit type
+          #
+          # @param name [Symbol] The attribute name
+          # @param type [Symbol] The attribute type
+          # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
+          # @param options [Hash] Attribute options
+          # @param block [Proc] Block for nested attributes
+          # @return [void]
+          def attribute(name, type, *helpers, **options, &block)
+            validate_no_use_entity_called!
+
+            @attributes_defined = true
+
+            @collection_of_attributes << create_attribute(
+              name,
+              type,
+              *helpers,
+              nesting_level: @nesting_level,
+              **options,
+              &block
+            )
+          end
+
+          # Handles DSL methods like `string :name` where method name is the type
+          #
+          # @param type [Symbol] The attribute type (method name)
+          # @param name [Symbol] The attribute name (first argument)
+          # @param helpers [Array<Symbol>] Helper symbols
+          # @param options [Hash] Attribute options
+          # @param block [Proc] Block for nested attributes
+          # @return [void]
+          def method_missing(type, name, *helpers, **options, &block)
+            if name.is_a?(Symbol) && HelperMapper.helper?(name)
+              helpers.unshift(name)
+              name = helpers.shift
+            end
+
+            attribute(name, type, *helpers, **options, &block)
+          end
+
+          # Checks if method should be handled by method_missing
+          #
+          # @param name [Symbol] Method name
+          # @return [Boolean]
+          def respond_to_missing?(name, *)
+            super
+          end
+
+          private
+
+          # Creates an attribute instance (must be implemented in subclasses)
+          #
+          # @raise [Treaty::Exceptions::NotImplemented] If subclass doesn't implement
+          # @return [Attribute::Base] Created attribute instance
+          def create_attribute(*)
+            raise Treaty::Exceptions::NotImplemented,
+                  I18n.t("treaty.attributes.builder.not_implemented", class: self.class)
+          end
+
+          # Validates that use_entity can be called (no attributes defined before)
+          #
+          # @raise [Treaty::Exceptions::Validation] if attributes were defined before use_entity
+          def validate_use_entity_preconditions!
+            return unless @attributes_defined
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.builder.use_entity_after_attributes")
+          end
+
+          # Validates that no use_entity was called before defining attributes
+          #
+          # @raise [Treaty::Exceptions::Validation] if use_entity was already called
+          def validate_no_use_entity_called!
+            return unless @use_entity_called
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.builder.attributes_after_use_entity")
+          end
+
+          # Validates that entity_class is a valid Treaty::Entity::Base subclass
+          #
+          # @param entity_class [Class] Entity class to validate
+          # @raise [Treaty::Exceptions::Validation] if entity_class is not valid
+          def validate_entity_class!(entity_class)
+            return if entity_class.is_a?(Class) && entity_class < Treaty::Entity::Base
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t(
+                    "treaty.attributes.builder.invalid_entity_class",
+                    type: entity_class.class,
+                    value: entity_class
+                  )
+          end
+
+          # Copies all attributes from entity_class to this builder's collection
+          # with adjusted nesting levels.
+          #
+          # @param entity_class [Class] Source entity class
+          def copy_attributes_from_entity(entity_class)
+            entity_class.collection_of_attributes.each do |source_attribute|
+              copied_attribute = deep_copy_attribute(source_attribute, @nesting_level)
+              @collection_of_attributes << copied_attribute
+            end
+          end
+
+          # Deep copies an attribute with adjusted nesting level.
+          # Must be implemented by subclasses to use proper attribute types.
+          #
+          # @param source_attribute [Attribute::Base] Attribute to copy
+          # @param new_nesting_level [Integer] New nesting level for copied attribute
+          # @return [Attribute::Base] Copied attribute with correct type
+          def deep_copy_attribute(_source_attribute, _new_nesting_level)
+            raise Treaty::Exceptions::NotImplemented,
+                  I18n.t(
+                    "treaty.attributes.builder.deep_copy_not_implemented",
+                    class: self.class
+                  )
+          end
+
+          # Deep copies options hash, preserving Proc references
+          # and recursively handling nested Hash/Array structures.
+          #
+          # @param options [Hash] Options to copy
+          # @return [Hash] Copied options
+          def deep_copy_options(options)
+            options.transform_values { |value| deep_copy_value(value) }
+          end
+
+          # Deep copies a single value, handling nested structures.
+          # Immutable types (Proc, Symbol, Numeric, nil, true, false) are returned as-is.
+          # Hash and Array are recursively copied. Strings are duplicated if not frozen.
+          #
+          # @param value [Object] Value to copy
+          # @return [Object] Copied value
+          def deep_copy_value(value)
+            case value
+            when Hash  then value.transform_values { |v| deep_copy_value(v) }
+            when Array then value.map { |v| deep_copy_value(v) }
+            when String then value.frozen? ? value : value.dup
+            else value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/collection.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Treaty
+  module Entity
+    module Attribute
+      # Collection wrapper for sets of attributes.
+      #
+      # ## Purpose
+      #
+      # Provides a unified interface for working with collections of attributes.
+      # Uses Ruby Set internally for uniqueness but exposes Array-like interface.
+      #
+      # ## Usage
+      #
+      # Used internally by:
+      # - Request/Response factories (to store attributes)
+      # - Attribute::Base (to store nested attributes)
+      #
+      # ## Methods
+      #
+      # Delegates common collection methods to internal Set:
+      # - `<<` - Add attribute
+      # - `each`, `map`, `select`, `reject` - Iteration
+      # - `find`, `first` - Access
+      # - `size`, `empty?` - Size checks
+      # - `to_h` - Convert to hash
+      #
+      # Custom methods:
+      # - `exists?` - Returns true if collection is not empty
+      #
+      # ## Example
+      #
+      #   collection = Collection.new
+      #   collection << Attribute::Base.new(:name, :string)
+      #   collection << Attribute::Base.new(:age, :integer)
+      #   collection.size  # => 2
+      #   collection.exists?  # => true
+      class Collection
+        extend Forwardable
+
+        def_delegators :@collection,
+                       :<<,
+                       :to_h, :map,
+                       :each_with_object, :each,
+                       :select, :reject, :size,
+                       :find, :first,
+                       :empty?
+
+        # Creates a new collection instance
+        #
+        # @param collection [Set] Initial collection (default: empty Set)
+        def initialize(collection = Set.new)
+          @collection = collection
+        end
+
+        # Checks if collection has any elements
+        #
+        # @return [Boolean] True if collection is not empty
+        def exists?
+          !empty?
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/dsl.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      # DSL module for defining attributes in Entity-like classes.
+      #
+      # This module provides the class-level DSL for defining attributes.
+      # It can be included in any class that needs attribute definition capabilities.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # class MyEntity
+      #   include Treaty::Entity::Attribute::DSL
+      #
+      #   string :name
+      #   integer :age
+      # end
+      # ```
+      module DSL
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          # Defines an attribute with explicit type
+          #
+          # @param name [Symbol] The attribute name
+          # @param type [Symbol] The attribute type
+          # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
+          # @param options [Hash] Attribute options
+          # @param block [Proc] Block for nested attributes
+          # @return [void]
+          def attribute(name, type, *helpers, **options, &block)
+            collection_of_attributes << create_attribute(
+              name,
+              type,
+              *helpers,
+              nesting_level: 0,
+              **options,
+              &block
+            )
+          end
+
+          # Returns collection of attributes for this class
+          #
+          # @return [Treaty::Entity::Attribute::Collection] Collection of attributes
+          def collection_of_attributes
+            @collection_of_attributes ||= Treaty::Entity::Attribute::Collection.new
+          end
+
+          # Handles DSL methods like `string :name` where method name is the type
+          #
+          # @param type [Symbol] The attribute type (method name)
+          # @param name [Symbol] The attribute name (first argument)
+          # @param helpers [Array<Symbol>] Helper symbols
+          # @param options [Hash] Attribute options
+          # @param block [Proc] Block for nested attributes
+          # @return [void]
+          def method_missing(type, *helpers, **options, &block)
+            name = helpers.shift
+
+            # If no attribute name provided, this is not an attribute definition
+            # Pass to super to handle it properly (e.g., for methods like 'info', 'call!', etc.)
+            return super if name.nil?
+
+            attribute(name, type, *helpers, **options, &block)
+          end
+
+          def respond_to_missing?(name, *)
+            super
+          end
+
+          private
+
+          # Creates an attribute instance (must be implemented by including class)
+          #
+          # @raise [Treaty::Exceptions::NotImplemented] If not implemented
+          # @return [Attribute::Base] Created attribute instance
+          def create_attribute(*)
+            raise Treaty::Exceptions::NotImplemented,
+                  I18n.t(
+                    "treaty.attributes.dsl.create_attribute_not_implemented",
+                    class: self
+                  )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/helper_mapper.rb

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