domainic-command 0.1.0.alpha.1.0.0 → 0.1.0

data/lib/domainic/command/result/error_set.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Command
+    class Result
+      # A flexible container for managing and formatting command errors. The ErrorSet provides a consistent
+      # interface for working with errors from various sources including simple strings, arrays, hashes,
+      # standard errors, and objects implementing a compatible `to_h` interface (like ActiveModel::Errors).
+      #
+      # @example Basic usage
+      #   errors = ErrorSet.new("Something went wrong")
+      #   errors[:generic] #=> ["Something went wrong"]
+      #   errors.full_messages #=> ["generic Something went wrong"]
+      #
+      # @example Hash-style errors
+      #   errors = ErrorSet.new(
+      #     name: "can't be blank",
+      #     email: ["invalid format", "already taken"]
+      #   )
+      #   errors[:name] #=> ["can't be blank"]
+      #   errors[:email] #=> ["invalid format", "already taken"]
+      #
+      # @example ActiveModel compatibility
+      #   user = User.new
+      #   user.valid? #=> false
+      #   errors = ErrorSet.new(user.errors)
+      #   errors[:email] #=> ["can't be blank"]
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class ErrorSet
+        # @rbs @lookup: Hash[Symbol, Array[String]]
+
+        # Creates a new ErrorSet instance
+        #
+        # @param errors [String, Array, Hash, StandardError, #to_h, nil] The errors to parse
+        #
+        # @raise [ArgumentError] If the errors cannot be parsed
+        # @return [ErrorSet] the new ErrorSet instance
+        # @rbs (?untyped? errors) -> void
+        def initialize(errors = nil)
+          @lookup = Parser.new(errors).parse!
+        end
+
+        # Retrieves error messages for a specific key
+        #
+        # @param key [String, Symbol] The error key to lookup
+        # @return [Array<String>, nil] The error messages for the key
+        # @rbs (String | Symbol key) -> Array[String]?
+        def [](key)
+          @lookup[key.to_sym]
+        end
+
+        # Adds a new error message for a specific key
+        #
+        # @param key [String, Symbol] The error key
+        # @param message [String, Array<String>] The error message(s)
+        #
+        # @return [void]
+        # @rbs (String | Symbol key, Array[String] | String message) -> void
+        def add(key, message)
+          key = key.to_sym
+          @lookup[key] ||= []
+          @lookup[key].concat(Array(message)) # steep:ignore ArgumentTypeMismatch
+        end
+
+        # Clear all errors from the set
+        #
+        # @return [void]
+        # @rbs () -> void
+        def clear
+          @lookup = {}
+        end
+
+        # Check if the error set is empty
+        #
+        # @return [Boolean] `true` if the error set is empty, `false` otherwise
+        # @rbs () -> bool
+        def empty?
+          @lookup.empty?
+        end
+
+        # Returns all error messages with their keys
+        #
+        # @return [Array<String>] All error messages prefixed with their keys
+        # @rbs () -> Array[String]
+        def full_messages
+          @lookup.each_with_object([]) do |(key, messages), result|
+            result.concat(messages.map { |message| "#{key} #{message}" })
+          end
+        end
+        alias to_a full_messages
+        alias to_array full_messages
+        alias to_ary full_messages
+
+        # Returns a hash of all error messages
+        #
+        # @return [Hash{Symbol => Array<String>}] All error messages grouped by key
+        # @rbs () -> Hash[Symbol, Array[String]]
+        def messages
+          @lookup.dup.freeze
+        end
+        alias to_h messages
+        alias to_hash messages
+
+        # A utility class for parsing various error formats into a consistent structure
+        #
+        # @!visibility private
+        # @api private
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.1.0
+        class Parser
+          # Mapping of classes to their parsing strategy methods
+          #
+          # @return [Hash{Class, Module => Symbol}]
+          TYPE_STRATEGIES = {
+            Array => :parse_array,
+            Hash => :parse_hash,
+            String => :parse_generic_error,
+            StandardError => :parse_standard_error
+          }.freeze #: Hash[Class | Module, Symbol]
+
+          # Mapping of method names to their parsing strategy methods
+          #
+          # @return [Hash{Symbol => Symbol}]
+          RESPOND_TO_STRATEGIES = { to_h: :parse_to_h }.freeze #: Hash[Symbol, Symbol]
+
+          # Create a new Parser instance
+          #
+          # @param errors [Object] the errors to parse
+          #
+          # @return [Parser] the new Parser instance
+          # @rbs (untyped errors) -> void
+          def initialize(errors)
+            @errors = errors
+            @parsed = {}
+          end
+
+          # Parses the errors into a consistent format
+          #
+          # @raise [ArgumentError] If the errors cannot be parsed
+          # @return [Hash{Symbol => Array<String>}]
+          # @rbs () -> Hash[Symbol, Array[String]]
+          def parse!
+            parse_errors!
+            @parsed.transform_values { |errors| Array(errors) }
+          end
+
+          private
+
+          # Parses an array of errors into the generic error category
+          #
+          # @param errors [Array<String, StandardError>] Array of errors to parse
+          #
+          # @raise [ArgumentError] If any array element is not a String or StandardError
+          # @return [void]
+          # @rbs (Array[String | StandardError] errors) -> void
+          def parse_array(errors)
+            errors.each do |error|
+              case error
+              when String then parse_generic_error(error)
+              when StandardError then parse_standard_error(error)
+              else raise_invalid_errors!
+              end
+            end
+          end
+
+          # Determines the appropriate parsing strategy and executes it
+          #
+          # @raise [ArgumentError] If no valid parsing strategy is found
+          # @return [void]
+          # @rbs () -> void
+          def parse_errors!
+            return if @errors.nil?
+
+            TYPE_STRATEGIES.each_pair { |type, strategy| return send(strategy, @errors) if @errors.is_a?(type) }
+
+            RESPOND_TO_STRATEGIES.each_pair do |method, strategy|
+              return send(strategy, @errors) if @errors.respond_to?(method)
+            end
+
+            raise_invalid_errors!
+          end
+
+          # Parses a string or array of strings into the generic error category
+          #
+          # @param errors [String, Array<String>] The error(s) to parse
+          #
+          # @return [void]
+          # @rbs (Array[String] | String errors) -> void
+          def parse_generic_error(errors)
+            @parsed[:generic] ||= []
+            @parsed[:generic].concat(Array(errors))
+          end
+
+          # Parses a hash of errors into categorized messages
+          #
+          # @param errors [Hash{String, Symbol => Array<String>, String}] Hash of errors
+          #
+          # @raise [ArgumentError] If any value cannot be parsed
+          # @return [void]
+          # @rbs (Hash[String | Symbol, Array[StandardError] | Array[String] | StandardError | String] errors) -> void
+          def parse_hash(errors)
+            @parsed.merge!(errors.transform_keys(&:to_sym).transform_values { |value| parse_hash_value(value) })
+          end
+
+          # Parses a single value from a hash array
+          #
+          # @param value [String, StandardError] The value to parse
+          #
+          # @raise [ArgumentError] If the value is neither a String nor StandardError
+          # @return [String] The parsed error message
+          # @rbs (String | StandardError value) -> String
+          def parse_hash_array_value(value)
+            case value
+            when String then value
+            when StandardError then value.message
+            else raise_invalid_errors!
+            end
+          end
+
+          # Parses a value from a hash of errors
+          #
+          # @param value [String, StandardError, Array<String, StandardError>] The value to parse
+          #
+          # @raise [ArgumentError] If the value cannot be parsed
+          # @return [Array<String>] The parsed error message(s)
+          # @rbs (String | StandardError | Array[String | StandardError] value) -> Array[String]
+          def parse_hash_value(value)
+            case value
+            when String then [value]
+            when StandardError then [value.message]
+            when Array then value.map { |array_value| parse_hash_array_value(array_value) }
+            else raise_invalid_errors!
+            end
+          end
+
+          # Parses a StandardError into the generic error category
+          #
+          # @param errors [StandardError] The error to parse
+          #
+          # @return [void]
+          # @rbs (StandardError errors) -> void
+          def parse_standard_error(errors)
+            parse_generic_error(errors.message)
+          end
+
+          # Parses an object that responds to to_h
+          #
+          # @param errors [#to_h] The object to parse
+          #
+          # @raise [ArgumentError] If the hash cannot be parsed
+          # @return [void]
+          # @rbs (untyped errors) -> void
+          def parse_to_h(errors)
+            parse_hash(errors.to_h)
+          end
+
+          # Raises an invalid errors exception
+          #
+          # @raise [ArgumentError] Always raises with an invalid errors message
+          # @return [void]
+          # @rbs () -> void
+          def raise_invalid_errors!
+            raise ArgumentError, "invalid errors: #{@errors}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/domainic/command/result/status.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Command
+    class Result
+      # Defines status codes for command execution results. These codes follow Unix exit code conventions,
+      # making them suitable for CLI applications while remaining useful for other contexts.
+      #
+      # The status codes are specifically chosen to provide meaningful feedback about where in the command
+      # lifecycle a failure occurred:
+      # * 0 (SUCCESS) - The command completed successfully
+      # * 1 (FAILED_AT_RUNTIME) - The command failed during execution
+      # * 2 (FAILED_AT_INPUT) - The command failed during input validation
+      # * 3 (FAILED_AT_OUTPUT) - The command failed during output validation
+      #
+      # @example Using with CLI
+      #   class MyCLI
+      #     def self.run
+      #       result = MyCommand.call(args)
+      #       exit(result.status_code)
+      #     end
+      #   end
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      module STATUS
+        # Indicates successful command execution
+        #
+        # @return [Integer] status code 0
+        SUCCESS = 0 #: Integer
+
+        # Indicates a failure during command execution
+        #
+        # @return [Integer] status code 1
+        FAILED_AT_RUNTIME = 1 #: Integer
+
+        # Indicates a failure during input validation
+        #
+        # @return [Integer] status code 2
+        FAILED_AT_INPUT = 2 #: Integer
+
+        # Indicates a failure during output validation
+        #
+        # @return [Integer] status code 3
+        FAILED_AT_OUTPUT = 3 #: Integer
+      end
+    end
+  end
+end

