domainic-command 0.1.0.alpha.1.0.0 → 0.1.0

data/lib/domainic/command/context/behavior.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'domainic/command/context/attribute'
+require 'domainic/command/context/attribute_set'
+
+module Domainic
+  module Command
+    module Context
+      # A module that provides attribute management for command contexts. When included in a class, it provides
+      # a DSL for defining and managing typed attributes with validation, default values, and thread-safe access.
+      #
+      # ## Thread Safety
+      # The attribute system is designed to be thread-safe during class definition and inheritance. A class-level
+      # mutex protects the attribute registry during:
+      # * Definition of new attributes via the DSL
+      # * Inheritance of attributes to subclasses
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      module Behavior
+        # @rbs (Class | Module base) -> void
+        def self.included(base)
+          super
+          base.extend(ClassMethods)
+        end
+
+        # Provides class-level methods for defining and managing attributes. These methods are
+        # automatically extended onto any class that includes {Behavior}.
+        #
+        # @since 0.1.0
+        module ClassMethods
+          # @rbs @attributes: AttributeSet
+          # @rbs @attribute_lock: Mutex
+
+          private
+
+          # Defines a new attribute for the context.
+          #
+          # @overload attribute(name, *type_validator_and_description, **options)
+          #   @param name [String, Symbol] The name of the attribute
+          #   @param type_validator_and_description [Array<Class, Module, Object, Proc, String, nil>] Type validator or
+          #     description arguments
+          #   @param options [Hash] Configuration options for the attribute
+          #   @option options [Object] :default A static default value
+          #   @option options [Proc] :default_generator A proc that generates the default value
+          #   @option options [Object] :default_value Alias for :default
+          #   @option options [String, nil] :desc Short description of the attribute
+          #   @option options [String, nil] :description Full description of the attribute
+          #   @option options [Boolean] :required Whether the attribute is required
+          #   @option options [Class, Module, Object, Proc] :type A type validator
+          #
+          #   @return [void]
+          # @rbs (
+          #   String | Symbol name,
+          #   *(Class | Module | Object | Proc | String)? type_validator_and_description,
+          #   ?default: untyped,
+          #   ?default_generator: untyped,
+          #   ?default_value: untyped,
+          #   ?desc: String?,
+          #   ?description: String?,
+          #   ?required: bool,
+          #   ?type: Class | Module | Object | Proc
+          #   ) -> void
+          def attribute(...)
+            # @type self: Class & Behavior & ClassMethods
+            attribute = Attribute.new(...)
+            attribute_lock.synchronize { attributes.add(attribute) }
+            attr_reader attribute.name
+          end
+
+          # Returns the mutex used to synchronize attribute operations.
+          #
+          # @return [Mutex]
+          # @rbs () -> Mutex
+          def attribute_lock
+            @attribute_lock ||= Mutex.new
+          end
+
+          # Returns the set of attributes defined for this context.
+          #
+          # @return [AttributeSet]
+          # @rbs () -> AttributeSet
+          def attributes
+            @attributes ||= AttributeSet.new
+          end
+
+          # Handles inheritance of attributes to subclasses.
+          #
+          # @param subclass [Class, Module] The inheriting class
+          #
+          # @return [void]
+          # @rbs (Class | Module subclass) -> void
+          def inherited(subclass)
+            super
+            attribute_lock.synchronize do
+              subclass.instance_variable_set(:@attributes, attributes.dup)
+            end
+          end
+        end
+
+        # Initializes a new context instance with the given attributes.
+        #
+        # @param options [Hash{String, Symbol => Object}] Attribute values for initialization
+        #
+        # @raise [ArgumentError] If any attribute values are invalid
+        # @return [Behavior]
+        # @rbs (**untyped options) -> void
+        def initialize(**options)
+          options = options.transform_keys(&:to_sym)
+
+          self.class.send(:attributes).each do |attribute|
+            value = options.fetch(attribute.name) { attribute.default if attribute.default? }
+            raise ArgumentError, "Invalid value for #{attribute.name}: #{value.inspect}" unless attribute.valid?(value)
+
+            instance_variable_set(:"@#{attribute.name}", value)
+          end
+        end
+
+        # Returns a hash of all attribute names and their values.
+        #
+        # @return [Hash{Symbol => Object}] A hash of attribute values
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_hash
+          self.class.send(:attributes).each_with_object({}) do |attribute, hash|
+            hash[attribute.name] = public_send(attribute.name)
+          end
+        end
+        alias to_h to_hash
+      end
+    end
+  end
+end

