treaty 0.18.0 → 0.20.0

data/lib/treaty/entity/base.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    # Base class for defining reusable entity classes in Treaty.
+    #
+    # ## Purpose
+    #
+    # Treaty::Entity::Base 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 an entity class by inheriting from Treaty::Entity::Base:
+    #
+    # ```ruby
+    # module Posts
+    #   module Create
+    #     class ResponseEntity < Treaty::Entity::Base
+    #       string :id
+    #       string :title
+    #       string :content
+    #       datetime :created_at
+    #     end
+    #   end
+    # end
+    # ```
+    #
+    # Then use it in your treaty definitions:
+    #
+    # ```ruby
+    # class Posts::CreateTreaty < ApplicationTreaty
+    #   version 1 do
+    #     request Posts::Create::RequestEntity
+    #     response 201, Posts::Create::ResponseEntity
+    #   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 Base
+      include Info::DSL
+      include Attribute::DSL
+
+      class << self
+        private
+
+        # Creates an Entity::Attribute for this Entity class
+        #
+        # @return [Treaty::Entity::Attribute::Attribute] Created attribute instance
+        def create_attribute(name, type, *helpers, nesting_level:, **options, &block)
+          Attribute::Attribute.new(
+            name,
+            type,
+            *helpers,
+            nesting_level:,
+            **options,
+            &block
+          )
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/builder.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    # DSL builder for defining entity attributes.
+    #
+    # ## Purpose
+    #
+    # Provides Entity-specific implementation of the attribute builder.
+    # Creates Entity::Attribute::Attribute instances with **required by default**
+    # behavior (unlike Request/Response which have different defaults).
+    #
+    # ## Inheritance
+    #
+    # Extends Treaty::Entity::Attribute::Builder::Base which provides:
+    # - DSL interface (string, integer, object, array, etc.)
+    # - method_missing magic for type-based method calls
+    # - Helper support (:required, :optional)
+    # - Entity reuse via use_entity
+    #
+    # ## Usage
+    #
+    # Used internally by:
+    # - Entity::Attribute::Attribute (when processing nested object/array blocks)
+    #
+    # ## Default Behavior
+    #
+    # Entity attributes default to **required: true**, meaning all fields
+    # must be present unless explicitly marked `:optional`.
+    #
+    # ## DSL Example
+    #
+    #   class UserEntity < Treaty::Entity::Base
+    #     object :user do
+    #       string :id                    # required by default
+    #       string :name                  # required by default
+    #       string :bio, :optional        # explicitly optional
+    #       object :profile do
+    #         string :avatar_url
+    #       end
+    #     end
+    #   end
+    #
+    # ## Methods
+    #
+    # Implements abstract methods from base class:
+    # - `create_attribute` - Creates Entity::Attribute::Attribute
+    # - `deep_copy_attribute` - Deep copies attribute for use_entity support
+    class Builder < Treaty::Entity::Attribute::Builder::Base
+      private
+
+      # Creates a new entity attribute instance
+      #
+      # Called by base class when defining attributes via DSL.
+      #
+      # @param name [Symbol] Attribute name
+      # @param type [Symbol] Attribute type (:string, :integer, :object, etc.)
+      # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
+      # @param nesting_level [Integer] Current nesting depth
+      # @param options [Hash] Attribute options (default:, format:, etc.)
+      # @param block [Proc] Block for nested attributes (object/array)
+      # @return [Treaty::Entity::Attribute::Attribute] Created attribute instance
+      def create_attribute(name, type, *helpers, nesting_level:, **options, &block)
+        Treaty::Entity::Attribute::Attribute.new(
+          name,
+          type,
+          *helpers,
+          nesting_level:,
+          **options,
+          &block
+        )
+      end
+
+      # Deep copies an attribute with adjusted nesting level
+      #
+      # Used when copying attributes from other Entity classes via use_entity.
+      # Recursively copies nested attributes for object/array types.
+      #
+      # @param source_attribute [Treaty::Entity::Attribute::Base] Source attribute to copy
+      # @param new_nesting_level [Integer] Nesting level for copied attribute
+      # @return [Treaty::Entity::Attribute::Attribute] Deep copied attribute
+      def deep_copy_attribute(source_attribute, new_nesting_level) # rubocop:disable Metrics/MethodLength
+        copied = Treaty::Entity::Attribute::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/{info/entity → entity/info}/builder.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Treaty
-  module Info
-    module Entity
+  module Entity
+    module Info
       class Builder
         attr_reader :attributes
 
@@ -26,6 +26,12 @@ module Treaty
 
         ##########################################################################
 
+        def build_nested_attributes(attribute, current_level)
+          return {} unless attribute.nested?
+
+          build_versions_with(attribute.collection_of_attributes, current_level + 1)
+        end
+
         def build_versions_with(collection, current_level = 0)
           collection.to_h do |attribute|
             [
@@ -38,12 +44,6 @@ module Treaty
             ]
           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

