treaty 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc42fa86dd5dc35d49f0a07a189d9ddc59f619e2341905c1ed62193e0d3069b7
-  data.tar.gz: ffc66f03e0ced6e666bb12db50f405117831b48c26475ab034ab4a16f4c431b1
+  metadata.gz: ed95ed37e55c61ca17604d5ef395f93405adbb8259064a08b9857b032d267c93
+  data.tar.gz: 48a97168517da5bbca25f73174e5caa666939505193d556b6612ea238f67b98a
 SHA512:
-  metadata.gz: 0b31ad204ddb19df8a296007f334d29e2e220fbb771f9c5a3851309e0a9ec1909dae0dbef3608633f6a5203da0b827fb90c75132e83f5ebb3fcc28f36fd33cc9
-  data.tar.gz: 0c6ec71d1be9155da662498264667a63072c5ce513d1ae0987a54091d76aa35a9fd21b3c722db38a8f4154919a2894f442736c44e23ff88961c9a1aadc841c49
+  metadata.gz: 8ae24db235dc2b5127d42e4823d7a103dc6bb85f39bd6ef7ef2ab27cf406bf6adb555177bea649bc3231fb7f8741753c217d976d11b65c10ae5675757aeeca98
+  data.tar.gz: 6985a2a682ee06acf5ae091bef6c6c15469ede66d4eebd6bf510973a2e84d16aa3144e82429e9ebbaaa662628eec7054287d708a9917f67e8214987174aa2b03

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.16.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.18.0"`) until the 1.0 release.
 
 ## 📚 Documentation
 
@@ -33,7 +33,7 @@ Treaty provides a complete solution for building versioned APIs in Ruby on Rails
 - **Type Safety** - Enforce strict type checking for request and response data
 - **API Versioning** - Manage multiple concurrent API versions effortlessly
 - **Unified Architecture** - Request blocks, response blocks, and Entity classes share the same validation system
-- **Entity Classes (DTOs)** - Define reusable data transfer objects for better code organization
+- **Entity Classes** - Define reusable entity classes for better code organization
 - **Built-in Validation** - Validate incoming requests and outgoing responses automatically
 - **Data Transformation** - Transform data seamlessly between different API versions
 - **Inventory System** - Pass controller-specific data to services efficiently

data/config/locales/en.yml

@@ -83,6 +83,10 @@ en:
       builder:
         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}"
+        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."
 
       # Attribute-level errors
       errors:

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

@@ -16,6 +16,7 @@ module Treaty
       # 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
       #
@@ -33,6 +34,18 @@ module Treaty
       # 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
@@ -63,12 +76,14 @@ module Treaty
       #
       # 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
@@ -80,6 +95,34 @@ module Treaty
         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 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
@@ -91,6 +134,10 @@ module Treaty
         # @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,
@@ -133,10 +180,93 @@ module Treaty
         # @raise [Treaty::Exceptions::NotImplemented] If subclass doesn't implement
         # @return [Attribute::Base] Created attribute instance
         def create_attribute(*)
-          # Must be implemented in subclasses
           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 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
+
+          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

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

@@ -17,6 +17,29 @@ module Treaty
             &block
           )
         end
+
+        # Deep copies an attribute with adjusted nesting level for Entity context.
+        #
+        # @param source_attribute [Treaty::Attribute::Base] Attribute to copy
+        # @param new_nesting_level [Integer] New nesting level
+        # @return [Entity::Attribute] Copied attribute
+        def deep_copy_attribute(source_attribute, new_nesting_level) # rubocop:disable Metrics/MethodLength
+          copied = Attribute.new(
+            source_attribute.name,
+            source_attribute.type,
+            nesting_level: new_nesting_level,
+            **deep_copy_options(source_attribute.options)
+          )
+
+          return copied unless source_attribute.nested?
+
+          source_attribute.collection_of_attributes.each do |nested_source|
+            nested_copied = deep_copy_attribute(nested_source, new_nesting_level + 1)
+            copied.collection_of_attributes << nested_copied
+          end
+
+          copied
+        end
       end
     end
   end

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

@@ -17,9 +17,9 @@ module Treaty
         #   integer :views, if: ->(post:) { post[:published_at].present? }
         #
         # Complex conditions:
-        #   string :admin_note, if: ->(**attrs) {
-        #     attrs.dig(:user, :role) == "admin" && attrs.dig(:post, :flagged)
-        #   }
+        #   string :admin_note, if: (lambda do |**attributes|
+        #     attributes.dig(:user, :role) == "admin" && attributes.dig(:post, :flagged)
+        #   end)
         #
         # ## Use Cases
         #