data/lib/domainic/command/context/input_context.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'domainic/command/context/behavior'
+
+module Domainic
+  module Command
+    module Context
+      # A context class for managing command input arguments. This class provides a structured way to define,
+      # validate, and access input parameters for commands.
+      #
+      # @example
+      #   class MyInputContext < Domainic::Command::Context::InputContext
+      #     argument :name, String, "The name to process"
+      #     argument :count, Integer, default: 1
+      #   end
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class InputContext
+        # @rbs! extend Behavior::ClassMethods
+
+        include Behavior
+
+        # Defines an input argument for the command
+        #
+        # @overload argument(name, *type_validator_and_description, **options)
+        #   @param name [String, Symbol] The name of the argument
+        #   @param type_validator_and_description [Array<Class, Module, Object, Proc, String, nil>] Type validator or
+        #     description arguments
+        #   @param options [Hash] Configuration options for the argument
+        #   @option options [Object] :default A static default value
+        #   @option options [Proc] :default_generator A proc that generates the default value
+        #   @option options [Object] :default_value Alias for :default
+        #   @option options [String, nil] :desc Short description of the argument
+        #   @option options [String, nil] :description Full description of the argument
+        #   @option options [Boolean] :required Whether the argument is required
+        #   @option options [Class, Module, Object, Proc] :type A type validator
+        #
+        #   @return [void]
+        # @rbs (
+        #   String | Symbol name,
+        #   *(Class | Module | Object | Proc | String)? type_validator_and_description,
+        #   ?default: untyped,
+        #   ?default_generator: untyped,
+        #   ?default_value: untyped,
+        #   ?desc: String?,
+        #   ?description: String?,
+        #   ?required: bool,
+        #   ?type: Class | Module | Object | Proc
+        #   ) -> void
+        def self.argument(...) = attribute(...)
+      end
+    end
+  end
+end

data/lib/domainic/command/context/output_context.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'domainic/command/context/behavior'
+
+module Domainic
+  module Command
+    module Context
+      # A context class for managing command output values. This class provides a structured way to define,
+      # validate, and access the return values from commands.
+      #
+      # @example
+      #   class MyOutputContext < Domainic::Command::Context::OutputContext
+      #     field :processed_name, String, "The processed name"
+      #     field :status, Symbol, default: :success
+      #   end
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class OutputContext
+        # @rbs! extend Behavior::ClassMethods
+
+        include Behavior
+
+        # Defines a return value for the command
+        #
+        # @overload field(name, *type_validator_and_description, **options)
+        #   @param name [String, Symbol] The name of the return value
+        #   @param type_validator_and_description [Array<Class, Module, Object, Proc, String, nil>] Type validator or
+        #     description arguments
+        #   @param options [Hash] Configuration options for the return value
+        #   @option options [Object] :default A static default value
+        #   @option options [Proc] :default_generator A proc that generates the default value
+        #   @option options [Object] :default_value Alias for :default
+        #   @option options [String, nil] :desc Short description of the return value
+        #   @option options [String, nil] :description Full description of the return value
+        #   @option options [Boolean] :required Whether the return value is required
+        #   @option options [Class, Module, Object, Proc] :type A type validator
+        #
+        #   @return [void]
+        # @rbs (
+        #   String | Symbol name,
+        #   *(Class | Module | Object | Proc | String)? type_validator_and_description,
+        #   ?default: untyped,
+        #   ?default_generator: untyped,
+        #   ?default_value: untyped,
+        #   ?desc: String?,
+        #   ?description: String?,
+        #   ?required: bool,
+        #   ?type: Class | Module | Object | Proc
+        #   ) -> void
+        def self.field(...) = attribute(...)
+      end
+    end
+  end
+end

