treaty 0.6.0 → 0.8.0

data/lib/treaty/attribute/validation/nested_array_validator.rb

@@ -8,7 +8,7 @@ module Treaty
       # ## Purpose
       #
       # Performs validation for nested array attributes during the validation phase.
-      # Handles both simple arrays (with :_self scope) and complex arrays (objects).
+      # Handles both simple arrays (with :_self attribute) and complex arrays (objects).
       #
       # ## Responsibilities
       #
@@ -19,7 +19,7 @@ module Treaty
       #
       # ## Array Types
       #
-      # ### Simple Array (`:_self` scope)
+      # ### Simple Array (`:_self` attribute)
       # Array containing primitive values (strings, integers, etc.)
       #
       # ```ruby
@@ -93,7 +93,7 @@ module Treaty
 
         private
 
-        # Validates array item for simple arrays (with :_self scope)
+        # Validates array item for simple arrays (with :_self attribute)
         # Simple array contains primitive values: strings, integers, datetimes, etc.
         # Example: ["ruby", "rails", "api"] where each item is a String
         #
@@ -115,10 +115,12 @@ module Treaty
           return if validated
 
           raise Treaty::Exceptions::Validation,
-                I18n.t("treaty.attributes.validators.nested.array.element_validation_error",
-                       attribute: @attribute.name,
-                       index:,
-                       errors: errors.join("; "))
+                I18n.t(
+                  "treaty.attributes.validators.nested.array.element_validation_error",
+                  attribute: @attribute.name,
+                  index:,
+                  errors: errors.join("; ")
+                )
         end
 
         # Validates array item for complex arrays (with regular attributes)
@@ -132,10 +134,12 @@ module Treaty
         def validate_regular_array_item!(array_item, index) # rubocop:disable Metrics/MethodLength
           unless array_item.is_a?(Hash)
             raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.nested.array.element_type_error",
-                         attribute: @attribute.name,
-                         index:,
-                         actual: array_item.class)
+                  I18n.t(
+                    "treaty.attributes.validators.nested.array.element_type_error",
+                    attribute: @attribute.name,
+                    index:,
+                    actual: array_item.class
+                  )
           end
 
           regular_validators.each do |nested_attribute, validator|
@@ -143,10 +147,12 @@ module Treaty
             validator.validate_value!(nested_value)
           rescue Treaty::Exceptions::Validation => e
             raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.nested.array.attribute_error",
-                         attribute: @attribute.name,
-                         index:,
-                         message: e.message)
+                  I18n.t(
+                    "treaty.attributes.validators.nested.array.attribute_error",
+                    attribute: @attribute.name,
+                    index:,
+                    message: e.message
+                  )
           end
         end
 

data/lib/treaty/attribute/validation/nested_transformer.rb

@@ -6,8 +6,8 @@ module Treaty
       # Handles transformation of nested attributes (objects and arrays).
       # Extracted from Orchestrator::Base to reduce complexity.
       class NestedTransformer
-        SELF_SCOPE = :_self
-        private_constant :SELF_SCOPE
+        SELF_OBJECT = :_self
+        private_constant :SELF_OBJECT
 
         attr_reader :attribute
 
@@ -118,8 +118,8 @@ module Treaty
 
         # Transforms array with nested attributes
         class ArrayTransformer
-          SELF_SCOPE = :_self
-          private_constant :SELF_SCOPE
+          SELF_OBJECT = :_self
+          private_constant :SELF_OBJECT
 
           attr_reader :attribute
 
@@ -150,10 +150,10 @@ module Treaty
 
           # Checks if this is a simple array (primitive values)
           #
-          # @return [Boolean] True if array contains primitive values with :_self scope
+          # @return [Boolean] True if array contains primitive values with :_self attribute
           def simple_array?
             attribute.collection_of_attributes.size == 1 &&
-              attribute.collection_of_attributes.first.name == SELF_SCOPE
+              attribute.collection_of_attributes.first.name == SELF_OBJECT
           end
 
           # Validates a simple array element (primitive value)