@@ -30,7 +30,7 @@ module Treaty
         #        string :id
         #        string :title
         #        datetime :published_at, :optional
-        #        integer :rating, if: ->(**attrs) { attrs.dig(:post, :published_at).present? }
+        #        integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
         #      end
         #    end
         #    # If published_at is nil → rating is excluded from response
@@ -80,7 +80,7 @@ module Treaty
         #
         # ```ruby
         # # For response with { post: { title: "...", published_at: "..." } }
-        # integer :rating, if: ->(**attrs) { attrs.dig(:post, :published_at).present? }
+        # integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
         #
         # # Alternative: named argument pattern
         # integer :rating, if: ->(post:) { post[:published_at].present? }

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

@@ -17,9 +17,9 @@ module Treaty
         #   integer :edit_count, unless: ->(post:) { post[:published_at].present? }
         #
         # Complex conditions:
-        #   string :internal_note, unless: ->(**attrs) {
-        #     attrs.dig(:user, :role) == "admin" && attrs.dig(:post, :flagged)
-        #   }
+        #   string :internal_note, unless: (lambda do |**attributes|
+        #     attributes.dig(:user, :role) == "admin" && attributes.dig(:post, :flagged)
+        #   end)
         #
         # ## Use Cases
         #
@@ -30,7 +30,7 @@ module Treaty
         #        string :id
         #        string :title
         #        datetime :published_at, :optional
-        #        integer :draft_views, unless: ->(**attrs) { attrs.dig(:post, :published_at).present? }
+        #        integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
         #      end
         #    end
         #    # If published_at is nil → draft_views is included in response
@@ -74,12 +74,12 @@ module Treaty
         #
         # ```ruby
         # # These are equivalent:
-        # integer :rating, if: ->(**attrs) { attrs.dig(:post, :published_at).present? }
-        # integer :rating, unless: ->(**attrs) { attrs.dig(:post, :published_at).blank? }
+        # 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: ->(**attrs) { attrs.dig(:post, :published_at).present? }
-        # integer :draft_views, if: ->(**attrs) { attrs.dig(:post, :published_at).blank? }
+        # integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+        # integer :draft_views, if: ->(**attributes) { attributes.dig(:post, :published_at).blank? }
         # ```
         #
         # ## Error Handling
@@ -96,7 +96,7 @@ module Treaty
         #
         # ```ruby
         # # For response with { post: { title: "...", published_at: "..." } }
-        # integer :draft_views, unless: ->(**attrs) { attrs.dig(:post, :published_at).present? }
+        # integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
         #
         # # Alternative: named argument pattern
         # integer :draft_views, unless: ->(post:) { post[:published_at].present? }

data/lib/treaty/attribute/option/modifiers/computed_modifier.rb

@@ -14,13 +14,13 @@ module Treaty
         # ## Usage Examples
         #
         # Simple mode:
-        #   string :full_name, computed: ->(**attrs) {
-        #     "#{attrs.dig(:user, :first_name)} #{attrs.dig(:user, :last_name)}"
-        #   }
+        #   string :full_name, computed: (lambda do |**attributes|
+        #     "#{attributes.dig(:user, :first_name)} #{attributes.dig(:user, :last_name)}"
+        #   end)
         #
         # Advanced mode with custom error message:
         #   string :full_name, computed: {
-        #     is: ->(**attrs) { "#{attrs.dig(:user, :first_name)} #{attrs.dig(:user, :last_name)}" },
+        #     is: ->(**attributes) { "#{attributes.dig(:user, :first_name)} #{attributes.dig(:user, :last_name)}" },
         #     message: "Failed to compute full name"
         #   }
         #
@@ -32,9 +32,9 @@ module Treaty
         #      object :user do
         #        string :first_name
         #        string :last_name
-        #        string :full_name, computed: ->(**attrs) {
-        #          "#{attrs.dig(:user, :first_name)} #{attrs.dig(:user, :last_name)}"
-        #        }
+        #        string :full_name, computed: (lambda do |**attributes|
+        #          "#{attributes.dig(:user, :first_name)} #{attributes.dig(:user, :last_name)}"
+        #        end)
         #      end
         #    end
         #    ```
@@ -44,9 +44,9 @@ module Treaty
         #    response 200 do
         #      object :post do
         #        string :content
