simple_command_dispatcher 4.0.0 → 4.2.0

data/lib/simple_command_dispatcher/commands/command_callable.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module SimpleCommandDispatcher
+  module Commands
+    # CommandCallable provides a standardized interface for command objects with built-in
+    # success/failure tracking and error handling.
+    #
+    # When prepended to a command class, it:
+    # - Adds a class-level `.call` method that instantiates and executes the command
+    # - Tracks command execution with `success?` and `failure?` methods
+    # - Provides error collection via the `errors` object
+    # - Stores the command's return value in `result`
+    #
+    # @example Basic usage
+    #   class AuthenticateUser
+    #     prepend SimpleCommandDispatcher::Commands::CommandCallable
+    #
+    #     def initialize(email:, password:)
+    #       @email = email
+    #       @password = password
+    #     end
+    #
+    #     def call
+    #       return nil unless user = User.find_by(email: @email)
+    #       return nil unless user.authenticate(@password)
+    #
+    #       user
+    #     end
+    #   end
+    #
+    #   command = AuthenticateUser.call(email: 'user@example.com', password: 'secret')
+    #   command.success? # => true if user found and authenticated
+    #   command.result   # => User object or nil
+    module CommandCallable
+      # @return [Object] the return value from the command's call method
+      attr_reader :result
+
+      module ClassMethods
+        # Creates a new instance of the command and calls it, passing all arguments through.
+        #
+        # @param args [Array] positional arguments passed to initialize
+        # @param kwargs [Hash] keyword arguments passed to initialize
+        # @return [Object] the command instance (not the result - use .result to get the return value)
+        def call(...)
+          new(...).call
+        end
+      end
+
+      def self.prepended(base)
+        base.extend ClassMethods
+      end
+
+      # Executes the command by calling super (your command's implementation).
+      # Tracks execution state and stores the result.
+      #
+      # @return [self] the command instance for method chaining
+      # @raise [NotImplementedError] if the including class doesn't define a call method
+      def call
+        raise NotImplementedError unless defined?(super)
+
+        @called = true
+        @result = super
+
+        self
+      end
+
+      # Returns true if the command was called successfully (no errors).
+      #
+      # @return [Boolean] true if called and no errors present
+      def success?
+        called? && !failure?
+      end
+      alias successful? success?
+
+      # Returns true if the command was called but has errors.
+      #
+      # @return [Boolean] true if called and errors are present
+      def failure?
+        called? && errors.any?
+      end
+
+      # Returns the errors collection for this command.
+      # If the command class defines its own errors method, that will be used instead.
+      #
+      # @return [Errors] the errors collection
+      def errors
+        return super if defined?(super)
+
+        @errors ||= Errors.new
+      end
+
+      private
+
+      # Returns true if the command's call method has been invoked.
+      #
+      # @return [Boolean] true if call has been invoked
+      def called?
+        @called ||= false
+      end
+    end
+  end
+end

data/lib/simple_command_dispatcher/commands/errors.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative 'utils'
+
+module SimpleCommandDispatcher
+  module Commands
+    module CommandCallable
+      # Raised when a command's call method is not implemented
+      class NotImplementedError < ::StandardError; end
+
+      # Error collection for CommandCallable commands.
+      # Stores validation errors as a hash where keys are field names and values are arrays of error messages.
+      class Errors < Hash
+        # Adds an error message to the specified field.
+        # Automatically prevents duplicate messages for the same field.
+        #
+        # @param key [Symbol, String] the field name
+        # @param value [String] the error message
+        # @param _opts [Hash] reserved for future use
+        # @return [Array] the updated array of error messages for this field
+        #
+        # @example
+        #   errors.add(:email, 'is required')
+        #   errors.add(:email, 'is invalid')
+        #   errors[:email] # => ['is required', 'is invalid']
+        def add(key, value, _opts = {})
+          self[key] ||= []
+          self[key] << value
+          self[key].uniq!
+        end
+
+        # Adds multiple errors from a hash.
+        # Values can be single messages or arrays of messages.
+        #
+        # @param errors_hash [Hash] hash of field names to error message(s)
+        #
+        # @example
+        #   errors.add_multiple_errors(email: 'is required', password: ['is too short', 'is too weak'])
+        def add_multiple_errors(errors_hash)
+          errors_hash.each do |key, values|
+            CommandCallable::Utils.array_wrap(values).each { |value| add key, value }
+          end
+        end
+
+        # Iterates over each field and message pair.
+        # If a field has multiple messages, yields once for each message.
+        #
+        # @yieldparam field [Symbol] the field name
+        # @yieldparam message [String] the error message
+        #
+        # @example
+        #   errors.each { |field, message| puts "#{field}: #{message}" }
+        def each
+          each_key do |field|
+            self[field].each { |message| yield field, message }
+          end
+        end
+
+        # Returns an array of formatted error messages.
+        # Messages are prefixed with the capitalized field name, except for :base.
+        #
+        # @return [Array<String>] formatted error messages
+        #
+        # @example
+        #   errors.add(:email, 'is required')
+        #   errors.add(:base, 'Something went wrong')
+        #   errors.full_messages # => ['Email is required', 'Something went wrong']
+        def full_messages
+          map { |attribute, message| full_message(attribute, message) }
+        end
+
+        private
+
+        def full_message(attribute, message)
+          return message if attribute == :base
+
+          attr_name = attribute.to_s.tr('.', '_').capitalize
+          "#{attr_name} #{message}"
+        end
+      end
+    end
+  end
+end

