treaty 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed95ed37e55c61ca17604d5ef395f93405adbb8259064a08b9857b032d267c93
-  data.tar.gz: 48a97168517da5bbca25f73174e5caa666939505193d556b6612ea238f67b98a
+  metadata.gz: c7b03c7d0eed4f560087ed9662f711e50ec947a78357d687ea2be29ddd9b7872
+  data.tar.gz: c9b3b121e50d75518e4db1a0b3c388f36334cce4b9995aefb5b24e3101e5d984
 SHA512:
-  metadata.gz: 8ae24db235dc2b5127d42e4823d7a103dc6bb85f39bd6ef7ef2ab27cf406bf6adb555177bea649bc3231fb7f8741753c217d976d11b65c10ae5675757aeeca98
-  data.tar.gz: 6985a2a682ee06acf5ae091bef6c6c15469ede66d4eebd6bf510973a2e84d16aa3144e82429e9ebbaaa662628eec7054287d708a9917f67e8214987174aa2b03
+  metadata.gz: 13ca45c37ea6988a5b046a8c7825cf11acfd62fbc5c32d120888c66623da24f52dbea656120a71e815018765573aa3b1c05370bba356fc4913dd02ec342022c6
+  data.tar.gz: 431831fb76b2a44997aef884aa3662d7cff2a474f13a308472af78cd298471776f001454b98d02ed38a11e3d9f9f84ff2e5034f77004533d092483fd4b8f6420

data/README.md

@@ -13,7 +13,7 @@
 </div>
 
 > [!WARNING]
-> **Development Status**: Treaty is currently under active development in the 0.x version series. Breaking changes may occur between minor versions (0.x) as we refine the API and add new features. The library will stabilize with the 1.0 release. We recommend pinning to specific patch versions in your Gemfile (e.g., `gem "treaty", "~> 0.18.0"`) until the 1.0 release.
+> **Development Status**: Treaty is currently under active development in the 0.x version series. Breaking changes may occur between minor versions (0.x) as we refine the API and add new features. The library will stabilize with the 1.0 release. We recommend pinning to specific patch versions in your Gemfile (e.g., `gem "treaty", "~> 0.19.0"`) until the 1.0 release.
 
 ## 📚 Documentation
 

data/config/locales/en.yml

@@ -84,7 +84,7 @@ en:
         not_implemented: "%{class} must implement #create_attribute"
         create_attribute_not_implemented: "Subclass %{class} must implement #create_attribute method"
         deep_copy_not_implemented: "%{class} must implement #deep_copy_attribute"
-        invalid_entity_class: "use_entity expects a Treaty::Entity subclass, got %{type}: %{value}"
+        invalid_entity_class: "use_entity expects a Treaty::Entity::Base subclass, got %{type}: %{value}"
         use_entity_after_attributes: "use_entity must be the only statement in the block. Cannot call use_entity after defining other attributes."
         attributes_after_use_entity: "use_entity must be the only statement in the block. Cannot define attributes after calling use_entity."
 
@@ -101,7 +101,7 @@ en:
       # Request factory DSL
       factory:
         unknown_method: "Unknown method '%{method}' in request definition. Use 'object :name do ... end' to define request structure"
-        invalid_entity_class: "Request expects a Treaty::Entity subclass, got %{type}: %{value}"
+        invalid_entity_class: "Request expects a Treaty::Entity::Base subclass, got %{type}: %{value}"
 
     # ============================================================================
     # Response: Response definition and structure
@@ -110,7 +110,7 @@ en:
       # Response factory DSL
       factory:
         unknown_method: "Unknown method '%{method}' in response definition. Use 'object :name do ... end' to define response structure"
-        invalid_entity_class: "Response expects a Treaty::Entity subclass, got %{type}: %{value}"
+        invalid_entity_class: "Response expects a Treaty::Entity::Base subclass, got %{type}: %{value}"
 
     # ============================================================================
     # Versioning: API version management and resolution

data/lib/treaty/engine.rb

@@ -12,7 +12,7 @@ module Treaty
 
     initializer "treaty.register_option_processors", before: :load_config_initializers do
       # Register all option processors (validators and modifiers)
-      require "treaty/attribute/option/registry_initializer"
+      require "treaty/entity/attribute/option/registry_initializer"
     end
 
     initializer "treaty.validate_configuration" do

data/lib/treaty/{attribute/entity → entity/attribute}/attribute.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Treaty
-  module Attribute
-    module Entity
+  module Entity
+    module Attribute
       # Entity-specific attribute that defaults to required: true
-      class Attribute < Treaty::Attribute::Base
+      class Attribute < Base
         private
 
         def apply_defaults!
@@ -16,7 +16,7 @@ module Treaty
         def process_nested_attributes(&block)
           return unless object_or_array?
 
-          builder = Builder.new(collection_of_attributes, @nesting_level + 1)
+          builder = Treaty::Entity::Builder.new(collection_of_attributes, @nesting_level + 1)
           builder.instance_eval(&block)
         end
       end

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 [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 [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