data/lib/domainic/command/context/runtime_context.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Command
+    module Context
+      # A flexible context class for managing command state during execution. This class provides a dynamic
+      # storage mechanism for command data, allowing both hash-style and method-style access to values.
+      #
+      # The RuntimeContext serves as a mutable workspace during command execution, bridging the gap between
+      # input parameters and output values. It automatically handles type coercion of keys to symbols and
+      # provides safe value duplication when converting to a hash.
+      #
+      # @example Hash-style access
+      #   context = RuntimeContext.new(count: 1)
+      #   context[:count] #=> 1
+      #   context[:count] = 2
+      #   context[:count] #=> 2
+      #
+      # @example Method-style access
+      #   context = RuntimeContext.new(name: "test")
+      #   context.name #=> "test"
+      #   context.name = "new test"
+      #   context.name #=> "new test"
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class RuntimeContext
+        # @rbs @data: Hash[Symbol, untyped]
+
+        # Creates a new RuntimeContext with the given options
+        #
+        # @param options [Hash] Initial values for the context
+        #
+        # @return [RuntimeContext]
+        # @rbs (**untyped options) -> void
+        def initialize(**options)
+          @data = options.transform_keys(&:to_sym)
+        end
+
+        # Retrieves a value by its attribute name
+        #
+        # @param attribute_name [String, Symbol] The name of the attribute to retrieve
+        #
+        # @return [Object, nil] The value associated with the attribute name
+        # @rbs (String | Symbol attribute_name) -> untyped
+        def [](attribute_name)
+          read_from_attribute(attribute_name)
+        end
+
+        # Sets a value for the given attribute name
+        #
+        # @param attribute_name [String, Symbol] The name of the attribute to set
+        # @param value [Object] The value to store
+        #
+        # @return [Object] The stored value
+        # @rbs (String | Symbol attribute_name, untyped value) -> untyped
+        def []=(attribute_name, value)
+          write_to_attribute(attribute_name, value)
+        end
+
+        # Converts the context to a hash, duplicating values where appropriate
+        #
+        # @note Class and Module values are not duplicated to prevent potential issues
+        #
+        # @return [Hash{Symbol => Object}] A hash containing all stored values
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_hash
+          @data.transform_values do |value|
+            value.is_a?(Class) || value.is_a?(Module) ? value : value.dup
+          end
+        end
+        alias to_h to_hash
+
+        private
+
+        # Handles dynamic method calls for reading and writing attributes
+        #
+        # @return [Object, nil]
+        # @rbs override
+        def method_missing(method_name, ...)
+          return super unless respond_to_missing?(method_name)
+
+          if method_name.to_s.end_with?('=')
+            write_to_attribute(method_name.to_s.delete_suffix('=').to_sym, ...)
+          else
+            @data[method_name]
+          end
+        end
+
+        # Reads a value from the internal storage
+        #
+        # @param attribute_name [String, Symbol] The name of the attribute to read
+        #
+        # @return [Object, nil] The stored value
+        # @rbs (String | Symbol attribute_name) -> untyped
+        def read_from_attribute(attribute_name)
+          @data[attribute_name.to_sym]
+        end
+
+        # Determines if a method name can be handled dynamically
+        #
+        # @param method_name [Symbol] The name of the method to check
+        # @param _include_private [Boolean] Whether to include private methods
+        #
+        # @return [Boolean] Whether the method can be handled
+        # @rbs (String | Symbol method_name, ?bool _include_private) -> bool
+        def respond_to_missing?(method_name, _include_private = false)
+          return true if method_name.to_s.end_with?('=')
+          return true if @data.key?(method_name.to_sym)
+
+          super
+        end
+
+        # Writes a value to the internal storage
+        #
+        # @param attribute_name [String, Symbol] The name of the attribute to write
+        # @param value [Object] The value to store
+        # @return [Object] The stored value
+        # @rbs (String | Symbol attribute_name, untyped value) -> untyped
+        def write_to_attribute(attribute_name, value)
+          @data[attribute_name.to_sym] = value
+        end
+      end
+    end
+  end
+end

data/lib/domainic/command/errors/error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Command
+    # Base error class for command-related errors. This class serves as the root of the command error
+    # hierarchy, allowing for specific error handling of command-related issues.
+    #
+    # @note This is an abstract class and should not be instantiated directly. Instead, use one of its
+    #   subclasses for specific error cases.
+    #
+    # @example Rescuing command errors
+    #   begin
+    #     # Command execution code
+    #   rescue Domainic::Command::Error => e
+    #     # Handle any command-related error
+    #   end
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    class Error < StandardError
+    end
+  end
+end