@@ -171,10 +171,12 @@ module Treaty
               validator.validate_value!(item)
             rescue Treaty::Exceptions::Validation => e
               raise Treaty::Exceptions::Validation,
-                    I18n.t("treaty.attributes.validators.nested.array.element_validation_error",
-                           attribute: attribute.name,
-                           index:,
-                           errors: e.message)
+                    I18n.t(
+                      "treaty.attributes.validators.nested.array.element_validation_error",
+                      attribute: attribute.name,
+                      index:,
+                      errors: e.message
+                    )
             end
           end
 
@@ -187,10 +189,12 @@ module Treaty
           def transform_array_item(item, index) # rubocop:disable Metrics/MethodLength
             unless item.is_a?(Hash)
               raise Treaty::Exceptions::Validation,
-                    I18n.t("treaty.attributes.validators.nested.array.element_type_error",
-                           attribute: attribute.name,
-                           index:,
-                           actual: item.class)
+                    I18n.t(
+                      "treaty.attributes.validators.nested.array.element_type_error",
+                      attribute: attribute.name,
+                      index:,
+                      actual: item.class
+                    )
             end
 
             transformed = {}
@@ -230,10 +234,12 @@ module Treaty
                                   end
             rescue Treaty::Exceptions::Validation => e
               raise Treaty::Exceptions::Validation,
-                    I18n.t("treaty.attributes.validators.nested.array.attribute_error",
-                           attribute: attribute.name,
-                           index:,
-                           message: e.message)
+                    I18n.t(
+                      "treaty.attributes.validators.nested.array.attribute_error",
+                      attribute: attribute.name,
+                      index:,
+                      message: e.message
+                    )
             end
 
             target_name = validator.target_name

data/lib/treaty/attribute/validation/orchestrator/base.rb

@@ -9,12 +9,12 @@ module Treaty
         # ## Purpose
         #
         # Coordinates the validation and transformation of request/response data for a specific
-        # API version. Processes all scopes and their attributes, applying validations and
-        # transformations defined in the treaty DSL.
+        # API version. Processes all attributes, applying validations and transformations
+        # defined in the treaty DSL.
         #
         # ## Responsibilities
         #
-        # 1. **Scope Processing** - Iterates through all defined scopes
+        # 1. **Attribute Processing** - Iterates through all defined attributes
         # 2. **Attribute Validation** - Validates each attribute's value
         # 3. **Data Transformation** - Transforms values (defaults, renaming)
         # 4. **Nested Handling** - Delegates nested structures to NestedTransformer
@@ -23,17 +23,16 @@ module Treaty
         # ## Usage
         #
         # Subclasses must implement:
-        # - `collection_of_scopes` - Returns scopes for this context (request/response)
-        # - `scope_data_for(name)` - Extracts data for a specific scope
+        # - `collection_of_attributes` - Returns attributes for this context (request/response)
         #
         # Example:
         #   orchestrator = Request::Orchestrator.new(version_factory: factory, data: params)
         #   validated_data = orchestrator.validate!
         #
-        # ## Special Scopes
+        # ## Special Case: object :_self
         #
-        # - Normal scope: `{ scope_name: { ... } }`
-        # - Self scope (`:_self`): Attributes merged directly into parent
+        # - Normal object: `{ object_name: { ... } }`
+        # - Self object (`:_self`): Attributes merged directly into parent
         #
         # ## Architecture
         #
@@ -41,13 +40,13 @@ module Treaty
         # - `AttributeValidator` - Validates individual attributes
         # - `NestedTransformer` - Handles nested objects and arrays
         #
-        # The refactored design separates concerns:
-        # - Orchestrator: High-level flow and scope iteration
+        # The design separates concerns:
+        # - Orchestrator: High-level flow and attribute iteration
         # - Validator: Individual attribute validation
         # - Transformer: Nested structure transformation
         class Base
