domainic-command 0.1.0.alpha.1.0.0 → 0.1.0

data/sig/domainic/command/result/error_set.rbs

@@ -0,0 +1,186 @@
+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
+        @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
+        def initialize: (?untyped? errors) -> void
+
+        # 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
+        def []: (String | Symbol key) -> Array[String]?
+
+        # 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]
+        def add: (String | Symbol key, Array[String] | String message) -> void
+
+        # Clear all errors from the set
+        #
+        # @return [void]
+        def clear: () -> void
+
+        # Check if the error set is empty
+        #
+        # @return [Boolean] `true` if the error set is empty, `false` otherwise
+        def empty?: () -> bool
+
+        # Returns all error messages with their keys
+        #
+        # @return [Array<String>] All error messages prefixed with their keys
+        def full_messages: () -> Array[String]
+
+        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
+        def messages: () -> Hash[Symbol, Array[String]]
+
+        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: Hash[Class | Module, Symbol]
+
+          # Mapping of method names to their parsing strategy methods
+          #
+          # @return [Hash{Symbol => Symbol}]
+          RESPOND_TO_STRATEGIES: Hash[Symbol, Symbol]
+
+          # Create a new Parser instance
+          #
+          # @param errors [Object] the errors to parse
+          #
+          # @return [Parser] the new Parser instance
+          def initialize: (untyped errors) -> void
+
+          # Parses the errors into a consistent format
+          #
+          # @raise [ArgumentError] If the errors cannot be parsed
+          # @return [Hash{Symbol => Array<String>}]
+          def parse!: () -> Hash[Symbol, Array[String]]
+
+          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]
+          def parse_array: (Array[String | StandardError] errors) -> void
+
+          # Determines the appropriate parsing strategy and executes it
+          #
+          # @raise [ArgumentError] If no valid parsing strategy is found
+          # @return [void]
+          def parse_errors!: () -> void
+
+          # Parses a string or array of strings into the generic error category
+          #
+          # @param errors [String, Array<String>] The error(s) to parse
+          #
+          # @return [void]
+          def parse_generic_error: (Array[String] | String errors) -> void
+
+          # 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]
+          def parse_hash: (Hash[String | Symbol, Array[StandardError] | Array[String] | StandardError | String] errors) -> void
+
+          # 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
+          def parse_hash_array_value: (String | StandardError value) -> String
+
+          # 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)
+          def parse_hash_value: (String | StandardError | Array[String | StandardError] value) -> Array[String]
+
+          # Parses a StandardError into the generic error category
+          #
+          # @param errors [StandardError] The error to parse
+          #
+          # @return [void]
+          def parse_standard_error: (StandardError errors) -> void
+
+          # 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]
+          def parse_to_h: (untyped errors) -> void
+
+          # Raises an invalid errors exception
+          #
+          # @raise [ArgumentError] Always raises with an invalid errors message
+          # @return [void]
+          def raise_invalid_errors!: () -> void
+        end
+      end
+    end
+  end
+end

data/sig/domainic/command/result/status.rbs

@@ -0,0 +1,47 @@
+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: Integer
+
+        # Indicates a failure during command execution
+        #
+        # @return [Integer] status code 1
+        FAILED_AT_RUNTIME: Integer
+
+        # Indicates a failure during input validation
+        #
+        # @return [Integer] status code 2
+        FAILED_AT_INPUT: Integer
+
+        # Indicates a failure during output validation
+        #
+        # @return [Integer] status code 3
+        FAILED_AT_OUTPUT: Integer
+      end
+    end
+  end
+end

data/sig/domainic/command/result.rbs

@@ -0,0 +1,149 @@
+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
+      @data: Struct
+
+      @status_code: Integer
+
+      @errors: ErrorSet
+
+      # 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
+      def self.failure: (untyped errors, ?Hash[String | Symbol, untyped] context, ?status: Integer) -> Result
+
+      # 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
+      def self.failure_at_input: (untyped errors, ?Hash[String | Symbol, untyped] context) -> Result
+
+      # 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
+      def self.failure_at_output: (untyped errors, ?Hash[String | Symbol, untyped] context) -> Result
+
+      # Creates a new success result
+      #
+      # @param context [Hash] The successful result data
+      #
+      # @return [Result] A new success result
+      def self.success: (Hash[String | Symbol, untyped] context) -> Result
+
+      # 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]
+      def initialize: (Integer status, ?context: Hash[String | Symbol, untyped], ?errors: untyped) -> void
+
+      # Indicates whether the command failed
+      #
+      # @return [Boolean] true if the command failed; false otherwise
+      def failure?: () -> bool
+
+      alias failed? failure?
+
+      # Indicates whether the command succeeded
+      #
+      # @return [Boolean] true if the command succeeded; false otherwise
+      def successful?: () -> bool
+
+      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: (untyped context) -> untyped
+
+      # 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: (untyped status_code) -> untyped
+
+      # 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
+      def method_missing: ...
+
+      # 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
+      def respond_to_missing?: (String | Symbol method_name, ?bool include_private) -> bool
+    end
+  end
+end

