domainic-command 0.1.0.alpha.1.0.0 → 0.1.0

data/sig/domainic/command/context/attribute.rbs

@@ -0,0 +1,104 @@
+module Domainic
+  module Command
+    module Context
+      # Represents an attribute within a command context. This class manages the lifecycle of an attribute, including
+      # its validation, default values, and metadata such as descriptions
+      #
+      # The `Attribute` class supports a variety of configuration options, such as marking an attribute as required,
+      # defining static or dynamic default values, and specifying custom validators. These features ensure that
+      # attributes conform to expected rules and provide useful metadata for documentation or runtime behavior
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class Attribute
+        # Represents an undefined default value for an attribute. This is used internally to distinguish between
+        # an attribute with no default and one with a defined default
+        #
+        # @return [Object] A frozen object representing an undefined default value
+        UNDEFINED_DEFAULT: Object
+
+        @type_validator: Class | Module | Object | Proc
+
+        @default: untyped
+
+        @description: String?
+
+        @name: Symbol
+
+        @required: bool
+
+        # The textual description of the attribute, providing metadata about its purpose or usage
+        #
+        # @return [String, nil] A description of the attribute
+        attr_reader description: String?
+
+        # The name of the attribute, uniquely identifying it within a command context
+        #
+        # @return [Symbol] The name of the attribute
+        attr_reader name: Symbol
+
+        # Create a new attribute instance
+        #
+        # @overload initialize(
+        #   name, type_validator_or_description = nil, description_or_type_validator = nil, **options
+        #   )
+        #   @param name [String, Symbol] The {#name} of the attribute
+        #   @param type_validator_or_description [Class, Module, Object, Proc, String, nil] A type validator or the
+        #     {#description} of the attribute
+        #   @param description_or_type_validator [Class, Module, Object, Proc, String, nil] The {#description} or a
+        #     type_validator of the attribute
+        #   @param options [Hash] Configuration options for the attribute
+        #   @option options [Object] :default The {#default} of the attribute
+        #   @option options [Proc] :default_generator An alias for :default
+        #   @option options [Object] :default_value An alias for :default
+        #   @option options [String, nil] :desc An alias for :description
+        #   @option options [String, nil] :description The {#description} of the attribute
+        #   @option options [Boolean] :required Whether the attribute is {#required?}
+        #   @option options [Class, Module, Object, Proc] :type A type validator for the attribute value
+        #
+        #   @return [Attribute] the new Attribute instance
+        def initialize: (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
+
+        # Retrieves the default value of the attribute. If a default generator is specified, it evaluates the generator
+        # and returns the result
+        #
+        # @return [Object, nil] The default value or the result of the generator
+        def default: () -> untyped
+
+        # Determines whether the attribute has a default value defined
+        #
+        # @return [Boolean] `true` if a default is set; otherwise, `false`
+        def default?: () -> bool
+
+        # Determines whether the attribute is marked as required
+        #
+        # @return [Boolean] `true` if the attribute is required; otherwise, `false`
+        def required?: () -> bool
+
+        # Validates the given value against the attribute's type validator
+        #
+        # @param value [Object] The value to validate
+        #
+        # @return [Boolean] `true` if the value is valid; otherwise, `false`
+        def valid?: (untyped value) -> bool
+
+        private
+
+        # Initializes the {#default} value for the attribute, using the provided options
+        #
+        # @param options [Hash] Configuration options containing default-related keys
+        #
+        # @return [void]
+        def initialize_default: (Hash[Symbol, untyped] options) -> void
+
+        # Initializes the description and type validator for the attribute based on the given arguments and options
+        #
+        # @param arguments [Array<Class, Module, Object, Proc, String, nil>] Arguments for validators or description
+        # @param options [Hash] Configuration options
+        #
+        # @return [void]
+        def initialize_description_and_type_validator: (Array[(Class | Module | Object | Proc | String)?] arguments, Hash[Symbol, untyped] options) -> void
+      end
+    end
+  end
+end

data/sig/domainic/command/context/attribute_set.rbs

@@ -0,0 +1,69 @@
+module Domainic
+  module Command
+    module Context
+      # A collection class for managing a set of command context attributes. This class provides a simple interface
+      # for storing, accessing, and iterating over {Attribute} instances.
+      #
+      # @example
+      #   set = AttributeSet.new
+      #   set.add(Attribute.new(:name))
+      #   set[:name] # => #<Attribute name=:name>
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class AttributeSet
+        @lookup: Hash[Symbol, Attribute]
+
+        # Creates a new AttributeSet instance
+        #
+        # @return [AttributeSet]
+        def initialize: () -> void
+
+        # Retrieves an attribute by name
+        #
+        # @param attribute_name [String, Symbol] The name of the attribute to retrieve
+        #
+        # @return [Attribute, nil] The attribute with the given name, or nil if not found
+        def []: (String | Symbol attribute_name) -> Attribute?
+
+        # Adds an attribute to the set
+        #
+        # @param attribute [Attribute] The attribute to add
+        #
+        # @raise [ArgumentError] If the provided attribute is not an {Attribute} instance
+        # @return [void]
+        def add: (Attribute attribute) -> void
+
+        # Returns all attributes in the set
+        #
+        # @return [Array<Attribute>] An array of all attributes
+        def all: () -> Array[Attribute]
+
+        # Iterates over each attribute in the set
+        #
+        # @yield [Attribute] Each attribute in the set
+        #
+        # @return [void]
+        def each: () { (Attribute) -> untyped } -> void
+
+        # Iterates over each attribute in the set with an object
+        #
+        # @overload each_with_object(object)
+        #   @param object [Object] The object to pass to the block
+        #   @yield [Attribute, Object] Each attribute and the object
+        #
+        #   @return [Object] The final state of the object
+        def each_with_object: [U] (U object) { (Attribute, U) -> untyped } -> U
+
+        private
+
+        # Ensure that Attributes are duplicated when the AttributeSet is duplicated
+        #
+        # @param source [AttributeSet] The source AttributeSet to copy
+        #
+        # @return [AttributeSet]
+        def initialize_copy: (untyped source) -> untyped
+      end
+    end
+  end
+end

data/sig/domainic/command/context/behavior.rbs

@@ -0,0 +1,82 @@
+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
+        def self.included: (Class | Module base) -> void
+
+        # 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
+          @attributes: AttributeSet
+
+          @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]
+          def attribute: (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
+
+          # Returns the mutex used to synchronize attribute operations.
+          #
+          # @return [Mutex]
+          def attribute_lock: () -> Mutex
+
+          # Returns the set of attributes defined for this context.
+          #
+          # @return [AttributeSet]
+          def attributes: () -> AttributeSet
+
+          # Handles inheritance of attributes to subclasses.
+          #
+          # @param subclass [Class, Module] The inheriting class
+          #
+          # @return [void]
+          def inherited: (Class | Module subclass) -> void
+        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]
+        def initialize: (**untyped options) -> void
+
+        # Returns a hash of all attribute names and their values.
+        #
+        # @return [Hash{Symbol => Object}] A hash of attribute values
+        def to_hash: () -> Hash[Symbol, untyped]
+
+        alias to_h to_hash
+      end
+    end
+  end
+end