-          SELF_SCOPE = :_self
-          private_constant :SELF_SCOPE
+          SELF_OBJECT = :_self
+          private_constant :SELF_OBJECT
 
           attr_reader :version_factory, :data
 
@@ -69,17 +68,22 @@ module Treaty
             @data = data
           end
 
-          # Validates and transforms all scopes
-          # Iterates through scopes, processes attributes, handles :_self scope
+          # Validates and transforms all attributes
+          # Iterates through attributes, processes them, handles :_self objects
           #
-          # @return [Hash] Transformed data with all scopes processed
+          # @return [Hash] Transformed data with all attributes processed
           def validate!
             transformed_data = {}
 
-            collection_of_scopes.each do |scope_factory|
-              transformed_scope_data = validate_and_transform_scope!(scope_factory)
-              transformed_data[scope_factory.name] = transformed_scope_data if scope_factory.name != SELF_SCOPE
-              transformed_data.merge!(transformed_scope_data) if scope_factory.name == SELF_SCOPE
+            collection_of_attributes.each do |attribute|
+              transformed_value = validate_and_transform_attribute!(attribute)
+
+              if attribute.name == SELF_OBJECT && attribute.type == :object
+                # For object :_self, merge nested attributes to root
+                transformed_data.merge!(transformed_value)
+              else
+                transformed_data[attribute.name] = transformed_value
+              end
             end
 
             transformed_data
@@ -87,103 +91,83 @@ module Treaty
 
           private
 
-          # Returns collection of scopes for this context
+          # Returns collection of attributes for this context
           # Must be implemented in subclasses
           #
           # @raise [Treaty::Exceptions::Validation] If not implemented
-          # @return [Array<ScopeFactory>] Collection of scope factories
-          def collection_of_scopes
+          # @return [Treaty::Attribute::Collection] Collection of attributes
+          def collection_of_attributes
             raise Treaty::Exceptions::Validation,
                   I18n.t("treaty.attributes.validators.nested.orchestrator.collection_not_implemented")
           end
 
-          # Validates all attributes in a scope (deprecated, not used)
-          #
-          # @param scope_factory [ScopeFactory] The scope to validate
-          # @return [void]
-          def validate_scope!(scope_factory)
-            scope_data = scope_data_for(scope_factory.name)
-
-            validators_for_scope(scope_factory).each do |attribute, validator|
-              value = scope_data.fetch(attribute.name, nil)
-              validator.validate_value!(value)
-            end
-          end
-
-          # Gets cached validators for scope or builds them
+          # Gets cached validators for attributes or builds them
           #
-          # @param scope_factory [ScopeFactory] The scope factory
           # @return [Hash] Hash of attribute => validator
-          def validators_for_scope(scope_factory)
-            @validators_cache ||= {}
-            @validators_cache[scope_factory] ||= build_validators_for_scope(scope_factory)
+          def validators_for_attributes
+            @validators_for_attributes ||= build_validators_for_attributes
           end
 
-          # Builds validators for all attributes in a scope
+          # Builds validators for all attributes
           #
-          # @param scope_factory [ScopeFactory] The scope factory
           # @return [Hash] Hash of attribute => validator
-          def build_validators_for_scope(scope_factory)
-            scope_factory.collection_of_attributes.each_with_object({}) do |attribute, cache|
+          def build_validators_for_attributes
+            collection_of_attributes.each_with_object({}) do |attribute, cache|
               validator = AttributeValidator.new(attribute)
               validator.validate_schema!
               cache[attribute] = validator
             end
           end
 
-          # Extracts data for a specific scope
-          # Must be implemented in subclasses
-          #
-          # @param _name [Symbol] The scope name
-          # @raise [Treaty::Exceptions::Validation] If not implemented
-          # @return [Hash] Scope data
-          def scope_data_for(_name)
-            raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.nested.orchestrator.scope_data_not_implemented")
-          end
-
-          # Validates and transforms all attributes in a scope
+          # Validates and transforms a single attribute
           # Handles both nested and regular attributes
           #
