treaty 0.19.0 → 0.20.0

data/lib/treaty/entity/builder.rb

@@ -2,10 +2,64 @@
 
 module Treaty
   module Entity
-    # Entity-specific attribute builder
+    # 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,
@@ -17,11 +71,14 @@ module Treaty
         )
       end
 
-      # Deep copies an attribute with adjusted nesting level for Entity context.
+      # 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] Attribute to copy
-      # @param new_nesting_level [Integer] New nesting level
-      # @return [Treaty::Entity::Attribute::Attribute] Copied attribute
+      # @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,

data/lib/treaty/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: treaty
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -147,11 +147,38 @@ files:
 - Rakefile
 - config/locales/en.yml
 - lib/treaty.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
@@ -203,34 +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/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

data/lib/treaty/base.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  class Base
-    include Info::Rest::DSL
-    include Context::DSL
-    include Versions::DSL
-  end
-end

data/lib/treaty/context/callable.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Context
-    module Callable
-      def call!(version:, params:, context: nil, inventory: nil)
-        treaty_instance = send(:new)
-
-        _call!(treaty_instance, context:, inventory:, version:, params:)
-      end
-
-      private
-
-      def _call!(treaty_instance, context:, inventory:, version:, params:)
-        treaty_instance.send(
-          :_call!,
-          context:,
-          inventory:,
-          version:,
-          params:,
-          collection_of_versions:
-        )
-      end
-    end
-  end
-end

data/lib/treaty/context/dsl.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Context
-    module DSL
-      def self.included(base)
-        base.extend(Callable)
-        base.include(Workspace)
-      end
-    end
-  end
-end

data/lib/treaty/context/workspace.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Context
-    module Workspace
-      private
-
-      def _call!(
-        context:,
-        inventory:,
-        version:,
-        params:,
-        collection_of_versions:
-      )
-        call!(
-          context:,
-          inventory:,
-          version:,
-          params:,
-          collection_of_versions:
-        )
-      end
-
-      def call!(
-        collection_of_versions:,
-        **
-      )
-        @collection_of_versions = collection_of_versions
-      end
-    end
-  end
-end

data/lib/treaty/executor/inventory.rb

@@ -1,122 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Executor
-    # Inventory wrapper that provides method-based access to inventory items.
-    #
-    # ## Purpose
-    #
-    # Wraps inventory collection and controller context, providing lazy evaluation
-    # of inventory items through method calls. This encapsulates all inventory logic
-    # within the class and provides a clean API for services.
-    #
-    # ## Usage
-    #
-    # ```ruby
-    # # Created internally by Treaty
-    # inventory = Treaty::Executor::Inventory.new(inventory_collection, controller_context)
-    #
-    # # Access via method calls - evaluates lazily
-    # inventory.posts          # => Calls controller method or evaluates proc
-    # inventory.current_user   # => Returns evaluated value
-    #
-    # # Raises exception for missing items
-    # inventory.missing_item   # => Treaty::Exceptions::Inventory
-    #
-    # # Convert to hash - evaluates all items
-    # inventory.to_h           # => { posts: [...], current_user: ... }
-    # ```
-    #
-    # ## Architecture
-    #
-    # The class encapsulates:
-    # - Inventory collection (from controller's treaty block)
-    # - Controller context (for method calls and proc evaluation)
-    # - Lazy evaluation logic (items evaluated on access)
-    #
-    # ## Error Handling
-    #
-    # If an inventory item is not found, raises `Treaty::Exceptions::Inventory` with
-    # an I18n-translated error message listing available items.
-    class Inventory
-      # Creates a new inventory instance
-      #
-      # @param inventory [Treaty::Inventory::Collection] Collection of inventory items
-      # @param context [Object] Controller instance for evaluation
-      def initialize(inventory, context)
-        @inventory = inventory
-        @context = context
-        @evaluated_cache = {}
-      end
-
-      # Provides method-based access to inventory items with lazy evaluation
-      #
-      # @param method_name [Symbol] The inventory item name
-      # @param _args [Array] Arguments (not used, for compatibility)
-      # @return [Object] The evaluated inventory item value
-      # @raise [Treaty::Exceptions::Inventory] If item not found
-      def method_missing(method_name, *_args)
-        # Check cache first
-        return @evaluated_cache[method_name] if @evaluated_cache.key?(method_name)
-
-        # Find inventory item
-        item = find_inventory_item(method_name)
-
-        # Evaluate and cache
-        @evaluated_cache[method_name] = item.evaluate(@context)
-      end
-
-      # Checks if inventory responds to a method
-      #
-      # @param method_name [Symbol] The method name to check
-      # @param include_private [Boolean] Whether to include private methods
-      # @return [Boolean] True if inventory has the item
-      def respond_to_missing?(method_name, include_private = false)
-        return false if @inventory.nil?
-
-        @inventory.names.include?(method_name) || super
-      end
-
-      # Converts inventory to hash, evaluating all items
-      #
-      # @return [Hash] Hash of all evaluated inventory items
-      def to_h
-        return {} if @inventory.nil?
-
-        @inventory.evaluate(@context)
-      end
-
-      # Returns string representation
-      #
-      # @return [String] Inventory description
-      def inspect
-        items = @inventory&.names || []
-        "#<Treaty::Executor::Inventory items=#{items.inspect}>"
-      end
-
-      private
-
-      # Finds inventory item by name
-      #
-      # @param name [Symbol] Inventory item name
-      # @return [Treaty::Inventory::Inventory] The inventory item
-      # @raise [Treaty::Exceptions::Inventory] If not found or inventory is nil
-      def find_inventory_item(name)
-        # Use find method for cleaner search
-        item = @inventory&.find { |item| item.name == name }
-
-        return item if item
-
-        # Item not found - list available items
-        available = @inventory&.names || []
-
-        raise Treaty::Exceptions::Inventory,
-              I18n.t(
-                "treaty.executor.inventory.item_not_found",
-                name:,
-                available: available.join(", ")
-              )
-      end
-    end
-  end
-end