data/lib/simple_command_dispatcher/commands/utils.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SimpleCommandDispatcher
+  module Commands
+    module CommandCallable
+      module Utils
+        # Borrowed from active_support/core_ext/array/wrap
+        def self.array_wrap(object)
+          if object.nil?
+            []
+          elsif object.respond_to?(:to_ary)
+            object.to_ary || [object]
+          else
+            [object]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simple_command_dispatcher/configuration.rb

@@ -3,8 +3,6 @@
 # This is the configuration for SimpleCommandDispatcher.
 module SimpleCommandDispatcher
   class << self
-    attr_reader :configuration
-
     # Configures SimpleCommandDispatcher by yielding the configuration object to the block.
     #
     # @yield [Configuration] yields the configuration object to the block
@@ -13,7 +11,7 @@ module SimpleCommandDispatcher
     # @example
     #
     # SimpleCommandDispatcher.configure do |config|
-    #  config.some_option = 'some value'
+    #  config.logger = Rails.logger
     # end
     def configure
       self.configuration ||= Configuration.new
@@ -23,6 +21,13 @@ module SimpleCommandDispatcher
       configuration
     end
 
+    # Returns the configuration object, initializing it if necessary
+    #
+    # @return [Configuration] the configuration object
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
     private
 
     attr_writer :configuration
@@ -31,16 +36,30 @@ module SimpleCommandDispatcher
   # This class encapsulates the configuration properties for this gem and
   # provides methods and attributes that allow for management of the same.
   class Configuration
-    # TODO: Add attr_xxx here
+    # @return [Logger] the logger instance used for debug output.
+    #   Defaults to Rails.logger in Rails applications, or Logger.new($stdout) otherwise.
+    attr_accessor :logger
 
     # Initializes a new Configuration instance with default values
     def initialize
       reset
     end
 
-    # Resets all configuration attributes to their default values
+    # Resets all configuration attributes to their default values.
+    # Sets logger to Rails.logger if Rails is defined, otherwise creates a new Logger writing to $stdout.
     def reset
-      # TODO: Reset our attributes here e.g. @attr = nil
+      @logger = default_logger
+    end
+
+    private
+
+    def default_logger
+      if defined?(Rails) && Rails.respond_to?(:logger)
+        Rails.logger
+      else
+        require 'logger'
+        ::Logger.new($stdout)
+      end
     end
   end
 end

data/lib/simple_command_dispatcher/helpers/camelize.rb

@@ -25,7 +25,7 @@ module SimpleCommandDispatcher
         # For RESTful paths → Ruby constants, use Rails' proven methods
         # They're fast, reliable, and handle edge cases that matter for constants
         result = trim_all(token)
-          .gsub(%r{[/\-\.\s:]+}, '/')                    # Normalize separators to /
+          .gsub(%r{[/\-.\s:]+}, '/') # Normalize separators to /
           .split('/')                                    # Split into path segments
           .reject(&:empty?)                              # Remove empty segments
           .map { |segment| segment.underscore.camelize } # Rails camelization