-        #        integer :word_count, computed: ->(**attrs) {
-        #          attrs.dig(:post, :content).to_s.split.size
-        #        }
+        #        integer :word_count, computed: (lambda do |**attributes|
+        #          attributes.dig(:post, :content).to_s.split.size
+        #        end)
         #      end
         #    end
         #    ```
@@ -57,9 +57,9 @@ module Treaty
         #      object :order do
         #        integer :quantity
         #        integer :unit_price
-        #        integer :total, computed: ->(**attrs) {
-        #          attrs.dig(:order, :quantity).to_i * attrs.dig(:order, :unit_price).to_i
-        #        }
+        #        integer :total, computed: (lambda do |**attributes|
+        #          attributes.dig(:order, :quantity).to_i * attributes.dig(:order, :unit_price).to_i
+        #        end)
         #      end
         #    end
         #    ```

data/lib/treaty/attribute/option/registry.rb

@@ -19,26 +19,27 @@ module Treaty
       #
       # ## Registered Options
       #
-      # ### Validators
-      # - `:required` → RequiredValidator
-      # - `:type` → TypeValidator
-      # - `:inclusion` → InclusionValidator
-      # - `:format` → FormatValidator
+      # ### Validators (sorted by position)
+      # - `:type` → TypeValidator (position: 100)
+      # - `:required` → RequiredValidator (position: 200)
+      # - `:inclusion` → InclusionValidator (position: 300)
+      # - `:format` → FormatValidator (position: 400)
       #
-      # ### Modifiers
-      # - `:as` → AsModifier
-      # - `:default` → DefaultModifier
-      # - `:transform` → TransformModifier
-      # - `:cast` → CastModifier
+      # ### Modifiers (sorted by position)
+      # - `:transform` → TransformModifier (position: 500)
+      # - `:cast` → CastModifier (position: 600)
+      # - `:computed` → ComputedModifier (position: 700)
+      # - `:default` → DefaultModifier (position: 800)
+      # - `:as` → AsModifier (position: 900)
       #
-      # ### Conditionals
+      # ### Conditionals (no position - handled separately)
       # - `:if` → IfConditional
       # - `:unless` → UnlessConditional
       #
       # ## Usage
       #
       # Registration (done in RegistryInitializer):
-      #   Registry.register(:required, RequiredValidator, category: :validator)
+      #   Registry.register(:required, RequiredValidator, category: :validator, position: 200)
       #   Registry.register(:if, IfConditional, category: :conditional)
       #
       # Retrieval (done in OptionOrchestrator):
@@ -64,11 +65,13 @@ module Treaty
           #
           # @param option_name [Symbol] The name of the option (e.g., :required, :as, :default)
           # @param processor_class [Class] The processor class
-          # @param category [Symbol] The category (:validator or :modifier)
-          def register(option_name, processor_class, category:)
+          # @param category [Symbol] The category (:validator, :modifier, or :conditional)
+          # @param position [Integer, nil] Execution order position (nil for conditionals)
+          def register(option_name, processor_class, category:, position: nil)
             registry[option_name] = {
               processor_class:,
-              category:
+              category:,
+              position:
             }
           end
 
@@ -88,6 +91,14 @@ module Treaty
             registry.dig(option_name, :category)
           end
 
+          # Get position for an option
+          #
+          # @param option_name [Symbol] The name of the option
+          # @return [Integer, nil] The execution order position or nil if not set
+          def position_for(option_name)
+            registry.dig(option_name, :position)
+          end
+
           # Check if an option is registered
           #
           # @param option_name [Symbol] The name of the option

data/lib/treaty/attribute/option/registry_initializer.rb

@@ -17,22 +17,22 @@ module Treaty
       # 3. **Conditional Registration** - Registers all built-in conditionals
       # 4. **Auto-Loading** - Executes automatically when file is loaded
       #
-      # ## Built-in Validators
+      # ## Built-in Validators (sorted by position)
       #
-      # - `:required` → RequiredValidator - Validates required/optional attributes
-      # - `:type` → TypeValidator - Validates value types
-      # - `:inclusion` → InclusionValidator - Validates value is in allowed set
-      # - `:format` → FormatValidator - Validates string values match specific formats
+      # - `:type` → TypeValidator (position: 100) - Validates value types
+      # - `:required` → RequiredValidator (position: 200) - Validates required/optional attributes
+      # - `:inclusion` → InclusionValidator (position: 300) - Validates value is in allowed set
+      # - `:format` → FormatValidator (position: 400) - Validates string values match specific formats
       #