data/lib/domainic/command/result.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'domainic/command/result/error_set'
+require 'domainic/command/result/status'
+
+module Domainic
+  module Command
+    # A value object representing the outcome of a command execution. The Result class provides
+    # a consistent interface for handling both successful and failed command executions, including
+    # return data and error information.
+    #
+    # Results are created through factory methods rather than direct instantiation, making the
+    # intent of the result clear:
+    #
+    # @example Creating a success result
+    #   result = Result.success(value: 42)
+    #   result.successful? #=> true
+    #   result.value #=> 42
+    #
+    # @example Creating a failure result
+    #   result = Result.failure_at_input(
+    #     { name: "can't be blank" },
+    #     context: { attempted_name: nil }
+    #   )
+    #   result.failure? #=> true
+    #   result.errors[:name] #=> ["can't be blank"]
+    #
+    # Results use status codes that align with Unix exit codes, making them suitable for
+    # CLI applications:
+    # * 0 - Successful execution
+    # * 1 - Runtime failure
+    # * 2 - Input validation failure
+    # * 3 - Output validation failure
+    #
+    # @example CLI usage
+    #   def self.run
+    #     result = MyCommand.call(args)
+    #     puts result.errors.full_messages if result.failure?
+    #     exit(result.status_code)
+    #   end
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    class Result
+      # @rbs @data: Struct
+      # @rbs @errors: ErrorSet
+      # @rbs @status_code: Integer
+
+      # The structured data returned by the command
+      #
+      # @return [Struct] A frozen struct containing the command's output data
+      attr_reader :data #: Struct
+
+      # The errors that occurred during command execution
+      #
+      # @return [ErrorSet] The set of errors from the command
+      attr_reader :errors #: ErrorSet
+
+      # The status code indicating the result of the command execution
+      #
+      # @return [Integer] The status code (0 for success, non-zero for failures)
+      attr_reader :status_code #: Integer
+
+      # Creates a new failure result with the given status
+      #
+      # @param errors [Object] The errors that caused the failure
+      # @param context [Hash] Optional context data for the failure
+      # @param status [Integer] The status code for the failure (defaults to FAILED_AT_RUNTIME)
+      #
+      # @return [Result] A new failure result
+      # @rbs (untyped errors, ?Hash[String | Symbol, untyped] context, ?status: Integer) -> Result
+      def self.failure(errors, context = {}, status: STATUS::FAILED_AT_RUNTIME)
+        new(status, context:, errors:)
+      end
+
+      # Creates a new input validation failure result
+      #
+      # @param errors [Object] The validation errors
+      # @param context [Hash] Optional context data for the failure
+      #
+      # @return [Result] A new input validation failure result
+      # @rbs (untyped errors, ?Hash[String | Symbol, untyped] context) -> Result
+      def self.failure_at_input(errors, context = {})
+        new(STATUS::FAILED_AT_INPUT, context:, errors:)
+      end
+
+      # Creates a new output validation failure result
+      #
+      # @param errors [Object] The validation errors
+      # @param context [Hash] Optional context data for the failure
+      #
+      # @return [Result] A new output validation failure result
+      # @rbs (untyped errors, ?Hash[String | Symbol, untyped] context) -> Result
+      def self.failure_at_output(errors, context = {})
+        new(STATUS::FAILED_AT_OUTPUT, context:, errors:)
+      end
+
+      # Creates a new success result
+      #
+      # @param context [Hash] The successful result data
+      #
+      # @return [Result] A new success result
+      # @rbs (Hash[String | Symbol, untyped] context) -> Result
+      def self.success(context)
+        new(STATUS::SUCCESS, context:)
+      end
+
+      # Creates a new result instance
+      #
+      # @param status_code [Integer] The status code for the result
+      # @param context [Hash] The data context for the result
+      # @param errors [Object, nil] Any errors that occurred
+      #
+      # @raise [ArgumentError] If status_code is invalid or context is not a Hash
+      # @return [void]
+      # @rbs (Integer status, ?context: Hash[String | Symbol, untyped], ?errors: untyped) -> void
+      def initialize(status_code, context: {}, errors: nil)
+        initialize_status_code(status_code)
+        initialize_data(context)
+        @errors = ErrorSet.new(errors)
+      end
+      private_class_method :new
+
+      # Indicates whether the command failed
+      #
+      # @return [Boolean] true if the command failed; false otherwise
+      # @rbs () -> bool
+      def failure?
+        status_code != STATUS::SUCCESS
+      end
+      alias failed? failure?
+
+      # Indicates whether the command succeeded
+      #
+      # @return [Boolean] true if the command succeeded; false otherwise
+      # @rbs () -> bool
+      def successful?
+        status_code == STATUS::SUCCESS
+      end
+      alias success? successful?
+
+      private
+
+      # Initializes the data struct from the context hash
+      #
+      # @param context [Hash] The context hash to convert to a struct
+      # @raise [ArgumentError] If context is not a Hash
+      # @return [void]
+      def initialize_data(context)
+        raise ArgumentError, ':context must be a Hash' unless context.is_a?(Hash)
+
+        context = context.transform_keys(&:to_sym)
+        @data = Struct.new(nil).new.freeze if context.empty?
+        @data = Struct.new(*context.keys, keyword_init: true).new(**context).freeze unless context.empty?
+      end
+
+      # Validates and initializes the status code
+      #
+      # @param status_code [Integer] The status code to validate
+      # @raise [ArgumentError] If the status code is not valid
+      # @return [void]
+      def initialize_status_code(status_code)
+        unless STATUS.constants.map { |c| STATUS.const_get(c) }.include?(status_code)
+          raise ArgumentError, "invalid status code: #{status_code}"
+        end
+
+        @status_code = status_code
+      end
+
+      # Delegate method calls to the data struct
+      #
+      # @param method_name [String, Symbol] The method name to call
+      #
+      # @return [Object] The result of the method call
+      # @rbs override
+      def method_missing(method_name, ...)
+        return super unless respond_to_missing?(method_name)
+
+        data.public_send(method_name.to_sym)
+      end
+
+      # Indicates whether the data struct responds to the given method
+      #
+      # @param method_name [String, Symbol] The method name to check
+      # @param _include_private [Boolean] Whether to include private methods
+      #
+      # @return [Boolean] `true` if the data struct responds to the method; `false` otherwise
+      # @rbs (String | Symbol method_name, ?bool include_private) -> bool
+      def respond_to_missing?(method_name, _include_private = false)
+        data.respond_to?(method_name.to_sym) || super
+      end
+    end
+  end
+end