data/lib/simple_command_dispatcher/logger.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SimpleCommandDispatcher
+  # Provides logging functionality for SimpleCommandDispatcher.
+  # Supports configuration to use Rails logger or custom loggers.
+  module Logger
+    private
+
+    def log_debug(string)
+      logger.debug(string) if logger.respond_to?(:debug)
+    end
+
+    def log_error(string)
+      logger.error(string) if logger.respond_to?(:error)
+    end
+
+    def logger
+      SimpleCommandDispatcher.configuration.logger
+    end
+  end
+end

data/lib/simple_command_dispatcher/services/command_service.rb

@@ -2,6 +2,7 @@
 
 require_relative '../errors'
 require_relative '../helpers/camelize'
+require_relative '../logger'
 require_relative 'command_namespace_service'
 
 module SimpleCommandDispatcher
@@ -9,8 +10,10 @@ module SimpleCommandDispatcher
     # Handles class and module transformations and instantiation.
     class CommandService
       include Helpers::Camelize
+      include Logger
 
-      def initialize(command:, command_namespace: {})
+      def initialize(command:, command_namespace: {}, options: {})
+        @options = options
         @command = validate_command(command:)
         @command_namespace = validate_command_namespace(command_namespace:)
       end
@@ -25,15 +28,24 @@ module SimpleCommandDispatcher
       #
       # @example
       #
-      #   to_class("Authenticate", "Api") # => Api::Authenticate
-      #   to_class(:Authenticate, [:Api, :AppName, :V1]) # => Api::AppName::V1::Authenticate
-      #   to_class(:Authenticate, { :api :Api, app_name: :AppName, api_version: :V2 })
+      #   CommandService.new(command: "Authenticate", command_namespace: "Api").to_class
+      #     # => Api::Authenticate
+      #   CommandService.new(command: :Authenticate, command_namespace: [:Api, :AppName, :V1]).to_class
+      #     # => Api::AppName::V1::Authenticate
+      #   CommandService.new(command: :Authenticate,
+      #                      command_namespace: { api: :Api, app_name: :AppName, api_version: :V2 }).to_class
       #     # => Api::AppName::V2::Authenticate
-      #   to_class("authenticate", { :api :api, app_name: :app_name, api_version: :v1 },
-      #     { titleize_class: true, titleize_module: true }) # => Api::AppName::V1::Authenticate
+      #   CommandService.new(command: "authenticate", command_namespace: "api::app_name::v1").to_class
+      #     # => Api::AppName::V1::Authenticate
       #
       def to_class
-        qualified_class_string = to_qualified_class_string(command, command_namespace)
+        qualified_class_string = to_qualified_class_string
+
+        if options.debug?
+          log_debug <<~DEBUG
+            Command to execute: #{qualified_class_string.inspect}
+          DEBUG
+        end
 
         begin
           qualified_class_string.constantize
@@ -44,24 +56,13 @@ module SimpleCommandDispatcher
 
       private
 
-      attr_accessor :command, :command_namespace
+      attr_reader :options, :command, :command_namespace
 
       # Returns a fully-qualified constantized class (as a string), given the command and command_namespace.
-      # Both parameters are automatically camelized/titleized during processing.
-      #
-      # @param command [Symbol, String] the class name.
-      # @param command_namespace [Hash, Array, String] the modules command belongs to.
       #
       # @return [String] the fully qualified class, which includes module(s) and class name.
       #
-      # @example
-      #
-      #   to_qualified_class_string("authenticate", "api") # => "Api::Authenticate"
-      #   to_qualified_class_string(:Authenticate, [:Api, :AppName, :V1]) # => "Api::AppName::V1::Authenticate"
-      #   to_qualified_class_string(:authenticate, { api: :api, app_name: :app_name, api_version: :v1 })
-      #      # => "Api::AppName::V1::Authenticate"
-      #
-      def to_qualified_class_string(command, command_namespace)
+      def to_qualified_class_string
         class_modules_string = CommandNamespaceService.new(command_namespace:).to_class_modules_string
         class_string = to_class_string(command:)
         "#{class_modules_string}#{class_string}"
@@ -87,19 +88,18 @@ module SimpleCommandDispatcher
 
       # @!visibility public
       #
-      # Validates command and returns command as a string after all blanks have been removed using
-      # command.gsub(/\s+/, "").
+      # Validates command and returns command as a string after leading and trailing whitespace is stripped.
       #
-      # @param [Symbol or String] command the class name to be validated. command cannot be empty?
+      # @param command [Symbol, String] the class name to be validated. command cannot be empty after stripping.
       #