data/lib/domainic/command/errors/execution_error.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'domainic/command/errors/error'
+
+module Domainic
+  module Command
+    # Error class raised when a command encounters an execution failure. This class provides access to
+    # both the error message and the {Result} object containing detailed information about the failure.
+    #
+    # @example Handling execution errors
+    #   begin
+    #     command.call!
+    #   rescue Domainic::Command::ExecutionError => e
+    #     puts e.message           # Access the error message
+    #     puts e.result.errors     # Access the detailed errors
+    #     puts e.result.status_code # Access the status code
+    #   end
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    class ExecutionError < Error
+      # The {Result} object containing detailed information about the execution failure
+      #
+      # @return [Result] The result object associated with the failure
+      attr_reader :result #: Result
+
+      # Creates a new execution error with the given message and result
+      #
+      # @param message [String] The error message describing what went wrong
+      # @param result [Result] The result object containing detailed failure information
+      #
+      # @return [void]
+      # @rbs (String message, Result result) -> void
+      def initialize(message, result)
+        @result = result
+        super(message)
+      end
+    end
+  end
+end

data/lib/domainic/command/instance_methods.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'domainic/command/errors/execution_error'
+require 'domainic/command/result'
+
+module Domainic
+  module Command
+    # Instance methods that are included in any class that includes {Command}. These methods provide
+    # the core execution logic and error handling for commands.
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    module InstanceMethods
+      # Executes the command with the given context, handling any errors
+      #
+      # @param context [Hash] The input context for the command
+      #
+      # @return [Result] The result of the command execution
+      # @rbs (**untyped context) -> Result
+      def call(**context)
+        call!(**context)
+      rescue ExecutionError => e
+        e.result
+      end
+
+      # Executes the command with the given context, raising any errors
+      #
+      # @param input [Hash] The input context for the command
+      #
+      # @raise [ExecutionError] If the command execution fails
+      # @return [Result] The result of the command execution
+      # @rbs (**untyped context) -> Result
+      def call!(**input)
+        __execute_command!(input)
+      rescue StandardError => e
+        raise e if e.is_a?(ExecutionError)
+
+        raise ExecutionError.new("#{self.class} failed", Result.failure(e, context.to_h))
+      end
+
+      # Executes the command's business logic
+      #
+      # @abstract Subclass and override {#execute} to implement command behavior
+      #
+      # @raise [NotImplementedError] If the subclass does not implement {#execute}
+      # @return [void]
+      # @rbs () -> void
+      def execute
+        raise NotImplementedError, "#{self.class} does not implement #execute"
+      end
+
+      private
+
+      # The runtime context for the command execution
+      #
+      # @return [Context::RuntimeContext] The runtime context
+      attr_reader :context #: Context::RuntimeContext
+
+      # Execute the command with the given input context
+      #
+      # @param input [Hash] The input context for the command
+      #
+      # @return [Result] The result of the command execution
+      # @rbs (Hash[String | Symbol, untyped] input) -> Result
+      def __execute_command!(input)
+        input_context = __validate_context!(:input, input)
+        @context = self.class.send(:runtime_context_class).new(**input_context.to_h)
+        execute
+        output_context = __validate_context!(:output, context.to_h)
+        Result.success(output_context.to_h)
+      end
+
+      # Validates an input or output context
+      #
+      # @param context_type [Symbol] The type of context to validate
+      # @param context [Hash] The context data to validate
+      #
+      # @raise [ExecutionError] If the context is invalid
+      # @return [Context::InputContext, Context::OutputContext] The validated context
+      # @rbs (
+      #   :input | :output context_type,
+      #   Hash[String | Symbol, untyped] context
+      #   ) -> (Context::InputContext | Context::OutputContext)
+      def __validate_context!(context_type, context)
+        self.class.send(:"#{context_type}_context_class").new(**context)
+      rescue StandardError => e
+        result = context_type == :input ? Result.failure_at_input(e) : Result.failure_at_output(e)
+        raise ExecutionError.new("#{self.class} has invalid #{context_type}", result)
+      end
+    end
+  end
+end