data/lib/treaty/inventory/collection.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Inventory
-    # Collection wrapper for sets of inventory items.
-    #
-    # ## Purpose
-    #
-    # Provides a unified interface for working with collections of inventory items.
-    # Uses Ruby Set internally for uniqueness but exposes Array-like interface.
-    #
-    # ## Usage
-    #
-    # Used internally by:
-    # - Inventory::Factory (to store inventory items during DSL processing)
-    #
-    # ## Methods
-    #
-    # Delegates common collection methods to internal Set:
-    # - `<<` - Add inventory item
-    # - `empty?` - Check if collection is empty
-    #
-    # Custom methods:
-    # - `exists?` - Returns true if collection is not empty
-    # - `evaluate` - Evaluates all inventory items with context
-    #
-    # ## Example
-    #
-    #   collection = Collection.new
-    #   collection << Inventory.new(name: :posts, source: :load_posts)
-    #   collection << Inventory.new(name: :meta, source: -> { { count: 10 } })
-    #   collection.size  # => 2
-    #   collection.exists?  # => true
-    class Collection
-      extend Forwardable
-
-      def_delegators :@collection, :<<, :each_with_object, :find, :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
-
-      # Returns array of all inventory item names
-      #
-      # @return [Array<Symbol>] Array of inventory item names
-      def names
-        @collection.each_with_object([]) { |item, names| names << item.name }
-      end
-
-      # Evaluates all inventory items with the given context
-      #
-      # @param context [Object] The controller instance to call methods on
-      # @return [Hash{Symbol => Object}] Hash of inventory name => resolved value
-      def evaluate(context)
-        @collection.each_with_object({}) do |inventory_item, hash|
-          hash[inventory_item.name] = inventory_item.evaluate(context)
-        end
-      end
-    end
-  end
-end

data/lib/treaty/inventory/factory.rb

@@ -1,91 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Inventory
-    # Factory for building inventory collections via DSL.
-    #
-    # ## Purpose
-    #
-    # Provides the `provide` DSL method for defining inventory items in controller blocks.
-    # Captures calls like `provide :posts, from: :load_posts` and builds a collection.
-    #
-    # ## Usage
-    #
-    # Used internally by Controller::DSL when processing treaty blocks:
-    #
-    # ```ruby
-    # treaty :index do
-    #   provide :posts, from: :load_posts       # Explicit source
-    #   provide :meta, from: -> { { count: 10 } } # Lambda source
-    #   provide :current_user                   # Shorthand: uses :current_user as source
-    # end
-    # ```
-    #
-    # ## Valid Sources
-    #
-    # - Symbol: Method name to call on controller (e.g., `:load_posts`)
-    # - Proc/Lambda: Callable object (e.g., `-> { Post.all }`)
-    # - Direct value: String, number, or any other value (e.g., `"Welcome"`)
-    # - Omitted: Uses inventory name as source (e.g., `provide :posts` → `from: :posts`)
-    #
-    # ## Invalid Sources
-    #
-    # - Direct method calls without symbol/proc (e.g., `from: load_posts`)
-    # - Explicit nil values (e.g., `from: nil`)
-    class Factory
-      attr_reader :collection
-
-      def initialize(action_name)
-        @action_name = action_name
-        @collection = Collection.new
-      end
-
-      # Handles the `provide` DSL method via method_missing
-      #
-      # @param method_name [Symbol] Should be :provide
-      # @param args [Array] First argument is the inventory name
-      # @param options [Hash] Optional :from key with source (defaults to inventory name)
-      # @return [Collection] The collection being built
-      # @raise [Treaty::Exceptions::Inventory] For invalid method or missing parameters
-      def method_missing(method_name, *args, **options, &_block) # rubocop:disable Metrics/MethodLength
-        # Only handle 'provide' method
-        unless method_name == :provide
-          raise Treaty::Exceptions::Inventory,
-                I18n.t(
-                  "treaty.inventory.unknown_method",
-                  method: method_name,
-                  action: @action_name
-                )
-        end
-
-        # Extract inventory name
-        inventory_name = args.first
-
-        unless inventory_name.is_a?(Symbol)
-          raise Treaty::Exceptions::Inventory,
-                I18n.t(
-                  "treaty.inventory.name_must_be_symbol",
-                  name: inventory_name.inspect
-                )
-        end
-
-        # Extract source from options (default to inventory name if not provided)
-        source = if options.key?(:from)
-                   options.fetch(:from)
-                 else
-                   inventory_name
-                 end
-
-        # Create and add inventory item to collection
-        @collection << Inventory.new(name: inventory_name, source:)
-
-        # Return collection for potential chaining
-        @collection
-      end
-
-      def respond_to_missing?(method_name, *)
-        method_name == :provide || super
-      end
-    end
-  end
-end