-      # @return [String] the validated class as a string with blanks removed.
+      # @return [String] the validated class as a string with leading/trailing whitespace removed.
       #
       # @raise [ArgumentError] if the command is empty? or not of type String or Symbol.
       #
       # @example
       #
-      #   validate_command(" My Class ") # => "MyClass"
-      #   validate_command(:MyClass) # => "MyClass"
+      #   validate_command(command: " MyClass ") # => "MyClass"
+      #   validate_command(command: :MyClass) # => "MyClass"
       #
       def validate_command(command:)
         unless command.is_a?(Symbol) || command.is_a?(String)
@@ -119,17 +119,17 @@ module SimpleCommandDispatcher
       #
       # Validates and returns command_namespace.
       #
-      # @param [Hash, Array or String] command_namespace the module(s) to be validated.
+      # @param command_namespace [Hash, Array, String] the module(s) to be validated.
       #
-      # @return [Hash, Array or String] the validated module(s).
+      # @return [Hash, Array, String] the validated module(s), or {} if blank.
       #
       # @raise [ArgumentError] if the command_namespace is not of type String, Hash or Array.
       #
       # @example
       #
-      #   validate_command_namespace(" Module ") # => " Module "
-      #   validate_command_namespace(:Module) # => :Module
-      #   validate_command_namespace("ModuleA::ModuleB") # => "ModuleA::ModuleB"
+      #   validate_command_namespace(command_namespace: "Api::V1") # => "Api::V1"
+      #   validate_command_namespace(command_namespace: [:Api, :V1]) # => [:Api, :V1]
+      #   validate_command_namespace(command_namespace: { api: :Api, version: :V1 }) # => { api: :Api, version: :V1 }
       #
       def validate_command_namespace(command_namespace:)
         return {} if command_namespace.blank?

data/lib/simple_command_dispatcher/services/options_service.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SimpleCommandDispatcher
+  module Services
+    # Handles options for command execution and ensures proper initialization.
+    #
+    # @example
+    #   options = OptionsService.new(options: { debug: true })
+    #   options.debug? # => true
+    class OptionsService
+      # Default options for command execution
+      DEFAULT_OPTIONS = {
+        debug: false
+      }.freeze
+
+      # Initializes the options service with the provided options merged with defaults.
+      #
+      # @param options [Hash] custom options
+      # @option options [Boolean] :debug (false) enables debug logging when true
+      def initialize(options: {})
+        @options = DEFAULT_OPTIONS.merge(options)
+      end
+
+      # Returns true if debug mode is enabled.
+      # When enabled, debug logging will show command execution flow.
+      #
+      # @return [Boolean] true if debug mode is enabled
+      def debug?
+        options[:debug]
+      end
+
+      private
+
+      attr_reader :options
+    end
+  end
+end

data/lib/simple_command_dispatcher/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleCommandDispatcher
-  VERSION = '4.0.0'
+  VERSION = '4.2.0'
 end

data/lib/simple_command_dispatcher.rb

@@ -3,12 +3,17 @@
 require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/string/inflections'
 require 'core_ext/kernel'
+require 'simple_command_dispatcher/commands/command_callable'
 require 'simple_command_dispatcher/configuration'
 require 'simple_command_dispatcher/errors'
+require 'simple_command_dispatcher/logger'
 require 'simple_command_dispatcher/services/command_service'
+require 'simple_command_dispatcher/services/options_service'
 require 'simple_command_dispatcher/version'
 
 module SimpleCommandDispatcher
+  extend Logger
+
   # Provides a way to call your custom commands dynamically.
   #
   class << self
@@ -17,10 +22,10 @@ module SimpleCommandDispatcher
     #
     # @param command [Symbol, String] the name of the Command to call.
     #
-    # @param command_namespace [Hash, Array] the ruby modules that qualify the Command to call.
+    # @param command_namespace [Hash, Array, String] the ruby modules that qualify the Command to call.
     #    When passing a Hash, the Hash keys serve as documentation only.
-    #    For example, ['Api', 'AppName', 'V1'] and { :api :Api, app_name: :AppName, api_version: :V1 }
-    #    will both produce 'Api::AppName::V1', this string will be prepended to the command to form the Command
+    #    For example, ['Api', 'AppName', 'V1'], 'Api::AppName::V1', and { :api :Api, app_name: :AppName, api_version: :V1 }
+    #    will all produce 'Api::AppName::V1', this string will be prepended to the command to form the Command
     #    to call (e.g. 'Api::AppName::V1::MySimpleCommand' = Api::AppName::V1::MySimpleCommand.call(*request_params)).
     #
     # @param request_params [Hash, Array, Object] the parameters to pass to the call method of the Command. This