-      # ## Built-in Modifiers
+      # ## Built-in Modifiers (sorted by position)
       #
-      # - `:computed` → ComputedModifier - Computes values from all raw data (executes first)
-      # - `:transform` → TransformModifier - Transforms values using custom lambdas
-      # - `:cast` → CastModifier - Converts values between types automatically
-      # - `:default` → DefaultModifier - Provides default values
-      # - `:as` → AsModifier - Renames attributes
+      # - `:transform` → TransformModifier (position: 500) - Transforms values using custom lambdas
+      # - `:cast` → CastModifier (position: 600) - Converts values between types automatically
+      # - `:computed` → ComputedModifier (position: 700) - Computes values from all raw data
+      # - `:default` → DefaultModifier (position: 800) - Provides default values
+      # - `:as` → AsModifier (position: 900) - Renames attributes
       #
-      # ## Built-in Conditionals
+      # ## Built-in Conditionals (no position - handled separately)
       #
       # - `:if` → IfConditional - Conditionally includes attributes based on runtime data
       # - `:unless` → UnlessConditional - Conditionally excludes attributes based on runtime data
@@ -76,25 +76,26 @@ module Treaty
           private
 
           # Registers all built-in validators
+          # Position determines execution order (lower = earlier)
           #
           # @return [void]
           def register_validators!
-            Registry.register(:required, Validators::RequiredValidator, category: :validator)
-            Registry.register(:type, Validators::TypeValidator, category: :validator)
-            Registry.register(:inclusion, Validators::InclusionValidator, category: :validator)
-            Registry.register(:format, Validators::FormatValidator, category: :validator)
+            Registry.register(:type, Validators::TypeValidator, category: :validator, position: 100)
+            Registry.register(:required, Validators::RequiredValidator, category: :validator, position: 200)
+            Registry.register(:inclusion, Validators::InclusionValidator, category: :validator, position: 300)
+            Registry.register(:format, Validators::FormatValidator, category: :validator, position: 400)
           end
 
           # Registers all built-in modifiers
-          # Order matters: computed runs first, then transform, cast, default, as
+          # Position determines execution order (lower = earlier)
           #
           # @return [void]
           def register_modifiers!
-            Registry.register(:computed, Modifiers::ComputedModifier, category: :modifier)
-            Registry.register(:transform, Modifiers::TransformModifier, category: :modifier)
-            Registry.register(:cast, Modifiers::CastModifier, category: :modifier)
-            Registry.register(:default, Modifiers::DefaultModifier, category: :modifier)
-            Registry.register(:as, Modifiers::AsModifier, category: :modifier)
+            Registry.register(:transform, Modifiers::TransformModifier, category: :modifier, position: 500)
+            Registry.register(:cast, Modifiers::CastModifier, category: :modifier, position: 600)
+            Registry.register(:computed, Modifiers::ComputedModifier, category: :modifier, position: 700)
+            Registry.register(:default, Modifiers::DefaultModifier, category: :modifier, position: 800)
+            Registry.register(:as, Modifiers::AsModifier, category: :modifier, position: 900)
           end
 
           # Registers all built-in conditionals

data/lib/treaty/attribute/option_normalizer.rb

@@ -87,18 +87,32 @@ module Treaty
 
       class << self
         # Normalizes all options from simple mode to advanced mode
+        # and sorts them by position for consistent execution order.
         #
         # @param options [Hash] Options hash in simple or advanced mode
-        # @return [Hash] Normalized options in advanced mode
+        # @return [Hash] Normalized options in advanced mode, sorted by position
         def normalize(options)
-          options.each_with_object({}) do |(key, value), result|
+          normalized = options.each_with_object({}) do |(key, value), result|
             advanced_key, normalized_value = normalize_option(key, value)
             result[advanced_key] = normalized_value
           end
+
+          sort_by_position(normalized)
         end
 
         private
 
+        # Sorts options by their registered position.
+        # Options without position (like conditionals) sort first (position 0).
+        #
+        # @param options_hash [Hash] Normalized options hash
+        # @return [Hash] Options sorted by position
+        def sort_by_position(options_hash)
+          options_hash.sort_by do |option_name, _|
+            Option::Registry.position_for(option_name) || 0
+          end.to_h
+        end
+
         # Normalizes a single option to advanced mode
         #
         # @param key [Symbol] Option key

data/lib/treaty/entity.rb