data/sig/domainic/command/context/input_context.rbs

@@ -0,0 +1,40 @@
+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
+        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]
+        def self.argument: (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
+      end
+    end
+  end
+end

data/sig/domainic/command/context/output_context.rbs

@@ -0,0 +1,40 @@
+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
+        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]
+        def self.field: (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
+      end
+    end
+  end
+end

data/sig/domainic/command/context/runtime_context.rbs

@@ -0,0 +1,90 @@
+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
+        @data: Hash[Symbol, untyped]
+
+        # Creates a new RuntimeContext with the given options
+        #
+        # @param options [Hash] Initial values for the context
+        #
+        # @return [RuntimeContext]
+        def initialize: (**untyped options) -> void
+
+        # 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
+        def []: (String | Symbol attribute_name) -> untyped
+
+        # 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
+        def []=: (String | Symbol attribute_name, untyped value) -> untyped
+
+        # 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
+        def to_hash: () -> Hash[Symbol, untyped]
+
+        alias to_h to_hash
+
+        private
+
+        # Handles dynamic method calls for reading and writing attributes
+        #
+        # @return [Object, nil]
+        def method_missing: ...
+
+        # 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
+        def read_from_attribute: (String | Symbol attribute_name) -> untyped
+
+        # 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
+        def respond_to_missing?: (String | Symbol method_name, ?bool _include_private) -> bool
+
+        # 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
+        def write_to_attribute: (String | Symbol attribute_name, untyped value) -> untyped
+      end
+    end
+  end
+end

data/sig/domainic/command/errors/error.rbs

@@ -0,0 +1,21 @@
+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/sig/domainic/command/errors/execution_error.rbs

@@ -0,0 +1,32 @@
+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]
+      def initialize: (String message, Result result) -> void
+    end
+  end
+end

data/sig/domainic/command/instance_methods.rbs

@@ -0,0 +1,56 @@
+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
+      def call: (**untyped context) -> Result
+
+      # 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
+      def call!: (**untyped context) -> Result
+
+      # 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]
+      def execute: () -> void
+
+      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
+      def __execute_command!: (Hash[String | Symbol, untyped] input) -> Result
+
+      # 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
+      def __validate_context!: (:input | :output context_type, Hash[String | Symbol, untyped] context) -> (Context::InputContext | Context::OutputContext)
+    end
+  end
+end