@@ -28,6 +33,10 @@ module SimpleCommandDispatcher
     #    keyword arguments, Array parameters are passed as positional arguments, and other objects are passed
     #    as a single argument.
     #
+    # @param options [Hash] optional configuration for command execution.
+    #    Supported options:
+    #    - :debug [Boolean] when true, enables debug logging of command execution flow
+    #
     # @return [Object] the Object returned as a result of calling the Command#call method.
     #
     # @example
@@ -49,20 +58,43 @@ module SimpleCommandDispatcher
     #     command_namespace: ['Api::Auth::JazzMeUp', :V1],
     #     request_params: ['jazz_me@gmail.com', 'JazzM3!']) # => Command result
     #
-    def call(command:, command_namespace: {}, request_params: nil)
+    def call(command:, command_namespace: {}, request_params: nil, options: {})
+      @options = Services::OptionsService.new(options:)
+
+      if @options.debug?
+        log_debug <<~DEBUG
+          Begin dispatching command
+            command: #{command.inspect}
+            command_namespace: #{command_namespace.inspect}
+        DEBUG
+      end
+
       # Create a constantized class from our command and command_namespace...
-      constantized_class_object = Services::CommandService.new(command:, command_namespace:).to_class
+      constantized_class_object = Services::CommandService.new(command:, command_namespace:, options: @options).to_class
+
+      if @options.debug?
+        log_debug <<~DEBUG
+          Constantized command: #{constantized_class_object.inspect}
+        DEBUG
+      end
+
       validate_command!(constantized_class_object)
 
       # We know we have a valid command class object if we get here. All we need to do is call the .call
       # class method, pass the request_params arguments depending on the request_params data type, and
       # return the results.
 
-      call_command(constantized_class_object:, request_params:)
+      command_object = call_command(constantized_class_object:, request_params:)
+
+      log_debug 'End dispatching command' if @options.debug?
+
+      command_object
     end
 
     private
 
+    attr_reader :options
+
     def call_command(constantized_class_object:, request_params:)
       if request_params.is_a?(Hash)
         constantized_class_object.call(**request_params)

data/simple_command_dispatcher.gemspec

@@ -10,12 +10,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Gene M. Angelo, Jr.']
   spec.email         = ['public.gma@gmail.com']
 
-  spec.summary       = 'Provides a way to dispatch simple_command (ruby gem) commands or your own custom commands (service objects) in a more dynamic manner
-                          within your service API. Ideal for rails-api.'
-  spec.description   = 'Within a services API (rails-api for instance), you may have a need to execute different simple_commands or your own custom commands (service objects)
-                          based on one or more factors: multiple application, API version, user type, user credentials, etc. For example,
-                          your service API may need to execute either Api::Auth::V1::AuthenticateCommand.call(...) or Api::Auth::V2::AuthenticateCommand.call(...)
-                          based on the API version. simple_command_dispatcher allows you to execute either command with one line of code dynamically.'.gsub(/\s+/, ' ')
+  spec.summary       = 'Dynamic command execution for Rails applications using convention over configuration - automatically maps request routes to command classes.'
+  spec.description   = 'A lightweight Ruby gem that enables Rails applications to dynamically execute command objects using convention over configuration. ' \
+                       'Automatically transforms request paths into Ruby class constants, allowing controllers to dispatch commands based on routes and parameters. ' \
+                       'Features the optional CommandCallable module for standardized command interfaces with built-in success/failure tracking and error handling. ' \
+                       'Perfect for clean, maintainable Rails APIs with RESTful route-to-command mapping. Only depends on ActiveSupport for reliable camelization.'
   spec.homepage      = 'https://github.com/gangelo/simple_command_dispatcher'
   spec.license       = 'MIT'
 
@@ -37,5 +36,5 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = Gem::Requirement.new('>= 3.3', '< 4.0')
 
-  spec.add_runtime_dependency 'activesupport', '>= 7.0.8', '< 8.0'
+  spec.add_runtime_dependency 'activesupport', '>= 7.0.8', '< 9.0'
 end