data/lib/treaty/{info/entity → entity/info}/dsl.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Treaty
-  module Info
-    module Entity
+  module Entity
+    module Info
       module DSL
         def self.included(base)
           base.extend(ClassMethods)

data/lib/treaty/{info/entity → entity/info}/result.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Treaty
-  module Info
-    module Entity
+  module Entity
+    module Info
       class Result
         attr_reader :attributes
 

data/lib/treaty/entity.rb

@@ -1,88 +1,16 @@
 # frozen_string_literal: true
 
 module Treaty
-  # Base class for defining reusable entity classes in Treaty.
+  # Entity namespace containing the base class and attribute system.
   #
-  # ## Purpose
+  # Users should inherit from Treaty::Entity::Base:
   #
-  # 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 an entity class by inheriting from Treaty::Entity:
-  #
-  # ```ruby
-  # module Posts
-  #   module Create
-  #     class ResponseEntity < Treaty::Entity
-  #       string :id
-  #       string :title
-  #       string :content
-  #       datetime :created_at
-  #     end
+  #   class MyEntity < Treaty::Entity::Base
+  #     string :name
+  #     integer :age
   #   end
-  # end
-  # ```
-  #
-  # Then use it in your treaty definitions:
-  #
-  # ```ruby
-  # class Posts::CreateTreaty < ApplicationTreaty
-  #   version 1 do
-  #     request Posts::Create::RequestEntity
-  #     response 201, Posts::Create::ResponseEntity
-  #   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
+  # @see Treaty::Entity::Base for full documentation and examples
+  module Entity
   end
 end

data/lib/treaty/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: treaty
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -147,44 +147,75 @@ files:
 - Rakefile
 - config/locales/en.yml
 - lib/treaty.rb
-- lib/treaty/attribute/base.rb
-- lib/treaty/attribute/builder/base.rb
-- lib/treaty/attribute/collection.rb
-- lib/treaty/attribute/dsl.rb
-- lib/treaty/attribute/entity/attribute.rb
-- lib/treaty/attribute/entity/builder.rb
-- lib/treaty/attribute/helper_mapper.rb
-- lib/treaty/attribute/option/base.rb
-- lib/treaty/attribute/option/conditionals/base.rb
-- lib/treaty/attribute/option/conditionals/if_conditional.rb
-- lib/treaty/attribute/option/conditionals/unless_conditional.rb
-- lib/treaty/attribute/option/modifiers/as_modifier.rb
-- lib/treaty/attribute/option/modifiers/cast_modifier.rb
-- lib/treaty/attribute/option/modifiers/computed_modifier.rb
-- lib/treaty/attribute/option/modifiers/default_modifier.rb
-- lib/treaty/attribute/option/modifiers/transform_modifier.rb
-- lib/treaty/attribute/option/registry.rb
-- lib/treaty/attribute/option/registry_initializer.rb
-- lib/treaty/attribute/option/validators/format_validator.rb
-- lib/treaty/attribute/option/validators/inclusion_validator.rb
-- lib/treaty/attribute/option/validators/required_validator.rb
-- lib/treaty/attribute/option/validators/type_validator.rb
-- lib/treaty/attribute/option_normalizer.rb
-- lib/treaty/attribute/option_orchestrator.rb
-- lib/treaty/attribute/validation/attribute_validator.rb
-- lib/treaty/attribute/validation/base.rb
-- lib/treaty/attribute/validation/nested_array_validator.rb
-- lib/treaty/attribute/validation/nested_object_validator.rb
-- lib/treaty/attribute/validation/nested_transformer.rb
-- lib/treaty/attribute/validation/orchestrator/base.rb
-- lib/treaty/base.rb
+- lib/treaty/action.rb
+- lib/treaty/action/base.rb
+- lib/treaty/action/context/callable.rb
+- lib/treaty/action/context/dsl.rb
+- lib/treaty/action/context/workspace.rb
+- lib/treaty/action/executor/inventory.rb
+- lib/treaty/action/info/builder.rb
+- lib/treaty/action/info/dsl.rb
+- lib/treaty/action/info/result.rb
+- lib/treaty/action/inventory/collection.rb
+- lib/treaty/action/inventory/factory.rb
+- lib/treaty/action/inventory/inventory.rb
+- lib/treaty/action/request/attribute/attribute.rb
+- lib/treaty/action/request/attribute/builder.rb
+- lib/treaty/action/request/entity.rb
+- lib/treaty/action/request/factory.rb
+- lib/treaty/action/request/validator.rb
+- lib/treaty/action/response/attribute/attribute.rb
+- lib/treaty/action/response/attribute/builder.rb
+- lib/treaty/action/response/entity.rb
+- lib/treaty/action/response/factory.rb
+- lib/treaty/action/response/validator.rb
+- lib/treaty/action/result.rb
+- lib/treaty/action/versions/collection.rb
+- lib/treaty/action/versions/dsl.rb
+- lib/treaty/action/versions/execution/request.rb
+- lib/treaty/action/versions/executor.rb
+- lib/treaty/action/versions/factory.rb
+- lib/treaty/action/versions/resolver.rb
+- lib/treaty/action/versions/semantic.rb
+- lib/treaty/action/versions/workspace.rb
 - lib/treaty/configuration.rb