-          # @param scope_factory [ScopeFactory] The scope to process
-          # @return [Hash] Transformed scope data
-          def validate_and_transform_scope!(scope_factory) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-            scope_data = scope_data_for(scope_factory.name)
-
-            return scope_data if scope_factory.collection_of_attributes.empty?
-
-            transformed_scope_data = {}
-
-            validators_for_scope(scope_factory).each do |attribute, validator|
-              source_name = attribute.name
-              value = scope_data.fetch(source_name, nil)
-
-              if attribute.nested?
-                transformed_value = validate_and_transform_nested(attribute, value, validator)
-              else
-                validator.validate_value!(value)
-                transformed_value = validator.transform_value(value)
-              end
-
-              target_name = validator.target_name
-
-              transformed_scope_data[target_name] = transformed_value
+          # @param attribute [Attribute] The attribute to process
+          # @return [Object] Transformed attribute value
+          def validate_and_transform_attribute!(attribute) # rubocop:disable Metrics/MethodLength
+            validator = validators_for_attributes.fetch(attribute)
+
+            # For :_self object, get data from root; otherwise from attribute key
+            value = if attribute.name == SELF_OBJECT && attribute.type == :object
+                      data
+                    else
+                      data.fetch(attribute.name, nil)
+                    end
+
+            if attribute.nested?
+              validate_and_transform_nested(attribute, value, validator)
+            else
+              validator.validate_value!(value)
+              validator.transform_value(value)
             end
-
-            transformed_scope_data
           end
 
           # Validates and transforms nested attribute (object/array)
           # Delegates transformation to NestedTransformer
           #
           # @param attribute [Attribute::Base] The nested attribute
-          # @param value [Object] The value to validate and transform
+          # @param value [Object, nil] The value to validate and transform
           # @param validator [AttributeValidator] The validator instance
-          # @return [Object] Transformed nested value
+          # @return [Object, nil] Transformed nested value or nil
+          #
+          # @note Flow control:
+          #   - If value is nil and attribute is required → validate_required! raises exception
+          #   - If value is nil and attribute is optional → validate_required! does nothing, returns nil
+          #   - If value is not nil → proceeds to transformation (value guaranteed non-nil)
           def validate_and_transform_nested(attribute, value, validator)
+            # Step 1: Validate type if value is present
             validator.validate_type!(value) unless value.nil?
+
+            # Step 2: Validate required constraint
+            # This will raise an exception if attribute is required and value is nil
             validator.validate_required!(value)
 
+            # Step 3: Early return for nil values
+            # Only reaches here if attribute is optional and value is nil
+            return nil if value.nil?
+
+            # Step 4: Transform non-nil value
+            # At this point, value is guaranteed to be non-nil
             transformer = NestedTransformer.new(attribute)
             transformer.transform(value)
           end

data/lib/treaty/base.rb

@@ -2,7 +2,7 @@
 
 module Treaty
   class Base
-    include Info::DSL
+    include Info::Rest::DSL
     include Context::DSL
     include Versions::DSL
   end

data/lib/treaty/controller/dsl.rb

@@ -25,7 +25,10 @@ module Treaty
           treaty_class_name.constantize
         rescue NameError
           raise Treaty::Exceptions::ClassName,
-                I18n.t("treaty.controller.treaty_class_not_found", class_name: treaty_class_name)
+                I18n.t(
+                  "treaty.controller.treaty_class_not_found",
+                  class_name: treaty_class_name
+                )
         end
 
         def treaty_class_name