data/sig/domainic/command.rbs

@@ -0,0 +1,67 @@
+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
+    def self.included: ...
+  end
+end

data/sig/domainic-command.rbs

@@ -0,0 +1 @@
+

data/sig/manifest.yaml

@@ -0,0 +1 @@
+dependencies: []

metadata

@@ -1,34 +1,70 @@
 --- !ruby/object:Gem::Specification
 name: domainic-command
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.1.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Aaron Allen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-21 00:00:00.000000000 Z
+date: 2024-12-29 00:00:00.000000000 Z
 dependencies: []
-description:
+description: Stop scattering your business logic across controllers and models! Domainic::Command
+  brings clarity to your domain operations with type-safe, self-documenting command
+  objects that actually tell you what went wrong. From simple CRUD to complex workflows,
+  make your business operations work for you, not against you!
 email:
 - hello@aaronmallen.me
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
+- CHANGELOG.md
 - LICENSE
 - README.md
-homepage: https://github.com/domainic/domainic/tree/domainic-command-v0.1.0-alpha.1.0.0/domainic-command
+- lib/domainic-command.rb
+- lib/domainic/command.rb
+- lib/domainic/command/class_methods.rb
+- lib/domainic/command/context/attribute.rb
+- lib/domainic/command/context/attribute_set.rb
+- lib/domainic/command/context/behavior.rb
+- lib/domainic/command/context/input_context.rb
+- lib/domainic/command/context/output_context.rb
+- lib/domainic/command/context/runtime_context.rb
+- lib/domainic/command/errors/error.rb
+- lib/domainic/command/errors/execution_error.rb
+- lib/domainic/command/instance_methods.rb
+- lib/domainic/command/result.rb
+- lib/domainic/command/result/error_set.rb
+- lib/domainic/command/result/status.rb
+- sig/domainic-command.rbs
+- sig/domainic/command.rbs
+- sig/domainic/command/class_methods.rbs
+- sig/domainic/command/context/attribute.rbs
+- sig/domainic/command/context/attribute_set.rbs
+- sig/domainic/command/context/behavior.rbs
+- sig/domainic/command/context/input_context.rbs
+- sig/domainic/command/context/output_context.rbs
+- sig/domainic/command/context/runtime_context.rbs
+- sig/domainic/command/errors/error.rbs
+- sig/domainic/command/errors/execution_error.rbs
+- sig/domainic/command/instance_methods.rbs
+- sig/domainic/command/result.rbs
+- sig/domainic/command/result/error_set.rbs
+- sig/domainic/command/result/status.rbs
+- sig/manifest.yaml
+homepage: https://github.com/domainic/domainic/tree/domainic-command-v0.1.0/domainic-command
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/domainic/domainic/issues
-  changelog_uri: https://github.com/domainic/domainic/releases/tag/domainic-command-v0.1.0-alpha.1.0.0
-  homepage_uri: https://github.com/domainic/domainic/tree/domainic-command-v0.1.0-alpha.1.0.0/domainic-command
+  changelog_uri: https://github.com/domainic/domainic/releases/tag/domainic-command-v0.1.0
+  documentation_uri: https://rubydoc.info/gems/domainic-command/0.1.0
+  homepage_uri: https://github.com/domainic/domainic/tree/domainic-command-v0.1.0/domainic-command
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/domainic/domainic/tree/domainic-command-v0.1.0-alpha.1.0.0/domainic-command
-  wiki_uri: https://github.com/domainic/domainic/wiki
+  source_code_uri: https://github.com/domainic/domainic/tree/domainic-command-v0.1.0/domainic-command
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -37,15 +73,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
-summary: Coming Soon
+summary: A robust implementation of the command pattern in Ruby, offering type-safe,
+  composable business operations with standardized error handling.
 test_files: []