data/lib/domainic/command.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'domainic/command/class_methods'
+require 'domainic/command/instance_methods'
+
+module Domainic
+  # A module that implements the Command pattern, providing a structured way to encapsulate business operations.
+  # Commands are single-purpose objects that perform a specific action, validating their inputs and outputs while
+  # maintaining a consistent interface for error handling and result reporting.
+  #
+  # @abstract Including classes must implement an {#execute} method that defines the command's business logic.
+  #   The {#execute} method has access to validated inputs via the {#context} accessor and should set any output values
+  #   on the context before returning.
+  #
+  # @example Basic command definition
+  #   class CreateUser
+  #     include Domainic::Command
+  #
+  #     argument :login, String, "The user's login", required: true
+  #     argument :password, String, "The user's password", required: true
+  #
+  #     output :user, User, "The created user", required: true
+  #     output :created_at, Time, "When the user was created"
+  #
+  #     def execute
+  #       user = User.create!(login: context.login, password: context.password)
+  #       context.user = user
+  #       context.created_at = Time.current
+  #     end
+  #   end
+  #
+  # @example Using external context classes
+  #   class CreateUserInput < Domainic::Command::Context::InputContext
+  #     argument :login, String, "The user's login", required: true
+  #     argument :password, String, "The user's password", required: true
+  #   end
+  #
+  #   class CreateUserOutput < Domainic::Command::Context::OutputContext
+  #     field :user, User, "The created user", required: true
+  #     field :created_at, Time, "When the user was created"
+  #   end
+  #
+  #   class CreateUser
+  #     include Domainic::Command
+  #
+  #     accepts_arguments_matching CreateUserInput
+  #     returns_output_matching CreateUserOutput
+  #
+  #     def execute
+  #       user = User.create!(login: context.login, password: context.password)
+  #       context.user = user
+  #       context.created_at = Time.current
+  #     end
+  #   end
+  #
+  # @example Command usage
+  #   # Successful execution
+  #   result = CreateUser.call(login: "user@example.com", password: "secret123")
+  #   result.successful? #=> true
+  #   result.user #=> #<User id: 1, login: "user@example.com">
+  #
+  #   # Failed execution
+  #   result = CreateUser.call(login: "invalid")
+  #   result.failure? #=> true
+  #   result.errors[:password] #=> ["is required"]
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since 0.1.0
+  module Command
+    # @rbs override
+    def self.included(base)
+      super
+      base.include(InstanceMethods)
+      base.extend(ClassMethods)
+    end
+  end
+end