@@ -1,34 +1,38 @@
 # frozen_string_literal: true
 
 module Treaty
-  # Base class for defining DTO (Data Transfer Object) entities in Treaty.
+  # Base class for defining reusable entity classes in Treaty.
   #
   # ## Purpose
   #
-  # Treaty::Entity provides a base class for creating reusable DTO classes
+  # Treaty::Entity provides a base class for creating reusable entity classes
   # that can be used in both request and response definitions. This allows
   # for better code organization and reusability of common data structures.
   #
   # ## Usage
   #
-  # Create a DTO class by inheriting from Treaty::Entity:
+  # Create an entity class by inheriting from Treaty::Entity:
   #
   # ```ruby
-  # class PostEntity < Treaty::Entity
-  #   string :id
-  #   string :title
-  #   string :content
-  #   datetime :created_at
+  # module Posts
+  #   module Create
+  #     class ResponseEntity < Treaty::Entity
+  #       string :id
+  #       string :title
+  #       string :content
+  #       datetime :created_at
+  #     end
+  #   end
   # end
   # ```
   #
   # Then use it in your treaty definitions:
   #
   # ```ruby
-  # class CreateTreaty < ApplicationTreaty
+  # class Posts::CreateTreaty < ApplicationTreaty
   #   version 1 do
-  #     request PostEntity
-  #     response 201, PostEntity
+  #     request Posts::Create::RequestEntity
+  #     response 201, Posts::Create::ResponseEntity
   #   end
   # end
   # ```

data/lib/treaty/request/attribute/builder.rb

@@ -17,6 +17,29 @@ module Treaty
             &block
           )
         end
+
+        # Deep copies an attribute with adjusted nesting level for Request context.
+        #
+        # @param source_attribute [Treaty::Attribute::Base] Attribute to copy
+        # @param new_nesting_level [Integer] New nesting level
+        # @return [Request::Attribute::Attribute] Copied attribute
+        def deep_copy_attribute(source_attribute, new_nesting_level) # rubocop:disable Metrics/MethodLength
+          copied = Attribute.new(
+            source_attribute.name,
+            source_attribute.type,
+            nesting_level: new_nesting_level,
+            **deep_copy_options(source_attribute.options)
+          )
+
+          return copied unless source_attribute.nested?
+
+          source_attribute.collection_of_attributes.each do |nested_source|
+            nested_copied = deep_copy_attribute(nested_source, new_nesting_level + 1)
+            copied.collection_of_attributes << nested_copied
+          end
+
+          copied
+        end
       end
     end
   end

data/lib/treaty/request/factory.rb

@@ -21,7 +21,7 @@ module Treaty
     # ## Entity Mode
     #
     # ```ruby
-    # request PostRequestEntity
+    # request Posts::Create::RequestEntity
     # ```
     class Factory
       # Uses a provided Entity class

data/lib/treaty/response/attribute/builder.rb

@@ -17,6 +17,29 @@ module Treaty
             &block
           )
         end
+
+        # Deep copies an attribute with adjusted nesting level for Response context.
+        #
+        # @param source_attribute [Treaty::Attribute::Base] Attribute to copy
+        # @param new_nesting_level [Integer] New nesting level
+        # @return [Response::Attribute::Attribute] Copied attribute
+        def deep_copy_attribute(source_attribute, new_nesting_level) # rubocop:disable Metrics/MethodLength
+          copied = Attribute.new(
+            source_attribute.name,
+            source_attribute.type,
+            nesting_level: new_nesting_level,
+            **deep_copy_options(source_attribute.options)
+          )
+
+          return copied unless source_attribute.nested?
+
+          source_attribute.collection_of_attributes.each do |nested_source|
+            nested_copied = deep_copy_attribute(nested_source, new_nesting_level + 1)
+            copied.collection_of_attributes << nested_copied
+          end
+
+          copied
+        end
       end
     end
   end

data/lib/treaty/response/factory.rb

@@ -21,7 +21,7 @@ module Treaty
     # ## Entity Mode
     #
     # ```ruby
-    # response 200, PostResponseEntity
+    # response 200, Posts::Create::ResponseEntity
     # ```
     class Factory
       attr_reader :status

data/lib/treaty/version.rb

@@ -3,7 +3,7 @@
 module Treaty
   module VERSION
     MAJOR = 0
-    MINOR = 16
+    MINOR = 18
     PATCH = 0
     PRE = nil
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: treaty
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Anton Sokolov