data/lib/treaty/inventory/inventory.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Inventory
-    # Represents a single inventory item that provides data to the treaty execution.
-    #
-    # An inventory item has a name and a source. The source can be:
-    # - Symbol: A method name to call on the controller (e.g., :load_posts)
-    # - Proc/Lambda: A callable object (e.g., -> { Post.all })
-    # - Direct value: Any other value to pass directly (e.g., "text", 42)
-    #
-    # ## Usage
-    #
-    # ```ruby
-    # # In controller
-    # treaty :index do
-    #   provide :posts, from: :load_posts
-    #   provide :meta, from: -> { { count: 10 } }
-    #   provide :title, from: "Welcome"
-    # end
-    # ```
-    class Inventory
-      attr_reader :name, :source
-
-      def initialize(name:, source:)
-        validate_name!(name)
-        validate_source!(source)
-
-        @name = name
-        @source = source
-      end
-
-      # Evaluates the inventory source with the given context
-      #
-      # @param context [Object] The controller instance to call methods on
-      # @return [Object] The resolved value
-      # @raise [Treaty::Exceptions::Inventory] If evaluation fails
-      def evaluate(context) # rubocop:disable Metrics/MethodLength
-        case source
-        when Symbol
-          evaluate_symbol(context)
-        when Proc
-          evaluate_proc(context)
-        else
-          source
-        end
-      rescue StandardError => e
-        raise Treaty::Exceptions::Inventory,
-              I18n.t(
-                "treaty.inventory.evaluation_error",
-                name: @name,
-                error: e.message
-              )
-      end
-
-      private
-
-      # Evaluates Symbol source by calling method on context
-      #
-      # @param context [Object] The controller instance
-      # @return [Object] The method return value
-      def evaluate_symbol(context)
-        context.send(source)
-      end
-
-      # Evaluates Proc source within controller context
-      #
-      # @param context [Object] The controller instance
-      # @return [Object] The proc return value
-      def evaluate_proc(context)
-        # Execute proc in controller context to access instance variables and methods
-        context.instance_exec(&source)
-      end
-
-      def validate_name!(name)
-        return if name.is_a?(Symbol) && !name.to_s.empty?
-
-        raise Treaty::Exceptions::Inventory,
-              I18n.t("treaty.inventory.invalid_name", name: name.inspect)
-      end
-
-      def validate_source!(source)
-        # Source must be Symbol, Proc, or any other direct value
-        # We don't allow nil as it's likely a mistake
-        return unless source.nil?
-
-        raise Treaty::Exceptions::Inventory,
-              I18n.t("treaty.inventory.source_required")
-      end
-    end
-  end
-end

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

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Request
-    module Attribute
-      # Request-specific attribute that defaults to required: true
-      class Attribute < Treaty::Entity::Attribute::Base
-        private
-
-        def apply_defaults!
-          # For request: required by default (true).
-          # message: nil means use I18n default message from validators
-          @options[:required] ||= { is: true, message: nil }
-        end
-
-        def process_nested_attributes(&block)
-          return unless object_or_array?
-
-          builder = Builder.new(collection_of_attributes, @nesting_level + 1)
-          builder.instance_eval(&block)
-        end
-      end
-    end
-  end
-end