data/lib/domainic-command.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'domainic/command'

data/sig/domainic/command/class_methods.rbs

@@ -0,0 +1,100 @@
+module Domainic
+  module Command
+    # Class methods that are extended onto any class that includes {Command}. These methods provide
+    # the DSL for defining command inputs and outputs, as well as class-level execution methods.
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    module ClassMethods
+      @input_context_class: singleton(Context::InputContext)
+
+      @runtime_context_class: singleton(Context::RuntimeContext)
+
+      @output_context_class: singleton(Context::OutputContext)
+
+      # Specifies an external input context class for the command
+      #
+      # @param input_context_class [Class] A subclass of {Context::InputContext}
+      #
+      # @raise [ArgumentError] If the provided class is not a subclass of {Context::InputContext}
+      # @return [void]
+      def accepts_arguments_matching: (singleton(Context::InputContext) input_context_class) -> void
+
+      # 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 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
+
+      # 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 context [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
+
+      # Defines an output field for the command
+      #
+      # @overload output(name, *type_validator_and_description, **options)
+      #   @param name [String, Symbol] The name of the output field
+      #   @param type_validator_and_description [Array<Class, Module, Object, Proc, String, nil>] Type validator or
+      #     description arguments
+      #   @param options [Hash] Configuration options for the output
+      #   @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 output
+      #   @option options [String, nil] :description Full description of the output
+      #   @option options [Boolean] :required Whether the output is required
+      #   @option options [Class, Module, Object, Proc] :type A type validator
+      #
+      # @return [void]
+      def output: (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
+
+      # Specifies an external output context class for the command
+      #
+      # @param output_context_class [Class] A subclass of {Context::OutputContext}
+      #
+      # @raise [ArgumentError] If the provided class is not a subclass of {Context::OutputContext}
+      # @return [void]
+      def returns_data_matching: (singleton(Context::OutputContext) output_context_class) -> void
+
+      private
+
+      # Returns the input context class for the command
+      #
+      # @return [Class] A subclass of {Context::InputContext}
+      def input_context_class: () -> singleton(Context::InputContext)
+
+      # Returns the output context class for the command
+      #
+      # @return [Class] A subclass of {Context::OutputContext}
+      def output_context_class: () -> singleton(Context::OutputContext)
+
+      # Returns the runtime context class for the command
+      #
+      # @return [Class] A subclass of {Context::RuntimeContext}
+      def runtime_context_class: () -> singleton(Context::RuntimeContext)
+    end
+  end
+end