-- lib/treaty/context/callable.rb
-- lib/treaty/context/dsl.rb
-- lib/treaty/context/workspace.rb
 - lib/treaty/controller/dsl.rb
 - lib/treaty/engine.rb
 - lib/treaty/entity.rb
+- lib/treaty/entity/attribute/attribute.rb
+- lib/treaty/entity/attribute/base.rb
+- lib/treaty/entity/attribute/builder/base.rb
+- lib/treaty/entity/attribute/collection.rb
+- lib/treaty/entity/attribute/dsl.rb
+- lib/treaty/entity/attribute/helper_mapper.rb
+- lib/treaty/entity/attribute/option/base.rb
+- lib/treaty/entity/attribute/option/conditionals/base.rb
+- lib/treaty/entity/attribute/option/conditionals/if_conditional.rb
+- lib/treaty/entity/attribute/option/conditionals/unless_conditional.rb
+- lib/treaty/entity/attribute/option/modifiers/as_modifier.rb
+- lib/treaty/entity/attribute/option/modifiers/cast_modifier.rb
+- lib/treaty/entity/attribute/option/modifiers/computed_modifier.rb
+- lib/treaty/entity/attribute/option/modifiers/default_modifier.rb
+- lib/treaty/entity/attribute/option/modifiers/transform_modifier.rb
+- lib/treaty/entity/attribute/option/registry.rb
+- lib/treaty/entity/attribute/option/registry_initializer.rb
+- lib/treaty/entity/attribute/option/validators/format_validator.rb
+- lib/treaty/entity/attribute/option/validators/inclusion_validator.rb
+- lib/treaty/entity/attribute/option/validators/required_validator.rb
+- lib/treaty/entity/attribute/option/validators/type_validator.rb
+- lib/treaty/entity/attribute/option_normalizer.rb
+- lib/treaty/entity/attribute/option_orchestrator.rb
+- lib/treaty/entity/attribute/validation/attribute_validator.rb
+- lib/treaty/entity/attribute/validation/base.rb
+- lib/treaty/entity/attribute/validation/nested_array_validator.rb
+- lib/treaty/entity/attribute/validation/nested_object_validator.rb
+- lib/treaty/entity/attribute/validation/nested_transformer.rb
+- lib/treaty/entity/attribute/validation/orchestrator/base.rb
+- lib/treaty/entity/base.rb
+- lib/treaty/entity/builder.rb
+- lib/treaty/entity/info/builder.rb
+- lib/treaty/entity/info/dsl.rb
+- lib/treaty/entity/info/result.rb
 - lib/treaty/exceptions/base.rb
 - lib/treaty/exceptions/class_name.rb
 - lib/treaty/exceptions/deprecated.rb
@@ -199,37 +230,8 @@ files:
 - lib/treaty/exceptions/version_default_deprecated_conflict.rb
 - lib/treaty/exceptions/version_multiple_defaults.rb
 - lib/treaty/exceptions/version_not_found.rb
-- lib/treaty/executor/inventory.rb
-- lib/treaty/info/entity/builder.rb
-- lib/treaty/info/entity/dsl.rb
-- lib/treaty/info/entity/result.rb
-- lib/treaty/info/rest/builder.rb
-- lib/treaty/info/rest/dsl.rb
-- lib/treaty/info/rest/result.rb
-- lib/treaty/inventory/collection.rb
-- lib/treaty/inventory/factory.rb
-- lib/treaty/inventory/inventory.rb
-- lib/treaty/request/attribute/attribute.rb
-- lib/treaty/request/attribute/builder.rb
-- lib/treaty/request/entity.rb
-- lib/treaty/request/factory.rb
-- lib/treaty/request/validator.rb
-- lib/treaty/response/attribute/attribute.rb
-- lib/treaty/response/attribute/builder.rb
-- lib/treaty/response/entity.rb
-- lib/treaty/response/factory.rb
-- lib/treaty/response/validator.rb
-- lib/treaty/result.rb
 - lib/treaty/support/loader.rb
 - lib/treaty/version.rb
-- lib/treaty/versions/collection.rb
-- lib/treaty/versions/dsl.rb
-- lib/treaty/versions/execution/request.rb
-- lib/treaty/versions/executor.rb
-- lib/treaty/versions/factory.rb
-- lib/treaty/versions/resolver.rb
-- lib/treaty/versions/semantic.rb
-- lib/treaty/versions/workspace.rb
 homepage: https://github.com/servactory/treaty
 licenses:
 - MIT