data/lib/treaty/entity.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Treaty
+  # Base class for defining DTO (Data Transfer Object) entities in Treaty.
+  #
+  # ## Purpose
+  #
+  # Treaty::Entity provides a base class for creating reusable DTO 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:
+  #
+  # ```ruby
+  # class PostEntity < Treaty::Entity
+  #   string :id
+  #   string :title
+  #   string :content
+  #   datetime :created_at
+  # end
+  # ```
+  #
+  # Then use it in your treaty definitions:
+  #
+  # ```ruby
+  # class CreateTreaty < ApplicationTreaty
+  #   version 1 do
+  #     request PostEntity
+  #     response 201, PostEntity
+  #   end
+  # end
+  # ```
+  #
+  # ## Attribute Defaults
+  #
+  # Unlike request/response blocks, Entity attributes are required by default:
+  # - All attributes have `required: true` unless explicitly marked as `:optional`
+  # - Use `:optional` helper to make attributes optional:
+  #   ```ruby
+  #   string :title           # required by default
+  #   string :summary, :optional  # optional
+  #   ```
+  #
+  # ## Features
+  #
+  # - **Type Safety** - Enforce strict type checking for all attributes
+  # - **Nested Structures** - Support for nested objects and arrays
+  # - **Validation** - Built-in validation for all attribute types
+  # - **Reusability** - Define once, use in multiple treaties
+  # - **Options** - Full support for attribute options (required, default, as, etc.)
+  #
+  # ## Supported Types
+  #
+  # - `string` - String values
+  # - `integer` - Integer values
+  # - `boolean` - Boolean values (true/false)
+  # - `datetime` - DateTime values
+  # - `array` - Array values (with nested type definition)
+  # - `object` - Object values (with nested attributes)
+  class Entity
+    include Info::Entity::DSL
+    include Attribute::DSL
+
+    class << self
+      private
+
+      # Creates an Attribute::Entity::Attribute for this Entity class
+      #
+      # @return [Attribute::Entity::Attribute] Created attribute instance
+      def create_attribute(name, type, *helpers, nesting_level:, **options, &block)
+        Attribute::Entity::Attribute.new(
+          name,
+          type,
+          *helpers,
+          nesting_level:,
+          **options,
+          &block
+        )
+      end
+    end
+  end
+end

data/lib/treaty/exceptions/nested_attributes.rb

@@ -18,7 +18,7 @@ module Treaty
     #
     # ```ruby
     # request do
-    #   scope :user do
+    #   object :user do
     #     object :profile do
     #       object :settings do
     #         object :preferences do
@@ -57,7 +57,7 @@ module Treaty
     #
     # - Keep nesting shallow (2-3 levels maximum)
     # - Consider flattening deeply nested structures
-    # - Use separate scopes instead of deep nesting
+    # - Use separate objects instead of deep nesting
     # - Refactor complex structures into simpler ones
     class NestedAttributes < Base
     end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Info
+    module Entity
+      class Builder
+        attr_reader :attributes
+
+        def self.build(...)
+          new.build(...)
+        end
+
+        def build(collection_of_attributes:)
+          build_all(
+            attributes: collection_of_attributes
+          )
+
+          self
+        end
+
+        private
+
+        def build_all(attributes:)
+          @attributes = build_versions_with(attributes)
+        end
+
+        ##########################################################################
+
+        def build_versions_with(collection, current_level = 0)
+          collection.to_h do |attribute|
+            [
+              attribute.name,
+              {
+                type: attribute.type,
+                options: attribute.options,
+                attributes: build_nested_attributes(attribute, current_level)
+              }
+            ]
+          end
+        end
+
+        def build_nested_attributes(attribute, current_level)
+          return {} unless attribute.nested?
+
+          build_versions_with(attribute.collection_of_attributes, current_level + 1)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Info
+    module Entity
+      module DSL
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def info
+            builder = Builder.build(
+              collection_of_attributes:
+            )
+
+            Result.new(builder)
+          end
+
+          # API: Treaty Web
+          def treaty?
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/info/entity/result.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Info
+    module Entity
+      class Result
+        attr_reader :attributes
+
+        def initialize(builder)
+          @attributes = builder.attributes
+        end
+      end
+    end
+  end
+end